草畜平衡计算功能需求.md 12KB
草畜平衡计算 — 功能需求
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. 业务流程
flowchart TD
A[进入草畜平衡计算] --> B[选择草场名称]
B --> C[确认/补全基础参数]
C --> D[填写羊单位参数与养殖数量]
D --> E{点击计算}
E -->|校验失败| F[提示修正]
F --> C
E -->|校验通过| G[按公式计算并展示结果]
G --> H{继续操作}
H -->|调整参数再算| C
H -->|清空| I[重置输入与输出]
I --> C
- 用户选择草场，系统带出（或补全）面积、产草与利用率。
- 填写羊单位年需草量、折算系数、养殖数量。
- 点击「计算」，通过校验后展示全部结果及平衡等级。
- 可修改参数重复计算，或「清空」重新开始。
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 |