# 养殖产业数据 — 功能需求

## 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 数据汇聚关系

```mermaid
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 用户使用路径

```mermaid
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 | （既有） | 总览存栏/出栏/农牧户改填报合计 |