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

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牦牛出栏数据填报 |
| 目标 | 按**乡镇 × 所属年份**填报、导入、维护县域农牧户牲畜**出栏及自食**统计数据，支撑养殖产业监管报表及历史年度对比 |
| 关联系统 | 业务后台（增删改查、Excel 导入）；组织机构 `sys_dept`（乡镇字典） |
| 修订依据 | 业务模板 `牲畜数据.xlsx` 第 **6** 个 Sheet（如「2026年度农牧户牲畜出栏及自食情况统计表」，附表 5）；用户填报诉求 |

本文档仅描述**功能需求与业务规则**，不涉及库表字段命名、接口路径、技术栈选型及实现细节（见同目录技术方案）。

---

## 2. 术语与统计口径

### 2.1 填报粒度

- 一条记录表示：**某一自然年、某一乡镇**的牲畜出栏及自食汇总数据（**不按村居拆行**）。  
- 同一「所属年份 + 所属乡镇」在系统中**仅允许一条记录**（物理删除后可重新填报）。

### 2.2 所属年份

| 规则 | 说明 |
| --- | --- |
| 可选范围 | **当前自然年**起向前共 **6 个自然年**（含当年），即「当年、前 1 年 … 前 5 年」 |
| 示例 | 若统计日为 2026 年，可选：2026、2025、2024、2023、2022、2021 |
| 展示 | 列表、表单、导入时均以**四位年份**展示与存储 |

### 2.3 所属乡镇

| 规则 | 说明 |
| --- | --- |
| 数据来源 | `sys_dept` 组织树**二级节点** |
| 纳入条件 | `parent_id` 为县级根节点（与现有数据一致时为 `100`），且 `order_num > 12`，且 `del_flag = '0'`、`status = '0'` |
| 展示名 | 使用 `sys_dept.dept_name`（如「巴青乡」「杂色镇」等） |
| 必填 | 新增、修改、导入时**必须**能解析到有效乡镇 |

本期乡镇名单与 `sql/sys_dept_import_town.sql` 一致（10 个乡镇/镇）。

### 2.4 出栏及自食指标含义

各数量字段均为**非负整数**，允许为空（未填报）；若填写则 **≥ 0**。

| 业务字段 | 单位 | 说明 |
| --- | --- | --- |
| 农牧户户数 | 户 | 纳入统计的农牧户数量 |
| 农牧户人数 | 人 | 纳入统计的农牧户人口数 |
| 牦牛出栏数 | 头 | 当年牦牛出栏合计 |
| 黄牛/奶牛/犏牛出栏数 | 头 | 黄牛、奶牛、犏牛出栏合计 |
| 绵羊出栏数 | 只 | 绵羊出栏合计 |
| 山羊出栏数 | 只 | 山羊出栏合计 |
| 马骡出栏数 | 匹 | 马、骡出栏合计 |
| 驴出栏数 | 头 | 驴出栏合计 |
| 自食牛头数 | 头 | 其中自食情况 — 牛 |
| 自食绵羊只数 | 只 | 其中自食情况 — 绵羊 |
| 自食山羊只数 | 只 | 其中自食情况 — 山羊 |

**说明**：模板中「出栏小计（头只匹）」「自食小计」为汇总列，**不入库**；系统可按需在前端或导出时计算展示，不作为持久化字段。

**交叉校验（建议，非阻断）**：自食牛/绵羊/山羊之和宜不超过对应出栏数；不一致时允许保存，导入结果可提示警告。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 分页列表 | 按所属年份、所属乡镇筛选；见 **§5.1** |
| 新增 | 手工填报一条乡镇年度数据；见 **§5.2** |
| 修改 | 编辑已有记录；见 **§5.3** |
| 删除 | **物理删除**；见 **§5.4** |
| 详情 | 查看指定展示字段；见 **§5.5** |
| Excel 导入 | 按模板批量导入**指定填报年份**下所有乡镇出栏数据；见 **§5.6** |
| Excel 导出 | 按**指定所属年份**导出巴青县**全部乡镇**出栏数据；见 **§5.7** |
| 乡镇下拉 | 从 `sys_dept` 动态加载合法乡镇；见 **§5.2** |
| 年份下拉 | 当前年起向前 5 年；见 **§2.2** |

**本期不实现：**

- 按村居维度的多行填报、审批流、版本对比  
- 逻辑删除

---

## 4. 业务流程

```mermaid
flowchart TD
    A[选择所属年份] --> B{录入方式}
    B -->|手工| C[选择乡镇并填写指标]
    B -->|导入| D[上传 Excel 模板]
    B -->|导出| X[下载全县乡镇 Excel]
    C --> E[保存]
    D --> F[解析并匹配乡镇]
    F --> G{同年同乡镇是否存在}
    G -->|否| H[新增]
    G -->|是| I[更新覆盖]
    E --> J[列表查询/详情]
    H --> J
    I --> J
    X --> J
```

---

## 5. 详细功能需求

### 5.1 列表查询

**筛选**

| 条件 | 规则 |
| --- | --- |
| 所属年份 | 选填；**精确**匹配；下拉范围为 **§2.2** |
| 所属乡镇 | 选填；**精确**匹配 `dept_id` |

**列表规则**

- 默认每页 **20** 条；排序：**所属年份倒序**，同年内按乡镇 `order_num` 升序（或乡镇名称拼音）。  
- 支持**重置**筛选。

**列表展示列**

| 列名 | 说明 |
| --- | --- |
| 所属年份 | 自然年 |
| 所属乡镇 | `town_name` |
| 农牧户户数 | 户 |
| 农牧户人数 | 人 |
| 牦牛出栏数 | 头 |
| 自食情况（牛） | 自食牛头数（头） |
| 操作 | 查看、修改、删除 |

---

### 5.2 新增

| 项 | 要求 |
| --- | --- |
| 必填 | **所属年份**、**所属乡镇** |
| 选填 | 农牧户户数、农牧户人数、各出栏数、各自食数、备注 |
| 乡镇 | 下拉仅含 **§2.3** 合法乡镇 |
| 唯一性 | 同年同乡镇已存在记录时**禁止新增**，提示「该年份该乡镇已填报」 |
| 数字 | 选填项若填写须为非负整数 |

---

### 5.3 修改

| 项 | 要求 |
| --- | --- |
| 可改字段 | 除主键外均可改；**所属年份、所属乡镇**修改后仍须满足唯一性 |
| 必填 | 所属年份、所属乡镇保持必填 |
| 表单 | 展示 **§2.4** 全部可填指标（含黄牛/犏牛、绵羊、山羊、马骡、驴及自食绵羊/山羊等列表未展示字段） |

---

### 5.4 删除

| 项 | 要求 |
| --- | --- |
| 方式 | **物理删除**（记录从库中移除，**不做逻辑删除**） |
| 确认 | 删除前二次确认 |
| 效果 | 同年同乡镇可重新新增或导入 |

---

### 5.5 详情

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「查看」 |
| 展示字段 | **所属年份**、**所属乡镇**、**农牧户户数**、**农牧户人数**、**牦牛出栏数**、**自食情况（牛）**（即自食牛头数） |
| 模式 | 只读 |

> 列表未展示的出栏分项（黄牛/犏牛、绵羊、山羊等）通过「修改」入口维护；若业务需要详情页展示全部指标，可在实施阶段扩展，**本期以用户指定 6 项为准**。

---

### 5.6 Excel 导入

| 项 | 要求 |
| --- | --- |
| 模板来源 | `牲畜数据.xlsx` 第 **6** 个 Sheet（年度出栏及自食统计表，如「那曲市巴青县2026年度农牧户牲畜出栏及自食情况统计表」） |
| 填报年份 | 导入前用户**必须选择**「填报年份」（范围 **§2.2**）；Sheet 标题中年份与所选年份不一致时，**以用户所选填报年份为准**写入 `stat_year` |
| 解析范围 | 从数据区首行（乡镇列有值且为合法乡镇名）起，至「合计」行或乡镇为空的行结束；**跳过**标题、表头、填表单位等说明行 |
| 乡镇匹配 | Excel「乡镇」列与 `sys_dept.dept_name` **精确匹配**（trim 后）；模板中若为「扎色镇」，宜按 **§8** 同义映射为「杂色镇」 |
| 唯一键 | **所属年份 + 所属乡镇（`town_dept_id`）** |
| 合并策略 | **upsert**：已存在 → 全量覆盖更新；不存在 → 新增 |
| 重复导入 | 允许对同一模板多次导入；已有乡镇行均为更新 |
| 结果反馈 | 返回 `insertCount`、`updateCount`、失败条数及失败明细（行号、乡镇、原因） |
| 文件限制 | `.xlsx`；大小上限与项目统一上传限制一致 |

**模板列映射（第 6 个 Sheet，0-based 列号以实施对照模板冻结）**

| 列号 | Excel 列 | 表头（约） | 映射字段 |
| --- | --- | --- | --- |
| 1 | B | 乡镇 | 所属乡镇 |
| 2 | C | 户数 | 农牧户户数 |
| 3 | D | 人数 | 农牧户人数 |
| 4 | E | 牦牛（头） | 牦牛出栏数 |
| 5 | F | 黄牛、奶牛、犏牛（头） | 黄牛/奶牛/犏牛出栏数 |
| 6 | G | 绵羊（只） | 绵羊出栏数 |
| 7 | H | 山羊（只） | 山羊出栏数 |
| 8 | I | 马骡（匹） | 马骡出栏数 |
| 9 | J | 驴（头） | 驴出栏数 |
| 10 | K | 小计（头只匹） | **忽略**（汇总列） |
| 11 | L | 牛（头） | 自食牛头数 |
| 12 | M | 绵羊（只） | 自食绵羊只数 |
| 13 | N | 山羊（只） | 自食山羊只数 |
| 14 | O | 自食小计 | **忽略**（汇总列） |
| 15 | P | 备注 | `remark` |

数据区起始行：表头含「乡镇」「户数」「牦牛（头）」的下一行（模板存在合并单元格，实施时按代码常量定位，参考 **§8**）。

---

### 5.7 Excel 导出

| 项 | 要求 |
| --- | --- |
| 入口 | 列表页「按年份导出」 |
| 导出年份 | 用户**必须选择**筛选条件中的「所属年份」（范围 **§2.2**）；未选择时前端提示 |
| 导出范围 | **巴青县全部乡镇**（**§2.3** 合法乡镇，按 `order_num` 排序），**不受**「所属乡镇」筛选限制 |
| 模板 | 与导入共用：`baqing-admin/src/main/resources/templates/yak_outbound_report_import_template.xlsx`（业务源文件 `牲畜数据.xlsx` 第 6 Sheet） |
| 填充规则 | 表头标题、表头「年牲畜出栏数」区块及 Sheet 页签中的年份均替换为所选年份；每个乡镇一行；有填报数据的乡镇填入全部指标；未填报乡镇仅保留乡镇名称，指标为空 |
| 合计行 | 数据区末行输出「合计」，对**已填报乡镇**的数值列求和；出栏小计（K 列）、自食小计（O 列）由分项加总后写入 |
| 文件格式 | `.xlsx`；文件名示例：`2026年牦牛出栏数据.xlsx` |
| 与导入关系 | 导出文件列结构与导入模板一致，可再次导入（同年将 upsert） |

**与「下载模板」区别**：「下载模板」为空白模板；「按年份导出」为按库内数据填充后的全县报表。

---

## 6. 权限矩阵

| 操作 | 建议权限 |
| --- | --- |
| 列表查询 | `dataModel:yakOutboundReport:list` |
| 详情 | `dataModel:yakOutboundReport:query` |
| 新增 | `dataModel:yakOutboundReport:add` |
| 修改 | `dataModel:yakOutboundReport:edit` |
| 删除 | `dataModel:yakOutboundReport:remove` |
| 导入 | `dataModel:yakOutboundReport:import` |
| 导出 | `dataModel:yakOutboundReport:export` |

数据权限：县级管理员可见全县；乡镇账号仅可见本乡镇数据（若启用部门数据权限，按 `town_dept_id` 与登录用户 `dept_id` 过滤）。

---

## 7. 提示与错误约定

- 必填项未填、年份/乡镇不合法、同年同乡镇重复新增  
- 导入：文件格式错误、乡镇无法匹配、数字非整数、行为空  
- 导出：未选年份、年份不在可选范围  
- 删除成功/失败、导入部分失败（展示明细）  

采用项目统一 `AjaxResult` 文案风格。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 性能 | 列表分页；导入单次 ≤ 20 行（10 乡镇 + 合计行跳过） |
| 审计 | 记录创建人、创建时间、更新人、更新时间 |
| 模板差异 | 业务源文件 `牲畜数据.xlsx` 第 6 Sheet 乡镇「扎色镇」与 `sys_dept`「杂色镇」同义，导入宜做别名映射 |
| 扩展 | 与「养殖产业数据」看板联动 |

---

## 9. 需求追溯

| 能力 | 章节 |
| --- | --- |
| 表字段与必填 | §2、§5.2 |
| 年份向前 5 年 | §2.2 |
| 乡镇 sys_dept | §2.3 |
| 增删改查 | §5.1～5.5 |
| 物理删除 | §5.4 |
| Excel 导入第 6 Sheet | §5.6 |
| Excel 按年份导出 | §5.7 |
| 列表/详情字段 | §5.1、§5.5 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：出栏及自食指标、乡镇年度填报、Excel 导入、物理删除 |
| 1.1 | 增加 **§5.7 按年份导出** 全县乡镇 Excel；权限 `export` |