养殖产业数据功能需求.md 17KB
养殖产业数据 — 功能需求
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无法识别时，不计入。
当前月折线点：月末日尚未结束时，以 统计日 代替月末日执行上式。
状态变更日期为空且当前为非正常状态：该个体在所有历史月末均不计入存栏趋势。
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 全县乡镇合计；统计年 = 当前自然年 − 1；接口字段 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 当前性别结构（数字）
在趋势图上方或侧栏展示两个指标（与原型一致）：
| 指标 | 单位 | 口径 |
|---|---|---|
| 公牛数量 | 头 | 当前存栏中性别为「公」的头数 |
| 母牛数量 | 头 | 当前存栏中性别为「母」的头数 |
数量关系： 公牛数量 + 母牛数量 + 未标注性别数量 = §2.3 当前存栏时点总量（原档案口径，不等同于 §5.2 第 1 项填报合计）。当未标注性别数量 > 0 时，在公、母牛数量旁展示 「未标注性别：N 头」（N 为整数）。
5.3.2 存栏趋势（折线图）
| 项 | 要求 |
|---|---|
| 图表类型 | 折线图 |
| 横轴 | 当前自然年 1 月～12 月（标签：1月…12月） |
| 纵轴 | 存栏数量，单位 头 |
| 序列 | 存栏总量一条折线 |
| 各月数值 | 按 §2.10 计算；仅绘制 1 月～当前月 有定义的月份点，未来月份不绘制 |
| 当前月 | 以 统计日 作为时点代入 §2.10（代替月末日） |
| 图例 | 「存栏数量」（或与原型一致） |
与总览联动： 当前月折线点与 §2.10 月末还原存栏一致；§5.2 第 1 项已改为全县填报合计，不要求与折线当前月点数值相同。
5.4 牦牛年龄结构
| 项 | 要求 |
|---|---|
| 图表类型 | 饼图（或环形图，与原型一致） |
| 统计对象 | §2.3 当前存栏个体 |
| 分档 | 三档，互斥且穷尽（月龄按 §2.3）： |
| 档位 | 月龄区间 |
|---|---|
| 1-6月龄 | 0 ≤ 月龄 ≤ 6 |
| 7-12月龄 | 7 ≤ 月龄 ≤ 12（含整 12 月龄） |
| 12月龄以上 | 月龄 ≥ 13 |
| 展示 | 每档展示占比（%）；图例或标签含档位名称与百分比；各档占比之和为 100%（四舍五入导致 ±1% 须在界面容忍） | | 数量为 0 | 该档占比 0%，饼图仍保留图例项 |
5.5 草场类型占比
本区上下两部分（与原型一致）。
5.5.1 利用状态数量
| 指标 | 单位 | 口径 |
|---|---|---|
| 可用草场 | 个 | §2.7 |
| 使用中草场 | 个 | §2.7 |
5.5.2 退化等级分布
| 项 | 要求 |
|---|---|
| 图表 | 环形图 + 列表（或表格）并列展示，与原型一致 |
| 维度 | 未退化、轻度、中度、重度、极重度 |
| 列表列 | 至少包含：退化等级名称、数量（个）、占比（%） |
| 占比 | §2.8；列表与图表数据一致 |
| 合计 | 五档数量之和 = §5.2 草场数量（在统计范围一致的前提下） |
6. 与其他模块的关系
| 模块 | 关系 |
|---|---|
| 牧场管理 | 提供牧场数量；经营状态、逻辑删除规则影响是否计入 |
| 草场管理 | 提供草场数量、面积、退化等级、利用类型、禁牧日期；驱动可用/使用中及退化占比 |
| 牦牛资产档案管理 | 提供存栏、性别、月龄、出栏量；资产状态与变更日期为核心字段 |
| 牦牛疾病预警 | 提供预警牦牛数量；周期与去重规则见 §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.10 月末还原与仅画至当前月 |
| 年龄分档边界 | §5.4（12 月龄归入 7～12 档） |
| 草场可用/使用中含义模糊 | §2.7 与草场管理字段挂钩 |
| 退化占比分母 | §2.8 有效草场总条数 |
| 技术栈、code/msg/data | 已移除 |
| 未写数据来源 | §4.1、§6 |
| 预警/出栏/性别等待定口径 | §2.4～§2.5、§2.9、§5.3.1 已固化为唯一约定 |
10. 需求追溯
| 能力 | 章节 |
|---|---|
| 产业总览六项 | §5.2、§2.3～§2.6 |
| 公母牛数量 + 月趋势 | §5.3 |
| 年龄三档占比 | §5.4 |
| 草场可用/使用中 + 退化占比 | §5.5、§2.7、§2.8 |
| 只读看板 | §3、§5.1 |
| 模块依赖 | §4.1、§6 |
| 数据权限 | §2.9 |
| 月趋势还原 | §2.10 |