畜牧产品产量登记

doc/产业数据模型及服务/家庭牧场数据填报/家庭牧场数据填报功能需求.md

@@ -0,0 +1,53 @@
+# 家庭牧场数据填报 — 功能需求
+
+## 1. 文档说明
+
+| 项 | 说明 |
+| --- | --- |
+| 模块名称 | 家庭牧场数据填报 |
+| 目标 | 按**村 × 所属年月 × 企业名称**登记家庭牧场；导入 upsert；导出按模板填充 |
+| 关联系统 | 业务后台；`sys_dept`（乡镇、村） |
+| 修订依据 | 交接表 `家庭牧场数据填报.xlsx`；运行模板 `family_ranch_import_template.xlsx` |
+
+---
+
+## 2. 填报粒度
+
+- 一条记录：某一自然年、某一自然月、某一行政村下某一家庭牧场（企业）快照。
+- 保存时由所选村反推所属乡镇。
+- 唯一键：所属年份 + 所属月份 + 所属村 + 企业名称。
+- 导入：存在则更新、不存在则插入（非增幅累加，也不按年月先删后插）。
+- 派生（保存时计算）：
+  - 年底牲畜存栏小计 = 牛年底存栏 + 羊年底存栏
+  - 草场面积小计 = 草畜平衡面积 + 流转经营草地面积
+  - 利润 = 收入 − 支出
+  - 是否草畜平衡户：核定年末草畜平衡载畜量 ≥ 年底牲畜存栏（绵羊单位）则为「是」，否则「否」
+- 草畜失衡预警：载畜量 < 存栏绵羊单位时写入 **`biz_yak_disease_warning`**（`warning_type=6`，`data_source=family_ranch`，`device_no=FR-{ranchId}`）；恢复平衡或删除记录时清除对应预警。不另建预警表。
+
+---
+
+## 3. 功能范围
+
+| 能力 | 说明 |
+| --- | --- |
+| 分页列表 | 筛选：年、月、乡镇、企业名称；列：年、月、乡镇、村、企业、法人、类型、注册资本、成立时间、牛存栏、牛出栏、草场面积 |
+| 新增 / 修改 | 选村；新增默认本年本月；企业类型默认个体工商户；销售渠道默认其他 |
+| 详情 | 全部字段含派生 |
+| 删除 | 物理删除（级联清预警） |
+| Excel 导入 | 表头约 1～5 行（多级）；另选年月；按唯一键 upsert |
+| Excel 导出 | 另选年月；**所属乡镇与列表一致**（同选项；打开时带入列表当前乡镇，可清空表示全部）；填表人=登录用户；无合计行 |
+
+---
+
+## 4. 权限
+
+`dataModel:familyRanch:list|query|add|edit|remove|import|export`
+
+---
+
+## 5. 修订记录
+
+| 版本 | 说明 |
+| --- | --- |
+| 1.0 | 首版：CRUD + upsert 导入 + 导出 + 草畜失衡写入疾病预警表 |
+| 1.1 | 导出所属乡镇与列表筛选保持一致（打开带入、可清空） |

doc/产业数据模型及服务/家庭牧场数据填报/家庭牧场数据填报技术方案.md

@@ -0,0 +1,54 @@
+# 家庭牧场数据填报 — 技术方案
+
+## 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_yak_disease_warning`
+  - `warning_type = 6`（草畜失衡）
+  - `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`

doc/产业数据模型及服务/家庭牧场数据填报/家庭牧场数据填报测试用例.md

@@ -0,0 +1,23 @@
+# 家庭牧场数据填报 — 测试用例
+
+> **接口 Base Path**：`/dataModel/familyRanch`  
+> **建表**：执行 `sql/biz_family_ranch.sql`  
+> **模板**：`family_ranch_import_template.xlsx`
+
+| 编号 | 场景 | 期望 |
+| --- | --- | --- |
+| UT-001 | 解析运行模板样例 | 2 行；企业名/乡镇村/成立日期（序列号→日期）正确 |
+| UT-002 | 派生计算 | 存栏小计、草场面积、利润、是否草畜平衡正确 |
+| API-001 | 新增 | 选村+企业名+年月成功；乡镇回填 |
+| API-002 | 唯一键 | 同年同月同村同企业名再增失败 |
+| API-003 | 导入 upsert | 已有更新、新建插入；不删同月其他记录 |
+| API-004 | 导入失败 | 乡镇/村无法识别 → 整批不写 |
+| API-005 | 导出 | 选年月导出；可选乡镇；无合计行；填表人为当前用户 |
+| API-005a | 列表已选乡镇后导出 | 导出弹窗所属乡镇与列表一致；传 `townDeptId` 仅该乡镇 |
+| API-005b | 导出弹窗清空乡镇 | 不传 `townDeptId`，导出全部乡镇 |
+| API-006 | 草畜失衡 | 载畜量<存栏绵羊单位 → `biz_yak_disease_warning` 有 `warning_type=6` 记录；改平衡后该预警消失 |
+| UI-001 | 列表筛选 | 年/月/乡镇/企业名 |
+| UI-002 | 表单村级联 | 只选村；新增默认本年本月 |
+| UI-003 | 列表选某乡镇后打开导出 | 标签/占位/选项与列表相同，且已选中该乡镇 |
+
+对应单测：`FamilyRanchExcelParserTest`