# 牦牛出栏数据填报 — 测试用例

> 依据：`牦牛出栏数据填报功能需求.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 |