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

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

依据：同目录 牦牛存栏数据填报功能需求.md；模板 baqing-admin/src/main/resources/templates/yak_herd_inventory_import_template.xlsx。

---

1. 技术架构

项	说明
后端	RuoYi v3.9.2（springboot2）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid
数据库	MySQL 5.7.39，InnoDB，utf8mb4
前端	若依 Vue2 + Element UI + @riophae/vue-treeselect
Excel	Apache POI
组织	sys_dept 乡镇/村字典；TownDeptSupport

分层：BizYakHerdInventoryController → IBizYakHerdInventoryService → BizYakHerdInventoryMapper → domain；Excel 由 YakHerdInventoryExcelParser（导入）、YakHerdInventoryExcelExporter（导出）承担；校验与派生计算由 YakHerdInventoryValidation。

代码位置：baqing-admin → com.ruoyi.web.modules.industryservice。

模板文件：baqing-admin/src/main/resources/templates/yak_herd_inventory_import_template.xlsx（导入、导出、下载模板共用）。

---

2. 数据库设计

2.1 表 biz_yak_herd_inventory（牦牛存栏数据填报）

字段	类型	非空	说明
id	bigint(20)	Y	主键
stat_year	int(11)	Y	所属年份
stat_month	int(11)	Y	所属月份（1～12）
town_dept_id	bigint(20)	Y	所属乡镇，sys_dept.dept_id（由村反推）
town_name	varchar(64)	Y	乡镇名称冗余
village_dept_id	bigint(20)	Y	所属村，sys_dept.dept_id
village_name	varchar(128)	Y	村名称冗余
village_count	int(11)	N	村居数
herdsman_household_count	int(11)	N	牧户数
breeding_bull_count	int(11)	N	种公牛
bull_castrated_count	int(11)	N	公牛/阉畜
bull_total	int(11)	N	公牛合计（派生）
cow_young_count	int(11)	N	0～1.5 岁幼畜（不含 1.5 岁）
cow_adult_count	int(11)	N	1.5 岁以上成畜（含 1.5 岁）
cow_total	int(11)	N	母牛合计（派生）
milking_cow_count	int(11)	N	产奶母牛
fertile_cow_count	int(11)	N	能繁母牛
dairy_total	int(11)	N	奶牛合计（派生）
sheep_total	int(11)	N	羊总数
milking_sheep_count	int(11)	N	产奶羊
insured_yak_count	int(11)	N	保险牦牛
yak_total	int(11)	N	牦牛总存栏（派生）
grand_total	int(11)	N	总合计（派生）
yak_sheep_total	int(11)	N	总量牦牛+羊（派生）
create_by / create_time	—	—	审计
update_by / update_time	—	—	审计
remark	varchar(500)	N	备注

说明：本表不使用逻辑删除；删除为物理删除。旧四档母牛年龄字段（cow_under_1_count 等）已废弃，以 cow_young_count / cow_adult_count 为准。

索引与约束

• UNIQUE uk_year_month_village (stat_year, stat_month, village_dept_id)
  
• KEY idx_stat_year_month (stat_year, stat_month)
  
• KEY idx_town_dept_id (town_dept_id)
  
• KEY idx_village_dept_id (village_dept_id)

DDL 文件：sql/biz_yak_herd_inventory.sql（全量覆盖建表）。已有库若仍为乡镇唯一键，执行 sql/biz_yak_herd_inventory_village_uk.sql（去掉 uk_year_month_town，改为村唯一）。

2.2 派生计算（YakHerdInventoryValidation.recalculateDerived）

bull_total      = breeding_bull_count + bull_castrated_count
cow_total       = cow_young_count + cow_adult_count
dairy_total     = milking_cow_count + fertile_cow_count
yak_total       = bull_total + cow_total + insured_yak_count
grand_total     = yak_total + dairy_total + sheep_total
yak_sheep_total = bull_total + cow_total + insured_yak_count + sheep_total

保存与导入落库前一律重算覆盖。

2.3 乡镇 / 村字典

• 乡镇：TownDeptSupport.listReportTowns()（parent_id=100 且 order_num>12）。
  
• 村树：TownDeptSupport.buildVillageTree() → 县→乡镇→村；父节点不 disabled（便于展开），前端 disable-branch-nodes 仅允许选村。
  
• 解析：resolveTownByName、resolveVillageByTownAndName、requireReportVillage。

2.4 可选年份 / 月份

• YakHerdInventoryYearSupport：当前年起向前 5 年，共 6 个。
  
• YakHerdInventoryMonthSupport.resolveMonthOptions()：1～12；validateStatPeriod 拒绝未来月。

---

3. 接口设计

Base Path：/dataModel/yakHerdInventory
权限前缀：dataModel:yakHerdInventory

#	说明	Method	URI	权限
3.1	分页列表	GET	/list	list
3.2	详情	GET	/{id}	query
3.3	新增	POST	/	add
3.4	修改	PUT	/	edit
3.5	删除	DELETE	/{ids}	remove
3.6	乡镇下拉	GET	/townOptions	list
3.6.1	村树	GET	/villageTree	list
3.7	年份下拉	GET	/yearOptions	list
3.7.1	月份下拉	GET	/monthOptions	list
3.8	导入	POST	/importData	import
3.9	下载导入模板	GET	/importTemplate	import
3.10	按年月导出（可选乡镇）	GET	/export	export

3.1.1 列表 Query

参数	类型	说明
pageNum / pageSize	int	默认 1 / 20
statYear / statMonth	int	精确
townDeptId	long	乡镇
villageDeptId	long	村

列表主要字段：statYear、statMonth、townName、villageName、villageCount、herdsmanHouseholdCount、yakTotal、bullTotal、cowTotal。

3.3.1 新增/修改 Body

字段	必填	校验
statYear / statMonth	Y	合法且非未来月
villageDeptId	Y	合法村；反推乡镇
明细 *Count	N	>= 0；产奶羊与羊总均非空时：milkingSheepCount < sheepTotal
id	修改必填	—

唯一性：countByYearMonthAndVillageExcludeId(...) > 0 →「该年该月该村已填报」。

3.8 导入

请求：multipart/form-data：file + statYear + statMonth。

策略（BizYakHerdInventoryServiceImpl.importData）：

1. 解析全部有效数据行；任一行乡镇/村无法匹配或校验失败 → 整体失败，不写库。
   
2. 全部成功 → 按 (statYear, statMonth, villageDeptId) 查重，存在 update、不存在 insert。
   
3. Excel 合计列与重算不一致 → 记入 warnMessages（非阻断）。

响应：insertCount、failCount、failMessages、warnMessages。

3.8.1 Excel 列映射（0-based，YakHerdInventoryExcelParser）

列号	Excel	用途
1	B 乡镇	匹配乡镇
2	C 村	匹配村
3	D 村居	villageCount
4	E 牧户	herdsmanHouseholdCount
5	F 总合计	Excel 对照
6～8	牦牛公母分类	Excel 对照
9	J 保险	insuredYakCount
10	K 公牛合计	Excel 对照
11	L 种公牛	breedingBullCount
12	M 阉畜	bullCastratedCount
13	N 母牛合计	Excel 对照
14	O 幼畜	cowYoungCount
15	P 成畜	cowAdultCount
16	Q 奶牛合计	Excel 对照
17	R 产奶母牛	milkingCowCount
18	S 能繁母牛	fertileCowCount
19	T 羊	sheepTotal
20	U 产奶羊	milkingSheepCount
21	V 总量	Excel 对照

数据起始行：headerRow + 3（三行表头）。

3.10 按年月导出

请求：GET /export?statYear=&statMonth=。

实现：查询该年月全部村记录 → YakHerdInventoryExcelExporter.export：

1. 替换标题年、月；填表人；填表时间=导出当日年月
   
2. 按记录写数据行（含派生合计）
   
3. 末行「合计」：合并列 0～2；自列 3（村居）起对各数值列求和写入
   
4. 删除合计行之后的空行
   

---

4. 前端设计（要点）

项	说明
路径	ruoyi-ui/src/views/dataModel/yakHerdInventory/index.vue
API	ruoyi-ui/src/api/dataModel/yakHerdInventory.js
列表	年/月/乡镇/村筛选；列含乡镇、村、存栏等
表单	年/月 + Treeselect 选村；仅明细录入字段；无派生合计输入
详情	含派生合计只读
导入/导出	先选年月

---

5. 菜单与权限（示例）

同权限标识：list|query|add|edit|remove|import|export。菜单 SQL 见 sql/biz_sys_menu_yak_herd_inventory.sql。

---

6. 与养殖产业数据看板 / 大屏的关系

场景	口径
全县存栏合计	biz_yak_herd_inventory 最近填报年月全县 yak_total / bull_total / cow_total 等合计（按村汇总）
年龄结构	两档：cow_young_count、cow_adult_count；bandCode=COW_YOUNG / COW_ADULT
地图乡镇存栏	按乡镇聚合该最近年月村记录

---

7. 交付清单

• sql/biz_yak_herd_inventory.sql、sql/biz_yak_herd_inventory_village_uk.sql
  
• Domain / Mapper / Service / Controller
  
• Parser / Exporter / Validation / TownDeptSupport 村树
  
• 前端列表/表单（Treeselect）/导入/导出
  
• 单元测试与 Excel 样例
  

---

8. 修订记录

版本	说明
1.0～1.5	乡镇粒度、按年月、四档母牛年龄等历史版本
1.6	村粒度 uk_year_month_village；新模板字段与派生合计；导入全量覆盖；导出合计按列求和；/villageTree；大屏年龄两档