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

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

依据：同目录功能需求；模板 baqing-admin/src/main/resources/templates/yak_outbound_report_import_template.xlsx。

1. 架构

Controller /dataModel/yakOutboundReport → Service → Mapper；Excel：YakOutboundReportExcelParser / YakOutboundReportExcelExporter；校验：YakOutboundReportValidation（村反推乡镇）。

2. 表 biz_yak_outbound_report

唯一键 uk_year_month_village (stat_year, stat_month, village_dept_id)；含 town_*、village_* 及出栏/自食明细字段。两项合计不落库。DDL：sql/biz_yak_outbound_report.sql（DROP 全量重建）。

3. 接口

URI	说明
CRUD /list /{id} POST/PUT/DELETE	同常规；列表/详情返回明细字段
/villageTree	县→乡镇→村
/importData	按唯一键 upsert（存在更新 / 不存在插入）
/export	按年月导出；可选 townDeptId，不传则全部乡镇

Excel 列（0-based）

列	字段
1～2	乡镇、村
3～4	户数、人数
5～10	六类出栏
11	出栏合计（导出算）
12～14	自食牛/绵羊/山羊
15	自食合计（导出算）

数据起始行：headerRow + 1。

4. 前端合计

字段	计算	使用处
牲畜总出栏数	六类出栏 sum	列表列、详情只读
自食牲畜总数	三类自食 sum	列表列、详情只读

新增/修改表单不渲染上述两项。

5. 导入 / 导出

• 导入：校验全部成功 → 按 (年,月,村) 存在 update、不存在 insert。
  
• 导出：写村行 + 行内小计；合计行合并 0～2 列；自户数起求和。

6. 大屏

地图乡镇标注对填报表按 town_dept_id 聚合 sum 后再关联。

8. 修订记录

版本	说明
2.0	村粒度全量覆盖；列映射对齐交接模板；大屏按乡镇聚合
2.1	列表/详情合计字段口径；新增修改不展示合计
2.2	导入改为 upsert；导出增加可选乡镇筛选