217 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 跨平台商品聚合与 AI 分析开发任务拆解
- 文档状态Draft
- 版本v0.4
- 更新时间2026-04-02
- 依据文档:
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/DevelopmentPlan.md`
- `docs/UIDesign.md`
- `docs/tdd.md`
## 1. 文档目标
本文件用于把上游产品、研发、UI 与 TDD 文档收敛为可执行的开发任务拆解,作为后续排期、分工、验收和变更同步的直接依据。项目当前进度、阶段判断与任务状态统一维护在 `TODO.md`
本文重点解决四件事:
1. 明确 P0 开发阶段到底要做哪些任务。
2. 给出任务的执行顺序、依赖关系和阶段出口。
3. 把页面、后端、采集、数据、AI、测试、运维任务统一到同一清单中。
4. 让每个任务都能对应到明确产出、验收标准和测试门禁。
## 2. 使用说明
### 2.1 进度维护约定
- `docs/tasks.md` 只维护任务范围、依赖关系、主要产出、验收标准和测试门禁。
- `TODO.md` 是项目进度的单一维护入口,负责记录阶段快照、任务状态、阻塞点和近期动作。
- `TODO.md` 中使用的任务编号必须与本文保持一致;若任务拆分、合并或改号,两个文件必须同步更新。
### 2.2 编号约定
本文使用 `S0``S5` 表示开发阶段编号,对应 `DevelopmentPlan.md` 中的 `Phase 0``Phase 5`;不等同于产品优先级里的 `P0 / P1`
### 2.3 角色约定
| 角色 | 说明 |
| --- | --- |
| 产品 | 产品经理 |
| 设计 | UI/UX 设计师 |
| 前端 | Web 前端工程师 |
| 后端 | API / BFF / 数据工程师 |
| 平台 | 平台采集与适配工程师 |
| 自动化 | 浏览器自动化 / 阻塞恢复工程师 |
| 数据AI | 标准化、聚合、报告生成工程师 |
| QA | 测试与验收工程师 |
## 3. 执行原则
| 原则 | 说明 |
| --- | --- |
| P0 范围优先 | 当前开发只覆盖天猫、京东、统一 Web 工作台、结构化报告、历史回看与平台级重试 |
| 测试先行 | 先固化状态机、报告 Schema、候选确认、版本规则和恢复流程再进入实现 |
| 非浏览器主路径优先 | 搜索、详情、评论默认优先走 `L0 Replay` / `L1 Hydration` / `L2 Template Refresh`,浏览器只负责会话、恢复和极端兜底 |
| 观测与审计前置 | 路由选择、状态转移、版本生成和删除动作必须先定义事件与指标记录口径,再进入实现 |
| 状态口径单一来源 | `task_status``task_stage``platform_status``execution_status` 由共享领域模型统一定义 |
| 人工确认不可省略 | 商品同款判断必须经过“系统召回 + 人工确认”闭环 |
| 部分成功可交付 | 单平台失败、阻塞或无结果不应拖死整任务;`PartialCompleted` 是正式可交付状态 |
| 报告必须可追溯 | 强结论必须引用 `evidence_ids`,并保留 90 天证据索引与摘录 |
| 变更必须联动同步 | 上游文档或枚举变更后,需同步检查 `docs/tasks.md``TODO.md` 与下游实现是否失效 |
## 4. 开发启动门禁
进入编码前,至少满足以下条件:
| 门禁项 | 要求 |
| --- | --- |
| 文档齐备 | `PRD``FeatureSummary``DevelopmentPlan``UIDesign``tdd``tasks` 已齐全 |
| 任务拆解完成 | 本文已完成并可直接用于排期 |
| 进度面板建立 | `TODO.md` 已创建,并可按任务编号维护当前状态、阻塞与下一步 |
| 评审门禁 | 本文需按仓库流程完成 Claude、Gemini、Codex 三方审阅与人工终审 |
| 平台范围冻结 | MVP 范围固定为天猫、京东;淘宝、抖音电商不进入本轮开发 |
| 状态与报告口径冻结 | 三层状态模型、`NoSelection` 终态、`PartialCompleted` 终态、报告 Schema 已冻结 |
| 观测口径冻结 | `task_events``strategy_attempts``report_metrics` 的最小字段、统计维度和审计要求已冻结 |
| 测试资产准备 | 至少具备首批 fixture、HAR 样本、报告 Schema 校验器和关键页面线框 |
## 5. 总体排期与里程碑
| 阶段 | 周期 | 目标 | 对应里程碑 |
| --- | --- | --- | --- |
| `S0` | 第 1-2 周 | 双平台能力勘探、PoC、方案冻结 | `M1` |
| `S1` | 第 3-4 周 | 基础骨架、状态机、任务系统、会话中心 | `M2` |
| `S2` | 第 5-6 周 | 单平台 API 优先闭环 | `M3` |
| `S3` | 第 7-9 周 | 双平台接入、模板刷新、阻塞恢复、部分成功 | `M4` |
| `S4` | 第 10-11 周 | 标准化、三级聚合、AI 报告、历史任务、版本管理 | `M5` |
| `S5` | 第 12 周 | 稳定性、性能、试运行、发布准备 | `M6` |
## 6. 阶段任务清单
### 6.1 `S0` 双平台可行性勘探与方案冻结
阶段目标:在正式编码前,验证双平台非浏览器主路径可行、服务端受控浏览器可接管、能力矩阵和工程方案可落地。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S0-01` | 冻结双平台能力矩阵 | 产品、平台、自动化 | `PRD``FeatureSummary``DevelopmentPlan` | 天猫/京东 `search/detail/reviews/login` 能力矩阵,`search_requirement`,默认路径与降级路径 | 每个平台都明确 `L0/L1/L2/L3` 路径、登录依赖、阻塞分类、可接受兜底成本 | fixture 解析测试、能力矩阵契约测试 |
| `S0-02` | 产出双平台首批 fixture 与 HAR 样本 | 平台、自动化、QA | `S0-01` | 搜索、详情、评论、阻塞场景样本;最小 HAR 回放样本 | 双平台至少覆盖“正常返回、无结果、需登录、抓取失败、样本不足”五类样本 | HAR 回放测试、fixture 冒烟测试 |
| `S0-03` | 验证服务端受控浏览器与会话快照 PoC | 自动化、后端 | `UIDesign``DevelopmentPlan` | 远程浏览器接管 PoC、会话快照保存与恢复 PoC | 用户可完成一次远程登录,系统可加密保存并复用会话,完成后可回跳来源页 | 浏览器接管冒烟测试、会话快照读写测试 |
| `S0-04` | 验证至少一个平台的非浏览器主路径 PoC | 平台、后端 | `S0-01``S0-02` | 至少一个平台的 `search/detail/reviews` 非浏览器主路径 PoC | 至少一个平台满足“搜索成功率 >= 80%、详情字段完整率 >= 85%、50 条评论耗时 <= 90s” | PoC 性能基准测试、路径降级测试 |
| `S0-05` | 搭建 Monorepo 与基础工程骨架 | 后端、前端 | `DevelopmentPlan` | `pnpm workspace + Turborepo`、应用目录、共享包目录、统一脚本 | `apps/``packages/` 结构落地;`dev/build/test/lint` 可运行 | 构建冒烟测试、CI 骨架校验 |
| `S0-06` | 冻结 Phase 0 量化评分表、`strategy_attempts` 记录格式与进入开发门槛 | 产品、QA、平台 | `S0-03``S0-04` | 量化评分表、`strategy_attempts` 最小记录格式、是否进入正式开发的结论 | 明确 `M1` 是否通过若未通过记录阻塞点和改造方向PoC 路由选择、结果和耗时统计口径已冻结 | Phase 0 结果审计清单、`strategy_attempts` 契约测试 |
### 6.2 `S1` 基础骨架与任务系统
阶段目标:搭起可测的系统骨架,固化状态模型、会话中心、任务创建与执行框架。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S1-01` | 共享领域模型与枚举包落地 | 后端、数据AI | `S0-05` | `task_status``task_stage``platform_status``execution_status`、报告 Schema 包 | Web、API、Worker 共用同一份枚举与类型定义;`NoSelection``PartialCompleted` 正式入模 | 枚举契约测试、报告 Schema 基础测试 |
| `S1-02` | 数据库、事件日志与对象存储模型落地 | 后端 | `S1-01` | `tasks``platform_runs``selected_links``task_events``strategy_attempts``raw_*``normalized_*``report_snapshots``evidence_index``session_states``artifact_refs` 等表结构与迁移 | 表结构覆盖 P0 全流程;事件、策略尝试和对象存储引用可关联任务与平台执行记录 | 数据迁移测试、实体约束测试、事件表契约测试 |
| `S1-03` | 任务编排、事件持久化与状态机骨架落地 | 后端 | `S1-01``S1-02` | BullMQ 队列、任务状态机、`task_events` 记录、平台并发控制、重试约束 | 可支持 `Draft -> Searching -> AwaitingConfirmation` 主路径;每次阶段/状态变更写入事件日志;`SearchBlocked` 不拖死整任务 | 状态机转移测试、事件持久化测试、队列载荷测试 |
| `S1-04` | API / BFF、平台就绪摘要与 `SSE` 基础接口落地 | 后端 | `S1-03` | 任务创建、任务详情、候选查询、历史查询、平台 readiness 摘要、会话入口、实时事件流接口 | 前端可查询任务、平台就绪状态、订阅事件并读取平台状态 | REST 契约测试、`SSE` 事件契约测试、platform readiness 契约测试 |
| `S1-05` | Web 工作台基础壳层与核心路由落地 | 前端、设计 | `UIDesign``S1-04` | 左侧导航、任务上下文头部、`TaskSpine`、基础页面路由 | 可访问 `/tasks/new``/tasks/:id/confirm``/tasks/:id/run``/history``/sessions/:platform/prepare`;基础布局与状态占位正确 | 页面路由测试、共享组件快照测试 |
| `S1-06` | 会话中心 v1 与全局会话准备后端入口落地 | 后端、自动化、前端 | `S0-03``S1-02``S1-04` | 会话保存、过期时间、手动清理、`/sessions/:platform/prepare` 入口、来源页回跳协议 | 支持加密存储、24 小时有效期、按平台查看与清理会话;完成准备后可返回来源页并刷新状态 | 会话保存/过期/清理测试、prepare 回跳测试 |
| `S1-07` | 新建任务页与全局会话准备入口落地 | 前端、后端、设计 | `UIDesign``S1-04``S1-05``S1-06` | `/tasks/new``Hero Composer``Sampling Config``Platform Readiness Panel``Recent Tasks Mini List`、全局会话准备入口 | 支持自然语言输入;默认 `per_link_limit = 100``task_total_limit = 500` 且允许按规则调整;正确展示 `required/recommended` 平台提示与创建前会话预热;创建成功后进入确认页 | 新建任务页交互测试、输入校验测试、prepare 入口回跳测试 |
| `S1-08` | TDD 与 CI 基础链路落地 | QA、前端、后端 | `S0-05` | `Vitest``Playwright`、Schema 校验、`lint/build/test` 流水线 | 提交前与 PR 阶段的最小测试链路可运行 | CI 冒烟测试、空场景回归测试 |
### 6.3 `S2` 单平台 API 优先闭环
阶段目标:先在一个平台跑通完整闭环,验证搜索、确认、详情、评论、标准化与最小报告链路。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S2-01` | 首个平台预检查与搜索适配器落地 | 平台、后端 | `S0-04``S1-03``S1-04` | 单平台 `precheck/search` 适配器、候选标准化结果、搜索阶段 `strategy_attempts` 记录 | 返回候选、`NoResult``SearchBlocked` 三类明确结果;`required/recommended` 平台搜索前行为符合既定口径;搜索路径选择与失败分类可回溯 | 搜索 fixture 测试、预检查规则测试、路由选择测试 |
| `S2-02` | 候选确认页与确认 API 落地 | 前端、后端、设计 | `S1-05``S2-01` | `/tasks/:taskId/confirm` 页、确认提交接口、`SelectionBasket` | 支持单选、多选、跳过、零确认收口;进入 `NoSelection` 时不生成报告 | 候选确认 E2E、`NoSelection` 终态测试 |
| `S2-03` | 单平台商品详情抓取链路落地 | 平台、后端 | `S2-01` | 详情采集器、原始字段留存、对象存储引用、详情阶段 `strategy_attempts` 记录 | 商品标题、价格、规格、店铺、评分、销量、抓取时间可抓取并回溯;详情抓取路径与失败分类可追溯 | 详情解析测试、原始字段留存测试、详情路由测试 |
| `S2-04` | 单平台评论采集与抽样链路落地 | 平台、后端 | `S2-03` | 评论采集器、三桶抽样、去重与样本不足标记、评论阶段 `strategy_attempts` 记录 | 满足 `40/30/30` 规则;评论不足时正确打 `sample_insufficient` 标记;评论抓取路径与失败分类可追溯 | 评论抽样测试、去重测试、样本不足测试、评论路由测试 |
| `S2-05` | 标准化 v1 与最小报告快照落地 | 数据AI、后端 | `S2-03``S2-04` | 商品/评论标准化、最小 `report_snapshot`、最小 `evidence_index` | 可生成单平台结构化摘要;关键字段统一到既定口径 | 标准化测试、最小报告 Schema 测试 |
| `S2-06` | 单平台执行页闭环与回归包落地 | 前端、后端、QA | `S1-07``S2-02``S2-05` | 执行页单平台闭环、首条端到端回归包 | 单平台可从新建任务走到 `Completed``NoSelection` 可独立收口;关键路由尝试与事件日志可用于回放问题 | 单平台 E2E、`SSE` 更新测试、可访问性基础测试 |
### 6.4 `S3` 双平台模板刷新与恢复体系
阶段目标:扩展到双平台,补齐阻塞恢复、模板刷新、部分成功与平台级重试。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S3-01` | 第二平台 `precheck/search/detail/reviews` 适配器落地 | 平台、后端 | `S2-05` | 双平台搜索、详情、评论适配器 | 双平台都能返回候选、无结果或阻塞原因,且至少有一条详情与评论抓取路径可用 | 双平台 fixture 测试、适配器回放测试 |
| `S3-02` | 模板刷新与 `L2` 路径落地 | 自动化、平台 | `S0-03``S3-01` | 模板刷新、动态参数补齐、策略切换逻辑 | 请求模板失效时可转入 `L2`,成功后回到 HTTP 主路径 | 路由降级测试、模板刷新冒烟测试 |
| `S3-03` | 阻塞恢复与 `L3 Browser Recovery` 落地 | 自动化、前端、后端 | `S1-06``S3-02` | `/tasks/:taskId/recovery/:platform`、恢复流程、恢复后回跳 | `SearchBlocked``Blocked` 平台可发起恢复;恢复成功后任务继续 | 阻塞恢复 E2E、会话恢复回跳测试 |
| `S3-04` | 双平台候选确认与执行控制台落地 | 前端、设计、后端 | `S3-01``S3-03` | 双平台 `Candidate Board``PlatformRunPanel``Live Event Feed` | 候选页、执行页能并列展示平台状态;新事件到达不打断当前阅读 | 双平台页面交互测试、`SSE` 并发更新测试 |
| `S3-05` | `PartialCompleted``Blocked``Failed` 汇总规则落地 | 后端、数据AI | `S3-01``S3-03` | 任务汇总逻辑、平台级重试入口、`RetryablePlatformPicker` | 一个平台成功、一个平台阻塞时进入 `PartialCompleted`;已确认平台全部失败时进入 `Failed``NoResult` / `Skipped` 不误算为 `Completed``Failed`;仅失败/阻塞平台可重试 | 状态汇总测试、平台级重试范围测试、`NoResult/Skipped` 汇总测试 |
| `S3-06` | 双平台主回归包落地 | QA、前端、后端 | `S3-05` | 双平台回归包与阶段验收记录 | 覆盖“一个 `SearchBlocked`、一个成功”“一个 `NoResult`、一个成功”“一个成功、一个 `Blocked`”“已确认平台全部失败”四类主场景 | 双平台 E2E、回归报告 |
### 6.5 `S4` 标准化、三级聚合、AI 报告与历史任务
阶段目标:完成报告产品化交付,包括标准化、聚合、证据索引、历史版本、留存与删除。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S4-01` | 完整标准化与三级聚合落地 | 数据AI、后端 | `S3-01``S3-05` | 商品/评论标准化、链接级/平台级/跨平台级聚合视图 | 平台内多链接不强制合并;跨平台默认以平台级为主视角 | 标准化全量测试、三级聚合测试 |
| `S4-02` | AI 结构化报告生成与版本规则落地 | 数据AI、后端 | `S4-01``S1-01` | `summary``product_snapshot``platform_insights``cross_platform_insights``recommendations``evidence_index``quality_flags``report_version` 生成规则 | 报告仅允许 `Completed` / `PartialCompleted`;强结论必须带证据;同一 `task_id``report_version``1` 递增且结果未变化不生成新版本 | 完整报告 Schema 测试、证据约束测试、版本规则测试 |
| `S4-03` | 报告页、证据抽屉与质量标记落地 | 前端、设计 | `S4-02``UIDesign` | `/tasks/:taskId/report``InsightCard``EvidenceDrawer``QualityFlagPanel` | 先展示摘要,再支持证据下钻;异常平台使用 `execution_status` 展示 | 报告页组件测试、证据抽屉测试、a11y 测试 |
| `S4-04` | 历史任务页、版本切换与删除入口落地 | 前端、后端 | `S4-02``S4-03` | `/history``VersionSwitcher`、搜索/筛选、删除确认、平台级重试入口、无报告任务展示 | 同一任务可切换 `report_version``NoSelection` / `Failed` 任务不显示为空白;历史页支持筛选、回看、删除和平台级重试入口 | 历史任务测试、版本切换测试、删除交互测试 |
| `S4-05` | 留存、删除 API 与联动清理链路落地 | 后端、QA | `S1-02``S4-04` | 30/90 天清理作业、任务级删除 API、对象存储联动清理、残留审计 | 原始数据 30 天、标准化与报告 90 天;用户删除后关联数据与产物一致清理;前台删除动作与后台清理结果一致 | 留存作业测试、删除 API 契约测试、删除联动测试 |
| `S4-06` | 完整可观测性与审计日志落地 | 后端、自动化、数据AI | `S1-02``S3-02``S4-02` | `strategy_attempts` 聚合查询、`platform_run_metrics``report_metrics``retention_metrics`、AI 请求摘要与恢复审计日志 | 能支持策略命中率、浏览器占比、重试效果、留存清理与报告质量统计;关键动作具备审计追溯能力 | 指标完整性测试、审计日志测试 |
### 6.6 `S5` 稳定性、性能、试运行与发布准备
阶段目标:把系统从“能跑”推进到“可试运行、可排障、可热修”。
| 编号 | 任务 | 责任角色 | 前置依赖 | 主要产出 | 验收标准 | 测试门禁 |
| --- | --- | --- | --- | --- | --- | --- |
| `S5-01` | 平台级定向重试稳定化 | 后端、平台、自动化 | `S3-05``S4-02``S4-04` | 失败/阻塞平台定向重试、重试幂等保护、结果差异检测接入既有版本规则 | 仅 `SearchBlocked``Blocked``Failed` 可重试;已成功平台不被误重跑;结果变化时沿用既定版本规则生成新版本 | 重试规则测试、重试范围测试、幂等性测试 |
| `S5-02` | 性能与成本优化 | 后端、平台、数据AI | `S4-06` | 限流、并发、评论分页、缓存、浏览器占比优化 | 任务时长 `P50 <= 20 分钟`;全量浏览器兜底占比 `<= 30%` | 性能基准测试、指标对账测试 |
| `S5-03` | UAT 与试运行任务集执行 | 产品、QA、前端、后端 | `S5-01``S5-02` | UAT 用例、试运行记录、问题清单 | 达到“报告可用于决策 >= 4/5”“报告采纳率 >= 70%” | 三条主链路 E2E、人工验收记录 |
| `S5-04` | 部署、值守、排障与热修手册落地 | 后端、自动化、QA | `S4-06` | 部署说明、回滚策略、值守流程、热修策略 | 形成内部受控环境发布包;明确按平台、按能力热修方式 | 预发布冒烟测试、回滚演练 |
| `S5-05` | 最终验收与文档同步收口 | 产品、设计、前端、后端、QA | `S5-03``S5-04` | P0 验收清单、偏差记录、必要文档回写 | 所有 P0 验收项通过;实现偏差已同步回上游文档 | P0 总体验收清单、文档一致性检查 |
## 7. 横向持续任务
以下任务不属于单一阶段,应从 `S0` 持续到 `S5`
| 编号 | 任务 | 责任角色 | 执行时机 | 产出与要求 |
| --- | --- | --- | --- | --- |
| `X-01` | 上下游文档变更同步 | 产品、设计、前端、后端 | 任何上游文档修改后 | 检查 `PRD``FeatureSummary``DevelopmentPlan``UIDesign``tdd``tasks``TODO.md` 是否失效,必要时同步修订 |
| `X-02` | 安全与合规检查 | 后端、自动化、QA | 每阶段出口前 | 确认不保存账号密码、会话加密、日志脱敏、仅抓取有权访问的数据 |
| `X-03` | 测试资产维护 | QA、平台、自动化 | 每新增平台能力或异常样本时 | 补齐 fixture、HAR、UI 状态快照、报告快照样本 |
| `X-04` | 设计一致性与可访问性检查 | 设计、前端、QA | 每个页面进入联调前 | 对照 `UIDesign.md` 检查状态语义、组件一致性、`WCAG AA``aria-live` |
| `X-05` | 观测指标复盘 | 产品、后端、平台、QA | 每阶段结束时 | 复盘 `strategy_attempts`、平台成功率、浏览器兜底占比、报告质量与重试效果 |
## 8. P0 验收映射
| P0 能力 | 对应任务 |
| --- | --- |
| 新建任务页 | `S1-04``S1-05``S1-07` |
| 创建前会话准备入口 | `S1-06``S1-07` |
| 天猫、京东站内搜索 | `S0-01``S2-01``S3-01` |
| 候选结果展示与人工确认 | `S2-02``S3-04` |
| 登录态校验与人工阻塞处理 | `S1-06``S3-02``S3-03` |
| 商品信息抓取 | `S2-03``S3-01` |
| 评论分层抽样抓取 | `S2-04``S3-01` |
| 数据标准化 | `S2-05``S4-01` |
| 多链接三级聚合 | `S4-01` |
| 结构化 AI 报告 | `S4-02``S4-03` |
| 历史任务回看与版本切换 | `S4-02``S4-04` |
| 历史任务删除 | `S4-04``S4-05` |
| 平台级重试 | `S3-05``S4-04``S5-01` |
| 留存与删除 | `S4-05` |
| 观测与试运行 | `S0-06``S1-02``S4-06``S5-02``S5-03` |
## 9. 非本阶段任务
以下任务明确不进入当前开发周期,仅作为后续版本储备:
| 项目 | 说明 |
| --- | --- |
| Markdown / PDF 导出 | 属于 P1不纳入当前任务拆解 |
| 淘宝、抖音电商及更多平台接入 | 当前不排期 |
| 多租户 / 团队协作 / SaaS 化 | 当前不排期 |
| 持续监控、自动巡检、定时重跑 | 当前不排期 |
| 更复杂的证据截图系统和 BI 可视化 | 当前不排期 |
## 10. 一句话结论
本轮开发任务应严格围绕 P0 闭环展开:先冻结双平台能力矩阵和测试资产,再搭骨架与单平台闭环,再扩双平台与阻塞恢复,最后补齐结构化报告、历史版本、留存删除与试运行;任何偏离这条主线的需求,都不应进入当前开发排期。项目实际执行状态、阶段快照与近期优先项统一维护在 `TODO.md`