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