# `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` 中关于“本地部署/用户端执行”的表述，避免上游与下游文档脱节。