# 大屏 — 共同富裕统计 — 测试用例

> 依据：`大屏共同富裕功能需求.md`（v1.1）、`大屏共同富裕技术方案.md`  
> **接口 Base Path**：`/bigScreen/commonProsperity`（含 `context-path`、网关前缀须补齐）。鉴权：若依 Cookie / `Authorization` Token；权限 `bigScreen:commonProsperity:query`。

**成果口径（图表）**：`achievement.monthly` 为**滚动最近 12 月**；含 `statYear`+`month`；**不**随 **Y**；缺月 **0**。**总览** `summary` 仍按 **Y** 全年汇总。

**UI 测试**：**Playwright** + **Chromium**，`playwright.config` 中 `use: { channel: 'chrome' }` 调用本机 **Google Chrome**。

---

## 测试数据样本

| 代号 | 说明 |
| --- | --- |
| **ACH-Y** | 统计年 **Y** 成果台账；如 `ACH-2026` 仅 `2026-03`、`2026-08` 各 1 条 |
| **ACH-EMPTY** | 某年无任何成果记录 |
| **PRJ-PUB-A** | 已发布；实施 `2025-01-01`～`2027-12-31`；`project_type=1`；含 2 张运营图 |
| **PRJ-PUB-B** | 已发布；实施 `2026-06-01`～`2026-12-31`；`project_type=2`；含视频+封面 |
| **PRJ-UNPUB** | `publish_status=0` |
| **PRJ-OFF** | 曾发布已下架 `publish_status=0` 且 `offline_time` 非空 |
| **PRJ-OUT** | 已发布；实施 `2024-01-01`～`2024-12-31`（与 **2026** 无交集） |
| **PRJ-EDGE** | 已发布；实施 `2026-01-01`～`2026-12-31`（边界交集） |

---

## 一、单元测试用例

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DP-GTFY-UT-001 | 参数校验 | statYear 合法 | 单元测试 | JUnit5 | 复用年度报告校验 | 无 | 传入 `2026`、`2000` | 解析通过 |
| DP-GTFY-UT-002 | 参数校验 | statYear 非法 | 单元测试 | JUnit5 | 异常入参 | 无 | 空、`26`、`abcd`、`1899` | 抛 `ServiceException` 或等价失败 |
| DP-GTFY-UT-003 | 成果聚合 | 复用 Aggregator 缺月 | 单元测试 | JUnit5 | 禁止大屏另写汇总 | Mock 2026 仅 3 月 1 条 | 调 `getAnnualReport(2026)` | `monthly` 长度 12；非 3 月指标为 0 |
| DP-GTFY-UT-004 | 成果聚合 | hasData 与 summary | 单元测试 | JUnit5 | §7.1 | Mock 空列表 | `buildReport(2026,[])` | `hasData=false`；`summary=null` |
| DP-GTFY-UT-005 | 成果聚合 | 比率十二月均 | 单元测试 | JUnit5 | §2.4 | 仅 6 月使用率 0.6 | `calcSummary` | `digitalPlatformUsageRate=0.05` |
| DP-GTFY-UT-006 | 项目筛选 | 实施周期交集 | 单元测试 | JUnit5 | §2.6 | 造 PRJ-PUB-A、PRJ-OUT、PRJ-EDGE | `filterByStatYear(2026)` | 含 A、EDGE；不含 OUT |
| DP-GTFY-UT-007 | 项目筛选 | 未发布/已下架排除 | 单元测试 | JUnit5 | §2.6、DP-10 | 含 PRJ-UNPUB、PRJ-OFF、PRJ-PUB-B | `filterByStatYear(2026)` | 仅 PUB-B（及满足交集的其他已发布项） |
| DP-GTFY-UT-008 | 项目筛选 | 边界日期含端点 | 单元测试 | JUnit5 | 交集边界 | `impl_start=2026-12-31`、`impl_end=2026-01-01` 各 1 条已发布 | `filterByStatYear(2026)` | 两条均纳入 |
| DP-GTFY-UT-009 | 分类统计 | 占比计算 | 单元测试 | JUnit5 | §5.10 | 类型 1×2、2×1、3×0 | `buildTypeStats` | count 2/1/0；ratio 2/3、1/3、0；合计 ratio≈1 |
| DP-GTFY-UT-010 | 分类统计 | 无项目固定三类 | 单元测试 | JUnit5 | §7.2 | 筛选结果空 | `buildTypeStats` | 返回 3 项；`count=0`、`ratio=0` |
| DP-GTFY-UT-011 | 可选年份 | 并集含当前年 | 单元测试 | JUnit5 | 年份下拉 | Mock 成果年 `[2025]`、项目年 `[]`；当前年 2026 | `buildAvailableYears` | 列表含 `2026`（当前年） |
| DP-GTFY-UT-012 | 列表排序 | 发布时间倒序 | 单元测试 | JUnit5 | §5.11.1 | 同类型两条 `publish_time` 不同 | `sortProjects` | 时间晚者在前 |
| DP-GTFY-UT-013 | 运营图 | 按 sort_order 组装 | 单元测试 | JUnit5 | §3.2.1 | 项目 2 张图 order 2、1 | `attachOpImages` | 输出顺序 1→2 |
| DP-GTFY-UT-014 | 看板编排 | 仅项目无成果 | 单元测试 | JUnit5 | §7.2 | Mock 成果空、项目 1 条 | `loadDashboard(2026)` | `achievement.hasData=false`；`hasProjectData=true` |
| DP-GTFY-UT-015 | 看板编排 | 仅成果无项目 | 单元测试 | JUnit5 | §7.2 | Mock 成果 1 条、项目空 | `loadDashboard(2026)` | `achievement.hasData=true`；`hasProjectData=false` |
| DP-GTFY-UT-016 | 约束 | 无写接口 | 单元测试 | JUnit5 | 只读 | 检查 ScreenService/Controller | 无 insert/update/delete | 仅查询与组装 |
| DP-GTFY-UT-017 | 约束 | 无详情接口定义 | 单元测试 | JUnit5 | §5.11 | 检查 Controller 映射 | 无 `GET .../{id}` 大屏详情 | 仅 dashboard、projects |
| DP-GTFY-UT-018 | 缓存 | forceRefresh 跳过 | 单元测试 | JUnit5 | 技术§2.3 可选 | 启用缓存且未过期 | `loadDashboard(2026,true)` | 不走缓存、重新查库 |

---

## 二、接口测试用例

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DP-GTFY-API-001 | 看板 | 满年成果+项目 | 接口测试 | Postman/curl | 正常流程 DP-01 | 已登录；2026 成果多月+已发布项目 | `GET .../dashboard?statYear=2026` | `code` 成功；`achievement.hasData=true`；`monthly.length=12`；`hasProjectData=true`；`projectTypeStats` 有数据 |
| DP-GTFY-API-002 | 看板 | 滚动 12 月缺月补零 | 接口测试 | Postman | DP-03 | ACH-2026 仅 3、8 月 | `statYear=2026` | `monthly` 含 `statYear`、`month`；缺槽 0；**不**随 **Y** 变窗口 |
| DP-GTFY-API-003 | 看板 | 全年无成果 | 接口测试 | Postman | DP-04 | 2026 ACH-EMPTY | `GET dashboard` | `achievement.hasData=false`；`summary=null`；`monthly` 仍 12 条全 0 |
| DP-GTFY-API-004 | 看板 | 仅项目无成果 | 接口测试 | Postman | §7.2 | 2026 无成果；有 PRJ-PUB-B | `GET dashboard` | `achievement.hasData=false`；`hasProjectData=true`；饼图 stats 正常 |
| DP-GTFY-API-005 | 看板 | 仅成果无项目 | 接口测试 | Postman | §7.2 | 2026 有 ACH；无符合交集项目 | `GET dashboard` | `achievement.hasData=true`；`hasProjectData=false`；`projectTypeStats` 三项 count=0 |
| DP-GTFY-API-006 | 看板 | 比率汇总 | 接口测试 | Postman | DP-05 | 2026 全年使用率均为 0.12 | `GET dashboard` | `summary.digitalPlatformUsageRate`≈0.12；`brandPremiumRate` 同理 |
| DP-GTFY-API-007 | 看板 | 缺 statYear | 接口测试 | Postman | 异常 | 已登录 | 不传 `statYear` | 失败；`msg` 提示参数错误 |
| DP-GTFY-API-008 | 看板 | 非法 statYear | 接口测试 | Postman | 异常 | 已登录 | `statYear=abc` | 失败 |
| DP-GTFY-API-009 | 看板 | statYear 回显 | 接口测试 | Postman | 一致性 | 已登录 | `statYear=2025` | `data.statYear=2025` |
| DP-GTFY-API-010 | 看板 | availableYears | 接口测试 | Postman | §5.1 | 成果 2025、项目交集 2026 | `GET dashboard` | `availableYears` 含 2025、2026、当前年；降序 |
| DP-GTFY-API-011 | 看板 | 分类占比之和 | 接口测试 | Postman | DP-07 | 2026 三类项目共 6 个 | `GET dashboard` | `sum(ratio)`≈1（±0.01）；count 之和=6 |
| DP-GTFY-API-012 | 看板 | 未发布项目不计 | 接口测试 | Postman | 业务约束 | 仅 PRJ-UNPUB | `GET dashboard` 2026 | `hasProjectData=false` 或 stats 全 0 |
| DP-GTFY-API-013 | 看板 | 下架项目不计 | 接口测试 | Postman | DP-10 | PRJ-OFF 曾计入、下架后 | 下架→`GET dashboard` | 分类与列表均不含该项目 |
| DP-GTFY-API-014 | 看板 | 实施年无交集排除 | 接口测试 | Postman | §2.6 | PRJ-OUT + PRJ-PUB-B | `statYear=2026` | stats/list 不含 OUT；含 B |
| DP-GTFY-API-015 | 看板 | forceRefresh | 接口测试 | Postman | 技术§3.1 | 已启用缓存 | `?statYear=2026&forceRefresh=true` | 成功；数据与库一致 |
| DP-GTFY-API-016 | 项目列表 | 分页首页 | 接口测试 | Postman | DP-08 | 2026 ≥9 条已发布项目 | `GET .../projects?statYear=2026&pageNum=1&pageSize=8` | `rows.length≤8`；`total` 正确 |
| DP-GTFY-API-017 | 项目列表 | 第二页 | 接口测试 | Postman | 分页 | 同上 | `pageNum=2` | 与第一页 `id` 不重复；顺序 `publish_time` 倒序 |
| DP-GTFY-API-018 | 项目列表 | 行内字段齐全 | 接口测试 | Postman | §5.11.2 | PRJ-PUB-B 有图视封面 | `GET projects` | 每条含 type、name、intro、content、周期、cover、video、operationImages |
| DP-GTFY-API-019 | 项目列表 | 全年无项目 | 接口测试 | Postman | §5.11.3 | 2026 无符合项目 | `GET projects` | `rows=[]`；`total=0` |
| DP-GTFY-API-020 | 项目列表 | 缺 statYear | 接口测试 | Postman | 异常 | 已登录 | 不传 `statYear` | 失败 |
| DP-GTFY-API-021 | 范围 | 无大屏详情接口 | 接口测试 | Postman | §5.11 | 已登录 | `GET .../bigScreen/commonProsperity/1` 或 `/project/1` | 404/405 |
| DP-GTFY-API-022 | 范围 | 无维护接口 | 接口测试 | Postman | §3.2 | 已登录 | `POST/PUT/DELETE .../bigScreen/commonProsperity/**` | 404/405 或无权限 |
| DP-GTFY-API-023 | 联动 | 成果补录后 | 接口测试 | Postman | DP-09 | 2026 原 ACH-EMPTY | 后台新增 `2026-01` 成果→`GET dashboard` | `hasData=true`；1 月有值 |
| DP-GTFY-API-024 | 联动 | 项目发布后 | 接口测试 | Postman | DP-09 | 2026 原无项目 | 后台发布 PRJ-EDGE→`GET dashboard`+`projects` | `hasProjectData=true`；列表可见 |
| DP-GTFY-API-025 | 鉴权 | 未登录 | 接口测试 | curl | 安全 | 无 Token | `GET dashboard` | 401 或统一未登录 |
| DP-GTFY-API-026 | 权限 | 无大屏权限 | 接口测试 | Postman | 越权 | 无 `bigScreen:commonProsperity:query` | `GET dashboard`、`GET projects` | 403 或无权限 |
| DP-GTFY-API-027 | 权限 | 有大屏无成果写 | 接口测试 | Postman | 只读 | 仅有 query | `GET` 成功；`POST /commonProsperity/achievement` 失败 | 大屏可读；台账不可写 |
| DP-GTFY-API-028 | 一致性 | 切年数据不串 | 接口测试 | Postman | DP-02 | 2025、2026 各不同数据 | 分别 `statYear=2025/2026` | 各年 `monthly`/项目集合互不混入 |

---

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

| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DP-GTFY-UI-001 | 页面 | 默认当前年加载 | UI 测试 | Playwright+Chrome | DP-01 | 已登录；有权限；有当前年数据 | 打开「大屏共同富裕」路由 | 年份为当前自然年；自动请求 dashboard+projects；各区块同年 |
| DP-GTFY-UI-002 | 筛选 | 切换年份整页刷新 | UI 测试 | Playwright+Chrome | DP-02、§5.1 | 含 2025、2026 数据 | 年份 2025→2026 | 成果区、图表、饼图、列表同步更新；无 2025 残留数字 |
| DP-GTFY-UI-003 | 筛选 | 加载中防残留 | UI 测试 | Playwright+Chrome | §7.3 | 已登录 | 切换年份（可 `route.fulfill` 延迟） | 出现 Loading/遮罩；完成后仅新年数据 |
| DP-GTFY-UI-004 | 空态 | 全年无成果 | UI 测试 | Playwright+Chrome | DP-04、§7.1 | 选 ACH-EMPTY 年 | 进入或切换该年 | 总览/图表/数字赋能空态文案；**不**显示全 0 汇总卡片 |
| DP-GTFY-UI-005 | 空态 | 无项目有成果 | UI 测试 | Playwright+Chrome | §7.2 | 2026 有成果无项目 | 打开 2026 | 图表正常；饼图空态；列表「本年度暂无共富项目」 |
| DP-GTFY-UI-006 | 总览 | 指标与单位 | UI 测试 | Playwright+Chrome | §5.2 | 2026 有成果 | 查看共富成果卡片区 | 名称/数值/单位正确（万元、人、个、亩）；比率显示 **%** |
| DP-GTFY-UI-007 | 图表 | 集体经济横向柱滚动 12 月 | UI 测试 | Playwright+Chrome | §5.3、DP-03 | ACH-2026 缺月 | 查看该图+悬停 | 12 刻度**仅月份**；悬停显 **YYYY年M月**+万元 |
| DP-GTFY-UI-008 | 图表 | 就业双系列 | UI 测试 | Playwright+Chrome | DP-06、§5.4 | 2026 有数据 | 查看就业带动图 | 两图例/两色系；Tooltip 区分人数与岗位 |
| DP-GTFY-UI-009 | 图表 | 环境治理/文化传承柱图 | UI 测试 | Playwright+Chrome | §5.5、§5.8 | 2026 有数据 | 查看两图 | 12 月；缺月为 0 |
| DP-GTFY-UI-010 | 图表 | 绿化折线 | UI 测试 | Playwright+Chrome | §5.6 | 2026 有数据 | 查看绿化建设 | 12 落点；缺月 0 不断线 |
| DP-GTFY-UI-011 | 图表 | 民族团结堆叠 | UI 测试 | Playwright+Chrome | DP-06、§5.9 | 2026 有数据 | 悬停某月 | 堆叠柱；Tooltip **分别**显示融合项目数、活动数 |
| DP-GTFY-UI-012 | 数字赋能 | 三指标展示 | UI 测试 | Playwright+Chrome | §5.7、DP-05 | 2026 有成果 | 查看数字赋能区 | 品牌数（加总）、溢价率/使用率（%）；与 API `summary` 一致 |
| DP-GTFY-UI-013 | 数字赋能 | 无成果空态 | UI 测试 | Playwright+Chrome | §5.7 | ACH-EMPTY 年 | 切换至该年 | 不展示 0% / 0 品牌误导数据 |
| DP-GTFY-UI-014 | 项目分类 | 饼图与图例 | UI 测试 | Playwright+Chrome | §5.10、DP-07 | 三类均有项目 | 查看饼图 | 三类名称与列表标签色一致；占比之和 100% |
| DP-GTFY-UI-015 | 项目分类 | 无项目空态 | UI 测试 | Playwright+Chrome | §7.2 | 2026 无符合项目 | 查看饼图区 | 空态；**无**单类 100% 假象 |
| DP-GTFY-UI-016 | 项目列表 | 行内信息完整 | UI 测试 | Playwright+Chrome | DP-08、§5.11.2 | PRJ-PUB-B 在列 | 查看列表行 | 类型、名称、简介、内容、周期、封面、视频、运营图可见 |
| DP-GTFY-UI-017 | 项目列表 | 无二级详情页 | UI 测试 | Playwright+Chrome | §5.11 | 列表有「详情」文案（若有） | 点击详情/名称 | **不**跳转路由/新 Tab；仅行内展开或浮层 |
| DP-GTFY-UI-018 | 项目列表 | 分页翻页 | UI 测试 | Playwright+Chrome | §5.11.1 | ≥9 条项目；pageSize=8 | 点下一页 | 仅列表区刷新；`waitForResponse('**/projects**')`；成果区不变 |
| DP-GTFY-UI-019 | 只读 | 无维护按钮 | UI 测试 | Playwright+Chrome | §3.2 | 已登录 | 扫描页面 | 无新增/编辑/删除/发布；可有刷新 |
| DP-GTFY-UI-020 | 错误 | 接口失败可重试 | UI 测试 | Playwright+Chrome | §7.3 | Mock dashboard 500 | 进入或切年 | 失败提示；可点重试；不长期半屏旧数据 |
| DP-GTFY-UI-021 | 联动 | 后台发布后刷新 | UI 集成 | Playwright+Chrome | DP-09 | 2026 列表原空 | 后台发布项目→大屏 F5 或重进 | 饼图与列表出现新项目 |
| DP-GTFY-UI-022 | 联动 | 下架后不可见 | UI 集成 | Playwright+Chrome | DP-10 | 列表曾显示某项目 | 后台下架→刷新大屏 | 饼图与列表均移除 |
| DP-GTFY-UI-023 | 权限 | 无菜单不可进 | UI 测试 | Playwright+Chrome | 安全 | 账号无大屏菜单 | 登录查侧栏 | 无「大屏共同富裕」；直链路由 403/无权限页 |
| DP-GTFY-UI-024 | 端到端 | 按年查阅全流程 | UI 集成 | Playwright+Chrome | §4、DP-01～08 | 2026 完整样本 | 登录→进大屏→默认年→改年→悬停图表→翻页 | 十区块数据正确；无控制台报错 |
| DP-GTFY-UI-025 | 刷新 | 手动/定时刷新 | UI 测试 | Playwright+Chrome | §7.4 | 已打开页；后台改成果 | 点击刷新或等待轮播周期 | 数据更新为最新（允许 1～5 分钟延迟配置） |

---

## Playwright 实施提示

```javascript
// playwright.config.ts 片段
use: { channel: 'chrome', headless: false }

// 登录后 storageState
await page.goto('/#/bigScreen/commonProsperity/index'); // 以实际路由为准

// 切年：监听双请求同成败
const [dash, proj] = await Promise.all([
  page.waitForResponse('**/bigScreen/commonProsperity/dashboard**'),
  page.waitForResponse('**/bigScreen/commonProsperity/projects**'),
  yearPicker.selectOption('2026'),
]);

// 空态
await expect(page.getByText(/暂无.*成果|请.*共同富裕成果/)).toBeVisible();

// 图表容器数量（按页面实现调整）
await expect(page.locator('[data-chart]')).toHaveCount(6); // 集体经济/就业/环境/绿化/文化/民族团结
```

---

## 覆盖对照

| 类别 | 单元 UT | 接口 API | 界面 UI |
| --- | --- | --- | --- |
| 正常流程 | UT-003～005、009、012～015 | API-001～002、006、010～011、016～018、023～024 | UI-001～002、006～012、014、016、018、024 |
| 异常流程 | UT-002、004 | API-003、007～008、019～020、025～026 | UI-004、020、023 |
| 业务约束 | UT-006～010、016～017 | API-004～005、012～014、021～022、028 | UI-004～005、013、015、017、019、022 |

---

## 功能需求追溯（DP / 章节）

| 追溯 | 要点 | 主要用例 |
| --- | --- | --- |
| DP-01 | 默认当前年 | UI-001；API-001 |
| DP-02 | 切年一致 | API-028；UI-002～003 |
| DP-03 | 滚动 12 月缺月=0 | UT-003；API-002；UI-007～011 |
| DP-04 | 无成果空态 | UT-004；API-003；UI-004、013 |
| DP-05 | 比率 % | UT-005；API-006；UI-006、012 |
| DP-06 | 双系列图 | UI-008、011 |
| DP-07 | 项目分类 | UT-009～010；API-011～014；UI-014～015 |
| DP-08 | 列表分页行内 | API-016～018；UI-016～018 |
| DP-09 | 后台变更刷新 | API-023～024；UI-021、025 |
| DP-10 | 下架不展示 | UT-007；API-013；UI-022 |
| §2.6 | 项目交集 | UT-006、008；API-014 |
| §3.2 | 只读 | UT-016～017；API-021～022；UI-019 |
| §5.11 | 无详情页 | UT-017；API-021；UI-017 |
| §7.3 | 加载失败 | UI-003、020 |

---

## 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初版：单元 18、接口 28、UI 25；覆盖 DP-01～10 与正常/异常/约束；Playwright+Chrome；Base `/bigScreen/commonProsperity` |