49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
234 lines
17 KiB
Markdown
234 lines
17 KiB
Markdown
# 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,与上表严格一致。)
|