intelligrow/cross-platform-products-ai-analyst
4
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs: 新增项目基础产品文档

Browse Source
This commit is contained in:
renzhiye 2026-04-02 16:28:44 +08:00
parent ba9a12a4b3
commit 02ec7c3a03
14 changed files with 4841 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -168,3 +168,7 @@ cython_debug/
# option (not recommended) you can uncomment the following to ignore the entire idea folder. # option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/ #.idea/
# Local tooling artifacts
.playwright-mcp/
.codex-config.staged.toml

94
AGENT.md Normal file
View File

@ -0,0 +1,94 @@
# Repository Guidelines
## Repository Mode
本仓库采用“文档驱动 + 多 AI 交叉审阅 + 人工终审 + 审阅通过后再开发”的工作流。所有核心产品文档统一存放在 `docs/`，默认使用中文撰写；如无必要，不要中英文混写。
## Required Documents
新产品默认必须产出以下文档，并按固定文件名维护：
- `docs/RequirementsDoc.md`
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/DevelopmentPlan.md`
- `docs/UIDesign.md`
- `docs/tdd.md`
- `docs/tasks.md`
可选文档按需要补充：
- `docs/Page_Design.md`
- `docs/User_Role_Interfaces.md`
- `docs/Responsive_Design.md`
命名统一使用 `RequirementsDoc.md`，不要混写为 `RequirementDoc.md`。
## Stage Workflow
每个阶段都必须先产出文档，再完成三方 AI 审阅，最后由人工终审。当前阶段未审完，不进入下一阶段。
1. 需求阶段：整理需求，产出 `docs/RequirementsDoc.md`。若使用 Claude Code，优先使用 `AskUserQuestion` 补齐需求缺口；其他代理也必须先澄清关键模糊点。
2. PRD 阶段：基于 `docs/RequirementsDoc.md` 产出 `docs/PRD.md`。若使用 Claude Code，此阶段必须开启 plan mode。
3. 功能阶段：基于 `docs/PRD.md` 产出 `docs/FeatureSummary.md`。
4. 开发规划阶段：基于 `docs/PRD.md` 与 `docs/FeatureSummary.md` 产出 `docs/DevelopmentPlan.md`，覆盖技术选型、开发周期、MVP 范围。
5. UI 设计阶段：基于 `docs/PRD.md`、`docs/FeatureSummary.md`、`docs/DevelopmentPlan.md` 产出 `docs/UIDesign.md`。优先使用 Gemini 3 Pro；若使用 Claude Code，则优先启用 frontend design skill。
6. TDD 阶段：基于 `docs/PRD.md`、`docs/FeatureSummary.md`、`docs/DevelopmentPlan.md`、`docs/UIDesign.md` 产出 `docs/tdd.md`。
7. 任务拆解阶段：基于 `docs/PRD.md`、`docs/FeatureSummary.md`、`docs/DevelopmentPlan.md`、`docs/UIDesign.md`、`docs/tdd.md` 产出 `docs/tasks.md`。
8. 开发阶段：只有在上述文档全部完成并通过审阅后，才开始编码。优先使用 Claude Code Opus 4.5；若不可用，则由 Codex 接续执行。
## Review Workflow
每份核心文档都必须经过 Claude、Gemini、Codex 三方审阅。三方审阅完成后，再由人工做一轮终审，确认是否进入下一阶段。
审阅文件建议独立保存，命名统一为：
- `docs/review-<DocName>-claude.md`
- `docs/review-<DocName>-gemini.md`
- `docs/review-<DocName>-codex.md`
审阅重点必须放在以下内容：
- 需求遗漏或前后矛盾
- 验收标准是否缺失
- 技术与实现风险是否明确
- 上下游文档是否闭环
- 是否存在无法执行或无法验证的描述
不要只做语气润色或表面改写。
## Change Propagation
上游文档变更后，必须同步检查下游文档是否失效。例如 `RequirementsDoc.md` 更新后，必须重新检查 `PRD.md`、`FeatureSummary.md`、`DevelopmentPlan.md`、`UIDesign.md`、`tdd.md`、`tasks.md` 是否仍然一致。禁止只改上游、不处理影响面。
## Agent Rules
在本仓库中，AI 代理不应跳过文档阶段直接写代码。即使用户要求尽快开发，也应先确认核心文档是否齐全。
对 Claude Code 的专属要求：
- 需求阶段优先使用 `AskUserQuestion`
- PRD 阶段开启 plan mode
- UI 设计阶段优先 frontend design skill
对 Gemini、Codex 等其他代理，执行同样的文档产出标准与评审门禁。
## Git Commit Rules
当用户要求提交代码时，代理应在确认变更范围和内容正确后，直接完成 `git add` / `git commit`，不要只停留在提示层。
提交信息规则如下：
- 必须使用中文描述
- 必须使用常见类型前缀：`feat`、`fix`、`docs`、`chore`、`refactor`、`test`、`style`、`build`、`ci`
- 推荐格式：`<type>: <中文摘要>`
- 一次提交只处理一个清晰主题，避免把文档、代码、重构、测试混在同一个提交里
示例：
- `feat: 新增跨平台商品分析任务创建流程`
- `fix: 修复评论抓取分页状态丢失问题`
- `docs: 补充 PRD 验收标准与任务拆解约束`
- `chore: 调整本地开发配置与脚本入口`
## Pre-Commit Checklist
提交前至少确认以下事项：
- 变更是否与当前阶段目标一致
- 文档与代码是否仍然相互对应
- 是否遗漏下游文档同步
- 是否混入无关改动
- 提交信息是否符合中文 Conventional Commit 规范

204
docs/CrawlerFeasibility.md Normal file
View File

@ -0,0 +1,204 @@
# 当前阶段平台爬虫可行性评估（天猫 / 京东）
- 文档状态：Draft
- 版本：v0.5
- 更新时间：2026-04-02
- 关联文档：
- `docs/RequirementsDoc.md`
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/DevelopmentPlan.md`
## 1. 评估目的
本文件用于回答当前阶段最关键的技术问题：在不依赖官方开放平台、且不把完整浏览器自动化作为默认主路径的前提下，天猫和京东的商品搜索、详情抓取与评论抓取，是否可以形成可持续、可恢复、可观测的稳定交付链路。
本轮评估采用以下边界：
1. 当前实现范围只包含天猫与京东。
2. 淘宝作为下一优先平台，放入后续扩展规划。
3. 抖音电商暂不进入当前实现阶段，只保留风险结论。
4. 评估以 2026-04-02 的实时页面与请求链路观察为准，不以官方开放平台能力作为唯一交付前提。
5. 最终判断标准不是“是否单次抓通”，而是“是否能形成可维护、可恢复、可审计的稳定交付能力”。
6. 若稳定交付必须依赖客户端上下文模拟或私有签名复现，这种依赖应被显式写入方案，而不是在评估阶段被默认排除。
7. 在授权会话与治理边界内，应尽可能探索一切可实现且可维护的路径，包括尽量对齐真实网页端搜索、跳转、查看与上下文建立行为，以提升链路稳定性并降低异常判定。
## 2. 最新范围结论
当前阶段的结论可以直接收敛为六点：
1. 天猫和京东都存在可行的非浏览器主路径，但这个“非浏览器”不是匿名静态 HTTP，而是“服务端会话驱动的同构请求回放 + Hydration 解析”。
2. 从交付视角，平台是否可做，取决于会话获取、模板刷新、阻塞恢复和观测告警能否一起做成工程能力，而不是是否存在一次性可用链路。
3. 浏览器仍然必要，但应被定义为受控恢复通道：负责登录、验证码、模板刷新、风控恢复和接口发现，不应承接常规搜索、详情和评论吞吐。
4. 若稳定交付依赖“客户端上下文模拟（含设备指纹相关字段补齐）”或“私有签名复现”，这些能力应被定义为受限工程依赖；它们不等于绕过登录，但会显著提高维护成本、漂移风险和治理要求。
5. 工程实施不应过早锁死为单一路径，而应并行探索请求回放、Hydration、受控浏览器、客户端上下文补齐与行为一致性调度等路线，最后以成功率、恢复成本和可治理性收敛。
6. 淘宝应作为下一优先扩展平台，因为天猫 PC 搜索实际已落在淘宝搜索与 `mtop/h5api` 基础设施之上，后续复用价值高。
7. 抖音电商当前阶段应延后实现；理由不是“永远不可做”，而是网页链路不清晰、成本高、与当前双平台闭环目标不一致，现阶段不适合承诺稳定交付。
补充说明：
1. 本文所说“同构请求”指尽量对齐平台页面真实请求族、Header、Cookie、动态参数和调用节奏。
2. 本文允许使用授权会话、模板回放、Hydration、受控浏览器恢复等工程手段，以稳定交付为目标。
3. “客户端上下文模拟（含设备指纹相关字段补齐）”与“私有签名复现”不应被直接等同于绕过登录；前提仍是用户正常登录并在授权会话内运行。
4. 但这类能力不应被包装成低维护、低风险能力，而应明确标记为受限工程依赖，单独承担版本漂移、恢复、审计和人工介入成本。
5. 若某平台关键动态参数无法在授权会话内通过现有上下文或受限工程依赖稳定刷新，应直接判定为 `Blocked` 或 `NotCommittable`，而不是继续对外承诺稳定交付。
6. 本文所说“行为一致性”指尽量对齐真实网页端入口、导航顺序、请求上下文、停留节奏和查看链路，以减少异常流量特征并提升链路稳定性。
## 3. 实时验证与证据
### 3.1 天猫
实时观察：
1. `https://www.tmall.com/robots.txt` 返回 `User-agent: *`、`Disallow: /*?*`。
参考：<https://www.tmall.com/robots.txt>
2. `https://list.tmall.com/robots.txt` 对通用抓取客户端返回 `User-agent: *`、`Disallow: /`。
参考：<https://list.tmall.com/robots.txt>
3. 2026-04-02 的实时页面测试中，PC 搜索实际落在 `https://s.taobao.com/search?q=iPhone%2015&tab=mall`。
4. 同次测试里，页面请求链路出现 `https://h5api.m.taobao.com/h5/...` 的多个 `mtop` 请求，且伴随 `sign`、`t`、`appKey=12574478`、`umidtoken`、`bx-ua`、`bx-et` 等动态参数。
判断：
1. 天猫搜索并不是一个“独立、稳定、静态”的天猫专属 HTTP 页面抓取问题，而是淘宝/天猫共用 H5API 基础设施的问题。
2. 因此天猫更适合走“会话驱动的请求回放”而不是“直接抓列表 DOM”。
3. 这也意味着后续接入淘宝时，可直接复用较大比例的请求模板、参数分类逻辑和字段映射框架。
### 3.2 京东
实时观察：
1. 2026-04-02 对 `https://search.jd.com/Search?keyword=iPhone%2015` 的实时测试中，页面直接跳转到 `passport.jd.com` 登录页。
2. 对 `https://item.jd.com/100068388535.html` 的实时测试中，页面同样跳转到登录页。
3. 但在商品页初始化请求链路里，仍可观察到 `api.m.jd.com` 的 PC 商品接口调用，例如 `functionId=pc_detailpage_wareBusiness`，并伴随 `h5st`、`x-api-eid-token`、`uuid` 等参数。
4. 同时可观察到 `cactus.jd.com/request_algo`、`jra.jd.com/jsTk.do`、`sgm-w.jd.com/h5` 等风控/参数初始化请求。
5. `https://item.jd.com/robots.txt` 的公开信息非常有限，不能据此推断搜索或详情路径可稳定匿名抓取。
参考：<https://item.jd.com/robots.txt>
判断：
1. 京东 PC 端存在明确的接口层，不是只能靠浏览器 DOM 抓。
2. 但接口调用明显依赖会话与动态参数上下文，不能把它当作无状态公开接口。
3. 京东的非浏览器路线是可行的，但必须建立在“先会话、后请求”的体系上。
### 3.3 淘宝
当前不进入实现，但应提前写入路线图：
1. 天猫搜索已实质依赖淘宝搜索与 `mtop/h5api` 请求族。
2. 因此淘宝不是一条全新技术线，而更像是天猫适配栈的横向扩展。
3. 这也是把淘宝放在抖音之前的主要原因。
### 3.4 抖音电商
当前阶段不进入实现，保留结论如下：
1. 网页链路与电商域链路边界不清晰。
2. 风控、动态参数和稳定回放成本明显高于当前双平台路线。
3. 即使未来要做，也不应阻塞当前天猫 / 京东闭环。
## 4. 非浏览器方案可行性判断
### 4.1 平台能力矩阵
| 平台 | 当前阶段定位 | 搜索 | 详情 | 评论 | 推荐主路径 | 结论 |
| --- | --- | --- | --- | --- | --- | --- |
| 天猫 | 当前 MVP | 中高 | 中高 | 中 | `L0 会话驱动请求回放 + L1 Hydration` | 可做，但必须接受其底层是淘宝/天猫共用请求体系 |
| 京东 | 当前 MVP | 中 | 中高 | 中 | `L0 会话驱动请求回放 + 登录前预检查` | 可做，但搜索和详情都受会话、风控和动态参数强约束 |
| 淘宝 | 下一优先平台 | 中高 | 中高 | 中 | 复用天猫适配栈 | 适合在双平台闭环稳定后接入 |
| 抖音电商 | 当前延后 | 低 | 低到中 | 低 | 暂不进入当前实现 | 不纳入当前排期 |
### 4.2 当前阶段默认 `delivery_requirement`
| 平台 | 暂定值 | 原因 |
| --- | --- | --- |
| 天猫 | `required` | 稳定交付不应依赖匿名链路的偶然可用性，会话、模板刷新与恢复闭环必须前置 |
| 京东 | `required` | 当前实时环境下搜索和详情都触发登录页，会话前置是硬要求 |
| 淘宝 | `required` | 作为后续平台，预计与天猫相似，若进入排期也应按稳定交付标准要求会话优先 |
| 抖音电商 | `not_committable` | 当前阶段缺少低风险、可维护的稳定链路，不应承诺交付 |
补充说明：
1. `required` 不等于只能使用纯 HTTP 回放，也允许在授权会话内接入受限工程依赖以补齐客户端上下文或签名能力。
2. 但一旦引入受限工程依赖，就必须额外满足隔离部署、版本控制、回归验证、审计留痕和快速熔断。
## 5. 关键难点
当前真正的难点不在“能不能发 HTTP 请求”，而在以下十件事：
1. 会话依赖：两个平台都不能假设匿名链路稳定，必须先解决会话获取、保存、校验和失效恢复。
2. 动态参数生命周期：天猫的 `sign/umidtoken/bx-*` 与京东的 `h5st/x-api-eid-token` 都不是静态模板字段，需要区分哪些是会话级、哪些是请求级、哪些是短时有效。
3. 模板热更新：请求模板一旦漂移，系统要能快速重新采样、比对和刷新，而不是整条链路报废。
4. 域名与上下文一致性：天猫与淘宝跨域，京东详情、登录、风控接口分散在不同域名，请求上下文不能只看单接口。
5. 评论分页吞吐：评论抓取若退化为浏览器滚动，整体时长会迅速失控，因此评论能力必须坚持 HTTP 主路径。
6. 阻塞识别与恢复：跳登录、验证码、风控、参数失效都要被产品化为显式状态，而不是笼统记为失败。
7. 可观测性：成功率、阻塞率、模板漂移率、恢复耗时和人工介入频次都必须可量化，否则无法承诺稳定交付。
8. 交付边界：若某平台只能维持“可探索”而不能维持“可恢复、可审计、可持续”的能力，应主动降级为研究态，而不是继续保留在承诺范围内。
9. 受限工程依赖治理：若引入客户端上下文模拟或私有签名复现，必须把依赖模块隔离、版本化、监控化，并明确人工接管和熔断条件。
10. 行为一致性调度：搜索、翻页、进详情、看评论、回退或继续浏览等动作若与真实网页端上下文脱节，链路稳定性会明显下降，因此需要单独设计调度与验证策略。
## 6. 具体实施计划
### 6.1 技术路线
当前阶段推荐的统一技术路线如下：
1. 服务端会话中心：统一保存各平台授权会话、有效期、最近校验结果和阻塞标记。
2. 请求模板实验室：保存 `HAR`、请求样本、参数分类、响应 Schema 和最近一次成功模板。
3. 适配器按能力拆分：每个平台至少拆成 `precheck`、`search`、`detail`、`reviews` 四个模块。
4. 默认主路径走 HTTP：搜索、详情、评论都先走会话驱动的请求回放或 Hydration 解析。
5. 浏览器做受控恢复通道：登录、验证码、模板刷新、风控恢复、接口发现都可通过浏览器完成，但必须可调度、可观测、可限流，不承接常规抓取吞吐。
6. 若项目明确接受高维护路径，则增加受限工程依赖层：单独承接客户端上下文模拟、签名复现或其他必须的客户端能力补齐，并与主采集链路隔离。
7. 增加稳定性交付控制面：统一暴露健康检查、模板版本、成功率、阻塞率、恢复队列和自动降级策略。
8. 增加行为一致性策略层：按平台沉淀入口选择、搜索后详情访问顺序、分页节奏、停留窗口和上下文延续规则，并以数据回放持续验证。
### 6.2 Phase 0：两周 PoC
天猫：
1. 固化搜索请求族和关键参数分类，验证是否能形成可复用的短期模板。
2. 验证详情页首屏字段是否可通过 `Hydration` 直接解析，必要时补接口回放。
3. 验证评论路径是否可在同一会话体系下稳定分页取样。
4. 对比不同搜索入口、列表到详情跳转方式和上下文建立方式对成功率与阻塞率的影响，沉淀行为一致性策略。
京东：
1. 固化登录前预检查规则，确保搜索前先判断是否可执行。
2. 验证详情接口族是否可以稳定返回商品核心字段。
3. 验证评论路径是否能形成统一的分页模板和错误分类。
4. 验证搜索、详情、评论之间的访问顺序和上下文延续是否影响稳定性，并沉淀最优调度策略。
通用：
1. 建立 `Blocked` 与交付状态分类：`NeedLogin`、`NeedVerify`、`TemplateExpired`、`RiskIntercepted`、`SchemaDrift`，以及不进入承诺范围的 `NotCommittable`。
2. 建立 `strategy_attempts` 记录每次尝试的路径、耗时、结果与恢复动作。
3. 建立模板刷新机制：手动登录或恢复后自动重新抓一份样本，更新请求模板。
4. 建立稳定性回归任务：按天回放核心链路，记录模板漂移、阻塞占比和恢复成功率。
5. 识别哪些链路依赖受限工程依赖，并分别记录其版本、漂移频率、人工维护成本和失效影响面。
6. 建立行为一致性实验记录：比较不同入口、动作序列和停留节奏对成功率、阻塞率和恢复成本的影响。
### 6.3 PoC 退出条件
至少一个当前 MVP 平台同时满足以下条件，才进入正式闭环开发：
1. 搜索候选返回成功率不低于 `80%`，且统计口径覆盖连续 `200` 次任务；`Blocked`、`NoResult` 记为可解释结果。
2. 商品详情必填字段完整率不低于 `85%`。
3. 评论样本抓取达到每链接 `50` 条时，单链接耗时不高于 `90s`。
4. 连续运行 `7` 天或 `200` 次任务，结构化字段漂移率不高于 `10%`，且不存在需要人工临时修补的系统性失败。
5. `TemplateExpired`、`NeedLogin`、`RiskIntercepted` 等常见阻塞具备明确恢复动作，恢复成功率不低于 `70%`，单次恢复时长不高于 `30min`。
6. 浏览器直接承接数据抓取的占比不高于 `20%`，且浏览器恢复任务本身具备成功率与耗时监控。
7. 若平台稳定性依赖受限工程依赖，则该依赖的版本切换、回归验证、审计留痕和一键熔断必须先通过演练。
8. 若平台稳定性明显依赖行为一致性策略，则该策略必须完成 A/B 回放验证，并能被配置化管理与快速回退。
## 7. 对文档的强制影响
本次评估要求上游文档统一以下口径：
1. 当前 MVP 平台范围只包含天猫和京东。
2. 淘宝写入下一优先扩展平台，而不是继续放在“其他平台”里。
3. 抖音电商写入延后实现，不进入当前排期和验收。
4. 当前主采集路径明确为“服务端会话驱动的 HTTP 请求回放 + Hydration 解析”。
5. 受控浏览器写成登录、模板刷新和阻塞恢复能力，而不是默认数据采集主通路。
6. 所有上游文档应把“稳定交付”而不是“单次抓通”作为验收口径。
7. 若某条交付链路依赖客户端上下文模拟、私有签名复现或其他受限工程依赖，必须在上游文档中显式写明，而不是继续沿用“纯 HTTP 回放”口径。
8. 任何高维护依赖若缺少版本控制、观测、审计、熔断和人工接管预案，仍不应进入承诺交付范围。
9. 上游文档应明确写入“尽可能探索所有可实现路径并优先选择与真实网页端行为一致的稳定方案”，但不得把不可治理的偶发链路包装成可承诺能力。

653
docs/DevelopmentPlan.md Normal file
View File

@ -0,0 +1,653 @@
# 跨平台商品聚合与 AI 分析开发计划
- 文档状态：Draft
- 版本：v0.6
- 更新时间：2026-04-02
- 依据文档：
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/CrawlerFeasibility.md`
- 本版说明：
- 本版继续采用“前端负责交互，采集执行统一在后端服务器”的基线。
- 本版当前 MVP 平台范围固定为“天猫 + 京东”，淘宝保留为下一优先扩展平台。
- 本版明确采集路线为“会话驱动请求回放优先，受控浏览器只负责会话与模板刷新”。
## 1. 文档目标
本文件用于把 `PRD` 和 `FeatureSummary` 中已经明确的产品边界，转换为研发可执行、可验证、可排期的开发方案。
### 1.1 本文回答什么
| 主题 | 需要回答的问题 | 输出形式 |
| --- | --- | --- |
| 架构形态 | 采集执行放在哪里，系统怎么拆层 | 架构图、分层表 |
| 采集路线 | 搜索、详情、评论分别优先走什么路径 | 采集分层表、路由规则 |
| 实施拆分 | 工程模块怎么拆，优先级怎么定 | 模块表、阶段计划 |
| 发布门槛 | 什么叫研发上可发布、可试运行 | 验收口径、观测指标 |
### 1.2 开发计划速览
| 项目 | 当前结论 |
| --- | --- |
| 交付目标 | 稳定产出可回溯的结构化报告 |
| 首版平台 | 天猫、京东 |
| 主体架构 | Web 工作台 + API/BFF + 任务编排 + API Worker + Browser Worker |
| 默认采集主路 | `L0 Replay` / `L1 Hydration` |
| 浏览器角色 | 登录、模板刷新、验证码与恢复，不作为默认主吞吐路径 |
| 队列与状态 | `PostgreSQL + Redis + BullMQ` |
| MVP 周期建议 | 12 周 |
### 1.3 总体架构概览
```mermaid
flowchart LR
A[Web 工作台] --> B[API / BFF]
B --> C[任务编排层]
C --> D[API 采集 Worker]
C --> E[Browser Recovery Worker]
D --> F[标准化与聚合]
F --> G[AI 报告模块]
E --> H[会话中心]
D --> I[(PostgreSQL)]
D --> J[(Object Storage)]
C --> K[(Redis / BullMQ)]
G --> I
H --> I
```
对应 ASCII 视图：
```text
Web 工作台
|
v
API / BFF
|
v
任务编排层 ----> Redis / BullMQ
| \
| \--> Browser Worker ----> 会话中心
|
\----> API Worker ---------> 标准化 / 聚合 ---------> AI 报告
\ /
\----> PostgreSQL / Object Storage
```
## 2. 开发目标与范围
### 2.1 MVP 交付目标
MVP 目标不是单纯跑通抓取链路，而是稳定产出可回溯的结构化报告。
| 闭环环节 | 交付目标 |
| --- | --- |
| 任务发起 | 用户通过 Web 工作台创建任务，输入关键词和评论抽样配置 |
| 搜索与确认 | 系统在后端服务器对天猫、京东执行预检查和站内搜索，用户完成逐平台确认 |
| 抓取与处理 | 服务端完成商品抓取、评论抽样、标准化和三级聚合 |
| 分析与报告 | AI 按固定 Schema 输出报告，并保留证据索引 |
| 回看与重试 | 用户可回看历史任务、切换版本，并对失败平台发起定向重试 |
| 阻塞恢复 | 用户可通过远程受控浏览器处理登录、验证码或风控阻塞 |
### 2.2 P0 范围
| 范围 | 内容 |
| --- | --- |
| 前台能力 | Web 工作台、候选确认、执行页、报告页、历史任务页 |
| 任务执行 | 双平台搜索前预检查、候选搜索与展示 |
| 平台交互 | 平台内单选、多选、跳过 |
| 会话与恢复 | 服务端会话中心、平台阻塞识别、人工恢复入口 |
| 数据采集 | 商品信息抓取、评论分层抽样抓取 |
| 数据处理 | 商品表、评论表标准化、三级聚合 |
| 报告 | AI 结构化报告与证据索引 |
| 运维能力 | 失败平台重试、报告版本切换、30/90 天留存、任务级删除 |
| 策略能力 | 采集策略中心、平台能力矩阵、API 优先路由机制 |
### 2.3 明确延后到 P1 的能力
| 延后项 | 说明 |
| --- | --- |
| Markdown / PDF 导出 | 不进入首版开发周期 |
| 自动巡检 / 定时重跑 / 持续监控 | 不进入 P0 |
| 淘宝接入与更多平台扩展 | 延后 |
| 更复杂的运营建议模板和可视化图表 | 延后 |
| 多租户 SaaS 化 | 延后 |
| 更细粒度的证据截图系统和审计看板 | 延后 |
| 更复杂的工作流编排 | 延后 |
## 3. 核心技术路线决策
### 3.1 核心决策总表
| 决策项 | 当前结论 | 原因 |
| --- | --- | --- |
| 采集执行位置 | 全部在后端服务器执行 | 便于统一治理限流、会话、热修、审计和排障 |
| 用户入口 | 统一 Web 工作台 | 用户只处理交互和必要人工恢复 |
| 默认抓取路线 | API / Hydration 优先 | 成本更低、吞吐更高、可观测性更强 |
| 浏览器角色 | 登录、模板刷新、恢复和极端兜底 | 浏览器成本高，不适合当默认主路径 |
| 队列编排 | `PostgreSQL + Redis + BullMQ` | 足以支撑 MVP 的异步执行、重试和并发 |
| AI 输出形态 | 受控 JSON Schema | 避免自由文本不可验证、不可稳定消费 |
### 3.2 MVP 首发运行方式
| 项目 | 口径 |
| --- | --- |
| 部署环境 | 内部受控服务器 |
| 用户访问方式 | 浏览器访问统一 Web 工作台 |
| 服务端进程 | API 服务、任务队列、采集 Worker、浏览器 Worker |
| 元数据存储 | `PostgreSQL` |
| 队列 | `Redis` |
| 原始产物 | 对象存储 |
| 浏览器 Worker | 独立隔离环境，支持远程人工介入 |
| 发布策略 | 单租户、内部小范围试运行，不直接做开放 SaaS |
### 3.3 架构分层
| 层级 | 职责 | 建议技术 |
| --- | --- | --- |
| Web 前端层 | 任务页、候选确认页、执行页、报告页、历史页、会话准备/恢复入口 | React + TypeScript |
| API / BFF 层 | 任务 API、查询 API、SSE 推送、权限与审计入口 | Node.js + Fastify |
| 任务编排层 | 队列、状态机、平台级并发控制、重试与版本计算 | BullMQ + Redis |
| 采集策略层 | 路由选择、能力矩阵、降级决策、健康度管理 | TypeScript 内部模块 |
| API 采集 Worker | 搜索、商品详情、评论接口调用与回放 | Node.js + undici |
| 浏览器兜底 Worker | 登录处理、接口发现、受控浏览器抓取、人工恢复 | Playwright |
| 会话中心 | 会话快照、加密存储、有效期校验、人工接管 | 服务端加密模块 |
| 数据层 | 任务状态、原始数据、标准化数据、报告快照、证据索引 | PostgreSQL + 对象存储 |
| AI 分析模块 | 结构化分析请求、模型路由、Schema 校验、日志 | Fastify 内部模块 |
### 3.4 关键设计原则
| 原则 | 说明 |
| --- | --- |
| 抓取只在后端执行 | 不在用户设备执行自动化 |
| 搜索/详情/评论默认走接口路径 | 浏览器只在必要时介入 |
| 平台能力按“平台 x 能力”管理 | 不能笼统写成“某平台使用 Playwright” |
| 状态流转必须持久化 | 不能只存在内存里 |
| 会话、业务数据、原始产物、审计日志分层存储 | 降低耦合与风险 |
| AI 输出必须受控 Schema | 禁止自由文本直出报告 |
| 优先切换策略，不优先判死任务 | 提升可恢复性 |
| 浏览器属于高成本路径 | 必须纳入占比和命中率约束 |
## 4. 核心采集方案
### 4.1 四层采集模型
steady-state 目标明确是“非浏览器数据通路”。
| 层级 | 路径 | 典型用途 | 速度 | 成本 | 说明 |
| --- | --- | --- | --- | --- | --- |
| L0 | 会话驱动的同构请求回放 | 搜索、详情、评论分页 | 最高 | 最低 | 服务端 HTTP 客户端复用真实请求族、Cookie 和必要动态参数 |
| L1 | HTML / SSR / Hydration 解析 | 商品基础信息、候选列表、首屏数据 | 高 | 低 | 适合页面首屏自带结构化数据的场景 |
| L2 | 模板刷新后请求回放 | 请求模板失效、动态参数补齐、接口发现 | 中 | 中 | 浏览器只用于刷新模板和参数，数据主体仍通过 HTTP 拉取 |
| L3 | 受控浏览器恢复 | 登录、验证码、风控处理、极端诊断 | 最低 | 最高 | 只用于会话恢复和极端排障，不作为常规抓取吞吐路径 |
### 4.2 能力级路由策略
| 能力 | 默认路径 | 第一降级 | 最终兜底 | 说明 |
| --- | --- | --- | --- | --- |
| 搜索 | `L0 Replay` | `L1 Hydration` 或 `L2 Template Refresh` | `L3 Browser Recovery` | 默认以真实请求回放为主，不把浏览器 DOM 当主路径 |
| 商品详情 | `L1 Hydration` 或 `L0 Replay` | `L2 Template Refresh` | `L3 Browser Recovery` | 优先抓结构化字段和业务接口 |
| 评论 | `L0 Replay` | `L2 Template Refresh` | `L3 Browser Recovery` | 评论分页吞吐要求高，必须坚持 HTTP 主路径 |
| 登录与会话恢复 | `L3 Browser Recovery` | 无 | 无 | 浏览器的核心职责之一 |
| 风控/验证码恢复 | `L3 Browser Recovery` | 无 | 无 | 需要用户人工介入 |
补充要求：
| 要求 | 说明 |
| --- | --- |
| 平台默认路径不是静态承诺 | 以当前阶段基线可行性矩阵为准 |
| 每个平台在 Phase 0 必须产出能力矩阵 | 至少包含搜索/详情/评论默认路径、登录依赖、签名/Token、回放支持、浏览器兜底成本 |
### 4.2.1 当前阶段基线可行性矩阵
基于 `docs/CrawlerFeasibility.md` 在 2026-04-02 的调研结果：
| 平台 | 当前阶段定位 | `search_requirement` 暂定值 | 搜索默认路径 | 详情默认路径 | 评论默认路径 | 研发结论 |
| --- | --- | --- | --- | --- | --- | --- |
| 天猫 | 当前 MVP 平台 | `recommended` | `L0 Replay`，必要时 `L2` | `L1` 或 `L0` | `L0`，必要时 `L2` | 搜索实际落在淘宝/天猫同构请求链路，浏览器只负责会话与模板刷新 |
| 京东 | 当前 MVP 平台 | `required` | `L0 Replay + Precheck`，必要时 `L3` | `L0` 或 `L1` | `L0`，必要时 `L2` | 详情接口层可见，但会话与风控前置约束强，需先完成会话中心 |
后续平台观察：
| 平台 | 当前判断 |
| --- | --- |
| 淘宝 | 下一优先平台，预期复用天猫 `L0/L2` 适配栈，但不进入当前 MVP 排期 |
| 抖音电商 | 当前阶段不排期，不进入当前验收 |
工程约束：
| 约束 | 说明 |
| --- | --- |
| 不允许把“浏览器抓通再优化”作为默认前提 | 天猫与京东必须先按非浏览器路线做闭环 |
| 关键动态参数无法在授权会话内刷新时 | 直接判定为 `Blocked` |
| 双平台需要并行勘探 | Phase 0 结束时用量化指标决定是否进入完整闭环开发 |
### 4.3 路由选择与降级规则
```mermaid
flowchart TD
A[读取能力矩阵 + 健康度 + 会话状态] --> B[选择默认路径]
B --> C{默认路径成功?}
C -->|是| D[记录成功路径并继续]
C -->|否| E{错误是否可切换?}
E -->|否| F[按错误类型落状态]
E -->|是| G[降级到下一层策略]
G --> H{是否已到 L3?}
H -->|否| C
H -->|是| I[L3 Browser 恢复或兜底]
I --> J[记录 strategy_attempts]
```
策略中心必须显式维护以下规则：
| 规则 | 说明 |
| --- | --- |
| 每次执行先读能力矩阵、平台健康度和会话状态 | 选择默认路径 |
| 只有“可切换”的错误类型才降级 | 避免无脑切浏览器 |
| `401` / 会话失效 / 验证码 / 风控拦截 | 优先归类为 `Blocked` |
| `Schema` 漂移 / 接口字段缺失 / Token 失效 | 可以优先切到 `L2` |
| 只有前三级策略都不可行 | 才进入 `L3 Browser` 全量兜底 |
| 任一路径成功后 | 记录为该平台该能力的最新可用策略 |
### 4.4 服务端受控浏览器方案
受控浏览器定义为“服务端浏览器实例 + 前端远程接管入口”，不承担常规搜索、详情、评论抓取吞吐。
恢复流程：
```mermaid
flowchart TD
A[用户点击处理登录/恢复阻塞] --> B[系统分配隔离 Browser Worker]
B --> C[生成临时会话令牌]
C --> D[前端远程接管浏览器]
D --> E[用户完成登录 / 验证码 / 风控处理]
E --> F[服务端提取并加密保存 storageState / cookies]
F --> G[任务恢复执行]
```
这样设计的原因：
| 原因 | 说明 |
| --- | --- |
| 用户只参与必须人工处理的步骤 | 不直接承担执行环境 |
| 会话、日志和浏览器版本统一治理 | 降低排障复杂度 |
| 浏览器抓取与人工恢复共享基础设施 | 提高复用率 |
### 4.5 效率优化策略
| 策略 | 说明 |
| --- | --- |
| 搜索、详情、评论分队列与并发配置 | 不共用单一串行流程 |
| 平台间允许并行 | 平台内按能力和限流策略有界并发 |
| 评论默认走接口分页或请求回放 | 不用浏览器逐页滚动加载 |
| 首屏结构化数据优先 `Hydration` | 减少浏览器渲染成本 |
| 稳定接口建立模板、Schema 与缓存 | 降低重复探测成本 |
| 浏览器 Worker 只承接登录、接口发现和极端兜底 | 控制高成本路径占比 |
| 所有策略切换记录到 `strategy_attempts` | 支撑命中率和兜底占比统计 |
## 5. 技术选型
### 5.1 Monorepo 与基础工程
推荐采用 `pnpm workspace + Turborepo` 管理多应用与共享包。
建议目录结构：
```text
.
├─ apps/
│ ├─ web/ # React + Vite 前端
│ ├─ api/ # Fastify API/BFF
│ ├─ worker-api/ # API 采集 Worker
│ └─ worker-browser/ # Browser Fallback Worker
├─ packages/
│ ├─ domain/ # 状态机、实体、类型定义
│ ├─ crawler-core/ # 策略路由、能力矩阵、公共采集能力
│ ├─ platform-adapters/ # 双平台能力实现与后续淘宝扩展
│ ├─ report-schema/ # AI 报告 Schema、验证器
│ ├─ db/ # PostgreSQL schema、迁移、查询封装
│ ├─ queue/ # 队列定义、任务类型、消费封装
│ └─ shared/ # 日志、错误码、工具函数
└─ docs/
```
选择理由：
| 理由 | 说明 |
| --- | --- |
| 类型与 Schema 复用需求高 | Web、API、Worker 共享领域模型 |
| 统一质量工具链 | 有利于统一 lint、test、build 和版本升级 |
| 平台适配和报告结构跨进程共享 | 拆仓会增加协同成本 |
### 5.2 Web 前端与 API 技术栈
| 层级 | 推荐选型 |
| --- | --- |
| Web 前端 | `React` + `TypeScript` + `Vite` + `Ant Design` |
| Web 状态 | `Zustand + TanStack Query` |
| 服务端 API | `Fastify` |
| 实时推送 | `SSE` |
选择理由：
| 技术点 | 说明 |
| --- | --- |
| React + TypeScript | 适合任务型工作台 |
| `SSE` | 足够支撑任务进度、平台状态、阻塞提示和重试结果的单向推送 |
| Fastify | 适合作为 API/BFF 和内部服务边界层 |
### 5.3 任务编排与状态机
MVP 推荐采用 `PostgreSQL + Redis + BullMQ`：
| 组件 | 作用 |
| --- | --- |
| `PostgreSQL` | 保存 `tasks`、`platform_runs`、`task_events`、`retry_logs`、`report_snapshots` 等业务状态 |
| `Redis + BullMQ` | 承担异步队列、延迟重试和 Worker 调度 |
| 三层状态模型 | 继续沿用 `task_status`、`task_stage`、`platform_status` |
| 执行模型 | 平台间并行、平台内有界并发、评论分页按平台规则限速 |
当前不引入 `Temporal` 的原因：
| 原因 | 说明 |
| --- | --- |
| 任务分支复杂度仍可控 | 当前还不需要更重的工作流引擎 |
| `BullMQ` 足以支撑 MVP | 队列、重试、分 Worker 部署都能覆盖 |
| 迁移窗口可后置 | 等 P1 出现更复杂人机协同时再评估 |
### 5.4 会话管理与安全
推荐采用“服务端会话中心 + 加密快照存储”。
| 做法 | 说明 |
| --- | --- |
| 用户只通过前端进入服务端浏览器处理登录或验证码 | 降低敏感信息扩散 |
| 仅保存最小必要会话快照 | 如 `cookies`、`storageState`、必要 Token |
| 会话快照统一 `AES-GCM` 加密 | 强化安全边界 |
| 会话元数据写入 `PostgreSQL` | 敏感正文写入对象存储或专用加密表 |
| 会话默认有效期 | 最后使用后 `24` 小时 |
| 用户可手动清除平台会话 | 必须支持 |
| 不保存账号密码 | 必须 |
### 5.5 数据存储
推荐选型：
| 类型 | 选型 |
| --- | --- |
| 关系存储 | `PostgreSQL` |
| ORM | `Drizzle ORM` |
| 队列缓存 | `Redis` |
| 对象存储 | `S3 / MinIO` |
建议核心数据表：
| 数据表 | 用途 |
| --- | --- |
| `tasks` | 任务主表 |
| `platform_runs` | 平台级执行状态 |
| `selected_links` | 已确认链接 |
| `raw_products` | 原始商品数据 |
| `raw_reviews` | 原始评论数据 |
| `normalized_products` | 标准化商品数据 |
| `normalized_reviews` | 标准化评论数据 |
| `report_snapshots` | 报告版本快照 |
| `evidence_index` | 证据索引 |
| `session_states` | 会话状态 |
| `task_logs` | 任务日志 |
| `strategy_attempts` | 策略尝试记录 |
| `artifact_refs` | 大对象产物引用 |
落盘原则：
| 类型 | 位置 |
| --- | --- |
| 原始接口响应、DOM 快照、HAR 摘要等大对象 | 对象存储 |
| 标准化字段、任务状态和可查询摘要 | `PostgreSQL` |
| 原始抓取数据 | 默认保留 30 天 |
| 标准化数据与报告 | 默认保留 90 天 |
| 用户删除与留存清理 | 属于 P0 必做能力 |
### 5.6 标准化、聚合与 AI 分析
继续采用三段式流水线：
| 阶段 | 作用 |
| --- | --- |
| `normalize` | 原始商品与评论字段映射到标准结构 |
| `aggregate` | 生成链接级、平台级、跨平台级中间视图 |
| `analyze` | 把聚合结果与证据索引送入 AI 模块，返回结构化报告 |
实施要求：
| 要求 | 说明 |
| --- | --- |
| AI 模块只接受受控 Schema | 返回 JSON 结构 |
| AI 请求只发送必要字段和证据摘要 | 控制成本与噪声 |
| 模型版本、请求摘要、校验结果、错误码都落日志 | 便于观测和追溯 |
| 报告版本切换、默认版本、旧版本回看 | 属于 P0 功能 |
### 5.7 测试与质量工具
| 类型 | 推荐选型 |
| --- | --- |
| 单元测试 | `Vitest` |
| E2E | `Playwright Test` |
| 契约测试 | 接口响应 Schema、报告 Schema、队列载荷 |
| 回放测试 | `HAR / fixture` 回放测试 |
| 代码质量 | `ESLint + Prettier` |
| CI | `GitHub Actions` |
测试分层：
| 层级 | 覆盖内容 |
| --- | --- |
| 领域层 | 状态机转移、评论抽样、聚合逻辑、报告 Schema |
| 策略层 | 路由选择、降级规则、错误分类、缓存与限流 |
| 适配层 | 平台接口 fixture、Hydration 解析、DOM 解析、HAR 回放 |
| 应用层 | 任务创建、候选确认、远程会话处理、报告回看、失败平台重试 |
| 验收层 | 至少覆盖“单平台 API 成功”“多平台部分失败”“浏览器阻塞恢复”三条主链路 |
## 6. 模块拆分与实施层级
| 模块 | 主要职责 | 优先级 |
| --- | --- | --- |
| 任务工作台 | 任务创建、候选确认、执行页、历史任务页 | P0 |
| 状态机与任务编排 | 三层状态机、队列编排、平台并发控制、重试 | P0 |
| 会话中心 | 登录入口、会话快照保存、有效期校验、手动清理 | P0 |
| 采集策略中心 | 能力矩阵、路由选择、降级规则、健康度记录 | P0 |
| 平台搜索采集器 | 搜索前预检查、候选搜索、候选标准化 | P0 |
| 商品详情采集器 | 商品原始字段采集、Hydration / API 解析 | P0 |
| 评论采集器 | 三桶抽样、去重、样本不足标记 | P0 |
| Browser Fallback Worker | 登录处理、接口发现、全量兜底抓取 | P0 |
| 标准化与聚合 | 统一字段、三级聚合、证据索引 | P0 |
| AI 报告模块 | 结构化报告生成、质量标记 | P0 |
| 历史任务与版本 | 报告版本生成、默认版本、旧版本切换 | P0 |
| 留存与删除 | 30/90 天清理、任务级删除、产物联动清除 | P0 |
| 导出模块 | Markdown / PDF 导出 | P1 |
## 7. 多阶段开发实施计划
### 7.1 周期总览
建议 MVP 采用 `12 周` 开发周期。
建议团队配置：
| 角色 | 数量 |
| --- | --- |
| 产品经理 | 1 |
| 设计师 | 1 |
| 前端工程师 | 1 |
| 后端 / 平台工程师 | 2 |
| 浏览器自动化工程师 | 1 |
| 数据与 AI 工程师 | 1 |
| QA | 1 |
阶段总表：
| Phase | 时间 | 主题 |
| --- | --- | --- |
| Phase 0 | 第 1-2 周 | 双平台可行性勘探与方案冻结 |
| Phase 1 | 第 3-4 周 | 基础骨架与任务系统 |
| Phase 2 | 第 5-6 周 | 单平台 API 优先闭环 |
| Phase 3 | 第 7-9 周 | 双平台模板刷新与恢复体系 |
| Phase 4 | 第 10-11 周 | 标准化、聚合、AI 报告与历史任务 |
| Phase 5 | 第 12 周 | 稳定性、效率与试运行 |
### 7.2 Phase 0：双平台可行性勘探与方案冻结（第 1-2 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 完成天猫、京东“搜索/详情/评论/登录”能力矩阵 v1；验证双平台非浏览器主路径；验证服务端浏览器接管与会话快照；冻结队列、存储和 Worker 拆分方案 |
| 交付物 | 双平台能力矩阵文档、接口或 Hydration PoC、服务端浏览器接管与模板刷新 PoC、Monorepo 脚手架、Phase 0 量化评分表 |
| 退出条件 | 至少一个平台搜索或详情默认不走 `L3`；用户可完成一次远程登录并保存会话；已明确双平台默认路径和首选降级路径；至少一个平台满足“搜索成功率 >= 80%、详情字段完整率 >= 85%、评论 50 条样本耗时 <= 90s”；浏览器直接承接数据抓取占比 <= 20% |
### 7.3 Phase 1：基础骨架与任务系统（第 3-4 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 完成 Web 前端、API 服务、`PostgreSQL`、`Redis` 和队列基础设施；完成三层状态持久化与流转；完成任务创建、平台预检查、执行页基础框架和会话中心基础能力 |
| 交付物 | 新建任务页与执行页框架、任务基础表与事件日志、队列模型与 Worker 骨架、会话中心与阻塞处理入口 |
| 退出条件 | 用户可创建任务并看到平台预检查结果；任务事件、平台状态和阶段流转均已落库；阻塞平台可生成可接管的服务端浏览器会话 |
### 7.4 Phase 2：单平台 API 优先闭环（第 5-6 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 跑通一个平台的“预检查 -> 搜索 -> 确认 -> 详情 -> 评论 -> 标准化 -> 报告摘要”闭环；默认路径优先使用接口或 Hydration；完成策略中心、错误分类和降级逻辑初版 |
| 交付物 | 单平台 `search/detail/reviews` 适配器、`strategy_attempts` 记录与路由逻辑、评论三桶抽样与去重规则、单平台最小报告快照 |
| 退出条件 | 单平台端到端闭环可用；默认抓取路径不依赖 `L3 Browser`；接口路径失败时系统能按规则切换到下一层策略 |
### 7.5 Phase 3：双平台模板刷新与恢复体系（第 7-9 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 完成天猫、京东双平台搜索与候选确认稳定可用；完成双平台详情和评论抓取能力矩阵；完成浏览器模板刷新辅助和人工恢复流程；明确每个平台的“默认路径 + 模板刷新策略 + 阻塞恢复动作” |
| 交付物 | 双平台 `precheck/search` 适配器、双平台详情与评论采集器、Template Refresh / Browser Recovery Worker 初版、阻塞恢复与平台级重试入口 |
| 退出条件 | 天猫、京东都能返回候选、无结果或阻塞原因；双平台都具备至少一条可运行的详情与评论抓取路径；用户能对阻塞平台发起人工恢复并继续任务 |
### 7.6 Phase 4：标准化、聚合、AI 报告与历史任务（第 10-11 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 完成标准化商品表、评论表和三级聚合；完成 AI 报告 Schema、证据索引、质量标记；完成历史任务页、报告版本管理和旧版本切换；完成 30/90 天留存与任务级删除实现 |
| 交付物 | 标准化与聚合模块、`report_snapshots` 生成器、报告页与历史任务页、版本切换与留存清理作业 |
| 退出条件 | 能生成符合 `PRD` Schema 的报告；历史任务可回看最新版本并切换旧版本；任务删除与留存清理逻辑可正确联动数据库和对象存储 |
### 7.7 Phase 5：稳定性、效率与试运行（第 12 周）
| 项目 | 内容 |
| --- | --- |
| 目标 | 完成平台级定向重试和复杂异常处理；跑通效率指标、稳定性指标和 UAT；形成试运行值守、排障和热修流程 |
| 交付物 | 平台级重试能力、采集效率与命中率看板、日志追踪与问题排查工具、MVP 试运行版本 |
| 退出条件 | 完成 P0 验收清单；关键指标达到试运行门槛；已形成按平台维度的热修和回滚策略 |
### 7.8 关键里程碑
| 里程碑 | 时间点 | 结果 |
| --- | --- | --- |
| M1 | 第 2 周末 | 天猫 / 京东能力矩阵完成，双平台 API/Hydration PoC 跑通 |
| M2 | 第 4 周末 | 任务系统、状态机、会话中心可用 |
| M3 | 第 6 周末 | 单平台 API 优先闭环可用 |
| M4 | 第 9 周末 | 双平台采集与模板刷新 / 恢复体系可用 |
| M5 | 第 11 周末 | AI 报告、历史任务、版本切换、留存删除可用 |
| M6 | 第 12 周末 | MVP 验收通过并进入试运行 |
## 8. MVP 验收与观测口径
### 8.1 功能验收出口
| 发布门槛 | 说明 |
| --- | --- |
| 双平台候选能力可用 | 天猫、京东搜索前预检查、候选搜索、候选展示可用 |
| 至少一个链接可跑通端到端任务 | 用户可确认至少一个链接并完成任务 |
| 单个平台阻塞不拖死整任务 | 必须成立 |
| 报告符合固定 Schema | 且关键洞察可回溯到证据索引 |
| 历史任务能力可用 | 可回看报告、切换旧版本、失败平台可定向重试 |
| 删除与清理联动正确 | 用户删除历史任务时，系统能清理关联数据与产物 |
| 阻塞恢复可用 | 可通过前端接入服务端浏览器完成人工恢复 |
### 8.2 采集效率与稳定性指标
| 指标 | 目标 |
| --- | --- |
| 默认配置下任务时长 `P50` | <= 20 分钟 |
| 搜索阶段 API/Hydration 命中率 | >= 70% |
| 商品详情默认不依赖 `L3 Browser` 的任务占比 | >= 60% |
| 评论抓取默认走接口或回放路径的任务占比 | >= 70% |
| 全量浏览器兜底占比 | <= 30% |
| 平台级定向重试后恢复成功率 | >= 50% |
| 关键结论证据可定位率 | >= 95% |
### 8.3 观测与统计实现
P0 必须同步实现以下观测能力：
| 观测项 | 说明 |
| --- | --- |
| `strategy_attempts` | 记录每次能力调用使用的层级、结果、耗时、错误类型 |
| `platform_run_metrics` | 记录每个平台的搜索耗时、详情耗时、评论耗时、重试次数 |
| `report_metrics` | 记录报告版本、样本量、失败平台、阻塞平台和质量标记 |
| `retention_metrics` | 记录留存清理、任务删除和残留对象数 |
## 9. 研发风险与发布运维
### 9.1 研发风险与应对
| 风险 | 说明 | 应对策略 |
| --- | --- | --- |
| 接口路径频繁变化 | 参数、签名或响应结构变化导致 API 路径失效 | 建立能力矩阵、契约测试和 HAR 回放测试，允许快速降级到下一层策略 |
| 服务端浏览器成本高 | 若大多数流量都落到浏览器，整体效率和成本会失控 | 把浏览器定义为兜底能力，持续统计命中率，超阈值时优先修复 API 路径 |
| 登录与风控不稳定 | 阻塞率高，影响任务完成率 | 维持平台级 `Blocked` 状态，支持远程人工恢复，避免整任务无差别失败 |
| 评论抓取吞吐不足 | 浏览器逐页抓取会拖慢整体任务 | 评论默认优先走接口分页或请求回放，不允许把浏览器滚动抓取当常规路径 |
| 服务端会话泄露风险 | 会话统一存储后安全要求更高 | 会话最小化保存、服务端加密、过期控制、审计和手动清理 |
| 90 天可追溯依赖证据快照留存 | 只保留 30 天原始大对象会让后期报告失去证据 | 把证据索引、摘录和来源元数据纳入 90 天留存 |
### 9.2 发布与运维建议
#### 9.2.1 MVP 发布方式
| 项目 | 建议 |
| --- | --- |
| 发布策略 | 先在内部受控服务器环境试运行，再扩大到小范围真实用户 |
| 交付形态 | 以服务端部署为准，不再以“用户本地启动脚本”为默认交付方式 |
| 部署方式 | 内部环境可使用 `Docker Compose` 或容器编排，浏览器 Worker 需独立隔离 |
| AI 配置 | 先使用单一配置和单一环境，控制成本和观察范围 |
#### 9.2.2 日志、排障与热修
MVP 至少保留以下日志与观测数据：
| 日志类型 | 用途 |
| --- | --- |
| 任务级事件日志 | 回溯任务状态流转 |
| 平台预检查、抓取失败和重试日志 | 定位平台级问题 |
| 策略选择与降级日志 | 观察路线命中和切换原因 |
| AI 请求摘要与响应校验日志 | 观察报告生成质量 |
| 报告版本生成日志 | 追踪版本变化 |
| 会话处理与人工恢复审计日志 | 追踪敏感恢复动作 |
日志要求：
| 要求 | 说明 |
| --- | --- |
| 前端只展示用户可理解信息 | 详细调试日志留在服务端 |
| 日志不得记录账号密码、完整 Cookie 或未脱敏敏感字段 | 必须 |
| 平台适配热修必须支持按平台、按能力快速发布 | 不要求整站全量重发 |
## 10. 下一阶段规划
MVP 稳定后，优先进入以下 P1 方向：
| 方向 | 说明 |
| --- | --- |
| Markdown / PDF 导出 | 扩展报告交付形态 |
| 更丰富的证据展示与截图系统 | 增强可验证性 |
| 更强的自动巡检、定时重跑与策略自适应 | 扩展任务模式 |
| 更多平台适配 | 从淘宝开始向外扩展 |
| 更细粒度的运营建议与可视化 | 提升分析深度 |
| 团队协作权限与多租户能力 | 扩展部署形态 |
## 11. 一句话结论
本项目的研发落地建议是：以“后端服务器统一采集执行”为前提，把当前 MVP 平台能力拆成“会话驱动请求回放优先、浏览器仅用于会话与模板刷新”的分层路线，先完成天猫与京东的高效率闭环，再进入版本回看、稳定试运行和后续淘宝扩展，而不是一开始就把浏览器自动化当作默认主通路。

512
docs/FeatureSummary.md Normal file
View File

@ -0,0 +1,512 @@
# 产品功能文档
- 文档名称：`FeatureSummary.md`
- 文档状态：Draft
- 版本：v0.4
- 更新时间：2026-04-02
- 依据文档：
- `docs/PRD.md`
- `docs/CrawlerFeasibility.md`
- `docs/review-PRD-codex.md`
## 1. 文档目的
本文件用于从功能视角总结跨平台商品聚合与 AI 分析产品的 MVP 方案，供产品、设计、研发和测试快速对齐。
相较完整 PRD，本文件重点回答四类问题：
1. 产品到底要做哪些功能。
2. 这些功能按什么流程组织。
3. 关键状态、规则和输出口径如何定义。
4. 哪些能力属于 MVP，哪些能力明确不做。
## 2. 产品概述
### 2.1 一句话定位
这是一个面向品牌运营、电商运营和竞品分析岗位的跨平台商品分析工作台：用户输入商品名称或描述，系统完成多平台搜索、人工确认、商品与评论抓取、标准化处理和 AI 分析，最终输出可追溯、可用于决策的结构化报告。
### 2.2 目标用户
| 用户角色 | 核心诉求 |
| --- | --- |
| 品牌方运营 | 快速了解同款或竞品在不同平台的卖点、价格、评价和风险 |
| 电商运营 | 对比自家商品与竞品在商品页、评论和店铺层面的表现差异 |
| 商品研究/竞品分析 | 产出一份可复用、可引用、可追溯的结构化分析报告 |
### 2.3 核心价值
1. 把分散在多个平台的手工检索整合成一次任务发起。
2. 用“系统召回 + 人工确认”降低同款识别错误率。
3. 把商品信息和评论样本统一成标准结构，减少人工整理成本。
4. 基于证据生成平台差异、卖点、风险点和运营建议，提升决策效率。
### 2.4 产品交付形态
MVP 以“内部受控部署的网页工作台”形态交付。用户通过浏览器访问统一 Web 工作台，在页面内完成任务创建、候选确认、抓取执行、报告查看和历史回看；采集执行、会话复用和阻塞恢复统一在服务端受控环境完成。
关键边界：
1. 首版以内部受控服务器部署、单工作区使用为基线。
2. 当前不以用户本机执行采集、多租户协作或云端 SaaS 作为 MVP 交付形态。
3. 团队协作与更广泛部署能力放入后续版本评估。
### 2.5 非目标
1. 不做持续监控、自动巡检或定时更新。
2. 不做消费者导购推荐。
3. 不做内容平台或社媒平台舆情分析。
4. 不保证评论全量抓取。
5. 不在无人工确认的前提下自动认定同款商品。
6. 不承诺绕过验证码、风控和登录限制。
## 3. MVP 范围
### 3.1 平台范围
MVP 仅支持以下平台：
1. 天猫
2. 京东
MVP 暂不覆盖：
1. 淘宝，作为下一优先扩展平台
2. 抖音电商，当前阶段延后实现
3. 拼多多、Amazon 等其他电商平台
4. 小红书、微博、B 站、短视频内容平台
### 3.2 输入与输出
输入：
1. 商品关键词或自然语言描述
2. 单链接评论抓取上限 `N`
输出：
1. 任务内结构化网页报告页
2. 原始抓取数据
3. 标准化商品与评论数据
4. 历史任务与报告版本回看
### 3.3 任务模式
1. MVP 采用一次性分析任务模式。
2. 每个任务从搜索开始，到报告产出结束。
3. 任务结束后支持回看和失败平台重试，不支持自动增量更新。
### 3.4 默认配置
1. 每个平台默认返回 Top 5 候选商品。
2. 单链接评论样本上限默认值为 `100`。
3. 单任务评论总上限为 `500`。
### 3.5 运行方式
1. MVP 先以内部受控服务端部署方式运行，用户通过浏览器访问统一工作台。
2. 当前不以用户本机执行采集或开放多租户形态交付。
3. 团队协作和更广泛部署能力放入后续版本评估。
## 4. 核心功能闭环
完整任务按以下顺序执行：
1. 用户创建任务，输入商品关键词和评论抓取配置。
2. 系统先按平台执行搜索前预检查，判断能否进入搜索。
3. 系统对可搜索平台执行站内搜索，返回候选结果、无结果或阻塞原因。
4. 用户按平台确认一个、多个或零个商品链接。
5. 若最终没有任何链接被确认，任务进入 `NoSelection` 终态，不进入抓取与报告生成。
6. 系统仅对已确认的平台执行抓取前会话与访问校验。
7. 校验通过的平台进入商品和评论抓取；校验失败的平台进入平台级阻塞。
8. 系统完成数据标准化、多链接聚合和 AI 分析。
9. 系统生成结构化报告快照，并写入历史任务记录。
10. 若存在失败或阻塞平台，用户可定向重试，不覆盖既有报告。
关键收敛规则：
1. 搜索前预检查发生在搜索之前；抓取前校验只发生在用户确认之后。
2. 单个平台异常不会默认终止整任务，只要仍有至少一个已确认平台可执行，任务继续。
3. 报告必须为结构化输出，不接受只有自由文本而无证据索引的结果。
4. 重试只针对失败、阻塞类平台执行；结果变化才生成新报告版本。
5. 新建任务页允许在创建任务前进入全局会话准备入口；该入口只更新平台会话状态，不创建任务。
## 5. 功能模块说明
### 5.1 任务创建
系统需支持：
1. 输入商品关键词或商品描述。
2. 配置单链接评论样本上限 `N`。
3. 在任务发起前展示平台可用性提示。
关键规则：
1. 平台提示来源于平台能力配置与最近一次会话校验结果，仅作预告。
2. `N` 的作用域为每个已确认链接，不是整任务统一平均值。
3. 若多个链接合计样本超过任务总上限，系统按比例收缩并明确提示。
4. 若平台需要会话准备，用户可直接进入全局会话准备入口，处理完成后返回当前页继续创建任务。
### 5.2 搜索召回与候选展示
系统需支持：
1. 分平台执行站内搜索。
2. 搜索前做轻量预检查，判断平台是否可搜索。
3. 返回候选商品列表、无结果或阻塞原因。
4. 对候选卡片展示足够用于判断的信息。
候选卡片至少包含：
1. 平台名称
2. 商品标题
3. 商品链接
4. 价格
5. 店铺名称
6. 主图或缩略图
7. 销量、热度、评分等辅助识别信息
候选规则：
1. 同平台下重复候选需去重，但原始候选结果仍可回看。
2. 同店铺疑似同款但规格不同的候选，不自动合并，需展示规格差异标签。
3. 不同店铺即使疑似同款，也保持独立候选，避免掩盖店铺差异。
4. 平台内默认排序按关键词匹配度、销量或热度、评价完整性、价格完整性综合排序。
### 5.3 商品链接确认
系统需支持：
1. 用户逐个平台浏览候选商品。
2. 在单个平台中单选、多选或跳过。
3. 记录确认结果并支持回看。
关键规则：
1. 平台内多选属于 MVP 核心能力。
2. 只有至少确认一个链接后，任务才允许进入抓取流程。
3. 一旦进入抓取阶段，只处理用户已确认的链接，不再自动扩展范围。
4. 若用户最终提交零确认链接，任务进入 `NoSelection` 终态；系统保留候选结果与原因摘要，但不生成报告快照。
### 5.4 平台登录与访问策略
MVP 采用“用户自有账号登录 + 服务端受控会话复用”模式。
每个平台需配置 `search_requirement`：
| 配置值 | 含义 | 搜索时行为 |
| --- | --- | --- |
| `none` | 搜索不依赖登录态 | 可直接搜索 |
| `recommended` | 不登录也可搜索，但结果可能不完整 | 允许搜索并提示风险 |
| `required` | 搜索依赖有效会话 | 无有效会话时不进入搜索 |
系统需支持：
1. 在真实搜索前执行平台预检查。
2. 仅对已确认平台执行抓取前校验。
3. 识别登录失效、跳转登录页、验证码和风控拦截。
4. 指引用户在服务端受控浏览器中处理登录或验证后继续任务。
5. 在任务外提供全局会话准备入口，用于在创建任务前预热 `required` 平台的会话状态。
关键规则：
1. 系统不保存用户账号密码。
2. 会话缓存仅在当前部署实例/工作区的服务端会话中心复用，并支持用户主动清除。
3. 搜索前校验失败只阻塞对应平台，不阻塞其余平台。
4. 抓取前校验失败不回退用户已完成的候选确认结果。
### 5.4.1 当前阶段可行性摘要
本节与 `docs/CrawlerFeasibility.md` 保持一致，用于把爬虫难点直接收敛进功能定义。
| 平台 | 暂定 `search_requirement` | 功能侧结论 |
| --- | --- | --- |
| 天猫 | `recommended` | 当前 MVP 平台；搜索和评论都应按“服务端会话驱动请求回放 + Hydration”预期设计 |
| 京东 | `required` | 当前 MVP 平台；搜索前必须做登录预检查，详情和评论优先走接口层 |
| 淘宝 | `recommended` | 下一优先平台；后续预期复用天猫适配栈 |
| 抖音电商 | `required` | 当前阶段延后实现；不进入当前验收与排期 |
关键规则：
1. 当前阶段不把官方开放平台当作本项目的直接数据源承诺。
2. 功能验收时要分别看搜索、详情、评论三项能力，不能只看“该平台是否有结果”。
3. 当前阶段的浏览器能力只用于登录、模板刷新和阻塞恢复，不承接常规抓取吞吐。
### 5.5 商品信息抓取
系统需对已确认链接抓取商品页可见信息，并保留原始字段。
MVP 优先抓取字段：
1. 商品标题、品牌、型号或系列
2. 当前价格、促销信息
3. 规格参数、SKU 选项
4. 商品详情文案与主卖点
5. 店铺名称、店铺类型、店铺评分
6. 商品评分、评论总量、销量或热度
7. 商品链接、平台名称、抓取时间
### 5.6 评论抓取与抽样
评论抓取目标是支撑分析，而不是全量抓取。
抽样规则：
1. 每个已确认链接独立抽样。
2. 优先从最新评论、最热评论、低分或差评评论三个桶取样。
3. 默认比例为 `40% / 30% / 30%`。
4. 若平台不支持某一抽样桶，则按剩余桶重新分配比例。
5. 若评论总量不足 `N`，抓取实际可得评论并标记样本不足。
评论至少保留：
1. 评论内容
2. 评论时间
3. 评论评分或情感标识
4. 点赞数或互动数
5. 规格或 SKU 信息
6. 评论来源标识
7. 对应商品链接
8. 抓取平台
去重规则：
1. 优先使用平台评论 ID 去重。
2. 无评论 ID 时，使用来源链接、评论时间和归一化评论文本组合去重。
### 5.7 数据标准化
系统需输出商品标准表和评论标准表，并保留原始字段。
核心标准字段包括：
1. `platform`
2. `source_url`
3. `price`
4. `product_rating`
5. `sales_volume`
6. `review_time`
7. `crawl_time`
8. `sampling_bucket`
关键规则：
1. 价格统一为人民币数值，原始价格文案单独保留。
2. 评分统一映射到 5 分制，无法映射时允许为空。
3. 时间统一使用 `Asia/Shanghai` 时区。
4. 所有无法标准化的原始字段不得丢弃。
### 5.8 多链接聚合
MVP 采用三级聚合逻辑：
1. 链接级：每个确认链接是最小分析单元，独立抓取、独立保留。
2. 平台级：同一平台下多个链接汇总，产出平台内价格区间、卖点共性、差评共性和店铺差异。
3. 跨平台级：以平台级结果作为主比较对象，同时保留链接级证据下钻能力。
关键规则：
1. 不把同一平台多个已确认链接强行合并成单一商品。
2. 报告中允许同时存在平台汇总结论和具体链接差异。
3. 跨平台对比默认展示平台聚合结果，避免报告被链接明细淹没。
### 5.9 AI 分析与结构化报告
AI 分析输出必须是结构化报告，而不是自由文本。
报告需包含以下核心部分：
1. 执行摘要
2. 商品快照
3. 平台洞察
4. 跨平台对比洞察
5. 运营或竞品建议
6. 证据索引
7. 质量标记
关键规则：
1. 每条强结论都必须可回溯到证据索引。
2. 若证据不足，不输出强结论，而是标记样本不足。
3. 报告中必须保留被纳入任务但未成功完成的平台状态。
4. 报告优先服务决策，不追求长篇自由描述。
### 5.10 历史任务、重试与版本
系统需支持：
1. 查看历史任务列表。
2. 回看任务输入、确认链接、执行状态和最终报告。
3. 在同一任务下切换不同报告版本。
4. 对失败或阻塞平台发起定向重试。
版本规则：
1. 同一 `task_id` 下首次成功产出报告记为 `report_version = 1`。
2. 重试仅针对 `SearchBlocked`、`Blocked`、`Failed` 平台。
3. 已完成平台默认复用上一次成功结果，不重复抓取。
4. 若重试导致平台状态或报告内容变化，生成新的报告版本。
5. 若重试未改变结果，仅追加执行日志，不生成新快照。
6. `default_report_version` 在 P0 恒等于 `latest_successful_report_version`，不支持人工改设默认版本。
## 6. 状态模型
### 6.1 状态口径
系统必须同时维护三层状态：
1. `task_status`：任务总体状态
2. `task_stage`：任务执行阶段
3. `platform_status`：单平台状态
### 6.2 `task_status`
| 状态 | 含义 |
| --- | --- |
| `Draft` | 任务已创建，尚未开始执行 |
| `Searching` | 正在做预检查或候选搜索 |
| `AwaitingConfirmation` | 等待用户确认候选商品 |
| `NoSelection` | 用户未确认任何链接，任务在确认阶段结束 |
| `Running` | 已进入抓取、标准化或分析阶段 |
| `Completed` | 所有已确认且可执行的平台均成功完成 |
| `PartialCompleted` | 已生成报告，但部分已确认平台失败或阻塞 |
| `Blocked` | 无成功平台，且剩余平台均因人工处理问题阻塞 |
| `Failed` | 无成功平台，且不存在可恢复执行对象 |
### 6.3 `task_stage`
| 阶段 | 说明 |
| --- | --- |
| `precheck` | 搜索前预检查 |
| `search` | 平台搜索候选 |
| `confirmation` | 用户确认链接 |
| `session_check` | 抓取前会话校验 |
| `crawl` | 商品与评论抓取 |
| `normalize` | 数据标准化 |
| `analyze` | AI 分析 |
| `publish` | 报告发布与版本写入 |
### 6.4 `platform_status`
| 状态 | 含义 |
| --- | --- |
| `Pending` | 未开始处理 |
| `SearchBlocked` | 搜索前已知受登录限制阻塞 |
| `Searching` | 搜索候选中 |
| `NoResult` | 搜索成功但无候选 |
| `AwaitingSelection` | 等待用户选择 |
| `Skipped` | 用户跳过平台 |
| `Selected` | 用户已确认链接，等待抓取前校验 |
| `Blocked` | 抓取前或抓取中遇到登录、验证码、风控问题 |
| `Running` | 抓取或平台级清洗中 |
| `Completed` | 平台结果已纳入报告 |
| `Failed` | 平台出现不可恢复执行失败 |
### 6.5 状态汇总规则
1. 单个平台进入 `SearchBlocked`、`Blocked` 或 `Failed`，不会自动把整任务置为失败。
2. `NoResult` 和 `Skipped` 不计入任务失败，但也不计入成功完成平台。
3. 若用户最终未确认任何链接，任务直接进入 `NoSelection`，不生成报告但保留历史记录。
4. 除 `NoSelection` 外，任务最终状态只基于已确认平台计算。
5. 只要至少一个已确认平台仍可继续，任务保持进行中或部分完成，而不是整体失败。
## 7. 报告输出结构
### 7.1 顶层结构
报告顶层至少包括以下字段：
| 字段 | 说明 |
| --- | --- |
| `report_id` | 报告唯一 ID |
| `report_version` | 报告版本号 |
| `task_id` | 所属任务 ID |
| `generated_at` | 报告生成时间 |
| `task_status` | 仅允许 `Completed` 或 `PartialCompleted` |
| `summary` | 执行摘要与限制 |
| `product_snapshot` | 分析对象快照 |
| `platform_insights` | 各平台结构化洞察 |
| `cross_platform_insights` | 跨平台对比洞察 |
| `recommendations` | 运营或竞品建议 |
| `evidence_index` | 证据索引 |
| `quality_flags` | 样本不足、部分失败等质量标记 |
### 7.2 报告内容要求
1. `summary` 需包含一句话摘要、关键结论和限制说明。
2. `platform_insights` 必须覆盖所有纳入任务的平台，即使该平台未成功完成。
3. 洞察卡片需包含标题、结论说明、置信度、样本标记、来源范围和证据引用。
4. `evidence_index` 至少包含平台、来源类型、原始链接、评论引用标识和抓取时间。
5. `quality_flags` 至少标记样本不足、部分平台失败和阻塞平台列表。
6. 报告页使用发布后的 `execution_status`，其值由运行态 `platform_status` 在发布阶段映射得到，不直接复用执行中状态枚举。
## 8. 数据、安全与合规边界
### 8.1 账号与会话
1. 不保存用户账号密码。
2. 仅复用当前工作区服务端会话中心中的用户会话态。
3. 会话缓存需支持加密存储和手动清除。
### 8.2 数据留存
1. 原始抓取数据默认保存 30 天。
2. 标准化数据、报告快照和证据索引默认保存 90 天。
3. 即使原始 DOM/HAR 等大对象在 30 天后清理，报告依赖的证据摘录与来源元数据仍保留到 90 天。
4. 用户可主动删除历史任务及相关数据。
### 8.3 合规边界
1. 仅抓取用户有权访问且页面可见的数据。
2. 不承诺绕过平台安全机制。
3. 平台规则变化导致能力不可用时，系统需明确提示，而非静默失败。
## 9. 版本优先级
### 9.1 P0
1. 新建任务页
2. 天猫、京东站内搜索
3. 候选结果展示
4. 商品链接人工确认
5. 登录态校验与人工阻塞处理
6. 商品信息抓取
7. 评论分层抽样抓取
8. 数据标准化
9. 多链接三级聚合
10. 结构化 AI 报告
11. 历史任务回看
### 9.2 P1
1. 更丰富的证据展示
2. Markdown/PDF 导出
3. 多租户与团队协作
4. 更细粒度的运营建议
5. 更强的失败重试与任务编排
6. 更多平台接入
## 10. 关键验收与质量指标
MVP 以“稳定产出可用报告”为验收目标，核心指标如下：
1. 任务完成率：进入 `Completed` 或 `PartialCompleted` 的任务占比不低于 `75%`。
2. 候选可用率：至少 2 个平台返回可确认候选或明确返回无结果的占比不低于 `85%`。
3. 候选确认准确率：人工抽检中，被确认链接确属目标分析对象的占比不低于 `90%`。
4. 任务时长：默认配置下，从任务发起到报告完成的 P50 时长不高于 `20` 分钟。
5. 报告可追溯率：关键结论带证据引用或明确标记样本不足的比例为 `100%`。
6. 证据引用有效率：可根据平台、链接、评论 ID 或索引与抓取时间定位到原证据的比例不低于 `95%`。
7. 用户可用性评分：试运行用户对报告“可用于决策”的评分不低于 `4/5`。
8. 报告采纳率：试运行用户认为无需重新整理即可进入后续分析或讨论的比例不低于 `70%`。
补充规则：
1. `PartialCompleted` 仅在已产出可阅读报告时计入完成率。
2. 若系统未产出报告，即使部分步骤成功，也不计入任务完成率。
3. `NoSelection` 不计入任务完成率，也不计入失败率。
4. 质量类指标以人工抽检和试运行记录为准，不依赖系统自报。
## 11. 一句话总结
本产品的本质不是跨平台抓取工具，而是一个围绕“商品分析任务”构建的产品化工作流：把搜索、确认、抓取、标准化、聚合和 AI 分析收敛为可追溯、可复用、可用于决策的结构化报告能力。

883
docs/PRD.md Normal file
View File

@ -0,0 +1,883 @@
# 跨平台商品聚合与 AI 分析 PRD
- 文档状态：Draft
- 版本：v0.6
- 更新时间：2026-04-02
- 参考文档：
- `docs/RequirementsDoc.md`
- `docs/CrawlerFeasibility.md`
- `docs/review-RequirementsDoc-codex.md`
- `docs/review-PRD-codex.md`
## 1. 文档目标
本 PRD 用于把现有需求草案收敛为可指导 MVP 设计、开发和验收的产品文档。
### 1.1 本文回答什么
| 主题 | 需要回答的问题 | 主要输出 |
| --- | --- | --- |
| 产品定义 | 这到底是一个什么产品，不是什么产品 | 定位、价值、边界 |
| MVP 范围 | 首版做什么，不做什么 | 平台范围、任务范围、输出范围 |
| 流程设计 | 用户如何从输入走到报告 | 主流程、状态模型、交互决策 |
| 结果交付 | 什么叫一份可用报告 | 报告 Schema、追溯口径、质量标记 |
| 验收标准 | 什么叫 MVP 可以交付 | 成功指标、验收标准、P0/P1 划分 |
### 1.2 PRD 速览
| 项目 | 结论 |
| --- | --- |
| 产品定位 | 面向品牌方、电商运营和竞品研究岗位的商品分析工作台 |
| 首版平台 | 天猫、京东 |
| 主入口 | 自然语言商品名称/描述 |
| 核心闭环 | 搜索 -> 候选确认 -> 抓取 -> 标准化 -> AI 报告 -> 回看 |
| 核心约束 | 人工确认优先、部分成功可产出、报告必须可追溯 |
| 交付形态 | 内部受控部署的统一 Web 工作台 |
| 不做事项 | 不做持续监控、不做导购、不做自动绕过风控、不做无确认同款判断 |
### 1.3 任务闭环总览
```mermaid
flowchart LR
A[输入商品关键词] --> B[平台预检查]
B --> C[站内搜索候选]
C --> D[用户确认链接]
D -->|零确认| X[NoSelection 终态]
D -->|至少一个确认| E[抓取前校验]
E --> F[商品与评论抓取]
F --> G[标准化与聚合]
G --> H[AI 结构化报告]
H --> I[历史回看 / 版本切换 / 平台级重试]
```
对应 ASCII 视图：
```text
+------------+ +------------+ +------------+ +------------+
| 输入查询 | -> | 候选搜索 | -> | 人工确认 | -> | 抓取分析 |
+------------+ +------------+ +------------+ +------------+
| |
| v
| +------------+
| | 报告回看 |
| +------------+
v
+------------+
| NoSelection|
+------------+
```
## 2. 产品定义
### 2.1 一句话定位
这是一个面向品牌方、电商运营和竞品研究岗位的跨平台商品分析工作台：用户输入商品名称，系统完成多平台搜索、人工确认、商品与评论抓取、标准化处理和 AI 分析，最终输出可追溯、可用于决策的结构化报告。
### 2.2 核心价值主张
当前用户的问题不是“拿不到数据”，而是“拿不到可用于决策的统一结论”。
| 价值层 | 用户原有问题 | 产品提供的价值 |
| --- | --- | --- |
| 检索成本 | 需要在多个平台重复搜索 | 用一次任务发起收敛多平台搜索 |
| 判断成本 | 同款识别不稳定 | 用“系统召回 + 人工确认”保障对象正确性 |
| 整理成本 | 商品与评论样本难统一 | 把原始数据标准化为统一结构 |
| 决策成本 | 结论依赖个人经验和截图 | 用 AI 输出结构化、可追溯的报告 |
### 2.3 产品形态
MVP 形态定义为“任务型分析工具”，而不是“持续监控平台”。
一个完整任务包含：
| 阶段 | 说明 |
| --- | --- |
| 输入 | 输入商品关键词或描述 |
| 搜索 | 获取多平台候选结果 |
| 确认 | 人工确认一个、多个或零个商品链接 |
| 执行 | 系统抓取、清洗、分析 |
| 输出 | 生成结构化报告并支持回看 |
### 2.4 MVP 交付形态
MVP 以“内部受控部署的网页工作台”形态交付。用户通过浏览器访问统一 Web 工作台，在页面内完成任务创建、候选确认、任务执行和报告回看；采集执行、会话复用和阻塞恢复统一在服务端受控环境完成。
| 决策项 | 口径 |
| --- | --- |
| 首版运行方式 | 内部受控服务器部署 |
| 采集执行位置 | 服务端统一执行 |
| 用户设备角色 | 只负责 Web 交互和必要的人机恢复操作 |
| 多租户/外部开放 | 不纳入 MVP |
| 后续扩展 | 待稳定性、成本和权限模型成熟后再评估 |
## 3. 用户、场景与问题
### 3.1 目标用户与典型场景
| 角色 | 核心任务 | 最关心的输出 |
| --- | --- | --- |
| 品牌方运营 | 看同款/竞品在不同平台如何卖、怎么被评价 | 平台差异、卖点总结、风险点、优化建议 |
| 电商运营 | 评估自家商品或竞品商品页与评论表现 | 价格与卖点对比、用户正负反馈、店铺差异 |
| 商品研究/竞品分析 | 快速完成一份可引用的商品分析报告 | 标准化数据、可追溯证据、结构化结论 |
### 3.2 非目标用户
| 用户类型 | 不覆盖原因 |
| --- | --- |
| 普通消费者导购用户 | 产品目标不是推荐购买，而是分析商品表现 |
| 内容/社媒舆情分析用户 | 当前只聚焦电商商品分析，不做内容平台监测 |
### 3.3 背景痛点
| 痛点 | 表现 |
| --- | --- |
| 平台分散 | 相同任务需要在多个站点重复执行 |
| 商品识别困难 | 同一商品往往有多店铺、多链接、多规格页并存 |
| 评论样本难整理 | 评论量大，但真正可用于分析的样本提取效率低 |
| 结果不可复用 | 分析结果依赖个人经验，难沉淀为结构化资产 |
### 3.4 机会判断
产品机会不只是“做一个抓取工具”，而是做一个围绕“商品分析任务”组织输入、处理和输出的产品化工作流。
## 4. MVP 目标与非目标
### 4.1 MVP 产品目标
| 目标 | 说明 |
| --- | --- |
| 一次任务发起 | 完成对天猫、京东的同类商品分析 |
| 人工确认保证正确性 | 不强行自动认定同款 |
| 输出可决策报告 | 报告需结构化、可回溯、可用于运营和竞品决策 |
| 支持部分成功产出 | 平台访问不稳定时仍尽量产出可用结果 |
### 4.2 明确的非目标
| 非目标 | 说明 |
| --- | --- |
| 持续监控/定时更新 | 不做自动巡检与自动重跑 |
| 消费者导购推荐 | 不面向普通购买决策 |
| 内容平台舆情聚合 | 不覆盖小红书、微博、B 站等场景 |
| 评论全量抓取 | 目标是足够支撑分析，不是尽可能抓全 |
| 无人工确认的同款判断 | 不自动代替用户做最终对象判断 |
| 自动绕过验证码/风控/登录限制 | 不承诺规避平台安全机制 |
## 5. MVP 范围与关键产品决策
### 5.1 覆盖平台
| 平台 | 当前状态 | 说明 |
| --- | --- | --- |
| 天猫 | MVP 覆盖 | 当前首发平台之一 |
| 京东 | MVP 覆盖 | 当前首发平台之一 |
| 淘宝 | 延后 | 下一优先扩展平台 |
| 抖音电商 | 延后 | 当前阶段不进入排期 |
| 拼多多 / Amazon 等 | 延后 | 不在 MVP 范围 |
| 小红书 / 微博 / B 站等 | 不覆盖 | 不属于当前产品目标 |
### 5.2 输入方式
| 项目 | 口径 |
| --- | --- |
| 主输入方式 | 自然语言商品名称/描述 |
| 示例 | `iPhone 15 Pro`、`大疆 Pocket 3`、`某品牌蓝牙耳机` |
| 不作为主流程的输入 | 直接粘贴商品链接 |
| 决策原因 | 关键词搜索更符合“跨平台聚合同一商品”的核心目标 |
### 5.3 任务模式
| 项目 | 口径 |
| --- | --- |
| 模式 | 一次性分析任务 |
| 起点 | 搜索开始 |
| 终点 | 报告产出结束 |
| 当前不支持 | 自动巡检、自动增量更新、定时重跑 |
### 5.4 输出形态
| 项目 | 口径 |
| --- | --- |
| 主输出 | 任务内结构化网页报告页 |
| 同时保留 | 原始数据、标准化数据、证据索引 |
| P1 输出 | Markdown / PDF 导出 |
| 运行方式 | 内部受控服务端部署，用户通过浏览器访问统一工作台 |
### 5.5 默认配置
| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| 每个平台候选数 | Top 5 | 默认候选返回规模 |
| 单链接评论样本上限 | `100` | 记为 `N` |
| 任务级评论总上限 | `500` | 超出时按已确认链接数进行比例分配并提示用户 |
## 6. 产品原则
| 原则 | 解释 |
| --- | --- |
| 人工确认优先于算法猜测 | 商品识别正确性优先于全自动化 |
| 证据优先于结论 | 报告结论必须能尽量回到商品链接、评论样本和抓取时间 |
| 部分成功优先于整体失败 | 允许单平台失败，但任务应尽可能产出可用结果 |
| 标准化优先于花哨展示 | 先把数据口径做对，再谈复杂展示 |
| 输出面向决策 | 报告不是信息堆叠，而是帮助用户做判断 |
## 7. 信息架构与核心用户流程
### 7.1 信息架构
| 页面/模块 | 作用 | 核心内容 |
| --- | --- | --- |
| 新建任务页 | 发起分析任务 | 商品关键词输入、评论上限配置、平台状态提示 |
| 候选确认页 | 完成平台候选商品确认 | 候选列表、单选/多选/跳过、确认回看 |
| 任务执行页 | 展示任务进度与异常状态 | 搜索中、等待确认、抓取中、分析中、部分失败 |
| 报告页 | 浏览结果与证据 | 商品汇总、平台对比、评论主题、风险点、证据引用 |
| 历史任务页 | 回看已完成任务 | 任务状态、商品关键词、更新时间、结果入口 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 历史任务页属于 MVP | 报告必须支持回看与复盘 |
| 候选确认页是核心页面 | 它负责正确性，不是可有可无的中间页 |
| 报告页是核心交付页面 | 它负责承接产品价值 |
### 7.2 主流程
```mermaid
flowchart TD
A[创建任务] --> B[平台预检查]
B --> C[搜索候选]
C --> D[候选返回 / 无结果 / 阻塞]
D --> E[用户确认一个、多个或零个链接]
E -->|零确认| F[NoSelection]
E -->|有确认链接| G[抓取前会话校验]
G --> H[商品与评论抓取]
H --> I[标准化]
I --> J[三级聚合]
J --> K[AI 结构化报告]
K --> L[查看报告与历史版本]
```
### 7.3 平台访问顺序与降级路径
| 规则 | 说明 |
| --- | --- |
| 新建页平台提示只用于预告 | 不替代实际执行时的预检查结果 |
| 每个平台维护 `search_requirement` | 取值为 `none`、`recommended`、`required` |
| 搜索前预检查只决定能否进入搜索 | 不直接决定整任务最终结果 |
| 抓取前校验只对已确认平台执行 | 避免无意义扩大人工处理面 |
| 单个平台阻塞不应立即终止其他平台 | 其余可执行平台继续 |
| 只要至少一个已确认平台可继续 | 任务继续执行 |
| 新建页提供全局会话准备入口 | 只更新会话状态，不创建任务 |
`search_requirement` 定义：
| 取值 | 含义 |
| --- | --- |
| `none` | 搜索不依赖登录态，可直接搜索 |
| `recommended` | 可直接搜索，但登录后结果更稳定或更完整 |
| `required` | 搜索前必须有有效会话，否则该平台不进入搜索 |
### 7.4 关键交互决策
| 交互 | 决策 |
| --- | --- |
| 平台内选择 | 支持单选、多选、跳过 |
| 进入抓取的前提 | 至少确认一个商品链接 |
| 任务执行中遇到验证码/登录失效/风控 | 优先标记为平台级阻塞，而不是默认整任务失败 |
| 零确认收口 | 允许进入 `NoSelection` 正式终态 |
## 8. 任务与平台状态模型
为避免把“整体任务结果”“执行阶段”和“单平台异常”混在一起，MVP 采用三层状态口径：
| 状态层 | 字段 | 用途 |
| --- | --- | --- |
| 任务层 | `task_status` | 历史任务列表、默认筛选、整体结果判断 |
| 阶段层 | `task_stage` | 执行页进度展示 |
| 平台层 | `platform_status` | 区分平台级正常、阻塞、失败和跳过 |
### 8.1 状态流总览
```mermaid
flowchart TD
A[Draft] --> B[Searching]
B --> C[AwaitingConfirmation]
C -->|零确认| D[NoSelection]
C -->|至少一个确认| E[Running]
E --> F[Completed]
E --> G[PartialCompleted]
E --> H[Blocked]
E --> I[Failed]
H -->|人工恢复后重试| E
G -->|平台级重试| E
```
### 8.2 `task_status`
| 状态 | 含义 | 触发条件 | 用户动作 |
| --- | --- | --- | --- |
| `Draft` | 任务已创建未启动 | 任务刚创建或等待用户发起 | 可编辑输入参数 |
| `Searching` | 正在做平台预检查或候选搜索 | 至少一个平台仍在预检查或搜索 | 等待系统返回结果 |
| `AwaitingConfirmation` | 等待用户确认候选商品 | 所有平台都已返回候选、无结果、阻塞或失败 | 单选、多选、跳过 |
| `NoSelection` | 用户未确认任何链接，任务在确认阶段结束 | 全部平台均无可执行选择，或用户主动以零确认链接提交 | 调整查询、重新搜索或预处理会话后新建任务 |
| `Running` | 已进入抓取、标准化或分析阶段 | 至少一个已确认平台仍在执行 | 等待完成或处理中断 |
| `Completed` | 所有已确认且可执行的平台均成功完成 | 至少一个已确认平台完成，且无已确认平台处于 `Blocked` 或 `Failed` | 查看报告 |
| `PartialCompleted` | 已产出报告，但有部分已确认平台失败或阻塞 | 至少一个已确认平台 `Completed`，且至少一个已确认平台 `Blocked` 或 `Failed` | 查看报告或重试失败平台 |
| `Blocked` | 没有成功完成的平台，且剩余平台均因人工介入问题被阻塞 | 零个已确认平台 `Completed`，且至少一个已确认平台 `Blocked`，并且无其他平台仍可继续 | 处理登录、验证码、风控后重试 |
| `Failed` | 没有成功完成的平台，且不存在可恢复的进行中平台 | 零个已确认平台 `Completed`，且已确认平台全部为 `Failed`、`Skipped` 或无可执行对象 | 重新发起任务或调整输入 |
### 8.3 `task_stage`
| 阶段 | 作用 | 说明 |
| --- | --- | --- |
| `precheck` | 平台预检查 | 判断平台能否进入搜索，不决定最终任务结果 |
| `search` | 搜索候选 | 拉取平台候选列表或无结果状态 |
| `confirmation` | 用户确认 | 等待用户确认候选链接 |
| `session_check` | 抓取前校验 | 只校验已确认平台的访问条件 |
| `crawl` | 商品与评论抓取 | 执行平台级抓取与原始数据留存 |
| `normalize` | 标准化处理 | 统一商品与评论字段口径 |
| `analyze` | AI 分析 | 生成结构化结论与证据关联 |
| `publish` | 报告发布 | 生成报告快照并更新历史版本索引 |
### 8.4 `platform_status`
| 状态 | 含义 | 是否可重试 | 备注 |
| --- | --- | --- | --- |
| `Pending` | 该平台尚未开始处理 | 否 | 初始状态 |
| `SearchBlocked` | 搜索前已知必须登录，但当前无有效会话 | 是 | 平台不进入搜索 |
| `Searching` | 正在搜索候选商品 | 否 | 过程态 |
| `NoResult` | 搜索成功但没有候选商品 | 否 | 不视为平台失败 |
| `AwaitingSelection` | 候选已返回，等待用户选择 | 否 | 过程态 |
| `Skipped` | 用户明确跳过该平台 | 否 | 不计入失败 |
| `Selected` | 用户已确认链接，待抓取前校验 | 否 | 过程态 |
| `Blocked` | 抓取前或抓取中遇到登录失效、验证码或风控 | 是 | 需用户人工处理 |
| `Running` | 抓取或平台级清洗中 | 否 | 过程态 |
| `Completed` | 该平台已产出有效结果并纳入聚合 | 否 | 可进入报告 |
| `Failed` | 该平台出现不可恢复执行失败 | 是 | 例如解析失败、数据异常、平台错误 |
### 8.5 汇总与重试规则
| 规则 | 说明 |
| --- | --- |
| 单个平台异常不自动拖死整任务 | `SearchBlocked`、`Blocked`、`Failed` 只影响对应平台 |
| `NoResult` 和 `Skipped` 不计入失败 | 但也不计入成功完成平台 |
| `NoSelection` 不生成报告 | 但保留历史记录和原因摘要 |
| 任务最终状态只基于已确认平台计算 | 未确认平台不影响报告完成态 |
| 重试只针对 `SearchBlocked`、`Blocked`、`Failed` | 已完成平台默认复用既有结果 |
| 重试造成结果变化才生成新版本 | 否则只追加执行日志 |
## 9. 功能需求
### 9.1 任务创建
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 输入 | 输入商品关键词或商品描述 |
| 配置 | 配置单链接评论抓取上限 `N` |
| 平台提示 | 在任务发起前展示平台可用性提示 |
| 会话准备入口 | 可在创建任务前进入全局会话准备 |
产品口径：
| 项目 | 口径 |
| --- | --- |
| 平台状态提示来源 | “平台能力配置 + 最近一次会话校验结果” |
| `search_requirement = required` 且最近会话不可用 | 提示“需登录后搜索” |
| `search_requirement = recommended` | 提示“未登录可能影响结果完整性” |
| `N` 的作用域 | 每个已确认链接的评论样本上限 |
| 多链接场景 | 先按链接分配 `N`，再受任务总上限约束 |
| 超过任务上限时 | 按比例收缩，并提示已触发任务级总量控制 |
### 9.2 搜索召回与候选展示
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 搜索执行 | 分平台执行站内搜索 |
| 搜索前预检查 | 明确平台是可搜索、受限还是阻塞 |
| 候选返回 | 返回候选列表、无结果或阻塞/失败原因 |
| 辅助判断 | 对候选展示基础识别信息与差异提示 |
候选列表至少展示：
| 字段 | 必须 |
| --- | --- |
| 平台名称 | 是 |
| 商品标题 | 是 |
| 商品链接 | 是 |
| 商品价格 | 是 |
| 店铺名称 | 是 |
| 主图/缩略图 | 是 |
| 销量/热度/评分等辅助信息 | 是 |
候选去重与差异展示规则：
| 规则 | 说明 |
| --- | --- |
| 相同 `canonical_product_id` 或规范化后完全相同链接 | 视为重复候选，只保留一张卡片 |
| 无稳定商品 ID 时 | 用“规范化标题 + 店铺名称 + 主图 + 价格区间”近似聚类 |
| 同店疑似同款但规格不同 | 不自动合并，用候选组 + 规格差异标签展示 |
| 不同店铺疑似同款 | 不自动合并，保持为独立候选 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 默认返回规模 | 每个平台 Top 5 |
| 候选展示要求 | 必须足够支撑用户判断，不能只返回标题和链接 |
| 搜索失败反馈 | 必须给出平台级明确反馈，避免误判卡死 |
| 平台内默认排序 | 关键词匹配度 > 销量/热度 > 评分与评价量完整性 > 价格信息完整性 |
### 9.3 商品链接确认
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 候选浏览 | 按平台浏览候选商品 |
| 平台内选择 | 单选、多选或跳过 |
| 回看确认结果 | 支持 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 平台内多选 | 属于 MVP 核心能力 |
| 进入抓取后 | 只处理用户已确认的链接，不自动扩展范围 |
| 候选组中的规格变体 | 用户必须明确勾选具体链接，系统不默认代选 |
| 零确认提交 | 进入 `NoSelection` 终态，不生成报告快照 |
### 9.4 平台登录与访问策略
MVP 采用“用户自有账号登录 + 服务端受控会话复用”模式。
`search_requirement` 行为定义：
| 配置值 | 含义 | 搜索时行为 | 抓取前行为 |
| --- | --- | --- | --- |
| `none` | 搜索不依赖登录态 | 直接搜索 | 对已确认链接做可访问性校验 |
| `recommended` | 未登录也可搜索，但结果可能不完整 | 允许搜索并提示风险 | 对已确认链接做会话与可访问性校验 |
| `required` | 搜索与抓取都依赖有效会话 | 无有效会话时标记 `SearchBlocked`，不进入搜索 | 用户处理会话后才能重试 |
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 搜索前预检查 | 在真实搜索前判断各平台是否满足搜索前提 |
| 抓取前校验 | 只对已确认链接所在平台执行 |
| 登录态访问 | 在用户自有账号登录态下访问平台页面 |
| 阻塞识别 | 识别登录失效、验证码、风控拦截等状态 |
| 恢复入口 | 提示用户在服务端受控浏览器中完成处理后继续任务 |
| 全局会话准备 | 在任务外提供独立入口 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 系统不保存账号密码 | 必须 |
| 会话复用方式 | 仅在当前工作区的服务端会话中心内加密复用 |
| 搜索前预检查失败 | 只阻塞对应平台 |
| 抓取前校验失败 | 只阻塞对应已确认平台，不回退已完成确认 |
| 会话缓存作用域 | 当前部署实例/工作区 |
| 默认过期时间 | 最后使用后 24 小时 |
| 平台策略变化导致失败 | 必须暴露可理解原因 |
### 9.4.1 当前阶段平台抓取约束
根据 `docs/CrawlerFeasibility.md` 在 2026-04-02 的调研结果，当前阶段增加以下硬约束：
| 平台 | 当前阶段定位 | 暂定 `search_requirement` | 当前产品约束 |
| --- | --- | --- | --- |
| 天猫 | 当前 MVP 平台 | `recommended` | 默认按淘宝/天猫同构请求链路设计；浏览器仅用于登录、验证码、模板刷新和恢复 |
| 京东 | 当前 MVP 平台 | `required` | 搜索和详情前必须做会话/登录预检查；默认按会话驱动请求回放设计 |
| 淘宝 | 下一优先平台 | `recommended` | 预期复用天猫适配栈；待双平台闭环稳定后接入 |
| 抖音电商 | 当前延后 | `required` | 不进入当前迭代范围；不参与当前验收与排期 |
补充产品决策：
| 决策项 | 说明 |
| --- | --- |
| 不承诺任何官方开放平台为直接数据源 | 当前不写入产品承诺 |
| 当前主路径 | 服务端 HTTP 请求回放与 Hydration 解析 |
| 平台级 `Blocked` | 视为产品常态，不视为偶发异常 |
| 阻塞后的默认动作 | 优先提供服务端受控浏览器恢复入口 |
| 无法刷新关键动态参数时 | 直接标记为 `Blocked`，不把逆向私有签名作为交付前提 |
### 9.5 商品信息抓取
系统需尽可能完整抓取商品页可访问信息，并保留原始字段。
MVP 优先抓取信息：
| 类别 | 字段 |
| --- | --- |
| 商品基础 | 商品标题、品牌、型号/系列 |
| 价格与促销 | 当前价格、促销信息 |
| 规格参数 | 规格参数、SKU 选项 |
| 页面内容 | 商品详情页文案、主卖点 |
| 店铺信息 | 店铺名称、店铺类型、店铺评分 |
| 表现数据 | 商品评分、评论总量、销量/热度 |
| 追溯信息 | 商品链接、平台名称、抓取时间 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 原始字段允许平台间不一致 | 是 |
| 标准化字段用于对比 | 原始字段用于回溯与补充展示 |
### 9.6 评论抓取与抽样策略
评论抓取目标是“足够支撑分析”，而不是“尽可能抓全”。
MVP 抽样策略：
| 项目 | 规则 |
| --- | --- |
| 抽样单位 | 每个已确认链接独立执行抽样 |
| 抽样桶 | 最新评论、最热评论、低分/差评评论 |
| 默认比例 | `40% / 30% / 30%` |
| 桶缺失时 | 将比例按剩余桶重新分配 |
| 评论不足 `N` 时 | 抓取实际可得评论并标记“样本不足” |
评论至少保留字段：
| 字段 | 必须 |
| --- | --- |
| 评论内容 | 是 |
| 评论时间 | 是 |
| 评论评分或情感标识 | 是 |
| 点赞数/互动数 | 是 |
| 规格/SKU 信息 | 是 |
| 评论来源标识 | 是 |
| 对应商品链接 | 是 |
| 抓取平台 | 是 |
去重口径：
| 规则 | 说明 |
| --- | --- |
| 优先口径 | 使用平台评论 ID 去重 |
| 无评论 ID 时 | 使用“来源链接 + 评论时间 + 归一化评论文本”组合去重 |
### 9.7 数据标准化与口径定义
系统需输出商品标准表与评论标准表，并保留原始字段。
核心口径：
| 字段 | 口径定义 |
| --- | --- |
| `platform` | 平台标准名称，MVP 当前限定为天猫、京东 |
| `source_url` | 被确认并实际抓取的商品链接 |
| `price` | 页面可见当前成交价，统一为人民币数值；原始价格文案单独保留 |
| `product_rating` | 统一映射到 5 分制；若无法映射则为空并保留原值 |
| `sales_volume` | 统一转换为数值字段；无法解析时保留原始文本 |
| `review_time` / `crawl_time` | 统一为 `Asia/Shanghai` 时区时间 |
| `sampling_bucket` | 固定枚举为 `latest`、`hot`、`negative` |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 标准化后的空值 | 允许，但必须可解释 |
| 无法标准化的字段 | 不得丢弃，应挂载在原始字段区域中 |
### 9.8 多链接聚合逻辑
MVP 明确采用三级聚合口径：
| 层级 | 说明 |
| --- | --- |
| 链接级 | 每个已确认链接作为最小分析单元，独立抓取、独立保留 |
| 平台级 | 同一平台下多个链接汇总展示，输出平台内价格区间、卖点共性、差评共性和店铺差异 |
| 跨平台级 | 以平台级结果为主比较对象，同时保留对链接级证据的下钻能力 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 不强行合并平台内多链接 | 保持链接级独立性 |
| 平台内允许同时展示汇总结论与具体差异 | 是 |
| 跨平台对比默认看平台聚合结果 | 避免被链接级细节淹没 |
### 9.9 AI 分析与报告 Schema
MVP 的 AI 分析不是自由文本生成，而是受控结构化输出。
报告结构总览：
```text
Report
├─ summary
├─ product_snapshot
├─ platform_insights[]
├─ cross_platform_insights[]
├─ recommendations[]
├─ evidence_index[]
└─ quality_flags
```
顶层 Schema：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `report_id` | string | 是 | 报告快照唯一 ID |
| `report_version` | integer | 是 | 同一 `task_id` 下从 `1` 递增 |
| `task_id` | string | 是 | 所属任务 ID |
| `generated_at` | datetime | 是 | 报告生成时间，使用 `Asia/Shanghai` 时区 |
| `task_status` | enum | 是 | 仅允许 `Completed` 或 `PartialCompleted` |
| `summary` | `Summary` | 是 | 执行摘要与限制说明 |
| `product_snapshot` | `ProductSnapshot` | 是 | 本次分析对象的基础汇总 |
| `platform_insights` | `PlatformInsight[]` | 是 | 每个平台一条结构化记录 |
| `cross_platform_insights` | `InsightCard[]` | 是 | 跨平台对比洞察卡片 |
| `recommendations` | `InsightCard[]` | 是 | 面向运营或竞品分析的建议卡片 |
| `evidence_index` | `Evidence[]` | 是 | 证据索引，供结论引用 |
| `quality_flags` | object | 是 | 样本不足、部分失败、平台阻塞等标记 |
`summary` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `headline` | string | 是 | 一句话摘要 |
| `key_points` | string[] | 是 | 2 到 5 条关键结论摘要 |
| `limitations` | string[] | 是 | 样本不足、平台缺失、时间范围等限制 |
`product_snapshot` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 用户原始输入关键词或描述 |
| `normalized_product_name` | string | 是 | 报告内统一使用的商品名称 |
| `platform_count` | integer | 是 | 纳入任务的平台数量 |
| `selected_link_count` | integer | 是 | 已确认链接总数 |
| `review_sample_count` | integer | 是 | 实际纳入分析的评论样本量 |
| `analysis_time_range` | object | 是 | 本次抓取与分析覆盖的时间范围 |
`platform_insights[]` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `platform` | enum | 是 | 天猫、京东 |
| `execution_status` | enum | 是 | `completed`、`blocked`、`failed`、`skipped`、`no_result` |
| `selected_link_count` | integer | 是 | 用户确认的链接数量 |
| `price_range` | object/null | 否 | 最低价、最高价，无法形成区间时为空 |
| `selling_points` | `InsightCard[]` | 是 | 平台卖点结论 |
| `positive_themes` | `InsightCard[]` | 是 | 好评主题 |
| `negative_themes` | `InsightCard[]` | 是 | 差评/风险主题 |
| `store_diff_notes` | `InsightCard[]` | 是 | 店铺或链接差异 |
发布时状态映射规则：
| 运行态 `platform_status` | 报告态 `execution_status` |
| --- | --- |
| `Completed` | `completed` |
| `Blocked` 或 `SearchBlocked` | `blocked` |
| `Failed` | `failed` |
| `Skipped` | `skipped` |
| `NoResult` | `no_result` |
补充规则：
| 规则 | 说明 |
| --- | --- |
| `Pending`、`Searching`、`AwaitingSelection`、`Selected`、`Running` | 不得出现在已发布报告快照中 |
`InsightCard` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `card_id` | string | 是 | 结论卡片唯一 ID |
| `title` | string | 是 | 结论标题 |
| `statement` | string | 是 | 结论说明 |
| `confidence` | enum | 是 | `high`、`medium`、`low` |
| `sample_flag` | enum | 是 | `sufficient`、`insufficient`、`partial` |
| `source_scope` | object | 是 | 来源平台、链接数、评论样本数 |
| `evidence_ids` | string[] | 是 | 指向 `evidence_index`；`sample_flag = insufficient` 时允许为空 |
`evidence_index[]` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `evidence_id` | string | 是 | 证据唯一 ID |
| `platform` | enum | 是 | 证据所属平台 |
| `source_type` | enum | 是 | `product` 或 `review` |
| `source_url` | string | 是 | 原始链接 |
| `review_ref` | string/null | 否 | 评论 ID；无 ID 时使用评论索引 |
| `snippet` | string | 是 | 简要摘录或摘要 |
| `captured_at` | datetime | 是 | 证据抓取时间 |
`quality_flags` 结构：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `sample_insufficient` | boolean | 是 | 是否存在样本不足 |
| `partial_platform_failure` | boolean | 是 | 是否存在已确认平台失败或阻塞 |
| `blocked_platforms` | string[] | 是 | 被阻塞平台列表 |
| `failed_platforms` | string[] | 是 | 失败平台列表 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 证据不足时 | 不输出强结论，对应卡片标记 `insufficient` |
| 报告风格 | 优先服务决策，不追求辞藻丰富 |
| 强结论必须有证据 | 任一 `InsightCard` 给出强结论时必须提供 `evidence_ids` |
| 平台洞察覆盖范围 | `platform_insights` 必须覆盖所有纳入任务的平台，即使被阻塞/失败/无结果 |
### 9.10 失败重试与报告版本策略
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 平台级重试 | 仅对 `SearchBlocked`、`Blocked`、`Failed` 平台发起 |
| 版本保留 | 重试后保留旧报告快照，并按版本回看 |
| 版本展示 | 在报告页与历史任务页显示当前默认版本和更新时间 |
| 版本字段 | 返回 `default_report_version` 与 `latest_successful_report_version` 的明确定义 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 首次成功报告 | `report_version = 1` |
| 已完成平台在失败平台重试中 | 默认复用上一次成功抓取的数据 |
| 重试未改变结果 | 不生成新快照，只追加执行日志 |
| P0 默认版本策略 | `default_report_version = latest_successful_report_version` |
| 报告默认展示 | 默认版本，允许用户切换查看旧版本 |
### 9.11 历史任务与结果回看
系统需支持：
| 能力 | 要求 |
| --- | --- |
| 历史任务列表 | 可查看 |
| 回看任务上下文 | 可回看任务输入、确认链接、执行状态和最终报告 |
| 失败平台查看 | 在部分失败任务中可查看失败平台及原因 |
| 报告版本切换 | 同一任务下可切换不同 `report_version` 的报告快照 |
产品决策：
| 决策项 | 说明 |
| --- | --- |
| 回看能力 | 是报告产品化的一部分，不是后台附属功能 |
| 报告必须绑定抓取时间 | 避免用户误把历史报告当实时结果 |
| 历史任务默认展示 | 最新成功报告版本，并允许下钻到旧版本 |
## 10. 数据、安全与合规边界
### 10.1 账号与会话
| 要求 | 说明 |
| --- | --- |
| 不保存用户账号密码 | 必须 |
| 会话复用位置 | 仅在当前工作区的服务端会话中心 |
| 会话缓存安全 | 需支持加密存储与用户手动清除 |
### 10.2 数据留存
| 数据类型 | 默认留存 |
| --- | --- |
| 原始抓取数据 | 30 天 |
| 标准化数据、报告快照、证据索引 | 90 天 |
| 原始大对象清理后 | 证据摘录、来源元数据和索引仍需保留到 90 天 |
| 用户主动删除 | 允许删除历史任务及相关数据 |
### 10.3 合规边界
| 边界 | 说明 |
| --- | --- |
| 数据范围 | 仅抓取用户有权访问、页面可见的数据 |
| 平台安全机制 | 不承诺绕过 |
| 平台规则变化导致不可用 | 优先保证用户知情，而不是静默失败 |
## 11. 成功指标
MVP 成功不以“功能做完”为标准，而以“任务能否稳定产出可用报告”为标准。
| 指标 | 定义 | 目标 |
| --- | --- | --- |
| 任务完成率 | 发起任务后进入 `Completed` 或 `PartialCompleted` 的比例 | >= 75% |
| 候选可用率 | 至少 2 个平台返回可供确认的候选项，或明确返回“无结果” | >= 85% |
| 候选确认准确率 | 人工抽检中，被确认链接确属目标分析对象的比例 | >= 90% |
| 人工确认效率 | 从候选页打开到提交确认的中位耗时 | <= 5 分钟 |
| 任务时长 | 默认配置下从发起到报告完成的 P50 时长 | <= 20 分钟 |
| 报告可追溯率 | 关键结论含来源范围与证据引用，或明确标记“样本不足”的比例 | 100% |
| 证据引用有效率 | 抽检中可通过平台、链接、评论 ID/索引与抓取时间定位到原证据的比例 | >= 95% |
| 用户可用性评分 | 试运行用户对报告“是否可用于决策”的评分 | >= 4/5 |
| 报告采纳率 | 试运行用户认为“无需重新整理即可进入后续分析或讨论”的比例 | >= 70% |
补充说明：
| 规则 | 说明 |
| --- | --- |
| `PartialCompleted` | 计入任务完成率，但必须已生成可阅读报告 |
| 无报告产出 | 即使部分步骤成功，也不计入完成率 |
| `NoSelection` | 不计入任务完成率，也不计入失败率 |
| 质量类指标 | 以人工抽检和试运行记录为准，不依赖系统自报 |
## 12. MVP 验收标准
| 模块 | 验收标准 |
| --- | --- |
| 任务创建 | 用户可输入关键词并配置评论上限，成功发起任务 |
| 搜索召回 | 每个平台在搜索前完成预检查，并返回候选列表、无结果或阻塞原因 |
| 候选展示 | 每个候选项至少包含标题、价格、店铺、链接，并能体现重复项与规格差异 |
| 人工确认 | 用户可单选、多选、跳过，并能回看确认结果 |
| 状态模型 | 系统同时维护 `task_status`、`task_stage`、`platform_status`，支持 `NoSelection` 终态，且单平台阻塞不自动阻塞整任务 |
| 登录与会话 | 系统可识别登录失效、验证码、风控，并支持“任务前会话准备 + 搜索前预检查 + 抓取前校验”三段式入口 |
| 商品抓取 | 对所有确认链接抓取商品信息，并保留原始字段 |
| 评论抓取 | 按既定抽样规则抓取评论，评论附带来源信息 |
| 数据标准化 | 输出统一结构，允许空值，但不得丢失未映射原始字段 |
| 多链接聚合 | 报告中同时存在链接级结果和平台级汇总 |
| AI 报告 | 输出固定 Schema，至少包含摘要、平台洞察、跨平台对比、建议、证据索引和质量标记 |
| 重试与版本 | 失败平台重试不覆盖旧报告；结果变化时生成新的 `report_version` |
| 可追溯性 | 报告关键结论可回溯到平台、链接、评论样本或抓取时间 |
| 容错 | 单个平台失败不阻塞整体任务完成，最终报告可见失败说明 |
## 13. 版本优先级
### 13.1 P0
| P0 项目 |
| --- |
| 新建任务页 |
| 天猫、京东站内搜索 |
| 候选结果展示 |
| 人工确认链接 |
| 登录态校验与人工阻塞处理 |
| 商品信息抓取 |
| 评论分层抽样抓取 |
| 数据标准化 |
| 多链接三级聚合 |
| 结构化 AI 报告 |
| 历史任务回看 |
### 13.2 P1
| P1 项目 |
| --- |
| 更丰富的证据展示 |
| Markdown / PDF 导出 |
| 多租户与团队协作 |
| 更细粒度的运营建议 |
| 更强的失败重试与任务编排 |
| 更多平台接入 |
## 14. 风险与依赖
| 风险/依赖 | 影响 | 应对策略 |
| --- | --- | --- |
| 平台登录与风控策略变化 | 导致搜索或抓取失败 | 明确 `Blocked` 状态，支持人工介入与失败提示 |
| 商品同款识别不稳定 | 导致分析对象错误 | 坚持“系统召回 + 用户确认” |
| 评论抽样偏斜 | 影响 AI 结论可靠性 | 使用分层抽样并在报告中标记样本范围 |
| 多链接结果过多 | 报告可读性下降 | 采用链接级、平台级、跨平台级三级展示 |
| 报告可读但不可验证 | 降低用户信任 | 强制引入来源范围、证据数量与引用 |
## 15. 一句话总结
本产品不是一个单纯的跨平台抓取工具，而是一个围绕“商品分析任务”设计的产品化工作流：把搜索、确认、抓取、标准化和 AI 分析整合为可追溯、可复用、可用于决策的结构化报告能力。

522
docs/RequirementsDoc.md Normal file
View File

@ -0,0 +1,522 @@
# 跨平台商品聚合与 AI 分析需求文档
- 文档状态：Draft
- 版本：v0.4
- 更新时间：2026-04-02
- 参考文档：
- `docs/CrawlerFeasibility.md`
## 1. 项目背景
品牌方或运营人员在分析某个商品时，通常需要分别打开多个电商平台，手动搜索同一商品，查看商品详情页、规格卖点、价格信息和评论区反馈，再自行做汇总与判断。该过程重复、耗时，且难以形成统一标准的数据与结论。
本项目目标是构建一个面向品牌方/运营人员的跨平台商品分析工具。用户输入商品名称后，系统自动在多个电商平台内搜索候选商品链接，由用户人工确认目标链接，再抓取商品信息和评论内容，并通过 AI 生成跨平台分析结果。
## 2. 产品目标
本项目 MVP 阶段的目标如下：
1. 用户输入自然语言商品名称后，系统可分别在天猫、京东中搜索候选商品。
2. 系统返回每个平台的多个最佳匹配结果，由用户人工确认目标商品链接。
3. 支持同一平台确认多个商品链接，以适配同一商品在不同店铺、不同销售页中的情况。
4. 在确认链接后，系统抓取商品页中的尽可能完整的信息，以及适量评论内容。
5. 系统将不同平台的原始数据统一映射为标准化字段。
6. 系统基于商品信息与评论内容，输出可供品牌方/运营使用的分析报告。
### 2.1 MVP 成功指标
以下指标用于判断 MVP 是否达到“可用可验证”状态，当前作为建议目标值：
1. 搜索召回可用率：每个平台均能返回候选列表或明确返回“无结果”，不出现静默失败。
2. 候选可确认率：在返回候选结果的平台中，用户能够确认至少一个有效商品链接。
3. 报告完成率：存在至少一个已确认链接的任务，应能产出结构化报告；允许部分平台失败，但不应整体中断。
4. 任务完成时长：在推荐配置下，80% 任务应在 15 分钟内完成从搜索到报告生成。
5. 结论可回溯率：报告中的关键结论应尽量附带平台、商品链接、评论样本或抓取时间等证据指针。
### 2.2 基础验收标准
| 模块 | 验收标准 |
| --- | --- |
| 搜索召回 | 每个平台返回候选列表或明确返回“无结果”；候选项至少包含标题、价格、店铺、链接 |
| 人工确认 | 用户可对每个平台执行单选、多选、跳过；确认结果可回看 |
| 商品抓取 | 对所有确认链接抓取商品信息，并保留原始字段与标准化结果 |
| 评论抓取 | 按既定抽样规则抓取评论；每条评论保留来源信息和所属链接 |
| 标准化 | 输出统一结构，允许空值，但需保留未映射原始字段 |
| AI 分析 | 报告至少包含卖点、好评点、差评点、跨平台差异，并附带来源摘要或证据指针 |
| 容错 | 单个平台失败不阻塞整体任务结束，最终结果中能看到失败原因 |
| 可追溯 | 报告中的关键结论可回溯到平台、商品链接、评论样本或抓取时间 |
## 3. 目标用户
主要目标用户：
1. 品牌方运营
2. 电商运营
3. 商品研究、竞品分析相关岗位
非目标用户：
1. 普通消费者导购场景
2. 纯内容平台舆情分析用户
### 3.1 典型使用场景与报告关注点
1. 品牌运营：重点关注卖点定位、平台差异、价格带与口碑风险。
2. 商品运营：重点关注差评原因、SKU/履约问题、详情页与促销优化建议。
3. 竞品研究：重点关注多店铺/多链接差异、评论结构与平台表现对比。
## 4. MVP 范围
### 4.1 输入方式
用户以自然语言输入商品名称或商品描述，系统基于该关键词在目标平台内执行搜索。
示例：
1. `iPhone 15 Pro`
2. `大疆 Pocket 3`
3. `某品牌蓝牙耳机`
说明：
1. MVP 不以用户提供单个平台商品链接作为主要输入方式。
2. 输入的核心目的是触发各平台内部搜索，以便聚合同一商品在不同平台的结果。
### 4.2 覆盖平台
MVP 仅覆盖以下电商平台：
1. 天猫
2. 京东
暂不纳入：
1. 淘宝，作为下一优先扩展平台
2. 抖音电商，当前阶段延后实现
3. 小红书、抖音内容、B 站、微博等内容平台
4. 拼多多、Amazon 等其他电商平台
### 4.3 分析方式
MVP 仅支持一次性分析任务，不支持持续监控。
即：
1. 用户发起一次商品分析任务
2. 系统完成搜索、确认、抓取、分析、报告输出
3. 不要求每日/每周自动更新
## 5. 核心用户流程
### 5.1 主流程
1. 用户输入商品名称。
2. 系统分别在天猫、京东中执行站内搜索。
3. 系统返回每个平台的候选商品列表；若未找到，则明确提示该平台未搜到相关商品。
4. 用户在每个平台中人工确认目标链接，允许单选、跳过或多选。
5. 用户配置评论抓取数量上限 `N`（默认按单个已确认链接生效）。
6. 系统在用户授权登录态下抓取已确认链接的商品信息与评论内容。
7. 系统对原始数据进行清洗、标准化与聚合。
8. 系统调用 AI 进行商品卖点、评论好评点、评论差评点等分析。
9. 系统输出结构化分析报告。
### 5.2 人工确认规则
为解决“是否为同一商品”的相关度问题，MVP 不做完全自动判定，而是采用“系统召回 + 用户确认”的方式。
要求：
1. 每个平台返回多个最佳匹配候选项。
2. 用户可在同一平台确认多个候选链接。
3. 若某平台未搜到合适结果，允许跳过该平台并继续分析其他平台。
4. 若某平台存在多个被确认链接，系统需对每个链接独立抓取，并在最终报告中进行平台内聚合展示。
## 6. 功能需求
### 6.1 平台搜索与候选返回
系统需支持以下能力：
1. 接收用户输入的商品关键词。
2. 在天猫、京东中分别执行站内搜索。
3. 返回每个平台的候选商品列表。
4. 对未搜索到候选结果的平台返回明确提示。
候选商品最少应展示以下信息：
1. 平台名称
2. 商品标题
3. 商品链接
4. 商品价格
5. 店铺名称
6. 主图或缩略图（如可获取）
7. 销量、热度、评分等辅助识别信息（如页面可见）
建议值：
1. MVP 每个平台默认返回 Top 5 候选结果。
2. 候选返回数量后续可配置。
### 6.2 商品链接确认
系统需支持以下交互：
1. 用户可按平台查看候选商品。
2. 用户可在单个平台中确认一个或多个链接。
3. 用户可跳过某个平台。
4. 用户确认完成后，系统仅对被确认的链接进入抓取阶段。
### 6.3 商品信息抓取
系统需尽可能完整抓取商品页原始信息，并保留原始数据。
优先抓取的信息包括：
1. 商品标题
2. 品牌
3. 型号/系列
4. 当前价格
5. 促销信息
6. 规格参数
7. SKU/规格选项
8. 商品主卖点描述
9. 商品详情页文案
10. 店铺名称
11. 店铺类型
12. 店铺评分或信誉信息（如可见）
13. 商品评分（如可见）
14. 评论总量（如可见）
15. 销量/热度/成交人数（如可见）
16. 商品链接
17. 抓取时间
18. 平台名称
说明：
1. “尽量全抓”指尽可能保留页面可访问范围内的商品信息。
2. 原始抓取字段允许平台间不一致。
3. 后续统一分析时，需再映射为标准化字段。
### 6.4 评论抓取
评论抓取要求：
1. 仅抓取适量评论，不要求全量抓取。
2. 用户可配置评论抓取上限 `N`；MVP 默认将 `N` 定义为“单个已确认商品链接”的评论抽样上限。
3. 若一个任务确认多个链接，则每个链接独立应用各自的 `N`，避免部分链接因共享额度而无样本。
4. 系统应采用分层抽样，而非只抓取单一排序下的前几条评论。
分层抽样默认规则：
1. 最新评论
2. 最热评论
3. 低分/差评评论
4. 默认分配比例建议为 `40% 最新 + 30% 最热 + 30% 低分/差评`。
5. 去重优先使用 `review_id`；若无 `review_id`，则使用标准化后的评论文本、评论时间、SKU 上下文和商品链接组合去重。
6. 若平台不支持某一排序或筛选条件，则降级为平台实际可访问的近似排序，并在 `sampling_bucket` 中记录实际来源。
7. 某抽样桶样本不足时，剩余额度回补到其他可访问抽样桶。
若平台能力受限，则应按平台实际可访问的评论排序或筛选条件执行。
评论至少应保留以下信息：
1. 评论内容
2. 评论时间
3. 评分或情感倾向标识（如可见）
4. 点赞数/互动数（如可见）
5. 规格/SKU 信息（如可见）
6. 评论来源链接或来源页面标识
7. 抓取平台
8. 对应商品链接
边界说明：
1. 不保证抓取评论总量覆盖平台全量评论。
2. “适量抓取”由用户通过 `N` 决定，且 `N` 的默认生效口径为单链接。
3. 系统目标是为分析提供足够样本，而不是穷尽式抓取。
### 6.5 数据清洗与标准化
系统需将各平台原始抓取数据转换为统一结构，以支撑跨平台汇总与比较。
标准化目标包括：
1. 将不同平台的商品信息映射为统一字段。
2. 将不同平台的评论信息映射为统一字段。
3. 保留无法映射的原始字段，供后续扩展或回查。
4. 当平台字段缺失时，允许标准化字段为空。
统一后的商品标准字段建议包含：
| 字段 | 说明 |
| --- | --- |
| platform | 平台名称 |
| source_url | 商品链接 |
| product_title | 商品标题 |
| brand | 品牌 |
| model | 型号/系列 |
| price | 当前价格 |
| promotion | 促销信息 |
| specifications | 主要规格参数 |
| sku_options | SKU/规格选项 |
| selling_points | 提取后的核心卖点 |
| shop_name | 店铺名称 |
| shop_type | 店铺类型 |
| product_rating | 商品评分 |
| review_count | 评论总量 |
| sales_volume | 销量/热度 |
| crawl_time | 抓取时间 |
统一后的评论标准字段建议包含：
| 字段 | 说明 |
| --- | --- |
| platform | 平台名称 |
| source_url | 商品链接 |
| review_id | 评论标识，若可获取 |
| review_time | 评论时间 |
| review_text | 评论文本 |
| review_rating | 评论评分，若可获取 |
| interaction_count | 点赞/互动量 |
| sku_context | 评论对应规格 |
| sampling_bucket | 抽样来源，如最新/最热/差评 |
| crawl_time | 抓取时间 |
字段类型与归一规则要求：
| 字段 | 类型/单位 | 归一规则 |
| --- | --- | --- |
| source_url | string | 对 URL 做标准化，移除无关追踪参数，作为链接级去重主键之一 |
| price | number，人民币元 | 统一转换为人民币元并保留两位小数；原始展示文本保留在原始字段中 |
| sales_volume / review_count / interaction_count | integer | 将“1.2万”“3k+”等展示格式转换为整数；无法解析时填 `null` |
| product_rating / review_rating | number，5 分制 | 如平台采用百分制、星级或其他刻度，需映射到 0-5 分制，并保留原始刻度 |
| review_time / crawl_time | datetime | 统一输出 ISO 8601 格式，时区按 `Asia/Shanghai` 解释；原始时间文本需保留 |
| specifications / sku_options | object 或 array | 优先结构化；无法可靠拆解时保留原文并标记未结构化 |
| 空值字段 | `null` | 缺失、不可见、不可解析均使用 `null`，不得以 `0` 或空字符串代替 |
### 6.6 AI 分析
MVP 阶段 AI 分析重点如下：
1. 基于商品信息提炼主要卖点。
2. 基于评论提炼用户好评点。
3. 基于评论提炼用户差评点。
4. 对多平台结果进行横向对比。
AI 输出应尽量做到：
1. 结论清晰
2. 可用于运营决策
3. 尽量附带来源依据
AI 输出必须遵循统一结构：
1. 每个平台至少输出：核心卖点、主要好评点、主要差评点、样本量说明。
2. 跨平台部分至少输出：共同卖点、差异点、潜在风险、运营建议。
3. 每条关键结论应附带来源摘要，至少关联到平台、商品链接、评论样本或商品字段。
4. 当证据不足或样本不足时，必须显式标注“样本不足”或“不形成明确结论”。
5. AI 不得补造未抓取到的商品参数、评论观点或平台差异。
### 6.7 报告输出
最终分析报告建议至少包含以下模块：
1. 商品基础信息汇总
2. 各平台商品卖点提炼
3. 评论正负面分析
4. 跨平台差异对比
5. 代表性评论证据
6. 运营建议或优化建议
说明：
1. “代表性评论证据”是重要能力，但不是首要完成优先级。
2. 即便前端暂不完整展示证据，底层也应尽量保留评论来源与商品链接，便于后续回溯。
报告补充要求：
1. 报告需标注各平台确认链接数、评论样本量与抓取时间。
2. 若存在部分失败，需单独列出失败平台、失败环节与其对结论范围的影响。
### 6.8 多链接聚合逻辑
当同一平台确认多个链接时，系统需支持以下逻辑：
1. 每个被确认链接均独立抓取、标准化并保留链接级结果。
2. 平台级结果需先在同平台内完成评论去重与字段汇总，再输出平台层摘要。
3. 跨平台比较时，仅使用平台层摘要进入横向比较，避免同平台多链接被重复放大权重。
4. 商品链接去重以标准化后的 `source_url` 为准，仅清理重复确认的同一页面；不同店铺或不同销售页链接不自动合并为同一商品。
5. 评论去重优先使用 `review_id`；缺失时按标准化评论文本、评论时间、SKU 上下文和标准化链接组合去重。
## 7. 登录态与平台访问要求
考虑到电商平台通常需要登录，且存在验证码、风控等问题，MVP 采用“用户自有账号授权登录”的模式。
### 7.1 平台接入模型
1. MVP 不采用“纯浏览器默认主路径”，而采用“服务端策略路由 + 会话驱动请求回放优先 + 受控浏览器旁路恢复”的平台接入模型。
2. 当前阶段不把任何官方开放平台当作直接数据源承诺；工程路线以平台真实页面请求链路为准。
3. 每个平台必须按 `search/detail/reviews/login` 四项能力分别定义默认路径、降级路径、阻塞信号和恢复动作，不能只写成“该平台可抓取”。
4. 当前阶段的主采集路径明确为“服务端 HTTP 请求回放 + Hydration 解析”；受控浏览器只用于登录、验证码、模板刷新、风控恢复和接口发现。
5. 每个平台使用独立会话容器，避免 Cookie/Session 串用。
6. 用户需在系统提供的受控会话中手动完成登录、验证码或人工确认；系统仅在授权会话范围内执行搜索和抓取。
7. MVP 默认不直接读取用户其他浏览器中的账号密码或任意 Cookie 文件；如后续支持导入登录态，必须经过单独授权并提供清理能力。
8. 若关键动态参数无法在授权会话内通过平台页面现有上下文刷新，应直接判定为 `Blocked`，不把逆向私有算法作为交付前提。
### 7.2 当前阶段平台可行性结论
基于 `docs/CrawlerFeasibility.md` 的 2026-04-02 调研结果，当前阶段的暂定结论如下：
| 平台 | 当前阶段定位 | 暂定 `search_requirement` | 工程默认路径 | 当前结论 |
| --- | --- | --- | --- | --- |
| 天猫 | 当前 MVP 平台 | `recommended` | `L0 Request Replay + L1 Hydration` | 搜索与评论都更适合按淘宝/天猫同构请求实现，浏览器只保留给登录和模板刷新 |
| 京东 | 当前 MVP 平台 | `required` | `L0 Request Replay + 搜索前预检查` | 详情接口层可见，但搜索和详情都受会话与风控约束，必须先完成稳定的会话中心 |
| 淘宝 | 下一优先平台 | `recommended` | 复用天猫 `mtop/h5api` 适配栈 | 后续新增淘宝具备明显适配复用价值，但不进入当前 MVP 排期 |
| 抖音电商 | 当前延后 | `required` | 暂不进入当前实现 | 当前阶段不排期、不验收，待网页链路和成本重新验证后再评估 |
补充约束：
1. 当前阶段只承诺天猫和京东的完整实现。
2. 非浏览器主路径应尽量对齐平台真实请求形态，但不把伪造设备、逆向私有签名或绕过风控作为交付前提。
3. 天猫与京东应先跑出可复用请求模板和稳定的 `Blocked` 恢复策略，再进入大规模功能开发。
### 7.3 账号安全与合规
1. 系统不得采集或保存用户账号密码。
2. 若需要复用登录态，仅允许在当前工作区的服务端会话中心加密保存 Cookie/Session，不下发明文，不跨工作区共享。
3. 会话默认最长保留最后使用后 `24` 小时；用户主动退出、平台判定失效或手动清理后应立即删除对应会话。
4. 系统异常退出后，下次启动需检测并清理过期、损坏或不可用的会话快照。
5. 产品需向用户明确提示：仅在其授权账号、合法访问范围和平台规则允许范围内使用。
### 7.4 失败回退策略
1. 支持识别登录失效、跳转登录页、验证码、风控拦截等状态。
2. 当出现无法自动继续的情况时，系统需暂停当前平台任务并明确提示人工处理。
3. 搜索、抓取阶段的会话失效应支持在用户恢复登录后继续执行，避免整任务重头开始。
4. 若平台访问策略变化导致抓取失败，系统需记录失败节点、失败原因和是否可重试。
边界说明：
1. 本项目不承诺无条件绕过所有平台风控。
2. 本项目的目标是在授权登录态下尽可能稳定地完成搜索、抓取和分析。
3. 若平台访问策略变化导致抓取失败，系统需可定位原因并向用户提示。
## 8. 非功能需求
### 8.1 可追溯性
系统输出的分析结果应尽量可回溯到原始来源，包括：
1. 商品链接
2. 平台名称
3. 评论文本或评论来源
4. 抓取时间
### 8.2 容错性
系统应允许部分平台失败或无结果，不应因单个平台异常导致整个任务失败。
例如：
1. 某平台未搜到候选商品
2. 某平台登录态失效
3. 某平台评论抓取失败
上述情况不应阻断其他平台的分析结果生成。
### 8.3 可配置性
以下参数建议支持配置：
1. 每个平台候选返回数量
2. 评论抓取上限 `N` 及其作用域
3. 评论抽样策略
4. AI 分析模板或提示词版本
### 8.4 任务反馈与状态机
由于搜索、抓取、分析过程可能耗时较长，系统应具备任务进度反馈和可重试状态流转能力。
推荐状态至少包括：
1. 待开始
2. 搜索中
3. 等待人工确认
4. 抓取中
5. 等待人工处理登录/验证码
6. 分析中
7. 已完成
8. 部分失败
9. 已失败
10. 已取消
状态流转要求：
1. 搜索中、抓取中、分析中支持有限次自动重试。
2. 登录失效、验证码或风控拦截时，进入“等待人工处理登录/验证码”状态。
3. 单个平台失败时，其他平台应继续执行，最终可进入“部分失败”。
4. 最终结果需展示各平台状态、失败节点、失败原因和重试结果。
### 8.5 性能与成本边界
1. MVP 推荐配置为：3 个平台、每个平台最多 2 个确认链接、单链接评论上限 `N <= 100`。
2. 在上述推荐配置下，80% 任务目标在 15 分钟内完成。
3. MVP 默认单用户同时仅运行 1 个抓取任务，避免登录态与抓取资源冲突。
4. AI 分析应优先消费标准化摘要和抽样评论，不直接发送全量原始页面内容，以控制成本和上下文长度。
### 8.6 数据留存与导出
1. 原始抓取数据默认保留 7 天，用于回溯、排错和证据复核。
2. 标准化数据与分析报告默认保留 30 天，后续可按部署形态调整。
3. 用户应可手动导出分析报告与标准化数据；MVP 至少支持 `Markdown` 和 `JSON` 导出。
4. 用户删除任务后，应同步清理与该任务相关的原始数据、标准化数据和报告缓存；登录会话按第 7 章单独管理。
## 9. 明确的非目标
MVP 阶段不包含以下能力：
1. 不做持续监控或定时更新
2. 不做面向消费者的导购推荐
3. 不做内容平台、社区平台、短视频平台的舆情聚合
4. 不保证评论全量抓取
5. 不在没有人工确认的前提下自动判定同款商品
6. 不承诺完全自动化绕过验证码、风控和登录限制
## 10. MVP 优先级建议
### 10.1 P0
1. 商品名称输入
2. 天猫、京东站内搜索
3. 候选商品返回
4. 人工确认商品链接
5. 商品信息抓取
6. 评论分层抽样抓取
7. 数据标准化
8. AI 输出卖点、好评点、差评点、跨平台对比
9. 生成基础分析报告
### 10.2 P1
1. 更丰富的证据展示
2. 更细的运营建议
3. 更完善的字段提取与结构化
4. 更强的失败恢复与任务编排
5. 更丰富的平台扩展能力
## 11. 当前建议值与待定项
以下内容当前可作为建议值进入设计与实现阶段，后续可调整：
1. 每个平台默认返回 Top 5 候选商品。
2. 评论抓取上限 `N` 默认按单个已确认链接生效，建议默认值先从 `100` 开始验证。
3. 评论抓取采用分层抽样，默认比例为 `40% 最新 + 30% 最热 + 30% 差评`。
4. 同平台多个确认链接在平台层汇总时仅做评论去重，不自动合并为单一商品。
5. 评分统一映射到 5 分制，销量/评论数统一转为整数，时间统一为 `Asia/Shanghai` 时区下的 ISO 8601。
6. 登录态仅允许在服务端会话中心加密保存，默认最长保留最后使用后 `24` 小时。
7. 报告输出优先满足“结构化分析报告 + 证据回溯”能力。
8. 最终呈现载体可后续再定为页面、Markdown、导出文件或其他形式。
## 12. 一句话定义
这是一个面向品牌方/运营人员的跨平台商品分析工具：用户输入商品名称，系统在天猫、京东中搜索候选商品，由用户人工确认一个或多个商品链接后，抓取商品信息与适量评论，统一标准化并用 AI 输出卖点、好评点、差评点及跨平台分析报告。

856
docs/UIDesign.md Normal file
View File

@ -0,0 +1,856 @@
# 跨平台商品聚合与 AI 分析 UI 设计文档
- 文档状态：Draft
- 版本：v0.2
- 更新时间：2026-04-02
- 依据文档：
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/DevelopmentPlan.md`
## 1. 文档目标
本文件用于把 `PRD`、`FeatureSummary` 和 `DevelopmentPlan` 中已经明确的产品边界、状态模型和研发形态，收敛为可执行的 Web 前端 UI 设计基线。
### 1.1 本文回答什么
| 主题 | 需要回答的问题 | 输出形式 |
| --- | --- | --- |
| 信息架构 | MVP 工作台如何承载完整任务闭环 | 页面结构、导航、流程图 |
| 状态表达 | 各类任务状态、平台状态、报告状态如何区分 | 状态表、状态流图 |
| 视觉风格 | 如何避免落成普通后台表格页 | 视觉原则、Token、线框 |
| 前端落地 | 页面模块、共享组件、接口契约如何协同 | 模块表、组件表、验收表 |
### 1.2 文档速览
| 项目 | 结论 |
| --- | --- |
| 产品形态 | 统一 Web 工作台，不做本机采集分支 |
| 核心闭环 | 新建任务 -> 候选确认 -> 任务执行 -> 报告阅读 -> 历史回看 |
| 关键设计目标 | 可发起、可判断、可恢复、可追溯 |
| UI 基调 | 研究台、证据板、暖色工作台、克制但有判断力 |
| P0 关键页面 | 新建、确认、执行、报告、历史、会话准备/恢复 |
| 关键风险处理 | 平台阻塞不等于整单失败，优先支持部分成功产出 |
### 1.3 任务闭环总览
```mermaid
flowchart LR
A[新建任务] --> B[多平台搜索]
B --> C[候选确认]
C -->|有确认链接| D[抓取与分析]
C -->|零确认收口| X[NoSelection 终态]
D --> E[报告发布]
D --> F[阻塞恢复]
F --> D
E --> G[报告阅读与证据下钻]
G --> H[历史回看 / 版本切换 / 平台级重试]
```
对应 ASCII 视图：
```text
+------------+ +------------+ +------------+ +------------+
| 新建任务 | --> | 候选确认 | --> | 任务执行 | --> | 报告阅读 |
+------------+ +------------+ +------------+ +------------+
| |
| v
| +------------+
+------------> | 阻塞恢复 |
+------------+
|
v
+------------+
| NoSelection|
+------------+
```
## 2. 设计输入与前置假设
### 2.1 业务基线
产品本质不是“抓取工具集合”，而是一个围绕商品分析任务组织输入、确认、执行和报告输出的工作台。
MVP 的核心目标与 `PRD` 保持一致：
| 目标 | 说明 |
| --- | --- |
| 一次任务发起 | 替代多平台反复手工搜索 |
| 系统召回 + 人工确认 | 保证分析对象正确性 |
| 标准化数据 + 结构化 AI 报告 | 降低整理与判断成本 |
| 部分成功可产出 | 不把所有异常都视为整单失败 |
### 2.2 交付形态对齐
当前上游文档已统一为“Web 工作台 + 后端统一采集执行 + 服务端远程受控浏览器处理会话”的形态。
| 项目 | 基线 |
| --- | --- |
| 执行位置 | 服务端统一执行 |
| 用户入口 | 统一 Web 工作台 |
| 会话处理 | 服务端远程受控浏览器 |
| 页面文案口径 | 使用“系统”“工作台”“当前任务”等中性表达 |
| 会话页面复用 | 任务前准备与任务中恢复共用一套页面模式 |
### 2.3 设计范围
#### P0 范围
| 范围 | 内容 |
| --- | --- |
| 页面 | 新建任务、候选确认、任务执行、报告、历史任务、会话准备/恢复 |
| 系统能力 | 视觉系统、状态系统、共享组件、响应式、可访问性 |
| 协同要求 | 与任务状态、平台状态、报告快照、会话恢复流程对齐 |
#### 非本文件范围
| 非范围项 | 说明 |
| --- | --- |
| 品牌官网式首页 | 不在 MVP 范围 |
| PDF/Markdown 导出视觉稿 | 本文不展开 |
| 多租户权限中心 | 不纳入 P0 |
| 高级 BI 大屏 | 不纳入 P0 |
## 3. 总体体验目标
### 3.1 四个体验问题
| 问题 | UI 需要解决什么 |
| --- | --- |
| 发起问题 | 用户能否快速开始，而不是被表单噪音淹没 |
| 判断问题 | 用户能否确认目标商品，而不是机械点按钮 |
| 过程问题 | 用户能否知道系统现在在做什么、卡在哪、下一步怎么做 |
| 结果问题 | 用户能否先得到结论，再下钻到证据 |
### 3.2 设计原则
| 原则 | 解释 |
| --- | --- |
| 任务优先于页面 | 页面只是同一任务在不同阶段的视图 |
| 证据优先于修辞 | 结论、建议、风险都要能回到证据索引 |
| 正确性优先于自动化感 | 确认页帮助判断，不制造“系统全懂了”的错觉 |
| 部分成功优先于全局失败 | 单个平台失败时，其余平台结果仍可阅读 |
| 状态必须可解释 | `Blocked`、`NoResult`、`NoSelection` 等必须明确区分 |
| 复杂信息分层展开 | 顶层摘要，细节通过抽屉、折叠、版本切换进入 |
### 3.3 视觉关键词
| 关键词 | 含义 |
| --- | --- |
| `研究台` | 像分析师的工作台，而不是通用 SaaS 后台 |
| `证据板` | 结论旁边始终有证据入口 |
| `暖色工作台` | 避免大面积冷白，增强阅读与停留感 |
| `克制但有判断力` | 状态色明确，但不过度装饰 |
## 4. 信息架构与导航
### 4.1 页面结构总表
| 页面 | 建议路由 | 核心问题 | 主操作 |
| --- | --- | --- | --- |
| 新建任务页 | `/tasks/new` | 我要分析什么，采样如何设置，哪些平台当前可能受限 | 创建任务 |
| 会话准备页 | `/sessions/:platform/prepare` | 在创建任务前如何完成某个平台的登录或会话预热 | 接管远程会话、返回原页面 |
| 候选确认页 | `/tasks/:taskId/confirm` | 哪些候选才是我要分析的对象 | 选择、跳过、提交确认 |
| 任务执行页 | `/tasks/:taskId/run` | 系统做到哪一步了，哪里被阻塞，是否需要我介入 | 查看进度、处理阻塞、重试平台 |
| 报告页 | `/tasks/:taskId/report` | 最终得出了什么结论，证据是什么 | 阅读、对比、切换版本、下钻证据 |
| 历史任务页 | `/history` | 过去做过哪些任务，哪些值得回看或继续处理 | 搜索、筛选、回看、删除、重试 |
| 阻塞恢复页 | `/tasks/:taskId/recovery/:platform` | 如何完成登录、验证码或风控处理并恢复任务 | 接管远程会话、完成恢复 |
### 4.2 全局工作台结构
MVP 采用“轻左侧导航 + 任务上下文头部 + 页面主体”的结构。
```text
+----------------------------------------------------------------------------------+
| 左侧导航 |
| - 新建任务 |
| - 历史任务 |
+----------------------+-----------------------------------------------------------+
| Task Context Header | 任务名 / task_status / 更新时间 / 平台概览 / 主操作 |
+----------------------+-----------------------------------------------------------+
| Task Spine | 输入 -> 确认 -> 执行 -> 报告 |
+----------------------+-----------------------------------------------------------+
| 页面主体 |
| - 新建页 / 确认页 / 执行页 / 报告页 / 历史页 / 会话页 |
+----------------------------------------------------------------------------------+
```
### 4.3 导航原则
| 原则 | 说明 |
| --- | --- |
| 单任务主线 | 任务创建后，后续页面围绕同一个 `task_id` 组织 |
| 历史页即首页 | 不额外引入空洞 Dashboard |
| 执行与报告互通 | 两者是同一任务的不同视图，不应割裂 |
| 会话页为旁路流程 | 只被拉起，不进入主导航 |
### 4.4 导航流转图
```mermaid
flowchart TD
A[/history 历史任务/] --> B[/tasks/:id/report 报告/]
A --> C[/tasks/:id/run 执行/]
D[/tasks/new 新建任务/] --> E[/tasks/:id/confirm 确认/]
E --> C
C --> B
D --> F[/sessions/:platform/prepare 会话准备/]
C --> G[/tasks/:id/recovery/:platform 阻塞恢复/]
F --> D
G --> C
```
## 5. 视觉系统
### 5.1 视觉基调
| 层次 | 设计要求 |
| --- | --- |
| 背景 | 有轻微纸面与桌面感，不是纯白办公后台 |
| 标题 | 有明显层级，突出任务对象与结果判断 |
| 状态 | 语义清晰，颜色服务于解释，不服务于装饰 |
| 报告 | 更像研究报告，不像长表格或运营后台 |
### 5.2 色彩系统
建议采用“暖底色 + 深墨文字 + 青铜系状态强调”的基线，并通过 CSS Variables 覆盖组件库 Token。
| Token | 建议值 | 用途 |
| --- | --- | --- |
| `--bg-canvas` | `#F2EEE6` | 全局背景，营造研究台底色 |
| `--bg-surface` | `#FBF8F2` | 普通卡片背景 |
| `--bg-elevated` | `#FFFFFF` | 浮层、抽屉、重要卡片 |
| `--text-primary` | `#1F2A30` | 主文字 |
| `--text-secondary` | `#5B6971` | 次级说明 |
| `--line-subtle` | `#D7D0C4` | 分隔线 |
| `--brand-primary` | `#146C6E` | 主按钮、焦点、关键链接 |
| `--brand-primary-soft` | `#D9EFEB` | 主品牌浅底 |
| `--accent-amber` | `#8C5A16` | 版本、限制、提醒 |
| `--success` | `#2E7D5B` | 成功态 |
| `--warning` | `#9A4B24` | 警示态 |
| `--blocked` | `#9E3F22` | 阻塞态 |
| `--danger` | `#B63E2F` | 失败态 |
| `--info` | `#2F6D8A` | 搜索中、待确认等信息态 |
### 5.3 色彩使用规则
| 规则 | 说明 |
| --- | --- |
| 平台身份不靠颜色区分 | 平台识别优先用名称、图标和标签 |
| 状态色只表达状态 | 不承担品牌装饰功能 |
| 报告图表控色 | 1 组品牌色 + 语义色，禁止彩虹配色 |
| 对比度合规 | 所有文本与状态标签需满足 `WCAG AA` |
### 5.4 字体系统
| 字体角色 | 建议字体 |
| --- | --- |
| 标题字体 | `Alibaba PuHuiTi 3.0` 或 `Source Han Sans SC` |
| 正文字体 | `Noto Sans SC` |
| 数字/技术字段 | `IBM Plex Mono` |
### 5.5 栅格、圆角、阴影
| 项目 | 建议 |
| --- | --- |
| 最大内容宽度 | `1440px` |
| 主栅格 | `12` 列 |
| 列间距 | `24px` |
| 卡片圆角 | `16px` |
| 大容器圆角 | `20px` |
| 主区块垂直间距 | 不低于 `24px` |
| 阴影策略 | 普通卡片以浅边框为主，阴影克制 |
### 5.6 动效原则
| 场景 | 规则 |
| --- | --- |
| 页面进入 | 轻微上浮 + 淡入，`160ms-240ms` |
| 执行中状态 | 低频呼吸光或进度线，不做大面积闪烁 |
| 抽屉/折叠/版本切换 | 用滑入强化层级关系 |
| 可访问性 | 支持 `prefers-reduced-motion` |
### 5.7 图表与对比呈现
| 推荐形式 | 不推荐形式 |
| --- | --- |
| 对比矩阵 | 饼图 |
| 区间条 | 雷达图 |
| 指标卡 | 词云 |
| 主题标签组 | 三维图形 |
| 证据抽屉 | 复杂 BI 大屏表达 |
## 6. 状态系统与交互规则
### 6.1 状态语义映射
| 语义层 | 适用状态 | 视觉表达 | 备注 |
| --- | --- | --- | --- |
| `neutral` | `Draft`、`Pending`、`Skipped` | 灰底或描边标签 | 中性过程态 |
| `info` | `Searching`、`AwaitingConfirmation`、`AwaitingSelection` | 蓝青色标签或提示条 | 说明系统正在组织信息 |
| `progress` | `Running`、`session_check`、`crawl`、`analyze` | 动态进度样式 | 强调过程，不代表结果 |
| `success` | `Completed` | 绿色确认样式 | 完整成功 |
| `warning` | `PartialCompleted`、样本不足、限制说明 | 琥珀色提醒 | 有产出但覆盖不完整 |
| `blocked` | `SearchBlocked`、`Blocked` | 橙红色阻塞样式 | 必须带恢复动作 |
| `danger` | `Failed` | 红色失败样式 | 明确失败 |
| `empty` | `NoResult`、`NoSelection` | 中性空状态 | 不等于失败 |
### 6.2 三层状态不可混用
| 层级 | 字段 | 放在哪里 | 回答什么问题 |
| --- | --- | --- | --- |
| 任务层 | `task_status` | 任务页顶部 | 整个任务当前是否可用 |
| 阶段层 | `task_stage` | 执行页阶段轴 | 系统现在正在做哪一步 |
| 平台层 | `platform_status` | 候选页与执行页的平台卡片 | 哪个平台现在发生了什么 |
| 报告层 | `execution_status` | 报告页平台 Section | 最终发布报告如何描述该平台结果 |
### 6.3 状态流图
```mermaid
flowchart TD
A[Draft] --> B[AwaitingConfirmation]
B -->|零确认收口| C[NoSelection]
B -->|至少一个确认| D[Running]
D --> E[Completed]
D --> F[PartialCompleted]
D --> G[Blocked]
D --> H[Failed]
G -->|恢复后继续| D
F -->|平台级重试| D
```
### 6.4 关键状态文案模板
| 状态 | 推荐文案结构 | 示例 |
| --- | --- | --- |
| `Blocked` | 结论 + 原因 + 下一步 | `需登录后才能继续抓取，请处理会话后重试` |
| `PartialCompleted` | 结论 + 缺口 + 可用性 | `报告已生成，但 1 个已确认平台未完成` |
| `NoResult` | 结论 + 归因 + 口径 | `该平台未找到候选结果，不计入失败` |
| `sample_flag=insufficient` | 结论 + 范围限制 | `样本不足，当前结论仅基于 24 条评论` |
| `NoSelection` | 结论 + 原因 + 后续动作 | `本次未确认任何链接，任务已结束；你可以处理会话后重新搜索` |
### 6.5 禁止做法
| 禁止项 | 原因 |
| --- | --- |
| 用单个总进度条替代全部状态 | 会丢失任务层、阶段层、平台层差异 |
| 把平台异常只写进日志 | 用户无法快速定位问题 |
| 用“处理中”“异常”覆盖多个状态 | 信息含糊，不利于恢复 |
| 在报告页直接复用运行态 `platform_status` | 会破坏报告快照口径 |
## 7. 页面级设计
### 7.1 新建任务页
#### 7.1.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让用户快速输入目标商品并理解任务边界 |
| 建议路由 | `/tasks/new` |
| 主按钮 | `创建任务` |
| 主要风险 | 平台可用性、样本规则、输入过载 |
#### 7.1.2 布局与模块
| 区块 | 内容 |
| --- | --- |
| 左侧主栏 `7` | 任务输入、评论样本配置、示例输入、规则说明 |
| 右侧侧栏 `5` | 平台可用性提示、最近会话状态、最近任务快捷入口 |
| 模块 | 作用 | 关键字段 |
| --- | --- | --- |
| `Hero Composer` | 输入查询词与商品描述 | `query`、`description` |
| `Sampling Config` | 配置评论样本策略 | `per_link_limit`、`task_total_limit` |
| `Platform Readiness Panel` | 展示平台会话与搜索要求 | `search_requirement`、最近会话状态 |
| `Scope Reminder` | 明确 P0 范围和限制 | 平台范围、样本说明 |
| `Recent Tasks Mini List` | 提供回看捷径 | 最近 3 到 5 条任务 |
#### 7.1.3 关键交互
| 交互 | 规则 |
| --- | --- |
| 输入校验 | 前置在字段下方，不使用提交后大弹窗 |
| 平台状态提示 | 只作预告，文案需说明“实际执行时将再次检查” |
| 去处理登录 | 从状态卡直接跳到 `/sessions/:platform/prepare` |
| 完成会话准备后 | 返回原页并刷新该平台会话状态 |
| 创建任务后 | 直接进入候选确认页 |
#### 7.1.4 ASCII 线框
```text
+----------------------------------------------------------------------------------+
| 新建任务 |
| 查询词 [______________________________] [创建任务] |
| 商品补充描述 [_______________________________________________] |
| |
| 左侧主栏 | 右侧侧栏 |
| +----------------------------------------------+ | +--------------------------+ |
| | Sampling Config | | | 平台就绪状态 | |
| | - 单链接评论上限 N | | | 天猫 需登录 / 去准备 | |
| | - 任务总上限 500 | | | 京东 可用 | |
| +----------------------------------------------+ | | 淘宝 后续扩展 | |
| +----------------------------------------------+ | +--------------------------+ |
| | Scope Reminder | | +--------------------------+ |
| | - 仅天猫、京东 | | | 最近任务 | |
| | - 淘宝为下一优先平台 | | | | |
| | - 不保证评论全量 | | +--------------------------+ |
| +----------------------------------------------+ | |
+----------------------------------------------------------------------------------+
```
### 7.2 候选确认页
#### 7.2.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 帮助用户在最短时间内确认正确商品链接 |
| 建议路由 | `/tasks/:taskId/confirm` |
| 主按钮 | `开始抓取与分析` |
| 次级动作 | `结束本次确认`、`跳过平台` |
#### 7.2.2 布局与模块
| 区块 | 内容 |
| --- | --- |
| 顶部 `Task Summary Strip` | 查询词、样本设置、平台返回概览 |
| 中部 `Candidate Board` | 按平台分区展示候选 |
| 右侧 `Selection Basket` | 汇总已确认链接、估算样本数、展示主动作 |
| 候选卡字段 | 必须包含 |
| --- | --- |
| 身份信息 | 平台标识、商品主图、商品标题 |
| 商业信息 | 价格、店铺名称、销量/热度/评分 |
| 判断辅助 | 规格差异标签、疑似重复、价格异常、信息不完整 |
| 行为控件 | 源链接入口、勾选控件 |
#### 7.2.3 关键交互
| 交互 | 规则 |
| --- | --- |
| 平台内多选 | 允许 |
| 平台跳过 | 每个平台都必须有显式入口 |
| 主按钮启用条件 | 至少确认一个链接 |
| 零确认收口 | 所有平台已无可继续选择时，允许提交为 `NoSelection` |
| 勾选反馈 | 除勾选状态外，还要提升卡片层级与边框对比 |
| 右侧篮子反馈 | 即时展示确认链接数、理论样本量、总上限提示 |
#### 7.2.4 异常状态
| 状态 | 页面表现 |
| --- | --- |
| `SearchBlocked` | 平台分区显示阻塞卡，不显示空白 |
| `NoResult` | 中性空状态，并标注“不计入失败” |
| 全部不可选 | 可提交进入 `NoSelection` 终态 |
| `NoSelection` 终态 | 给出原因摘要和两个动作：返回新建、处理会话后重搜 |
#### 7.2.5 ASCII 线框
```text
+------------------------------------------------------------------------------------------------+
| 候选确认 |
| 查询词: 无线蓝牙耳机 样本: 每链接 100 / 总上限 500 平台返回: 天猫 4 京东 3 |
+-----------------------------------------------+----------------------------+-------------------+
| Candidate Board | Candidate Board | Selection Basket |
| 天猫 | 京东 | 已确认 2 个链接 |
| +-------------------------------------------+ | +------------------------+ | 理论样本 200 |
| | [x] 主图 标题 价格 店铺 规格标签 | | | [ ] 主图 标题... | | 预计收缩: 否 |
| | 疑似重复 / 信息不完整 / 查看原链接 | | | SearchBlocked | | [开始抓取与分析] |
| +-------------------------------------------+ | | [去处理会话] | | [结束本次确认] |
| | +------------------------+ | |
| | | |
| | | |
| | | |
+------------------------------------------------------------------------------------------------+
```
### 7.3 任务执行页
#### 7.3.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让长任务变成可理解、可恢复、可追踪的过程 |
| 建议路由 | `/tasks/:taskId/run` |
| 实时机制 | `SSE` |
| 核心动作 | 处理阻塞、重试平台、查看当前报告 |
#### 7.3.2 布局与模块
| 区块 | 内容 |
| --- | --- |
| 左侧主栏 `8` | `Task Hero Banner`、`Stage Rail`、`Platform Run Panels` |
| 右侧侧栏 `4` | `Live Event Feed`、执行摘要、阻塞恢复入口、可重试动作 |
| 模块 | 作用 |
| --- | --- |
| `Task Hero Banner` | 展示 `task_status`、`task_stage`、已用时、已确认链接数、已完成平台数 |
| `Stage Rail` | 显示 `precheck -> search -> confirmation -> session_check -> crawl -> normalize -> analyze -> publish` |
| `Platform Run Panels` | 每个平台单独展示状态、最近事件、错误原因、下一步动作 |
| `Live Event Feed` | 按时间线展示事件，支持按平台筛选 |
| `Action Panel` | 统一放置处理阻塞、重试、查看报告入口 |
#### 7.3.3 关键交互
| 交互 | 规则 |
| --- | --- |
| 实时刷新 | 使用 `SSE`，不使用高频轮询 |
| 新事件到达 | 不强制打断用户当前阅读位置 |
| `Blocked` 平台 | 在平台卡片内直接提供恢复按钮 |
| 重试动作 | 必须通过 `RetryablePlatformPicker`，只列出 `SearchBlocked`、`Blocked`、`Failed` |
| `PartialCompleted` | 主按钮切为“查看当前报告”，同时保留平台级重试入口 |
| 有部分产出时 | 至少一个平台完成后，允许提前查看报告 |
#### 7.3.4 三层信息并列规则
```text
+----------------------------------------------------------------------------------+
| Task Hero Banner |
| task_status = PartialCompleted task_stage = publish 已用时 07:42 |
+----------------------------------------------------------------------------------+
| Stage Rail |
| precheck -> search -> confirmation -> session_check -> crawl -> normalize -> ... |
+------------------------------------------------------+---------------------------+
| Platform Run Panels | Live Event Feed |
| 天猫 Blocked [去恢复] | 14:02 天猫需登录 |
| 京东 Running | 14:03 京东抓取中 |
| 系统 模板刷新完成 | 14:04 请求模板已更新 |
+------------------------------------------------------+---------------------------+
```
三层分别回答：
| 信息层 | 回答的问题 |
| --- | --- |
| 顶部任务状态 | 整任务是否可用 |
| 阶段轴 | 系统正在做哪一步 |
| 平台运行卡 | 哪个平台发生了什么 |
### 7.4 报告页
#### 7.4.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让用户先获得结论，再快速验证结论 |
| 建议路由 | `/tasks/:taskId/report` |
| 核心能力 | 摘要、对比、洞察、证据下钻、版本切换 |
| 状态来源 | 只消费报告快照中的 `execution_status` |
#### 7.4.2 信息顺序
| 顺序 | 区块 | 作用 |
| --- | --- | --- |
| 1 | 报告头部摘要 | 给出对象、版本、结论、限制 |
| 2 | 商品快照 | 用指标卡建立全局认知 |
| 3 | 质量标记与限制 | 说明样本和覆盖范围 |
| 4 | 跨平台对比 | 给出平台级矩阵 |
| 5 | 平台级洞察 | 展开每个平台的结构化结论 |
| 6 | 建议区 | 按优先级组织动作建议 |
| 7 | 证据索引与抽屉 | 提供可回溯证据链 |
#### 7.4.3 头部与快照
| 区块 | 必须包含 |
| --- | --- |
| 头部 | 查询词、标准化商品名、`report_version`、默认/历史版本标识、生成时间、`task_status`、`headline`、限制摘要 |
| 商品快照 | 平台数、已确认链接数、评论样本数、抓取时间范围、报告版本、质量标记摘要 |
若为 `PartialCompleted`：
| 要求 | 说明 |
| --- | --- |
| 组合状态条 | 顶部必须显式显示 |
| 平台缺口说明 | 明确列出阻塞或失败平台 |
| 可读性说明 | 提示“报告可阅读，但覆盖范围有限” |
#### 7.4.4 跨平台对比区
| 对比行 | 内容 |
| --- | --- |
| 价格区间 | 平台价格带和主销规格 |
| 平台主卖点 | 平台商品页主叙事 |
| 主要好评主题 | 高频正向反馈 |
| 主要差评/风险主题 | 高频负向反馈 |
| 店铺或链接差异 | 店铺差异、规格差异、显著异动 |
展示规则：
| 规则 | 说明 |
| --- | --- |
| 默认只看平台级 | 不直接铺满链接级细节 |
| 异常平台保留列位 | `blocked`、`failed`、`no_result` 仍保留列位 |
| 主动下钻再展开细节 | 通过卡片或证据抽屉进入 |
#### 7.4.5 平台级洞察区
| Section 结构 | 内容 |
| --- | --- |
| 平台头部 | 平台名称、`execution_status`、已确认链接数、价格区间 |
| `selling_points` | 卖点卡组 |
| `positive_themes` | 好评主题卡组 |
| `negative_themes` | 差评主题卡组 |
| `store_diff_notes` | 店铺差异卡组 |
#### 7.4.6 InsightCard 结构
| 字段 | 必须 |
| --- | --- |
| 标题 | 是 |
| 结论说明 | 是 |
| 置信度 | 是 |
| 样本标记 | 是 |
| 来源范围摘要 | 是 |
| 证据数量或证据链接 | 是 |
交互规则：
| 交互 | 规则 |
| --- | --- |
| 点击卡片 | 打开 `EvidenceDrawer` |
| 样本不足 | 必须显式标识“样本不足” |
| 置信度表达 | 文字枚举 + 视觉样式，不能只靠颜色 |
#### 7.4.7 证据抽屉
| 内容 | 说明 |
| --- | --- |
| 证据摘要 | 当前结论对应的证据简介 |
| 来源平台 | 天猫 / 京东 |
| 来源类型 | `product` / `review` |
| 源链接 | 原始来源入口 |
| 评论引用标识 | 用于回溯 |
| 抓取时间 | 时间上下文 |
| 摘录或摘要 | 当前证据文本 |
#### 7.4.8 ASCII 线框
```text
+--------------------------------------------------------------------------------------------------+
| 报告页 |
| 商品: XX 蓝牙耳机 report_version: v3 状态: PartialCompleted [切换版本] |
| headline: 两平台价格接近，但京东差评集中在续航，天猫平台样本不足 |
+---------------------------------------------------------------+----------------------------------+
| 商品快照指标卡 | 质量标记 / 限制 |
| 平台数 2 | 已确认链接 3 | 评论样本 186 | 时间范围 7d | 样本不足 / 覆盖有限 |
+---------------------------------------------------------------+----------------------------------+
| 跨平台对比矩阵 |
| 价格区间 | 卖点 | 好评主题 | 风险主题 | 店铺差异 |
+----------------------------------------------------------------------------------+---------------+
| 平台级洞察 | EvidenceDrawer |
| 天猫 Section | 证据摘要 |
| 京东 Section | 来源链接 |
| Cross-platform Summary | 评论摘录 |
+----------------------------------------------------------------------------------+---------------+
```
### 7.5 历史任务页
#### 7.5.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 同时承担工作台首页与任务账本 |
| 建议路由 | `/history` |
| 核心动作 | 搜索、筛选、回看、删除、版本切换、平台级重试 |
#### 7.5.2 布局与字段
| 区块 | 内容 |
| --- | --- |
| 左侧筛选栏 | 状态、平台、时间、是否部分完成等筛选 |
| 中间任务列表 | 搜索、排序、主浏览 |
| 右侧预览面板 | 摘要、版本、失败平台、最近更新时间、快捷操作 |
| 列表字段 | 至少展示 |
| --- | --- |
| 查询词 | 任务识别主信息 |
| 最新 `task_status` | 结果口径 |
| 报告版本 | 无报告则显示 `No report` |
| 更新时间 | 倒序主排序字段 |
| 平台覆盖情况 | 概览 |
| 失败/阻塞平台数 | 风险提示 |
| 快捷入口 | 查看报告、继续执行、重试、删除 |
#### 7.5.3 关键交互
| 交互 | 规则 |
| --- | --- |
| 默认排序 | 最近更新时间倒序 |
| 快速筛选 | 支持 `Completed`、`PartialCompleted`、`Blocked`、`Failed`、`NoSelection` |
| 版本切换 | 可在预览面板完成 |
| 无报告任务 | 显示 `NoSelection` 或失败原因摘要，不渲染为空白 |
| 删除 | 必须二次确认，并说明会删除关联数据与报告 |
### 7.6 会话准备与阻塞恢复页
#### 7.6.1 页面概要
| 项目 | 说明 |
| --- | --- |
| 页面目标 | 为会话准备、登录恢复、验证码和风控处理提供最短闭环 |
| 模式 | `prepare`、`recovery` |
| 共同布局 | 左侧远程浏览器，右侧恢复侧栏 |
#### 7.6.2 页面结构
| 区块 | 内容 |
| --- | --- |
| `Remote Browser Viewport` | 远程浏览器画面 |
| `Recovery Sidebar` | 当前平台、阻塞原因、处理步骤、会话剩余时间、校验按钮、返回按钮 |
#### 7.6.3 状态流
| 状态 | 说明 |
| --- | --- |
| `allocating` | 分配会话资源 |
| `connecting` | 建立连接 |
| `live` | 用户可操作 |
| `verifying` | 系统校验恢复结果 |
| `recovered` | 已恢复成功 |
| `expired` | 会话过期 |
#### 7.6.4 恢复流程图
```mermaid
flowchart TD
A[进入 prepare/recovery] --> B[allocating]
B --> C[connecting]
C --> D[live]
D --> E[用户处理登录/验证码/风控]
E --> F[verifying]
F -->|成功| G[recovered]
F -->|失败或过期| H[expired]
H --> B
G --> I[返回来源页并刷新状态]
```
#### 7.6.5 关键交互
| 交互 | 规则 |
| --- | --- |
| 从 `recovery` 进入 | 返回时保留执行页滚动位置和筛选上下文 |
| 从 `prepare` 进入 | 完成后返回来源页并刷新会话状态 |
| 恢复成功后 | 优先返回原来源页，不跳陌生页面 |
| 连接失败或过期 | 必须提供重新申请入口 |
| 移动端 | 降级为“请在桌面端继续处理”的受限视图 |
## 8. 共享组件与前端模块建议
### 8.1 共享组件总表
| 组件 | 用途 | 主要出现页面 |
| --- | --- | --- |
| `TaskContextHeader` | 任务头部上下文 | 确认、执行、报告 |
| `TaskSpine` | 任务主线阶段表达 | 确认、执行、报告 |
| `PlatformStatusTag` | 平台状态标签 | 确认、执行、报告 |
| `PlatformSummaryTile` | 平台摘要卡 | 新建、确认、报告 |
| `CandidateCard` | 候选商品卡片 | 确认 |
| `SelectionBasket` | 已确认集合与主动作 | 确认 |
| `PlatformRunPanel` | 平台运行卡 | 执行 |
| `InsightCard` | 洞察卡片 | 报告 |
| `EvidenceDrawer` | 证据抽屉 | 报告 |
| `QualityFlagPanel` | 质量与限制说明 | 报告 |
| `VersionSwitcher` | 版本切换 | 报告、历史预览 |
| `SessionLauncher` | 发起会话准备/恢复 | 新建、执行 |
| `RetryablePlatformPicker` | 平台级重试选择器 | 执行、历史 |
### 8.2 与组件库的关系
| 类型 | 策略 |
| --- | --- |
| 复用 Ant Design 的部分 | 表单、抽屉、弹层、表格、分段控件、消息提示 |
| 业务自定义组件 | 候选卡、平台运行卡、洞察卡、证据抽屉头部、状态条 |
| 样式控制 | 用全局 Token 和 CSS Variables 覆盖默认色彩、圆角、边框、排版 |
### 8.3 前端模块映射
| 前端模块 | 对应页面 | 核心依赖 |
| --- | --- | --- |
| `task-composer` | 新建任务页 | 任务创建 API、平台可用性摘要、全局会话准备入口 |
| `candidate-board` | 候选确认页 | 平台候选列表、平台状态、用户选择提交 |
| `task-live-console` | 执行页 | 任务详情 API、SSE 事件流、阻塞恢复入口、可重试平台提交 |
| `report-viewer` | 报告页 | `report_snapshot`、版本列表、证据索引 |
| `history-browser` | 历史任务页 | 历史任务列表、筛选、删除、可重试平台提交 |
| `session-console` | 会话准备页 / 阻塞恢复页 | 远程会话分配、状态校验、恢复结果 |
## 9. 响应式与可访问性
### 9.1 响应式策略
| 断点 | 规则 |
| --- | --- |
| `>= 1280px` | 完整工作台布局 |
| `1024px - 1279px` | 侧栏下移，三列变双列或单列 |
| `768px - 1023px` | 候选分区改为折叠面板，报告矩阵改为堆叠卡片 |
| `< 768px` | 保留新建、历史、报告查看和执行状态查看；会话页降级为提示视图 |
### 9.2 可访问性要求
| 要求 | 说明 |
| --- | --- |
| 状态不可只靠颜色 | 必须同时提供图标和文字 |
| 键盘可达 | 主要交互可通过键盘完成 |
| 实时更新可读 | 执行页更新区域需支持 `aria-live` |
| 对比度合规 | 至少满足 `WCAG AA` |
| 动效可减弱 | 支持减少动态偏好 |
## 10. 前端实现约束
### 10.1 状态管理建议
| 技术 | 适用范围 |
| --- | --- |
| `TanStack Query` | 任务详情、历史列表、报告快照、版本列表、平台候选等服务端状态 |
| `Zustand` | 候选页勾选态、报告页证据抽屉开合、历史页筛选器、执行页局部 UI 状态 |
| `SSE` | 执行页实时任务事件 |
### 10.2 接口契约要求
| 契约 | 要求 |
| --- | --- |
| 任务状态字段 | `task_status`、`task_stage`、`platform_status` 必须原样返回枚举值 |
| `NoSelection` | 必须作为正式终态返回 |
| 报告结构 | 直接返回 `PRD` 定义的结构化 Schema |
| 状态映射 | `platform_status -> execution_status` 由后端在发布阶段完成 |
| 候选数据 | 必须包含足以判断的识别字段，不能只给标题和链接 |
| 会话恢复接口 | 必须返回会话模式、恢复状态和来源页信息 |
| 版本列表 | 必须明确“默认版本”和“最新版本”定义 |
| 历史任务无报告场景 | 必须显式返回“无报告”信息 |
### 10.3 文案与日志边界
| 项目 | 原则 |
| --- | --- |
| 用户可见文案 | 只展示用户可理解的状态描述 |
| 开发诊断信息 | 可作为独立字段，不直接暴露技术错误栈 |
| 平台失败原因 | 尽量转译为“登录已失效”“页面校验失败”“评论接口不可用”等可理解表述 |
## 11. 已收口决策
| 决策 | 说明 |
| --- | --- |
| 统一工作台形态 | 只保留“Web 工作台 + 后端统一执行 + 服务端受控会话中心” |
| `NoSelection` 正式化 | 允许确认页以零确认链接结束任务 |
| 报告状态隔离 | 报告页只消费 `execution_status`，运行页和确认页只消费 `platform_status` |
| 重试都是平台级 | 必须通过可重试平台选择器发起 |
| 默认版本策略 | P0 中默认版本等于最新成功版本 |
| 追溯策略 | 90 天追溯依赖证据索引与摘录快照，不依赖长期保留全部原始大对象 |
## 12. UI 验收清单
| 验收项 | 标准 |
| --- | --- |
| 新建任务页可理解 | 用户能看懂平台提示、样本规则和主操作 |
| 会话准备可回跳 | 拉起会话页后，返回能刷新平台状态 |
| 确认页能正确收口 | 支持多选、跳过平台和 `NoSelection` 终态 |
| 执行页三层状态清晰 | 同时表达任务状态、任务阶段、平台状态 |
| `Completed` 与 `PartialCompleted` 区分明显 | 视觉和文案均有明确差异 |
| 报告页先摘要后证据 | 能先读结论，再下钻验证 |
| 历史页不是空账本 | 支持筛选、回看、切换版本、删除和平台级重试 |
| 会话恢复流程闭环 | 入口、状态流、返回路径清晰 |
| 移动端不崩坏 | 至少能完成阅读、状态查看和基础导航 |
## 13. 一句话结论
MVP 的 UI 不应被做成普通后台管理页，而应被设计成一个“围绕任务与证据组织信息的分析工作台”：新建页负责发起，候选页负责判断，执行页负责解释过程，报告页负责支持决策，历史页负责沉淀与回看，会话页负责最短人工介入闭环。

143
docs/review-DevelopmentPlan-codex.md Normal file
View File

@ -0,0 +1,143 @@
# `DevelopmentPlan.md` 审阅报告
- 审阅对象：`docs/DevelopmentPlan.md`
- 文档版本：Draft v0.2
- 审阅时间：2026-04-02
- 审阅人：Codex
## 1. 总体结论
当前版本的 `DevelopmentPlan.md` 还不能作为研发实施基线直接使用，核心问题不在于章节不完整，而在于最关键的实施假设选错了方向。
文档当前把 MVP 建立在“本地部署 + 用户端执行受控浏览器抓取”的前提上，这会把采集执行、会话管理、排障、热修、效率优化和运维能力全部绑定到用户设备，既不利于稳定性，也不利于后续扩大任务量。对这个项目来说，真正需要优先冻结的不是“前端本地还是网页”，而是“采集执行统一放在哪里、默认走哪条采集路径、浏览器自动化在体系中处于什么角色”。
如果要把本项目做成可持续迭代的商品分析工作台，建议把开发计划改为以下基线：
1. 采集执行统一放在后端服务器，不在用户端运行抓取任务。
2. 采集路线采用“API 优先、浏览器兜底”，而不是“浏览器为主、接口为辅”。
3. 受控浏览器的职责收敛为三类：登录与人工介入、接口发现与回放辅助、API 路径失效时的最终兜底。
4. 开发排期先验证三平台接口可行性与能力矩阵，再决定每个平台每个能力点最终落在哪一层采集策略上。
## 2. 当前版本的主要问题
### 2.1 抓取执行位置判断错误
当前文档把 Playwright 调度、本地会话恢复和任务执行都放在用户端机器，这个决策会带来四个直接问题：
1. 无法统一控制采集环境，排障和热修成本高。
2. 无法集中管理平台限流、重试、代理、观测和审计。
3. 会话、浏览器版本、网络环境和系统依赖都受用户设备影响，稳定性不可控。
4. 后续一旦要提升并发或加入协作能力，几乎要重做采集层。
对这类任务型分析系统来说，前端可以是网页，但采集执行应统一放在后端受控环境。
### 2.2 对“如何爬取”讨论过浅
当前版本虽然写了 `Playwright + Adapter`，但没有真正回答以下核心实施问题：
1. 搜索、商品详情、评论抓取分别优先走接口、HTML 内嵌数据还是浏览器 DOM。
2. 每个平台是否有可复用的接口路由、签名参数、请求头和 Cookie 约束。
3. 接口失败时如何逐级降级，而不是直接切到全浏览器抓取。
4. 浏览器在体系中是主通路、辅助通路还是最后兜底。
这部分如果不补齐，研发团队会默认走“先用浏览器抓通，再慢慢优化”，最终大概率得到一个能跑但成本高、速度慢、维护重的版本。
### 2.3 技术栈与部署形态不再匹配
当前文档选用 `SQLite`、本地 Fastify 服务和本地加密会话方案，这套组合适合单机工具，不适合后端统一执行采集任务的服务架构。一旦采集放到服务端，至少要重估以下基础设施：
1. 元数据存储是否切到 `PostgreSQL`。
2. 任务编排是否引入 `Redis + BullMQ` 或同类队列。
3. 原始抓取产物是否放到对象存储，而不是本地文件。
4. 会话密钥是否放到服务端密钥管理，而不是依赖用户系统密钥链。
### 2.4 缺少“能力矩阵 + 采集策略矩阵”
当前文档把三平台视为统一适配对象，但在实际实施中，至少要按“平台 x 能力”拆开定义：
1. 搜索
2. 商品详情
3. 评论
4. 登录与会话恢复
5. 阻塞恢复
每一项能力都应明确优先策略、备选策略、是否依赖会话、是否依赖浏览器、是否可缓存、预期耗时。没有这张矩阵，后续排期无法真实反映风险。
### 2.5 缺少效率目标与策略命中率目标
当前文档只保留了任务总耗时 `P50 <= 20 分钟`，但没有拆解出采集层自身的效率目标，例如：
1. API 路径命中率目标
2. 全浏览器兜底占比目标
3. 单平台搜索耗时目标
4. 单链接商品详情抓取耗时目标
5. 评论抓取吞吐目标
没有这些中间指标，团队会到联调后才发现总耗时超标，却无法判断问题到底出在搜索、评论、浏览器阻塞还是 AI 分析。
### 2.6 P0 中遗漏了删除、留存和旧版本回看实现项
当前文档提到了 30/90 天留存、报告版本快照和历史任务回看，但没有把“任务级删除”“旧版本切换回看”“留存清理作业”明确拆进模块和阶段计划。这会导致这些能力在后期被当作补丁需求，而不是 MVP 的一部分。
## 3. 建议的修订方向
建议把 `DevelopmentPlan.md` 按下面四条主线重写。
### 3.1 先改架构基线
把产品实施基线改为：
1. Web 前端负责任务创建、结果确认、会话处理入口和报告查看。
2. 后端 API 和任务引擎统一调度采集、标准化、聚合和 AI 分析。
3. API 采集 Worker 与 Browser Fallback Worker 分离部署。
4. 所有抓取、会话恢复、日志和审计统一发生在后端受控环境。
### 3.2 把采集策略改成分层模型
建议采用四层策略，从高效率到低效率依次尝试：
1. 直接调用平台页面背后的接口。
2. 解析 HTML/SSR/Hydration 中的结构化数据。
3. 通过浏览器辅助发现接口，再回放请求。
4. 在前三级不可行时，再使用完整浏览器 DOM 抓取。
### 3.3 把阶段计划改成“先验证采集可行性，再做产品闭环”
相比旧版“先搭前端和本地服务，再跑通一个平台”，更合适的顺序是：
1. 先做三平台采集能力调研和能力矩阵。
2. 先跑通一个平台的 API 优先闭环。
3. 再补浏览器兜底与人工介入方案。
4. 最后再做多平台扩展、报告版本和试运行。
### 3.4 把效率和稳定性写成正式验收项
建议新增以下开发与试运行指标：
1. API 优先路径命中率
2. 浏览器全量兜底占比
3. 单平台搜索 `P50`
4. 单链接详情抓取 `P50`
5. 评论抓取吞吐与失败率
6. 平台级重试成功率
## 4. 建议直接补进下一版 DevelopmentPlan 的重点条款
| 模块 | 建议补充条款 |
| --- | --- |
| 产品形态 | 采集执行统一在后端服务器；用户端只承载交互和人工介入入口 |
| 采集策略 | 明确 `API -> Hydration -> Browser Replay -> Browser DOM` 的分层路由 |
| 会话管理 | 用户通过远程受控浏览器处理登录；服务端保存加密会话快照；不保存账号密码 |
| 任务编排 | 采用服务端队列与 Worker 池；区分 API Worker 和 Browser Worker |
| 存储 | 元数据、原始产物、证据快照、会话状态分层存储 |
| 研发计划 | 第一阶段先产出平台能力矩阵与单平台 API PoC，不再默认以 Playwright 打头 |
| 验收标准 | 新增 API 命中率、浏览器兜底占比、删除与留存、旧版本切换回看等验收项 |
## 5. 最终判断
这份 `DevelopmentPlan.md` 的结构框架是可用的，但最重要的实施假设需要调整。当前版本适合“本地工具型采集器”，不适合作为“后端统一执行、强调效率和可维护性”的研发基线。
要进入下一阶段，建议先完成两件事：
1. 重写 `docs/DevelopmentPlan.md`，把采集执行迁移到后端服务器，并把“API 优先、浏览器兜底”写成正式路线。
2. 在下一轮同步检查 `docs/PRD.md` 和 `docs/FeatureSummary.md` 中关于“本地部署/用户端执行”的表述，避免上游与下游文档脱节。

75
docs/review-FeatureSummary-codex.md Normal file
View File

@ -0,0 +1,75 @@
# `FeatureSummary.md` 审阅报告
- 审阅对象：`docs/FeatureSummary.md`
- 文档版本：Draft v0.1
- 审阅时间：2026-04-02
- 审阅人：Codex
## 1. 总体结论
这份 `FeatureSummary.md` 已经把 PRD 中的大部分核心功能、流程、状态和边界压缩成了一份更适合横向对齐的摘要文档，整体方向是对的，且没有明显偏离 MVP 范围。
但如果它要作为“产品、设计、研发和测试快速对齐”的直接基线，当前版本还有 4 个需要尽快收紧的问题：零确认链接任务缺少明确终态、报告 Schema 被压缩得过粗、证据留存策略和可追溯承诺互相冲突、模块级验收口径缺失。这些问题不解决，后续最容易出现的不是“功能没做”，而是“状态口径、接口契约和验收标准各自理解不同”。
## 2. 主要发现
### 2.1 P0：缺少“零确认链接/全无结果”任务的明确终态
当前文档要求“至少确认一个链接后，任务才允许进入抓取流程”（`FeatureSummary.md:167-168`），同时又规定 `NoResult` 和 `Skipped` 不计入失败，且任务最终状态只基于“已确认平台”计算（`FeatureSummary.md:366-369`）。但 `task_status` 枚举中并没有为“用户全部跳过”“所有平台都无结果”“没有任何确认链接可执行”提供稳定终态（`FeatureSummary.md:324-333`）。
这会导致历史任务列表、重试入口和完成率统计出现歧义：任务既不能进入 `Running`，又不完全符合 `Blocked`/`Failed` 的定义，最终很容易在实现里被各端自行兜底。
建议至少补一种明确口径：
1. 增加 `NoSelection` / `NoExecutableTarget` 一类任务终态；或
2. 明确“零确认链接”统一归入 `Failed`，并把该条件写入 `task_status` 定义和汇总规则。
### 2.2 P0：报告结构只保留顶层字段，已经不足以支撑研发与测试对齐
摘要文档当前只保留了报告顶层字段和少量内容要求（`FeatureSummary.md:375-398`），但文档同时又要求：
1. 每条强结论都必须可回溯到证据索引（`FeatureSummary.md:290-292`）。
2. 洞察卡片需包含置信度、样本标记、来源范围和证据引用（`FeatureSummary.md:396-398`）。
3. 报告必须覆盖失败/阻塞平台及质量标记（`FeatureSummary.md:292-293`, `FeatureSummary.md:398`）。
问题在于，这些约束都没有被收敛为字段级契约。例如 `platform_insights` 是否必须包含执行状态、`quality_flags` 的固定字段有哪些、证据引用是 `id` 还是内嵌对象、失败平台如何在报告中表达，当前都没有定义。相比 `PRD.md` 已经给出的详细 Schema（`PRD.md:434-514`），这里的压缩已经丢失了前后端接口和测试用例所需的最小约束。
建议直接把 PRD 中已经冻结的最小 Schema 下沉到摘要文档，至少补齐：
1. `platform_insights[].execution_status`
2. `InsightCard.confidence` / `sample_flag` / `evidence_ids`
3. `evidence_index[].evidence_id` / `source_type` / `review_ref` / `captured_at`
4. `quality_flags.sample_insufficient` / `blocked_platforms` / `failed_platforms`
### 2.3 P1：证据留存策略与“可追溯报告”承诺存在时间窗口冲突
文档规定原始抓取数据默认保存 30 天，而标准化数据和报告保存 90 天（`FeatureSummary.md:410-412`）。但同一份文档又把“可追溯、可用于决策”作为产品核心承诺（`FeatureSummary.md:26`, `FeatureSummary.md:111`, `FeatureSummary.md:452-453`），并要求证据引用可以定位到原证据。
如果第 31 天开始原始抓取数据已经过期，而报告还要继续保留 60 天，那么很多历史报告实际上只剩结论、链接和索引，未必还能完成“定位到原证据”的核验。这会直接削弱文档最强调的证据可信度。
建议二选一：
1. 将原始证据最小留存期对齐到报告留存期；或
2. 在报告侧定义“长期留存的最小证据快照”，例如评论摘要、来源链接、评论引用标识、抓取时间和必要上下文，确保 90 天内仍可核验。
### 2.4 P1：文档目标强调“供设计、研发、测试快速对齐”，但摘要版已丢失模块级验收口径
文档开头明确说这份摘要是给产品、设计、研发和测试快速对齐使用的（`FeatureSummary.md:13`）。但在可验证性上，当前只保留了总体质量指标（`FeatureSummary.md:446-461`），没有保留 PRD 中按模块拆开的验收标准，例如任务创建、搜索召回、状态模型、评论抓取、重试版本等模块的通过条件（`PRD.md:597-614`）。
这会让 QA 和研发在执行层面只能对齐“总体结果”，难以对齐“每个模块做到什么程度算完成”。尤其是异常流和状态流相关能力，很容易在联调后才暴露口径差异。
建议在摘要文档末尾补一个极简“模块级验收清单”，不需要复刻完整 PRD，但至少保留：
1. 搜索召回
2. 候选确认
3. 状态模型
4. 登录与会话
5. 评论抽样
6. 报告可追溯性
7. 失败重试与版本
## 3. 最终判断
这份 `FeatureSummary.md` 作为“功能摘要”已经合格，但作为直接驱动设计、开发和测试协作的摘要基线，仍然少了几条关键硬约束。
优先级上，建议先补“零确认链接终态”和“报告最小 Schema”，这两项会直接影响状态机、接口定义和测试用例；随后再处理证据留存与模块级验收口径，否则这份摘要文档会更像“压缩版说明书”，而不是一份真正可执行的对齐基线。

97
docs/review-PRD-codex.md Normal file
View File

@ -0,0 +1,97 @@
# `PRD.md` 审阅报告
- 审阅对象：`docs/PRD.md`
- 文档版本：Draft v0.1
- 审阅时间：2026-04-02
- 审阅人：Codex
## 1. 总体结论
这份 PRD 已经明显从“需求草案”推进到“可指导 MVP 设计、研发拆解和验收”的阶段。相较前一版 `RequirementsDoc.md`，文档已经补齐了产品目标与非目标、任务状态机、评论抽样口径、数据标准化规则、数据与合规边界、成功指标和验收标准，整体方向正确，范围控制也比较克制。
如果要据此直接进入详细设计和开发排期，当前版本还建议再补齐 3 个 P0 级定义：任务状态的粒度与重试规则、AI 报告的结构化 Schema、搜索与登录态检查的先后关系。这三个点如果不继续收敛，开发阶段仍容易出现前后端契约不一致、异常路径理解不一致和历史结果不可追踪的问题。
## 2. 相比前序需求文档的明显进步
| 维度 | 本版补强点 | 价值 |
| --- | --- | --- |
| 目标定义 | 明确了产品目标与非目标 | 让 MVP 范围更可控，减少后续需求膨胀 |
| 任务机制 | 增加了完整任务状态机 | 有利于处理长任务、阻塞任务和部分成功任务 |
| 抽样口径 | 明确了评论按链接抽样、分层抽样和总量上限 | 降低实现歧义，提升分析稳定性 |
| 数据口径 | 增加商品/评论标准化字段定义 | 为跨平台比较和报告生成提供统一基础 |
| 报告约束 | 明确要求结构化输出、证据引用、置信度标记 | 提升报告的可追溯性和可信度 |
| 安全合规 | 增加会话、数据留存和合规边界 | 把高风险问题前置到产品定义阶段 |
| 验收闭环 | 增加成功指标与 MVP 验收标准 | 让“做完”和“可用”之间有可执行判断标准 |
## 3. 当前文档的主要优点
### 3.1 产品边界足够清晰
文档明确把产品定位为“任务型分析工具”，而不是“持续监控平台”。覆盖平台、输入方式、输出形态和非目标都写得比较克制，这使 MVP 范围收敛得更合理。
### 3.2 主流程和价值闭环已经成立
从“关键词输入”到“候选召回”到“人工确认”再到“抓取、标准化、AI 分析、报告回看”，主流程完整且顺序清楚，已经具备产品化工作流的骨架。
### 3.3 对真实世界异常的考虑比较成熟
文档没有把平台访问理想化，而是明确承认登录失效、验证码、风控拦截、平台失败和部分成功是常态，并为此设计了 `Blocked`、`PartialCompleted` 等状态。这一点很重要，说明文档是在为真实可运行场景做定义，而不是只写 happy path。
### 3.4 多链接与证据回溯设计合理
同一平台允许多选，并采用链接级、平台级、跨平台级三级聚合，这个决策很关键。它既承认多店铺、多销售页并存是常态，又避免了报告被链接级细节完全淹没。
### 3.5 数据标准化与报告可信度意识较强
文档明确要求保留原始字段、允许标准化空值、强制证据优先于结论，并要求关键结论尽量附带来源范围、证据数量和证据引用。这使产品不只是“会生成结论”，而是朝着“结论可验证”推进。
## 4. 仍需明确的关键问题
下表列出当前最值得继续补齐的点。
| 优先级 | 问题 | 当前表现 | 影响 | 建议补充 |
| --- | --- | --- | --- | --- |
| P0 | 任务状态粒度仍偏粗 | 目前状态机主要是任务级状态，但 `Blocked`、`PartialCompleted`、`Failed` 实际混入了平台级异常 | 一旦某个平台阻塞，容易出现“整任务阻塞”还是“其余平台继续”的实现分歧 | 增加 `task_status` 与 `platform_status` 两层状态；明确单平台阻塞、单平台失败、多平台成功时的流转规则 |
| P0 | AI 报告仍缺少可执行 Schema | 文档说明了报告模块和结论卡片要素，但没有定义稳定的数据结构 | 前后端接口、存储模型和提示词约束都可能漂移，导致“都叫结构化，实际格式不同” | 定义固定报告 Schema，例如摘要、平台洞察、风险主题、证据引用、置信度枚举和样本不足标记的字段级约束 |
| P0 | 搜索与登录校验的顺序存在歧义 | 新建任务页要求展示平台可用性提示，主流程中又是先搜索、后检查会话 | 对需要登录才能搜索的平台，产品交互和技术实现都可能出现冲突 | 明确哪些平台的搜索依赖登录态；定义预检查、搜索、确认、抓取前校验的先后关系和降级路径 |
| P1 | 失败重试后的报告版本规则未定义 | 文档支持 `PartialCompleted` 后重试失败平台，但未说明是覆盖旧报告还是生成新版本 | 可能破坏历史回看、审计和用户对“当次结果”的理解 | 增加报告版本策略，至少明确重试是否生成新快照、历史版本是否保留、展示哪个版本为默认 |
| P1 | 候选商品卡片的去重与差异展示规则不够明确 | 当前只定义了候选项应展示哪些字段，没有定义重复候选、同店多 SKU、同款不同规格如何提示 | 用户确认效率和正确性会受到影响 | 增加候选卡片的去重规则、规格差异展示规则和平台内排序依据 |
| P1 | 成功指标偏效率导向，缺少“正确性”衡量 | 当前指标覆盖完成率、时长和可追溯率，但缺少确认对象正确性或报告有效性的抽检指标 | 系统可能“稳定产出”，但不一定“稳定产出正确对象和可信结论” | 增加候选确认准确性抽检、证据引用有效率或试运行报告采纳率等质量指标 |
## 5. 建议优先补齐的五个决策
如果只优先补五件事，建议按下面顺序推进：
1. 明确任务级与平台级双层状态机。
重点回答单平台 `Blocked` 时，其余平台是否继续，以及最终是进入 `Blocked`、`PartialCompleted` 还是 `Completed`。
2. 冻结 AI 报告的结构化 Schema。
需要从“模块要求”进一步收敛到“字段契约”，否则开发和提示词工程很难稳定。
3. 明确搜索、登录检查和抓取校验的交互顺序。
这会直接影响任务入口、异常提示和用户操作成本。
4. 明确失败重试与报告版本策略。
否则历史任务页和报告页的“回看”语义会变得不稳定。
5. 补充质量类成功指标。
让 MVP 不只看“任务跑完没有”，还看“跑出来的对象和结论是否可信”。
## 6. 建议补进下一版 PRD 的补充口径
以下内容可以直接演化为下一版 PRD 的补充条款。
| 模块 | 建议补充口径 |
| --- | --- |
| 状态机 | 每个任务维护一个 `task_status`，每个平台维护一个 `platform_status`；任务最终状态由平台状态汇总决定 |
| 搜索前检查 | 明确平台可用性提示的来源，是静态能力检查、登录态检查，还是最近一次访问结果 |
| 报告结构 | 为报告定义固定字段，如 `summary`、`platform_insights[]`、`positive_themes[]`、`negative_themes[]`、`evidences[]`、`confidence` |
| 证据引用 | 证据引用至少包含平台、链接、评论 ID 或评论索引、抓取时间，避免“有引用但无法定位原证据” |
| 失败重试 | 重试失败平台后，保留旧报告快照，并对新报告标记版本号与更新时间 |
| 质量指标 | 增加人工抽检指标，如候选确认准确率、证据引用有效率、报告被采纳率 |
## 7. 最终判断
这份 PRD 的方向是对的，而且已经解决了前一版需求文档中大部分真正会阻塞开发的定义缺口。当前版本已经足以支持原型设计、数据模型初稿和任务流程拆解。
剩下的问题不在于“还差很多功能点”，而在于“还差少数几个会决定实现一致性的硬约束”。只要把状态粒度、报告 Schema 和搜索/登录顺序这三个问题继续收紧，这份文档就可以作为 MVP 研发和验收的正式基线文档。

126
docs/review-RequirementsDoc-codex.md Normal file
View File

@ -0,0 +1,126 @@
# `RequirementsDoc.md` 审阅报告
- 审阅对象：`docs/RequirementsDoc.md`
- 文档版本：Draft v0.1
- 审阅时间：2026-04-02
- 审阅人：Codex
## 1. 总体结论
这份需求文档已经具备较好的 MVP 雏形，产品定位、目标用户、核心流程、范围边界和数据标准化方向都写得比较清楚，适合作为方案评审和原型设计的基础文档。
但如果要据此直接进入开发，当前版本仍缺少几类关键定义：成功指标、平台接入与登录策略、评论抽样口径、多链接聚合规则、AI 输出验收标准、合规与数据治理要求。换句话说，这份文档已经能回答“要做什么”，但对“做到什么程度算完成”以及“用什么约束保证能落地”定义还不够。
## 2. 文档核心内容梳理
| 维度 | 当前定义 |
| --- | --- |
| 产品定位 | 面向品牌方、电商运营、商品研究/竞品分析岗位的跨平台商品分析工具 |
| 核心价值 | 将跨平台商品搜索、人工确认、商品抓取、评论抓取、标准化和 AI 分析串成闭环 |
| 覆盖平台 | 抖音电商、天猫、京东 |
| 输入方式 | 自然语言输入商品名称或商品描述 |
| 关键机制 | 系统召回候选商品，用户人工确认一个或多个链接 |
| 数据范围 | 商品基础信息、规格/SKU、价格、店铺信息、评论样本 |
| 分析输出 | 卖点提炼、好评点、差评点、跨平台差异、基础运营建议 |
| 任务模式 | 一次性分析任务，不做持续监控 |
| 非目标 | 不做消费者导购、不做内容舆情聚合、不保证全量评论抓取、不承诺绕过风控 |
## 3. 当前文档的主要优点
### 3.1 产品边界控制得比较克制
文档没有一开始就把平台范围、任务形态和分析能力铺得过大，而是明确限定在三大电商平台、一次性分析任务和结构化报告输出，这使 MVP 更容易落地。
### 3.2 核心流程闭环完整
从“用户输入商品”到“搜索候选结果”到“人工确认链接”再到“抓取、标准化、AI 分析、报告输出”，主流程是连贯的，基本覆盖了最小可用闭环。
### 3.3 对真实业务难点有认知
文档明确承认了几个现实问题：同款商品识别困难、平台需要登录、存在验证码和风控、评论不适合全量抓取、允许部分平台失败。这说明文档不是停留在理想状态，而是在向可执行方案靠拢。
### 3.4 多链接场景考虑得较早
同一平台允许确认多个商品链接，这一点很重要。很多竞品分析任务并不是“一平台一个商品页”就能描述完整的，多店铺、多规格、多销售页并存是常态。文档提前把这个场景纳入 MVP，是合理的。
### 3.5 已经具备结构化数据意识
商品字段和评论字段的标准化表格写得比较明确，这对后续做跨平台比较、报告生成、证据回溯都很关键，也能降低后续数据层返工风险。
## 4. 关键问题与缺口
下表按优先级列出当前最值得补齐的内容。
| 优先级 | 问题 | 影响 | 建议补充 |
| --- | --- | --- | --- |
| P0 | 缺少明确的成功指标和验收标准 | 无法判断 MVP 是否达标，开发完成后也难以评估质量 | 增加任务成功率、候选召回可用率、用户确认耗时、报告生成时长、报告可用性评分等指标 |
| P0 | 平台接入方式没有定义清楚 | 技术方案无法收敛，不清楚是浏览器自动化、嵌入式浏览器、现有登录态复用，还是其他方式 | 明确每个平台的接入方式、运行环境、对登录态的依赖方式、失败回退策略 |
| P0 | “用户自有账号授权登录”缺少安全与合规定义 | 涉及账号安全、Cookie/Session 存储、平台条款、数据权限边界，风险很高 | 定义登录信息是否落盘、保存多久、是否加密、是否仅本机使用、异常退出如何清理 |
| P0 | 评论抓取上限 `N` 的口径不清 | 实现和分析结果都会不一致，不清楚 `N` 是按任务、按平台还是按链接生效 | 明确 `N` 的作用域，并定义默认分配方式，例如“每个确认链接独立分配抽样额度” |
| P1 | 评论分层抽样规则还不够落地 | 不同平台的评论排序能力不同，样本可能严重偏斜 | 定义抽样桶优先级、分配比例、去重规则、当平台不支持某类筛选时的降级策略 |
| P1 | 多链接聚合逻辑只定义了方向，没有定义口径 | 平台内汇总、跨平台比较和最终报告都可能出现重复统计或口径不一 | 明确链接级、平台级、跨平台级三层结果的聚合规则，以及重复商品/重复评论的去重标准 |
| P1 | 标准化字段缺少类型、单位和归一规则 | 跨平台对比可能失真，例如价格、销量、评分、时间等字段不可直接比较 | 为字段补充数据类型、单位、空值规则、时间时区、销量格式转换、评分刻度映射 |
| P1 | AI 输出要求偏原则性，缺少结构化验收 | 报告容易变成“能看但不稳定”，且结论难以验证 | 明确 AI 输出模板，要求每类结论都附来源摘要、样本依据或链接引用 |
| P1 | 失败恢复与任务状态缺少状态机定义 | 长任务容易出现中断、重试不一致、用户不知道下一步该做什么 | 增加任务状态流转图，定义可重试节点、人工介入节点、部分失败的最终展示规则 |
| P2 | 报告使用场景还不够细化 | 不同角色对报告期望不同，容易导致“信息很多但不够决策” | 区分品牌运营、商品运营、竞品研究三类用户，补充他们最关心的报告模块 |
| P2 | 性能和成本边界未定义 | 很难预估系统规模、资源成本和用户体验 | 补充单任务目标时长、并发上限、默认评论抓取规模、AI 调用成本约束 |
| P2 | 数据留存与导出策略未定义 | 后续会影响复盘、审计、合规和用户信任 | 定义原始抓取数据、标准化数据、分析报告的保存周期与导出规则 |
## 5. 建议重点补齐的五个决策
如果只允许优先补五件事，建议按下面顺序推进：
1. 定义 MVP 成功标准
例如：三平台任务完成率、候选可确认率、单任务平均完成时长、报告可回溯率。
2. 定义平台接入与登录模型
需要明确是否依赖用户本地浏览器登录态、是否需要独立浏览器容器、如何处理验证码和会话失效。
3. 定义评论抽样与 `N` 的口径
这是后续数据质量和 AI 分析稳定性的基础，不宜留到开发时临场决定。
4. 定义多链接聚合规则
否则平台内多链接一旦出现，最终的汇总、对比和证据引用都会不稳定。
5. 定义 AI 报告模板和证据约束
需要明确哪些是必须输出项，哪些结论必须引用来源，证据不足时如何表述。
## 6. 建议补充的验收标准示例
下面这组内容可以直接演化成下一版 PRD 的验收标准。
| 模块 | 建议验收标准 |
| --- | --- |
| 搜索召回 | 每个平台返回候选列表或明确返回“无结果”；候选项至少包含标题、价格、店铺、链接 |
| 人工确认 | 用户可对每个平台执行单选、多选、跳过；确认结果可回看 |
| 商品抓取 | 对所有确认链接抓取商品信息，并保留原始字段与标准化结果 |
| 评论抓取 | 按既定抽样规则抓取评论；每条评论保留来源信息和所属链接 |
| 标准化 | 输出统一结构，允许空值，但需保留未映射原始字段 |
| AI 分析 | 报告至少包含卖点、好评点、差评点、跨平台差异，并尽量附证据依据 |
| 容错 | 单个平台失败不阻塞整体任务结束，最终结果中能看到失败原因 |
| 可追溯 | 报告中的结论可回溯到平台、商品链接、评论样本或抓取时间 |
## 7. 对下一版 PRD 的结构建议
建议在当前文档基础上新增或强化以下章节：
1. **成功指标与验收标准**
用于定义 MVP 是否真的“可用”。
2. **平台接入与账号安全策略**
用于处理登录态、Cookie、会话复用、异常清理和风险提示。
3. **数据口径定义**
用于统一价格、销量、评分、评论抽样、时间等字段的解释方式。
4. **任务状态机与异常处理**
用于定义可重试、需人工介入、部分失败完成等状态。
5. **AI 报告输出 Schema**
用于约束输出稳定性，避免报告风格和内容漂移。
## 8. 最终判断
这份文档的方向是对的，尤其是“系统召回 + 用户确认 + 原始抓取 + 标准化 + AI 分析”的产品骨架已经成立，且范围控制基本合理。
当前最主要的问题不是“缺功能点”，而是“缺落地约束”。只要把成功标准、登录接入策略、抽样口径、聚合规则和 AI 验收模板补齐，这份文档就能从“思路清晰的需求草案”提升为“可以指导 MVP 设计与开发的正式需求文档”。

220
docs/tasks.md Normal file
View File

@ -0,0 +1,220 @@
# 跨平台商品聚合与 AI 分析开发任务清单
- 文档状态：Draft
- 版本：v0.2
- 更新时间：2026-04-02
- 依据文档：
- `docs/PRD.md`
- `docs/FeatureSummary.md`
- `docs/DevelopmentPlan.md`
- `docs/UIDesign.md`
- `docs/tdd.md`
## 1. 文档目标
本文件用于把上游产品、研发、UI 与 TDD 文档收敛为可执行的开发任务清单，作为后续排期、分工、验收和变更同步的直接依据。
本文重点解决四件事：
1. 明确 P0 开发阶段到底要做哪些任务。
2. 给出任务的执行顺序、依赖关系和阶段出口。
3. 把页面、后端、采集、数据、AI、测试、运维任务统一到同一清单中。
4. 让每个任务都能对应到明确产出、验收标准和测试门禁。
## 2. 使用说明
### 2.1 任务状态约定
本文所有任务初始状态默认为 `未开始`。执行时建议维护以下状态：
| 状态 | 含义 |
| --- | --- |
| `未开始` | 尚未进入开发 |
| `进行中` | 已开始执行但未达到退出条件 |
| `阻塞` | 受外部依赖、平台策略或设计未决问题阻塞 |
| `已完成` | 已满足本文定义的产出、验收和测试门禁 |
### 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 天证据索引与摘录 |
| 变更必须联动同步 | 上游文档或枚举变更后，需同步检查 `tasks.md` 与下游实现是否失效 |
## 4. 开发启动门禁
进入编码前，至少满足以下条件：
| 门禁项 | 要求 |
| --- | --- |
| 文档齐备 | `PRD`、`FeatureSummary`、`DevelopmentPlan`、`UIDesign`、`tdd`、`tasks` 已齐全 |
| 任务拆解完成 | 本文已完成并可直接用于排期 |
| 评审门禁 | 本文需按仓库流程完成 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` 是否失效，必要时同步修订 |
| `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 闭环展开：先冻结双平台能力矩阵和测试资产，再搭骨架与单平台闭环，再扩双平台与阻塞恢复，最后补齐结构化报告、历史版本、留存删除与试运行；任何偏离这条主线的需求，都不应进入当前开发排期。

452
docs/tdd.md Normal file
View File

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