草蓄平衡计算技术方案.md 8.6KB
草畜平衡计算 — 技术方案
依据：同目录
草畜平衡计算功能需求.md。本期为无状态测算服务：接收参数、服务端按公式计算并返回结果；不落库测算记录。
1. 技术架构
| 项 | 说明 |
|---|---|
| 后端 | RuoYi v3.9.2（springboot2 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| 数据库 | MySQL 5.7.39，InnoDB，utf8mb4 |
| 前端 | 若依 Vue2（本方案不展开） |
| 依赖主数据 | biz_grassland（草场管理） |
分层：Controller → GrassLivestockBalanceService（GrassLivestockBalanceValidation 校验 + GrassLivestockBalanceCalculator 纯计算）→ 可选读 BizGrasslandMapper 校验草场有效。
代码位置（建议）：baqing-admin → com.ruoyi.web.modules.industryservice（GrassLivestockBalanceController、support/GrassLivestockBalance*）。
业务摘要
| 场景 | 行为 |
|---|---|
| 草场下拉/带出 | 复用草场管理接口或本模块只读查询；del_flag='0' |
| 计算 | POST 入参 → 校验 → 计算 11 项指标 → 返回 DTO；不写库 |
| 清空 | 前端重置表单；无后端接口 |
| 默认值 | 羊单位年需草量、折算系数可从 sys_config 读取（可选） |
2. 数据库设计
2.1 本期：无新增业务表
功能需求 §3 明确本期不保存测算历史；计算过程无持久化，仅依赖已有草场台账。
| 依赖表 | 用途 |
|---|---|
biz_grassland |
草场下拉、选定后带出 area_mu、grass_yield_per_mu、utilization_rate、grassland_name |
2.2 关联表字段（biz_grassland 摘录）
| 字段 | 类型 | 测算用途 |
|---|---|---|
id |
bigint(20) |
入参 grasslandId |
grassland_name |
varchar(32) |
展示 |
area_mu |
decimal(12,2) |
草场面积（亩） |
grass_yield_per_mu |
decimal(12,2) |
亩产草量（kg/亩） |
utilization_rate |
decimal(5,4) |
利用率 0～1 |
del_flag |
char(1) |
仅 0 可选 |
2.3 系统参数（可选，非必须建表）
| 配置键（示例） | 说明 | 默认值（示例） |
|---|---|---|
grass.balance.sheepUnitAnnualForageKg |
羊单位年需草量 kg/SU | 按县级规范配置 |
grass.balance.sheepUnitConvertCoeff |
羊单位折算系数 SU/头 | 如牦牛折算系数 |
存于若依 sys_config，由 GET .../defaults 下发给前端初始填充。
2.4 后续扩展（本期不建）
若需测算留痕，可增表 biz_grass_livestock_balance_record（输入快照 + 结果 JSON + 操作人/时间）；本期不实现。
3. 接口设计
统一响应：AjaxResult（code / msg / data）。
权限标识：dataModel:grassLivestockBalance:query（进入模块、计算、读默认值）
Base Path：/dataModel/grassLivestockBalance
| # | 说明 | Method | URI | 权限 | 要点 |
|---|---|---|---|---|---|
| 3.1 | 执行计算 | POST | /dataModel/grassLivestockBalance/calculate |
query |
Body 3.1.1；返回 3.1.2 |
| 3.2 | 羊单位默认参数 | GET | /dataModel/grassLivestockBalance/defaults |
query |
读 sys_config，可选 |
| 3.3 | 草场台账（复用） | GET | /dataModel/grassland/list |
草场 list 权限 |
下拉；keyword 模糊名称 |
| 3.4 | 草场参数带出（复用） | GET | /dataModel/grassland/{id} |
草场 query 权限 |
选定草场后取面积、产草、利用率 |
本期不提供测算记录的增删改查接口；清空为前端行为。
3.1.1 计算请求 Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
grasslandId |
long | Y | 关联 biz_grassland.id，须 del_flag='0' |
areaMu |
decimal | Y | 草场面积（亩），> 0 |
grassYieldPerMu |
decimal | Y | 亩产草量（kg/亩），≥ 0 |
utilizationRate |
decimal | Y | 利用率 0～1（前端传 % 时先换算） |
sheepUnitAnnualForageKg |
decimal | Y | 羊单位年需草量（kg/SU），> 0 |
sheepUnitConvertCoeff |
decimal | Y | 折算系数（SU/头），> 0 |
breedingHeadCount |
int | Y | 养殖数量（头），≥ 0 |
面积、产草、利用率允许与台账不一致（用户调整后测算）；
grasslandId用于校验草场有效及回显名称。
3.1.2 计算响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
grasslandId |
long | 回显 |
grasslandName |
string | 来自台账 |
availableForageKg |
decimal | 可利用饲草量（kg） |
theoreticalCarryingSu |
decimal | 理论载畜量（SU） |
actualCarryingSu |
decimal | 实际载畜量（SU） |
balanceIndex |
decimal | 草畜平衡指数 |
overloadRate |
decimal | 超载率（%，已×100） |
balanceLevel |
int | 等级码 §3.2 |
balanceLevelName |
string | 等级中文 |
overloadSu |
decimal | 超载羊单位（SU）；未超载可为负 |
annualForageDemandKg |
decimal | 全年需草量（kg） |
forageGapKg |
decimal | 饲草缺口（kg） |
theoreticalSuitableHeads |
decimal | 理论适宜放牧（头） |
actualOverloadHeads |
int | 实际超载数量（头），未超载为 0 |
warning |
string | 边界提示（如理论载畜量为 0），可选 |
数值：金额类指标保留 2 位小数；actualOverloadHeads 为整数；overloadRate 保留 2 位小数。
3.2 等级码 balance_level
| 值 | balanceLevelName |
超载率 R（比较前保留 4 位小数） |
|---|---|---|
1 |
未超载 | R ≤ 0 |
2 |
基本平衡 | 0 < R ≤ 0.15 |
3 |
超载 | 0.15 < R ≤ 0.50 |
4 |
严重超载 | R > 0.50 |
其中 R = balanceIndex - 1（与需求「超载率 = (指数−1)×100%」一致，判定用未乘 100 的比率）。
3.3 服务端计算公式（与需求 §5.3 一致）
availableForageKg = areaMu × grassYieldPerMu × utilizationRate
theoreticalCarryingSu = availableForageKg / sheepUnitAnnualForageKg
actualCarryingSu = breedingHeadCount × sheepUnitConvertCoeff
balanceIndex = actualCarryingSu / theoreticalCarryingSu // theoretical=0 见 §3.4
overloadRate = (balanceIndex - 1) × 100
overloadSu = actualCarryingSu - theoreticalCarryingSu
annualForageDemandKg = actualCarryingSu × sheepUnitAnnualForageKg
forageGapKg = annualForageDemandKg - availableForageKg
theoreticalSuitableHeads = theoreticalCarryingSu / sheepUnitConvertCoeff
actualOverloadHeads = max(0, breedingHeadCount - floor(theoreticalSuitableHeads)) // 头数取整策略见 §3.4
balanceLevel = resolveLevel(overloadRate/100)
3.4 边界实现约定
| 情形 | 实现 |
|---|---|
sheepUnitAnnualForageKg 或 sheepUnitConvertCoeff ≤ 0 |
校验失败，ServiceException |
theoreticalCarryingSu = 0 且 breedingHeadCount > 0 |
balanceIndex、overloadRate 置 null；balanceLevel=4；warning="无饲草供给" |
theoreticalCarryingSu = 0 且 breedingHeadCount = 0 |
balanceIndex=0；等级 未超载 |
breedingHeadCount = 0 |
实际载畜量、全年需草量为 0；超载率为 −100%；等级 未超载 |
theoreticalSuitableHeads 取整 |
默认 四舍五入保留 2 位小数参与比较；actualOverloadHeads 用 breedingHeadCount - theoreticalSuitableHeads 向上取整为整数且 <0 则 0 |
| 超载羊单位/饲草缺口为负 | 原值返回（保留 2 位小数），前端可标注「余量」 |
3.5 校验（GrassLivestockBalanceValidation）
与需求 §5.1 一致；grasslandId 须 selectBizGrasslandById 存在且 del_flag='0'。
4. 菜单与权限（示例）
| 类型 | 名称 | 权限标识 |
|---|---|---|
| 菜单 | 草畜平衡计算 | dataModel:grassLivestockBalance:query |
| 按钮 | 计算 | dataModel:grassLivestockBalance:query |
组件路径：dataModel/grassLivestockBalance/index（产业数据体系目录下）。
草场下拉另需：dataModel:grassland:list、dataModel:grassland:query。
5. 交付清单
-
GrassLivestockBalanceValidation、GrassLivestockBalanceCalculator、GrassLivestockBalanceRules -
GrassLivestockBalanceController、IGrassLivestockBalanceService - 单元测试：公式、等级区间、边界（理论载畜量 0、存栏 0）
- MockMvc：
POST /calculate成功/校验失败 - （可选）
sys_config初始化 SQL 与GET /defaults
6. 修订记录
| 版本 | 说明 |
|---|---|
| 1.0 | 初稿：无新表；POST 计算 + 复用草场接口；等级码 1～4；公式与功能需求 §5.3 对齐 |