西藏巴青项目

养殖产业数据 — 功能需求

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 牦牛「存栏」认定

用于存栏总量、性别结构、年龄结构、存栏趋势等。

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

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

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

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

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

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

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

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

指标/图表	数据源	规则
总览存栏	`biz_yak_herd_inventory.yak_total`	全县合计；最近填报年月（`stat_year`+`stat_month` 最大）
总览出栏、农牧户	`biz_yak_outbound_report`	同上最近填报年月；字段 `yak_outbound_count`、`farmer_household_count`
公/母牛数量	`biz_yak_herd_inventory`	最近填报年月全县 `bull_total`、`cow_total`
存栏趋势	`biz_yak_herd_inventory`	距当前 12 个自然月；按月全县公/母合计；缺月 0
年龄结构	`biz_yak_herd_inventory`	最近填报年月母牛四龄档合计

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

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

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_yak_outbound_report.farmer_household_count` 全县乡镇合计；最近填报年月；接口字段 `pastureCount`
5	草场数量	个	§2.6
6	草场面积	亩	§2.6

展示规则：

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

5.3 牦牛存栏变动

5.3.1 当前性别结构（数字）

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

指标	单位	口径
公牛数量	头	`biz_yak_herd_inventory.bull_total` 全县乡镇合计；取最近填报年月（`stat_year` + `stat_month` 最大）
母牛数量	头	`biz_yak_herd_inventory.cow_total` 全县乡镇合计；同上

不展示「未标注性别」；与大屏首页存栏变动 header 口径一致。

5.3.2 存栏趋势（折线图）

项	要求
图表类型	折线图（公牛、母牛两系列）
数据范围	距当前时间最近 12 个自然月（与大屏「牦牛存栏变动」一致）
横轴	12 个刻度，仅显示月份；悬停展示 YYYY年M月
纵轴	存栏数量，单位头
接口字段	`monthlyTrend[]` 含 `statYear`、`month`、`bullCount`、`cowCount`；缺月补 0

5.4 牦牛年龄结构

项	要求
图表类型	饼图（或环形图，与原型一致）
统计对象	存栏填报最近年月全县母牛分龄合计
分档	四档（与大屏一致）：1岁以下、1～3岁、3～12岁、12岁以上
编码	`COW_U1` / `COW_1_3` / `COW_3_12` / `COW_O12`
展示	每档展示头数与占比（%）；各档占比之和为 100%（四舍五入 ±1% 可接受）

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
草场可用/使用中 + 退化占比	§5.5、§2.7、§2.8
只读看板	§3、§5.1

11. 修订记录

版本	日期	说明
1.2	2026-07-04	存栏变动/年龄/总览三项改填报表；滚动 12 月；母牛四档；与大屏对齐
1.1	（既有）	总览存栏/出栏/农牧户改填报合计

养殖产业数据功能需求.md 18KB Vēsture Neapstrādāts