# 跨平台商品聚合与 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 平台能力拆成“会话驱动请求回放优先、浏览器仅用于会话与模板刷新”的分层路线，先完成天猫与京东的高效率闭环，再进入版本回看、稳定试运行和后续淘宝扩展，而不是一开始就把浏览器自动化当作默认主通路。