# 草畜平衡计算 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 草畜平衡计算（产业数据体系 · 草场资源分析） |
| 目标 | 基于草场生产力与养殖规模，在线测算草畜承载能力、超载程度及饲草缺口，为放牧强度调控、草场利用决策提供量化依据 |
| 关联系统 | 业务后台；**草场名称**宜关联「草场管理」台账，自动带出面积、产草与利用率等基础指标 |
| 修订依据 | 同目录 `草蓄平衡计算功能需求-草稿.md`、界面原型（`Snipaste_2026-05-19_12-33-53.jpg`） |

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

> **命名说明：** 业务标准用语为「**草畜**平衡」；目录名「草蓄」若为笔误，界面与文档对外统一展示「草畜平衡计算」。

---

## 2. 术语与枚举

### 2.1 羊单位（SU）

- 草畜平衡分析中的**统一计量单位**，用于将不同畜种、不同头数折算为可比较的承载量。  
- **实际载畜量** = 养殖数量（头）× **羊单位折算系数**（每头折合多少 SU）。  
- **理论载畜量**表示当前草场饲草资源可支撑的 SU 上限。

### 2.2 输入参数含义

| 参数 | 含义 | 单位 | 来源/填写 |
| --- | --- | --- | --- |
| 草场名称 | 参与测算的草场 | — | 下拉选择有效草场台账；选定后宜带出 **§2.3** 三项 |
| 草场面积 | 测算范围面积 | **亩** | 默认来自草场台账，可允许为本次测算调整（评审确认是否只读） |
| 亩产草量 | 单位面积可产饲草量 | **kg/亩** | 默认来自草场台账 |
| 利用率 | 产草量中可被牲畜利用的比例 | **0～1**（界面可用 % 展示，计算时换算为小数） | 默认来自草场台账 |
| 羊单位年需草量 | 每 SU 全年饲草需求量 | **kg/SU** | 用户填写；宜提供县级参考默认值 |
| 羊单位折算系数 | 每头牲畜折合 SU 数 | **SU/头** | 用户填写；不同畜种可预设模板（评审） |
| 养殖数量 | 当前（或计划）存栏头数 | **头** | 用户填写 |

### 2.3 与草场台账的联动

- 用户从下拉框选择**未删除**的草场记录后，系统宜将台账中的**面积、亩产草量、利用率**填入基础参数区，减少重复录入。  
- 若台账某项为空，对应输入框留空，由用户补全后方可计算。  
- 本模块**不替代**草场管理维护职责；台账变更后，已打开的计算页不自动刷新，需重新选择草场或手动改参。

### 2.4 输出指标含义

| 指标 | 含义 | 单位 |
| --- | --- | --- |
| 可利用饲草量 | 该草场在测算假设下全年可供给牲畜的饲草总量 | **kg** |
| 理论载畜量 | 饲草资源可承载的羊单位上限 | **SU** |
| 实际载畜量 | 当前养殖规模折算的羊单位 | **SU** |
| 草畜平衡指数 | 实际载畜量相对理论载畜量的比值（>1 表示超载倾向） | 无量纲 |
| 超载率 | 相对理论承载能力的超出比例 | **%** |
| 草畜平衡等级 | 按超载率划分的定性结论 | 枚举，见 **§2.5** |
| 超载羊单位 | 超出理论承载的 SU 数；未超载时为 0 或负值（表示余量，展示规则见 **§5.4**） | **SU** |
| 全年需草量 | 维持当前实际载畜量所需的饲草总量 | **kg** |
| 饲草缺口 | 需草量超出可利用饲草量的部分；有余量时为 0 或负值 | **kg** |
| 理论适宜放牧 | 饲草资源可支撑的牲畜头数（按当前折算系数反算） | **头** |
| 实际超载数量 | 超出适宜放牧规模的头数；未超载时为 **0** | **头** |

### 2.5 草畜平衡等级

按**超载率**（**§5.3** 公式 5）划分；区间**左开右闭**或边界归属如下表（与草稿、原型红字公式一致并消除 0～5% 空白带）：

| 超载率 R | 等级 |
| --- | --- |
| R ≤ 0% | **未超载** |
| 0% < R ≤ 15% | **基本平衡** |
| 15% < R ≤ 50% | **超载** |
| R > 50% | **严重超载** |

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 基础参数录入 | 草场选择 + 生产力与养殖参数，见 **§5.1** |
| 一键计算 | 校验通过后按 **§5.3** 公式输出全部结果指标 |
| 结果展示 | 只读结果区，单位与原型一致 |
| 清空 | 重置输入与输出 |
| 公式说明 | 页面展示计算口径（可与原型底部公式列表一致） |

**本期不实现：**

- 测算记录的保存、历史列表、导出 PDF/Excel（若需留痕另出需求）  
- 多草场汇总、区域统计、时间序列对比  
- 与畜群台账、草场使用记录的自动取数（养殖数量、面积等仍手工或通过草场带出）  
- 自动给出改良方案或轮牧计划（仅输出量化指标）  

---

## 4. 业务流程

```mermaid
flowchart TD
    A[进入草畜平衡计算] --> B[选择草场名称]
    B --> C[确认/补全基础参数]
    C --> D[填写羊单位参数与养殖数量]
    D --> E{点击计算}
    E -->|校验失败| F[提示修正]
    F --> C
    E -->|校验通过| G[按公式计算并展示结果]
    G --> H{继续操作}
    H -->|调整参数再算| C
    H -->|清空| I[重置输入与输出]
    I --> C
```

1. 用户选择草场，系统带出（或补全）面积、产草与利用率。  
2. 填写羊单位年需草量、折算系数、养殖数量。  
3. 点击「**计算**」，通过校验后展示全部结果及平衡等级。  
4. 可修改参数重复计算，或「**清空**」重新开始。

---

## 5. 详细功能需求

### 5.1 基础参数区

**布局（与原型一致）**

- 左侧或上部：**基础参数**（草场名称、面积、亩产草量、利用率、羊单位年需草量、折算系数、养殖数量）。  
- 操作按钮：**计算**、**清空**。

**校验规则（计算前）**

| 参数 | 规则 |
| --- | --- |
| 草场名称 | **必选** |
| 草场面积 | **必填**；> 0 |
| 亩产草量 | **必填**；≥ 0（=0 时理论载畜量为 0，见 **§5.5**） |
| 利用率 | **必填**；**0～1**（若界面为 %，须在计算前换算） |
| 羊单位年需草量 | **必填**；> 0（否则无法计算理论载畜量） |
| 羊单位折算系数 | **必填**；> 0 |
| 养殖数量 | **必填**；≥ 0 整数 |

未通过校验时**不更新**结果区（或清空结果区），并给出可理解的字段级提示。

### 5.2 草场名称下拉

- 数据源为**草场管理**中有效（未删除）草场；展示名称，支持关键字过滤（若原型有搜索框则实现，否则列表选择）。  
- 切换草场时，宜刷新带出的面积、亩产草量、利用率；**清空**已展示的计算结果，避免旧结果误导。

### 5.3 计算公式（业务口径）

以下公式中，面积单位为**亩**，饲草量为 **kg**，载畜量为 **SU**，头数为**头**。除法运算在分母为 0 时按 **§5.5** 处理。

| 序号 | 指标 | 公式 |
| --- | --- | --- |
| 1 | 可利用饲草量 | 草场面积 × 亩产草量 × 利用率 |
| 2 | 理论载畜量 | 可利用饲草量 ÷ 羊单位年需草量 |
| 3 | 实际载畜量 | 养殖数量 × 羊单位折算系数 |
| 4 | 草畜平衡指数 | 实际载畜量 ÷ 理论载畜量 |
| 5 | 超载率 | （草畜平衡指数 − 1）× 100% |
| 6 | 草畜平衡等级 | 按超载率查 **§2.5** |
| 7 | 超载羊单位 | 实际载畜量 − 理论载畜量 |
| 8 | 全年需草量 | 实际载畜量 × 羊单位年需草量 |
| 9 | 饲草缺口 | 全年需草量 − 可利用饲草量 |
| 10 | 理论适宜放牧 | 理论载畜量 ÷ 羊单位折算系数 |
| 11 | 实际超载数量 | 若 养殖数量 > 理论适宜放牧，则为 养殖数量 − 理论适宜放牧；否则为 **0** |

> **修订说明：** 草稿第 13 条「实际超载数量 = 理论适宜放牧 − 养殖数量」与业务含义相反，已按 **§5.3 序号 11** 更正。

**指数与率的关系**

- 草畜平衡指数 = 1 时，超载率为 0%，等级为**未超载**。  
- 指数 < 1 时，超载率为负，等级一般为**未超载**；超载羊单位、饲草缺口可为负值，表示资源有余（展示见 **§5.4**）。

### 5.4 计算结果区

**展示列（与原型一致）**

可利用饲草量、理论载畜量、实际载畜量、草畜平衡指数、超载率、草畜平衡等级、超载羊单位、全年需草量、饲草缺口、理论适宜放牧、实际超载数量。

**展示规则**

| 项 | 规则 |
| --- | --- |
| 触发时机 | 仅在校验通过并点击「计算」后刷新；未计算前结果区为空或占位「—」 |
| 数值精度 | 饲草量、载畜量、指数等宜保留 **2 位小数**；头数为**整数**；超载率以 **%** 展示并保留 2 位小数 |
| 超载羊单位 | 未超载（≤0）时，可展示负值并标注为「余量」或统一显示为 0（**评审选定一种**，全系统一致） |
| 饲草缺口 | 有余量时可为负或显示 0，与超载羊单位策略一致 |
| 草畜平衡等级 | 文本展示 **§2.5** 四档之一；宜配颜色或图标区分严重超载（评审） |
| 只读 | 结果区不可编辑 |

### 5.5 边界与异常情形

| 情形 | 处理 |
| --- | --- |
| 羊单位年需草量 = 0 | 禁止计算，提示须大于 0 |
| 羊单位折算系数 = 0 | 禁止计算，提示须大于 0 |
| 理论载畜量 = 0（如亩产草量为 0） | 若养殖数量 > 0：指数、超载率按业务约定视为极高超载或单独提示「无饲草供给」（**评审确认**）；若养殖数量 = 0：指数按 0 或「—」展示 |
| 养殖数量 = 0 | 实际载畜量、全年需草量为 0；指数 = 0；超载率按公式为 −100%；等级为**未超载**；实际超载数量为 0 |
| 计算过程浮点误差 | 等级判定前宜对超载率做合理舍入（如保留 4 位小数再比较区间） |

### 5.6 清空

- 点击「**清空**」：基础参数恢复初始状态（草场名称、面积等全部清空，或仅清空养殖相关项——**评审确认**；默认**全部清空**）。  
- 结果区同步清空。  
- 不清空草场台账数据本身。

### 5.7 公式说明区（可选）

- 页面底部或折叠区展示 **§5.3** 公式列表及 **§2.5** 等级表，与原型红字说明一致，便于县级用户理解口径。  
- 文案随需求变更同步维护，**不作为**计算逻辑的第二套实现（计算以 **§5.3** 为准）。

---

## 6. 权限矩阵

| 操作 | 条件 |
| --- | --- |
| 进入模块、查看公式说明 | 具备本模块菜单权限 |
| 执行计算、清空 | 同上（本期不区分只读/操作角色；若需限制「仅查看公式」另定） |
| 维护草场台账 | 不在本模块；归属「草场管理」 |

---

## 7. 提示与错误约定

采用项目统一提示方式；**不约定** HTTP 字段。宜区分：

- 必填项未填、数值越界（面积≤0、利用率不在 0～1 等）；  
- 分母为 0 导致无法计算；  
- 未选择草场；  
- 计算成功（可选弱提示，非必须）。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 易用性 | 参数分组清晰；结果与输入分区；关键指标单位标注 |
| 性能 | 纯前端或单次服务端计算，响应宜 < 1 秒 |
| 可配置 | 羊单位年需草量、折算系数默认值可后台配置（若实现） |
| 审计 | 若后续增加「保存测算记录」，须记录操作人、时间、输入快照 |
| 双语 | 界面 i18n（汉语 + 藏文） |

---

## 9. 相对草稿的修订说明

| 草稿问题 | 处理 |
| --- | --- |
| 含技术栈、code/msg/data | 已移除 |
| 等级区间 0～5% 空白 | 统一为 **§2.5** 四档连续区间 |
| 实际超载数量公式反向 | 更正为 **§5.3 序号 11** |
| 未描述草场联动、校验、清空范围 | 补充 **§2.3、§5.1、§5.2、§5.6** |
| 未定义边界情形 | 补充 **§5.5、§5.4** 展示规则 |
| 指标命名「牧场草畜平衡指数」 | 统一为「草畜平衡指数」 |

---

## 10. 需求追溯

| 能力 | 章节 |
| --- | --- |
| 参数输入与草场联动 | §5.1、§5.2 |
| 计算公式 | §5.3 |
| 等级判定 | §2.5、§5.3 序号 6 |
| 结果展示 | §5.4 |
| 计算/清空 | §4、§5.6 |
| 边界处理 | §5.5 |