package com.ruoyi.web.modules.screen.service;

import java.util.List;
import java.util.Map;
import com.ruoyi.common.core.domain.TreeSelect;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenCooperativeDevelopmentListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenDashboardVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenFamilyRanchListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenFarmerHouseholdListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenImbalanceWarningListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenLargeLivestockFarmerListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenLivestockOwnershipHouseholdListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenPerCapitaIncomeListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenStandardListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenTownMapVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenYakHerdInventoryListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenBreedingEntityQuantityListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenYakInventoryOutboundListItemVo;
import com.ruoyi.web.modules.screen.domain.vo.HomeScreenYakOutboundReportListItemVo;

/**
 * 大屏首页统计服务。
 * <p>
 * 聚合产业总览、畜群/牦牛结构、牲畜出栏与自食、企业收支、人均收入等；
 * 看板已屏蔽惠农补贴、草场类型占比、牦牛出栏月度、牦牛存栏变动。
 */
public interface IHomeScreenService
{
    /**
     * 加载首页看板。
     *
     * @param statYear 统计年份字符串，如 {@code "2026"}
     */
    HomeScreenDashboardVo loadDashboard(String statYear);

    /**
     * 分页查询养殖标准列表。
     *
     * @param category {@link com.ruoyi.web.modules.screen.support.HomeScreenStandardCategory} 枚举名
     */
    List<HomeScreenStandardListItemVo> listStandards(String statYear, String category);

    /**
     * 地图标注：所选年份内存栏/出栏表各自最大填报月，按乡镇汇总各村牦牛存栏/出栏。
     *
     * @param statYear 统计年份字符串，如 {@code "2026"}
     */
    HomeScreenTownMapVo loadTownMapMarkers(String statYear);

    /**
     * 草畜失衡预警明细（分页由 Controller {@code startPage} 控制；按预警时间倒序）。
     *
     * @param statYear      所属年份，可选
     * @param statMonth     所属月份，可选
     * @param townDeptId    所属乡镇，可选
     * @param villageDeptId 所属村，可选
     */
    List<HomeScreenImbalanceWarningListItemVo> listGrassLivestockImbalanceWarnings(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 人均收入情况明细（分页由 Controller {@code startPage} 控制；按所属年份倒序）。
     *
     * @param statYear 所属年份，可选；未传不过滤（跨年按年倒序）
     */
    List<HomeScreenPerCapitaIncomeListItemVo> listPerCapitaIncomes(Integer statYear);

    /**
     * 农牧户数据明细（分页由 Controller {@code startPage} 控制；按年、月倒序）。
     * 草场面积数据明细复用本方法，不另开接口。
     *
     * @param statYear      所属年份，可选；未传不过滤
     * @param statMonth     所属月份，可选；未传不过滤
     * @param townDeptId    所属乡镇，可选
     * @param villageDeptId 所属村，可选
     */
    List<HomeScreenFarmerHouseholdListItemVo> listFarmerHouseholds(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 合作社发展数据明细（分页由 Controller {@code startPage} 控制；按年、月倒序）。
     */
    List<HomeScreenCooperativeDevelopmentListItemVo> listCooperativeDevelopments(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 家庭牧场数据明细（分页由 Controller {@code startPage} 控制；按年、月倒序）。
     */
    List<HomeScreenFamilyRanchListItemVo> listFamilyRanches(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 养殖大户数据明细（分页由 Controller {@code startPage} 控制；按年、月倒序）。
     */
    List<HomeScreenLargeLivestockFarmerListItemVo> listLargeLivestockFarmers(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 牦牛出栏数据明细（分页；按年、月倒序）。
     */
    List<HomeScreenYakOutboundReportListItemVo> listYakOutboundReports(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 牦牛存栏数据明细（分页；按年、月倒序）。
     */
    List<HomeScreenYakHerdInventoryListItemVo> listYakHerdInventories(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 有无畜户数据明细（分页；按年、月倒序）。
     */
    List<HomeScreenLivestockOwnershipHouseholdListItemVo> listLivestockOwnershipHouseholds(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 牦牛存出栏情况明细（分页；按年、月倒序）。
     * 按 {@code (stat_year, stat_month, village_dept_id)} 关联存栏/出栏填报表。
     * 年月未传不过滤，支持跨多年全量翻页。
     */
    List<HomeScreenYakInventoryOutboundListItemVo> listYakInventoryOutbounds(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 养殖主体数量明细（分页；按年、月倒序）。
     * 村×年月键集 = 农牧户 ∪ 合作社 ∪ 家庭牧场 ∪ 养殖大户（不同组织形式）。
     * 任一形式有数据即可查出，其余数量为 0。年月未传不过滤，支持跨多年全量翻页（界面默认当前年月）。
     */
    List<HomeScreenBreedingEntityQuantityListItemVo> listBreedingEntityQuantities(
            Integer statYear, Integer statMonth, Long townDeptId, Long villageDeptId);

    /**
     * 大屏乡镇下拉（全县填报乡镇，不按登录人数据权限收窄）。
     */
    List<Map<String, Object>> listTownOptions();

    /**
     * 大屏村树（县 → 乡镇 → 村，全县口径）。
     */
    List<TreeSelect> listVillageTree();
}
