crawler-plugin/docs/plans/00-plan-overview.md

# crawler-plugin 性能与资源优化 Plan 总览

> 生成时间：2026-08-29T14:02:50+08:00（Asia/Shanghai）
> 适用仓库：`D:/todesk/副业/数富AI/crawler-plugin`
> 当前基线：HEAD `3229056`（2026-08-29），本计划来源为代码审计；仓库当前不存在 `docs/specs/`，因此本文件先作为现状优化计划总览。

## 1. 计划说明

本计划针对大数据量、多图片、多任务并发场景，覆盖 Java 主后端、Python 插件后端、Vue 前端以及数据库/Redis/RustFS/RocketMQ 资源链路。

每个任务按约 8-15 分钟设计，开发时必须严格执行以下 TDD 顺序：

1. 先编写该任务全部测试；
2. 运行测试确认 RED；
3. 实现功能并运行测试确认 GREEN；
4. 执行 lint/format、定向测试和必要的集成验证；
5. 任务独立提交 commit 后，才能开始下一个任务。

涉及 I/O、数据库、HTTP、RustFS、Redis、文件或外部服务的任务，必须包含 mock 单元测试和至少一个真实集成/启动调用验证。每个普通功能任务在对应模块计划中至少列出 8 个语义化测试用例：正常路径 3 个、边界 3 个、异常/错误 2 个。

## 2. 已验证基线

- `backend-java`：`mvn -q -DskipTests compile` 通过。
- `backend-java`：`mvn -q test`，54 个测试类、344 项测试，0 失败。
- `frontend-vue`：`npm run build` 通过；仍有公共 chunk 超过 500KB 的构建警告。
- `backend`：`python -m unittest discover -s tests -p "test*.py"`，13 项测试通过。
- 当前没有生产压测、JFR、数据库 EXPLAIN 和真实 RustFS/Coze 指标，因此计划中的性能收益必须通过后续基准和压测确认。

## 3. 模块与任务范围

| 模块编号 | 模块 | 任务范围 | 任务数 |
|---|---|---:|---:|
| 01 | Similar ASIN 性能与资源优化 | 1-20 | 20 |
| 02 | 店铺数据抓取性能与累计文件优化 | 21-40 | 20 |
| 03 | 采集数据批处理与结果文件优化 | 41-60 | 20 |
| 04 | 共享任务、对象存储、调度与清理优化 | 61-80 | 20 |
| 05 | 前端轮询、缓存、构建与交付验收 | 81-100 | 20 |

模块计划文件将在本总览确认后按模块单独生成，不合并不同模块；每个模块文件将补充详细功能要求、完整测试清单、TDD RED/GREEN 流程和验证命令。

## 4. 全部任务清单

| N | 功能点 | 模块 | 依赖 | 预估耗时 |
|---:|---|---|---|---|
| 1 | 建立 Similar ASIN 性能基线夹具：1000/5000 行、图片开关、chunk 数与 payload 大小采样 | Similar ASIN 性能与资源优化 | 无 | 8-15 分钟 |
| 2 | 将解析载荷改为单一规范行集合，消除 items/groups/allItems 重复数据结构 | Similar ASIN 性能与资源优化 | 1 | 8-15 分钟 |
| 3 | 保留旧 payload 读取兼容逻辑，并验证新旧结构均可恢复全量行 | Similar ASIN 性能与资源优化 | 2 | 8-15 分钟 |
| 4 | 解析接口改为只返回固定数量预览行，完整行仅保存在后端任务载荷 | Similar ASIN 性能与资源优化 | 3 | 8-15 分钟 |
| 5 | 为预览行数量增加配置边界、空文件和超限输入校验 | Similar ASIN 性能与资源优化 | 4 | 8-15 分钟 |
| 6 | 将分组数据改为索引/范围引用，避免 groups 嵌套复制完整行对象 | Similar ASIN 性能与资源优化 | 5 | 8-15 分钟 |
| 7 | 限制单文件大小、最大行数和最大字段长度，防止解析任务无界增长 | Similar ASIN 性能与资源优化 | 6 | 8-15 分钟 |
| 8 | 将 WorkbookFactory 输入解析改为受控读取，并验证超大 Excel 的失败提示 | Similar ASIN 性能与资源优化 | 7 | 8-15 分钟 |
| 9 | 将 chunk 查询从单行分页改为批量 keyset 分页，保持低内存读取 | Similar ASIN 性能与资源优化 | 8 | 8-15 分钟 |
| 10 | 为 chunk 结果建立按 row key 的批量索引，消除跨 chunk 线性扫描 | Similar ASIN 性能与资源优化 | 9 | 8-15 分钟 |
| 11 | 将 Coze 结果合并的重复检测从 O(n²) 改为 HashSet/稳定 row key | Similar ASIN 性能与资源优化 | 10 | 8-15 分钟 |
| 12 | 扩展 Coze 结果缓冲覆盖范围，减少频繁读写完整 chunk payload | Similar ASIN 性能与资源优化 | 11 | 8-15 分钟 |
| 13 | 为 chunk 合并增加单次最大行数与 payload 字节上限 | Similar ASIN 性能与资源优化 | 12 | 8-15 分钟 |
| 14 | 图片 DB cache 改为批量读取缩略图，并只更新实际命中的 last_used_at | Similar ASIN 性能与资源优化 | 13 | 8-15 分钟 |
| 15 | 将图片缓存访问时间更新改为异步批量刷新，减少逐图 UPDATE | Similar ASIN 性能与资源优化 | 14 | 8-15 分钟 |
| 16 | 图片预取改为短预算 best-effort，超时后直接回退 URL | Similar ASIN 性能与资源优化 | 15 | 8-15 分钟 |
| 17 | 优化图片解码采样、像素上限和 JPEG 质量搜索，降低 CPU 与堆峰值 | Similar ASIN 性能与资源优化 | 16 | 8-15 分钟 |
| 18 | 统一图片 spool 生命周期，确保超时、取消和异常路径删除临时文件 | Similar ASIN 性能与资源优化 | 17 | 8-15 分钟 |
| 19 | 将 Coze 请求/响应及 Python 回传日志改为采样、截断和 DEBUG 级别 | Similar ASIN 性能与资源优化 | 18 | 8-15 分钟 |
| 20 | 完成 Similar ASIN 端到端压测、JFR/GC 分析与结果文件兼容回归 | Similar ASIN 性能与资源优化 | 19 | 8-15 分钟 |
| 21 | 建立店铺抓取性能基线：单店铺 1k/5k 行、多国家、图片成功/失败场景 | 店铺数据抓取性能与累计文件优化 | 无 | 8-15 分钟 |
| 22 | 将店铺 Excel 图片缓存替换为有界字节缓存 | 店铺数据抓取性能与累计文件优化 | 21 | 8-15 分钟 |
| 23 | 图片嵌入成功后立即释放外部缩略图字节副本 | 店铺数据抓取性能与累计文件优化 | 22 | 8-15 分钟 |
| 24 | 为店铺图片预取增加任务级数量、字节和超时上限 | 店铺数据抓取性能与累计文件优化 | 23 | 8-15 分钟 |
| 25 | 评估并实现店铺结果 workbook 的 SXSSF 或 spool 化写入路径 | 店铺数据抓取性能与累计文件优化 | 24 | 8-15 分钟 |
| 26 | 为模板 workbook 增加大行数下的样式、图片和工作表兼容测试 | 店铺数据抓取性能与累计文件优化 | 25 | 8-15 分钟 |
| 27 | 将 chunk 接收改为原子插入/幂等 upsert，减少先查后插 | 店铺数据抓取性能与累计文件优化 | 26 | 8-15 分钟 |
| 28 | 以 scope 计数器替代每个 chunk 的 COUNT(*) 完整统计 | 店铺数据抓取性能与累计文件优化 | 27 | 8-15 分钟 |
| 29 | 合并 scope 状态查询与更新，减少单 chunk 数据库往返 | 店铺数据抓取性能与累计文件优化 | 28 | 8-15 分钟 |
| 30 | 为国家结果行建立稳定去重键，替换线性重复扫描 | 店铺数据抓取性能与累计文件优化 | 29 | 8-15 分钟 |
| 31 | 将任务快照改为轻量进度字段，避免每次写入完整结果 JSON | 店铺数据抓取性能与累计文件优化 | 30 | 8-15 分钟 |
| 32 | 将 task entity 本地缓存替换为有容量和过期回收的实现 | 店铺数据抓取性能与累计文件优化 | 31 | 8-15 分钟 |
| 33 | 将店铺源文件 key 映射改为确定路径，取消临时目录递归扫描 | 店铺数据抓取性能与累计文件优化 | 32 | 8-15 分钟 |
| 34 | 将 ownerInstanceId 从 JSON 查询迁移到显式列并补充索引 | 店铺数据抓取性能与累计文件优化 | 33 | 8-15 分钟 |
| 35 | 将每日累计文件改为数据层增量模型，避免每次下载并重写完整 XLSX | 店铺数据抓取性能与累计文件优化 | 34 | 8-15 分钟 |
| 36 | 为每日累计文件引入版本号/CAS，缩短店铺级锁的持有时间 | 店铺数据抓取性能与累计文件优化 | 35 | 8-15 分钟 |
| 37 | 拆分每日累计文件组装与任务结果接收，增加异步文件作业状态 | 店铺数据抓取性能与累计文件优化 | 36 | 8-15 分钟 |
| 38 | 历史列表与进度查询增加分页、字段裁剪和批量任务加载 | 店铺数据抓取性能与累计文件优化 | 37 | 8-15 分钟 |
| 39 | 补充删除、超时、重复回传和累计文件失败的资源清理测试 | 店铺数据抓取性能与累计文件优化 | 38 | 8-15 分钟 |
| 40 | 完成店铺抓取压测并比较内存、CPU、DB QPS、对象存储流量和锁等待 | 店铺数据抓取性能与累计文件优化 | 39 | 8-15 分钟 |
| 41 | 建立 Collect Data 1k/10k 行、多个 chunk 和品牌检测场景基线 | 采集数据批处理与结果文件优化 | 无 | 8-15 分钟 |
| 42 | 限制采集解析的文件大小、最大行数和单 chunk 行数 | 采集数据批处理与结果文件优化 | 41 | 8-15 分钟 |
| 43 | 将采集源文件查找改为确定路径/索引查询 | 采集数据批处理与结果文件优化 | 42 | 8-15 分钟 |
| 44 | 保留原始 chunk payload 的同时，减少逐行 extra JSON 的重复序列化 | 采集数据批处理与结果文件优化 | 43 | 8-15 分钟 |
| 45 | 将 ASIN 去重查询与无效品牌查询统一为批量集合查询 | 采集数据批处理与结果文件优化 | 44 | 8-15 分钟 |
| 46 | 跳过空品牌批次的无效远程品牌检查请求 | 采集数据批处理与结果文件优化 | 45 | 8-15 分钟 |
| 47 | 为品牌检查结果增加任务内短期缓存，避免同品牌重复远程调用 | 采集数据批处理与结果文件优化 | 46 | 8-15 分钟 |
| 48 | 将 invalid ASIN 记录改为批量 INSERT IGNORE/upsert | 采集数据批处理与结果文件优化 | 47 | 8-15 分钟 |
| 49 | 将结果明细从逐行 RustFS 对象改为 chunk 级 payload 存储 | 采集数据批处理与结果文件优化 | 48 | 8-15 分钟 |
| 50 | 为结果明细设计批量 upsert mapper 与幂等唯一键 | 采集数据批处理与结果文件优化 | 49 | 8-15 分钟 |
| 51 | 将 accepted 行的序列化和 hash 计算改为批量处理 | 采集数据批处理与结果文件优化 | 50 | 8-15 分钟 |
| 52 | 生成结果文件时按 chunk 一次读取，取消逐行对象读取 | 采集数据批处理与结果文件优化 | 51 | 8-15 分钟 |
| 53 | 将 rawRows 与 finalRows 的内存生命周期分段，避免同时长期驻留 | 采集数据批处理与结果文件优化 | 52 | 8-15 分钟 |
| 54 | 将 finalRowCount 从每个 chunk COUNT(*) 改为任务内增量计数 | 采集数据批处理与结果文件优化 | 53 | 8-15 分钟 |
| 55 | 将进度统计更新改为节流/合并写，减少高频 task UPDATE | 采集数据批处理与结果文件优化 | 54 | 8-15 分钟 |
| 56 | 为采集结果文件增加流式写入失败后的临时文件清理 | 采集数据批处理与结果文件优化 | 55 | 8-15 分钟 |
| 57 | 为采集结果对象增加数据库删除与物理对象删除的一致性处理 | 采集数据批处理与结果文件优化 | 56 | 8-15 分钟 |
| 58 | 补充外部品牌服务不可用、RustFS 超时和重复 chunk 的降级测试 | 采集数据批处理与结果文件优化 | 57 | 8-15 分钟 |
| 59 | 完成采集模块数据库索引、批量 SQL 和对象存储调用次数验证 | 采集数据批处理与结果文件优化 | 58 | 8-15 分钟 |
| 60 | 完成采集模块 10k 行压测并验收结果完整性、内存和吞吐 | 采集数据批处理与结果文件优化 | 59 | 8-15 分钟 |
| 61 | 建立共享任务链路资源指标基线：线程、连接、队列、GC、Redis、RustFS 和 DB | 共享任务、对象存储、调度与清理优化 | 无 | 8-15 分钟 |
| 62 | 为本地任务实体缓存增加最大条目数、TTL 和定时清理 | 共享任务、对象存储、调度与清理优化 | 61 | 8-15 分钟 |
| 63 | 为前端/后端进度快照增加写入去重和最小更新间隔 | 共享任务、对象存储、调度与清理优化 | 62 | 8-15 分钟 |
| 64 | 将 transient payload 压缩改为直接 gzip 二进制流上传 | 共享任务、对象存储、调度与清理优化 | 63 | 8-15 分钟 |
| 65 | 为 transient payload 读取增加流式解压和解压后字节上限 | 共享任务、对象存储、调度与清理优化 | 64 | 8-15 分钟 |
| 66 | 限制 RustFS 并发读写与重试的总资源预算，防止多任务叠加爆发 | 共享任务、对象存储、调度与清理优化 | 65 | 8-15 分钟 |
| 67 | 复用 RustFS/MinIO 客户端与 HTTP 连接池，减少每次操作创建客户端 | 共享任务、对象存储、调度与清理优化 | 66 | 8-15 分钟 |
| 68 | 将 payload 引用删除改为批量引用检查与异步物理删除 | 共享任务、对象存储、调度与清理优化 | 67 | 8-15 分钟 |
| 69 | 为数据库删除任务补充 transient payload 指针收集和清理队列 | 共享任务、对象存储、调度与清理优化 | 68 | 8-15 分钟 |
| 70 | 将历史清理改为 keyset 分页、小批量和短事务 | 共享任务、对象存储、调度与清理优化 | 69 | 8-15 分钟 |
| 71 | 清理日志改为数量与 sample ID，禁止输出超长任务 ID 列表 | 共享任务、对象存储、调度与清理优化 | 70 | 8-15 分钟 |
| 72 | 为文件作业实现数据库原子 claim，避免重复派发同一 job | 共享任务、对象存储、调度与清理优化 | 71 | 8-15 分钟 |
| 73 | 为本地文件作业队列增加 in-flight 去重和队列背压 | 共享任务、对象存储、调度与清理优化 | 72 | 8-15 分钟 |
| 74 | 隔离调度线程池、文件作业线程池和外部 Coze/图片执行池 | 共享任务、对象存储、调度与清理优化 | 73 | 8-15 分钟 |
| 75 | 为虚拟线程任务增加等待队列上限与拒绝/延迟指标 | 共享任务、对象存储、调度与清理优化 | 74 | 8-15 分钟 |
| 76 | 将 JSON owner 查询迁移到显式列并补充任务/状态复合索引 | 共享任务、对象存储、调度与清理优化 | 75 | 8-15 分钟 |
| 77 | 统一 Coze、品牌检查和紫鸟 HTTP 客户端的连接复用策略 | 共享任务、对象存储、调度与清理优化 | 76 | 8-15 分钟 |
| 78 | 为所有外部调用增加耗时、重试、失败率和 payload 字节指标 | 共享任务、对象存储、调度与清理优化 | 77 | 8-15 分钟 |
| 79 | 为对象存储、数据库和队列增加故障注入测试 | 共享任务、对象存储、调度与清理优化 | 78 | 8-15 分钟 |
| 80 | 补充 JVM 堆、直接内存、临时磁盘和连接池容量配置说明 | 共享任务、对象存储、调度与清理优化 | 79 | 8-15 分钟 |
| 81 | 建立前端任务轮询请求量、响应体大小和页面内存基线 | 前端轮询、缓存、构建与交付验收 | 无 | 8-15 分钟 |
| 82 | 为进度响应 Map 增加 TTL 清理与最大条目数 | 前端轮询、缓存、构建与交付验收 | 81 | 8-15 分钟 |
| 83 | 统一不同页面的轮询去重、in-flight 合并和终态清理 | 前端轮询、缓存、构建与交付验收 | 82 | 8-15 分钟 |
| 84 | 优化店铺抓取队列状态合并，消除 historyItems 的线性重复查找 | 前端轮询、缓存、构建与交付验收 | 83 | 8-15 分钟 |
| 85 | 优化 Similar ASIN 轮询与文件生成等待，避免重复 force 请求 | 前端轮询、缓存、构建与交付验收 | 84 | 8-15 分钟 |
| 86 | 将隐藏页面轮询间隔、前台恢复和退避策略统一配置化 | 前端轮询、缓存、构建与交付验收 | 85 | 8-15 分钟 |
| 87 | 限制 localStorage 中任务、快照和队列数据的最大数量/字节数 | 前端轮询、缓存、构建与交付验收 | 86 | 8-15 分钟 |
| 88 | 解析结果前端只接收预览数据，避免大 payload 进入响应式对象 | 前端轮询、缓存、构建与交付验收 | 87 | 8-15 分钟 |
| 89 | 清理页面卸载时的所有 timer、请求和临时 URL | 前端轮询、缓存、构建与交付验收 | 88 | 8-15 分钟 |
| 90 | 为进度接口增加断网、超时、服务恢复和重复响应测试 | 前端轮询、缓存、构建与交付验收 | 89 | 8-15 分钟 |
| 91 | 按页面拆分 Element Plus 与公共业务 chunk | 前端轮询、缓存、构建与交付验收 | 90 | 8-15 分钟 |
| 92 | 配置 Vite manualChunks 并比较各页面首屏传输大小 | 前端轮询、缓存、构建与交付验收 | 91 | 8-15 分钟 |
| 93 | 补充 Similar ASIN、店铺抓取和采集数据页面的 E2E 核心路径 | 前端轮询、缓存、构建与交付验收 | 92 | 8-15 分钟 |
| 94 | 补充移动端与桌面端响应式页面验收截图 | 前端轮询、缓存、构建与交付验收 | 93 | 8-15 分钟 |
| 95 | 补充深色主题、错误提示、重试和终态刷新验收 | 前端轮询、缓存、构建与交付验收 | 94 | 8-15 分钟 |
| 96 | 建立 Java/Python/Vue 三端统一的 API 字段兼容检查 | 前端轮询、缓存、构建与交付验收 | 95 | 8-15 分钟 |
| 97 | 执行 Java 全量测试、Python unittest、Vue 类型检查与构建 | 前端轮询、缓存、构建与交付验收 | 96 | 8-15 分钟 |
| 98 | 执行真实启动、健康检查、核心请求和外部依赖调用验证 | 前端轮询、缓存、构建与交付验收 | 97 | 8-15 分钟 |
| 99 | 执行全链路压测并记录 CPU、内存、GC、DB、Redis、RustFS、网络结果 | 前端轮询、缓存、构建与交付验收 | 98 | 8-15 分钟 |
| 100 | 完成发布前回滚演练、git commit 对应关系检查和交付清单 | 前端轮询、缓存、构建与交付验收 | 99 | 8-15 分钟 |

## 5. 收尾硬性 Gate

以下验证不是可选项，任一失败都不能视为计划完成：

1. 使用项目实际启动命令启动 Java 服务，并通过健康检查端点。
2. 启动 Python 后端并确认核心管理入口可访问。
3. 访问 Similar ASIN、店铺数据抓取和采集数据页面，确认关键元素存在。
4. 使用真实最小文件完成一次解析、任务创建、任务执行和结果下载。
5. 使用多样化输入验证关键业务逻辑不是固定模板或纯回显。
6. 验证数据库、Redis、RustFS、RocketMQ 和外部 HTTP 服务确实发生调用。
7. 验证非法输入、依赖不可用、超时、断网和重复回传有明确错误或降级行为。
8. 验证任务取消、页面关闭、服务重启和 owner 路由后不会残留锁、线程、timer 或临时文件。
9. Java 全量测试全绿。
10. Python 测试全绿。
11. Vue 类型检查和生产构建通过。
12. Java、Python 和前端 lint/format 检查零错误。
13. Playwright 完成桌面端页面可访问和关键交互路径验证。
14. Playwright 验证断网、恢复、错误提示和重试行为。
15. 页面主题切换行为符合预期（如项目页面支持主题）。
16. 保存 Desktop 1280x800 与 Mobile 375x812 响应式验收截图。
17. 执行 Java、Python、Vue 三端接口字段一致性检查。
18. 执行 `git log` 检查 1-100 每个任务均有对应 commit。
19. 最后执行 `python check_progress.py`，仅当输出 `all tasks done` 且退出码为 0 时才宣布计划完成。

## 6. 当前阶段

当前已生成本 `00-plan-overview.md`、5 个模块详细 plan 文件及根目录 `progress.json`；各任务状态全部为 `pending`。详细 plan 已按模块拆分，完成全部任务后执行收尾 Gate 并进入 Step 3。

总任务数：100