牦牛出栏数据填报 — 测试用例
依据：牦牛出栏数据填报功能需求.md、牦牛出栏数据填报技术方案.md
接口 Base Path（示例）：/dataModel/yakOutboundReport
模板文件：牲畜数据.xlsx 第 6 个 Sheet（2026 年度出栏及自食统计表）
乡镇样本：巴青乡、江绵乡、岗切乡、雅安镇、拉西镇、本塔乡、杂色镇、贡日乡、玛如乡、阿秀乡（sys_dept，parent_id=100，order_num>12）
通用前置：已登录且具备模块权限；sys_dept 已执行 sql/sys_dept_import_town.sql；测试库无冲突数据或已隔离。
一、单元测试用例
| 用例编号 |
测试模块 |
测试项 |
测试类型 |
测试工具 |
测试目的 |
前置条件 |
测试步骤 |
预期结果 |
| ZCZX-MYCNCL-UT-001 |
年份 |
可选年份范围 |
单元测试 |
JUnit5 |
§2.2 |
固定时钟 2026 |
yearOptions |
返回 2026～2021 共 6 年 |
| ZCZX-MYCNCL-UT-002 |
乡镇 |
字典过滤 |
单元测试 |
JUnit5 |
§2.3 |
Mock dept 表 |
TownDeptSupport.listReportTowns() |
仅 parent_id=100 且 order_num>12 |
| ZCZX-MYCNCL-UT-003 |
校验 |
必填年份乡镇 |
单元测试 |
JUnit5 |
§5.2 |
无 |
validate(row) 缺 statYear |
抛 ServiceException |
| ZCZX-MYCNCL-UT-004 |
校验 |
负数拒绝 |
单元测试 |
JUnit5 |
§2.4 |
无 |
yakOutboundCount=-1 |
校验失败 |
| ZCZX-MYCNCL-UT-005 |
唯一性 |
同年同月同乡镇 |
单元测试 |
JUnit5+Mockito |
§5.2 |
已存在 2026-05+巴青乡 |
insert 同键 |
失败「该年该月该乡镇已填报」 |
| ZCZX-MYCNCL-UT-006 |
新增 |
新增成功 |
单元测试 |
JUnit5+Mockito |
§5.2 |
无同年同月同乡镇 |
insert 最小必填 |
成功 |
| ZCZX-MYCNCL-UT-007 |
导入解析 |
识别第 6 Sheet |
单元测试 |
JUnit5 |
§5.6 |
牲畜数据.xlsx |
getSheetAt(5) |
Sheet 标题含「出栏及自食」 |
| ZCZX-MYCNCL-UT-008 |
导入解析 |
识别表头行 |
单元测试 |
JUnit5 |
§3.9.1 |
模板 |
detectHeaderRow |
定位含「乡镇」「户数」表头 |
| ZCZX-MYCNCL-UT-009 |
导入解析 |
乡镇名匹配 |
单元测试 |
JUnit5 |
§5.6 |
行「杂色镇」 |
resolveTownDeptId |
返回对应 dept_id |
| ZCZX-MYCNCL-UT-010 |
导入解析 |
扎色镇别名 |
单元测试 |
JUnit5 |
§8 |
行「扎色镇」 |
resolveTownDeptId |
映射为「杂色镇」dept_id |
| ZCZX-MYCNCL-UT-011 |
导入解析 |
跳过合计行 |
单元测试 |
JUnit5 |
§5.6 |
含「合计」行 |
parseRows |
不写入合计 |
| ZCZX-MYCNCL-UT-012 |
导入解析 |
列映射 |
单元测试 |
JUnit5 |
§5.6 |
巴青乡样本行 |
解析 |
yakOutboundCount、selfConsumptionCattleCount 等与模板一致 |
| ZCZX-MYCNCL-UT-013 |
导入 |
upsert 新增 |
单元测试 |
JUnit5+Mockito |
§5.6 |
DB 无 2026-05+本塔乡 |
importData(2026,5,file) |
insertCount>=1 |
| ZCZX-MYCNCL-UT-014 |
导入 |
upsert 更新 |
单元测试 |
JUnit5+Mockito |
§5.6 |
已有 2026-05 各乡镇 |
同一文件再导入 |
updateCount=10；insertCount=0 |
| ZCZX-MYCNCL-UT-015 |
修改 |
记录不存在 |
单元测试 |
JUnit5+Mockito |
§5.3 |
id 不存在 |
update |
抛 ServiceException |
| ZCZX-MYCNCL-UT-016 |
删除 |
物理删除 |
单元测试 |
JUnit5+Mockito |
§5.4 |
有效 id |
deleteByIds |
调用 Mapper 物理删除；无 del_flag 更新 |
| ZCZX-MYCNCL-UT-017 |
数据权限 |
乡镇账号过滤 |
单元测试 |
JUnit5+Mockito |
§6 |
用户 dept=杂色镇 |
selectList |
仅本乡镇 |
| ZCZX-MYCNCL-UT-018 |
警告 |
自食大于出栏 |
单元测试 |
JUnit5 |
§2.4 |
自食牛>牦牛出栏 |
校验/导入 |
允许保存；warnMessages 含提示 |
| ZCZX-MYCNCL-UT-019 |
导出 |
按年月填充模板 |
单元测试 |
JUnit5 |
§5.7 |
模板+1 乡镇样本 |
YakOutboundReportExcelExporter.export |
返回 xlsx；解析含对应出栏数 |
| ZCZX-MYCNCL-UT-020 |
导出 |
全县乡镇行数 |
单元测试 |
JUnit5 |
§5.7 |
10 乡镇字典 |
export(2026, towns, map) |
解析 10 数据行；无样例残留数据 |
| ZCZX-MYCNCL-UT-021 |
月份 |
未来月拒绝 |
单元测试 |
JUnit5 |
§2.2.1 |
当前年 |
validateStatPeriod(2026, 未来月) |
抛 ServiceException |
| ZCZX-MYCNCL-UT-022 |
月份 |
月份选项 |
单元测试 |
JUnit5 |
§2.2.1 |
无 |
resolveMonthOptions() |
返回 1～12 |
二、接口测试用例
| 用例编号 |
测试模块 |
测试项 |
测试类型 |
测试工具 |
测试目的 |
前置条件 |
测试步骤 |
预期结果 |
| ZCZX-MYCNCL-API-001 |
列表 |
默认分页 |
接口测试 |
Postman |
§5.1 |
已登录；有样本 |
GET /list |
code=200；含所属年份、所属月份、所属乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食情况（牛） |
| ZCZX-MYCNCL-API-002 |
列表 |
按年份筛选 |
接口测试 |
Postman |
§5.1 |
有 2025、2026 数据 |
statYear=2026 |
仅 2026 |
| ZCZX-MYCNCL-API-002a |
列表 |
按年月筛选 |
接口测试 |
Postman |
§5.1 |
同 year 多 month |
statYear=2026&statMonth=5 |
仅 2026 年 5 月 |
| ZCZX-MYCNCL-API-003 |
列表 |
按乡镇筛选 |
接口测试 |
Postman |
§5.1 |
已知 dept_id |
townDeptId= |
仅该乡镇 |
| ZCZX-MYCNCL-API-004 |
列表 |
组合筛选 |
接口测试 |
Postman |
§5.1 |
已登录 |
年+月+乡镇 |
交集结果 |
| ZCZX-MYCNCL-API-005 |
详情 |
指定七字段 |
接口测试 |
Postman |
§5.5 |
有效 id |
GET /{id} |
含年份、月份、乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食牛头数 |
| ZCZX-MYCNCL-API-006 |
新增 |
必填成功 |
接口测试 |
Postman |
§5.2 |
无重复 |
POST 含 statYear+statMonth+townDeptId |
成功 |
| ZCZX-MYCNCL-API-007 |
新增 |
缺年份 |
接口测试 |
Postman |
§5.2 |
已登录 |
缺 statYear |
失败 |
| ZCZX-MYCNCL-API-008 |
新增 |
缺乡镇 |
接口测试 |
Postman |
§5.2 |
已登录 |
缺 townDeptId |
失败 |
| ZCZX-MYCNCL-API-009 |
新增 |
重复同年月乡镇 |
接口测试 |
Postman |
§5.2 |
已有记录 |
再 POST 同键 |
失败 |
| ZCZX-MYCNCL-API-010 |
修改 |
更新出栏指标 |
接口测试 |
Postman |
§5.3 |
有效 id |
PUT 改 yakOutboundCount、绵羊出栏等 |
成功；详情/列表为新值 |
| ZCZX-MYCNCL-API-011 |
删除 |
物理删除 |
接口测试 |
Postman |
§5.4 |
有效 id |
DELETE /{id} |
成功；库中无该记录 |
| ZCZX-MYCNCL-API-012 |
下拉 |
年份选项 |
接口测试 |
Postman |
§2.2 |
已登录 |
GET /yearOptions |
6 个年份 |
| ZCZX-MYCNCL-API-013 |
下拉 |
乡镇选项 |
接口测试 |
Postman |
§2.3 |
已登录 |
GET /townOptions |
10 个乡镇 |
| ZCZX-MYCNCL-API-013a |
下拉 |
月份选项 |
接口测试 |
Postman |
§2.2.1 |
已登录 |
GET /monthOptions |
1～12 |
| ZCZX-MYCNCL-API-014 |
导入 |
全量乡镇 |
接口测试 |
Postman |
§5.6 |
空库 2026-05 |
POST /importData+第 6 Sheet+statYear=2026&statMonth=5 |
insertCount=10；failCount=0 |
| ZCZX-MYCNCL-API-015 |
导入 |
覆盖更新 |
接口测试 |
Postman |
§5.6 |
已有 2026-05 全量 |
改 Excel 一行再导入 |
updateCount>=1 |
| ZCZX-MYCNCL-API-016 |
导入 |
缺填报年月 |
接口测试 |
Postman |
§5.6 |
已登录 |
仅上传文件或缺 statMonth |
失败 |
| ZCZX-MYCNCL-API-017 |
导入 |
非 xlsx |
接口测试 |
Postman |
§5.6 |
已登录 |
上传 .csv |
失败 |
| ZCZX-MYCNCL-API-018 |
权限 |
无 add |
接口测试 |
Postman |
§6 |
仅 list 角色 |
POST / |
403 |
| ZCZX-MYCNCL-API-019 |
权限 |
无 import |
接口测试 |
Postman |
§6 |
无 import |
POST /importData |
403 |
| ZCZX-MYCNCL-API-020 |
端到端 |
导入-查-详情 |
接口测试 |
Postman |
§4 |
空库 |
导入 2026-05→list→detail |
牦牛出栏数、自食牛与 Excel 一致 |
| ZCZX-MYCNCL-API-021 |
导出 |
按年月导出 |
接口测试 |
Postman/MockMvc |
§5.7 |
有 2026-05 数据 |
GET /export?statYear=2026&statMonth=5 |
200；xlsx |
| ZCZX-MYCNCL-API-022 |
导出 |
缺 statMonth |
接口测试 |
Postman |
§5.7 |
已登录 |
GET /export?statYear=2026 |
失败 |
| ZCZX-MYCNCL-API-023 |
导出 |
非法年份 |
接口测试 |
Postman |
§5.7 |
已登录 |
statYear=1999 |
失败 |
| ZCZX-MYCNCL-API-024 |
权限 |
无 export |
接口测试 |
Postman |
§6 |
无 export |
GET /export?statYear=2026&statMonth=5 |
403 |
| ZCZX-MYCNCL-API-025 |
端到端 |
导出-再导入 |
接口测试 |
Postman |
§5.7 |
有 2026-05 全量 |
导出→改一行→导入 |
upsert 成功 |
三、界面测试用例（UI）
工具：Playwright + Chrome（与项目其他模块一致）。
| 用例编号 |
测试模块 |
测试项 |
测试类型 |
测试工具 |
测试目的 |
前置条件 |
测试步骤 |
预期结果 |
| ZCZX-MYCNCL-UI-001 |
列表 |
默认加载 |
UI 测试 |
Playwright |
§5.1 |
有数据 |
进入菜单 |
列含所属年份、所属月份、乡镇…；年月筛选为空 |
| ZCZX-MYCNCL-UI-002 |
列表 |
年月乡镇筛选 |
UI 测试 |
Playwright |
§5.1 |
有数据 |
选择后搜索 |
结果正确 |
| ZCZX-MYCNCL-UI-003 |
列表 |
重置 |
UI 测试 |
Playwright |
§5.1 |
已筛选 |
点重置 |
条件清空 |
| ZCZX-MYCNCL-UI-004 |
新增 |
必填校验 |
UI 测试 |
Playwright |
§5.2 |
有 add 权限 |
不选乡镇提交 |
表单提示 |
| ZCZX-MYCNCL-UI-005 |
新增 |
年份下拉 6 项 |
UI 测试 |
Playwright |
§2.2 |
打开表单 |
查看年份下拉 |
当年起前 5 年 |
| ZCZX-MYCNCL-UI-006 |
新增 |
乡镇下拉 |
UI 测试 |
Playwright |
§2.3 |
打开表单 |
查看乡镇下拉 |
10 个乡镇 |
| ZCZX-MYCNCL-UI-007 |
新增 |
全指标可填 |
UI 测试 |
Playwright |
§5.3 |
打开表单 |
填写绵羊/山羊出栏等 |
可保存 |
| ZCZX-MYCNCL-UI-008 |
修改 |
回显保存 |
UI 测试 |
Playwright |
§5.3 |
有记录 |
修改牦牛出栏数保存 |
列表更新 |
| ZCZX-MYCNCL-UI-009 |
删除 |
二次确认 |
UI 测试 |
Playwright |
§5.4 |
有记录 |
删除确认 |
行消失 |
| ZCZX-MYCNCL-UI-010 |
详情 |
七字段只读 |
UI 测试 |
Playwright |
§5.5 |
有完整数据 |
点查看 |
展示年份、月份、乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食情况（牛） |
| ZCZX-MYCNCL-UI-011 |
导入 |
选年月上传 |
UI 测试 |
Playwright |
§5.6 |
有 import 权限 |
默认当前年月→上传第 6 Sheet |
成功摘要 |
| ZCZX-MYCNCL-UI-012 |
导入 |
未选月份 |
UI 测试 |
Playwright |
§5.6 |
有 import 权限 |
缺月份提交 |
表单校验失败 |
| ZCZX-MYCNCL-UI-013 |
权限 |
无导入按钮 |
UI 测试 |
Playwright |
§6 |
无 import |
进入页面 |
无导入入口 |
| ZCZX-MYCNCL-UI-014 |
端到端 |
导入后列表 |
UI 集成 |
Playwright |
§4 |
空库 |
导入→筛选 2026-05 |
10 行乡镇数据 |
| ZCZX-MYCNCL-UI-015 |
导出 |
按年月导出 |
UI 测试 |
Playwright |
§5.7 |
有 export 权限 |
选年月导出 |
下载 {年}年{月}月牦牛出栏数据.xlsx |
| ZCZX-MYCNCL-UI-016 |
导出 |
未选月份 |
UI 测试 |
Playwright |
§5.7 |
有 export 权限 |
缺月份点导出 |
表单校验失败 |
| ZCZX-MYCNCL-UI-017 |
权限 |
无导出按钮 |
UI 测试 |
Playwright |
§6 |
无 export |
进入页面 |
无导出入口 |
四、覆盖对照
| 需求章节 |
要点 |
主要用例 |
| §2.2 年份 |
向前 5 年 |
UT-001；API-012；UI-005 |
| §2.2.1 月份 |
1～12、非未来月 |
UT-021～022；API-013a |
| §2.3 乡镇 |
sys_dept 二级 order_num>12 |
UT-002；API-013；UI-006 |
| §5.1 列表 |
7 数据列+操作；默认不筛年月 |
API-001～004、002a；UI-001～003 |
| §5.2～5.4 CRUD |
必填、唯一、物理删除 |
UT-003～006、015～016；API-006～011 |
| §5.5 详情 |
七字段（含月份） |
API-005；UI-010 |
| §5.6 导入 |
第 6 Sheet |
UT-007～014；API-014～017；UI-011～012 |
| §5.7 导出 |
按年月全县乡镇 |
UT-019～020；API-021～025；UI-015～016 |
| §6 权限 |
按钮级 |
API-018～019、024；UI-013、017 |
| §8 扎色镇别名 |
导入映射 |
UT-010 |
五、修订记录
| 版本 |
说明 |
| 1.0 |
初版：单元 18、接口 20、UI 14；编号前缀 ZCZX-MYCNCL |
| 1.1 |
补充按年份导出用例 UT-019～020、API-021～025、UI-015～017 |
| 1.2 |
按年月填报：UT-005/021～022；API-002a/013a/014/021～022；UI 年月筛选与导出；唯一键改为年+月+乡镇 |
