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

> 依据：同目录功能需求；模板 `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；导出增加可选乡镇筛选 |