西藏巴青项目

大屏 — 首页统计 — 技术方案

依据：同目录 大屏首页功能需求.md；数据来自养殖产业、流通交易、服务预约、补贴发放、养殖标准五类子表、科技资源与实战培训等既有表。本模块为大屏只读看板，无业务台账 CRUD。

1. 技术架构

项	说明
后端	RuoYi v3.9.2（springboot2 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid
数据库	MySQL 5.7.39，InnoDB，`utf8mb4`
前端	大屏独立首页（`ruoyi-screen`）；切换 `statYear` 拉看板主数据，养殖标准分页单独请求；存栏变动/出栏统计图表见 §4.1
代码包	`com.ruoyi.web.modules.screen`（`HomeScreenController` / `IHomeScreenService` / `vo` / `support`）

分层：Controller → IHomeScreenService（口径编排、按 Y 计算统计日）→ 扩展 Mapper / 复用 BreedingIndustryStatsMapper + BreedingIndustryCalculator（只读）。

场景	行为
进入 / 切换 `statYear`	调用 §3.1 + §3.2（`pageNum=1`）
标准列表翻页 / 切 Tab	仅 §3.2
数据权限	全县聚合：牦牛、牧场取全部 `biz_status=1` 且 `del_flag=0` 的牧场 ID（与疫病风险大屏一致，不按登录用户牧场过滤）；草场全县 `del_flag=0`
统计日	`Y = 当前年` → `statDate = 今日`；`Y` 为历史年 → `statDate = Y-12-31`（时点、月末还原、年出栏上界均据此）
主数据三项	供应商 / 承销商 / 交易市场实时快照，不随 `statYear` 变
滚动 12 月图表	存栏变动、出栏统计、预约堆叠、培训趋势；锚点 = 当前 `YearMonth`；不随 `statYear` 变
按月图表（Y 年内）	已无（预约/培训已并入滚动 12 月）
性能	默认实时聚合；可选 §2.3 缓存表

依赖表（只读）

表	用途
`biz_yak_asset` / `biz_pasture` / `biz_grassland`	产业总览、存栏趋势、年龄结构、出栏、草场
`biz_supplier` / `biz_distributor` / `biz_trade_market`	流通主数据条数（实时）
`biz_service_appointment`	线下服务预约
`biz_subsidy_grant_record`	惠农补贴
`biz_breeding_standard` 等 5 张标准表	养殖标准分页列表
`biz_tech_resource`	视频课程（`004008`）
`biz_practical_training`	实战培训场次与报名趋势
`biz_yak_herd_inventory`	产业总览存栏（所选年最大月）、存栏变动、年龄结构、地图标注
`biz_yak_outbound_report`	产业总览出栏（所选年最大月）、出栏统计、地图标注
`biz_farmer_household`	产业总览农牧户（所选年最大月全县村级 `household_count` 合计）
`biz_cooperative_development`	产业总览合作社（所选年最大月记录条数）
`biz_family_ranch`	产业总览家庭牧场（所选年最大月记录条数）
`biz_large_livestock_farmer`	产业总览养殖大户（所选年最大月记录条数）
`biz_livestock_ownership_household`	产业总览有畜户数（所选年最大月 `with_livestock_household_count` 合计）
`sys_dept`	地图标注 — 乡镇列表（`parent_id=100` 且 `order_num>12`）

2. 数据库设计

2.1 本模块业务表

无新增业务台账表。 DDL 以各业务 sql/*.sql 为准。

2.2 公共参数

记 statYear = Y，statDate 见 §1。

边界	表达式
年区间起	`Y-01-01 00:00:00`
年区间止（年内累计）	`Y` 为当前年：`statDate 23:59:59`；历史年：`Y-12-31 23:59:59`
按月分组键	`MONTH(日期字段)`，应用层补全 1～12

2.3 可选表 `biz_home_screen_cache`（性能优化）

非本期必建。

字段	类型	说明
`id`	`bigint(20)`	主键
`stat_year`	`int(11)`	统计年份
`payload_json`	`mediumtext`	§3.1 响应 JSON（不含标准分页列表）
`expire_time`	`datetime`	过期时间
`create_time`	`datetime`	写入时间

索引：UNIQUE uk_stat_year (stat_year)。TTL 建议 1～5 分钟。

2.4 查询口径（按表）

牦牛填报（大屏首页存栏/出栏/年龄/趋势/地图）

指标	要点
所选年最大填报月	`stat_year = Y` 时 `MAX(stat_month)`；存栏 / 出栏 / 农牧户表可不同月；产业总览三项、地图标注用此口径
最近填报年月	全库 `MAX(stat_year, stat_month)`；存栏变动/年龄用此口径（若已改为所选年则见对应章节）
产业总览三项	所选年最大月全县 `yak_total` / `yak_outbound_count` / `farmer_household_count`
存栏变动 header	最近年月全县 `bull_total`、`cow_total`、`yak_total`
滚动 12 月存栏趋势	`biz_yak_herd_inventory` 按 `stat_year+stat_month` 全县 `bull_total`/`cow_total` 合计
滚动 12 月出栏	`biz_yak_outbound_report` 按 `stat_year+stat_month` 全县 `yak_outbound_count` 合计
年龄结构	最近年月母牛两档：`cow_young_count`（0～1.5 岁）、`cow_adult_count`（1.5 岁以上）
地图标注	所选年各自最大填报月下，按乡镇 `SUM(yak_total)` / `SUM(yak_outbound_count)`

养殖产业档案（草场等，复用 Mapper）

实现复用 BreedingIndustryStatsMapper；大屏传入全县 allowedPastureIds（全部正常牧场 ID）。

指标	要点
草场	`del_flag=0`；面积 `SUM(area_mu)`；可用/使用中/退化分组同养殖产业

首页不含预警牦牛；不查 biz_yak_disease_warning。

流通主数据（实时，与 Y 无关）

表	指标	条件
`biz_supplier`	供应商数	`del_flag='0'`
`biz_distributor`	承销商数	`del_flag='0'`
`biz_trade_market`	交易市场数	`del_flag='0'` AND `operate_status=1`

服务预约 `biz_service_appointment`

项	条件
按年	`appoint_date >= Y-01-01` AND `appoint_date <= Y-12-31`
状态	`status NOT IN (2,3)`（排除已拒绝、已取消）；表无 `del_flag`
分类	`provider_type`：`1` 兽医 → 展示「兽医人员」；`3` 专家 →「专家人员」；`2` 机构 →「诊疗机构」
统计	每条记录计 1 人次；年度卡片为三类合计；按月 `GROUP BY MONTH(appoint_date), provider_type`

补贴发放 `biz_subsidy_grant_record`

项	条件
按年	`grant_date` 在 Y 年内（含起止日）
分组	`subsidy_type`：`1` 农业生产、`2` 住房基建、`3` 民生保障
指标	`SUM(subsidy_amount)`；服务端换算万元（÷10000，保留 2 位小数）

农技课堂

指标	表	条件
课程视频数	`biz_tech_resource`	`del_flag='0'` AND `publish_status=1` AND `resource_type='004008'` AND `publish_time` 落在 Y 年
实战培训场次	`biz_practical_training`	`del_flag='0'` AND `publish_status=1` AND `publish_time` 落在 Y 年
培训内容合计	—	视频数 + 场次数（应用层相加）

实战培训报名趋势 `biz_practical_training`

系列	条件
活动数/月	`del_flag='0'` AND `publish_status=1` AND `YEAR(training_time)=Y` AND `MONTH(training_time)=m` → `COUNT(*)`
报名人数/月	同上月的培训行，`SUM(actual_enrolled_count)`
无培训	`hasTrainingData=false`（§3.1），前端走空态，不强行全 0 曲线

养殖标准（分页，§3.2）

纳入：publish_status=1；DATE(create_time) 落在 Y 年内（与功能需求 §2.9 一致）。

Tab → 物理表与 standard_type 白名单

`category`（请求枚举）	表	`standard_type IN`
`BREEDING_MGMT`	`biz_breeding_standard`	`001001`,`001002`,`001003`,`001004`
`FEEDING`	`biz_feeding_standard`	`001005`,`001006`
`EQUIPMENT`	`biz_equipment_work_standard`	`001007`,`001008`,`001009`,`001010`
`TREATMENT`	`biz_epidemic_treatment_standard`	`001013`
`GROWTH`	`biz_growth_slaughter_standard`	`001011`,`001012`

排序：create_time DESC, id DESC。

2.5 索引建议（既有表）

表	建议
`biz_yak_asset`	`(pasture_id, del_flag, asset_status)`、`status_change_date`
`biz_service_appointment`	沿用 `idx_appoint_date`、`idx_provider`
`biz_subsidy_grant_record`	沿用 `idx_grant_date`、`idx_subsidy_type`
`biz_tech_resource`	`(resource_type, publish_status, publish_time)`
`biz_practical_training`	沿用 `idx_training_time`、`idx_publish`
各 `biz_*_standard`	沿用 `idx_create_time`、`idx_type`

2.6 Mapper 扩展（建议）

Mapper	方法	说明
`HomeScreenStatsMapper`	`selectLatestHerdInventoryStatPeriodByYear`、`selectLatestOutboundReportStatPeriodByYear`、`selectLatestFarmerHouseholdStatPeriodByYear`、`sumFarmerHouseholdCountByStatYearMonth`、`selectLatestHerdInventoryStatPeriod`、`selectLatestOutboundReportStatPeriod`、`selectHerdInventoryBullCowByYearMonthRange`、`selectOutboundReportYakCountByYearMonthRange`、`selectTownMapMarkers` 等	填报表聚合
`BreedingIndustryStatsMapper`	（复用）	草场统计
`BizSupplierMapper` / `BizDistributorMapper` / `BizTradeMarketMapper`	`countForScreen()`	主数据条数
`BizServiceAppointmentMapper`	`selectStatsByYear(int y)`	返回 appoint_date、provider_type 明细或按月聚合行
`BizSubsidyGrantRecordMapper`	`sumAmountByTypeForYear(int y)`	三类金额
`BizTechResourceMapper`	`countPublishedVideoByYear(int y)`	`004008`
`BizPracticalTrainingMapper`	`countPublishedByYear` / `selectPublishedByYear`	场次与按月趋势
`HomeScreenStandardMapper`	`selectListForScreen(category, y, ...)`	按 §2.4 Tab 路由到对应表

大屏首页牦牛趋势/出栏不调用 BreedingIndustryCalculator 月末还原；填报缺月由 HomeScreenSupport.buildRolling12Month* 补 0。

3. 接口设计

统一响应：AjaxResult（code / msg / data）；标准列表用 TableDataInfo（rows / total）。

权限标识（示例）：bigScreen:home:query

Base Path：/bigScreen/home

#	说明	Method	URI	权限
3.1	看板主数据（除标准分页外全部区块）	GET	`/bigScreen/home/dashboard`	`bigScreen:home:query`
3.2	养殖标准分页列表	GET	`/bigScreen/home/standards`	同上
3.3	地图标注（乡镇存栏/出栏）	GET	`/bigScreen/home/townMapMarkers`	同上
3.4	草畜失衡预警明细	GET	`/bigScreen/home/grassLivestockImbalanceWarnings`	同上
3.5	人均收入情况明细	GET	`/bigScreen/home/perCapitaIncomes`	同上
3.6	农牧户数据明细（草场面积明细复用本接口）	GET	`/bigScreen/home/farmerHouseholds`	同上
3.7	合作社发展数据明细	GET	`/bigScreen/home/cooperativeDevelopments`	同上
3.8	家庭牧场数据明细	GET	`/bigScreen/home/familyRanches`	同上
3.9	养殖大户数据明细	GET	`/bigScreen/home/largeLivestockFarmers`	同上
3.10	牦牛出栏数据明细	GET	`/bigScreen/home/yakOutboundReports`	同上
3.11	牦牛存栏数据明细	GET	`/bigScreen/home/yakHerdInventories`	同上
3.12	有无畜户数据明细	GET	`/bigScreen/home/livestockOwnershipHouseholds`	同上
3.13	牦牛存出栏情况明细	GET	`/bigScreen/home/yakInventoryOutbounds`	同上
3.14	养殖主体数量明细	GET	`/bigScreen/home/breedingEntityQuantities`	同上
3.15	乡镇列表	GET	`/bigScreen/home/townOptions`	同上
3.16	村树结构	GET	`/bigScreen/home/villageTree`	同上

前端：切换 statYear → 3.1 + 3.2（pageNum=1）+ 3.3；仅翻页 / 切 Tab → 3.2；进入首页 → 3.1 + 3.2 + 3.3。

3.1 看板主数据

Query

参数	类型	必填	说明
`statYear`	string	Y	四位年份；非法 → 业务异常（复用 `AchievementReportValidation.parseStatYear`）
`forceRefresh`	boolean	N	默认 `false`；`true` 时跳过 §2.3 缓存

响应 `data`（顶层）

字段	类型	说明
`statYear`	int	回显
`statDate`	string	统计时点 `yyyy-MM-dd`
`availableYears`	int[]	各业务表出现过的年份并集 + 当前年，降序
`industryOverview`	object	产业总览八项 §3.1.1
`inventoryChange`	object	存栏变动 §3.1.2
`ageStructure`	array	年龄结构 §3.1.3
`outboundMonthly`	array	出栏按月 §3.1.4
`grassland`	object	草场 §3.1.5
`appointment`	object	预约 §3.1.6
`subsidy`	object	补贴 §3.1.7
`agriClassroom`	object	农技课堂 §3.1.8
`trainingTrend`	object	实战培训报名 §3.1.9

3.1.1 `industryOverview`

字段	说明
`inventoryTotal`	牦牛存栏（头），所选年 Y 内最大填报月全县村级 `yak_total` 合计
`annualOutbound`	年出栏（头），所选年 Y 内最大填报月全县村级 `yak_outbound_count` 合计
`pastureCount`	农牧户（户），所选年 Y 内 `biz_farmer_household` 最大填报月全县村级 `household_count` 合计
`cooperativeCount`	合作社（个），所选年 Y 内 `biz_cooperative_development` 最大填报月记录条数
`familyRanchCount`	家庭牧场（个），所选年 Y 内 `biz_family_ranch` 最大填报月记录条数
`largeLivestockFarmerCount`	养殖大户（个），所选年 Y 内 `biz_large_livestock_farmer` 最大填报月记录条数
`withLivestockHouseholdCount`	有畜户数（户），所选年 Y 内 `biz_livestock_ownership_household` 最大填报月全县村级 `with_livestock_household_count` 合计
`grasslandCount`	草场块数（台账快照，供草场类型区块）
`grasslandAreaMu`	草场面积（亩），所选年 Y 内 `biz_farmer_household` 最大填报月全县村级 `pasture_contract_area` 合计
`supplierCount` / `distributorCount` / `tradeMarketCount`	流通三项实时快照（接口保留；首页卡片改展示合作社等）

3.1.2 `inventoryChange`

字段	说明
`bullCount` / `cowCount` / `unknownGenderCount`	存栏表最近填报年月全县公/母/`yak_total` 合计
`monthlyTrend`	固定 12 条；滚动最近 12 自然月；不随 `statYear` 变

monthlyTrend[]：

字段	说明
`statYear`	所属自然年
`month`	所属月份 1～12
`bullCount` / `cowCount`	该 `statYear-month` 全县填报合计；无数据为 0

3.1.3 `ageStructure[]`

字段	说明
`bandCode`	`COW_YOUNG` / `COW_ADULT`
`bandLabel`	`0～1.5岁幼畜` / `1.5岁以上成畜`
`count` / `ratio`	头数；占比 0～100 数值

两档固定返回；无存栏时 count=0，ratio=0。对齐存栏填报 cow_young_count / cow_adult_count。

3.1.4 `outboundMonthly[]`

字段	说明
`statYear`	所属自然年
`month`	所属月份 1～12
`outboundCount`	该月全县出栏头数；无数据为 0

固定 12 条；滚动窗口规则同 §3.1.2 monthlyTrend。

3.1.5 `grassland`

字段	说明
`availableCount` / `inUseCount`	可用 / 使用中（个）
`degradationStats[]`	`degradationLevel`(1～5)、`degradationLabel`、`count`、`ratio`（% 数值）

五档固定返回。

3.1.6 `appointment`

字段	说明
`annualVetCount` / `annualExpertCount` / `annualOrgCount`	三类年度合计
`monthlyStacked[]`	固定 12 条；滚动最近 12 自然月；不随 `statYear` 变

monthlyStacked[]：statYear、month、vetCount、expertCount、orgCount（缺月各计数为 0）。

3.1.7 `subsidy`

字段	说明
`typeStats[]`	固定 3 条：`subsidyType`(1～3)、`subsidyTypeName`、`amountWan`（万元）
`hasSubsidyData`	Y 年是否存在任一条发放记录

3.1.8 `agriClassroom`

字段	说明
`videoCourseCount`	视频课程数
`practicalTrainingCount`	实战培训场次
`trainingContentTotal`	二者之和
`hasAgriData`	两项是否均为 0

3.1.9 `trainingTrend`

字段	说明
`hasTrainingData`	滚动 12 月窗口内是否存在已发布且 `training_time` 落在窗口内的培训
`monthly[]`	固定 12 条；`statYear`、`month`、`activityCount`、`enrolledCount`

hasTrainingData=false 时 monthly 仍为 12 条全 0（前端以 hasTrainingData 走空态）。

响应示例（节选）

{
  "statYear": 2026,
  "statDate": "2026-05-20",
  "availableYears": [2026, 2025],
  "industryOverview": {
    "inventoryTotal": 120,
    "annualOutbound": 8,
    "pastureCount": 12,
    "grasslandCount": 80,
    "grasslandAreaMu": 12500.50,
    "supplierCount": 5,
    "distributorCount": 3,
    "tradeMarketCount": 2
  },
  "inventoryChange": {
    "bullCount": 45,
    "cowCount": 60,
    "unknownGenderCount": 15,
    "monthlyTrend": [
      { "statYear": 2025, "month": 8, "bullCount": 40, "cowCount": 55 },
      { "statYear": 2026, "month": 7, "bullCount": 45, "cowCount": 60 }
    ]
  },
  "outboundMonthly": [
    { "statYear": 2025, "month": 8, "outboundCount": 0 },
    { "statYear": 2026, "month": 5, "outboundCount": 88 }
  ],
  "appointment": {
    "annualVetCount": 10,
    "annualExpertCount": 5,
    "annualOrgCount": 8,
    "monthlyStacked": [{ "month": 1, "vetCount": 2, "expertCount": 1, "orgCount": 0 }]
  },
  "trainingTrend": { "hasTrainingData": true, "monthly": [{ "month": 3, "activityCount": 1, "enrolledCount": 20 }] }
}

服务端逻辑（摘要）

1. year = parseStatYear(statYear); statDate = resolveStatDate(year)
2. anchor = YearMonth.now(Asia/Shanghai); startYm/endYm = 锚点向前 11 月～锚点（yyyyMM）
3. latestHerd / latestOutbound = 各表最近 stat_year+stat_month
4. industryOverview 三项 = 最近年月全县合计（与 year 无关）
5. inventoryChange header + ageStructure = latestHerd 年月全县合计
6. monthlyTrend = buildRolling12MonthBullCowTrend(selectHerd...Range(startYm,endYm), anchor)
7. outboundMonthly = buildRolling12MonthOutbound(selectOutbound...Range(startYm,endYm), anchor)
8. grassland / tradeCounts / appointment / subsidy / agri / training = 按 year 或实时（同前）
9. return AjaxResult.success(vo)

3.2 养殖标准分页列表

Query

参数	类型	必填	说明
`statYear`	string	Y	同 3.1
`category`	string	Y	`BREEDING_MGMT` / `FEEDING` / `EQUIPMENT` / `TREATMENT` / `GROWTH`
`pageNum`	int	N	默认 `1`
`pageSize`	int	N	默认 `10`；建议 5～10

响应

TableDataInfo：rows 为 §3.2.1 数组，total 为当前 Tab 下符合条件的总数。

不提供大屏专用 GET /standards/{id}；行内详情字段一次返回（对齐共同富裕列表约定）。

3.2.1 `rows[]`

字段	类型	说明
`id`	long	标准 ID
`standardName`	string	标准名称
`standardType`	string	类型编码
`standardTypeName`	string	类型展示名（字典/资讯类别）
`introduction`	string	简介
`contentFileUrl`	string	正文附件 URL
`coverFileUrl`	string	封面 URL，可空
`createTime`	string	创建时间
`publishTime`	string	发布时间

默认排序：create_time DESC, id DESC。

3.3 地图标注

Query

参数	类型	必填	说明
`statYear`	string	是	统计年份 Y，如 `2026`

存栏/出栏各取所选年内最大 stat_month（两表可不同月）：

字段	说明
`herdStatYear` / `herdStatMonth`	存栏表所选年内最大填报年月
`outboundStatYear` / `outboundStatMonth`	出栏表所选年内最大填报年月

响应 `data`

字段	类型	说明
`herdStatYear`	int	存栏数据填报年（可空）
`herdStatMonth`	int	存栏数据填报月（可空）
`outboundStatYear`	int	出栏数据填报年（可空）
`outboundStatMonth`	int	出栏数据填报月（可空）
`markers`	array	乡镇标注列表，见下表

markers[]：

字段	类型	说明
`townDeptId`	long	所属乡镇 `dept_id`（`sys_dept`）
`townName`	string	乡镇名称
`yakInventoryCount`	int	牦牛存栏数（头），该乡镇下各村 `yak_total` 合计；无填报为 0
`yakOutboundCount`	int	牦牛出栏数（头），该乡镇下各村 `yak_outbound_count` 合计；无填报为 0

乡镇范围

与牦牛存栏/出栏填报模块一致：sys_dept 中 parent_id = 100、order_num > 12、del_flag = '0'、status = '0'，按 order_num、dept_id 升序。

服务端逻辑（摘要）

1. year = parseStatYear(statYear)
2. yearHerd = selectLatestHerdInventoryStatPeriodByYear(year)
3. yearOutbound = selectLatestOutboundReportStatPeriodByYear(year)
4. markers = selectTownMapMarkers(herdYear, herdMonth, outboundYear, outboundMonth)
   （按 town_dept_id 汇总各村合计；无年月时该侧为 0）
5. return AjaxResult.success(vo)

3.5 人均收入情况明细

Query

参数	类型	必填	说明
`statYear`	int	N	所属年份；未传默认当前自然年
`pageNum` / `pageSize`	int	N	分页（PageHelper）

排序：stat_year DESC, id DESC。

数据源：biz_disposable_income。

响应 `rows[]`

字段	类型	说明
`statYear`	int	年份
`ruralDisposableIncome`	decimal	农村居民人均可支配收入（元）
`incomeIncrease`	decimal	增幅（元）
`incomeGrowthRate`	decimal	增速（%）
`povertyNetIncome`	decimal	脱贫人口人均纯收入（元）

3.6 农牧户数据明细（草场面积明细复用）

草场面积数据明细不另开接口，直接调用本接口；产业总览草场面积取自同表 pasture_contract_area（全县最大月合计），明细行内字段为 pastureContractArea（及禁牧/草畜平衡等面积相关列）。

Query

参数	类型	必填	说明
`statYear`	int	N	所属年份；未传默认当前自然年
`statMonth`	int	N	所属月份；未传默认当前自然月
`townDeptId`	long	N	所属乡镇
`villageDeptId`	long	N	所属村
`pageNum` / `pageSize`	int	N	分页（PageHelper）

排序：stat_year DESC, stat_month DESC, …（与填报列表一致）。

数据源：biz_farmer_household（全县口径，清空 dataScope）。

响应 `rows[]`

返回填报全部业务字段，含：id、statYear、statMonth、townDeptId、townName、villageDeptId、villageName、householdCount、populationCount、pastureContractArea、grazingBanArea、grassBalanceArea、approvedCarryingCapacity、yearEndStockSheepUnit、isPureHerder、isNoLivestock、isExtinctHousehold、isOverloadHerder、needCap、needFloor、grazingBanSubsidy、grassBalanceReward、subsidyRewardSubtotal、afterCapFloorSubsidy、villageSupervisorSubsidy、subsidyTotal。

3.7～3.9 合作社 / 家庭牧场 / 养殖大户数据明细

Query（三者相同）

参数	类型	必填	说明
`statYear`	int	N	所属年份；未传默认当前自然年
`statMonth`	int	N	所属月份；未传默认当前自然月
`townDeptId`	long	N	所属乡镇
`villageDeptId`	long	N	所属村
`pageNum` / `pageSize`	int	N	分页（PageHelper）

排序：stat_year DESC, stat_month DESC, …（与各自填报列表一致）。全县口径，清空 dataScope。

#	URI	数据源	响应
3.7	`/cooperativeDevelopments`	`biz_cooperative_development`	全部业务字段（含 `cooperativeName`、`businessModel` 等）
3.8	`/familyRanches`	`biz_family_ranch`	全部业务字段（含 `enterpriseName`、收入支出补助等）
3.9	`/largeLivestockFarmers`	`biz_large_livestock_farmer`	全部业务字段（含 `enterpriseName`、存栏出栏草场等）
3.10	`/yakOutboundReports`	`biz_yak_outbound_report`	全部业务字段（含出栏六畜、自食三项等）
3.11	`/yakHerdInventories`	`biz_yak_herd_inventory`	全部业务字段（含公母牛/奶牛/羊/保险等）
3.12	`/livestockOwnershipHouseholds`	`biz_livestock_ownership_household`	全部业务字段（有畜/无畜户数人数劳动力等）

查询条件与 3.7～3.9 相同：年/月默认当前年月，乡镇/村可选；按年、月倒序；全县口径清空 dataScope。

3.13 牦牛存出栏情况明细

Query

参数	类型	必填	说明
`statYear`	int	N	所属年份；未传不过滤（支持跨多年全量翻页）
`statMonth`	int	N	所属月份；未传不过滤
`townDeptId`	long	N	所属乡镇
`villageDeptId`	long	N	所属村
`pageNum` / `pageSize`	int	N	分页（PageHelper）

关联：biz_yak_herd_inventory 为主表 LEFT JOIN biz_yak_outbound_report（唯一键 (stat_year, stat_month, village_dept_id)），UNION ALL 补仅出栏侧有数据的行；缺一侧时对应计数为 0。

排序：stat_year DESC, stat_month DESC, town_dept_id ASC, village_dept_id ASC（对齐唯一键，利于索引序）。

性能说明：条件下推至基表；关联走 uk_year_month_village；跨年全量时仍建议控制 pageSize，超深 offset 会随页码增大变慢。

响应 `rows[]`

字段	说明
`statYear` / `statMonth`	年份、月份
`townDeptId` / `townName`	乡镇
`villageDeptId` / `villageName`	村
`yakTotal`	牦牛总存栏数（头）
`yakOutboundCount`	牦牛总出栏数（头）

3.14 养殖主体数量明细

Query

参数	类型	必填	说明
`statYear`	int	N	所属年份；未传不过滤（支持跨多年全量翻页）；前端筛选项可默认当前年
`statMonth`	int	N	所属月份；未传不过滤；前端筛选项可默认当前月
`townDeptId`	long	N	所属乡镇
`villageDeptId`	long	N	所属村
`pageNum` / `pageSize`	int	N	分页（PageHelper）

关联：以 biz_farmer_household 为主表，按 (stat_year, stat_month, village_dept_id) 相关子查询计数合作社 / 家庭牧场 / 养殖大户条数（无则 0）。

排序：stat_year DESC, stat_month DESC, town_dept_id ASC, village_dept_id ASC。

性能：主表驱动 + 本页行相关子查询（走各表村年月索引）；COUNT 可收敛为主表条件计数。

响应 `rows[]`

字段	说明
`statYear` / `statMonth`	年份、月份
`townDeptId` / `townName`	乡镇
`villageDeptId` / `villageName`	村
`farmerHouseholdCount`	农牧户数（户）
`cooperativeCount`	合作社（个）
`familyRanchCount`	家庭牧场（个）
`largeLivestockFarmerCount`	养殖大户（个）

3.15 乡镇列表

无 Query。响应 data[]：deptId、deptName、orderNum。全县填报乡镇（与地图标注乡镇口径一致），不按登录人数据权限收窄。

3.16 村树结构

无 Query。响应 data[] 为 TreeSelect：县（根）→ 乡镇 → 村；仅叶子村为筛选目标。全县口径。

4. 前端实现要点

工程：ruoyi-screen/src/views/home/（index.vue、chartOptions.js）。

4.1 滚动 12 月图表（存栏 / 出栏 / 预约 / 培训）

项	实现
数据字段	`monthlyTrend[]`、`outboundMonthly[]`、`appointment.monthlyStacked[]`、`trainingTrend.monthly[]`
排序	按 `statYear`、`month` 升序
横轴	仅月份（`8月`）；`chartOptions.js`
Tooltip	完整年月（`2025年8月`）+ 数值
与 `statYear`	切换年份不改变上述图表数据窗口

5. 菜单与权限（示例）

类型	名称	权限标识
菜单	大屏首页	`bigScreen:home:query`

SQL 示例：sql/big_screen_home_perm.sql（挂载「大屏」父菜单下）。

6. 交付清单

HomeScreenController + IHomeScreenService + VO + HomeScreenSupport
复用 BreedingIndustryStatsMapper / BreedingIndustryCalculator（按 Y 与全县牧场）
预约、补贴、标准、科技资源、实战培训 Mapper 扩展（§2.6）
单元测试：滚动 12 月补 0、statYear+month、主数据不随 Y 变、地图所选年最大填报月
接口测试：/bigScreen/home/dashboard、/standards、/townMapMarkers
菜单权限 SQL；依赖各业务表 DDL 已执行

7. 修订记录

版本	日期	说明
1.17	2026-07-23	新增大屏 `/townOptions`、`/villageTree`（全县口径）
1.16	2026-07-23	新增养殖主体数量明细分页接口 `/breedingEntityQuantities`
1.15	2026-07-23	`/yakInventoryOutbounds`：年月未传不过滤；SQL 改为存栏主表 LEFT JOIN + UNION ALL 补仅出栏
1.14	2026-07-23	新增牦牛存出栏情况明细分页接口 `/yakInventoryOutbounds`
1.13	2026-07-23	明确草场面积数据明细复用 `/farmerHouseholds`，不另开接口
1.12	2026-07-23	新增牦牛出栏/存栏、有无畜户明细分页接口
1.11	2026-07-23	新增合作社/家庭牧场/养殖大户明细分页接口
1.10	2026-07-23	新增农牧户数据明细分页接口 `/farmerHouseholds`（默认当前年月、按时间倒序）
1.9	2026-07-23	新增人均收入情况明细分页接口 `/perCapitaIncomes`（默认当前年、按年倒序）
1.8	2026-07-23	地图标注改为所选年最大填报月按乡镇汇总；`townMapMarkers` 增 `statYear` 与填报月字段
1.7	2026-07-23	有畜户数、草场面积改为填报表所选年最大月合计
1.6	2026-07-23	产业总览增合作社/家庭牧场/养殖大户（所选年最大填报月记录数）
1.5	2026-07-23	产业总览农牧户改 `biz_farmer_household` 所选年最大填报月村级合计
1.4	2026-07-23	产业总览存栏/出栏改为所选年最大填报月全县村级合计
1.3	2026-07-17	年龄结构两档 `COW_YOUNG`/`COW_ADULT`，字段 `cow_young_count`/`cow_adult_count`
1.2	2026-07-04	预约堆叠、培训趋势改滚动 12 月 + statYear；前端横轴/Tooltip 与存栏出栏一致
1.1	2026-07-04	存栏/出栏改填报表滚动 12 月；VO 增 `statYear`；年龄四档；地图/总览最近填报年月；§4 前端横轴/Tooltip
1.0	2026-05-20	初稿：无新表；双接口；对齐 `大屏首页功能需求.md` v1.0

大屏首页技术方案.md 31KB Історія Запис

大屏 — 首页统计 — 技术方案

1. 技术架构

2. 数据库设计

2.1 本模块业务表

2.2 公共参数

2.3 可选表 biz_home_screen_cache（性能优化）

2.4 查询口径（按表）

牦牛填报（大屏首页存栏/出栏/年龄/趋势/地图）

养殖产业档案（草场等，复用 Mapper）

流通主数据（实时，与 Y 无关）

服务预约 biz_service_appointment

补贴发放 biz_subsidy_grant_record

农技课堂

实战培训报名趋势 biz_practical_training

养殖标准（分页，§3.2）

2.5 索引建议（既有表）

2.6 Mapper 扩展（建议）

3. 接口设计

3.1 看板主数据

Query

响应 data（顶层）

3.1.1 industryOverview

3.1.2 inventoryChange

3.1.3 ageStructure[]

3.1.4 outboundMonthly[]

3.1.5 grassland

3.1.6 appointment

3.1.7 subsidy

3.1.8 agriClassroom

3.1.9 trainingTrend

响应示例（节选）

服务端逻辑（摘要）

3.2 养殖标准分页列表

Query

响应

3.2.1 rows[]

3.3 地图标注

Query

响应 data

乡镇范围

服务端逻辑（摘要）

3.5 人均收入情况明细

Query

响应 rows[]

3.6 农牧户数据明细（草场面积明细复用）

Query

响应 rows[]

3.7～3.9 合作社 / 家庭牧场 / 养殖大户数据明细

Query（三者相同）

3.13 牦牛存出栏情况明细

Query

响应 rows[]

3.14 养殖主体数量明细

Query

响应 rows[]

3.15 乡镇列表

3.16 村树结构

4. 前端实现要点

4.1 滚动 12 月图表（存栏 / 出栏 / 预约 / 培训）

5. 菜单与权限（示例）

6. 交付清单

7. 修订记录

大屏首页技术方案.md 31KB

Історія Запис

2.3 可选表 `biz_home_screen_cache`（性能优化）

服务预约 `biz_service_appointment`

补贴发放 `biz_subsidy_grant_record`

实战培训报名趋势 `biz_practical_training`

响应 `data`（顶层）

3.1.1 `industryOverview`

3.1.2 `inventoryChange`

3.1.3 `ageStructure[]`

3.1.4 `outboundMonthly[]`

3.1.5 `grassland`

3.1.6 `appointment`

3.1.7 `subsidy`

3.1.8 `agriClassroom`

3.1.9 `trainingTrend`

3.2.1 `rows[]`

响应 `data`

响应 `rows[]`

响应 `rows[]`

响应 `rows[]`

响应 `rows[]`