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

## 1. 接口

Base Path：`/dataModel/farmerHousehold`

| 方法 | 路径 | 权限 |
| --- | --- | --- |
| GET | `/list` | list |
| GET | `/{id}` | query |
| POST | `/` | add |
| PUT | `/` | edit |
| DELETE | `/{ids}` | remove |
| GET | `/yearOptions` `/monthOptions` `/townOptions` `/villageTree` | list |
| POST | `/importData` | import |
| GET | `/importTemplate` | import |
| GET | `/export?statYear=&statMonth=&townDeptId=` | export |

## 2. 表结构

见 `sql/biz_farmer_household.sql`：

- 主表 `biz_farmer_household`
- 唯一键 `(stat_year, stat_month, village_dept_id)`
- 派生落库：`pasture_contract_area`、`subsidy_reward_subtotal`、`subsidy_total`
  - `subsidy_total` = `subsidy_reward_subtotal` + `after_cap_floor_subsidy` + `village_supervisor_subsidy`
- 草畜失衡预警：**独立表** `biz_grass_livestock_imbalance_warning`
  - `data_source = farmer_household`，`source_key = FH-{id}`
  - `data_source = farmer_household`
  - `device_no = FH-{id}`（定位/去重）
  - `pasture_name` = 村名；`measured_value` = 存栏绵羊单位；`reference_range` = 核定载畜量
  - 失衡 upsert；平衡或删除填报记录时按 `data_source + device_no` 删除

## 3. Excel

| 项 | 说明 |
| --- | --- |
| 模板 | `templates/farmer_household_import_template.xlsx` |
| 表头识别 | 含「乡镇」「村」；`HEADER_SPAN=3` |
| 导入跳过 | 草场承包小计(col5)、补助奖励小计(col18)、合计(col21) |
| 导出 | 无合计行；填表人替换「登录用户名称」；派生列回写 |

## 4. 前端

- 页面：`ruoyi-ui/src/views/dataModel/farmerHousehold/index.vue`
- API：`ruoyi-ui/src/api/dataModel/farmerHousehold.js`
- 菜单组件：`dataModel/farmerHousehold/index`
- 村选择：级联树（县→乡镇→村），仅选叶子村；提交只传 `villageDeptId`
- 导出弹窗所属乡镇：与列表共用选项；打开时带入列表 `townDeptId`；清空则不传
- 前端技术方案：同目录 `农牧户数据填报前端技术方案.md`

## 5. 主要类

`BizFarmerHousehold*`、`FarmerHouseholdExcelParser/Exporter/Validation/DerivedSupport`