huimv-baqing/doc/产业数据模型及服务/养殖产业数据/养殖产业数据功能需求.md

养殖产业数据 — 功能需求

1. 文档说明

项	说明
模块名称	养殖产业数据
目标	以看板形式集中展示县域（或授权范围内）牦牛养殖与草场资源的关键指标与结构，支撑产业监管、决策研判与日常巡查
关联系统	业务后台（单页看板，只读展示）
修订依据	同目录 养殖产业数据功能需求-草稿.md、界面原型（Snipaste_2026-05-19_12-33-09.jpg）

本文档仅描述功能需求与业务规则，不涉及库表结构、接口路径、请求参数字段命名、技术栈选型及实现方案。

---

2. 术语与统计口径

2.1 看板与数据性质

• 本模块为只读数据看板：不提供指标手工录入、修改、删除；所有数值由关联业务模块台账或同步数据汇总计算后展示。
  
• 页面自上而下分为四个功能区：产业总览、牦牛存栏变动、牦牛存栏结构、草场类型占比（与原型布局一致）。
  
• 指标非最终版：草稿说明产业数据可能随第三方对接扩展；新增指标须修订本文档并更新原型。

2.2 统计范围与时间

项	约定
空间范围	见 §2.9 数据权限与纳入范围
「当前」时点	用户打开或刷新看板时的系统日期（记为 统计日）；各「当前存栏」类指标按统计日计算
趋势图月份	横轴为当前自然年 1 月～12 月；未到来的月份不展示数据点（折线止于当前月）
自然年	公历当年 1 月 1 日 0:00～12 月 31 日 23:59:59

看板进入时自动加载最新统计结果；须提供刷新操作重新计算（见 §5.1）。页面不自动定时刷新（§8 扩展项除外）。

2.3 牦牛「存栏」认定

用于存栏总量、性别结构、存栏趋势等（档案口径，预警等仍可能引用；看板主指标见 §2.11）。

规则	说明
纳入存栏	「牦牛资产档案」中档案有效（未逻辑删除），且资产状态为 正常 的个体
不纳入存栏	资产状态为 死淘、丢失、出栏 的个体
性别	以档案「性别」为准，分为 公、母；性别为空或无法映射为公/母的个体不计入公、母分项，计入存栏总量
月龄	优先按档案「月龄」字段；缺失时由「出生日期」与统计日计算整月龄（不足 1 月记为 0 月龄）

2.4 牦牛年出栏量

规则	说明
统计周期	当前自然年 1 月 1 日 0:00 至统计日 24:00
计数对象	资产状态为 出栏，且 状态变更日期 落在上述周期内的档案（按头计，一头一条档案计 1）
去重	同一牦牛编号仅计 1 次
缺失变更日期	状态变更日期为空的出栏档案不计入年出栏量（计入数据质量风险，由档案同步维护解决）

2.5 预警牦牛数量

与「牦牛疾病预警」模块对齐，本看板只展示结果，不维护预警。

规则	说明
统计周期	当前自然年 1 月 1 日 0:00 至 统计日 23:59:59（与「牦牛疾病预警」§5.6 一致）
计数方式	周期内存在至少 1 条未逻辑删除预警记录的 去重牦牛编号 头数
处置状态	本期无预警处置闭环，不区分是否已读/已处理，凡在周期内且未删除的预警均参与去重计数

2.6 牧场与草场（总览用）

指标	规则（默认）
牧场数量	「牧场管理」中未逻辑删除，且经营状态为 正常 的主体条数，单位 个
草场数量	「草场管理」中未逻辑删除的草场条数，单位 个
草场面积	上述有效草场的面积字段之和，单位 亩；面积为空的不计入求和

2.7 草场「可用」与「使用中」

用于 §5.5 草场类型占比区上部数量展示。

分类	含义（默认）
可用草场	未逻辑删除的草场中，退化等级为 未退化 或 轻度 的条数（视为具备利用或改良潜力的资源）
使用中草场	未逻辑删除的草场中，利用类型为 全年放牧 或 轮牧 的条数；若利用类型为 禁牧，仅当当前日期不在该条记录填写的禁牧开始～结束日期闭区间内时，计入「使用中」，否则不计入

逻辑关系：「使用中」为「可用」资源的子集场景之一；可用 + 使用中 不宜简单相加为总量（二者有交叉）。界面分别展示两个数字即可（与原型一致）。
退化等级取值与「草场管理」§2.1 一致：未退化、轻度、中度、重度、极重度。

2.8 草场退化结构占比

对未逻辑删除的全部草场，按退化等级分组：

• 统计各等级的条数；
  
• 计算各等级条数占草场总条数的百分比（保留 1 位小数或整数百分比，与界面一致）；
  
• 五类等级均需展示；某等级为 0 时显示 0 及 0%。

2.9 数据权限与纳入范围

对象	纳入规则
牧场	未逻辑删除，且经营状态为 正常；且落在当前用户可见牧场集合内（与项目全局数据权限一致）
牦牛	未逻辑删除；档案 pasture_id 非空且对应牧场在用户可见牧场集合内；pasture_id 为空的档案不参与看板任何牦牛类统计
草场	未逻辑删除；本期按用户全县（或授权区域）草场台账统计，不按牧场拆分校准（与草场管理台账一致）
预警	仅统计牦牛编号落在上述「纳入统计的牦牛」集合内的预警记录

县级管理员可见全部主体时，等价于全量有效台账统计。

2.10 历史月末存栏还原（趋势图）

折线图各月数值须在该月最后一日还原「当日应计入存栏」的个体数（应用 §2.3 的存栏语义，按时点而非仅看当前状态）。

记 月末日 为自然月最后一天。非正常资产状态指：死淘（2）、丢失（3）、出栏（4）。

在 月末日 时点，档案计入当月存栏，当且仅当同时满足：

1. 档案未逻辑删除，且符合 §2.9 纳入范围；
   
2. 不满足：当前 asset_status 为非正常状态 且 status_change_date 不为空 且 status_change_date ≤ 月末日（表示该日或之前已变为死淘/丢失/出栏）；
   
3. asset_status 为 正常（1），或虽当前为非正常但 status_change_date 晚于 月末日（月末时尚未发生该次状态变更）；
   
4. asset_status 无法识别时，不计入。

当前月折线点：月末日尚未结束时，以 统计日 代替月末日执行上式。

状态变更日期为空且当前为非正常状态：该个体在所有历史月末均不计入存栏趋势。

看板说明（v1.5）：§5.3 存栏变动、§5.4 牦牛存栏结构及总览存栏/出栏/农牧户/草场面积已改由 §2.11 填报表 按所选年统计，不再使用本节档案月末还原。本节保留供档案类指标（如预警关联档案）参考。

2.11 存栏出栏填报（看板主口径）

与大屏首页一致，数据来自乡镇填报表：

指标/图表	数据源	规则
总览存栏	biz_yak_herd_inventory.yak_total	全县合计；所选年内最大填报月
总览出栏	biz_yak_outbound_report.yak_outbound_count	同上；所选年最大填报月
农牧户、草场面积	biz_farmer_household	所选年最大填报月；household_count、pasture_contract_area（与大屏一致）
公/母牛数量	biz_yak_herd_inventory	所选年最大填报月全县 bull_total、cow_total；未标注=yak−公−母
存栏趋势	biz_yak_herd_inventory	所选年 1～填报最大月；缺月补 0；无填报为空数组
牦牛存栏结构	biz_yak_herd_inventory	与大屏 yakInventoryStructure 一致：所选年最大填报月公牛/母牛/保险及细分

默认年份：进入看板时所选年为当前自然年（可切换）。

---

3. 功能范围

本期实现：

能力	说明
产业总览	六项指标卡片展示，见 §5.2
牦牛存栏变动	当前公、母牛数量 + 按月存栏趋势图，见 §5.3
牦牛存栏结构	双层饼图（内环公牛·母牛·保险牛，外环细分），与大屏一致，见 §5.4
草场类型占比	可用/使用中数量 + 退化等级数量与占比，见 §5.5
刷新	重新拉取并计算全页指标，见 §5.1

本期不实现：

• 看板内指标的手工维护、阈值配置、报表导出、打印
  
• 点击指标跳转明细列表（若需下钻，另立需求）
  
• 按牧场、区域、自定义时间段的筛选（见 §8）
  
• 与第三方平台的独立同步入口（数据由各业务模块维护/同步后汇总）
  
• 移动端独立看板（若需，另立需求）
  

---

4. 业务流程

4.1 数据汇聚关系

flowchart TB
    subgraph sources [数据来源模块]
        A[牧场管理]
        G[草场管理]
        Y[牦牛资产档案管理]
        W[牦牛疾病预警]
    end
    subgraph board [养殖产业数据看板]
        O[产业总览]
        I[牦牛存栏变动]
        Age[牦牛存栏结构]
        Grass[草场类型占比]
    end
    A --> O
    G --> O
    G --> Grass
    Y --> O
    Y --> I
    Y --> Age
    W --> O

各业务模块按各自需求维护台账或同步数据；本看板不写入业务库，仅读取汇总。

4.2 用户使用路径

flowchart LR
    Enter[进入菜单] --> Load[自动加载全页指标]
    Load --> View[浏览四个功能区]
    View --> Refresh{需要最新数据?}
    Refresh -->|是| Reload[点击刷新]
    Reload --> View
    Refresh -->|否| Exit[离开页面]
    View --> Exit

1. 授权用户从菜单进入「养殖产业数据」。
   
2. 系统按 §2 口径计算并展示四块内容；加载中显示统一加载态。
   
3. 用户阅读总览卡片与图表；必要时点击刷新更新。
   
4. 离开页面不保留编辑状态（无表单）。

---

5. 详细功能需求

5.1 页面通用规则

项	要求
布局	单页纵向滚动；四块标题：产业总览、牦牛存栏变动、牦牛存栏结构、草场类型占比
年份	工具栏提供年份选择；默认当前自然年；切换后按所选年重算总览填报项、存栏变动、存栏结构（与大屏一致）
加载	首次进入全页加载；失败时给出明确提示，不得展示上一用户缓存数据冒充成功
刷新	页面提供「刷新」按钮（位置与全局规范一致，如右上角工具栏）；刷新中防重复点击；成功后更新全部指标与图表
空数据	某模块无数据时，数字显示 0 或「—」，图表展示空态说明，不报错崩溃
单位	界面须标注单位：头、个、亩、% 等，与 §5.2～§5.5 一致
权限	仅查询/查看权限；无新增、编辑、删除操作

5.2 产业总览

以指标卡片形式横向排列六项（与原型一致），每项包含指标名称、数值、单位（名称旁或数值旁标注）。

序号	指标名称	单位	统计口径
1	牦牛存栏总量	头	biz_yak_herd_inventory.yak_total 全县合计；所选年最大填报月；接口字段 inventoryTotal
2	牦牛年出栏量	头	biz_yak_outbound_report.yak_outbound_count 全县合计；所选年最大填报月；接口字段 annualOutbound
3	预警牦牛数量	头	§2.5（档案时点口径）
4	农牧户	户	biz_farmer_household.household_count 全县合计；所选年最大填报月；接口字段 pastureCount
5	草场数量	个	§2.6（台账块数）
6	草场面积	亩	biz_farmer_household.pasture_contract_area 全县合计；所选年最大填报月；接口字段 grasslandAreaMu

展示规则：

• 数值为非负整数（面积可为小数，保留位数与「草场管理」录入一致，默认最多 2 位小数）。
  
• 卡片仅展示，本期不提供点击跳转。
  
• 六项宜在同一屏首屏可见或略经滚动可见（以实现为准）。

5.3 牦牛存栏变动

5.3.1 当前性别结构（数字）

在趋势图上方展示两个指标（与原型一致）：

指标	单位	口径
公牛数量	头	biz_yak_herd_inventory.bull_total 全县合计；取所选年最大填报月
母牛数量	头	biz_yak_herd_inventory.cow_total 全县合计；同上

接口另回传 unknownGenderCount = max(0, yak−bull−cow)（与大屏一致；页面可不展示）。

5.3.2 存栏趋势（折线图）

项	要求
图表类型	折线图（公牛、母牛两系列）
数据范围	所选年 1～填报最大月（与大屏「牦牛存栏变动」一致）；无填报为空
横轴	按月刻度，仅显示月份；悬停展示 YYYY年M月
纵轴	存栏数量，单位 头
接口字段	monthlyTrend[] 含 statYear、month、bullCount、cowCount；区间内缺月补 0

5.4 牦牛存栏结构

项	要求
图表类型	双层饼图（内环大类、外环细分；与大屏「牦牛存栏结构」一致）
统计对象	存栏填报所选年最大填报月全县合计
内环	公牛 / 母牛 / 保险牛
外环	种公牛、公牛/阉畜、0～1.5岁、1.5岁以上、保险
接口字段	yakInventoryStructure[]（与大屏同结构）
默认年份	当前自然年
展示	内环/外环均展示头数与占比（%）；占比按牦牛总量（公牛+母牛+保险）计算

5.5 草场类型占比

本区上下两部分（与原型一致）。

5.5.1 利用状态数量

指标	单位	口径
可用草场	个	§2.7
使用中草场	个	§2.7

5.5.2 退化等级分布

项	要求
图表	环形图 + 列表（或表格）并列展示，与原型一致
维度	未退化、轻度、中度、重度、极重度
列表列	至少包含：退化等级名称、数量（个）、占比（%）
占比	§2.8；列表与图表数据一致
合计	五档数量之和 = §5.2 草场数量（在统计范围一致的前提下）

---

6. 与其他模块的关系

模块	关系
牧场管理	提供牧场数量；经营状态、逻辑删除规则影响是否计入
草场管理	提供草场数量、面积、退化等级、利用类型、禁牧日期；驱动可用/使用中及退化占比
牦牛资产档案管理	预警等仍关联档案；存栏变动/年龄已改填报表 §2.11
牦牛存栏数据填报	驱动总览存栏、公母数量、趋势、存栏结构
牦牛出栏数据填报	驱动总览出栏、农牧户
牦牛疾病预警	提供预警牦牛数量；周期与去重规则见 §2.5、该模块 §5.6
草畜平衡计算	本期看板不展示平衡指数；若后续纳入须修订本文档

依赖顺序（业务理解）： 看板数据正确性依赖各台账模块数据完整；档案未同步、草场未录入会导致对应指标偏低或为 0，界面不区分「真零」与「未录入」，必要时在 §7 用加载失败或运维提示说明。

---

7. 权限与提示

7.1 权限

操作	要求
查看看板	具备本模块菜单及查询权限
刷新	与查看一致，或单独「刷新」权限（默认与查看合并）
维护业务数据	在各自业务模块进行，本模块无维护入口

数据权限规则见 §2.9；过滤后各指标仅统计纳入范围内的牧场、牦牛、草场与预警。

7.2 提示场景

采用项目统一提示方式，不约定技术字段形态。

场景	提示方向（示例）
加载成功	无打扰式展示数据；可选轻提示「数据已更新」
加载失败	加载失败，请稍后重试
刷新中	正在刷新…
无权限	无权限访问
部分模块无数据	不单独弹窗；对应区域空态或 0

---

8. 非功能需求（建议）

类别	建议
性能	全页汇总宜在可接受时间内完成（如 ≤5 秒，视数据量评审）；大数据量时可分批渲染四块
一致性	刷新后四块数据同一统计时点
扩展	支持按牧场、乡镇、自定义年份筛选；支持导出 PNG/PDF
下钻	点击「预警牦牛数量」跳转预警列表并带筛选条件
历史趋势	支持选择历年对比存栏曲线
双语	界面 i18n（汉语 + 藏文）

---

9. 相对草稿的修订说明

草稿问题	处理
缺页面结构、刷新与加载	§5.1、§4.2
指标无统计口径	§2 分节定义；§5.2～§5.5 引用
存栏趋势「按月」未说明横轴与序列	§5.3.2、§2.11 滚动 12 月；横轴仅月、悬停显年月
年龄分档边界	§5.4 母牛四档（与大屏一致）
草场可用/使用中含义模糊	§2.7 与草场管理字段挂钩
退化占比分母	§2.8 有效草场总条数
技术栈、code/msg/data	已移除
未写数据来源	§4.1、§6
预警/出栏/性别等待定口径	§2.4～§2.5、§2.11、§5.3.1 已固化为填报表 + 预警档案口径

---

10. 需求追溯

能力	章节
产业总览六项	§5.2、§2.3～§2.6、§2.11
公母牛数量 + 月趋势	§5.3、§2.11
牦牛存栏结构双层饼	§5.4、§2.11
草场可用/使用中 + 退化占比	§5.5、§2.7、§2.8
只读看板	§3、§5.1

---

11. 修订记录

版本	日期	说明
1.5	2026-07-24	原「年龄结构」改为「牦牛存栏结构」，与大屏 yakInventoryStructure 双层饼口径一致；默认当前年
1.4	2026-07-24	产业总量/存栏变动/年龄与大屏按所选年对齐；默认当前年；农牧户与草场面积改农牧户填报
1.3	2026-07-17	年龄结构改为母牛两档（0～1.5 / 1.5+），与存栏填报、大屏对齐
1.2	2026-07-04	存栏变动/年龄/总览三项改填报表；滚动 12 月；母牛四档；与大屏对齐
1.1	（既有）	总览存栏/出栏/农牧户改填报合计