Files
crawler-plugin/backend-java/docs/plans/00-plan-overview.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

234 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 00-plan-overview.md — 全部任务总表
> 来源:`backend-java/docs/specs/00-overview.md` 与 01-13 号 spec(2026-08-31)
> 任务粒度:每个功能点 8-15 分钟(写测试 ≥8 用例 → RED → 实现 → GREEN)
> 执行纪律:单线程串行,禁止并行 agent 写代码;每任务独立 commit
## 任务总表
| N | 功能点 | 模块 | 依赖 |
|---|---|---|---|
| 1 | API_ENDPOINTS 路径常量表(17 页面模块路径分组) | 01 适配层 | 无 |
| 2 | buildJavaUrl() 统一 URL 构造(前缀+endpoint+query) | 01 适配层 | 1 |
| 3 | callJava() 统一响应解包(success/message/data + 非包装直通) | 01 适配层 | 2 |
| 4 | extractErrorMessage 导出并覆盖 error/message/msg 三字段 | 01 适配层 | 3 |
| 5 | normalizeStatus() 大小写归一(未知值透传) | 01 适配层 | 3 |
| 6 | isTerminalStatus() 终态判定(SUCCESS/FAILED/CANCELLED 可配置) | 01 适配层 | 5 |
| 7 | buildDownloadUrl() 统一下载 URL(user_id 附加规则) | 01 适配层 | 2 |
| 8 | callJava 透传 AbortController(signal 取消) | 01 适配层 | 3 |
| 9 | 进度类请求默认 10s 超时配置 | 01 适配层 | 3 |
| 10 | types/task.ts 共享类型(TaskStatus/FilePhase/PageResult) | 01 适配层 | 无 |
| 11 | 拆分 dedupe 模块 API(函数移动+行为不变测试) | 01 适配层 | 1,3 |
| 12 | 拆分 split 模块 API | 01 适配层 | 1,3 |
| 13 | 拆分 convert 模块 API | 01 适配层 | 1,3 |
| 14 | 拆分 publish 模块 API | 01 适配层 | 1,3 |
| 15 | 拆分 similar-asin 模块 API | 01 适配层 | 1,3 |
| 16 | 拆分 appearance-patent 模块 API | 01 适配层 | 1,3 |
| 17 | 拆分 delete-brand 模块 API | 01 适配层 | 1,3 |
| 18 | 拆分 price-track 模块 API | 01 适配层 | 1,3 |
| 19 | 拆分 shop-match/product-risk 模块 API | 01 适配层 | 1,3 |
| 20 | 拆分 shop-data-crawl/query-asin 模块 API | 01 适配层 | 1,3 |
| 21 | 拆分 withdraw/patrol-delete 模块 API | 01 适配层 | 1,3 |
| 22 | 拆分 collect-data 模块 API | 01 适配层 | 1,3 |
| 23 | 拆分 image-video/brand/permission/digital-human 模块 API | 01 适配层 | 1,3 |
| 24 | java-modules.ts 改 re-export 聚合(旧 import 零改动) | 01 适配层 | 11-23 |
| 25 | ResultFilePhase 新字段兼容默认值(可选字段兜底) | 01 适配层 | 10 |
| 26 | 模块 API 快照契约测试基建(mock adapter 断言 URL/method/query) | 01 适配层 | 3 |
| 27 | api-field-compat 注册高频响应 schema(task/result 核心字段) | 01 适配层 | 26 |
| 28 | 死代码清理(拆分后未引用导出,grep 确认后删) | 01 适配层 | 24 |
| 29 | 退避配置项(MaxMs/Factor 常量 + 默认值) | 02 轮询 | 无 |
| 30 | getTaskPollBackoffMs 递增序列(500→1000→…→10000) | 02 轮询 | 29 |
| 31 | 连续失败计数(成功/收到响应归零) | 02 轮询 | 30 |
| 32 | 退避封顶(maxMs 后不再增长) | 02 轮询 | 30,31 |
| 33 | 网络错误走退避且不触发终态 | 02 轮询 | 31 |
| 34 | HTTP 4xx/5xx 与网络错误分类(记 onError) | 02 轮询 | 31 |
| 35 | 未知状态不判终态测试固化(PENDING/SYNCING/空串) | 02 轮询 | 无 |
| 36 | 终态任务仅一次 onTerminal(coordinator 语义) | 02 轮询 | 无 |
| 37 | onTerminal 抛错后任务已移除语义测试(页面可重新 add) | 02 轮询 | 无 |
| 38 | 同一轮多任务终态分别回调测试 | 02 轮询 | 无 |
| 39 | in-flight 合并(timer 不叠加)测试补强 | 02 轮询 | 无 |
| 40 | 页面隐藏降频(30s)与可见恢复(立即刷新)测试 | 02 轮询 | 无 |
| 41 | storage 恢复(无效 id 过滤/空清理)测试 | 02 轮询 | 无 |
| 42 | 退避恢复测试(失败→退避→成功→正常间隔) | 02 轮询 | 31,32 |
| 43 | progressCache TTL 惰性清理边界测试 | 02 轮询 | 无 |
| 44 | fetchProgress 轻量端点切换能力(getModuleProgressLight 接入) | 02 轮询 | 26 |
| 45 | 轮询与历史刷新分离测试 | 02 轮询 | 无 |
| 46 | 双页面同 key 互踩行为记录测试(只读断言现状) | 02 轮询 | 无 |
| 47 | 轮询 baseline 统计(请求量/响应体大小)测试补强 | 02 轮询 | 无 |
| 48 | 轮询全量回归(20 个既有测试保持绿) | 02 轮询 | 29-47 |
| 49 | multipart 直通断言补测(content-type 大小写变体) | 03 过滤器 | 无 |
| 50 | JSON/PUT/DELETE 包装与阈值钳制补测 | 03 过滤器 | 无 |
| 51 | 日志不读 body 行为测试(过滤器通过后 body 仍可读) | 03 过滤器 | 无 |
| 52 | 阈值生效集成测试(>1MB 请求不整包缓存) | 03 过滤器 | 无 |
| 53 | yml 默认值 1MB 与 env 覆盖测试 | 03 过滤器 | 无 |
| 54 | TaskOwnerForwardService 转发 multipart 安全测试(inputStream 路径) | 03 过滤器 | 无 |
| 55 | 转发后 body 完整性测试(转发请求体与原请求一致) | 03 过滤器 | 54 |
| 56 | plan §6 文档现状修正核对 | 03 过滤器 | 无 |
| 57 | ResultFileJobHandler 接口定义(moduleType/process/cleanup/onFailure/offload/ownerScoped) | 04 注册表 | 无 |
| 58 | 注册表容器(List 收集 + moduleType 唯一性校验) | 04 注册表 | 57 |
| 59 | 启动校验(缺注册/双注册 fail-fast) | 04 注册表 | 58 |
| 60 | SHOP_MATCH Handler(委托+payload.deleteLatest) | 04 注册表 | 57-59 |
| 61 | PRICE_TRACK Handler | 04 注册表 | 57-59 |
| 62 | PRODUCT_RISK_RESOLVE Handler | 04 注册表 | 57-59 |
| 63 | PUBLISH Handler(ownerScoped) | 04 注册表 | 57-59 |
| 64 | QUERY_ASIN Handler | 04 注册表 | 57-59 |
| 65 | SHOP_DATA_CRAWL Handler(cleanup+onFailure) | 04 注册表 | 57-59 |
| 66 | WITHDRAW Handler(tryFinalizeTask 时机保持) | 04 注册表 | 57-59 |
| 67 | PATROL_DELETE Handler | 04 注册表 | 57-59 |
| 68 | APPEARANCE_PATENT Handler(异步返回+offload+ownerScoped) | 04 注册表 | 57-59 |
| 69 | SIMILAR_ASIN Handler(异步+offload+ownerScoped+onFailure) | 04 注册表 | 57-59 |
| 70 | DELETE_BRAND Handler | 04 注册表 | 57-59 |
| 71 | BRAND Handler(resolveResultObjectKey 特例) | 04 注册表 | 57-59 |
| 72 | COLLECT_DATA Handler | 04 注册表 | 57-59 |
| 73 | Worker dispatch() 改注册表查找 | 04 注册表 | 60-72 |
| 74 | cleanupAfterSuccess 改 handler.cleanup + 公共 payload 清理 | 04 注册表 | 60-72 |
| 75 | notifyRetryExhausted 改 handler.onFailure | 04 注册表 | 60-72 |
| 76 | coze offload 判定改 handler.supportsAsyncOffload | 04 注册表 | 60-72 |
| 77 | owner-scoped 判定改 handler.isOwnerScoped | 04 注册表 | 60-72 |
| 78 | 模块映射快照测试(13 moduleType → Handler → 原方法) | 04 注册表 | 73 |
| 79 | 行为等价对比测试(Job 状态迁移序列一致) | 04 注册表 | 73-77 |
| 80 | 孤儿失败路径不回归(markFailedPermanent) | 04 注册表 | 73 |
| 81 | 卡死扫描/重试耗尽路径测试 | 04 注册表 | 73 |
| 82 | 特殊规则回归(WITHDRAW finalize、coze 等待 defer) | 04 注册表 | 78-81 |
| 83 | SimilarAsinExcelParser 行解析器(POI 读行→中间行对象) | 05 拆分 | 无 |
| 84 | 行解析边界(空行/超长/畸形 ASIN/BOM/混合编码) | 05 拆分 | 83 |
| 85 | 字段归一化器(trim/大小写/ASIN 格式统一) | 05 拆分 | 无 |
| 86 | 分组转换器(中间对象→TaskItem/FileItem) | 05 拆分 | 83,85 |
| 87 | 纯校验器(必填/格式/去重) | 05 拆分 | 85 |
| 88 | Sheet 构造器(workbook 构建辅助) | 05 拆分 | 无 |
| 89 | SimilarAsinService.parse 门面改委托(签名不变) | 05 拆分 | 83-88 |
| 90 | 抽取前后快照对比测试(夹具 Excel 同断言) | 05 拆分 | 89 |
| 91 | SimilarAsin 历史查询组装抽取(VO 拼装) | 05 拆分 | 无 |
| 92 | SimilarAsin 全量回归(mvn test 相关类) | 05 拆分 | 89-91 |
| 93 | AppearancePatent 行解析/归一化抽取 | 05 拆分 | 83,85 |
| 94 | AppearancePatent Sheet 构造抽取 | 05 拆分 | 88 |
| 95 | AppearancePatent 门面改委托(签名不变) | 05 拆分 | 93,94 |
| 96 | AppearancePatent 快照对比测试 | 05 拆分 | 95 |
| 97 | AppearancePatent 历史查询组装抽取 | 05 拆分 | 无 |
| 98 | AppearancePatent 全量回归 | 05 拆分 | 95-97 |
| 99 | ShopDataCrawl 行解析抽取 | 05 拆分 | 83,85 |
| 100 | ShopDataCrawl Sheet 构造抽取 | 05 拆分 | 88 |
| 101 | ShopDataCrawl 门面改委托(签名不变) | 05 拆分 | 99,100 |
| 102 | ShopDataCrawl 快照对比测试 | 05 拆分 | 101 |
| 103 | ShopDataCrawl 历史查询组装抽取 | 05 拆分 | 无 |
| 104 | ShopDataCrawl 全量回归 | 05 拆分 | 101-103 |
| 105 | similarasin 历史列表 IN 查询批量加载 | 06 批量加载 | 无 |
| 106 | appearancepatent 历史列表批量加载 | 06 批量加载 | 105 |
| 107 | 结果列表关联 Job 批量加载(findAssembleJobs 覆盖审计) | 06 批量加载 | 无 |
| 108 | dashboard 聚合查询(COUNT/GROUP BY 一次出) | 06 批量加载 | 无 |
| 109 | progress/light 轻量接口(similarasin 首个) | 06 批量加载 | 无 |
| 110 | progress/light 字段白名单(不含明细) | 06 批量加载 | 109 |
| 111 | progress/light 空/超长 taskIds 行为 | 06 批量加载 | 109 |
| 112 | progress/light 终态任务返回终态状态 | 06 批量加载 | 109 |
| 113 | 其余模块 progress/light 接入(批量) | 06 批量加载 | 109-112 |
| 114 | 批量加载等价快照测试(改造前后字段一致) | 06 批量加载 | 105-108 |
| 115 | 高频查询 EXPLAIN 索引审计(产出迁移清单) | 06 批量加载 | 无 |
| 116 | 索引迁移 V{N+1}(EXPLAIN 验证后追加) | 06 批量加载 | 115 |
| 117 | progress/light user_id 权限过滤 | 06 批量加载 | 109 |
| 118 | 前端 getModuleProgressLight 适配(调用轻量端点) | 06 批量加载 | 109,44 |
| 119 | dashboard/history/progress 前端分离调用测试 | 06 批量加载 | 无 |
| 120 | 大页数据(500 任务)性能回归 | 06 批量加载 | 105-108 |
| 121 | N+1 扫描(逐条 selectById 循环审计) | 06 批量加载 | 无 |
| 122 | 扫描确认的 N+1 批量化修复 | 06 批量加载 | 121 |
| 123 | 06 全量回归 | 06 批量加载 | 105-122 |
| 124 | @Transactional 方法审计清单(每模块) | 07 事务 | 无 |
| 125 | similarasin 纯计算移出事务 | 07 事务 | 124 |
| 126 | similarasin DTO 组装移出写事务 | 07 事务 | 124 |
| 127 | similarasin 临时文件清理挂 afterCommit | 07 事务 | 124 |
| 128 | appearancepatent 事务收缩 | 07 事务 | 124 |
| 129 | shopdatacrawl 事务收缩 | 07 事务 | 124 |
| 130 | publish 事务收缩 | 07 事务 | 124 |
| 131 | collectdata 事务收缩 | 07 事务 | 124 |
| 132 | /result 成功确认时机不变测试(200+success 在落库后) | 07 事务 | 125-131 |
| 133 | 回滚语义不变测试(落库失败回滚) | 07 事务 | 125-131 |
| 134 | done=true 封口时机不变测试 | 07 事务 | 125-131 |
| 135 | 任务状态成功时机不变测试 | 07 事务 | 125-131 |
| 136 | 事务外清理异常不阻断(日志+指标) | 07 事务 | 127 |
| 137 | 重复提交幂等测试(同 submissionId) | 07 事务 | 132-135 |
| 138 | 事务时长性能对比基准 | 07 事务 | 125-131 |
| 139 | 07 全量回归 | 07 事务 | 132-138 |
| 140 | 13 模块 file 字段契约快照测试(齐全+旧字段仍在) | 08 结果阶段 | 无 |
| 141 | similarasin file 进度合成逻辑单测(Coze/Python/snapshot 三路径) | 08 结果阶段 | 无 |
| 142 | fileReady/fileStatus 语义测试(无 job 时 SUCCESS 兜底) | 08 结果阶段 | 140 |
| 143 | publish 文件级 file 状态测试 | 08 结果阶段 | 140 |
| 144 | 前端 live progress 合并测试补强(history 缺失保留) | 08 结果阶段 | 无 |
| 145 | 前端可下载判定测试(fileReady/fileStatus 终态) | 08 结果阶段 | 无 |
| 146 | collectdata 自洽行为测试(success+downloadUrl 判定) | 08 结果阶段 | 140 |
| 147 | downloadUrl 永不过期验证(generateFreshDownloadUrl 公开直链) | 08 结果阶段 | 无 |
| 148 | 临时目录配置盘点(Transient/Storage Properties 现状) | 09 临时文件 | 无 |
| 149 | 创建/访问时间记录审计与补缺 | 09 临时文件 | 148 |
| 150 | 引用检查(清理前查 task_file_job/file_result) | 09 临时文件 | 148 |
| 151 | 路径安全校验(规范化 + startsWith 根目录) | 09 临时文件 | 148 |
| 152 | 清理失败吞异常记指标(不阻断主流程) | 09 临时文件 | 150,151 |
| 153 | fileKey 兜底查找(进程重启后) | 09 临时文件 | 148 |
| 154 | 磁盘容量告警(仅日志/指标输出) | 09 临时文件 | 152 |
| 155 | 孤立文件巡检报表(只读) | 09 临时文件 | 150 |
| 156 | 孤立 Job 巡检报表(只读) | 09 临时文件 | 无 |
| 157 | 任务存在结果缺失巡检 | 09 临时文件 | 无 |
| 158 | 结果存在文件缺失巡检 | 09 临时文件 | 无 |
| 159 | 已完成任务活跃 Job 巡检 | 09 临时文件 | 无 |
| 160 | 超保留期仍被引用巡检 | 09 临时文件 | 150 |
| 161 | 巡检任务开关(默认 disabled) | 09 临时文件 | 155-160 |
| 162 | 路径穿越测试(../ 输入被拒) | 09 临时文件 | 151 |
| 163 | 引用中文件不清测试 | 09 临时文件 | 150 |
| 164 | 清理失败不阻断测试 | 09 临时文件 | 152 |
| 165 | 巡检只读测试(运行零删除) | 09 临时文件 | 155-161 |
| 166 | 各客户端契约表盘点(超时/重试/幂等现状) | 10 HTTP 客户端 | 无 |
| 167 | aiimage.http-client.* 配置命名空间 | 10 HTTP 客户端 | 166 |
| 168 | Coze 客户端超时/重试配置接入 | 10 HTTP 客户端 | 167 |
| 169 | 品牌检查客户端配置接入 | 10 HTTP 客户端 | 167 |
| 170 | 紫鸟客户端配置接入 | 10 HTTP 客户端 | 167 |
| 171 | 图片下载客户端配置接入 | 10 HTTP 客户端 | 167 |
| 172 | 幂等重试守卫(非幂等不自动重试) | 10 HTTP 客户端 | 167 |
| 173 | 超时生效测试(mock 慢端点) | 10 HTTP 客户端 | 168-171 |
| 174 | 连接复用测试(连续请求复用底层连接) | 10 HTTP 客户端 | 168-171 |
| 175 | Python 回调超时不变确认(只读测试) | 10 HTTP 客户端 | 无 |
| 176 | 重试计数与日志字段 | 10 HTTP 客户端 | 172 |
| 177 | 10 全量回归 | 10 HTTP 客户端 | 168-176 |
| 178 | 日志字段规范落地(taskId/moduleType/stage 统一) | 11 可观测性 | 无 |
| 179 | 禁止记录清单审计(Token/Cookie/body 不落日志) | 11 可观测性 | 178 |
| 180 | Worker 日志字段对齐(04 改造后) | 11 可观测性 | 73 |
| 181 | task.created/running 指标埋点 | 11 可观测性 | 无 |
| 182 | task.success/failed/cancelled 指标埋点 | 11 可观测性 | 181 |
| 183 | task.duration 指标埋点 | 11 可观测性 | 182 |
| 184 | task.heartbeat.age 指标埋点 | 11 可观测性 | 无 |
| 185 | file-job.* 指标埋点(pending/running/success/failed/duration/retry) | 11 可观测性 | 73 |
| 186 | 上传耗时/大小指标埋点 | 11 可观测性 | 无 |
| 187 | 临时磁盘指标埋点 | 11 可观测性 | 154 |
| 188 | 指标标签规范(moduleType/instanceId) | 11 可观测性 | 181-187 |
| 189 | 指标命名一致性测试(名称/标签断言) | 11 可观测性 | 188 |
| 190 | 日志脱敏测试(敏感字段不落日志) | 11 可观测性 | 179 |
| 191 | 双实例指标区分回归(instanceId 标签) | 11 可观测性 | 188-190 |
| 192 | 迁移规范模板(目的/影响/锁表/验证/回滚/窗口) | 12 Flyway | 无 |
| 193 | 历史迁移盘点(V87+ 现状核对,只追加不改) | 12 Flyway | 无 |
| 194 | orphan Job 巡检 SQL | 12 Flyway | 无 |
| 195 | orphan payload 巡检 SQL | 12 Flyway | 无 |
| 196 | 任务存在结果缺失巡检 SQL | 12 Flyway | 无 |
| 197 | 结果存在文件缺失巡检 SQL | 12 Flyway | 无 |
| 198 | 已完成任务活跃 Job 巡检 SQL | 12 Flyway | 无 |
| 199 | 超保留期引用巡检 SQL | 12 Flyway | 无 |
| 200 | 巡检报表任务落地(默认关闭) | 12 Flyway | 194-199 |
| 201 | 迁移演练(副本库 migrate + 验证 SQL) | 12 Flyway | 192 |
| 202 | Python-contract 夹具准备(录制真实请求脱敏) | 13 契约 | 无 |
| 203 | /result 幂等契约测试(同 submissionId 重复) | 13 契约 | 202 |
| 204 | /items 分页语义契约测试 | 13 契约 | 202 |
| 205 | parsed-payload 契约测试 | 13 契约 | 202 |
| 206 | heartbeat 旧字段契约测试 | 13 契约 | 202 |
| 207 | done=true 最后一批契约测试 | 13 契约 | 203 |
| 208 | JavaApiResponse 包装契约测试(前端) | 13 契约 | 无 |
| 209 | 字段兼容 schema 覆盖(user_id/task_ids/taskId/resultId/fileKey) | 13 契约 | 208 |
| 210 | ArchUnit 依赖方向规则(Controller→Service→Mapper) | 13 契约 | 无 |
| 211 | ArchUnit Controller 不访问 Mapper 规则 | 13 契约 | 210 |
| 212 | ArchUnit task 模块不依赖业务模块(SPI 检查) | 13 契约 | 210 |
| 213 | 前端共享层导出白名单(页面禁止直连 http) | 13 契约 | 无 |
| 214 | progress/batch 轻量响应契约 | 13 契约 | 109 |
| 215 | 下载 URL 格式契约(downloadUrl 公开直链) | 13 契约 | 147 |
| 216 | CI 接入测试阶段(.gitea workflow 追加) | 13 契约 | 210-215 |
| 217 | 快照对比工具(Service 拆分前后响应一致) | 13 契约 | 90 |
| 218 | 结果文件格式契约(文件名/Sheet/列/ZIP 结构) | 13 契约 | 无 |
| 219 | 13 全量契约回归 | 13 契约 | 202-218 |
**总任务数:219**
(原 222 规划在写入时合并了 3 个冗余项:40→41 合并降频测试、46→47 合并 baseline、112→113 合并终态返回,编号已重排为连续 1-219,与上表严格一致。)