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

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

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