# 牦牛出栏数据填报 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牦牛出栏数据填报 |
| 目标 | 按**村 × 所属年月**填报、导入、维护农牧户牲畜出栏及自食情况；**每月导入一次**当月快照 |
| 关联系统 | 业务后台；`sys_dept`（乡镇、村） |
| 修订依据 | 交接表 `牦牛出栏数据填报.xlsx`；运行模板 `yak_outbound_report_import_template.xlsx` |

---

## 2. 术语与统计口径

### 2.1 填报粒度

- 一条记录：**某一自然年、某一自然月、某一行政村**的出栏及自食汇总。  
- 保存时由所选村反推所属乡镇。  
- 唯一键：所属年份 + 所属月份 + 所属村。  
- 同月重复导入为**该年月全量覆盖**（先删后插）。

### 2.2～2.4 年月 / 乡镇 / 村

与存栏模块一致：年份向前 6 年、月份 1～12 不可未来月；乡镇为 `sys_dept` 二级合法节点；村为三级叶子；表单只选村。

### 2.5 指标

**录入（新增/修改可编辑）**：农牧户数、农牧人数；牦牛、黄牛/奶牛/犏牛、绵羊、山羊、马骡、驴出栏；自食牛、自食绵羊、自食山羊；备注。  

**计算字段（不入库）**：

| 名称 | 计算规则 | 展示位置 |
| --- | --- | --- |
| 牲畜总出栏数 | 六类出栏之和 | 列表、详情、Excel 导出；**新增/修改不展示** |
| 自食牲畜总数 | 三类自食之和 | 列表、详情、Excel 导出；**新增/修改不展示** |

自食大于对应出栏时允许保存，导入可返回警告。

---

## 3. 功能范围

| 能力 | 说明 |
| --- | --- |
| 分页列表 | 见 **§5.1** |
| 新增 / 修改 | 见 **§5.2** |
| 详情 | 见 **§5.3** |
| 删除 | 物理删除 |
| Excel 导入 / 导出 / 下载模板 | 见 **§5.4～5.5** |

---

## 5. 详细功能需求

### 5.1 列表查询

**筛选**：所属年份、所属月份、所属乡镇、所属村（均可清空；进入页不默认年月）。

**列表展示列**

| 列名 | 说明 |
| --- | --- |
| 所属年份 | `stat_year` |
| 所属月份 | `stat_month`（展示为「N 月」） |
| 所属乡镇 | `town_name` |
| 所属村 | `village_name` |
| 农牧户数 | `farmer_household_count` |
| 农牧人数 | `farmer_population_count` |
| 牦牛出栏数 | `yak_outbound_count` |
| 牲畜总出栏数 | 六类出栏之和（前端计算） |
| 自食牛数 | `self_consumption_cattle_count` |
| 自食牲畜总数 | 三类自食之和（前端计算） |
| 操作 | 查看、修改、删除 |

### 5.2 新增 / 修改

| 项 | 要求 |
| --- | --- |
| 必填 | 所属年份、所属月份、所属村 |
| 录入项 | **§2.5** 全部可编辑明细（不含两项合计） |
| 乡镇 | 由村反推，表单不单独选择 |
| 默认值 | 新增时年月默认当前年月 |
| 唯一性 | 同年同月同村已存在则禁止新增 |
| 合计 | **不展示**牲畜总出栏数、自食牲畜总数 |

### 5.3 详情

展示与新增录入字段一致的全部明细，并额外展示：**所属乡镇**、**牲畜总出栏数**、**自食牲畜总数**（只读计算）。

### 5.4 Excel 导入

选填报年月 → 解析乡镇+村 → 任一行失败则不写库 → 成功则该年月全量覆盖。

### 5.5 Excel 导出

导出该月已填报村行；合计行合并序号+乡镇+村；自户数起按列求和；填表时间为导出当日年月。

Excel 列：序号、乡镇、村、户数、人数、六类出栏、出栏合计、三类自食、自食合计。

---

## 6. 权限

`dataModel:yakOutboundReport:list|query|add|edit|remove|import|export`

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0～1.x | 乡镇粒度、按年月、upsert 等历史版本 |
| 2.0 | 按村填报；列含村；导入全量覆盖；导出合计按列求和；对齐交接模板 |
| 2.1 | 列表增牲畜总出栏数/自食牲畜总数；详情展示全部明细+合计；新增/修改不展示合计 |