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

> 依据：同目录 `牦牛存栏数据填报功能需求.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` 可选月份（1～12） |
| `listYakHerdInventoryTownOptions` | GET | `/townOptions` 乡镇下拉 |
| `importYakHerdInventory` | POST | `/importData`（`multipart/form-data`：`file` + `statYear` + `statMonth`） |
| `exportYakHerdInventory` | GET | `/export`（`statYear` + `statMonth`，`responseType: blob`） |

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

---

## 3. 页面结构

1. **筛选区**：所属年份、**所属月份**、所属乡镇（均可清空）；**搜索**、**重置**、**新增**、**导入**、**导出**。  
2. **列表区**：所属年份、**所属月份**、乡镇、村居数、牧户数、存栏数、公牛/母牛存栏数；空值展示 `—`。  
3. **操作列**：查看、修改、删除。  
4. **新增/编辑弹窗**：年份、月份、乡镇必填；存栏指标必填；**新增时默认当前年月**。  
5. **查看弹窗**：全字段只读（含预留村居、审计信息）；可跳转编辑。  
6. **导入弹窗**：选「填报年份」「填报月份」（**默认当前年月**）→ 上传 `.xlsx` → 展示 insert/update/fail 及 fail/warn 明细。  
7. **导出弹窗**：选「所属年份」「所属月份」（**默认当前年月**）→ 下载 `{年}年{月}月牦牛存栏数据.xlsx`。

---

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

| 规则 | 实现 |
| --- | --- |
| 年份范围 | 由 `/yearOptions` 动态加载（当前年起向前 5 年） |
| 月份范围 | 页面 `monthOptions` 固定 1～12；展示 `{month}月`（i18n `statMonthLabel`） |
| 乡镇下拉 | `/townOptions` 返回 `deptId` / `deptName` |
| 列表筛选 | `statYear`、`statMonth`、`townDeptId` 精确匹配；**进入页面不默认年月** |
| 重置 | 清空年份、月份、乡镇后重新查询 |
| 存栏数字 | 必填；须为大于等于 0 的整数 |
| 唯一性 | 同年同月同乡镇重复由后端拦截，前端展示 `msg` |
| 导入 | `FormData` 含 `statYear`、`statMonth`；成功后 `$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` |
| **月份文案** | `queryStatMonth`、`colStatMonth`、`formStatMonth`、`importStatMonth`、`exportStatMonth`、`statMonthLabel` 等 |

---

## 6. 联调说明

1. 部署后端 `BizYakHerdInventoryController` 及 `biz_yak_herd_inventory` 表（含 `stat_month`）。  
2. 已有库执行 `sql/biz_yak_herd_inventory_stat_month.sql`。  
3. 菜单组件 `dataModel/yakHerdInventory/index`，权限与后端 §5 一致。  
4. 验证：年月/乡镇筛选、CRUD、导入导出、双语切换。  
5. 导入联调：选填报年月 → 上传 `2026年.xlsx` 格式文件。

---

## 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 |
| 1.1 | 按年月填报：列表月份列与筛选；导入/导出/新增默认当前年月；列表不默认年月；导出已实现 |