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

> 依据：同目录 `牦牛存栏数据填报功能需求.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` |

---

## 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` 可选年份 |
| `listYakHerdInventoryTownOptions` | GET | `/townOptions` 乡镇下拉 |
| `importYakHerdInventory` | POST | `/importData`（`multipart/form-data`：`file` + `statYear`） |

模板下载使用 `downloadYakHerdInventoryTemplate()`（**GET** + `responseType: 'blob'`），勿用若依全局 `this.download()`（固定 **POST**，仅适用于导出类接口）。

---

## 3. 页面结构

1. **筛选区**：所属年份（`yearOptions`）、所属乡镇（`townOptions`）；**搜索**、**重置**、**新增**、**导入**。  
2. **列表区**：所属年份、乡镇、村居数、牧户数、存栏数、公牛存栏数、母牛存栏数；空值展示 `—`。  
3. **操作列**：查看、修改、删除。  
4. **新增/编辑弹窗**：年份/乡镇必填；存栏指标必填，`el-input-number`（`:min="0"` `:precision="0"`，非负整数）；备注选填。  
5. **查看弹窗**：全字段只读（含预留村居、审计信息）；可跳转编辑。  
6. **导入弹窗**：先选「填报年份」→ 上传 `.xlsx` → 展示 insert/update/fail 及 fail/warn 明细。

**本期前端不实现**：Excel 导出（后端已有 `/export`，需求 §3 标注后续立项）。

---

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

| 规则 | 实现 |
| --- | --- |
| 年份范围 | 由 `/yearOptions` 动态加载（当前年起向前 5 年） |
| 乡镇下拉 | `/townOptions` 返回 `deptId` / `deptName` |
| 列表筛选 | `statYear`、`townDeptId` 精确匹配 |
| 存栏数字 | 必填；须为大于等于 0 的整数 |
| 唯一性 | 同年同乡镇重复由后端拦截，前端展示 `msg` |
| 导入 | `FormData` 提交；成功后 `$alert` 展示摘要与明细 |
| 删除 | `$modal.confirm` 后 `delYakHerdInventory(id)` |
| 预留村居 | 详情展示 `villageDeptId` / `villageName`；表单本期不编辑 |

---

## 5. 国际化

| 项 | 说明 |
| --- | --- |
| **语言包** | `dataModel.yakHerdInventory`、`dataModel.common` |
| **文件** | `lang/zh/dataModel.js`、`lang/bo/dataModel.js` |
| **Mixin** | `dataModelLocaleMixin`，`dmNs = 'yakHerdInventory'`，`dmT` / `dmCommon` |
| **注册** | 已随 `dataModel` 模块在 `lang/zh-CN.js`、`lang/bo.js` 引入 |

---

## 6. 联调说明

1. 部署后端 `BizYakHerdInventoryController` 及 `biz_yak_herd_inventory` 表。  
2. 菜单组件 `dataModel/yakHerdInventory/index`，权限与后端 §5 一致。  
3. 执行 `sql/biz_yak_herd_inventory.sql`（及乡镇 `sys_dept` 数据）。  
4. 验证：年份/乡镇筛选、CRUD、导入模板下载、导入结果反馈、双语切换。  
5. 导入联调：选填报年份 → 上传 `2026年.xlsx` 格式文件；开发环境对照后端日志与 `failMessages`。

---

## 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；对齐功能需求 v1.3 |