# 共同富裕成果年度报告 — 测试用例

> 依据：`共同富裕成果年度报告功能需求.md`、`共同富裕成果年度报告技术方案.md`  
> **接口 Base Path（示例）**：`/commonProsperity/achievementReport`；若含 `context-path` 或网关前缀须补齐。鉴权与若依一致（Cookie / Token）。

**通用前置（无特殊说明）**：具备本模块**查询**权限的账号已登录。**数据依赖**：成果台账表 `biz_common_prosperity_achievement` 已有测试数据。**缺月规则**：1～最大月内无台账月份指标按 **0**；**全年无记录**时 `hasData=false`，`summary=null`，`monthly=[]`。**总览**：取该年**最大统计月**单月值（与大屏一致）。

**界面（UI）测试**：借助 **Playwright** 启动 **Chromium**（与 **Google Chrome 同源内核**）；可配置 `channel: 'chrome'` 调用本机已安装的谷歌浏览器。

---

## 一、单元测试用例

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| GTFY-NB-UT-001 | 参数校验 | statYear 合法 | 单元测试 | JUnit5 | 四位年份 | 无 | `2026`、`2000` 通过 | 校验通过 |
| GTFY-NB-UT-002 | 参数校验 | statYear 非法 | 单元测试 | JUnit5 | 技术方案 §3.3 | 无 | 空、`26`、`20266`、`abcd`、`1899`（若下限 1900） | 校验失败 |
| GTFY-NB-UT-003 | 缺月补零 | 分月序列 | 单元测试 | JUnit5 | §2.2 | Mock 仅 3 月 1 条 | `buildMonthly(2026, rows)` | `monthly` 长度 12；1、2 月指标为 0；3 月为台账值 |
| GTFY-NB-UT-004 | 缺月补零 | 12 月均有数据 | 单元测试 | JUnit5 | 满年 | Mock 12 条 | 组装 monthly | 每月值与台账一致，无 0 误填 |
| GTFY-NB-UT-005 | 年度汇总 | 加总类 SUM | 单元测试 | JUnit5 | §2.4 | 已知 3 月：收入 10、就业 30；其余月 0 | `calcSummary(monthly)` | `collectiveEconomyIncome=10`；`employmentDrivenCount=30` |
| GTFY-NB-UT-006 | 年度汇总 | 比率类均值 | 单元测试 | JUnit5 | ÷12 | 仅 1 月：使用率 0.6；其余 0 | `calcSummary` | `digitalPlatformUsageRate=0.05`（0.6/12） |
| GTFY-NB-UT-007 | 年度汇总 | 多月比率 | 单元测试 | JUnit5 | 缺月=0 参与 | 3 月 0.6、6 月 0.6；其余 0 | `calcSummary` | 使用率 = 1.2/12 = 0.1 |
| GTFY-NB-UT-008 | hasData | 全年无记录 | 单元测试 | JUnit5 | §2.4 空态 | Mock 空列表 | `buildReport(2026, [])` | `hasData=false`；`summary=null` |
| GTFY-NB-UT-009 | hasData | 至少一条 | 单元测试 | JUnit5 | 有数据判定 | Mock 1 条 `2026-05` | `buildReport` | `hasData=true`；`summary` 非 null |
| GTFY-NB-UT-010 | 跨年隔离 | 仅取选定年 | 单元测试 | JUnit5 | §6 | rows 含 `2025-12`、`2026-01` | `selectByStatYear(2026)` 或过滤逻辑 | 仅 `2026-01` 进入 2026 年报 |
| GTFY-NB-UT-011 | 月份映射 | stat_period 解析 | 单元测试 | JUnit5 | YYYY-MM | `stat_period=2026-09` | 解析月份 | `month=9` |
| GTFY-NB-UT-012 | 月份顺序 | monthly 排序 | 单元测试 | JUnit5 | 1→12 | 乱序输入 12、3、1 月 | 输出 monthly | `month` 递增 1～12 |
| GTFY-NB-UT-013 | 可选年份 | distinct years | 单元测试 | JUnit5 | §3.2 | Mock 含 2024、2026 | `listYears()` | 返回 `[2026,2024]` 降序或约定序 |
| GTFY-NB-UT-014 | 边界 | 单月收入为 0 | 单元测试 | JUnit5 | 合法台账 0 | 1 月收入 0、就业 5 | 汇总 | 收入 SUM=0；就业 SUM=5 |
| GTFY-NB-UT-015 | 约束 | 无写操作 | 单元测试 | JUnit5 | 只读模块 | ReportService | 检查无 insert/update/delete 方法暴露 | 仅查询与聚合 |

---

## 二、接口测试用例

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| GTFY-NB-API-001 | 年度报告 | 满年数据查询 | 接口测试 | Postman/curl | 正常流程 | 已登录；2026 年 12 月均有台账 | `GET .../achievementReport?statYear=2026` | `code` 成功；`hasData=true`；`monthly.length=12`；`summary` 各字段与手工核算一致 |
| GTFY-NB-API-002 | 年度报告 | 部分月份有数据 | 接口测试 | Postman | 缺月=0 | 2026 仅 3、6 月有台账 | `statYear=2026` | `hasData=true`；缺月 `monthly` 指标为 0；加总/比率符合 §2.4 |
| GTFY-NB-API-003 | 年度报告 | 全年无数据 | 接口测试 | Postman | §7.2 空态 | 2026 无台账 | `statYear=2026` | `hasData=false`；`summary=null`；`monthly` 仍为 12 条（全 0）或约定结构 |
| GTFY-NB-API-004 | 年度报告 | 未来年份 | 接口测试 | Postman | 边界 | 已登录 | `statYear=2099` | `hasData=false`；`summary=null` |
| GTFY-NB-API-005 | 年度报告 | 缺 statYear | 接口测试 | Postman | 异常 | 已登录 | 不传 `statYear` | 失败；`msg` 提示年份必填或参数错误 |
| GTFY-NB-API-006 | 年度报告 | 非法 statYear | 接口测试 | Postman | 异常 | 已登录 | `statYear=abc` 或 `26` | 失败 |
| GTFY-NB-API-007 | 年度报告 | statYear 回显 | 接口测试 | Postman | 一致性 | 已登录 | `statYear=2025` | `data.statYear=2025` |
| GTFY-NB-API-008 | 年度报告 | 跨年不串数据 | 接口测试 | Postman | §6 | 2025-12、2026-01 各 1 条 | 分别请求 2025、2026 | 各年 `monthly` 仅含对应年月份与数值 |
| GTFY-NB-API-009 | 年度报告 | 比率汇总精度 | 接口测试 | Postman | 月均 ÷12 | 2026 全年使用率均为 0.12 | `GET` 2026 报告 | `summary.digitalPlatformUsageRate`≈0.12（或约定四舍五入） |
| GTFY-NB-API-010 | 年度报告 | monthly 字段齐全 | 接口测试 | Postman | 结构 | 2026 有 1 条 | `GET` 报告 | 每条含 `month`、12 项指标驼峰字段 |
| GTFY-NB-API-011 | 可选年份 | years 列表 | 接口测试 | Postman | §3.2 | 台账含 2024、2026 | `GET .../achievementReport/years` | `years` 含 2024、2026；无数据年不出现 |
| GTFY-NB-API-012 | 可选年份 | 无台账 | 接口测试 | Postman | 边界 | 库空 | `GET .../years` | `years` 为空数组 |
| GTFY-NB-API-013 | 数据联动 | 台账新增后 | 接口测试 | Postman | §6 刷新 | 2026 原无数据 | 先 `POST` 成果 `2026-01`→再 `GET` 报告 | `hasData=true`；1 月有值 |
| GTFY-NB-API-014 | 数据联动 | 台账修改后 | 接口测试 | Postman | 一致性 | 2026-03 收入 10 | `PUT` 改为 20→`GET` 报告 | 3 月收入 20；`summary` 收入同步变 |
| GTFY-NB-API-015 | 数据联动 | 台账删除后 | 接口测试 | Postman | 一致性 | 2026 仅 1 条 | `DELETE` 该条→`GET` 报告 | `hasData=false`（若全年删空） |
| GTFY-NB-API-016 | 鉴权 | 未登录 | 接口测试 | curl | 安全 | 无 Token | `GET .../achievementReport?statYear=2026` | 401 或统一未登录 |
| GTFY-NB-API-017 | 权限 | 无报告权限 | 接口测试 | Postman | 越权 | 无 `achievementReport:query` | `GET` 报告 | 403 或无权限失败 |
| GTFY-NB-API-018 | 权限 | 仅有报告权限 | 接口测试 | Postman | 只读 | 无成果 CRUD 权限 | `GET` 报告成功；`POST` 成果失败 | 报告可读；台账不可写 |
| GTFY-NB-API-019 | 响应 | 失败可读 | 接口测试 | Postman | §7.1 | 已登录 | 触发 API-005、006 | `code`、`msg` 可区分 |
| GTFY-NB-API-020 | 性能 | 单次返回整页 | 接口测试 | Postman | §8 | 2026 满年 | 单次 `GET` 报告 | 响应含 `summary`+`monthly`；无需多接口拼图表 |

---

## 三、界面测试用例（UI）

**测试工具**：**Playwright** + **Chromium**（`channel: 'chrome'` 使用本机 **Google Chrome**）。

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| GTFY-NB-UI-001 | 页面 | 默认进入当前年 | UI 测试 | Playwright+Chrome | §5.1 | 已登录；有报告权限 | 打开「共同富裕成果年度报告」 | 年份控件为当前年；自动加载数据 |
| GTFY-NB-UI-002 | 筛选 | 切换年份刷新 | UI 测试 | Playwright+Chrome | §5.10 | 含 2025、2026 数据 | 年份改 2025→2026 | 总览与全部图表同步更新；无旧年残留 |
| GTFY-NB-UI-003 | 筛选 | 加载中状态 | UI 测试 | Playwright+Chrome | 防闪烁 | 已登录 | 切换年份（可 throttle 网络） | 出现 Loading；完成后展示新数据 |
| GTFY-NB-UI-004 | 空态 | 全年无数据 | UI 测试 | Playwright+Chrome | §7.2 | 选无台账年份 | 进入或切换至该年 | 空态文案；引导至成果台账；**不**展示误导性全 0 总览 |
| GTFY-NB-UI-005 | 总览 | 12 项指标展示 | UI 测试 | Playwright+Chrome | §5.2 | 2026 有数据 | 查看总览区 | 12 项名称与单位正确（万元/人/个/亩/%） |
| GTFY-NB-UI-006 | 总览 | 汇总值正确 | UI 测试 | Playwright+Chrome | §2.4 | 已知台账可手工算 | 对比总览数字与 API/手工 | 加总、比率月均一致 |
| GTFY-NB-UI-007 | 图表 | 集体经济横向柱 | UI 测试 | Playwright+Chrome | §5.4 | 2026 有数据 | 查看该图 | 横轴 12 月；缺月柱为 0 |
| GTFY-NB-UI-008 | 图表 | 就业双折线 | UI 测试 | Playwright+Chrome | §5.5 | 2026 有数据 | 查看就业带动图 | 两条系列；图例区分人数/岗位 |
| GTFY-NB-UI-009 | 图表 | 环境治理柱图 | UI 测试 | Playwright+Chrome | §5.6 | 2026 有数据 | 查看环境治理图 | 12 月柱；缺月为 0 |
| GTFY-NB-UI-010 | 图表 | 绿化折线 | UI 测试 | Playwright+Chrome | §5.7 | 2026 有数据 | 查看绿化建设图 | 折线落点 12 个；缺月为 0 不断线 |
| GTFY-NB-UI-011 | 图表 | 文化传承柱图 | UI 测试 | Playwright+Chrome | §5.8 | 2026 有数据 | 查看文化传承图 | 正常渲染 |
| GTFY-NB-UI-012 | 图表 | 民族团结堆叠柱 | UI 测试 | Playwright+Chrome | §5.9 | 2026 有数据 | 查看民族团结图 | 双系列堆叠；Tooltip 分项显示 |
| GTFY-NB-UI-013 | 图表 | Tooltip | UI 测试 | Playwright+Chrome | §5.3 | 有数据 | 鼠标悬停某月数据点 | 显示该月数值+单位 |
| GTFY-NB-UI-014 | 只读 | 无增删改按钮 | UI 测试 | Playwright+Chrome | §2.5 | 已登录 | 检查页面按钮 | 无新增/编辑/删除；可有刷新 |
| GTFY-NB-UI-015 | 联动 | 台账补录后刷新 | UI 集成 | Playwright+Chrome | §6 | 2026 原空 | 成果台账新增 `2026-01`→回报告页刷新/重选 2026 | 由空态变为有数据；1 月有值 |
| GTFY-NB-UI-016 | 联动 | 台账修改后 | UI 集成 | Playwright+Chrome | 一致性 | 2026-03 已展示 | 成果页改 3 月收入→回报告页 | 总览与 3 月图表更新 |
| GTFY-NB-UI-017 | 权限 | 无菜单权限 | UI 测试 | Playwright+Chrome | §8 | 账号无报告菜单 | 登录查看侧栏 | 不显示「共同富裕成果年度报告」 |
| GTFY-NB-UI-018 | 权限 | 无权限直链 | UI 测试 | Playwright+Chrome | 安全 | 无 query 权限 | `goto` 报告路由 | 403 或跳转无权限页 |
| GTFY-NB-UI-019 | 错误 | 接口失败提示 | UI 测试 | Playwright+Chrome | §7.1 | Mock 500 或断网 | 进入/切换年份 | Message 加载失败；可重试 |
| GTFY-NB-UI-020 | 端到端 | 按年查阅全流程 | UI 集成 | Playwright+Chrome | §4 | 2026 多月数据 | 登录→进报告→默认年→改年→悬停图表 | 总览+6 图正确；无报错 |
| GTFY-NB-UI-021 | 双语 | 藏文切换（若启用） | UI 测试 | Playwright+Chrome | §8 i18n | 系统支持藏文 | 切换语言 | 指标标题与单位切换为藏文 |
| GTFY-NB-UI-022 | 布局 | 区块顺序 | UI 测试 | Playwright+Chrome | §5.10 | 已登录 | 目视/快照 | 年份筛选→总览→各图表顺序与原型一致 |

---

## Playwright 与谷歌浏览器（实施提示）

- 安装：`npm i -D @playwright/test`；`npx playwright install chromium`；`playwright.config` 中 `use: { channel: 'chrome' }` 使用本机 **Google Chrome**。  
- 登录：复用项目 `storageState` 或 `page.fill` 若依登录页。  
- 导航：`page.getByText('共同富裕成果年度报告')` 或 `goto('/commonProsperity/achievementReport')`（以实际路由为准）。  
- 年份：`el-date-picker[type=year]` → `click` 选年；断言 `network` 仅 1 次 `achievementReport?statYear=` 请求（切换年份时）。  
- 空态：`expect(page.getByText(/暂无|无数据|补录/)).toBeVisible()`；`expect(summary区域).not.toContainText('万元')` 或根据实现断言 `hasData` 对应 DOM。  
- 图表：对 ECharts 容器 `locator('.chart-container')` 计数为 6；`page.waitForResponse('**/achievementReport**')`。

---

## 覆盖对照

| 类别 | 单元 UT | 接口 API | 界面 UI |
| --- | --- | --- | --- |
| 正常流程 | UT-003～007、009、011～012 | API-001～002、007～011、013～014、020 | UI-001～003、005～013、015～016、020、022 |
| 异常流程 | UT-002、008 | API-003～006、012、015～019 | UI-004、017～019 |
| 业务约束 | UT-001、005～007、010、014～015 | API-002、008～009、018 | UI-004、006、014、007～012（缺月=0） |

---

## 功能需求追溯（自查）

| 需求章节 | 要点 | 主要对应用例 |
| --- | --- | --- |
| §2.2 缺月=0 | 12 月、缺月 0 | UT-003～005；API-002；UI-007～012 |
| §2.4 汇总口径 | SUM / ÷12 | UT-005～007；API-001、009；UI-006 |
| §2.5 只读 | 无 CRUD | UT-015；API-018；UI-014 |
| §5.1 按年筛选 | statYear | API-005～007；UI-001～003 |
| §5.2 总览 | 12 指标 | API-010；UI-005～006 |
| §5.4～5.9 图表 | 6 类图 | UI-007～012、013 |
| §5.10 整页刷新 | Loading、一致 | API-020；UI-002～003 |
| §6 数据联动 | 台账变更 | API-013～015；UI-015～016 |
| §7 空态/错误 | hasData、失败提示 | UT-008～009；API-003～004；UI-004、019 |
| §8 权限 | 独立 query | API-016～018；UI-017～018 |

---

## 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：单元 15、接口 20、UI 22；缺月=0、hasData 空态；Playwright+Chrome；Base `/commonProsperity/achievementReport` |