# 牦牛存栏数据填报 — 前端技术方案

> 依据：同目录 `牦牛存栏数据填报功能需求.md`、`牦牛存栏数据填报技术方案.md`；布局对齐 `dataModel/grassland/index.vue`（双 `el-card` + 分页表格）；字段 **小驼峰**。

---

## 1. 页面与路由

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

---

## 2. API 模块

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

| 方法 | HTTP | 说明 |
| --- | --- | --- |
| `listYakHerdInventory` | GET | `/list` 分页列表 |
| `getYakHerdInventory` | GET | `/{id}` 详情 |
| `addYakHerdInventory` | POST | `/` 新增 |
| `updateYakHerdInventory` | PUT | `/` 修改 |
| `delYakHerdInventory` | DELETE | `/{ids}` 删除 |
| `listYakHerdInventoryYearOptions` | GET | `/yearOptions` |
| `listYakHerdInventoryMonthOptions` | GET | `/monthOptions` |
| `listYakHerdInventoryTownOptions` | GET | `/townOptions` |
| `listYakHerdInventoryVillageTree` | GET | `/villageTree` 县→乡镇→村 |
| `importYakHerdInventory` | POST | `/importData`（`file` + `statYear` + `statMonth`） |
| `exportYakHerdInventory` | GET | `/export`（`statYear` + `statMonth`，`blob`） |

模板下载：`downloadYakHerdInventoryTemplate()`（**GET** + `blob`），勿用若依全局 `this.download()`（固定 POST）。

---

## 3. 页面结构

1. **筛选区**：所属年份、所属月份、所属乡镇、所属村（Treeselect）；搜索、重置、新增、导入、导出。  
2. **列表区**：所属年份、所属月份、所属乡镇、所属村、村居数、牧户数、存栏数、公牛/母牛存栏数；空值展示 `—`。  
3. **操作列**：查看、修改、删除。  
4. **新增/编辑弹窗**：年份、月份、所属村（必填）；明细录入字段（`INPUT_COUNT_FIELDS`）；**不展示**派生合计；新增默认当前年月。  
5. **查看弹窗**：全字段只读（含派生合计、审计信息）。  
6. **导入弹窗**：选填报年月（默认当前）→ 上传 `.xlsx` → 展示 insert/fail/warn。  
7. **导出弹窗**：选所属年月（默认当前）、可选所属乡镇（与列表一致，可清空；不选则全部乡镇）→ 下载 `{年}年{月}月牦牛存栏数据.xlsx`。

---

## 4. 业务规则（前端）

| 规则 | 实现 |
| --- | --- |
| 年份 / 月份 | `/yearOptions`、`/monthOptions`；展示 `{month}月` |
| 村树 | `/villageTree`；`vue-treeselect`：`disable-branch-nodes`、`append-to-body` |
| 列表筛选 | `statYear`、`statMonth`、`townDeptId`、`villageDeptId`；进入页不默认年月 |
| 提交体 | 传 `villageDeptId` 与明细；不传乡镇（后端反推） |
| 派生字段 | 仅详情 `DERIVED_COUNT_FIELDS` 展示 |
| 唯一性 | 同年同月同村重复由后端拦截 |
| 导入 | `FormData` 含年月；成功后 `$alert` 摘要 |
| 删除 | `$modal.confirm` 后删除 |

**录入字段**（`INPUT_COUNT_FIELDS`）：`villageCount`、`herdsmanHouseholdCount`、`breedingBullCount`、`bullCastratedCount`、`cowYoungCount`、`cowAdultCount`、`milkingCowCount`、`fertileCowCount`、`sheepTotal`、`milkingSheepCount`、`insuredYakCount`。

**派生字段**（`DERIVED_COUNT_FIELDS`）：`bullTotal`、`cowTotal`、`dairyTotal`、`yakTotal`、`grandTotal`、`yakSheepTotal`。

---

## 5. 国际化

| 项 | 说明 |
| --- | --- |
| **语言包** | `dataModel.yakHerdInventory`、`dataModel.common` |
| **文件** | `lang/zh/dataModel.js`、`lang/bo/dataModel.js` |
| **Mixin** | `dataModelLocaleMixin`，`dmNs = 'yakHerdInventory'` |

---

## 6. 联调说明

1. 部署后端并执行 `sql/biz_yak_herd_inventory.sql`（或村唯一键迁移脚本）。  
2. 菜单组件 `dataModel/yakHerdInventory/index`。  
3. 验证：村树选村、CRUD、导入全量覆盖、导出合计行、详情含派生字段、双语。  

---

## 7. 文件清单

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

---

## 8. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：列表/CRUD/详情/导入；汉藏 i18n |
| 1.1 | 按年月填报：列表月份筛选；导入/导出 |
| 1.2 | 按村填报：Treeselect 村树；列表乡镇+村；表单仅明细；详情含派生合计；字段对齐新模板 |