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

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牦牛存栏数据填报 |
| 目标 | 按**乡镇 × 所属年份**填报、导入、维护县域牦牛存栏结构统计数据，支撑养殖产业看板、监管报表及历史年度对比 |
| 关联系统 | 业务后台（增删改查、Excel 导入/导出）；组织机构 `sys_dept`（乡镇字典） |
| 修订依据 | 业务模板 `2026年.xlsx`（农业农村和科技水利局-业务办-畜群结构）；用户填报诉求 |

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

---

## 2. 术语与统计口径

### 2.1 填报粒度

- 一条记录表示：**某一自然年、某一乡镇**的牦牛存栏汇总数据（**不按村居拆行**）。  
- **所属村居**（`village_name`、`village_dept_id`）为预留字段，**非必填**，本期可空；后续若按村居下钻再扩展。  
- 同一「所属年份 + 所属乡镇」在系统中**仅允许一条记录**（物理删除后可重新填报）。

### 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 所属村居（预留）

| 规则 | 说明 |
| --- | --- |
| `village_dept_id` | 预留；关联 `sys_dept.dept_id`（预期为所选乡镇下三级村居节点），**非必填** |
| `village_name` | 预留；村居名称冗余展示，**非必填** |
| 本期 | 表单、导入均不强制填写；Excel 导入不解析该字段 |
| 校验 | 若填写 `village_dept_id`，宜校验其 `parent_id` 与当前 `town_dept_id` 一致（实施阶段可选） |

### 2.5 存栏指标含义

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

| 业务字段 | 说明 |
| --- | --- |
| 村居数 | 该乡镇下纳入统计的行政村（居）数量 |
| 牧户数 | 从事牧业生产的牧户数量 |
| 牦牛存栏数 | 牦牛总存栏（头） |
| 公牛存栏数 | 公牛合计（头） |
| 母牛存栏数 | 母牛合计（头） |
| 种公牛存栏数 | 种用公牛（头） |
| 公牛/阉畜存栏数 | 除种公牛外的公牛及阉畜（头） |
| 1 岁以下母牛存栏数 | 月龄 < 12 个月的母牛 |
| 1～3 岁母牛存栏数 | 月龄/年龄在 1 岁（含）至 3 岁（不含或按县级口径，见 **§8**） |
| 3～12 岁母牛存栏数 | 年龄在 3 岁（含）至 12 岁（不含或按县级口径） |
| 12 岁以上母牛存栏数 | 年龄 ≥ 12 岁的母牛 |

**交叉校验（建议，非阻断）**：母牛分龄之和宜等于「母牛存栏数」；「种公牛 + 公牛/阉畜」宜等于「公牛存栏数」。不一致时允许保存，列表/导入结果可提示警告（见技术方案）。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 分页列表 | 按所属年份、所属乡镇筛选；见 **§5.1** |
| 新增 | 手工填报一条乡镇年度数据；见 **§5.2** |
| 修改 | 编辑已有记录；见 **§5.3** |
| 删除 | 物理删除；见 **§5.4** |
| 详情 | 查看全部字段；见 **§5.5** |
| Excel 导入 | 按模板批量导入**指定填报年份**下所有乡镇数据；见 **§5.6** |
| Excel 导出 | 按**指定所属年份**导出巴青县**全部乡镇**存栏数据；见 **§5.7** |
| 乡镇下拉 | 从 `sys_dept` 动态加载合法乡镇；见 **§5.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` 升序（或乡镇名称拼音）。  
- 支持**重置**筛选。

**列表展示列**

| 列名 | 说明 |
| --- | --- |
| 所属年份 | `stat_year` |
| 乡镇 | `town_name`（所属乡镇） |
| 村居数 | `village_count` |
| 牧户数 | `herdsman_household_count` |
| 存栏数 | `yak_total`（牦牛总存栏，头） |
| 公牛存栏数 | `bull_total` |
| 母牛存栏数 | `cow_total` |
| 操作 | 查看、修改、删除 |

---

### 5.2 新增

| 项 | 要求 |
| --- | --- |
| 必填 | **所属年份**、**所属乡镇** |
| 选填 | 所属村居（`village_dept_id`、`village_name`，预留）、村居数、牧户数及全部存栏数字段 |
| 乡镇 | 下拉仅含 **§2.3** 合法乡镇；选定后展示 `dept_name` |
| 唯一性 | 同年同乡镇已存在有效记录时**禁止新增**，提示「该年份该乡镇已填报」 |
| 数字 | 选填项若填写须为非负整数 |

---

### 5.3 修改

| 项 | 要求 |
| --- | --- |
| 可改字段 | 除主键外均可改；**所属年份、所属乡镇**修改后仍须满足唯一性 |
| 必填 | 所属年份、所属乡镇保持必填 |
| 权限 | 具备修改权限 |

---

### 5.4 删除

| 项 | 要求 |
| --- | --- |
| 方式 | **物理删除**（`DELETE FROM biz_yak_herd_inventory`） |
| 确认 | 删除前二次确认 |
| 效果 | 记录从库中移除；同年同乡镇可重新新增或导入 |

---

### 5.5 详情

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「查看」 |
| 内容 | 展示**全部字段**（列表未展示的项均包含）：所属年份、乡镇、`village_dept_id`、`village_name`、村居数、牧户数、存栏数、公牛/母牛存栏数、种公牛、公牛/阉畜、母牛分龄（1 岁以下、1～3 岁、3～12 岁、12 岁以上）、备注及创建/更新审计信息 |
| 模式 | 只读 |

---

### 5.6 Excel 导入

| 项 | 要求 |
| --- | --- |
| 模板来源 | `2026年.xlsx` **第一个 Sheet**（表名以文件为准，通常为畜群结构统计表） |
| 填报年份 | 导入前用户**必须选择**「填报年份」（范围 **§2.2**）；文件中**不写年份**时以所选年份为准 |
| 解析范围 | 从数据区首行（乡镇列有值）起，至乡镇为空的行结束；**跳过**表头、标题、填表单位等说明行 |
| 乡镇匹配 | Excel「乡镇」列文本与 `sys_dept.dept_name` **精确匹配**（trim 后）；仅接受 **§2.3** 范围内部门 |
| 唯一键 | **所属年份（填报年份）+ 所属乡镇（`town_dept_id`）**；同一键在库中仅保留一条有效业务数据 |
| 合并策略 | 按「年份 + 乡镇」**upsert**：该键**已存在** → **全量覆盖更新**；**不存在** → **新增** |
| 重复导入 | **允许**对同一 `牦牛存栏数据.xlsx` 多次导入；第二次及以后 `updateCount` 增加、`insertCount` 为 0（乡镇均有数据时） |
| 结果反馈 | 返回 `insertCount`、`updateCount`、失败条数及失败明细（行号、乡镇、原因） |
| 文件限制 | `.xlsx`；大小上限与项目统一上传限制一致 |
| 列映射 | 与模板列顺序一致，见技术方案 **§3.8** |

**模板列（与 `2026年.xlsx` 第一个 Sheet 对齐）**

| 列序 | 表头（约） | 映射字段 |
| --- | --- | --- |
| A | 序号 | 忽略 |
| B | 乡镇 | 所属乡镇 |
| C | 村居数 | 村居数 |
| D | 牧户数 | 牧户数 |
| E | 总合计（头）/ 牦牛合计 | 牦牛存栏数 |
| F～ | 公牛相关分列 | 公牛存栏数、种公牛、公牛/阉畜等（以模板合并表头为准，实施时按单元格列号固化） |
| — | 母牛合计 | 母牛存栏数 |
| — | 1 岁以下母牛 | 1 岁以下母牛存栏数 |
| — | 1～3 岁母牛 | 1～3 岁母牛存栏数 |
| — | 3～12 岁母牛 | 3～12 岁母牛存栏数 |
| — | 12 岁以上母牛 | 12 岁以上母牛存栏数 |
| — | 备注 | `remark` |

实施阶段须对照真实模板冻结列号（技术方案给出默认列映射）。

---

### 5.7 Excel 导出

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

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

---

## 6. 权限矩阵

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

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

---

## 7. 提示与错误约定

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

采用项目统一 `AjaxResult` 文案风格，**不约定** HTTP 状态码细节。

---

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

| 类别 | 建议 |
| --- | --- |
| 性能 | 列表分页；导入单次 ≤ 50 行（10 乡镇 × 多年份分批） |
| 审计 | 记录创建人、创建时间、更新人、更新时间 |
| 口径 | 母牛分龄边界若有县级红头文件，以业务口径覆盖本文档示例说明 |
| 扩展 | 所属村居（`village_dept_id`）下钻、与「养殖产业数据」看板联动 |

---

## 9. 需求追溯

| 能力 | 章节 |
| --- | --- |
| 表字段与必填 | §2、§5.2 |
| 年份向前 5 年 | §2.2 |
| 乡镇 sys_dept | §2.3 |
| 增删改查 | §5.1～5.5 |
| Excel 导入 | §5.6 |
| Excel 导出 | §5.7 |
| 列表/详情字段 | §5.1 列表 7 列；§5.5 详情全字段 |
| 预留村居 `village_dept_id` | §2.4、§5.2、§5.5 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿 |
| 1.1 | 增加 `village_dept_id` 预留字段；列表列「乡镇」「存栏数」 |
| 1.2 | 增加 **§5.7 按年份导出** 全县乡镇 Excel；权限 `export` |
| 1.3 | 明确导入 upsert：唯一键「年份+乡镇」；重复导入更新 |
| 1.4 | 取消逻辑删除：表无 `del_flag`，删除为物理删除；唯一约束 `uk_year_town` |