# 农牧户数据填报 — 前端技术方案

> 依据：同目录功能需求、技术方案；交互对齐畜牧产品产量等村×年月填报；字段 **小驼峰**。

---

## 1. 页面与路由

| 项 | 说明 |
| --- | --- |
| **Vue 路径** | `ruoyi-ui/src/views/dataModel/farmerHousehold/index.vue` |
| **组件名** | `FarmerHousehold` |
| **菜单配置** | 组件路径：`dataModel/farmerHousehold/index` |
| **权限前缀** | `dataModel:farmerHousehold:list\|query\|add\|edit\|remove\|import\|export` |

---

## 2. API 模块

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

CRUD、`yearOptions` / `monthOptions` / `townOptions` / `villageTree`、导入 `importData`、模板 `importTemplate`、导出 `export`（可选 `townDeptId`）与同类村级填报模块同构；模板/导出均为 **GET + blob**。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `listFarmerHousehold` | GET `/list` | 分页；筛选年、月、乡镇 |
| `getFarmerHousehold` | GET `/{id}` | 详情（含派生） |
| `addFarmerHousehold` | POST `/` | 新增 |
| `updateFarmerHousehold` | PUT `/` | 修改 |
| `delFarmerHousehold` | DELETE `/{ids}` | 删除 |
| `listFarmerHouseholdYearOptions` | GET `/yearOptions` | 年份下拉 |
| `listFarmerHouseholdMonthOptions` | GET `/monthOptions` | 月份下拉 |
| `listFarmerHouseholdTownOptions` | GET `/townOptions` | 乡镇下拉 |
| `listFarmerHouseholdVillageTree` | GET `/villageTree` | 县→乡镇→村树 |
| `importFarmerHousehold` | POST `/importData` | FormData：`file` + `statYear` + `statMonth` |
| `downloadFarmerHouseholdTemplate` | GET `/importTemplate` | 模板 blob |
| `exportFarmerHousehold` | GET `/export` | 参数：`statYear`、`statMonth`、可选 `townDeptId` |

---

## 3. 页面结构

1. **筛选**：年、月、乡镇（与需求一致，无村筛选）。  
2. **列表**：年、月、乡镇、村、农牧户数、农牧人数、草场承包总面积（`pastureContractArea`）、操作。  
3. **新增/编辑**：选村（可搜索，标签「乡镇 / 村」）；新增默认本年本月；派生字段只读展示。  
4. **详情**：与表单同分区标题；含派生只读值 + 乡镇；数值用 `formatWithUnit` 带单位。  
5. **导入**：选年月 → upsert 摘要（insert/update/fail）；任一行失败整批不写（后端）。  
6. **导出**：选年月；所属乡镇与列表共用选项，打开时带入列表当前乡镇，清空=全部。

### 表单 / 查看分区

| 分区 | 内容 |
| --- | --- |
| 基本信息 | 年月、村（查看含乡镇）；农牧户数、农牧人数 |
| 草畜平衡情况 | 禁牧面积、草畜平衡面积；只读草场承包总面积（=禁牧+草畜平衡）；核定载畜量、年底存栏绵羊单位 |
| 封顶保底情况 | 纯牧户 / 无畜户 / 绝户 / 超载 / 需封顶 / 需保底（是/否） |
| 本年受助情况 | 禁牧补助、草畜平衡奖励；只读补助奖励总资金（=二者之和）；封顶保底后补助、村级监督员补助；只读补助合计金额（=封顶保底后+村级监督员）；备注 |

---

## 4. 业务规则

| 规则 | 实现 |
| --- | --- |
| 唯一键 | 年 + 月 + 村（前端提交只传 `villageDeptId`；乡镇由后端反推） |
| 必填 | 年、月、村 |
| 前端只读派生 | 草场承包总面积、补助奖励总资金、补助合计金额（表单禁用预览；详情同公式） |
| 是/否 | 六项封顶保底字段单选「是」「否」 |
| 不可未来月 | 表单 / 导入 / 导出校验 |
| 草畜失衡预警 | 后端写入 `biz_yak_disease_warning`（type=6）；前端不单独处理 |

### 派生预览公式

- 草场承包总面积 = 禁牧面积 + 草畜平衡面积  
- 补助奖励总资金 = 禁牧补助 + 草畜平衡奖励  
- 补助合计金额（前端展示）= 封顶保底后享受补助奖励总资金 + 村级草原监督员补助  

> 说明：后端落库的 `subsidyTotal` 另含「补助奖励总资金」三项合计；前端「补助合计金额」按本次产品口径仅展示后两项之和。

---

## 5. 国际化

`dataModel.farmerHousehold`（`lang/zh|bo/dataModel.js`）；页面 `dmNs = 'farmerHousehold'`，复用 `dataModelLocaleMixin`（`dmT` / `dmCommon` / `formatWithUnit`）。查看表单使用 `dm-view-form` 高亮。

---

## 6. 联调说明

1. 执行 `sql/biz_farmer_household.sql`。  
2. 菜单组件 `dataModel/farmerHousehold/index`，权限见 §1。  
3. 验证：新增默认年月、表单无派生列、详情有派生、导出乡镇带入列表筛选、草畜失衡写入疾病预警（后端）。

---

## 7. 文件清单

| 类型 | 路径 |
| --- | --- |
| 页面 | `ruoyi-ui/src/views/dataModel/farmerHousehold/index.vue` |
| API | `ruoyi-ui/src/api/dataModel/farmerHousehold.js` |
| i18n | `lang/zh/dataModel.js`、`lang/bo/dataModel.js` → `farmerHousehold` |
| 前端技术方案 | 本文档 |

---

## 8. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：村×年月；CRUD + upsert 导入 + 导出乡镇与列表联动；表单不展示派生、详情展示；分区对齐其它产业填报页 |