453 lines
22 KiB
Markdown
453 lines
22 KiB
Markdown
# 跨平台商品聚合与 AI 分析测试驱动开发计划
|
||
|
||
- 文档状态：Draft
|
||
- 版本：v0.1
|
||
- 更新时间：2026-04-02
|
||
- 依据文档：
|
||
- `docs/PRD.md`
|
||
- `docs/FeatureSummary.md`
|
||
- `docs/DevelopmentPlan.md`
|
||
- `docs/UIDesign.md`
|
||
|
||
## 1. 文档目标
|
||
|
||
本计划用于把产品文档中的 MVP 范围、状态模型、报告 Schema、开发阶段和 UI 交互，收敛为一套“先写测试、再写实现、最后重构”的执行方案。
|
||
|
||
本文重点回答四个问题：
|
||
|
||
1. 哪些能力必须先用测试固化，再允许进入开发。
|
||
2. 单元、契约、回放、集成、E2E、可访问性测试分别覆盖什么。
|
||
3. 12 周开发周期内，每个阶段要先写哪些失败测试。
|
||
4. 什么叫某一阶段“测试上可放行”。
|
||
|
||
## 2. 适用范围与非范围
|
||
|
||
### 2.1 适用范围
|
||
|
||
本计划覆盖 P0 / MVP 范围内的测试驱动开发工作：
|
||
|
||
1. 天猫、京东双平台。
|
||
2. 任务创建、候选召回、人工确认、抓取、标准化、聚合、AI 报告、历史任务、版本切换、平台级重试。
|
||
3. 服务端统一执行、服务端受控会话准备与阻塞恢复。
|
||
4. Web 工作台前端、API / BFF、任务编排、采集 Worker、Browser Worker、会话中心、数据层、AI 报告模块。
|
||
|
||
### 2.2 非范围
|
||
|
||
以下内容不纳入本版 TDD 目标：
|
||
|
||
1. Markdown / PDF 导出。
|
||
2. 淘宝、抖音电商及更多平台接入。
|
||
3. 多租户 SaaS 化。
|
||
4. 持续监控、定时重跑、自动巡检。
|
||
5. 高级 BI 大屏与复杂可视化。
|
||
|
||
## 3. TDD 质量基线
|
||
|
||
以下规则来自上游文档，必须先以测试固化，再允许实现进入主干。
|
||
|
||
### 3.1 产品级硬约束
|
||
|
||
| 类别 | 必达规则 |
|
||
| --- | --- |
|
||
| 平台范围 | MVP 仅覆盖天猫、京东 |
|
||
| 主流程 | 搜索 -> 候选确认 -> 抓取 -> 标准化 -> AI 报告 -> 回看 |
|
||
| 输入方式 | 主入口为自然语言商品名称/描述 |
|
||
| 确认机制 | 同款判断以“系统召回 + 人工确认”为准 |
|
||
| 终态约束 | `NoSelection` 必须是正式终态，且不生成报告 |
|
||
| 成功策略 | 单平台失败不能自动拖死整任务 |
|
||
| 报告约束 | 报告必须是结构化 Schema，必须可追溯 |
|
||
| 交付形态 | 用户通过统一 Web 工作台操作，采集执行统一在服务端 |
|
||
|
||
### 3.2 状态级硬约束
|
||
|
||
| 层级 | 必测项 |
|
||
| --- | --- |
|
||
| `task_status` | `Draft`、`Searching`、`AwaitingConfirmation`、`NoSelection`、`Running`、`Completed`、`PartialCompleted`、`Blocked`、`Failed` |
|
||
| `task_stage` | `precheck`、`search`、`confirmation`、`session_check`、`crawl`、`normalize`、`analyze`、`publish` |
|
||
| `platform_status` | `Pending`、`SearchBlocked`、`Searching`、`NoResult`、`AwaitingSelection`、`Skipped`、`Selected`、`Blocked`、`Running`、`Completed`、`Failed` |
|
||
| 创建主路径 | 创建任务后先落 `Draft`，随后自动转 `Searching`；仅在搜索结果收口后进入 `AwaitingConfirmation`，UI 跳转不等于状态跳过 |
|
||
| 状态汇总 | 任务最终状态只基于已确认平台计算，且 `NoResult`、`Skipped` 不得被误算为 `Completed` 或 `Failed` |
|
||
| 重试规则 | 仅 `SearchBlocked`、`Blocked`、`Failed` 可重试 |
|
||
| 报告隔离 | 报告页只消费 `execution_status`，不直接消费运行态 `platform_status` |
|
||
|
||
### 3.3 报告级硬约束
|
||
|
||
| 类别 | 必测项 |
|
||
| --- | --- |
|
||
| 顶层字段 | `report_id`、`report_version`、`task_id`、`generated_at`、`task_status`、`summary`、`product_snapshot`、`platform_insights`、`cross_platform_insights`、`recommendations`、`evidence_index`、`quality_flags` |
|
||
| 报告终态 | `task_status` 仅允许 `Completed` 或 `PartialCompleted` |
|
||
| 状态映射 | `Completed -> completed`，`Blocked/SearchBlocked -> blocked`，`Failed -> failed`，`Skipped -> skipped`，`NoResult -> no_result` |
|
||
| 禁止出现在报告中的运行态 | `Pending`、`Searching`、`AwaitingSelection`、`Selected`、`Running` |
|
||
| 证据约束 | 强结论必须带 `evidence_ids` |
|
||
| 质量标记 | 必须覆盖样本不足、部分平台失败、阻塞平台、失败平台 |
|
||
| 版本约束 | 同一 `task_id` 下 `report_version` 从 `1` 递增；结果未变化不得生成新版本 |
|
||
|
||
### 3.4 发布门槛与指标
|
||
|
||
| 类别 | 门槛 |
|
||
| --- | --- |
|
||
| 功能门槛 | 双平台候选能力可用；至少一个链接可端到端跑通；阻塞恢复可用；历史任务与版本切换可用 |
|
||
| 任务结果 | 任务完成率 `Completed + PartialCompleted >= 75%` |
|
||
| 时效 | 默认配置下任务时长 `P50 <= 20 分钟` |
|
||
| 路由命中 | 搜索阶段 API/Hydration 命中率 `>= 70%` |
|
||
| 评论路径 | 评论抓取默认走接口或回放路径的任务占比 `>= 70%` |
|
||
| 浏览器占比 | 全量浏览器兜底占比 `<= 30%` |
|
||
| 可追溯性 | 关键结论证据可定位率 `>= 95%` |
|
||
| UI 可访问性 | 关键页面满足 `WCAG AA`，执行页更新区支持 `aria-live` |
|
||
|
||
## 4. 测试驱动原则
|
||
|
||
### 4.1 执行原则
|
||
|
||
1. 先验收场景，后领域规则，最后实现细节。
|
||
2. 先非浏览器主路径，后浏览器恢复与兜底。
|
||
3. 先固定 Schema 和枚举，后联调页面和 Worker。
|
||
4. 先写失败测试，确认失败原因正确，再补最小实现。
|
||
5. 任何状态枚举、报告字段、版本规则变化，必须先改测试再改代码。
|
||
6. 没有 fixture、HAR、Schema 或验收用例的需求，不进入开发。
|
||
|
||
### 4.2 单个需求的 Red-Green-Refactor 节奏
|
||
|
||
1. 写验收场景：明确用户动作、状态变化、预期输出。
|
||
2. 写契约测试：锁定 API 响应、SSE 事件、队列载荷或报告 Schema。
|
||
3. 写领域测试：锁定状态机、抽样、聚合、版本规则等业务逻辑。
|
||
4. 写适配层测试：锁定平台 fixture、Hydration 解析、请求回放和错误分类。
|
||
5. 用最小代码让测试变绿。
|
||
6. 在不改行为的前提下重构，保持测试全绿。
|
||
7. 把通过的用例纳入回归包和 CI。
|
||
|
||
### 4.3 Definition of Ready
|
||
|
||
需求进入开发前，必须具备：
|
||
|
||
1. 至少 1 条验收场景。
|
||
2. 至少 1 组状态变化预期。
|
||
3. 明确的输入输出契约。
|
||
4. 对应 fixture / HAR / 页面线框 / Schema 来源。
|
||
5. 失败口径，尤其是 `Blocked`、`Failed`、`NoResult`、`NoSelection`、`PartialCompleted` 的处理方式。
|
||
|
||
### 4.4 Definition of Done
|
||
|
||
需求完成必须同时满足：
|
||
|
||
1. 对应单元/契约/集成/E2E 测试全部通过。
|
||
2. 涉及页面、共享组件或状态文案的需求，必须补齐并通过可访问性测试。
|
||
3. 必要观测字段已落库或可统计，如 `strategy_attempts`、`platform_run_metrics`、`report_metrics`。
|
||
4. 无新增未分类状态。
|
||
5. 无未覆盖的报告 Schema 变更。
|
||
6. UI 状态文案与上游口径一致，不暴露技术错误栈。
|
||
|
||
## 5. 测试分层与工具
|
||
|
||
| 层级 | 目标 | 主要覆盖对象 | 推荐工具 |
|
||
| --- | --- | --- | --- |
|
||
| 领域层 | 固化核心业务规则 | 状态机、评论抽样、去重、聚合、版本规则、状态映射 | `Vitest` |
|
||
| 契约层 | 锁定可消费接口 | REST 响应、SSE 事件、队列载荷、报告 Schema、历史任务无报告场景 | `Vitest` + Schema 校验 |
|
||
| 适配层 | 锁定平台数据通路 | 搜索、详情、评论 fixture；Hydration 解析；HAR 回放；错误分类 | `Vitest` + fixture / HAR |
|
||
| 应用层 | 验证跨模块协同 | API / BFF、编排、数据库、队列、Worker、会话中心 | `Vitest` 集成测试 |
|
||
| 前端交互层 | 锁定 UI 状态表达 | 页面主流程、组件行为、状态标签、抽屉、版本切换 | 组件测试 + 路由测试 |
|
||
| E2E / 验收层 | 验证用户可用闭环 | 新建、确认、执行、恢复、报告、历史、重试 | `Playwright Test` |
|
||
| 可访问性层 | 锁定基础可达性 | 键盘操作、状态文本、对比度、`aria-live` | Playwright + a11y 检查 |
|
||
|
||
### 5.1 建议的测试占比
|
||
|
||
不以堆用例数量为目标，优先保证“规则密度高的地方测试密度更高”。
|
||
|
||
| 层级 | 建议占比 | 说明 |
|
||
| --- | --- | --- |
|
||
| 领域层 + 契约层 | 50% | 最稳定、最应该先写 |
|
||
| 适配层 | 20% | 平台变化频繁，必须用 fixture 固定输入 |
|
||
| 应用层 | 15% | 验证编排与持久化协同 |
|
||
| 前端交互层 | 5% | 关键组件和状态表达 |
|
||
| E2E / 验收层 | 10% | 验证闭环，不承担大部分规则覆盖 |
|
||
|
||
## 6. 需求到测试的映射
|
||
|
||
| 功能模块 | 必须先写的测试 | 通过标准 |
|
||
| --- | --- | --- |
|
||
| 任务创建 | 输入校验、`N` 与任务总上限分配、平台提示口径、创建后状态主路径 | 创建后先落 `Draft` 并自动进入 `Searching`；搜索收口后进入 `AwaitingConfirmation`，并展示平台提示 |
|
||
| 搜索预检查 | `search_requirement` 分类、无会话时 `SearchBlocked`、推荐登录提示 | `required` 平台无会话不能进入搜索；`recommended` 平台可继续 |
|
||
| 候选召回 | 候选卡字段完整性、去重、差异标签、排序规则 | 候选至少包含标题、价格、店铺、链接、主图和辅助识别信息 |
|
||
| 商品确认 | 单选、多选、跳过、零确认收口 | 零确认进入 `NoSelection` 且不生成报告 |
|
||
| 抓取前校验 | 仅校验已确认平台、失败不回退确认结果 | `Blocked` 平台保留确认结果并可恢复 |
|
||
| 商品抓取 | 详情字段抓取、原始字段留存、平台级异常分类 | 原始字段与标准化字段可追溯 |
|
||
| 评论抽样 | 三桶抽样比例、去重、样本不足标记 | `40/30/30` 规则正确；不足时正确打标 |
|
||
| 标准化 | 价格、评分、销量、时间、`sampling_bucket` 转换 | 空值允许但不得丢原始字段 |
|
||
| 三级聚合 | 链接级、平台级、跨平台级聚合逻辑 | 平台内不强制合并；跨平台以平台级为主视角 |
|
||
| 任务结果汇总 | `Completed`、`PartialCompleted`、`Blocked`、`Failed` 聚合规则，`NoResult`/`Skipped` 不误判 | 最终 `task_status` 仅基于已确认平台计算，且失败摘要可回看 |
|
||
| AI 报告 | 顶层 Schema、`InsightCard`、`evidence_index`、`quality_flags` | 报告能过 Schema 校验；强结论必须带证据 |
|
||
| 历史任务 | 历史列表、有报告/无报告/失败摘要展示、版本切换 | `NoSelection`、`Failed` 任务不能渲染为空白，`NoResult` 平台需保留原因摘要 |
|
||
| 版本与重试 | 仅失败/阻塞平台可重试、变更才升版、默认版本指向最新成功版本 | 无变化不升版；有变化正确递增 |
|
||
| 阻塞恢复 | 远程会话分配、恢复返回路径、状态刷新 | 恢复后回到来源页并更新状态 |
|
||
| UI 状态表达 | `Completed`、`PartialCompleted`、`Blocked`、`NoSelection` 文案与颜色语义 | 状态可解释，不只靠颜色表达 |
|
||
| 可访问性 | 键盘可达、状态文本、`aria-live`、`WCAG AA` | 执行页和报告页关键路径可读可操作 |
|
||
|
||
## 7. 核心回归包
|
||
|
||
以下场景构成 P0 核心回归包，并按对应能力落地阶段纳入稳定回归：
|
||
|
||
1. `[Phase 1]` 新建任务时，平台提示正确区分 `required` 与 `recommended`，且任务状态遵循 `Draft -> Searching -> AwaitingConfirmation`。
|
||
2. `[Phase 2]` 单平台搜索成功并返回候选，候选卡字段完整。
|
||
3. `[Phase 3]` 双平台搜索中，一个 `SearchBlocked`、一个正常返回候选。
|
||
4. `[Phase 3]` 双平台搜索中，一个 `NoResult`、一个正常返回候选，确认页仍可继续且空结果原因可见。
|
||
5. `[Phase 2]` 全部平台零确认提交，任务进入 `NoSelection`。
|
||
6. `[Phase 2]` 单平台完整成功，任务进入 `Completed`，生成 `report_version = 1`。
|
||
7. `[Phase 2]` 确认页多选同平台多个链接，并保留差异。
|
||
8. `[Phase 3]` 双平台中一个成功、一个 `Blocked`，任务进入 `PartialCompleted`。
|
||
9. `[Phase 3]` 已确认平台全部不可恢复失败时，任务进入 `Failed`，并保留失败原因摘要。
|
||
10. `[Phase 3]` 执行页中 `Blocked` 平台可发起恢复，会话完成后返回执行页继续。
|
||
11. `[Phase 4]` 评论样本不足时，报告 `quality_flags.sample_insufficient = true`，相关卡片 `sample_flag = insufficient`。
|
||
12. `[Phase 4]` 报告中的强结论卡必须能通过 `evidence_ids` 下钻到 `evidence_index`。
|
||
13. `[Phase 4]` 失败平台重试后结果未变化，不生成新 `report_version`。
|
||
14. `[Phase 4]` 失败平台重试后结果变化，生成新版本，且默认版本指向最新成功版本。
|
||
15. `[Phase 4]` 历史任务页可正确展示有报告、无报告、失败摘要和版本切换。
|
||
16. `[Phase 4]` 删除任务后，数据库记录、报告快照和关联产物清理一致。
|
||
|
||
## 8. 分阶段 TDD 计划
|
||
|
||
### 8.1 Phase 0：双平台可行性勘探与方案冻结（第 1-2 周）
|
||
|
||
目标：先验证可测试的数据通路，再决定开发主线。
|
||
|
||
先写的失败测试：
|
||
|
||
1. 天猫、京东搜索 / 详情 / 评论的最小 fixture 解析测试。
|
||
2. 搜索、详情、评论默认路径与降级路径的能力矩阵测试。
|
||
3. 浏览器接管与会话快照保存的冒烟测试。
|
||
4. `strategy_attempts` 记录格式测试。
|
||
|
||
阶段出口：
|
||
|
||
1. 至少一个平台搜索或详情默认不依赖 `L3`。
|
||
2. 至少一个平台满足“搜索成功率 >= 80%、详情字段完整率 >= 85%、评论 50 条样本耗时 <= 90s”。
|
||
3. 浏览器直接承接数据抓取占比 `<= 20%`。
|
||
4. 双平台能力矩阵、fixture、HAR 样本沉淀完成。
|
||
|
||
### 8.2 Phase 1：基础骨架与任务系统（第 3-4 周）
|
||
|
||
目标：先把状态机、编排和基础页面做成“可测系统”。
|
||
|
||
先写的失败测试：
|
||
|
||
1. `task_status`、`task_stage`、`platform_status` 转移与汇总测试。
|
||
2. 任务创建 API 契约测试（创建后先落 `Draft`，再自动进入 `Searching`）。
|
||
3. 任务事件日志、状态落库、队列载荷测试。
|
||
4. 新建任务页和执行页基础状态渲染测试。
|
||
5. 会话中心保存、过期、手动清理测试。
|
||
|
||
阶段出口：
|
||
|
||
1. 可创建任务并看到预检查结果。
|
||
2. 事件、平台状态、阶段流转均持久化。
|
||
3. `SearchBlocked` 和 `Blocked` 都能产生可恢复入口。
|
||
|
||
### 8.3 Phase 2：单平台 API 优先闭环（第 5-6 周）
|
||
|
||
目标：先做一条完整闭环，再扩平台。
|
||
|
||
先写的失败测试：
|
||
|
||
1. 单平台“预检查 -> 搜索 -> 确认 -> 详情 -> 评论 -> 标准化 -> 报告摘要”端到端测试。
|
||
2. 评论三桶抽样与去重测试。
|
||
3. 报告最小 Schema 测试。
|
||
4. 路由选择与降级逻辑测试。
|
||
5. `NoSelection` 终态测试。
|
||
|
||
阶段出口：
|
||
|
||
1. 单平台闭环稳定可运行。
|
||
2. 默认抓取路径不依赖 `L3 Browser`。
|
||
3. 路径失败时可按规则降级。
|
||
|
||
### 8.4 Phase 3：双平台模板刷新与恢复体系（第 7-9 周）
|
||
|
||
目标：把“部分成功”和“人工恢复”做成产品级能力。
|
||
|
||
先写的失败测试：
|
||
|
||
1. 双平台候选召回与确认测试。
|
||
2. `SearchBlocked`、`Blocked`、`Failed` 分类和恢复入口测试。
|
||
3. `PartialCompleted` / `Failed` 聚合测试。
|
||
4. `RetryablePlatformPicker` 仅列出可重试平台测试。
|
||
5. 会话恢复成功后回跳来源页并刷新状态测试。
|
||
|
||
阶段出口：
|
||
|
||
1. 天猫、京东都能返回候选、无结果或阻塞原因。
|
||
2. 双平台都至少有一条详情和评论抓取路径可运行。
|
||
3. 用户能发起恢复并继续任务。
|
||
|
||
### 8.5 Phase 4：标准化、聚合、AI 报告与历史任务（第 10-11 周）
|
||
|
||
目标：把“可读报告”和“可追溯资产”固定下来。
|
||
|
||
先写的失败测试：
|
||
|
||
1. 标准化字段转换测试。
|
||
2. 三级聚合测试。
|
||
3. 完整报告 Schema 测试。
|
||
4. `execution_status` 映射测试。
|
||
5. 版本递增、默认版本、无变化不升版测试。
|
||
6. 历史任务页、有报告/无报告/失败摘要展示、版本切换测试。
|
||
7. 30/90 天留存和任务删除联动测试。
|
||
|
||
阶段出口：
|
||
|
||
1. 报告符合 `PRD` 定义的完整 Schema。
|
||
2. 历史任务可回看最新版本并切换旧版本。
|
||
3. 删除与清理正确联动数据库和对象存储。
|
||
|
||
### 8.6 Phase 5：稳定性、效率与试运行（第 12 周）
|
||
|
||
目标：把测试从“功能正确”推进到“可发布”。
|
||
|
||
先写的失败测试：
|
||
|
||
1. 关键路径性能基准测试。
|
||
2. 平台级定向重试恢复率测试。
|
||
3. `strategy_attempts`、`platform_run_metrics`、`report_metrics`、`retention_metrics` 观测完整性测试。
|
||
4. 三条主验收链路 E2E：
|
||
- 单平台 API 成功
|
||
- 多平台部分失败
|
||
- 浏览器阻塞恢复
|
||
5. UAT 回归包。
|
||
|
||
阶段出口：
|
||
|
||
1. 完成 P0 验收清单。
|
||
2. 达到试运行门槛：
|
||
- 任务时长 `P50 <= 20 分钟`
|
||
- 搜索 API/Hydration 命中率 `>= 70%`
|
||
- 评论抓取接口或回放占比 `>= 70%`
|
||
- 全量浏览器兜底占比 `<= 30%`
|
||
- 关键结论证据可定位率 `>= 95%`
|
||
3. 形成按平台维度的热修与回滚回归包。
|
||
|
||
## 9. 测试资产规划
|
||
|
||
### 9.1 Fixture 与样本分层
|
||
|
||
| 资产类型 | 用途 |
|
||
| --- | --- |
|
||
| 搜索结果 fixture | 候选召回、去重、排序、差异标签 |
|
||
| 商品详情 fixture | 原始字段抓取、Hydration 解析、标准化 |
|
||
| 评论分页 fixture | 三桶抽样、去重、样本不足 |
|
||
| HAR / 回放样本 | `L0 Replay`、`L2 Template Refresh` |
|
||
| 报告快照 fixture | Schema 校验、历史版本切换 |
|
||
| UI 状态快照 | `NoSelection`、`Blocked`、`PartialCompleted`、`Completed` |
|
||
|
||
### 9.2 必备异常样本
|
||
|
||
1. 无会话导致 `SearchBlocked`。
|
||
2. 抓取中登录失效导致 `Blocked`。
|
||
3. 页面结构变化导致解析失败。
|
||
4. 评论接口可用但样本不足。
|
||
5. 同平台候选重复。
|
||
6. 同店铺同款不同规格。
|
||
7. 多店铺疑似同款但需保持独立。
|
||
8. 重试后结果无变化。
|
||
9. 重试后生成新报告版本。
|
||
|
||
### 9.3 AI 测试策略
|
||
|
||
CI 中不依赖真实模型质量波动，采用三层校验：
|
||
|
||
1. 结构层：校验报告 JSON 必须满足 Schema。
|
||
2. 规则层：强结论必须带证据；样本不足时必须打标。
|
||
3. 抽检层：预发布环境对真实模型输出做人工抽检与快照比对。
|
||
|
||
## 10. 前端测试重点
|
||
|
||
### 10.1 页面级重点
|
||
|
||
| 页面 | 重点测试项 |
|
||
| --- | --- |
|
||
| 新建任务页 | 平台提示、采样规则、会话准备入口、创建后跳转 |
|
||
| 候选确认页 | 候选字段完整、多选、跳过、零确认收口 |
|
||
| 任务执行页 | 三层状态并列、SSE 更新、阻塞恢复、平台级重试 |
|
||
| 报告页 | 先摘要后证据、`execution_status` 渲染、质量标记、版本切换 |
|
||
| 历史任务页 | 筛选、无报告任务展示、删除、重试 |
|
||
| 会话准备 / 恢复页 | 分配、连接、验证、回跳、过期 |
|
||
|
||
### 10.2 共享组件重点
|
||
|
||
| 组件 | 重点测试项 |
|
||
| --- | --- |
|
||
| `TaskSpine` | 阶段顺序、当前阶段高亮、终态展示 |
|
||
| `PlatformStatusTag` | 枚举映射、文本与图标并存 |
|
||
| `CandidateCard` | 核心字段、差异标签、链接操作 |
|
||
| `PlatformRunPanel` | 阻塞动作、重试入口、局部状态更新 |
|
||
| `InsightCard` | 结论、置信度、样本标记、证据入口 |
|
||
| `EvidenceDrawer` | `evidence_ids` 对应关系、来源信息、时间 |
|
||
| `VersionSwitcher` | 默认版本与最新版本标识 |
|
||
| `RetryablePlatformPicker` | 仅显示可重试平台 |
|
||
|
||
### 10.3 可访问性重点
|
||
|
||
1. 所有状态不可只靠颜色表达。
|
||
2. 执行页事件更新区域必须支持 `aria-live`。
|
||
3. 核心操作支持键盘完成。
|
||
4. 关键页面文本和状态标签满足 `WCAG AA`。
|
||
5. 会话页在移动端降级时仍提供清晰提示。
|
||
|
||
## 11. CI 与准入门槛
|
||
|
||
### 11.1 CI 阶段
|
||
|
||
| 阶段 | 必跑项 |
|
||
| --- | --- |
|
||
| 提交前 | 领域层测试、契约测试、核心 lint |
|
||
| PR | 全量单元测试、契约测试、适配层 fixture / HAR 回放、关键前端组件测试 |
|
||
| 合并前 | 应用层集成测试、主回归 E2E、可访问性检查 |
|
||
| 预发布 | 真实环境冒烟、性能基线、AI 报告抽检 |
|
||
|
||
### 11.2 阻断规则
|
||
|
||
出现以下任一情况，不允许合并：
|
||
|
||
1. 状态枚举变化但无测试更新。
|
||
2. 报告 Schema 变化但无契约测试更新。
|
||
3. `NoSelection`、`PartialCompleted`、`Blocked`、`Failed` 任一主场景回归失败。
|
||
4. 搜索成功但 `NoResult` 的主场景渲染或汇总测试失败。
|
||
5. `execution_status` 映射测试失败。
|
||
6. 证据索引或版本规则测试失败。
|
||
7. 执行页 `aria-live` 或关键状态可访问性测试失败。
|
||
|
||
## 12. 角色分工
|
||
|
||
| 角色 | 主要责任 |
|
||
| --- | --- |
|
||
| 产品经理 | 提供验收场景、口径差异判定、`NoSelection` / 版本 / 重试规则确认 |
|
||
| 设计师 | 提供页面状态稿、文案口径、可访问性要求 |
|
||
| 前端工程师 | 页面交互测试、组件测试、E2E 页面侧实现 |
|
||
| 后端 / 平台工程师 | 状态机、契约、编排、适配层、版本规则测试 |
|
||
| 浏览器自动化工程师 | 会话恢复、模板刷新、阻塞恢复测试资产 |
|
||
| 数据与 AI 工程师 | 标准化、聚合、报告 Schema、证据索引测试 |
|
||
| QA | 主回归包维护、UAT、阶段出口审核 |
|
||
|
||
## 13. 里程碑交付物
|
||
|
||
| 里程碑 | 必交付测试资产 |
|
||
| --- | --- |
|
||
| M1 | 双平台能力矩阵、最小 fixture / HAR 样本、路径验证测试 |
|
||
| M2 | 三层状态机测试、任务 API 契约测试、会话中心测试 |
|
||
| M3 | 单平台闭环回归包、最小报告快照测试 |
|
||
| M4 | 双平台恢复与部分成功回归包 |
|
||
| M5 | 完整报告 Schema 测试、历史任务与版本回归包 |
|
||
| M6 | P0 验收回归包、性能基线、试运行值守清单 |
|
||
|
||
## 14. 风险与控制
|
||
|
||
| 风险 | 对应控制 |
|
||
| --- | --- |
|
||
| 平台接口频繁变化 | 用 fixture / HAR 回放、契约测试、能力矩阵测试锁住降级逻辑 |
|
||
| 浏览器兜底比例失控 | 把浏览器占比和命中率纳入 CI 报表与阶段出口 |
|
||
| AI 输出不稳定 | CI 只认 Schema 和规则，不把文本风格当通过条件 |
|
||
| 状态口径被前后端各自解释 | 用同源枚举测试和 UI 状态映射测试统一口径 |
|
||
| `PartialCompleted` 被当作失败或成功粗暴处理 | 单独保留回归用例和页面文案检查 |
|
||
| 历史版本和删除规则出错 | 用版本递增、默认版本、无变化不升版、删除联动测试锁定 |
|
||
|
||
## 15. 一句话结论
|
||
|
||
本项目的测试驱动开发不是“先写几个单元测试”，而是把状态模型、报告 Schema、平台路由、恢复流程和 UI 验收统一前置：先固定规则，再做实现；先跑单平台闭环，再扩双平台；先保证 `NoSelection`、`PartialCompleted`、证据索引和版本切换正确，再谈吞吐和试运行。
|