Neo-ZQYY/docs/_overview/03-test-spec.md

测试规范(Wave 1-5 验证判据)

生成日期:2026-05-04 / 用途:Wave 1-5 走查时的"过线判据"基础 / 引用源:01-product-overview.md 02a-miniprogram-page-matrix.md 02b-adminweb-page-matrix.md

本文不重复产品定义(去 01),不重复每页字段(去 02a/02b),只定义测试该怎么跑、什么算过线。

一、测试视角分层

层	内容	工具	判据来源
L1 工程层	代码可启动 / 无控制台错误 / API 200	Playwright Console + Network	tsc/lint/build 通过
L2 接口层	API 返回结构符合契约 / 必填字段齐	curl + Playwright Network	NS1/NS2/NS3/NS4 + .tsx 实际调用
L3 展示层	UI 渲染必现字段 / 空态文案对 / 数据展示标准对	Playwright Snapshot + Screenshot	02a 02b 必现字段 + DISPLAY-STANDARDS
L4 业务层	数据语义对 / 跨页一致 / 角色权限对	Playwright + 微信 IDE + DB 校核	01-product-overview.md 业务概念
L5 数据层	DB 视图 / RLS 隔离 / DWS 字段口径	pg-etl-test / pg-app-test MCP	db/CLAUDE.md + 飞球 CLAUDE.md DWS 权威

L1 不过 L2 不测;L2 不过 L3/L4 无意义;L4 失败 ≠ Bug,可能是 L5 数据问题。 走查时按层判读。

二、9 主题 × 测试维度映射(基于蓝本 §3.1-§3.9)

主题	L1	L2	L3	L4	L5
§3.1 AI 模块重构(8 APP)	✓	✓	-	✓ 调用链路	-
§3.2 admin-web AI 套件	✓	✓	✓	✓	-
§3.3 App2 prompt v5.1	-	✓ A/B 评分	-	✓ 12 项指标产出	-
§3.4 App3 线索完整详情	-	✓	-	✓	-
§3.5 Runtime Context 沙箱	✓	✓	✓	✓ 时间漂移	✓ DB 视图
§3.6 AI 触发器 + prewarm	✓	✓	✓	-	✓ trigger_jobs 表
§3.7 飞球 DWS / RLS	-	-	-	-	✓ 重点
§3.8 沙箱 admin-web 验证	✓	-	✓	✓	-
§3.9 部署文档	-	-	-	-	-

三、单页面测试模板(每页都按这个跑)

打开页面后,按顺序跑 5 步:

1. L1 加载校核
   • URL 状态 200
   • 控制台 0 error(401/403 在登录前可允许)
   • 主体内容 < 3s 加载
2. L2 接口校核
   • 抓 Network,核对调用的 API 与 02a/02b 列出的"主要后端 API"一致
   • 响应 200 + 必填字段齐
   • 无 4xx/5xx(除非是测试错误路径)
3. L3 必现字段校核
   • 对照 02a/02b 该页"必现字段"清单逐条勾
   • 空数据时显示"空态文案"(对照清单)
   • 金额 / 日期 / 数字格式按 02a §四 跨页共性 检查
4. L4 业务语义校核
   • 数据是不是这个角色 / 这个门店应该看到的(参考 01 §二角色矩阵 + §五.6 site_id 隔离)
   • 跨页跳转携带的参数是否对(对照 02a/02b 入口字段)
   • 同一指标在多页显示是否一致(如近 7 日营收 vs board-finance vs my-profile)
5. L5 数据校核(可选,仅当 L4 怀疑数据错时)
   • 直查测试库:SELECT ... FROM dws.dws_* 或 app.v_*
   • 对照 飞球 CLAUDE.md DWS 权威规范
   • 对照页面展示数,差异 > 0.01 即标 D Bug

四、走查规模估算(更新版)

基于 Wave 0 调研后的修正:

小程序(21 页)

• 必走查:21 页 × 1 角色(当前账号,Neo 决定)= 21 个 case
• 可选:某些页有多入口(如 customer-records / customer-service-records),每入口 +1 case

admin-web(19 路由)

• 必走查:19 路由 = 19 个 case
• 多 Tab 路由额外展开:/etl-tasks(5 Tab) /triggers(4 Tab) /ai/* 各页可能有 Tab,需逐 Tab 走 → +约 15 case

数据库 / ETL(L5)

• RLS 业务日上界视图重建对照:N 个视图(待 pg_get_viewdef 列表)
• finance_area_daily DWS 幂等性:测试库重跑同窗口
• AI 触发器 jobs 表:实际行数 + cron 重调度对比
• sandbox runtime_context 表:虚拟时间漂移多账号

AI 调用(L4 高成本部分)

• 8 APP × 1 次 / APP = 8 次(蓝本 §3.1)+ App2a 区域财务 = 9 次
• A/B prompt 评分(P2 §3.3)= 20 个以内 Neo 默认授权,先单调通,再批跑

总规模(刷新)

• L1-L4 走查:21 + 19 + 15 = 55 个 UI case
• L5 数据校核:约 10 个 SQL 验证点
• AI 调用:9 次单调通 + 20 次 A/B 评分(可选)
• 合计:约 75-95 个测试 case(原估算 60,Wave 0 调研后更准)

预计:Wave 1(Runtime Context)≈ 15 case + DB,Wave 2(admin-web AI)≈ 20 case,Wave 3(小程序)≈ 21 case,Wave 4(DWS/RLS)≈ 15 case + DB,Wave 5(部署)≈ 5 case + 总报告。

五、测试产物存放约定

每个 Wave 产出一份验证报告 → docs/audit/changes/2026-05-04__verify_wave_<N>_<slug>.md,内容:

# Wave <N> 验证报告 — <主题>

| 字段 | 值 |
|---|---|
| 日期 | 2026-05-04 |
| Wave | <N> |
| 范围 | <对照蓝本 §3.x> |
| 通过 | X 个 case |
| 失败 | Y 个 case(P0:a / P1:b / P2:c) |
| 截图 | docs/audit/changes/2026-05-04__verify_wave_<N>_screenshots/*.png |

## 1. case 清单(对照测试矩阵)
| # | 页面/接口 | L1 | L2 | L3 | L4 | L5 | 结论 |

## 2. 失败明细(每条:现状 / 期望 / 复现 / 截图 / 建议优先级)

## 3. 不通过项 todo
- [ ] P0-X: ...
- [ ] P1-Y: ...

## 4. Wave 收尾建议

六、判 Bug 时的"先看一眼"清单

发现疑似 Bug 时,在标 D 之前先查这 5 条:

1. 是不是文档过期? → 查 04-doc-conflicts.md,本 Wave 0 已登记 39 条
2. 是不是角色权限? → 查 01-product-overview.md §二
3. 是不是门店 site_id 隔离? → 查 01-product-overview.md §五.6
4. 是不是飞球数据本身就缺? → 查 朗朗桌球停业日期 记忆 + DWD 是否有数据
5. 是不是 Runtime Context 虚拟时间漂移? → 查 01-product-overview.md §五.7

5 项都排除后再标 D Bug。

七、不在测试范围内

• 生产服务器(SSH)— 只在测试库
• 性能压测 — 仅做基本 Lighthouse / 加载时间
• 跨浏览器 — 仅 Chromium(Playwright 默认)
• 多账号并发 — 仅当前登录账号
• 多终端模拟 — 仅微信开发者工具默认尺寸

八、引用

• 01-product-overview.md 产品全景脑图
• 02a-miniprogram-page-matrix.md 小程序 21 页指纹
• 02b-adminweb-page-matrix.md admin-web 19 路由指纹
• 04-doc-conflicts.md 39 条文档冲突清单
• 05-orphan-pages-cleanup.md 6 个 admin-web 页面处置
• docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 原蓝本
• apps/etl/connectors/feiqiu/CLAUDE.md 飞球数据规范(L5 判据)
• db/CLAUDE.md 数据库分层(L5 判据)