# 家庭牧场数据填报 — 技术方案

## 1. 接口

Base Path：`/dataModel/familyRanch`

| 方法 | 路径 | 权限 |
| --- | --- | --- |
| 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_family_ranch.sql`：

- `biz_family_ranch`：业务主表；唯一键 `(stat_year, stat_month, village_dept_id, enterprise_name)`
- 草畜失衡预警：**独立表** `biz_grass_livestock_imbalance_warning`
  - `data_source = family_ranch`，`source_key = FR-{id}`
  - `data_source = family_ranch`
  - `device_no = FR-{ranchId}`（定位/去重）
  - `pasture_name` = 企业名称；`measured_value` = 存栏绵羊单位；`reference_range` = 核定载畜量
  - 失衡 upsert；平衡或删除牧场记录时按 `data_source + device_no` 删除

## 3. Excel

| 项 | 说明 |
| --- | --- |
| 模板 | `templates/family_ranch_import_template.xlsx` |
| 表头识别 | 含「乡镇名称」「村居名称」；`HEADER_SPAN=3` |
| 列序 | 乡镇在前、村在后；企业名称第 4 列（0-based index 3） |
| 导入跳过 | 存栏小计、草场面积小计、是否草畜平衡、利润（由系统计算后导出回写） |
| 导出 | 无合计行；填表人替换模板「登录用户名称」 |

## 4. 前端

- 页面：`ruoyi-ui/src/views/dataModel/familyRanch/index.vue`
- API：`ruoyi-ui/src/api/dataModel/familyRanch.js`
- 菜单组件：`dataModel/familyRanch/index`
- 村选择：级联树（县→乡镇→村），仅选叶子村
- **导出弹窗所属乡镇**：
  - 与列表共用 `townOptions`、文案「所属乡镇」、占位「请选择」
  - 打开导出时带入列表当前 `queryParams.townDeptId`；清空则不传 `townDeptId`（导出全部乡镇）
  - 请求：`GET /export?statYear=&statMonth=&townDeptId=`（`townDeptId` 可选）

## 5. 主要类

`BizFamilyRanch*`、`FamilyRanchExcelParser/Exporter/Validation/DerivedSupport`