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

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

---

## 1. 页面与路由

| 项 | 说明 |
| --- | --- |
| **Vue 路径** | `ruoyi-ui/src/views/dataModel/yakOutboundReport/index.vue` |
| **组件名** | `YakOutboundReport` |
| **菜单配置** | 组件路径：`dataModel/yakOutboundReport/index`（「产业数据模型及服务」目录下） |
| **权限前缀** | `dataModel:yakOutboundReport:list\|query\|add\|edit\|remove\|import\|export` |

---

## 2. API 模块

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

| 方法 | HTTP | 说明 |
| --- | --- | --- |
| `listYakOutboundReport` | GET | `/list` 分页列表 |
| `getYakOutboundReport` | GET | `/{id}` 详情 |
| `addYakOutboundReport` | POST | `/` 新增 |
| `updateYakOutboundReport` | PUT | `/` 修改 |
| `delYakOutboundReport` | DELETE | `/{ids}` 删除 |
| `listYakOutboundReportYearOptions` | GET | `/yearOptions` 可选年份 |
| `listYakOutboundReportMonthOptions` | GET | `/monthOptions` 可选月份（1～12） |
| `listYakOutboundReportTownOptions` | GET | `/townOptions` 乡镇下拉 |
| `importYakOutboundReport` | POST | `/importData`（`multipart/form-data`：`file` + `statYear` + `statMonth`） |
| `downloadYakOutboundReportTemplate` | GET | `/importTemplate` 空白模板（`responseType: 'blob'`） |
| `exportYakOutboundReport` | GET | `/export?statYear=&statMonth=` 按年月导出（`responseType: 'blob'`） |

模板下载、按年月导出均使用 **GET** + `responseType: 'blob'`，勿用若依全局 `this.download()`（固定 **POST**）。

---

## 3. 页面结构

1. **筛选区**：所属年份、**所属月份**、所属乡镇（均可清空）；**搜索**、**重置**、**新增**、**导入**、**导出**。  
2. **列表区**：所属年份、**所属月份**、所属乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食情况（牛）；空值展示 `—`。  
3. **操作列**：查看、修改、删除。  
4. **新增/编辑弹窗**：年份、月份、乡镇必填；出栏及自食指标选填，`el-input-number`（`:min="0"` `:precision="0"`）；备注选填；**新增时默认当前年月**。表单分四块：基本信息、农牧户情况、出栏情况、自食情况。  
5. **查看弹窗**：只读展示需求 **§5.5** 七字段（年份、**月份**、乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食牛头数）；可跳转编辑。  
6. **导入弹窗**：选「填报年份」「填报月份」（**默认当前年月**）→ 上传 `.xlsx` → 展示 insert/update/fail 及 fail/warn 明细。  
7. **导出弹窗**：选「所属年份」「所属月份」（**默认当前年月**）→ `GET /export` 下载 `{年}年{月}月牦牛出栏数据.xlsx`。

---

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

| 规则 | 实现 |
| --- | --- |
| 年份范围 | 由 `/yearOptions` 动态加载（当前年起向前 5 年，共 6 年） |
| 月份范围 | 页面 `monthOptions` 固定 1～12；展示 `{month}月`（i18n `statMonthLabel`） |
| 乡镇下拉 | `/townOptions` 返回 `deptId` / `deptName` |
| 列表筛选 | `statYear`、`statMonth`、`townDeptId` 精确匹配；**进入页面不默认年月** |
| 重置 | 清空年份、月份、乡镇后重新查询 |
| 数量字段 | 选填；填写时须为 ≥ 0 的整数 |
| 单位后缀 | 户、人、头、只、匹（见 i18n `unit*`） |
| 唯一性 | 同年同月同乡镇重复新增由后端拦截，前端展示 `msg` |
| 导入 | `FormData` 含 `statYear`、`statMonth`；全局 loading；成功后 `$alert` 展示摘要与明细 |
| 导出 | 弹框选年月；年月须在合法范围内 |
| 删除 | `$modal.confirm` 后 `delYakOutboundReport(id)`，物理删除 |

---

## 5. 字段映射（表单 / 接口 Body）

| 前端 prop | 说明 | 单位 |
| --- | --- | --- |
| `statYear` | 所属年份 | — |
| `statMonth` | 所属月份（1～12） | — |
| `townDeptId` | 所属乡镇 | — |
| `farmerHouseholdCount` | 农牧户户数 | 户 |
| `farmerPopulationCount` | 农牧户人数 | 人 |
| `yakOutboundCount` | 牦牛出栏数 | 头 |
| `cattleOutboundCount` | 黄牛/奶牛/犏牛出栏数 | 头 |
| `sheepOutboundCount` | 绵羊出栏数 | 只 |
| `goatOutboundCount` | 山羊出栏数 | 只 |
| `horseMuleOutboundCount` | 马骡出栏数 | 匹 |
| `donkeyOutboundCount` | 驴出栏数 | 头 |
| `selfConsumptionCattleCount` | 自食牛头数 | 头 |
| `selfConsumptionSheepCount` | 自食绵羊只数 | 只 |
| `selfConsumptionGoatCount` | 自食山羊只数 | 只 |
| `remark` | 备注 | — |

---

## 6. 国际化

| 项 | 说明 |
| --- | --- |
| **语言包** | `dataModel.yakOutboundReport`、`dataModel.common` |
| **文件** | `lang/zh/dataModel.js`、`lang/bo/dataModel.js` |
| **Mixin** | `dataModelLocaleMixin`，`dmNs = 'yakOutboundReport'`，`dmT` / `dmCommon` |
| **注册** | 已随 `dataModel` 模块在 `lang/zh-CN.js`、`lang/bo.js` 引入 |
| **月份文案** | `queryStatMonth`、`colStatMonth`、`formStatMonth`、`importStatMonth`、`exportStatMonth`、`statMonthLabel` 等 |

---

## 7. 联调说明

1. 部署后端 `BizYakOutboundReportController` 及 `biz_yak_outbound_report` 表（含 `stat_month`）。  
2. 已有库自 v1.1 按年表升级时执行迁移 SQL（历史 `stat_month` 默认 **12**）。  
3. 菜单组件 `dataModel/yakOutboundReport/index`，权限与后端 §5 一致。  
4. 验证：年月/乡镇筛选、CRUD、导入模板下载、导入结果反馈、按年月导出、双语切换。  
5. 导入联调：选填报年月 → 上传 `牲畜数据.xlsx` 第 6 Sheet 格式文件；对照 `failMessages` / `warnMessages`。

---

## 8. 文件清单

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

---

## 9. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：列表/CRUD/详情/导入/模板下载/按年导出；汉藏 i18n；对齐功能需求 v1.1 |
| 1.1 | 按年月填报：列表月份列与筛选；导入/导出/新增默认当前年月；列表不默认年月；`/monthOptions`；导出文件名含月份 |