huimv-baqing/doc/产业数据模型及服务/牦牛出栏数据填报/牦牛出栏数据填报前端技术方案.md

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

依据：同目录 牦牛出栏数据填报功能需求.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 可选年份
listYakOutboundReportTownOptions	GET	/townOptions 乡镇下拉
importYakOutboundReport	POST	/importData（multipart/form-data：file + statYear）
downloadYakOutboundReportTemplate	GET	/importTemplate 空白模板（responseType: 'blob'）
exportYakOutboundReport	GET	/export?statYear= 按年份导出（responseType: 'blob'）

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

---

3. 页面结构

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

---

4. 业务规则（前端）

规则	实现
年份范围	由 /yearOptions 动态加载（当前年起向前 5 年，共 6 年）
乡镇下拉	/townOptions 返回 deptId / deptName
列表筛选	statYear、townDeptId 精确匹配
数量字段	选填；填写时须为 ≥ 0 的整数
单位后缀	户、人、头、只、匹（见 i18n unit*）
唯一性	同年同乡镇重复新增由后端拦截，前端展示 msg
导入	FormData 提交；全局 loading；成功后 $alert 展示摘要与明细
导出	弹框选年；年份须在 yearOptions 内
删除	$modal.confirm 后 delYakOutboundReport(id)，物理删除

---

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

前端 prop	说明	单位
statYear	所属年份	—
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 引入

---

7. 联调说明

1. 部署后端 BizYakOutboundReportController 及 biz_yak_outbound_report 表。
   
2. 菜单组件 dataModel/yakOutboundReport/index，权限与后端 §5 一致。
   
3. 执行 sql/biz_yak_outbound_report.sql（及乡镇 sys_dept 数据）。
   
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