牦牛出栏数据填报 — 功能需求
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.2.1 所属月份
| 规则 |
说明 |
| 取值范围 |
1～12（自然月） |
| 填报限制 |
不可填报未来月份（相对服务器当前年月） |
| 展示 |
列表、表单、导入、导出均以「N 月」展示 |
| 历史数据 |
升级前按年填报的数据，迁移时默认 stat_month = 12 |
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 |
| 月份下拉 |
1～12；见 §2.2.1 |
本期不实现：
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 |
| 所属月份 |
选填；精确匹配（1～12）；列表进入时不默认选中 |
| 所属乡镇 |
选填；精确匹配 dept_id |
列表规则
- 默认每页 20 条；排序：所属年份倒序、所属月份倒序，同年内同月按乡镇
order_num 升序。
- 支持重置筛选（年份、月份、乡镇均清空）。
列表展示列
| 列名 |
说明 |
| 所属年份 |
自然年 |
| 所属月份 |
展示为「N 月」 |
| 所属乡镇 |
town_name |
| 农牧户户数 |
户 |
| 农牧户人数 |
人 |
| 牦牛出栏数 |
头 |
| 自食情况（牛） |
自食牛头数（头） |
| 操作 |
查看、修改、删除 |
5.2 新增
| 项 |
要求 |
| 必填 |
所属年份、所属月份、所属乡镇 |
| 选填 |
农牧户户数、农牧户人数、各出栏数、各自食数、备注 |
| 乡镇 |
下拉仅含 §2.3 合法乡镇 |
| 默认值 |
打开新增弹窗时，所属年份、所属月份默认当前年月（可改） |
| 唯一性 |
同年同月同乡镇已存在记录时禁止新增，提示「该年该月该乡镇已填报」 |
| 数字 |
选填项若填写须为非负整数 |
5.3 修改
| 项 |
要求 |
| 可改字段 |
除主键外均可改；所属年份、所属月份、所属乡镇修改后仍须满足唯一性 |
| 必填 |
所属年份、所属月份、所属乡镇保持必填 |
| 表单 |
展示 §2.4 全部可填指标（含黄牛/犏牛、绵羊、山羊、马骡、驴及自食绵羊/山羊等列表未展示字段） |
5.4 删除
| 项 |
要求 |
| 方式 |
物理删除（记录从库中移除，不做逻辑删除） |
| 确认 |
删除前二次确认 |
| 效果 |
同年同月同乡镇可重新新增或导入 |
5.5 详情
| 项 |
要求 |
| 入口 |
列表「查看」 |
| 展示字段 |
所属年份、所属月份、所属乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食情况（牛）（即自食牛头数） |
| 模式 |
只读 |
列表未展示的出栏分项（黄牛/犏牛、绵羊、山羊等）通过「修改」入口维护；若业务需要详情页展示全部指标，可在实施阶段扩展，本期以用户指定 7 项为准（含月份）。
5.6 Excel 导入
| 项 |
要求 |
| 模板来源 |
牲畜数据.xlsx 第 6 个 Sheet（年度出栏及自食统计表，如「那曲市巴青县2026年度农牧户牲畜出栏及自食情况统计表」） |
| 填报年月 |
导入前用户必须选择「填报年份」「填报月份」（月份 §2.2.1）；Sheet 标题中年份与所选年份不一致时，以用户所选填报年份为准写入 stat_year；文件中不写月份时以所选为准 |
| 解析范围 |
从数据区首行（乡镇列有值且为合法乡镇名）起，至「合计」行或乡镇为空的行结束；跳过标题、表头、填表单位等说明行 |
| 乡镇匹配 |
Excel「乡镇」列与 sys_dept.dept_name 精确匹配（trim 后）；模板中若为「扎色镇」，宜按 §8 同义映射为「杂色镇」 |
| 唯一键 |
所属年份 + 所属月份 + 所属乡镇（town_dept_id） |
| 合并策略 |
按「年月 + 乡镇」upsert：已存在 → 全量覆盖更新；不存在 → 新增 |
| 重复导入 |
允许对同一文件在同一填报年月多次导入；第二次及以后 updateCount 增加、insertCount 为 0（乡镇均有数据时） |
| 结果反馈 |
返回 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.2.1）；弹窗打开时默认当前年月 |
| 导出范围 |
巴青县全部乡镇（§2.3 合法乡镇，按 order_num 排序），不受列表「所属乡镇」筛选限制 |
| 模板 |
与导入共用：baqing-admin/src/main/resources/templates/yak_outbound_report_import_template.xlsx（业务源文件 牲畜数据.xlsx 第 6 Sheet） |
| 填充规则 |
表头标题、表头「年牲畜出栏数」区块及 Sheet 页签中的年份均替换为所选年份；每个乡镇一行；有该年月填报数据的乡镇填入全部指标；未填报乡镇仅保留乡镇名称，指标为空 |
| 合计行 |
数据区末行输出「合计」，对已填报乡镇的数值列求和；出栏小计（K 列）、自食小计（O 列）由分项加总后写入 |
| 文件格式 |
.xlsx；文件名示例：2026年7月牦牛出栏数据.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 |
| 月份 1～12、不可填未来月 |
§2.2.1 |
| 乡镇 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 |
| 1.2 |
按年月填报：增加 stat_month；唯一键「年+月+乡镇」；每月导入一次；列表/导入/导出支持月份；列表进入不默认年月；新增/导入/导出默认当前年月 |
