# 家庭牧场数据填报 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 家庭牧场数据填报 |
| 目标 | 按**村 × 所属年月 × 企业名称**登记家庭牧场；导入 upsert；导出按模板填充 |
| 关联系统 | 业务后台；`sys_dept`（乡镇、村） |
| 修订依据 | 交接表 `家庭牧场数据填报.xlsx`；运行模板 `family_ranch_import_template.xlsx` |

---

## 2. 填报粒度

- 一条记录：某一自然年、某一自然月、某一行政村下某一家庭牧场（企业）快照。
- 保存时由所选村反推所属乡镇。
- 唯一键：所属年份 + 所属月份 + 所属村 + 企业名称。
- 导入：存在则更新、不存在则插入（非增幅累加，也不按年月先删后插）。
- 派生（保存时计算）：
  - 年底牲畜存栏小计 = 牛年底存栏 + 羊年底存栏
  - 草场面积小计 = 草畜平衡面积 + 流转经营草地面积
  - 利润 = 收入 − 支出
  - 是否草畜平衡户：核定年末草畜平衡载畜量 ≥ 年底牲畜存栏（绵羊单位）则为「是」，否则「否」
- 草畜失衡预警（**不依赖**「草畜平衡计算」模块）：
  - 导入 / 新增 / 修改保存后：若该年该月某家庭牧场 **核定年末草畜平衡载畜量 < 年底牲畜存栏（绵羊单位）** → 写入/更新 `biz_grass_livestock_imbalance_warning`（`data_source=family_ranch`，`source_key=FR-{id}`）
  - 后续修改后 **核定载畜量 ≥ 年底存栏**（或字段不全无法判定）→ 对应预警记录删除
  - 删除填报记录时同步清除预警

---

## 3. 功能范围

| 能力 | 说明 |
| --- | --- |
| 分页列表 | 筛选：年、月、乡镇、企业名称；列：年、月、乡镇、村、企业、法人、类型、注册资本、成立时间、牛存栏、牛出栏、草场面积 |
| 新增 / 修改 | 选村；新增默认本年本月；企业类型默认个体工商户；销售渠道默认其他 |
| 详情 | 全部字段含派生 |
| 删除 | 物理删除（级联清预警） |
| Excel 导入 | 表头约 1～5 行（多级）；另选年月；按唯一键 upsert |
| Excel 导出 | 另选年月；**所属乡镇与列表一致**（同选项；打开时带入列表当前乡镇，可清空表示全部）；填表人=登录用户；无合计行 |

---

## 4. 权限

`dataModel:familyRanch:list|query|add|edit|remove|import|export`

---

## 5. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 首版：CRUD + upsert 导入 + 导出 + 草畜失衡写入疾病预警表 |
| 1.1 | 导出所属乡镇与列表筛选保持一致（打开带入、可清空） |
| 1.2 | 预警改写独立表；规则：载畜量<存栏触发，≥则预警消失；不走草畜平衡计算 |