cross-platform-products-ai-analyst/docs/tdd.md

跨平台商品聚合与 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、证据索引和版本切换正确，再谈吞吐和试运行。