牦牛出栏数据填报 — 测试用例
依据：牦牛出栏数据填报功能需求.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+巴青乡 |
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.8.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+本塔乡 |
importYear(2026,file) |
insertCount>=1 |
| ZCZX-MYCNCL-UT-014 |
导入 |
upsert 更新 |
单元测试 |
JUnit5+Mockito |
§5.6 |
已有 2026 各乡镇 |
同一文件再导入 |
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-API-001 |
列表 |
默认分页 |
接口测试 |
Postman |
§5.1 |
已登录；有样本 |
GET /list |
code=200；含所属年份、所属乡镇、农牧户户数、农牧户人数、牦牛出栏数、自食情况（牛） |
| ZCZX-MYCNCL-API-002 |
列表 |
按年份筛选 |
接口测试 |
Postman |
§5.1 |
有 2025、2026 数据 |
statYear=2026 |
仅 2026 |
| 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+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-014 |
导入 |
全量乡镇 |
接口测试 |
Postman |
§5.6 |
空库 2026 |
POST /importData+第 6 Sheet+statYear=2026 |
insertCount=10；failCount=0 |
| ZCZX-MYCNCL-API-015 |
导入 |
覆盖更新 |
接口测试 |
Postman |
§5.6 |
已有 2026 全量 |
改 Excel 一行再导入 |
updateCount>=1 |
| ZCZX-MYCNCL-API-016 |
导入 |
缺填报年份 |
接口测试 |
Postman |
§5.6 |
已登录 |
仅上传文件 |
失败 |
| 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→list→detail |
牦牛出栏数、自食牛与 Excel 一致 |
| ZCZX-MYCNCL-API-021 |
导出 |
按年份导出 |
接口测试 |
Postman/MockMvc |
§5.7 |
有 2026 数据 |
GET /export?statYear=2026 |
200；Content-Type 为 xlsx |
| ZCZX-MYCNCL-API-022 |
导出 |
缺 statYear |
接口测试 |
Postman |
§5.7 |
已登录 |
GET /export 无参 |
失败 |
| ZCZX-MYCNCL-API-023 |
导出 |
非法年份 |
接口测试 |
Postman |
§5.7 |
已登录 |
statYear=1999 |
失败 |
| ZCZX-MYCNCL-API-024 |
权限 |
无 export |
接口测试 |
Postman |
§6 |
无 export |
GET /export?statYear=2026 |
403 |
| ZCZX-MYCNCL-API-025 |
端到端 |
导出-再导入 |
接口测试 |
Postman |
§5.7 |
有 2026 全量 |
导出→改一行→导入 |
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 权限 |
选 2026→上传第 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 |
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.3 乡镇 |
sys_dept 二级 order_num>12 |
UT-002；API-013；UI-006 |
| §5.1 列表 |
6 数据列+操作 |
API-001～004；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～017 |
| §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 |
