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

17 KiB
Raw Blame History

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,与上表严格一致。)