牦牛存栏数据填报 — 功能需求
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. 业务流程
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 |
