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

## 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）。

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

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

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

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

---

## 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 | 牦牛存栏总量 | 头 | **§2.3** 当前存栏头数 |
| 2 | 牦牛年出栏量 | 头 | **§2.4** |
| 3 | 预警牦牛数量 | 头 | **§2.5** |
| 4 | 牧场数量 | 个 | **§2.6** |
| 5 | 草场数量 | 个 | **§2.6** |
| 6 | 草场面积 | 亩 | **§2.6** |

**展示规则：**

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

### 5.3 牦牛存栏变动

#### 5.3.1 当前性别结构（数字）

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

| 指标 | 单位 | 口径 |
| --- | --- | --- |
| 公牛数量 | 头 | 当前存栏中性别为「公」的头数 |
| 母牛数量 | 头 | 当前存栏中性别为「母」的头数 |

**数量关系：** 公牛数量 + 母牛数量 + 未标注性别数量 = 牦牛存栏总量（**§5.2** 第 1 项）。当未标注性别数量 > 0 时，在公、母牛数量旁展示 **「未标注性别：N 头」**（N 为整数）。

#### 5.3.2 存栏趋势（折线图）

| 项 | 要求 |
| --- | --- |
| 图表类型 | 折线图 |
| 横轴 | 当前自然年 1 月～12 月（标签：1月…12月） |
| 纵轴 | 存栏数量，单位 **头** |
| 序列 | **存栏总量**一条折线 |
| 各月数值 | 按 **§2.10** 计算；仅绘制 **1 月～当前月** 有定义的月份点，**未来月份不绘制** |
| 当前月 | 以 **统计日** 作为时点代入 **§2.10**（代替月末日） |
| 图例 | 「存栏数量」（或与原型一致） |

**与总览联动：** 当前月折线点宜与 **§5.2**「牦牛存栏总量」一致（同一统计日、同一纳入范围）；已结束月份各点可小于或等于总览值。

### 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 |