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

> 依据：同目录功能需求、技术方案；交互对齐出栏/合作社村级填报；字段 **小驼峰**。

---

## 1. 页面与路由

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

---

## 2. API 模块

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

CRUD、`yearOptions` / `monthOptions` / `townOptions` / `villageTree`、导入 `importData`、模板 `importTemplate`、导出 `export`（可选 `townDeptId`）与畜牧产品产量模块同构；模板/导出均为 **GET + blob**。

---

## 3. 页面结构

1. **筛选**：年、月、乡镇、企业名称（无村筛选，与需求一致）。  
2. **列表**：年、月、乡镇、村、企业、法人、类型、注册资本、成立时间、牛存栏、牛出栏、草场面积（`grasslandAreaSubtotal`）、操作。  
3. **新增/编辑**：选村（可搜索）；企业类型默认「个体工商户」、销售渠道默认「其他」；成立时间 `el-date-picker`（`yyyy-MM-dd`）；派生字段只读展示。  
4. **详情**：全部字段含派生 + 乡镇只读。  
5. **导入**：选年月 → upsert 摘要。  
6. **导出**：选年月；所属乡镇与列表共用选项与文案，打开时带入列表当前乡镇，清空=全部。

---

## 4. 业务规则

| 规则 | 实现 |
| --- | --- |
| 必填 | 年、月、村、企业名称 |
| 提交 | 只传 `villageDeptId` 与录入项；乡镇与派生由后端计算 |
| 前端只读派生 | 存栏小计、草场面积小计、利润、是否草畜平衡户（与后端公式一致，便于预览） |
| 是/否 | `hasSubsidy` / `hasTrademark` / `hasQualityCert` 单选「是」「否」 |
| 枚举 | 企业类型、销售渠道与后端 `FamilyRanchValidation` 一致 |

---

## 5. 国际化

`dataModel.familyRanch`（`lang/zh|bo/dataModel.js`）；`dmNs = 'familyRanch'`。

---

## 6. 联调说明

1. 执行 `sql/biz_family_ranch.sql`。  
2. 菜单组件 `dataModel/familyRanch/index`。  
3. 验证：默认类型/渠道、派生只读、导出乡镇带入列表筛选、草畜失衡写入疾病预警（后端）。

---

## 7. 文件清单

| 类型 | 路径 |
| --- | --- |
| 页面 | `ruoyi-ui/src/views/dataModel/familyRanch/index.vue` |
| API | `ruoyi-ui/src/api/dataModel/familyRanch.js` |
| i18n | `lang/zh/dataModel.js`、`lang/bo/dataModel.js` |

---

## 8. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：村×年月×企业；CRUD + 导入 upsert + 导出乡镇与列表联动 |
| 1.1 | 成立时间日期组件；补助资金年份 `type=year`（`yyyy`）；派生字段表单只读预览 |
