# 草场平衡计算 — 前端技术方案

> 依据：`doc/产业数据模型及体系/草蓄平衡计算/草畜平衡计算功能需求.md`、`草蓄平衡计算技术方案.md`；界面布局对齐原型 `Snipaste_2026-05-19_12-33-53.jpg`；字段 **小驼峰**。

---

## 1. 页面与路由

| 项 | 说明 |
| --- | --- |
| **Vue 路径** | `ruoyi-ui/src/views/dataModel/grassLivestockBalance/index.vue` |
| **组件名** | `GrassLivestockBalance` |
| **菜单配置** | 组件路径：`dataModel/grassLivestockBalance/index`（手工配置，不提供 SQL） |
| **权限前缀** | `dataModel:grassLivestockBalance:query` |

草场下拉另需：`dataModel:grassland:list`、`dataModel:grassland:query`。

---

## 2. API 模块

| 项 | 说明 |
| --- | --- |
| **文件** | `ruoyi-ui/src/api/dataModel/grassLivestockBalance.js` |
| **Base** | `/dataModel/grassLivestockBalance` |

| 方法 | HTTP | 说明 |
| --- | --- | --- |
| `calculateGrassLivestockBalance` | POST | `/calculate`，Body 见技术方案 §3.1.1 |
| `getGrassLivestockBalanceDefaults` | GET | `/defaults`，羊单位默认参数 |

**草场主数据**：复用 `listGrassland`（`keyword` 模糊）、`getGrassland`（选定后带出面积、产草、利用率）。

---

## 3. 页面结构

1. **基础参数区**（`el-card`）：草场 remote 下拉；面积、亩产草量、利用率（0～1）；羊单位年需草量、折算系数、养殖数量；**计算**、**清空**。  
2. **计算结果区**（`el-card`）：11 项只读指标，按原型三行展示；等级字段按 `balanceLevel` 配色；`warning` 时 `el-alert`。  
3. **公式说明区**（`el-collapse`）：11 条公式 + 四档等级表（文案 i18n，不参与计算）。

---

## 4. 业务规则（前端）

| 规则 | 实现 |
| --- | --- |
| 草场联动 | `getGrassland(id)` 填充 `areaMu`、`grassYieldPerMu`、`utilizationRate`；切换草场清空结果 |
| 默认羊单位参数 | `created` 调 `GET /defaults` 填充；清空后恢复默认 |
| 利用率 | 与草场管理一致，传 **0～1** 小数，非百分比 |
| 校验 | 与技术方案 §3.5 / 功能需求 §5.1 一致；失败不展示结果 |
| 计算 | 校验通过后 `POST /calculate`，展示 `data` 各字段 |
| 超载羊单位 / 饲草缺口 | 负值展示绝对值并附「（余量）」 |
| 数值格式 | 金额类 2 位小数；超载率加 `%`；超载头数为整数 |
| 清空 | 表单、结果、草场选项一并重置 |

---

## 5. 国际化

| 项 | 说明 |
| --- | --- |
| **语言包** | `dataModel.grassLivestockBalance`（`lang/zh/dataModel.js`、`lang/bo/dataModel.js`） |
| **Mixin** | `dataModelLocaleMixin`，`dmNs = 'grassLivestockBalance'` |
| **单位** | 亩、kg/亩、0～1 复用 `dataModel.grassland` |

---

## 6. 联调说明

1. 部署 `GrassLivestockBalanceController` 及草场台账 `biz_grassland`。  
2. 菜单权限：`dataModel:grassLivestockBalance:query`。  
3. 验证：草场带出、默认值、计算 11 项、等级颜色、边界 `warning`、清空与双语切换。

---

## 7. 文件清单

| 类型 | 路径 |
| --- | --- |
| 页面 | `ruoyi-ui/src/views/dataModel/grassLivestockBalance/index.vue` |
| API | `ruoyi-ui/src/api/dataModel/grassLivestockBalance.js` |
| i18n | `ruoyi-ui/src/lang/zh/dataModel.js`、`lang/bo/dataModel.js`（`grassLivestockBalance` 段） |

---

## 8. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：三卡片布局；POST 计算 + GET 默认值；复用草场接口；公式折叠区 |