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