docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
# 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,与上表严格一致。)
|
||||
@@ -0,0 +1,429 @@
|
||||
# 01-plan — frontend-vue Java API 适配层
|
||||
|
||||
> 对应 `docs/specs/01-frontend-api-adapter.md`。技术栈:TypeScript + Vue3 + Vitest(`frontend-vue/`)。
|
||||
> 测试命令:`cd crawler-plugin/frontend-vue && npx vitest run <file>`;类型检查:`npx vue-tsc --noEmit`。
|
||||
|
||||
## 任务 1:API_ENDPOINTS 路径常量表
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
新建 `src/shared/api/endpoints.ts`,导出按模块分组的路径常量表 `API_ENDPOINTS`(17 个页面模块:split/dedupe/convert/publish/query-asin/similar-asin/appearance-patent/delete-brand/price-track/shop-match/product-risk/shop-data-crawl/withdraw/patrol-delete/collect-data/image-video/brand/permission/digital-human)。每个模块含 parse/activate/progress/history/result/download 等端点常量。路径值与现 java-modules.ts 内联 URL 完全一致(不含 /newApi/api 前缀,前缀由 buildJavaUrl 加)。
|
||||
|
||||
### 测试用例(≥8,先写 RED)
|
||||
1. test_endpoints_all_modules_present — 17 模块键齐全
|
||||
2. test_endpoint_path_format — 每个端点以 /api/ 开头
|
||||
3. test_no_newapi_prefix_in_endpoint — 不含 /newApi/api 前缀
|
||||
4. test_progress_batch_paths_match_controllers — progress 端点与 Java controller 路径一致(快照)
|
||||
5. test_download_paths_match — download 端点模式
|
||||
6. test_endpoints_frozen_snapshot — 常量表 JSON 快照(防漂移)
|
||||
7. test_endpoint_values_no_trailing_slash — 无尾斜杠
|
||||
8. test_endpoint_keys_convention — 键名 snake_case 或小驼峰一致性
|
||||
|
||||
### TDD 流程
|
||||
1. 写上述全部测试 → `npx vitest run src/shared/api/__tests__/endpoints.test.ts` 确认 RED(文件不存在)
|
||||
2. 实现 endpoints.ts → 确认 GREEN
|
||||
3. `npx vue-tsc --noEmit` 通过
|
||||
|
||||
### 验证方法
|
||||
`npx vitest run`(新建测试全绿)+ `npx vue-tsc --noEmit`。
|
||||
|
||||
## 任务 2:buildJavaUrl() 统一 URL 构造
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`buildJavaUrl(module, endpoint, query?)`:`/newApi` + `/api` 前缀 + endpoint + 可选 query 序列化;对空 query 不追加 `?`。与现有 `JAVA_API_PREFIX` 常量保持一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_build_url_prefixed — 输出以 /newApi/api 开头
|
||||
2. test_build_url_with_query — query 参数正确编码
|
||||
3. test_build_url_no_query — 无 query 不加 ?
|
||||
4. test_build_url_query_encoding — 特殊字符编码(空格/中文/&)
|
||||
5. test_build_url_empty_query_object — 空对象不加 query
|
||||
6. test_build_url_trailing_slash_endpoint — endpoint 尾斜杠规范化
|
||||
7. test_build_url_undefined_query — undefined 安全
|
||||
8. test_build_url_join_no_duplicate_slash — 前缀与端点之间无重复斜杠
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上:先 RED,实现 GREEN,`vue-tsc` 通过。
|
||||
|
||||
## 任务 3:callJava() 统一响应解包
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:2 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`callJava<T>(config): Promise<T>`:发起请求;响应 data 为 `JavaApiResponse<T>`(success/message/data)时解包返回 data;为 `LegacyApiSuccess`(success/msg/data)时兼容解包;非包装结构直通;success=false 抛错(message 优先);不改变 http.ts 现有导出。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_call_java_success_unwraps — JavaApiResponse 解包出 data
|
||||
2. test_call_java_legacy_msg_unwraps — LegacyApiSuccess(msg)解包
|
||||
3. test_call_java_success_false_throws — success=false 抛错
|
||||
4. test_call_java_message_precedence — message 优先于 msg 于 error
|
||||
5. test_call_java_non_wrapped_passthrough — 非包装对象直通
|
||||
6. test_call_java_null_data — success 且 data=null 返回 null
|
||||
7. test_call_java_network_error — 网络错误抛出 Error
|
||||
8. test_call_java_http_error_status — HTTP 错误状态提取 message
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 4:extractErrorMessage 导出与三字段覆盖
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
http.ts 的 `extractErrorMessage` 提升为命名导出(保持内部逻辑);错误对象覆盖 `error`/`message`/`msg` 三字段;字符串响应体回退;无字段回退 axios message / 通用文案。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_extract_error_field — error 字段优先
|
||||
2. test_extract_message_field — message 字段
|
||||
3. test_extract_msg_field — msg 字段
|
||||
4. test_extract_error_precedence — error > message > msg
|
||||
5. test_extract_string_body — 字符串响应体
|
||||
6. test_extract_fallback_message — 无字段回退
|
||||
7. test_extract_axios_non_error — 非 AxiosError
|
||||
8. test_extract_blank_values_skipped — 空字符串跳过
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 5:normalizeStatus() 状态归一
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`normalizeStatus(raw: string|null|undefined): string`:小写转大写(success→SUCCESS);带空格/连字符清理(in-progress→IN_PROGRESS);null/undefined/空串返回原样或 ''(不抛);未知值透传不改。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_normalize_lower_to_upper — success→SUCCESS
|
||||
2. test_normalize_mixed_case — rUnNiNg→RUNNING
|
||||
3. test_normalize_with_hyphen — in-progress→IN_PROGRESS
|
||||
4. test_normalize_null — null 安全
|
||||
5. test_normalize_undefined — undefined 安全
|
||||
6. test_normalize_empty_string — 空串返回空
|
||||
7. test_normalize_unknown_passthrough — 未知值(SYNCING)原样
|
||||
8. test_normalize_whitespace_padded — 首尾空白清理
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 6:isTerminalStatus() 终态判定
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:5 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`isTerminalStatus(status, extras?)`:默认 SUCCESS/FAILED 为终态;可扩展(CANCELLED);先经 normalizeStatus;空值非终态。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_terminal_success — SUCCESS true
|
||||
2. test_terminal_failed — FAILED true
|
||||
3. test_terminal_lowercase — success true(归一后)
|
||||
4. test_terminal_pending_false — PENDING false
|
||||
5. test_terminal_null_false — null false
|
||||
6. test_terminal_cancelled_default_false — CANCELLED 默认 false
|
||||
7. test_terminal_cancelled_extended_true — 传 extras 后 true
|
||||
8. test_terminal_unknown_false — 未知状态 false
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 7:buildDownloadUrl() 统一下载 URL
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:2 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`buildDownloadUrl(path, userId?)`:下载端点拼 user_id 附加规则(有 userId 时追加);已有 user_id 参数时不重复;无 userId 不追加;支持 freshDownloadUrl 优先的辅助 `resolveDownloadUrl(item)`(fresh 优先,缺失回退 downloadUrl)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_download_url_user_id — 追加 user_id
|
||||
2. test_download_url_no_user_id — 无 userId 不追加
|
||||
3. test_download_url_existing_user_id — 已含不重复
|
||||
4. test_resolve_download_fresh_priority — freshDownloadUrl 优先
|
||||
5. test_resolve_download_fallback — 缺失回退 downloadUrl
|
||||
6. test_resolve_download_both_blank — 都空返回空
|
||||
7. test_download_url_query_merge — 已有 query 合并
|
||||
8. test_resolve_download_null_safe — null 安全
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 8:callJava 透传 AbortController
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
callJava 支持 `{ signal }`:axios 透传;signal 已中止时请求立即失败(AbortError);页面卸载可取消 in-flight。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_signal_abort_before_send — 发送前中止立即拒绝
|
||||
2. test_signal_abort_mid_request — 进行中中止拒绝
|
||||
3. test_signal_passthrough — signal 传到 axios 配置
|
||||
4. test_signal_abort_error_message — 错误消息含 AbortError 特征
|
||||
5. test_signal_not_provided — 无 signal 正常
|
||||
6. test_abort_after_resolve — 完成后 abort 无副作用
|
||||
7. test_abort_rejects_promise — 中止拒绝 Promise
|
||||
8. test_signal_multiple_calls_independent — 多次调用互不影响
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 9:进度类请求默认超时
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
进度类 API 函数(get*TaskProgressBatch)默认 10s 超时(现有 30s);可通过配置覆盖;非进度请求保持 30s。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_progress_timeout_default — 进度请求 10s
|
||||
2. test_progress_timeout_override — 显式覆盖生效
|
||||
3. test_non_progress_timeout_30s — 非进度 30s
|
||||
4. test_timeout_config_name — 配置键存在且为正数
|
||||
5. test_progress_timeout_minimum — 非法配置钳制
|
||||
6. test_override_via_options — 函数级 options 覆盖
|
||||
7. test_timeout_zero — 0 钳制为正数
|
||||
8. test_default_config_freeze — 默认值快照
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 10:types/task.ts 共享类型
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
新建 `src/shared/api/types/task.ts`:`TaskStatus`(联合类型)、`ResultFilePhase`(fileReady/fileStatus/fileProgress*/freshDownloadUrl 可选)、`PageResult<T>`、`TaskProgressBatchVo`。纯类型,测试以类型断言为主(可降为 5 用例)。
|
||||
|
||||
### 测试用例(≥5)
|
||||
1. test_type_task_status_assignable — SUCCESS 等可赋值
|
||||
2. test_type_result_file_phase_all_optional — 字段全部可选
|
||||
3. test_type_page_result_shape — 分页字段结构
|
||||
4. test_type_progress_batch_shape — 批量进度结构
|
||||
5. test_type_compat_compile — vue-tsc 全量通过
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
先写类型 + 编译期断言(`@ts-expect-error` 负例),RED 后实现。
|
||||
|
||||
## 任务 11:拆分 dedupe 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
将 java-modules.ts 中 dedupe 相关函数(runDedupe/getDedupeHistory/deleteDedupeHistory/getDedupeResultDownloadUrl)及类型移到 `types/modules/dedupe.ts`;内部改调 callJava+buildJavaUrl;函数签名、参数、返回语义一字不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dedupe_run_url — runDedupe 请求 URL 正确
|
||||
2. test_dedupe_run_method_payload — POST + 请求体
|
||||
3. test_dedupe_history_url — history URL/method
|
||||
4. test_dedupe_delete_history — delete URL/method
|
||||
5. test_dedupe_download_url — download URL + user_id
|
||||
6. test_dedupe_signature_unchanged — 参数顺序与类型快照
|
||||
7. test_dedupe_export_compat — 旧路径 import 可用
|
||||
8. test_dedupe_unwrap — 返回解包后的 data
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上(mock adapter 断言 URL)。
|
||||
|
||||
## 任务 12:拆分 split 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
与 11 同构:runSplit/getSplitHistory/deleteSplitHistory/getSplitResultDownloadUrl + SplitRunRequest/SplitRunVo/SplitHistoryVo/SplitArchiveEntry。
|
||||
|
||||
### 测试用例(≥8)
|
||||
split 对应 8 例:run URL/method/payload、history、delete、download+user_id、签名快照、旧 import 兼容、解包、异常回传。
|
||||
|
||||
## 任务 13:拆分 convert 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
与 11 同构:getExcelInfo/runConvert/getConvertHistory/deleteConvertHistory/getConvertResultDownloadUrl/getConvertTemplates/importConvertTemplate/setDefaultConvertTemplate/deleteConvertTemplate + 模板相关类型。
|
||||
|
||||
### 测试用例(≥8)
|
||||
convert 对应 8 例:getExcelInfo URL、runConvert 解析、history、download、模板列表/导入/默认/删除 URL、签名快照。
|
||||
|
||||
## 任务 14:拆分 publish 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
publish:parsePublish/activatePublishTask/activatePublishFile/getPublishItemsPage/getPublishTaskProgressBatch/submitPublishTaskResult/getPublishDashboard/getPublishHistory/deletePublishTask。
|
||||
|
||||
### 测试用例(≥8)
|
||||
publish 8 例:parse URL、activate、itemsPage 分页参数、progressBatch(含超时断言)、submitResult 请求体、dashboard、delete、签名快照。
|
||||
|
||||
## 任务 15:拆分 similar-asin 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
similar-asin:parseSimilarAsin/getSimilarAsinDashboard/getSimilarAsinHistory/getSimilarAsinTaskProgressBatch/activateSimilarAsinTask/deleteSimilarAsinTask/deleteSimilarAsinHistory/getSimilarAsinResultDownloadUrl。
|
||||
|
||||
### 测试用例(≥8)
|
||||
similar-asin 8 例:parse URL/payload、progressBatch 10s 超时、activate user_id、history、dashboard、delete task/history、download。
|
||||
|
||||
## 任务 16:拆分 appearance-patent 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
appearance-patent:parseAppearancePatent/getAppearancePatentParsedPayload/getAppearancePatentQueuePayload/getAppearancePatentDashboard/getAppearancePatentHistory/getAppearancePatentTaskProgressBatch/activateAppearancePatentTask/deleteAppearancePatentTask/deleteAppearancePatentHistory/getAppearancePatentResultDownloadUrl。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:parse、parsedPayload、queuePayload、progressBatch、activate、dashboard、history、delete/download。
|
||||
|
||||
## 任务 17:拆分 delete-brand 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
delete-brand:runDeleteBrand/getDeleteBrandHistory/deleteDeleteBrandHistory/getDeleteBrandTaskDetail/getDeleteBrandTaskDetails/getDeleteBrandTaskDownloadUrl/getDeleteBrandResultDownloadUrl/submitDeleteBrandResult。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:run URL、taskDetail/taskDetails、taskDownloadUrl、resultDownloadUrl、submitResult 请求体、delete、history、签名快照。
|
||||
|
||||
## 任务 18:拆分 price-track 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
price-track:listPriceTrackCandidates/add/deleteCandidate/getCountryPreference/putPreference/matchPriceTrackShops/createPriceTrackTask/getPriceTrackTasksBatch/getPriceTrackTaskProgressBatch/deletePriceTrackTask/loopRun 系列/checkTaskSkipPriceAsin/markPriceTrackDispatchFailed。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:create URL/payload、progressBatch、loopRun 创建/派发、skipAsin 检查、candidates、preference、download、签名快照。
|
||||
|
||||
## 任务 19:拆分 shop-match / product-risk 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
shop-match + product-risk:matchProductRiskShops/listProductRiskCandidates/add/deleteCandidate/getCountryPreference/putPreference/getShopMatchTaskProgressBatch/getProductRiskTaskProgressBatch/getProductRiskDashboard/getProductRiskHistory。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:matchShops URL、candidates CRUD、preference、两个 progressBatch、dashboard、history、签名快照。
|
||||
|
||||
## 任务 20:拆分 shop-data-crawl / query-asin 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
shop-data-crawl + query-asin:listShopDataCrawlCandidates/matchShopDataCrawlShops/createShopDataCrawlTask/getShopDataCrawlDashboard/getShopDataCrawlHistory/getShopDataCrawlTaskProgressBatch/deleteShopDataCrawlTask/deleteShopDataCrawlHistory/getShopDataCrawlResultDownloadUrl + query-asin 对应函数。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:create URL、progressBatch、candidates、dashboard/history、query-asin 组、download、签名快照、旧 import。
|
||||
|
||||
## 任务 21:拆分 withdraw / patrol-delete 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
withdraw + patrol-delete:listWithdrawCandidates/matchWithdrawShops/createWithdrawTask/submitWithdrawTaskResult/getWithdrawTaskProgressBatch/getWithdrawResultDownloadUrl + patrol-delete 对应。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:withdraw create、submitResult、progress、patrol-delete 组、download、签名快照、旧 import、异常回传。
|
||||
|
||||
## 任务 22:拆分 collect-data 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
collect-data:parseCollectData/activateCollectDataTask/getCollectDataItemsPage/getCollectDataDashboard/getCollectDataHistory/getCollectDataTaskProgressBatch/deleteCollectDataTask/deleteCollectDataHistory/failCollectDataTask/getCollectDataCountryPreference/putCollectDataCountryPreference。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:parse、itemsPage 分页参数、progressBatch、fail 请求体、preference、dashboard、delete、签名快照。
|
||||
|
||||
## 任务 23:拆分 image-video / brand / permission / digital-human 模块 API
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
|
||||
|
||||
image-video(secret/workflow/voice/asyncTask 系列)+ brand(BrandTaskListResponse 相关)+ permission + digital-human 独立文件已有,移动对齐。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:image-video workflow 创建、result 查询、voice 列表/删除、brand 列表、permission、digital-human、签名快照、旧 import。
|
||||
|
||||
## 任务 24:java-modules.ts 改 re-export 聚合
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:11-23 **预估**:8-15 分钟
|
||||
|
||||
java-modules.ts 只保留 re-export:`export * from './types/modules/dedupe'` 等;删光被移动的函数体;任何旧 import 路径继续可用(类型与运行时双兼容)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_reexport_all_symbols — 全部导出符号可从 java-modules 获取
|
||||
2. test_reexport_type_compiles — 类型 import 可用
|
||||
3. test_reexport_no_duplicate — 无重复导出
|
||||
4. test_reexport_build_passes — vue-tsc 全量通过
|
||||
5. test_reexport_import_compat — 各页面旧 import 快照编译
|
||||
6. test_reexport_no_dead_body — 原函数体不存在(防残留)
|
||||
7. test_reexport_runtime_symbols — 运行时函数可调用
|
||||
8. test_reexport_vitest_full — 全量测试绿
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
先写 re-export 后的测试断言(指向符号存在)→ 尚未 re-export 时 RED → 改文件 GREEN → `npm run build`(vue-tsc + vite build)通过。
|
||||
|
||||
## 任务 25:ResultFilePhase 新字段兼容默认值
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:10 **预估**:8-15 分钟
|
||||
|
||||
`applyFilePhaseDefaults(item)`:fileReady/fileStatus/fileProgress* 缺省补默认(false/'PENDING'/0/0/0);旧 Java 版本响应(无新字段)时页面行为一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_defaults_filled — 缺省字段补齐
|
||||
2. test_existing_values_kept — 已有值不覆盖
|
||||
3. test_file_ready_true_preserved — true 保留
|
||||
4. test_partial_input — 部分字段缺失补齐
|
||||
5. test_null_input_safe — null 安全
|
||||
6. test_defaults_idempotent — 二次调用幂等
|
||||
7. test_status_success_maps_ready — fileStatus=SUCCESS 且 fileReady 缺失 → ready true
|
||||
8. test_unknown_status_untouched — 未知 status 不动
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 26:模块 API 快照契约测试基建
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
|
||||
|
||||
测试基建:vitest + axios mock adapter(或拦截 http.request),对每个模块 API 函数断言(url, method, params, data)快照;集中式 `assertApiCall()` helper。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_snapshot_helper_url — helper 断言 URL
|
||||
2. test_snapshot_helper_method — 断言 method
|
||||
3. test_snapshot_helper_params — 断言 query
|
||||
4. test_snapshot_helper_body — 断言请求体
|
||||
5. test_snapshot_all_modules_covered — 全部已拆模块注册
|
||||
6. test_snapshot_fail_message — 失败信息含 URL 上下文
|
||||
7. test_snapshot_allowlist — 白名单外字段报错
|
||||
8. test_snapshot_regression_guard — 快照变更即失败
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 27:api-field-compat 高频响应 schema
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:26 **预估**:8-15 分钟
|
||||
|
||||
为 task/result 核心响应注册 schema(taskId/resultId/status/fileStatus/fileReady/downloadUrl 等),接入 createApiFieldCompatChecker 在契约测试与联调前跑检查。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_schema_task_required_fields — 必填字段声明
|
||||
2. test_schema_result_required_fields — 结果字段
|
||||
3. test_checker_passes_valid — 合法对象通过
|
||||
4. test_checker_missing_required — 缺必填报 missing
|
||||
5. test_checker_wrong_type — 类型不符报 type
|
||||
6. test_checker_batch — 批量检查
|
||||
7. test_schema_registered_modules — 各模块 schema 注册齐全
|
||||
8. test_schema_versioned — schema 版本标记
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 28:死代码清理
|
||||
|
||||
**所属模块**:01 适配层 **依赖**:24 **预估**:8-15 分钟
|
||||
|
||||
拆分后 grep 确认 java-modules.ts 无残留函数体、无未引用导出;删除确认死代码;`npm run build` + 全量测试验证。
|
||||
|
||||
### 测试用例(≥8,测试为验证型)
|
||||
1. test_no_unexported_duplicates — 无重复导出
|
||||
2. test_build_typecheck — vue-tsc 通过
|
||||
3. test_full_vitest_green — 全量测试绿
|
||||
4. test_no_console_debug_left — 无调试日志残留
|
||||
5. test_no_unused_import — 无未用 import(lint)
|
||||
6. test_entry_points_compile — 17 个入口编译
|
||||
7. test_bundle_build — vite build 产出
|
||||
8. test_git_diff_scope — 变更仅限 api 目录
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
`npm run build` + `npx vitest run` 全绿。
|
||||
@@ -0,0 +1,399 @@
|
||||
# 02-plan — 任务轮询审计补强
|
||||
|
||||
> 对应 `docs/specs/02-task-polling-audit.md`。技术栈:TypeScript + Vitest(`frontend-vue/`)。
|
||||
> 核心决策:不重写,只补强;`getTaskPollBackoffMs` 保持签名向后兼容。
|
||||
|
||||
## 任务 29:退避配置项(MaxMs/Factor)
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
task-progress-config.ts 新增 `getTaskPollBackoffMaxMs()`(默认 10000)与 `getTaskPollBackoffFactor()`(默认 2);默认值可通过 window 配置/测试注入覆盖。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_backoff_max_default — 默认 10000
|
||||
2. test_backoff_factor_default — 默认 2
|
||||
3. test_backoff_max_override — 可覆盖
|
||||
4. test_backoff_max_positive — 非正钳制
|
||||
5. test_backoff_factor_min_one — factor <1 钳制为 1
|
||||
6. test_backoff_config_isolated — 配置隔离(不串到其他用例)
|
||||
7. test_backoff_max_freeze — 默认值快照
|
||||
8. test_backoff_factor_freeze — factor 快照
|
||||
|
||||
### TDD 流程
|
||||
1. 写测试 → `npx vitest run src/shared/__tests__/task-progress-config.test.ts` RED
|
||||
2. 实现 → GREEN
|
||||
3. `vue-tsc --noEmit` 通过
|
||||
|
||||
## 任务 30:getTaskPollBackoffMs 递增序列
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:29 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`getTaskPollBackoffMs(attempt)`:500 * factor^attempt 递增;attempt=0 返回 500(与现状一致);上限 maxMs;现签名向后兼容(attempt 省略视为 0)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_backoff_attempt0_500 — attempt0=500
|
||||
2. test_backoff_attempt1_1000 — attempt1=1000
|
||||
3. test_backoff_attempt2_2000 — attempt2=2000
|
||||
4. test_backoff_sequence_monotonic — 序列递增
|
||||
5. test_backoff_capped_at_max — 封顶 10000
|
||||
6. test_backoff_no_attempt_default — 省略参数=500
|
||||
7. test_backoff_negative_attempt_zero — 负 attempt 当 0
|
||||
8. test_backoff_custom_factor — 自定义 factor 生效
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 31:连续失败计数
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:30 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
轮询循环维护失败计数:refreshOnce 成功(收到响应)归零;连续失败递增;提供测试可观测出口(onError 带 attempt)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_failure_count_increments — 连续失败递增
|
||||
2. test_success_resets_count — 成功后归零
|
||||
3. test_any_response_resets — 4xx 也算收到响应归零
|
||||
4. test_on_error_receives_attempt — onError 带 attempt
|
||||
5. test_initial_count_zero — 初始 0
|
||||
6. test_interleaved_fail_success — 失败成功交错计数正确
|
||||
7. test_count_bounded — 计数有界(不溢出)
|
||||
8. test_dispose_clears_count — dispose 后不再上报
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 32:退避封顶
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:30,31 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
失败计数继续增长但退避间隔停在 maxMs;达到封顶后不再增长(间隔恒等于 maxMs)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_backoff_cap_reached — 达到封顶
|
||||
2. test_backoff_stays_capped — 之后保持 maxMs
|
||||
3. test_cap_with_low_max — 低 maxMs 提前封顶
|
||||
4. test_cap_with_high_factor — 高 factor 快速封顶
|
||||
5. test_cap_resets_after_success — 成功后重新从 500 起
|
||||
6. test_cap_attempt_boundary — 恰好等于封顶那一档
|
||||
7. test_cap_integration_loop — 集成:循环内退避生效
|
||||
8. test_cap_config_negative — 非法 maxMs 钳制
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 33:网络错误走退避且不触发终态
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:31 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
网络错误(fetch 拒绝/超时)不触发 onTerminal、不修改 taskStatuses、进入退避;恢复后继续轮询。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_network_error_no_terminal — 不触发 onTerminal
|
||||
2. test_network_error_no_status_change — 状态不变
|
||||
3. test_network_error_backoff_scheduled — 进入退避
|
||||
4. test_network_error_on_error_called — onError 调用
|
||||
5. test_network_recovery — 恢复后轮询继续
|
||||
6. test_network_error_repeated — 多次失败仍退避
|
||||
7. test_network_error_keeps_task — 任务不丢失
|
||||
8. test_network_error_then_success — 失败后成功收到响应
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
vitest fake timers + mock fetch 拒绝。
|
||||
|
||||
## 任务 34:HTTP 4xx/5xx 分类
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:31 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
4xx/5xx 记 onError 并退避;5xx 且无法解析明细时不误判 FAILED;不触发终态。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_4xx_on_error — 4xx 记 onError
|
||||
2. test_5xx_on_error — 5xx 记 onError
|
||||
3. test_5xx_no_terminal_failed — 不误判 FAILED
|
||||
4. test_5xx_backoff — 5xx 退避
|
||||
5. test_5xx_unknown_status_untouched — 未知状态不动
|
||||
6. test_4xx_recovery — 4xx 后恢复
|
||||
7. test_status_500_partial_items — 部分 items 仍处理
|
||||
8. test_5xx_no_status_wipe — 不清空已有状态
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 35:未知状态不判终态固化
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
PENDING/SYNCING/空串/undefined 状态:isTerminal=false,不触发终态回调,轮询继续。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_pending_not_terminal — PENDING false
|
||||
2. test_syncing_not_terminal — SYNCING false
|
||||
3. test_empty_status_not_terminal — 空串 false
|
||||
4. test_undefined_status_not_terminal — undefined false
|
||||
5. test_unknown_status_continues_polling — 轮询继续
|
||||
6. test_mixed_terminal_unknown — 同批终态+未知分开处理
|
||||
7. test_custom_is_terminal — 自定义判定生效
|
||||
8. test_lowercase_unknown — 小写未知值也不误判
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
扩展 polling-state-machine.test.ts。
|
||||
|
||||
## 任务 36:终态任务仅一次 onTerminal
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
coordinator.markTerminal 语义:终态任务只触发一次 onTerminal;重复收到同任务终态不再回调;从轮询集合移除。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_terminal_called_once — 只一次
|
||||
2. test_terminal_removed_from_poll — 移除
|
||||
3. test_terminal_repeat_response — 重复响应不回调
|
||||
4. test_terminal_after_readd — 重新 add 后可再触发
|
||||
5. test_terminal_multiple_tasks — 多任务各自一次
|
||||
6. test_terminal_coordinator_order — markTerminal 先于 remove
|
||||
7. test_terminal_storage_cleared — localStorage 清空
|
||||
8. test_terminal_dispose_no_call — dispose 后不回调
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 37:onTerminal 抛错语义测试
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
onTerminal 抛错:任务已从轮询集合移除(语义固化);错误不中断其他终态回调;页面可自行重新 add() 恢复。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_terminal_error_does_not_break_loop — 不中断循环
|
||||
2. test_terminal_error_task_removed — 任务已移除
|
||||
3. test_terminal_error_re_add_works — 重新 add 生效
|
||||
4. test_terminal_error_other_tasks — 其他终态仍回调
|
||||
5. test_terminal_error_swallowed — 错误被捕获不抛到外层
|
||||
6. test_terminal_error_then_success — 后一轮正常
|
||||
7. test_terminal_error_not_retried — 不自动重试回调
|
||||
8. test_terminal_error_status_kept — 状态保留
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 38:同轮多任务终态分别回调
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
同一轮响应中多个任务同时终态:每个任务各触发一次 onTerminal(带各自 detail/status);顺序按响应顺序。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_multi_terminal_each_called — 各自回调
|
||||
2. test_multi_terminal_correct_detail — 各自 detail
|
||||
3. test_multi_terminal_correct_status — 各自 status
|
||||
4. test_multi_terminal_order — 按响应顺序
|
||||
5. test_multi_terminal_one_fails_other_runs — 一个抛错另一个仍回调
|
||||
6. test_multi_terminal_all_removed — 全部移除
|
||||
7. test_multi_terminal_await_sequence — 依次 await
|
||||
8. test_multi_terminal_async_on_terminal — 异步回调等待
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 39:in-flight 合并测试补强
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
in-flight 期间不叠加 timer;等待上一次完成再按退避重试;同一时间只有一个请求。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_in_flight_no_second_request — 不并发
|
||||
2. test_in_flight_queues_after — 完成后继续
|
||||
3. test_in_flight_backoff_wait — 等待按退避
|
||||
4. test_in_flight_timer_single — 仅一个 timer
|
||||
5. test_in_flight_add_during — 期间 add 不重复
|
||||
6. test_in_flight_error_releases — 失败后释放
|
||||
7. test_in_flight_immediate_repeat — ensure(true) 不叠加
|
||||
8. test_in_flight_long_request — 长请求期间无叠加
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 40:页面隐藏降频与可见恢复
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
visibilityState=hidden 时 30s 间隔;切回 visible 立即刷新(开关可配置、延迟可配置);降频不改任务集合。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_hidden_30s_interval — 隐藏 30s
|
||||
2. test_visible_5s_interval — 可见 5s
|
||||
3. test_foreground_refresh_triggered — 恢复立即刷新
|
||||
4. test_foreground_refresh_disabled — 开关关闭不刷新
|
||||
5. test_foreground_refresh_delayed — 延迟生效
|
||||
6. test_hidden_polling_continues — 隐藏仍轮询
|
||||
7. test_visibility_event_bound_unbound — 事件绑定/解绑
|
||||
8. test_hidden_no_immediate_refresh — 隐藏不触发即时刷新
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
mock document.visibilityState + dispatchEvent。
|
||||
|
||||
## 任务 41:storage 恢复与清理
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
恢复时过滤非正数/非数字;空列表清除 key;终态清理后同步 storage;写失败不影响功能。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_storage_restore_valid_ids — 恢复合法 id
|
||||
2. test_storage_restore_filters_invalid — 过滤非法
|
||||
3. test_storage_restore_empty_clears — 空列表清 key
|
||||
4. test_storage_terminal_removes — 终态后 key 更新
|
||||
5. test_storage_write_failure_ignored — 写失败不抛
|
||||
6. test_storage_bad_json — 坏 JSON 返回空
|
||||
7. test_storage_restore_starts_polling — 恢复即开始轮询
|
||||
8. test_storage_no_key_noop — 无 key 无操作
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
mock localStorage。
|
||||
|
||||
## 任务 42:退避恢复测试
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:31,32 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
失败→退避序列→成功→恢复 500ms 正常间隔;连续失败计数归零后重新从 500 起。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_recovery_after_failure — 失败后成功恢复
|
||||
2. test_backoff_reset_after_success — 计数归零
|
||||
3. test_interval_returns_to_base — 回到正常间隔
|
||||
4. test_recovery_cycle_repeat — 多次失败成功循环
|
||||
5. test_recovery_partial_items — 部分成功算成功
|
||||
6. test_recovery_with_foreground — 前台刷新下恢复
|
||||
7. test_recovery_after_many_failures — 长失败后恢复
|
||||
8. test_recovery_timing_assert — 时间断言(fake timers)
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
fake timers 时间断言。
|
||||
|
||||
## 任务 43:progressCache TTL 惰性清理边界
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
缓存条目超 TTL 在读取时清理;条目数上限(溢出淘汰最旧);空缓存 get 返回 undefined。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_cache_get_hit — 命中返回
|
||||
2. test_cache_get_expired_cleared — 过期清理
|
||||
3. test_cache_max_entries_evict — 超上限淘汰
|
||||
4. test_cache_empty_get_undefined — 空缓存
|
||||
5. test_cache_set_overwrites — 同 key 覆盖
|
||||
6. test_cache_ttl_zero — TTL=0 立即过期
|
||||
7. test_cache_lazy_cleanup — 惰性清理不主动扫
|
||||
8. test_cache_after_polling_cycle — 轮询周期内缓存可用
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
扩展 progress-response-cache.test.ts。
|
||||
|
||||
## 任务 44:轻量端点切换能力
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:26 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
useTaskProgressLoop 的 fetchProgress 可切到轻量端点(只返回 taskId/status/fileStatus 的 items);返回结构兼容(extractTaskId/extractStatus 从轻量字段取);默认仍走原端点。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_fetch_used — 切换后调轻量
|
||||
2. test_light_detail_shape_parsed — 轻量结构解析
|
||||
3. test_light_fallback_to_old — 默认旧端点
|
||||
4. test_light_missing_optional — 轻量缺字段容错
|
||||
5. test_light_terminal_detection — 终态判定
|
||||
6. test_light_progress_cache — 缓存写入
|
||||
7. test_light_on_update_called — onUpdate 收到
|
||||
8. test_light_snapshot_compat — 与旧响应兼容
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 45:轮询与历史刷新分离
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
进度轮询不触发历史接口;历史刷新独立触发(onTerminal 或页面主动);同一轮中不混发 history 请求。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_polling_no_history_request — 轮询不发 history
|
||||
2. test_terminal_triggers_history — 终态触发历史刷新
|
||||
3. test_history_separate_call — 独立调用
|
||||
4. test_no_burst_history — 同轮不多发
|
||||
5. test_history_ttl_cache — 历史 TTL 生效
|
||||
6. test_history_force_refresh — force 参数跳过缓存
|
||||
7. test_polling_history_parallel — 可并行不阻塞
|
||||
8. test_polling_continues_after_history — 历史后轮询继续
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 46:双页面同 key 行为记录
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读断言现状:两页面同 storageKey 时各自独立轮询集合,互不等待(记录已知边界,不改实现)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_two_loops_same_key_independent — 独立
|
||||
2. test_shared_key_no_crash — 不崩溃
|
||||
3. test_shared_key_last_write — 写互相覆盖(现状)
|
||||
4. test_shared_key_restore_both — 各自恢复
|
||||
5. test_shared_key_no_live_sync — 无实时同步(现状)
|
||||
6. test_shared_key_dispose_one — 一方卸载另一方不受影响
|
||||
7. test_documented_boundary — 行为与文档一致
|
||||
8. test_shared_key_separate_storage — 不同 key 完全隔离
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 47:轮询 baseline 统计补强
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
baseline 记录:请求量、响应体大小、缓存内存占用、轮询失败次数;每轮 refreshOnce 后回传 baseline 实例。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_baseline_request_count — 请求计数
|
||||
2. test_baseline_response_size — 响应大小
|
||||
3. test_baseline_cache_usage — 缓存占用
|
||||
4. test_baseline_failure_count — 失败次数
|
||||
5. test_baseline_callback_after_round — 每轮回调
|
||||
6. test_baseline_round_accuracy — 轮次准确
|
||||
7. test_baseline_reset — 重置
|
||||
8. test_baseline_optional_off — 不传 onBaseline 不创建
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
扩展 task-polling-baseline.test.ts。
|
||||
|
||||
## 任务 48:轮询全量回归
|
||||
|
||||
**所属模块**:02 轮询 **依赖**:29-47 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
20 个既有轮询相关测试 + 本轮新增全部通过;`npm run build`(vue-tsc)通过;无行为回退。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8. 回归清单:既有 20 文件全绿、新 19 文件全绿、build 通过、无类型错误、无未用导出、页面入口编译、快照一致、git diff 仅限 shared 目录
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
`npx vitest run` 全绿 + `npm run build` 通过。
|
||||
@@ -0,0 +1,169 @@
|
||||
# 03-plan — RequestTraceFilter 验证与补测
|
||||
|
||||
> 对应 `docs/specs/03-request-trace-filter.md`。**实现已完成**(multipart 直通、阈值 1MB、5 个测试)。
|
||||
> 本 plan 将测试补齐到 ≥8/功能点,并对实现做验证型补强。技术栈:Java 21 + JUnit5 + MockMvc(`backend-java/`)。
|
||||
> 测试命令:`cd crawler-plugin/backend-java && mvn test -Dtest=<类名>`。
|
||||
|
||||
## 任务 49:multipart 直通断言补测
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
multipart Content-Type(含大小写、带 boundary 参数、其他 multipart 子类型)请求一律不包装;现有 5 个测试保留。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_multipart_upper_boundary — Multipart/Form-Data 大写不包装
|
||||
2. test_multipart_mixed_case — mUlTiPaRt 混合大小写
|
||||
3. test_multipart_related — multipart/related 不包装
|
||||
4. test_multipart_no_boundary — 无 boundary 不包装
|
||||
5. test_multipart_with_params — 多参数 content-type
|
||||
6. test_multipart_whitespace — 首尾空白 content-type
|
||||
7. test_multipart_put_not_wrapped — multipart PUT 不包装
|
||||
8. test_application_json_still_wrapped — 对照:json 仍包装
|
||||
|
||||
### TDD 流程
|
||||
1. 追加测试 → 运行确认现有实现是否满足(若已满足为 GREEN,逐条确认覆盖)→ 任何一条失败修正实现
|
||||
2. `mvn test -Dtest=RequestTraceFilterTest` 全绿
|
||||
|
||||
### 验证方法
|
||||
`mvn test -Dtest=RequestTraceFilterTest`:Tests run ≥13。
|
||||
|
||||
## 任务 50:包装与阈值钳制补测
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
JSON/PUT/DELETE 包装;阈值钳制(<1MB 请求钳到 1MB 下限;0/负数钳制);ContentCachingRequestWrapper 构造参数生效。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_json_post_wrapped_limit — json 用传入阈值
|
||||
2. test_limit_below_minimum_clamped — 小于 1MB 钳制
|
||||
3. test_limit_zero_clamped — 0 钳制
|
||||
4. test_limit_negative_clamped — 负数钳制
|
||||
5. test_limit_exact_minimum — 恰好 1MB 不钳
|
||||
6. test_limit_large_kept — 大阈值保留
|
||||
7. test_delete_wrapped — DELETE 包装
|
||||
8. test_put_wrapped — PUT 包装
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上(构造 RequestTraceFilter 实例断言阈值字段,或包内可见字段读取)。
|
||||
|
||||
## 任务 51:日志不读 body 行为测试
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
过滤器执行前后:body 缓存未被读取(日志只消费 method/uri/status/headers);JSON 请求过滤后业务侧仍可读 body。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_filter_log_no_body_read — 日志不含 body 内容
|
||||
2. test_filter_passes_chain — 过滤链正常
|
||||
3. test_business_reads_body_json — 业务可读 json body
|
||||
4. test_business_reads_body_multipart — multipart 业务可读
|
||||
5. test_body_read_after_filter — 过滤后输入流可再读
|
||||
6. test_headers_added — 实例响应头存在
|
||||
7. test_cost_logged — costMs 记录
|
||||
8. test_request_id_logged — requestId 传递
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
MockMvc 集成:POST json 断言 200 + 业务 handler 收到 body。
|
||||
|
||||
## 任务 52:阈值生效集成测试
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
>1MB JSON 请求不整包缓存(wrapper 截断缓存);body 读取行为正确;multipart 大文件上传不受影响。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_large_json_over_1mb — >1MB json 请求成功
|
||||
2. test_large_json_not_cached_fully — 缓存截断(断言 wrapper 截断语义)
|
||||
3. test_large_multipart_upload — >1MB multipart 上传成功
|
||||
4. test_large_body_business_reads — 业务读完整 body
|
||||
5. test_small_json_cached — 小 json 正常缓存
|
||||
6. test_upload_content_length_header — content-length 保留
|
||||
7. test_large_json_forward_path — 转发路径大 body 正常
|
||||
8. test_large_json_time_bounded — 大 body 处理耗时合理
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
MockMvc + 大字符串 body(需注意阈值配置注入)。
|
||||
|
||||
## 任务 53:yml 默认值与 env 覆盖测试
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
application.yml 默认 1048576(1MB);`AIIMAGE_INSTANCE_ROUTE_REQUEST_BODY_CACHE_LIMIT_BYTES` 覆盖生效;占位符语法正确。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_yml_default_1mb — yml 值 1048576
|
||||
2. test_env_override_value — env 覆盖生效
|
||||
3. test_env_override_large — 大值覆盖
|
||||
4. test_env_override_small — 小值覆盖(被钳制)
|
||||
5. test_placeholder_format — ${VAR:default} 格式
|
||||
6. test_default_matches_code — 与代码默认一致
|
||||
7. test_env_unset_uses_default — 未设 env 用默认
|
||||
8. test_yml_loads — Spring 上下文加载配置
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
配置加载测试(@Value 注入断言)。
|
||||
|
||||
## 任务 54:转发服务 multipart 安全测试
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
TaskOwnerForwardService.requestBody 非 wrapper 时走 inputStream 路径;multipart 转发不抛错;body 字节与原请求一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_forward_non_wrapper_reads_stream — inputStream 路径
|
||||
2. test_forward_wrapper_reads_cache — wrapper 路径
|
||||
3. test_forward_multipart_body_ok — multipart 转发成功
|
||||
4. test_forward_io_error_message — IO 异常消息
|
||||
5. test_forward_hop_by_hop_removed — hop-by-hop 头剔除
|
||||
6. test_forward_forwarded_header_set — 转发头设置
|
||||
7. test_forward_content_type_kept — content-type 保留
|
||||
8. test_forward_loop_detected — 循环转发拒绝
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
MockHttpServletRequest + 反射/包可见调用 requestBody。
|
||||
|
||||
## 任务 55:转发 body 完整性测试
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:54 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
转发后:JSON 与 multipart body 均与原始一致(字节级);双实例 owner 路由场景转发内容不损坏。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_forward_json_bytes_equal — json 字节一致
|
||||
2. test_forward_multipart_bytes_equal — multipart 字节一致
|
||||
3. test_forward_empty_body — 空 body 安全
|
||||
4. test_forward_large_body — 大 body 一致
|
||||
5. test_forward_utf8_chinese — 中文内容一致
|
||||
6. test_forward_special_chars — 特殊字符一致
|
||||
7. test_forward_multiple_chunks — 多段内容一致
|
||||
8. test_forward_identity_repeated — 两次转发一致
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
同上。
|
||||
|
||||
## 任务 56:plan §6 文档现状修正核对
|
||||
|
||||
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
更新 `java-architecture-optimization-plan.md` §6:现状描述改为"已实现 multipart 直通 + 1MB 阈值 + 过滤器日志不读 body";移除"大范围缓存风险"表述;标注本轮未做项(上传指标/流式下载/磁盘告警→后续批次)。
|
||||
|
||||
### 测试用例(≥8,验证型)
|
||||
1. test_doc_no_obsolete_default — 文档无 104857600 残留
|
||||
2. test_doc_multipart_stated — 直通已记录
|
||||
3. test_doc_threshold_1mb — 阈值 1MB 已记录
|
||||
4. test_doc_not_reading_body — 不读 body 已记录
|
||||
5. test_doc_deferred_listed — 未做项已列
|
||||
6. test_doc_specs_referenced — 引用 03 spec
|
||||
7. test_doc_consistency_overview — 与 00-overview 实施记录一致
|
||||
8. test_doc_no_todo_left — 无 TBD/TODO 残留
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
grep 校验文档(写一个简单断言脚本/测试读取 md 断言)。
|
||||
@@ -0,0 +1,419 @@
|
||||
# 04-plan — TaskResultFileJobWorker Handler 注册表
|
||||
|
||||
> 对应 `docs/specs/04-result-file-job-handler-registry.md`。技术栈:Java 21 + Spring + JUnit5。
|
||||
> 纪律:第一阶段 Handler 只委托原 Service,不同时重写业务逻辑;Job 状态值、创建时机、重试入口不变。
|
||||
|
||||
## 任务 57:ResultFileJobHandler 接口定义
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`modules/task/service/ResultFileJobHandler.java`:moduleType() / process(job) 返回 boolean / cleanup(job) 默认空 / onFailure(job,msg) 默认空 / supportsAsyncOffload() 默认 false / isOwnerScoped() 默认 false。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_interface_methods_present — 6 方法签名齐全
|
||||
2. test_cleanup_default_noop — 默认空实现
|
||||
3. test_on_failure_default_noop — 默认空实现
|
||||
4. test_offload_default_false — 默认 false
|
||||
5. test_owner_scoped_default_false — 默认 false
|
||||
6. test_process_returns_boolean — boolean 返回类型
|
||||
7. test_module_type_identity — moduleType 唯一标识
|
||||
8. test_javadoc_contract — 契约文档注释齐全(模块类型对应表)
|
||||
|
||||
### TDD 流程
|
||||
1. 写接口 + 编译测试(实现类模拟)→ 类不存在 RED
|
||||
2. 实现接口 → GREEN
|
||||
3. `mvn test` 通过
|
||||
|
||||
## 任务 58:注册表容器与唯一性校验
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`ResultFileJobHandlerRegistry`:构造时收集 List<ResultFileJobHandler>,构建 moduleType→handler Map;重复 moduleType 抛 IllegalStateException(含模块名);提供 `resolve(moduleType)` 与 `moduleTypes()`。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_register_all_handlers — 全部注册
|
||||
2. test_resolve_existing — 解析已知模块
|
||||
3. test_resolve_unknown_throws — 未知模块抛异常
|
||||
4. test_duplicate_module_type_throws — 重复注册抛 IllegalStateException
|
||||
5. test_duplicate_error_message — 错误消息含模块名
|
||||
6. test_module_types_listed — 枚举全部模块
|
||||
7. test_empty_registry_ok — 空注册表可解析(抛错)
|
||||
8. test_resolve_case_sensitive — 大小写敏感
|
||||
|
||||
### TDD 流程
|
||||
1. 写测试(先 mock handler)→ RED
|
||||
2. 实现注册表 → GREEN
|
||||
3. `mvn test -Dtest=ResultFileJobHandlerRegistryTest` 通过
|
||||
|
||||
## 任务 59:启动校验(fail-fast)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:58 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
Spring 启动时校验:TaskFileJobConfig 的每个 moduleType 有且仅有一个 Handler;缺注册(如新增模块未配 Handler)启动失败并给出缺失清单。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_startup_all_modules_covered — 全部 moduleType 覆盖
|
||||
2. test_startup_missing_handler_fails — 缺注册启动失败
|
||||
3. test_startup_missing_message_lists — 错误消息列缺失模块
|
||||
4. test_startup_duplicate_fails — 双注册失败
|
||||
5. test_startup_config_source — 从 TaskFileJobConfig 枚举
|
||||
6. test_startup_no_handler_new_module — 新模块无 handler 失败
|
||||
7. test_startup_valid_no_error — 合法配置启动通过
|
||||
8. test_startup_check_idempotent — 校验可重复执行
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
ApplicationContextRunner 或直接调用校验方法断言。
|
||||
|
||||
## 任务 60:SHOP_MATCH Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`ShopMatchResultFileJobHandler`:moduleType="SHOP_MATCH";process 委托 shopMatchTaskService.processResultFileJob 返回 true;cleanup 调 taskResultPayloadService.deleteLatest(原 cleanupAfterSuccess 分支)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type — 正确
|
||||
2. test_process_delegates — 委托调用
|
||||
3. test_process_returns_true — true
|
||||
4. test_cleanup_calls_delete_latest — 清理调用
|
||||
5. test_cleanup_args — taskId/moduleType/scopeKey 参数
|
||||
6. test_offload_false — 不支持异步
|
||||
7. test_owner_scoped_false — 非 owner scoped
|
||||
8. test_process_null_job_guarded — 空 job 安全
|
||||
|
||||
### TDD 流程
|
||||
1. 写测试 mock Service → RED
|
||||
2. 实现 Handler → GREEN
|
||||
3. `mvn test -Dtest=ShopMatchResultFileJobHandlerTest` 通过
|
||||
|
||||
## 任务 61:PRICE_TRACK Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
与 60 同构:moduleType="PRICE_TRACK";process→priceTrackTaskService;cleanup→deleteLatest。
|
||||
|
||||
### 测试用例(≥8)
|
||||
8 例:moduleType、delegate、true、cleanup、参数、offload false、ownerScoped false、空 job。
|
||||
|
||||
## 任务 62:PRODUCT_RISK_RESOLVE Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
与 60 同构:moduleType="PRODUCT_RISK_RESOLVE";process→productRiskTaskService。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 61。
|
||||
|
||||
## 任务 63:PUBLISH Handler(ownerScoped)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType=PublishTaskService.MODULE_TYPE;process→publishTaskService.processResultFileJob;cleanup→publishTaskService.cleanupResultFileJob;**isOwnerScoped()=true**(原 Worker isOwnerScopedJob 含 PUBLISH)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type_constant — 用 MODULE_TYPE 常量
|
||||
2. test_process_delegates
|
||||
3. test_cleanup_delegates — cleanupResultFileJob
|
||||
4. test_owner_scoped_true — true
|
||||
5. test_process_true
|
||||
6. test_cleanup_no_delete_latest — 不走 payload.deleteLatest
|
||||
7. test_offload_false
|
||||
8. test_null_job_guarded
|
||||
|
||||
## 任务 64:QUERY_ASIN Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
与 60 同构:moduleType="QUERY_ASIN";process→queryAsinTaskService。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 61。
|
||||
|
||||
## 任务 65:SHOP_DATA_CRAWL Handler(cleanup+onFailure)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="SHOP_DATA_CRAWL";process→shopDataCrawlTaskService;cleanup→deleteLatest + cleanupResultFileJob(两处都调);**onFailure→handleResultFileJobFailure**;**isOwnerScoped()=true**。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_delegates
|
||||
3. test_cleanup_delete_latest_and_service — 两处清理都调
|
||||
4. test_on_failure_delegates — handleResultFileJobFailure
|
||||
5. test_on_failure_args — job+message 参数
|
||||
6. test_owner_scoped_true
|
||||
7. test_process_true
|
||||
8. test_null_job_guarded
|
||||
|
||||
## 任务 66:WITHDRAW Handler(finalize 时机保持)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="WITHDRAW";process→withdrawTaskService.processResultFileJob;cleanup→deleteLatest;**onSuccess 扩展:tryFinalizeTask 在 markSuccess 之后调用**(原 finalizeWithdraw 标志语义,时机严格保持)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_delegates
|
||||
3. test_cleanup_delete_latest
|
||||
4. test_finalize_after_success_order — 顺序:成功后再 finalize
|
||||
5. test_finalize_called_once — 只调一次
|
||||
6. test_finalize_false_result — 非成功不 finalize
|
||||
7. test_owner_scoped_false
|
||||
8. test_null_job_guarded
|
||||
|
||||
## 任务 67:PATROL_DELETE Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
与 60 同构:moduleType="PATROL_DELETE";process→patrolDeleteTaskService。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 61。
|
||||
|
||||
## 任务 68:APPEARANCE_PATENT Handler(异步+offload)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="APPEARANCE_PATENT";process→appearancePatentTaskService(返回 boolean,false=等待异步);cleanup→cleanupResultFileJob;**supportsAsyncOffload()=true;isOwnerScoped()=true**。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_boolean_true — true 情况
|
||||
3. test_process_boolean_false — false(等待异步)
|
||||
4. test_cleanup_delegates
|
||||
5. test_offload_true
|
||||
6. test_owner_scoped_true
|
||||
7. test_false_means_waiting — false 语义与 Worker defer 对应
|
||||
8. test_null_job_guarded
|
||||
|
||||
## 任务 69:SIMILAR_ASIN Handler(异步+offload+onFailure)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="SIMILAR_ASIN";process→similarAsinTaskService(boolean);cleanup→cleanupResultFileJob;**onFailure→handleResultFileJobFailure;offload=true;ownerScoped=true**。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_true / 3. test_process_false
|
||||
4. test_cleanup_delegates
|
||||
5. test_on_failure_delegates
|
||||
6. test_offload_true
|
||||
7. test_owner_scoped_true
|
||||
8. test_null_job_guarded
|
||||
|
||||
## 任务 70:DELETE_BRAND Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="DELETE_BRAND";process→deleteBrandRunService;cleanup→cleanupResultFileJob。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:moduleType、delegate、true、cleanup、offload false、ownerScoped false、参数、空 job。
|
||||
|
||||
## 任务 71:BRAND Handler(resolveResultObjectKey 特例)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="BRAND";process→brandTaskService.processResultFileJob;**resultFileUrl 解析特例:resolveResultObjectKey(无 resultId 也走)保留在 Worker 公共路径 resolveResultFileUrl**——Handler 不接管 URL 解析,测试验证该特例不受影响。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_delegates
|
||||
3. test_result_url_brand_special — brand resolveResultObjectKey 仍走公共路径
|
||||
4. test_cleanup_delegates
|
||||
5. test_offload_false
|
||||
6. test_owner_scoped_false
|
||||
7. test_null_job_guarded
|
||||
8. test_no_delete_latest — brand 不走 payload.deleteLatest
|
||||
|
||||
## 任务 72:COLLECT_DATA Handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
|
||||
|
||||
moduleType="COLLECT_DATA";process→collectDataService.processResultFileJob;cleanup 为空(原无分支)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_type
|
||||
2. test_process_delegates
|
||||
3. test_process_true
|
||||
4. test_cleanup_noop — 无清理
|
||||
5. test_offload_false
|
||||
6. test_owner_scoped_false
|
||||
7. test_null_job_guarded
|
||||
8. test_no_delete_latest
|
||||
|
||||
## 任务 73:Worker dispatch() 改注册表查找
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
TaskResultFileJobWorker.dispatch(job) 替换 13 个 if/else 为 `handlerRegistry.resolve(moduleType).process(job)`;未知模块 IllegalArgumentException 消息保留;Worker 注入改为 registry。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dispatch_resolves_handler — 注册表查找
|
||||
2. test_dispatch_known_module — 已知模块行为一致
|
||||
3. test_dispatch_unknown_throws — 未知模块 IllegalArgumentException
|
||||
4. test_dispatch_unknown_message — 消息含模块名
|
||||
5. test_dispatch_all_13_modules — 13 模块各委托正确
|
||||
6. test_dispatch_null_job — 空 job 安全
|
||||
7. test_dispatch_no_longer_branch — 无 if/else 残留(静态检查)
|
||||
8. test_dispatch_integration_process — process 全链路
|
||||
|
||||
### TDD 流程
|
||||
1. 测试先断言 dispatch 行为(对现有实现 GREEN 基线)→ 改为注册表后仍 GREEN
|
||||
2. `mvn test` 相关测试通过
|
||||
|
||||
## 任务 74:cleanupAfterSuccess 改 handler.cleanup
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
|
||||
|
||||
cleanupAfterSuccess(job):公共 payload 清理保留(部分模块)或进 handler.cleanup;确保原分支语义逐一映射(SHOP_DATA_CRAWL 两处、APPEARANCE_PATENT/SIMILAR_ASIN/PUBLISH/DELETE_BRAND 各 cleanup、其余 deleteLatest)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_cleanup_shop_data_crawl_both — 两处清理
|
||||
2. test_cleanup_delete_latest_modules — deleteLatest 模块组
|
||||
3. test_cleanup_appearance — cleanupResultFileJob
|
||||
4. test_cleanup_similar — cleanupResultFileJob
|
||||
5. test_cleanup_publish — cleanupResultFileJob
|
||||
6. test_cleanup_delete_brand — cleanupResultFileJob
|
||||
7. test_cleanup_collect_data_noop — 无清理
|
||||
8. test_cleanup_unknown_ignored — 未知模块不抛
|
||||
|
||||
## 任务 75:notifyRetryExhausted 改 handler.onFailure
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
|
||||
|
||||
notifyRetryExhausted(job,msg) 改 handler.onFailure;SHOP_DATA_CRAWL/SIMILAR_ASIN 有回调,其余 noop;回调幂等(失败重试安全)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_on_failure_shop_data_crawl — 回调
|
||||
2. test_on_failure_similar — 回调
|
||||
3. test_on_failure_others_noop — 其余无操作
|
||||
4. test_on_failure_unknown_ignored — 未知模块安全
|
||||
5. test_on_failure_idempotent — 重复调用安全
|
||||
6. test_on_failure_error_swallowed — 回调抛错不中断
|
||||
7. test_on_failure_args_passed — job+message 传递
|
||||
8. test_exhausted_finalize_flow — 重试耗尽全流程
|
||||
|
||||
## 任务 76:coze offload 判定改 handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
|
||||
|
||||
process() 中 APPEARANCE_PATENT/SIMILAR_ASIN 的 cozeTaskExecutor offload 判定改 handler.supportsAsyncOffload();offload 失败回退内联逻辑保持。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_offload_modules_detected — offload 模块识别
|
||||
2. test_offload_executes_on_coze_executor — 线程池执行
|
||||
3. test_offload_failure_fallback — 提交失败回退内联
|
||||
4. test_offload_other_modules_inline — 非 offload 内联
|
||||
5. test_offload_only_async_modules — 仅异步模块
|
||||
6. test_offload_no_duplicate_execution — 不回退重复执行
|
||||
7. test_offload_heartbeat_started — 心跳启动
|
||||
8. test_offload_integration — 全链路
|
||||
|
||||
## 任务 77:owner-scoped 判定改 handler
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
|
||||
|
||||
isOwnerScopedJob 改 handler.isOwnerScoped();owner 解析(scopeKey :owner: 标记)保留公共逻辑;非本实例跳过逻辑保持。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_owner_scoped_modules — 4 个 owner 模块
|
||||
2. test_owner_scoped_other_owner_skip — 他实例跳过
|
||||
3. test_owner_scoped_self_process — 本实例处理
|
||||
4. test_owner_scope_parse — :owner: 解析
|
||||
5. test_owner_scope_blank — 空 scope 视为本实例
|
||||
6. test_owner_non_scoped_modules — 非 owner 模块不受影响
|
||||
7. test_owner_unknown_instance_id — 未配置实例
|
||||
8. test_owner_integration — 全链路
|
||||
|
||||
## 任务 78:模块映射快照测试
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
快照断言:13 个 moduleType → Handler 类 → 原 Service 方法一一对应;与 04 spec §3 映射表一致;新增模块类型未映射即失败。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_snapshot_all_13_mapped — 13 全映射
|
||||
2. test_snapshot_shop_match_delegate — 委托方法名快照
|
||||
3. test_snapshot_appearance_boolean — 返回类型快照
|
||||
4. test_snapshot_publish_owner — owner 标记快照
|
||||
5. test_snapshot_failure_callbacks — onFailure 回调快照
|
||||
6. test_snapshot_no_extra_modules — 无多余映射
|
||||
7. test_snapshot_mapping_frozen — JSON 快照文件比对
|
||||
8. test_snapshot_new_module_fails — 新 moduleType 快照失败
|
||||
|
||||
## 任务 79:行为等价对比测试
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:73-77 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
同一 Job 序列(成功/失败/重试耗尽/异步等待/owner 跳过)改造前后产生相同状态迁移与依赖调用;用 mock 记录调用序列对比。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_equiv_success_job — 成功序列一致
|
||||
2. test_equiv_failed_job — 失败序列一致
|
||||
3. test_equiv_retry_exhausted — 重试耗尽一致
|
||||
4. test_equiv_async_wait — 异步等待一致
|
||||
5. test_equiv_owner_skip — owner 跳过一致
|
||||
6. test_equiv_orphan_failure — 孤儿失败一致
|
||||
7. test_equiv_call_sequence — 依赖调用顺序一致
|
||||
8. test_equiv_state_transition — 状态迁移一致
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
对比测试:改造前录制调用序列(golden),改造后断言一致。
|
||||
|
||||
## 任务 80:孤儿失败路径不回归
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
|
||||
|
||||
BusinessException 含 not found 文案 → markFailedPermanent;非孤儿失败 → markFailed + retry 判断;错误文案匹配清单(task not found/result record not found/任务不存在/记录不存在)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_orphan_task_not_found_en — 英文文案
|
||||
2. test_orphan_result_not_found_en
|
||||
3. test_orphan_cn_messages — 中文文案
|
||||
4. test_orphan_mark_permanent — markFailedPermanent
|
||||
5. test_non_orphan_mark_failed — 普通失败
|
||||
6. test_non_business_exception — 非业务异常
|
||||
7. test_retry_exhausted_after_orphan — 耗尽后终态
|
||||
8. test_orphan_no_requeue — 孤儿不重排
|
||||
|
||||
## 任务 81:卡死扫描/重试耗尽路径测试
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
|
||||
|
||||
resetStuckRunningJobsDetailed:超时卡死 job 重置;耗尽 job 走 finalizeRetryExhausted;消息默认文案("文件生成任务运行超时")。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_stuck_reset — 超时重置
|
||||
2. test_stuck_exhausted_finalize — 耗尽 finalize
|
||||
3. test_stuck_default_message — 默认文案
|
||||
4. test_stuck_custom_message — 自定义文案
|
||||
5. test_stuck_heartbeat_timeout — 心跳超时边界
|
||||
6. test_stuck_scan_interval — 调度间隔配置
|
||||
7. test_stuck_no_reset_active — 活跃 job 不重置
|
||||
8. test_stuck_idempotent — 重复扫描安全
|
||||
|
||||
## 任务 82:特殊规则回归(WITHDRAW/coze defer)
|
||||
|
||||
**所属模块**:04 注册表 **依赖**:78-81 **预估**:8-15 分钟
|
||||
|
||||
WITHDRAW markSuccess 后 tryFinalizeTask;coze 模块 dispatch 返回 false → touchRunning(owner)或 deferRunning;状态与时机与原实现完全一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_withdraw_finalize_after_success — 成功后 finalize
|
||||
2. test_withdraw_no_finalize_failed — 失败不 finalize
|
||||
3. test_coze_false_owner_touch — owner 路径 touchRunning
|
||||
4. test_coze_false_defer — 非 owner deferRunning
|
||||
5. test_coze_false_no_mark_failed — 等待不标记失败
|
||||
6. test_coze_true_mark_success — 完成后 markSuccess
|
||||
7. test_withdraw_finalize_once — 只一次
|
||||
8. test_special_rules_integration — 全链路
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 全量 + `mvn clean package -DskipTests` 通过;04 spec §4 兼容清单逐项核对。
|
||||
@@ -0,0 +1,286 @@
|
||||
# 05-plan — 巨型 Service 纯函数抽取
|
||||
|
||||
> 对应 `docs/specs/05-service-pure-function-extraction.md`。目标:SimilarAsinTaskService(7228 行)、AppearancePatentTaskService(3195)、ShopDataCrawlTaskService(3013)。
|
||||
> 纪律:只抽纯函数;门面签名不收缩;每模块独立提交;同一提交只做类拆分。
|
||||
|
||||
## 任务 83:SimilarAsinExcelParser 行解析器
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
新类 `modules/similarasin/service/support/SimilarAsinExcelParser`:POI 读 Excel 行 → 中间行对象(原始单元格值);输入 InputStream/文件 → 输出 List<中间行>;不改动现有解析语义(同一文件输出与现状逐字节一致)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_parse_normal_rows — 正常多行解析
|
||||
2. test_parse_single_row — 单行
|
||||
3. test_parse_columns_mapping — 列序映射
|
||||
4. test_parse_empty_sheet — 空表返回空
|
||||
5. test_parse_empty_rows_skipped — 空行跳过
|
||||
6. test_parse_null_input_throws — 空输入抛 IllegalArgumentException
|
||||
7. test_parse_unsupported_format — 非 Excel 文件抛对应异常
|
||||
8. test_parse_no_mutation — 输入流不被篡改(可重复读)
|
||||
|
||||
### TDD 流程
|
||||
1. 写测试(用夹具 xlsx 放 test resources)→ RED
|
||||
2. 实现解析器(从 Service 中搬移现有解析逻辑)→ GREEN
|
||||
3. `mvn test -Dtest=SimilarAsinExcelParserTest` 通过
|
||||
|
||||
## 任务 84:行解析边界测试
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:83 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
边界输入:超长字段(>32767)、畸形 ASIN(特殊字符)、BOM、混合编码、行数上限(>65535 xlsx)、数值/文本混合单元格。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_parse_long_field — 超长字段不截断/按现状
|
||||
2. test_parse_malformed_asin — 畸形 ASIN 原样透传
|
||||
3. test_parse_bom — BOM 头处理
|
||||
4. test_parse_mixed_encoding — 混合编码单元格
|
||||
5. test_parse_numeric_cell — 数值单元格转文本
|
||||
6. test_parse_date_cell — 日期单元格
|
||||
7. test_parse_formula_cell — 公式单元格取缓存值
|
||||
8. test_parse_large_sheet — 大表(5000 行)性能上界
|
||||
|
||||
## 任务 85:字段归一化器
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`SimilarAsinRowNormalizer`:trim/大小写/ASIN 格式统一(保留现状规则,不改变输出);纯函数无状态。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_trim_whitespace — 首尾空白
|
||||
2. test_lowercase_asin — 小写转大写
|
||||
3. test_mixed_case_asin — 混合大小写统一
|
||||
4. test_internal_whitespace_kept — 内部空格保留(现状)
|
||||
5. test_null_safe — null 安全
|
||||
6. test_empty_string — 空串
|
||||
7. test_special_chars_untouched — 特殊字符不动
|
||||
8. test_normalize_identity_after — 幂等(二次归一不变)
|
||||
|
||||
## 任务 86:分组转换器
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`SimilarAsinGroupingConverter`:归一化行 → 分组 → DTO(TaskItem/FileItem);分组规则与现状一致(同组/子行 2_2、2_3 处理);纯函数。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_group_normal — 正常分组
|
||||
2. test_group_sub_rows — 子行归组
|
||||
3. test_group_single_item — 单元素组
|
||||
4. test_group_empty_input — 空输入空输出
|
||||
5. test_group_dto_fields — DTO 字段映射
|
||||
6. test_group_dedup — 组内去重
|
||||
7. test_group_order — 分组顺序保持
|
||||
8. test_group_missing_key — 缺分组键兜底
|
||||
|
||||
## 任务 87:纯校验器
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:85 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`SimilarAsinRowValidator`:必填检查、ASIN 格式校验、重复检测;返回错误清单(不抛异常,由调用方决定);规则与现状一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_validate_required_present — 必填齐全通过
|
||||
2. test_validate_required_missing — 缺必填报错
|
||||
3. test_validate_asin_format — ASIN 格式
|
||||
4. test_validate_duplicates — 重复标记
|
||||
5. test_validate_blank_row — 空白行
|
||||
6. test_validate_no_error_happy — 无误通过
|
||||
7. test_validate_error_detail — 错误含行列信息
|
||||
8. test_validate_null_input — 空输入错误清单
|
||||
|
||||
## 任务 88:Sheet 构造器
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`SimilarAsinSheetBuilder`:结果 Workbook/Sheet 构造辅助(表头、列顺序、样式);输入数据 → 输出 workbook;不落库、无 IO 依赖。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_sheet_header_row — 表头正确
|
||||
2. test_sheet_column_order — 列顺序固定
|
||||
3. test_sheet_data_rows — 数据行写入
|
||||
4. test_sheet_empty_data — 空数据仍出表头
|
||||
5. test_sheet_style_applied — 样式应用
|
||||
6. test_sheet_zip_output — 可输出 xlsx 文件流
|
||||
7. test_sheet_large_rows — 大行数(5000)性能
|
||||
8. test_sheet_no_state_leak — 多次调用独立
|
||||
|
||||
## 任务 89:SimilarAsinService.parse 门面改委托
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:83-88 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
parse 方法内部改为:parser.parse → normalizer.normalize → validator → converter → 落库(落库逻辑保留原处);方法签名、参数、返回类型一字不变;删除搬走的代码。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_parse_signature_unchanged — 签名编译兼容
|
||||
2. test_parse_delegates_parser — 调用解析器
|
||||
3. test_parse_delegates_normalizer
|
||||
4. test_parse_delegates_validator
|
||||
5. test_parse_delegates_converter
|
||||
6. test_parse_persistence_kept — 落库逻辑仍在
|
||||
7. test_parse_result_same — 与改造前结果一致
|
||||
8. test_parse_exception_same — 异常行为一致
|
||||
|
||||
## 任务 90:抽取前后快照对比测试
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:89 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
夹具 Excel → 解析结果快照(golden 文件);抽取前后同一夹具输出完全一致;快照变更即失败(防止行为漂移)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_snapshot_parse_output — 解析输出快照一致
|
||||
2. test_snapshot_groups — 分组快照
|
||||
3. test_snapshot_dtos — DTO 快照
|
||||
4. test_snapshot_error_cases — 错误案例快照
|
||||
5. test_snapshot_reproducible — 可重复(跑两次一致)
|
||||
6. test_snapshot_golden_committed — golden 文件存在
|
||||
7. test_snapshot_diff_detected — 篡改 golden 即失败
|
||||
8. test_snapshot_regression_all_parse — 全 parse 路径回归
|
||||
|
||||
## 任务 91:SimilarAsin 历史查询组装抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
历史列表 VO 拼装(history + toHistoryItem 辅助)抽到独立组件 `SimilarAsinHistoryAssembler`;只读不落库;输出与现状一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_assembler_history_items — 历史项组装
|
||||
2. test_assembler_no_result — 无结果空列表
|
||||
3. test_assembler_file_state — file 状态附带
|
||||
4. test_assembler_order — 排序保持
|
||||
5. test_assembler_null_task — 缺 task 兜底
|
||||
6. test_assembler_download_url — URL 构造
|
||||
7. test_assembler_immutable_input — 输入不被改
|
||||
8. test_assembler_consistency — 与现状输出一致
|
||||
|
||||
## 任务 92:SimilarAsin 全量回归
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:89-91 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
similarasin 模块相关测试全绿;`mvn test` 无回归;API 行为与改造前一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8. 回归清单:新组件测试全绿、既有 similarasin 测试全绿、controller 签名编译、DTO 字段快照、Python 回调相关测试、单测全量、package 通过、git diff 无越界
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
`mvn test` + `mvn clean package -DskipTests`。
|
||||
|
||||
## 任务 93:AppearancePatent 行解析/归一化抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
|
||||
|
||||
同 83/85 模式,针对 AppearancePatentTaskService 的解析与归一化逻辑(注意其 Excel 结构与 similarasin 不同)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:正常解析、单行、空表、空行、归一化规则、边界(超长/畸形)、输入安全、快照一致。
|
||||
|
||||
## 任务 94:AppearancePatent Sheet 构造抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:88 **预估**:8-15 分钟
|
||||
|
||||
同 88 模式(列顺序以 appearancepatent 现状为准)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:表头、列序、数据行、空数据、样式、输出流、大行数、无状态泄漏。
|
||||
|
||||
## 任务 95:AppearancePatent 门面改委托
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:93,94 **预估**:8-15 分钟
|
||||
|
||||
同 89 模式;注意 appearancepatent 的 submitResult 双事务路径不动。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:签名不变、委托各组件、落库保留、结果一致、异常一致、双事务路径不变、owner 检查不变、全回归。
|
||||
|
||||
## 任务 96:AppearancePatent 快照对比测试
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:95 **预估**:8-15 分钟
|
||||
|
||||
同 90 模式(夹具为 appearancepatent 实际 Excel 结构)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 90。
|
||||
|
||||
## 任务 97:AppearancePatent 历史查询组装抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 91 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 91。
|
||||
|
||||
## 任务 98:AppearancePatent 全量回归
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:95-97 **预估**:8-15 分钟
|
||||
|
||||
同 92 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 92(appearancepatent 相关)。
|
||||
|
||||
## 任务 99:ShopDataCrawl 行解析抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
|
||||
|
||||
同 93 模式(shopdatacrawl 结构)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 93。
|
||||
|
||||
## 任务 100:ShopDataCrawl Sheet 构造抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:88 **预估**:8-15 分钟
|
||||
|
||||
同 94 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 94。
|
||||
|
||||
## 任务 101:ShopDataCrawl 门面改委托
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:99,100 **预估**:8-15 分钟
|
||||
|
||||
同 95 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 95。
|
||||
|
||||
## 任务 102:ShopDataCrawl 快照对比测试
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:101 **预估**:8-15 分钟
|
||||
|
||||
同 96 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 96。
|
||||
|
||||
## 任务 103:ShopDataCrawl 历史查询组装抽取
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 97 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 97。
|
||||
|
||||
## 任务 104:ShopDataCrawl 全量回归
|
||||
|
||||
**所属模块**:05 拆分 **依赖**:101-103 **预估**:8-15 分钟
|
||||
|
||||
同 98 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 98。
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 全量 + `mvn clean package -DskipTests`;05 spec §4 不变要求逐项核对;三模块各一个独立提交。
|
||||
@@ -0,0 +1,325 @@
|
||||
# 06-plan — 只读查询与批量加载优化
|
||||
|
||||
> 对应 `docs/specs/06-read-query-batch-loading.md`。行为不变型优化 + 新增 progress/light 轻量接口。
|
||||
> 技术栈:Java 21 + MyBatis-Plus + Flyway。
|
||||
|
||||
## 任务 105:similarasin 历史列表 IN 查询批量加载
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
history 方法:任务+结果+Job 关联数据由逐条查询改为 IN 批量查询 + 按 ID Map 装配;分页结果、排序、过滤不变;输出与现状一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_history_batch_loads — 批量加载装配
|
||||
2. test_history_single_row — 单条
|
||||
3. test_history_multiple_tasks — 多任务
|
||||
4. test_history_no_jobs — 无 Job 兼容
|
||||
5. test_history_order_unchanged — 排序不变
|
||||
6. test_history_pagination — 分页不变
|
||||
7. test_history_missing_related — 关联缺失兜底
|
||||
8. test_history_sql_count — IN 查询次数(≤N,断言 mapper 调用次数)
|
||||
|
||||
### TDD 流程
|
||||
1. 写测试(mock mapper 断言查询次数与装配)→ RED
|
||||
2. 改造 history 实现 → GREEN
|
||||
3. `mvn test -Dtest=SimilarAsinTaskServiceTest` 通过
|
||||
|
||||
## 任务 106:appearancepatent 历史列表批量加载
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:105 **预估**:8-15 分钟
|
||||
|
||||
同 105 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 105(appearancepatent)。
|
||||
|
||||
## 任务 107:结果列表关联 Job 批量加载
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
结果列表/详情页关联 TaskFileJob 状态:findAssembleJobsByResultIds 覆盖审计;逐条查 result→job 的路径改 IN;输出不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_result_job_batch — 批量取 Job
|
||||
2. test_result_job_single — 单条
|
||||
3. test_result_job_empty — 空结果
|
||||
4. test_result_job_map_keyed — 按 resultId Map
|
||||
5. test_result_job_missing — 缺 Job 兜底
|
||||
6. test_result_job_query_count — 查询次数断言
|
||||
7. test_result_job_null_guard — null 安全
|
||||
8. test_result_job_consistency — 与现状一致
|
||||
|
||||
## 任务 108:dashboard 聚合查询
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
dashboard 统计改批量聚合(COUNT/GROUP BY 一次出);状态分类计数与逐条统计结果一致;输出结构不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dashboard_counts — 各状态计数
|
||||
2. test_dashboard_empty — 空用户 0 计数
|
||||
3. test_dashboard_aggregate_sql — 聚合 SQL 调用
|
||||
4. test_dashboard_recent_tasks — 最近任务列表
|
||||
5. test_dashboard_consistency — 与逐条一致
|
||||
6. test_dashboard_mixed_status — 混合状态
|
||||
7. test_dashboard_user_filter — 用户过滤
|
||||
8. test_dashboard_big_data — 大数据量聚合
|
||||
|
||||
## 任务 109:progress/light 轻量接口(similarasin 首个)
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
新端点 `POST /api/similar-asin/tasks/progress/light`:body {taskIds};resp items[{taskId,status,statusCode?,fileStatus,fileReady,updatedAt}];旧 progress/batch 保留不动;走轻量查询(不查明细/result 行)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_returns_light_fields — 只返回轻量字段
|
||||
2. test_light_missing_task — missingTaskIds
|
||||
3. test_light_empty_ids — 空 ids 空结果
|
||||
4. test_light_dedup_ids — 去重
|
||||
5. test_light_old_endpoint_untouched — 旧端点仍工作
|
||||
6. test_light_status_mapping — 状态映射正确
|
||||
7. test_light_file_fields — file 字段附带
|
||||
8. test_light_unknown_id — 未知 id 缺失列表
|
||||
|
||||
### TDD 流程
|
||||
1. 测试(MockMvc 打新端点)→ RED(404)
|
||||
2. 实现 controller + service → GREEN
|
||||
3. `mvn test -Dtest=SimilarAsinControllerTest` 通过
|
||||
|
||||
## 任务 110:progress/light 字段白名单
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
响应仅含白名单字段(taskId/status/statusCode/fileStatus/fileReady/updatedAt);不含 items 明细/payload/result 内容;序列化断言。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_whitelist_no_items — 无明细数组
|
||||
2. test_whitelist_no_payload — 无 payload 字段
|
||||
3. test_whitelist_exact_keys — 键集合精确匹配
|
||||
4. test_whitelist_file_phase — file 字段在白名单
|
||||
5. test_whitelist_extra_rejected — 多余键测试失败
|
||||
6. test_whitelist_null_values_ok — null 值允许
|
||||
7. test_whitelist_response_size_small — 响应体小(<1KB)
|
||||
8. test_whitelist_documented — 白名单文档一致
|
||||
|
||||
## 任务 111:progress/light 空/超长 taskIds
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
空数组→空 items;null→空;>200 个截断或返回错误(定义行为);非正数过滤。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_empty_array — 空数组
|
||||
2. test_light_null_body — null body 处理
|
||||
3. test_light_negative_filter — 负数过滤
|
||||
4. test_light_zero_filter — 0 过滤
|
||||
5. test_light_over_200 — 超长截断/错误
|
||||
6. test_light_duplicates — 重复去重
|
||||
7. test_light_single — 单 id
|
||||
8. test_light_max_exact — 恰好上限
|
||||
|
||||
## 任务 112:progress/light 终态任务返回
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
SUCCESS/FAILED 任务在 light 接口返回终态状态 + file 阶段;前端可凭此停止轮询并展示。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_success_task — SUCCESS 返回
|
||||
2. test_light_failed_task — FAILED 返回
|
||||
3. test_light_pending — PENDING
|
||||
4. test_light_running — RUNNING
|
||||
5. test_light_success_file_status — 附带 fileStatus
|
||||
6. test_light_failed_file_error — 失败附带 fileError
|
||||
7. test_light_terminal_complete — 终态字段完整
|
||||
8. test_light_status_frozen — 状态值语义不变
|
||||
|
||||
## 任务 113:其余模块 progress/light 接入
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109-112 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
同构端点接入:appearancepatent/publish/queryasin/shopdatacrawl/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/collectdata(11 个);路径模式统一;字段白名单一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_all_modules_exist — 12 个 light 端点存在
|
||||
2. test_light_common_shape — 响应结构一致
|
||||
3. test_light_module_specific_status — 各模块状态映射
|
||||
4. test_light_publish_files — publish 文件级字段
|
||||
5. test_light_old_endpoints_all_kept — 旧端点全保留
|
||||
6. test_light_whitelist_all — 白名单一致
|
||||
7. test_light_missing_all — 缺失任务处理
|
||||
8. test_light_contract_frozen — 契约快照
|
||||
|
||||
## 任务 114:批量加载等价快照测试
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:105-108 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
改造前后同数据:历史页、结果页、dashboard 输出字段完全一致(快照对比)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_history_snapshot_equiv — 历史快照一致
|
||||
2. test_dashboard_snapshot_equiv — dashboard 一致
|
||||
3. test_result_snapshot_equiv — 结果一致
|
||||
4. test_pagination_equiv — 分页一致
|
||||
5. test_snapshot_reproducible — 可重复
|
||||
6. test_snapshot_diff_fails — 篡改即失败
|
||||
7. test_snapshot_covers_all — 覆盖三页
|
||||
8. test_snapshot_regression_guard — 全量回归门禁
|
||||
|
||||
## 任务 115:高频查询 EXPLAIN 索引审计
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
对高频查询(history/progress/dashboard)逐条 EXPLAIN;产出索引迁移清单(表/列/类型/收益/风险);不做 DDL。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_explain_history_plan — history 执行计划记录
|
||||
2. test_explain_progress_plan — progress 计划
|
||||
3. test_explain_dashboard_plan — dashboard 计划
|
||||
4. test_full_scan_detected — 全表扫描标记
|
||||
5. test_index_candidates_listed — 候选索引清单
|
||||
6. test_plan_documented — 审计文档产出
|
||||
7. test_plan_repeatable — 可重复执行
|
||||
8. test_no_ddl_this_task — 本任务无 DDL
|
||||
|
||||
## 任务 116:索引迁移 V{N+1}
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:115 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
按审计清单追加 `db/V{N+1}__*.sql`(只追加不改历史);包含验证 SQL;标注锁表风险与窗口。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_migration_file_exists — 迁移文件存在
|
||||
2. test_migration_version_sequential — 版本号续接
|
||||
3. test_migration_validated — 验证 SQL 通过(副本库)
|
||||
4. test_migration_index_created — 索引生效
|
||||
5. test_explain_improved — 执行计划改善
|
||||
6. test_migration_no_alter_legacy — 不改历史迁移
|
||||
7. test_migration_rollback_doc — 回滚步骤记录
|
||||
8. test_migration_backward_safe — 旧数据兼容
|
||||
|
||||
## 任务 117:progress/light user_id 权限过滤
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
user_id 传入时仅返回该用户任务;未传时按 taskId 反查;越权任务进 missingTaskIds(不泄露)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_user_filter — 用户过滤
|
||||
2. test_light_no_user_reverse — 无 user 反查
|
||||
3. test_light_other_user_hidden — 他人任务隐藏
|
||||
4. test_light_missing_on_unauthorized — 越权进 missing
|
||||
5. test_light_user_null — 全空 userId
|
||||
6. test_light_admin_scope — 管理范围(按现状)
|
||||
7. test_light_user_consistent — 与旧端点一致
|
||||
8. test_light_no_leak — 响应不含他人数据
|
||||
|
||||
## 任务 118:前端 getModuleProgressLight 适配
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:109,44 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
java-modules.ts 新增 `getModuleProgressLight(module, taskIds)` 调 light 端点;返回结构归一为现有 progress 类型;页面可渐进切换。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_light_url_module — 模块路径正确
|
||||
2. test_light_payload — taskIds body
|
||||
3. test_light_response_shape — 归一结构
|
||||
4. test_light_fallback_flag — 可开关
|
||||
5. test_light_missing_ids — missingTaskIds 映射
|
||||
6. test_light_timeout — 10s 超时
|
||||
7. test_light_type_compat — 与旧类型兼容
|
||||
8. test_light_snapshot — 快照
|
||||
|
||||
## 任务 119:前端 dashboard/history/progress 分离调用测试
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
前端页面:dashboard 只调统计、history 只调摘要、progress 只调轻量;首次打开不加载全部明细;断言请求路径分离。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_page_dashboard_only_stats — 只调统计
|
||||
2. test_page_history_only_summary — 只调摘要
|
||||
3. test_page_progress_only_light — 只调进度
|
||||
4. test_page_no_full_detail_on_load — 首开不拉明细
|
||||
5. test_page_items_on_open — 打开明细才请求
|
||||
6. test_page_result_on_demand — 结果按需
|
||||
7. test_page_request_count_bounded — 请求数有界
|
||||
8. test_page_snapshot — 请求快照
|
||||
|
||||
## 任务 120:大页数据性能回归
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:105-108 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
500 任务级数据:history/dashboard/progress 响应时间上界(基准线);不劣于改造前。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_perf_history_500 — 历史耗时
|
||||
2. test_perf_dashboard_500 — dashboard 耗时
|
||||
3. test_perf_progress_200 — 200 任务进度
|
||||
4. test_perf_light_200 — light 更快
|
||||
5. test_perf_query_count — 查询次数上界
|
||||
6. test_perf_no_regression — 与基线对比
|
||||
7. test_perf_memory_bounded — 内存有界
|
||||
8. test_perf_report — 结果记录
|
||||
|
||||
## 任务 121:N+1 扫描审计
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
对 modules 下 Service 扫描逐条 selectById/selectOne 循环模式;产出 N+1 清单(位置/对象/影响);不做修改。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_scan_select_in_loop — 识别循环内单查
|
||||
2. test_scan_output_listed — 清单产出
|
||||
3. test_scan_priority — 按影响排序
|
||||
4. test_scan_module_coverage — 覆盖主要模块
|
||||
5. test_scan_false_positive_checked — 排除误报(已批量)
|
||||
6. test_scan_repeatable — 可重复
|
||||
7. test_scan_documented — 文档产出
|
||||
8. test_scan_no_edit — 本任务不改代码
|
||||
|
||||
## 任务 122:N+1 批量化修复
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:121 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
按清单修复高影响 N+1(IN 查询 + Map 装配);行为不变;快照对比验证。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_fix_in_query — 改 IN 查询
|
||||
2. test_fix_map_assembly — Map 装配
|
||||
3. test_fix_behavior_same — 行为一致
|
||||
4. test_fix_single_row — 单行兼容
|
||||
5. test_fix_empty — 空兼容
|
||||
6. test_fix_query_count_reduced — 查询次数下降
|
||||
7. test_fix_snapshot — 输出快照
|
||||
8. test_fix_no_side_effect — 无副作用
|
||||
|
||||
## 任务 123:06 全量回归
|
||||
|
||||
**所属模块**:06 批量加载 **依赖**:105-122 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
06 全部任务产出物 + 既有测试全绿;light 契约快照冻结;无行为回退。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:全部新测试绿、既有回归绿、light 契约快照、旧端点可用、索引迁移就绪、前端适配编译、性能基线、git diff 范围
|
||||
|
||||
### 验证方法
|
||||
`mvn test` 全量 + `cd frontend-vue && npm run build` + `npx vitest run`。
|
||||
@@ -0,0 +1,250 @@
|
||||
# 07-plan — 保守缩短事务边界
|
||||
|
||||
> 对应 `docs/specs/07-transaction-boundary.md`。硬约束:Python /result 成功确认时机、done=true 封口、状态成功时机、回滚语义全部不变。
|
||||
> 技术栈:Java 21 + Spring Transaction。
|
||||
|
||||
## 任务 124:@Transactional 方法审计清单
|
||||
|
||||
**所属模块**:07 事务 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
扫描 modules 下全部 @Transactional 方法,产出审计清单:方法/事务内代码段分类(必须事务内:落库/状态/锁;可移出:纯计算/DTO 组装/日志/清理);文档产出,不改代码。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_audit_covers_all_modules — 覆盖全部业务模块
|
||||
2. test_audit_classification — 分类完整(必须/可移出)
|
||||
3. test_audit_result_endpoints — /result 方法都在清单
|
||||
4. test_audit_python_facing — Python 回调相关标记
|
||||
5. test_audit_priority_order — 按收益排序
|
||||
6. test_audit_no_code_change — 本任务零代码变更
|
||||
7. test_audit_documented — 文档产出
|
||||
8. test_audit_repeatable — 可重复执行
|
||||
|
||||
### TDD 流程
|
||||
1. 写审计脚本/测试(断言清单文件存在且字段齐全)→ RED
|
||||
2. 产出清单 → GREEN
|
||||
3. 文档校验
|
||||
|
||||
## 任务 125:similarasin 纯计算移出事务
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
similarasin 的 /result 提交事务内纯计算段(分组/百分比/校验)抽为无事务方法,在写库前调用;输出与现状一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_pure_compute_outside_tx — 计算在事务外
|
||||
2. test_compute_result_same — 结果一致
|
||||
3. test_tx_persistence_kept — 落库仍在事务内
|
||||
4. test_failure_rollback — 落库失败回滚(计算无副作用)
|
||||
5. test_compute_idempotent — 计算幂等
|
||||
6. test_compute_repeat_safe — 重复调用安全
|
||||
7. test_no_tx_annotation_moved — 移动的方法无事务注解
|
||||
8. test_behavior_snapshot — 快照一致
|
||||
|
||||
### TDD 流程
|
||||
1. 测试断言事务边界(TransactionSynchronization 观察)→ RED
|
||||
2. 重构 → GREEN
|
||||
3. `mvn test -Dtest=SimilarAsinTaskServiceTest` 通过
|
||||
|
||||
## 任务 126:similarasin DTO 组装移出写事务
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
结果回传的 DTO/VO 组装移到事务提交后(afterCompletion 或事务外);不影响落库字段。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dto_assembly_after_tx — 组装在事务后
|
||||
2. test_assembled_fields_same — 字段一致
|
||||
3. test_tx_commit_then_assembly — 先提交后组装
|
||||
4. test_rollback_no_assembly — 回滚不组装
|
||||
5. test_assembly_error_safe — 组装错误不影响事务
|
||||
6. test_response_built_ok — 响应正常构造
|
||||
7. test_assembly_no_db_read — 组装不读库
|
||||
8. test_snapshot_same — 快照一致
|
||||
|
||||
## 任务 127:similarasin 临时文件清理挂 afterCommit
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
事务完成后的临时文件清理改挂 TransactionSynchronization.afterCommit;回滚不清理(文件保留);清理异常不阻断。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_cleanup_after_commit — 提交后清理
|
||||
2. test_cleanup_no_rollback — 回滚不清理
|
||||
3. test_cleanup_error_swallowed — 异常吞掉
|
||||
4. test_cleanup_order — 在提交后
|
||||
5. test_cleanup_retryable — 失败可重试
|
||||
6. test_cleanup_tx_done — 事务状态已结束
|
||||
7. test_cleanup_idempotent — 幂等
|
||||
8. test_cleanup_integration — 全链路
|
||||
|
||||
## 任务 128:appearancepatent 事务收缩
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
同 125-127 模式(注意双事务路径:persistSubmittedChunk + completeSubmittedChunk 两段不变)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:计算移外、双事务路径不变、落库保留、回滚一致、清理时机、幂等、快照一致、集成。
|
||||
|
||||
## 任务 129:shopdatacrawl 事务收缩
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
同 125 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 125(shopdatacrawl 特有:items 分页写入路径)。
|
||||
|
||||
## 任务 130:publish 事务收缩
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
同 125 模式(publish 特有:RustFS 分片合并路径不动)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 125(publish:分片合并后落库仍在事务内)。
|
||||
|
||||
## 任务 131:collectdata 事务收缩
|
||||
|
||||
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
|
||||
|
||||
同 125 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 125。
|
||||
|
||||
## 任务 132:/result 成功确认时机不变测试
|
||||
|
||||
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
/result 返回 HTTP 200 + success=true 在结果分片可靠落库**之后**;未落库前不返回成功;事务失败返回错误。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_result_200_after_persist — 落库后 200
|
||||
2. test_result_success_true — success=true
|
||||
3. test_result_persist_fail_no_200 — 落库失败不 200
|
||||
4. test_result_timing_order — 顺序断言
|
||||
5. test_result_retry_after_failure — 失败后重试
|
||||
6. test_result_chunk_then_ack — 分片先落库
|
||||
7. test_result_ack_then_response — 响应在 ACK 后
|
||||
8. test_result_contract_frozen — 契约快照
|
||||
|
||||
## 任务 133:回滚语义不变测试
|
||||
|
||||
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
落库异常 → 完整回滚(任务状态、结果、payload 不变);纯计算无副作用;重试安全。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_rollback_full — 完整回滚
|
||||
2. test_rollback_status_unchanged — 状态不变
|
||||
3. test_rollback_payload — payload 不变
|
||||
4. test_rollback_retry — 重试安全
|
||||
5. test_rollback_compute_noop — 计算无副作用
|
||||
6. test_rollback_error_raised — 异常抛出
|
||||
7. test_rollback_partial_write — 部分写入也回滚
|
||||
8. test_rollback_consistency — 与改造前一致
|
||||
|
||||
## 任务 134:done=true 封口时机不变测试
|
||||
|
||||
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
done=true 最后一批:强制处理未满批数据、生成结果文件的时机不变;封口语义不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_done_finalizes — 封口触发
|
||||
2. test_done_after_last_chunk — 最后一批后
|
||||
3. test_done_processes_remainder — 处理剩余
|
||||
4. test_done_generates_file — 生成结果
|
||||
5. test_done_idempotent — 重复 done 安全
|
||||
6. test_done_timing — 时机断言
|
||||
7. test_done_no_double — 不重复生成
|
||||
8. test_done_contract — 契约快照
|
||||
|
||||
## 任务 135:任务状态成功时机不变测试
|
||||
|
||||
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
任务状态变 SUCCESS 的时机(结果文件生成完成判断)不变;fileReady/downloadUrl 含义不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_success_timing — 成功时机
|
||||
2. test_success_after_file — 文件生成后
|
||||
3. test_file_ready_semantics — fileReady 语义
|
||||
4. test_download_url_semantics — downloadUrl 语义
|
||||
5. test_success_no_file — 无文件不成功
|
||||
6. test_success_state_transition — 状态迁移
|
||||
7. test_success_observable — 前端可观测
|
||||
8. test_success_contract — 契约快照
|
||||
|
||||
## 任务 136:事务外清理异常不阻断
|
||||
|
||||
**所属模块**:07 事务 **依赖**:127 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
afterCommit 清理抛异常:记录日志+指标,不影响响应;不重试成循环。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_cleanup_error_logged — 日志记录
|
||||
2. test_cleanup_error_response_ok — 响应不受影响
|
||||
3. test_cleanup_error_no_retry_loop — 不循环
|
||||
4. test_cleanup_error_tx_committed — 事务已提交
|
||||
5. test_cleanup_error_metric — 指标记录
|
||||
6. test_cleanup_error_next_time — 下次仍可清理
|
||||
7. test_cleanup_error_partial — 部分清理成功
|
||||
8. test_cleanup_error_integration — 集成
|
||||
|
||||
## 任务 137:重复提交幂等测试
|
||||
|
||||
**所属模块**:07 事务 **依赖**:132-135 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
同 submissionId 重复提交 /result:幂等接受(成功返回,不重复落库);不同内容冲突拒绝。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_duplicate_same_id_ok — 同 id 幂等
|
||||
2. test_duplicate_no_double_persist — 不重复落库
|
||||
3. test_duplicate_success_true — 返回成功
|
||||
4. test_duplicate_diff_content_reject — 内容不同拒绝
|
||||
5. test_duplicate_chunk_conflict — chunk 冲突
|
||||
6. test_duplicate_after_done — 封口后重复
|
||||
7. test_duplicate_many — 多次重复
|
||||
8. test_duplicate_contract — 契约快照
|
||||
|
||||
## 任务 138:事务时长性能对比基准
|
||||
|
||||
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
改造前后 /result 事务耗时基准对比(纯计算移出后的时间下降);记录基准数据。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_tx_duration_recorded — 耗时记录
|
||||
2. test_tx_duration_before_after — 前后对比
|
||||
3. test_tx_improved_or_equal — 不劣化
|
||||
4. test_tx_measure_repeatable — 可重复
|
||||
5. test_tx_load_200_chunks — 200 分片负载
|
||||
6. test_tx_no_regression — 无回退
|
||||
7. test_tx_benchmark_documented — 基准文档
|
||||
8. test_tx_bound_reasonable — 上界合理
|
||||
|
||||
## 任务 139:07 全量回归
|
||||
|
||||
**所属模块**:07 事务 **依赖**:132-138 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
07 全部契约测试(132-135)+ 各模块事务重构测试全绿;`mvn test` 无回归。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:契约 4 项全绿、幂等全绿、回滚全绿、各模块重构测试、全量单测、package、契约快照、git diff 范围
|
||||
|
||||
### 验证方法
|
||||
`mvn test` + `mvn clean package -DskipTests`。
|
||||
@@ -0,0 +1,158 @@
|
||||
# 08-plan — 结果文件阶段字段契约固化
|
||||
|
||||
> 对应 `docs/specs/08-result-file-phase-and-download.md`。**审计结论:Java 13 模块字段已实现、前端已消费,无代码改动需求。**
|
||||
> 本 plan 将现状固化为契约测试,防止未来回归;不新增业务字段。
|
||||
> 技术栈:Java 21 + JUnit5 + Vitest(前端)。
|
||||
|
||||
## 任务 140:13 模块 file 字段契约快照测试
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
对 13 个业务模块(similarasin/appearancepatent/shopdatacrawl/queryasin/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/publish/collectdata/brand)的响应 VO 断言 file 阶段字段存在且类型正确(collectdata 除外:断言其自洽语义);旧字段(taskId/resultId/downloadUrl/status)仍在。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_similar_has_file_fields — similarasin 字段齐全
|
||||
2. test_appearance_has_file_fields
|
||||
3. test_shopdatacrawl_has_file_fields
|
||||
4. test_publish_has_file_fields — publish 文件级
|
||||
5. test_collectdata_self_consistent — collectdata 无 file 字段(现状)
|
||||
6. test_old_fields_present — 旧字段全在
|
||||
7. test_file_field_types — 类型正确(boolean/string/integer)
|
||||
8. test_contract_frozen_snapshot — JSON 快照冻结
|
||||
|
||||
### TDD 流程
|
||||
1. 测试断言 VO 字段(反射/样例对象)→ 对现状应 GREEN(基线固化)
|
||||
2. 若未来删除字段即 RED(回归保护)
|
||||
3. `mvn test -Dtest=ResultFilePhaseContractTest` 通过
|
||||
|
||||
## 任务 141:similarasin file 进度合成逻辑单测
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
attachFileProgress 三路径:Coze 阶段(cozeCompleted/pending>0)、Python 上传阶段(未完成)、snapshot 百分比(上传完成无 coze);fileReady=true 时 100%。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_coze_progress_path — Coze 路径
|
||||
2. test_python_upload_path — Python 上传路径
|
||||
3. test_snapshot_percent_path — snapshot 路径
|
||||
4. test_file_ready_100 — ready=100%
|
||||
5. test_upload_not_complete_no_snapshot — 未完成且无快照
|
||||
6. test_can_treat_completed — 可视为完成
|
||||
7. test_task_not_running_skip — 非运行中跳过
|
||||
8. test_percent_cap_99 — 未 ready 时 ≤99
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
构造 FileResultEntity/TaskFileJobEntity/TaskProgressSnapshotEntity 组合断言输出(调用包可见/测试可见的 attachFileProgress 或经 toHistoryItem)。
|
||||
|
||||
## 任务 142:fileReady/fileStatus 语义测试
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
fileReady = resultFileUrl 非空;无 job 时 fileStatus = ready?SUCCESS:null;有 job 时 fileStatus = job.status;fileError = job.errorMessage。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_ready_url_present — 有 URL ready=true
|
||||
2. test_ready_url_blank — 空 URL ready=false
|
||||
3. test_no_job_success_status — 无 job ready 时 SUCCESS
|
||||
4. test_no_job_null_status — 无 job 未 ready null
|
||||
5. test_job_status_mapped — job 状态映射
|
||||
6. test_job_error_mapped — job 错误映射
|
||||
7. test_ready_blank_whitespace — 空白字符串
|
||||
8. test_semantics_frozen — 语义快照
|
||||
|
||||
## 任务 143:publish 文件级 file 状态测试
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
publish 的 file 状态是文件级(PublishResultVo.setFileReady(ready)/setFileStatus(file.status)),与其余模块 job 级不同;语义固化。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_publish_file_ready — ready 设置
|
||||
2. test_publish_file_status — 文件状态
|
||||
3. test_publish_per_file — 按文件独立
|
||||
4. test_publish_mixed_files — 多文件混合状态
|
||||
5. test_publish_ready_all — 全 ready
|
||||
6. test_publish_no_files — 无文件
|
||||
7. test_publish_failed_file — 失败文件
|
||||
8. test_publish_semantics_frozen — 语义快照
|
||||
|
||||
## 任务 144:前端 live progress 合并测试补强
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
mergeHistoryItemPreservingLiveProgress:history 缺失 file 进度时保留 live progress;incoming 有进度时用 incoming;可下载时不保留。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_merge_keeps_live_when_history_missing — 保留 live
|
||||
2. test_merge_incoming_wins — incoming 优先
|
||||
3. test_merge_no_keep_when_downloadable — 可下载不保留
|
||||
4. test_merge_no_previous — 无 previous 返回 incoming
|
||||
5. test_merge_partial_fields — 部分字段保留
|
||||
6. test_merge_meaningful_progress — 有效进度值判断
|
||||
7. test_merge_file_ready_flag — ready 标志保留
|
||||
8. test_merge_idempotent — 幂等
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
`npx vitest run`(扩展既有测试文件或新增)。
|
||||
|
||||
## 任务 145:前端可下载判定测试
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
canDownload/fileReady/fileStatus 终态判定:fileReady=true 可下载;fileStatus=SUCCESS/FAILED 可下载(FAILED 可下载错误文件或展示错误);其余不可下载。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_can_download_ready — ready 可下载
|
||||
2. test_can_download_status_success — SUCCESS 可下载
|
||||
3. test_can_download_status_failed — FAILED 展示错误
|
||||
4. test_can_not_download_pending — PENDING 不可
|
||||
5. test_can_not_download_null — null 不可
|
||||
6. test_file_status_lowercase — 小写归一
|
||||
7. test_ready_false_status_success — 组合判断
|
||||
8. test_download_flow_no_result_resubmit — 下载失败不重提交
|
||||
|
||||
## 任务 146:collectdata 自洽行为测试
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
collectdata 前端用 success + downloadUrl 判定下载;后端不返回 file 字段;行为自洽(任务 SUCCESS 且有 URL 才可下载)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_collect_success_downloadable — SUCCESS+URL 可下载
|
||||
2. test_collect_success_no_url — 无 URL 不可
|
||||
3. test_collect_failed_no_download — 失败不可
|
||||
4. test_collect_ready_download_url — URL 有效
|
||||
5. test_collect_progress_display — 进度显示
|
||||
6. test_collect_self_consistent_backend — 后端无 file 字段
|
||||
7. test_collect_status_flow — 状态流
|
||||
8. test_collect_contract_frozen — 快照
|
||||
|
||||
## 任务 147:downloadUrl 永不过期验证
|
||||
|
||||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
generateFreshDownloadUrl 行为:result/ 前缀走 download-endpoint;非 result/ 走公开端点;无签名(URL 无过期参数);bucket 前缀正确。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_result_prefix_download_endpoint — result/ 走下载域名
|
||||
2. test_other_prefix_public — 其他走公开
|
||||
3. test_no_signed_params — 无签名参数
|
||||
4. test_bucket_in_url — bucket 包含
|
||||
5. test_blank_input_fallback — 空值回退
|
||||
6. test_uri_encoding — 路径编码
|
||||
7. test_scheme_https — https
|
||||
8. test_url_stable_over_time — 时间无关(无过期)
|
||||
|
||||
### TDD 流程 / 验证方法
|
||||
OssStorageService 单测(配置注入 mock endpoint)。
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 相关类 + `cd frontend-vue && npx vitest run` 全绿;08 spec §2/§3 清单与实际一致。
|
||||
@@ -0,0 +1,322 @@
|
||||
# 09-plan — 临时文件生命周期治理
|
||||
|
||||
> 对应 `docs/specs/09-temp-file-lifecycle.md`。第一阶段只巡检不自动删;路径安全是硬门槛。
|
||||
> 技术栈:Java 21 + Spring Scheduling + JUnit5。
|
||||
|
||||
## 任务 148:临时目录配置盘点
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
盘点 TransientStorageProperties/StorageProperties/TransientPayloadStorageService 的临时目录配置(路径、前缀、保留期、现有清理逻辑);产出配置清单文档;不改代码。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_config_listed — 配置项清单齐全
|
||||
2. test_temp_root_defined — 临时根目录定义
|
||||
3. test_retention_period — 保留期定义
|
||||
4. test_payload_prefixes — payload 前缀
|
||||
5. test_upload_dir — 上传目录
|
||||
6. test_existing_cleanup_noted — 现有清理逻辑记录
|
||||
7. test_doc_committed — 文档存在
|
||||
8. test_no_code_change — 零代码变更
|
||||
|
||||
### TDD 流程
|
||||
1. 断言清单文档存在且字段齐全 → RED
|
||||
2. 产出文档 → GREEN
|
||||
|
||||
## 任务 149:创建/访问时间记录审计与补缺
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
临时文件创建时间/大小/最后访问时间记录:现有实现缺最后访问时间则补(文件 mtime 或记录表);不改变文件语义。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_creation_time_recorded — 创建时间
|
||||
2. test_size_recorded — 大小
|
||||
3. test_access_time_readable — 访问时间可读
|
||||
4. test_access_time_fallback — mtime 回退
|
||||
5. test_record_update — 访问更新
|
||||
6. test_record_missing_grace — 缺记录容忍
|
||||
7. test_record_no_io_error — IO 错误不阻断
|
||||
8. test_record_consistency — 一致
|
||||
|
||||
## 任务 150:引用检查(清理前)
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
清理前确认无任务引用:fileKey 被 task_file_job/file_result 引用则不清理;引用判定逻辑可测试。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_referenced_kept — 被引用不清理
|
||||
2. test_unreferenced_candidate — 无引用可清理
|
||||
3. test_reference_by_job — job 引用
|
||||
4. test_reference_by_result — result 引用
|
||||
5. test_reference_unknown — 未知引用安全
|
||||
6. test_check_no_side_effect — 检查无副作用
|
||||
7. test_check_failure_keeps — 检查失败保守保留
|
||||
8. test_check_batch — 批量检查
|
||||
|
||||
## 任务 151:路径安全校验
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
删除前校验:路径规范化后 startsWith(临时根目录);穿越(../、绝对路径逃逸、符号链接)拒绝;非法路径不删除并记录。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_inside_root_ok — 根内允许
|
||||
2. test_traversal_rejected — ../ 拒绝
|
||||
3. test_absolute_escape — 绝对路径逃逸拒绝
|
||||
4. test_symlink_escape — 符号链接逃逸拒绝
|
||||
5. test_normalize_before_check — 规范化后校验
|
||||
6. test_relative_subdir — 子目录允许
|
||||
7. test_sibling_rejected — 兄弟目录拒绝
|
||||
8. test_illegal_logged — 非法路径记录
|
||||
|
||||
### TDD 流程
|
||||
1. 测试(构造各种路径)→ RED
|
||||
2. 实现校验 → GREEN
|
||||
3. `mvn test -Dtest=TransientPathGuardTest` 通过
|
||||
|
||||
## 任务 152:清理失败吞异常记指标
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:150,151 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
清理失败:记录日志+指标(清理失败计数),不抛异常、不阻断主流程;不自动重试成循环。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_failure_logged — 日志
|
||||
2. test_failure_metric — 指标
|
||||
3. test_failure_no_throw — 不抛出
|
||||
4. test_failure_flow_continues — 主流程继续
|
||||
5. test_failure_no_retry_loop — 不循环
|
||||
6. test_failure_next_round — 下轮可再试
|
||||
7. test_failure_partial — 部分失败处理
|
||||
8. test_failure_isolation — 隔离其他文件
|
||||
|
||||
## 任务 153:fileKey 兜底查找
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
进程重启后 fileKey 兜底:上传记录持久化或重启后按 fileKey 重建索引;找不到时明确失败而非静默。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_file_key_found — 找到
|
||||
2. test_file_key_after_restart — 重启后找到
|
||||
3. test_file_key_missing — 缺失明确失败
|
||||
4. test_file_key_null — null 安全
|
||||
5. test_file_key_cleanup — 清理后不可找
|
||||
6. test_file_key_record_persist — 记录持久化
|
||||
7. test_file_key_rebuild — 索引重建
|
||||
8. test_file_key_semantics_frozen — 语义不变
|
||||
|
||||
## 任务 154:磁盘容量告警
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:152 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
临时目录容量超阈值:记录告警日志(当前容量/阈值);无监控栈时仅日志输出;不阻塞业务。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_warning_threshold — 阈值判断
|
||||
2. test_warning_logged — 告警日志
|
||||
3. test_under_threshold_silent — 未超不告警
|
||||
4. test_warning_repeat_limited — 告警频率限制
|
||||
5. test_usage_measured — 容量测量
|
||||
6. test_usage_zero — 空目录
|
||||
7. test_measure_error_grace — 测量失败容忍
|
||||
8. test_warning_no_block — 不阻塞
|
||||
|
||||
## 任务 155:孤立文件巡检报表
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:临时目录中无任何引用/超过保留期的文件清单输出到报表(日志或报表文件);不删除。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_orphan_detected — 孤立文件检出
|
||||
2. test_referenced_not_reported — 被引用不报
|
||||
3. test_report_output — 报表输出
|
||||
4. test_read_only_no_delete — 只读不删
|
||||
5. test_report_batch — 批量
|
||||
6. test_report_empty — 无孤立空报表
|
||||
7. test_report_rerun_safe — 可重复
|
||||
8. test_report_details — 详情(路径/大小/时间)
|
||||
|
||||
## 任务 156:孤立 Job 巡检报表
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:task_file_job 无对应 task/result 的孤儿 Job 清单;输出报表;不修改状态。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_orphan_job_detected — 检出
|
||||
2. test_valid_job_not_reported — 正常不报
|
||||
3. test_report_output — 输出
|
||||
4. test_read_only — 不修改
|
||||
5. test_job_retry_orphan — 重试耗尽孤儿
|
||||
6. test_report_empty — 空
|
||||
7. test_report_details — 详情
|
||||
8. test_rerun_safe — 可重复
|
||||
|
||||
## 任务 157:任务存在结果缺失巡检
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:任务存在但结果缺失(SUCCESS 任务无 file_result)清单。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_missing_result_detected — 检出
|
||||
2. test_with_result_not_reported — 有结果不报
|
||||
3. test_success_no_result — SUCCESS 无结果
|
||||
4. test_running_ignored — 运行中忽略
|
||||
5. test_report_empty
|
||||
6. test_read_only
|
||||
7. test_details
|
||||
8. test_rerun_safe
|
||||
|
||||
## 任务 158:结果存在文件缺失巡检
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:file_result 的 resultFileUrl 对应文件在 OSS/本地不存在清单。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_file_missing_detected
|
||||
2. test_file_exists_ok
|
||||
3. test_blank_url_handled — 空 URL
|
||||
4. test_oss_check — OSS 校验(mock)
|
||||
5. test_report_empty
|
||||
6. test_read_only
|
||||
7. test_details
|
||||
8. test_rerun_safe
|
||||
|
||||
## 任务 159:已完成任务活跃 Job 巡检
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:任务已终态(SUCCESS/FAILED)但仍有活跃(RUNNING/PENDING)Job 清单。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_active_job_after_terminal — 检出
|
||||
2. test_terminal_no_job_ok
|
||||
3. test_job_active_task_running_ok — 运行中任务正常
|
||||
4. test_stuck_job_reported — 卡死 Job
|
||||
5. test_report_empty
|
||||
6. test_read_only
|
||||
7. test_details
|
||||
8. test_rerun_safe
|
||||
|
||||
## 任务 160:超保留期仍被引用巡检
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读巡检:临时文件超保留期但仍有引用清单(供人工处理)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_over_retention_referenced — 检出
|
||||
2. test_in_retention_ok
|
||||
3. test_over_retention_unreferenced — 无引用(另表)
|
||||
4. test_boundary_retention — 边界时间
|
||||
5. test_report_empty
|
||||
6. test_read_only
|
||||
7. test_details
|
||||
8. test_rerun_safe
|
||||
|
||||
## 任务 161:巡检任务开关(默认 disabled)
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:155-160 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
全部巡检任务由配置开关控制(默认 disabled);启用后按调度间隔执行;双实例不重复输出(owner 或随机)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_disabled_by_default — 默认关
|
||||
2. test_enabled_runs — 启用执行
|
||||
3. test_schedule_interval — 间隔配置
|
||||
4. test_dual_instance_no_dup — 双实例不重复
|
||||
5. test_run_error_grace — 异常不阻断
|
||||
6. test_each_report_independent — 各报表独立
|
||||
7. test_config_override — 覆盖生效
|
||||
8. test_enabled_no_crash — 启用稳定
|
||||
|
||||
## 任务 162:路径穿越测试
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:151 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
穿越输入矩阵:`../`、`..\\`、绝对路径、URL 编码 `%2e%2e`、Unicode 全角点、混合分隔符——全部拒绝。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dotdot_slash — ../
|
||||
2. test_dotdot_backslash — ..\
|
||||
3. test_encoded_dotdot — %2e%2e
|
||||
4. test_fullwidth_dot — 全角点
|
||||
5. test_abs_win_path — C:\ 形式
|
||||
6. test_abs_unix_path — /etc 形式
|
||||
7. test_mixed_separator — 混合分隔符
|
||||
8. test_null_byte — 空字节
|
||||
|
||||
## 任务 163:引用中文件不清测试
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
被 job/result 引用的文件:清理流程跳过;仅未引用文件被清理(清理流程本身在后续批次实现时,本任务先固化引用检查)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_job_referenced_skip — job 引用跳过
|
||||
2. test_result_referenced_skip — result 引用跳过
|
||||
3. test_unreferenced_passes — 未引用通过
|
||||
4. test_multi_reference — 多引用
|
||||
5. test_check_after_delete_history — 删历史后解除引用
|
||||
6. test_check_batch_mixed — 混合批次
|
||||
7. test_check_null_safe
|
||||
8. test_check_idempotent
|
||||
|
||||
## 任务 164:清理失败不阻断测试
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:152 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
清理一个文件失败不影响其他文件清理;主业务不受影响;错误可见(日志/指标)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_one_fail_others_succeed — 单失败其余成功
|
||||
2. test_failure_visible — 错误可见
|
||||
3. test_no_throw_up — 不上抛
|
||||
4. test_retry_next_round — 下轮重试
|
||||
5. test_partial_result_reported — 部分结果报告
|
||||
6. test_metric_recorded — 指标
|
||||
7. test_flow_continues — 流程继续
|
||||
8. test_no_cascading — 无级联
|
||||
|
||||
## 任务 165:巡检只读测试
|
||||
|
||||
**所属模块**:09 临时文件 **依赖**:155-161 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
全部巡检运行后:零删除、零状态修改、零写库(只读);可重复执行。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_no_delete — 零删除
|
||||
2. test_no_state_change — 状态不变
|
||||
3. test_no_db_write — 无写库
|
||||
4. test_read_repeatable — 重复一致
|
||||
5. test_isolated_reports — 报表隔离
|
||||
6. test_read_only_assert — 只读断言
|
||||
7. test_no_side_effects — 无副作用
|
||||
8. test_full_suite_run — 全巡检套件
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 相关类全绿;09 spec §4 不变要求逐项核对(fileKey 语义、上传协议不变)。
|
||||
@@ -0,0 +1,184 @@
|
||||
# 10-plan — 外部 HTTP 客户端配置治理
|
||||
|
||||
> 对应 `docs/specs/10-http-client-governance.md`。现状:HttpClientPool 已统一(Coze/品牌/紫鸟共用连接池)。
|
||||
> 技术栈:Java 21 + JDK HttpClient + RestClient。
|
||||
|
||||
## 任务 166:各客户端契约表盘点
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
盘点 Coze/OSS/RustFS/图片下载/紫鸟各客户端现状:connect/read/write/call timeout、重试、幂等性;产出契约表文档;标注 JDK HttpClient 平台限制(无独立 write timeout、连接池上限不可配置);不改代码。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_contract_table_all_clients — 全客户端
|
||||
2. test_timeouts_listed — 超时现状
|
||||
3. test_retry_listed — 重试现状
|
||||
4. test_idempotency_listed — 幂等性
|
||||
5. test_jdk_limits_noted — 平台限制
|
||||
6. test_doc_committed — 文档存在
|
||||
7. test_no_code_change — 零代码
|
||||
8. test_repeatable — 可复查
|
||||
|
||||
### TDD 流程
|
||||
1. 断言文档存在 → RED
|
||||
2. 产出契约表 → GREEN
|
||||
|
||||
## 任务 167:aiimage.http-client.* 配置命名空间
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:166 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
application.yml 新增 `aiimage.http-client.*` 命名空间(connect-timeout/read-timeout/call-timeout/retry 默认值);默认值与现状一致;配置类绑定校验。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_config_namespace_exists — 命名空间
|
||||
2. test_defaults_match_current — 默认一致
|
||||
3. test_connect_timeout_bound — 合法值
|
||||
4. test_read_timeout_bound
|
||||
5. test_retry_count_bound
|
||||
6. test_invalid_values_clamped — 非法钳制
|
||||
7. test_config_class_binding — 绑定类
|
||||
8. test_env_override — env 覆盖
|
||||
|
||||
## 任务 168:Coze 客户端配置接入
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
Coze 客户端从配置读取超时/重试(现为硬编码或独立配置);行为不变(默认值等同现状)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_coze_timeout_from_config — 配置生效
|
||||
2. test_coze_default_kept — 默认不变
|
||||
3. test_coze_override — 覆盖
|
||||
4. test_coze_call_timeout — 总时长
|
||||
5. test_coze_retry_config — 重试配置
|
||||
6. test_coze_pool_shared — 共用连接池
|
||||
7. test_coze_idempotent_post — 幂等标注
|
||||
8. test_coze_behavior_same — 行为一致
|
||||
|
||||
## 任务 169:品牌检查客户端配置接入
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||||
|
||||
同 168 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 168(品牌检查)。
|
||||
|
||||
## 任务 170:紫鸟客户端配置接入
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||||
|
||||
同 168 模式。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 168(紫鸟)。
|
||||
|
||||
## 任务 171:图片下载客户端配置接入
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||||
|
||||
同 168 模式(图片下载特有:大响应流式读取)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:配置生效、默认、覆盖、call timeout、重试、池共享、幂等、流式读取。
|
||||
|
||||
## 任务 172:幂等重试守卫
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
统一重试守卫:仅幂等请求(GET/HEAD)自动重试;非幂等(POST/PUT)不自动重试;重试次数与退避从配置;防重试风暴。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_get_retried — GET 重试
|
||||
2. test_post_not_retried — POST 不重试
|
||||
3. test_retry_count_limited — 次数限制
|
||||
4. test_retry_backoff — 退避
|
||||
5. test_idempotent_header_override — 显式幂等标记
|
||||
6. test_retry_success_after_fail — 重试成功
|
||||
7. test_retry_exhausted_fail — 耗尽失败
|
||||
8. test_no_retry_storm — 不风暴
|
||||
|
||||
## 任务 173:超时生效测试
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
mock 慢端点(>read timeout):请求在超时内失败;connect timeout 生效;call timeout 生效(RestClient 层)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_read_timeout_fires — 读超时
|
||||
2. test_read_timeout_duration — 时长断言
|
||||
3. test_connect_timeout_fires — 连接超时
|
||||
4. test_connect_timeout_duration
|
||||
5. test_call_timeout_fires — 总时长
|
||||
6. test_fast_response_ok — 快响应正常
|
||||
7. test_timeout_error_type — 错误类型
|
||||
8. test_timeout_after_config — 配置生效
|
||||
|
||||
## 任务 174:连接复用测试
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
连续 N 请求复用底层连接(共享 HttpClient);不同客户端共用连接池;连接不复用时暴露。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_connection_reused — 复用
|
||||
2. test_shared_across_clients — 跨客户端共用
|
||||
3. test_sequential_requests — 顺序复用
|
||||
4. test_keep_alive_header — keep-alive
|
||||
5. test_no_new_connection_burst — 突发不建新连
|
||||
6. test_pool_singleton — 单例
|
||||
7. test_concurrent_reuse — 并发复用
|
||||
8. test_connection_stats — 连接统计
|
||||
|
||||
## 任务 175:Python 回调超时不变确认
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
只读确认:Java 侧外部客户端改动不影响 Python 回调请求的超时与重试约定(Python 侧 requests 调用不动);写断言测试固化 Python 回调契约不受 Java 配置影响。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_python_callback_contract — 回调契约
|
||||
2. test_no_java_config_affects_python — 不受影响
|
||||
3. test_python_timeout_doc — 文档一致
|
||||
4. test_python_retry_doc
|
||||
5. test_python_headers — 头一致
|
||||
6. test_python_success_detection — 成功判定
|
||||
7. test_python_contract_frozen — 快照
|
||||
8. test_no_code_change_python — Python 零改动
|
||||
|
||||
## 任务 176:重试计数与日志字段
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:172 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
重试时记录日志(客户端/URL/尝试次数/耗时);重试计数指标;不记录敏感信息。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_retry_logged — 日志
|
||||
2. test_retry_attempt_field — 尝试次数
|
||||
3. test_retry_duration — 耗时
|
||||
4. test_retry_metric — 指标
|
||||
5. test_no_token_in_log — 无敏感信息
|
||||
6. test_success_no_retry_log — 成功不记
|
||||
7. test_log_level — 日志级别
|
||||
8. test_final_failure_logged — 最终失败
|
||||
|
||||
## 任务 177:10 全量回归
|
||||
|
||||
**所属模块**:10 HTTP 客户端 **依赖**:168-176 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
全部客户端配置改造后:现有测试全绿;外部服务 mock 集成测试通过;行为与默认配置下现状一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:各客户端测试绿、HttpClientPool 既有测试绿、配置绑定测试、超时测试、复用测试、幂等守卫、日志脱敏、全量单测
|
||||
|
||||
### 验证方法
|
||||
`mvn test` 全量 + `mvn clean package -DskipTests`。
|
||||
@@ -0,0 +1,245 @@
|
||||
# 11-plan — 可观测性:指标定义与日志字段规范
|
||||
|
||||
> 对应 `docs/specs/11-observability.md`。决策:指标名与日志字段规范先行落地;不引入新监控组件(Micrometer 若已依赖则用,未依赖则手动计数器+日志)。
|
||||
> 技术栈:Java 21 + Slf4j +(可选 Micrometer)。
|
||||
|
||||
## 任务 178:日志字段规范落地
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
业务日志统一携带结构化字段:traceId/taskId/moduleType/stage/submissionId/chunkIndex/chunkTotal/jobId/result/errorType;缺失字段用占位;不删现有日志。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_worker_log_has_task_id — Worker 日志含 taskId
|
||||
2. test_worker_log_has_module_type
|
||||
3. test_worker_log_has_stage
|
||||
4. test_result_log_fields — /result 日志字段
|
||||
5. test_heartbeat_log_fields
|
||||
6. test_missing_field_placeholder — 缺字段占位
|
||||
7. test_log_field_names_frozen — 字段名快照
|
||||
8. test_no_log_content_break — 日志内容不破坏
|
||||
|
||||
## 任务 179:禁止记录清单审计
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:178 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
审计日志代码:Token/Cookie/完整请求体/文件二进制/用户凭据/敏感 API Key 不入日志;发现问题修正。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_no_token_logged — 无 Token
|
||||
2. test_no_cookie_logged — 无 Cookie
|
||||
3. test_no_full_body_logged — 无完整 body
|
||||
4. test_no_binary_logged — 无二进制
|
||||
5. test_no_credential_logged — 无凭据
|
||||
6. test_no_api_key_logged — 无 API Key
|
||||
7. test_allowed_fields_kept — 允许字段保留
|
||||
8. test_audit_script — 审计脚本可重复
|
||||
|
||||
## 任务 180:Worker 日志字段对齐
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
TaskResultFileJobWorker(04 改造后)日志字段与规范对齐:jobId/taskId/moduleType/stage/errorType;现有 [task-file-job] 前缀保留。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_dispatch_log_fields — dispatch 日志
|
||||
2. test_success_log_fields
|
||||
3. test_failure_log_fields
|
||||
4. test_retry_log_fields
|
||||
5. test_heartbeat_log_fields
|
||||
6. test_stuck_log_fields
|
||||
7. test_field_names_consistent — 与规范一致
|
||||
8. test_no_sensitive — 无敏感
|
||||
|
||||
## 任务 181:task.created/running 指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
任务创建(created 计数)与运行中(running gauge)指标;带 moduleType/instanceId 标签;无监控栈时输出日志记录。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_created_incremented — 创建计数
|
||||
2. test_running_gauge — 运行 gauge
|
||||
3. test_module_label — 标签
|
||||
4. test_instance_label — instanceId 标签
|
||||
5. test_created_module_specific — 分模块
|
||||
6. test_counter_persistent — 计数正确性
|
||||
7. test_gauge_update — 更新
|
||||
8. test_metric_name_frozen — 名称快照
|
||||
|
||||
## 任务 182:task.success/failed/cancelled 指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:181 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
终态计数:success/failed/cancelled 各模块独立计数;与状态迁移一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_success_counted
|
||||
2. test_failed_counted
|
||||
3. test_cancelled_counted
|
||||
4. test_module_split — 分模块
|
||||
5. test_no_double_count — 不重复计
|
||||
6. test_terminal_once — 只计一次
|
||||
7. test_failed_then_success — 状态反转不重计
|
||||
8. test_names_frozen
|
||||
|
||||
## 任务 183:task.duration 指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:182 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
任务耗时(开始→终态)记录;直方图或耗时日志;分模块。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_duration_recorded — 记录
|
||||
2. test_duration_positive — 正值
|
||||
3. test_module_split
|
||||
4. test_short_task — 短任务
|
||||
5. test_long_task — 长任务
|
||||
6. test_duration_bound — 上界
|
||||
7. test_duration_zero_guard — 零保护
|
||||
8. test_name_frozen
|
||||
|
||||
## 任务 184:task.heartbeat.age 指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
心跳年龄 gauge:任务最后心跳距今时间;超阈值可观测(日志告警)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_age_computed — 年龄计算
|
||||
2. test_age_fresh — 新鲜
|
||||
3. test_age_stale — 陈旧
|
||||
4. test_age_threshold_warn — 阈值告警
|
||||
5. test_no_heartbeat — 无心跳处理
|
||||
6. test_age_zero — 刚心跳
|
||||
7. test_age_clock_negative — 时钟负保护
|
||||
8. test_name_frozen
|
||||
|
||||
## 任务 185:file-job.* 指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
TaskFileJobWorker 指标:pending/running/success/failed/duration/retry;分 moduleType/instanceId。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_pending_counted
|
||||
2. test_running_counted
|
||||
3. test_success_counted
|
||||
4. test_failed_counted
|
||||
5. test_duration_recorded
|
||||
6. test_retry_counted
|
||||
7. test_module_instance_labels
|
||||
8. test_names_frozen
|
||||
|
||||
## 任务 186:上传耗时/大小指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
文件上传:耗时、大小、成功率指标;分 moduleType。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_upload_duration
|
||||
2. test_upload_size
|
||||
3. test_upload_success_rate
|
||||
4. test_module_split
|
||||
5. test_upload_failed
|
||||
6. test_upload_large
|
||||
7. test_size_bound
|
||||
8. test_names_frozen
|
||||
|
||||
## 任务 187:临时磁盘指标埋点
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:154 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
临时磁盘容量/占用指标;与 09 告警联动。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_disk_usage_measured
|
||||
2. test_disk_capacity
|
||||
3. test_usage_percent
|
||||
4. test_threshold_warn
|
||||
5. test_empty_dir
|
||||
6. test_measure_failure_grace
|
||||
7. test_name_frozen
|
||||
8. test_no_block
|
||||
|
||||
## 任务 188:指标标签规范
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:181-187 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
统一标签:moduleType/instanceId 必带;标签值规范化(null→unknown);不记录用户级数据。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_module_label_all_metrics — 全指标带
|
||||
2. test_instance_label_all
|
||||
3. test_null_module_unknown — null 归一
|
||||
4. test_no_user_label — 无用户级
|
||||
5. test_label_consistent — 命名一致
|
||||
6. test_label_value_clean — 值清洗
|
||||
7. test_cardinality_bounded — 基数有界
|
||||
8. test_spec_frozen — 规范冻结
|
||||
|
||||
## 任务 189:指标命名一致性测试
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:188 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
全部指标名与 11 spec §1 标准名一致(aiimage.* 前缀);无拼写漂移。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_prefix_aiimage — 前缀
|
||||
2. test_task_metric_names — 任务族
|
||||
3. test_file_job_metric_names — 文件族
|
||||
4. test_no_typo_drift — 无拼写漂移
|
||||
5. test_snapshot_all_metrics — 全指标快照
|
||||
6. test_new_metric_must_register — 新指标注册
|
||||
7. test_metric_doc_sync — 文档同步
|
||||
8. test_case_consistent — 大小写一致
|
||||
|
||||
## 任务 190:日志脱敏测试
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:179 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
敏感值(Token/Key/凭据)即使传入日志调用点也被脱敏(占位符);断言日志输出无原文。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_token_masked
|
||||
2. test_api_key_masked
|
||||
3. test_password_masked
|
||||
4. test_cookie_masked
|
||||
5. test_partial_token_masked — 部分值
|
||||
6. test_url_query_masked — URL 查询参数
|
||||
7. test_masking_consistent — 一致
|
||||
8. test_normal_fields_kept — 正常字段保留
|
||||
|
||||
## 任务 191:双实例指标区分回归
|
||||
|
||||
**所属模块**:11 可观测性 **依赖**:188-190 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
双实例部署:instanceId 标签区分 server-110/server-121;指标不串;日志含实例标识。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_instance_110_label
|
||||
2. test_instance_121_label
|
||||
3. test_no_cross_instance — 不串
|
||||
4. test_instance_unknown — 未配置
|
||||
5. test_log_has_instance — 日志实例
|
||||
6. test_metric_aggregation_ok — 聚合可用
|
||||
7. test_label_stable — 标签稳定
|
||||
8. test_snapshot_frozen
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 相关类全绿;11 spec §2 禁止记录清单逐项对照。
|
||||
@@ -0,0 +1,137 @@
|
||||
# 12-plan — Flyway 迁移规范与只读巡检
|
||||
|
||||
> 对应 `docs/specs/12-flyway-and-inspection.md`。只追加不改历史;巡检默认关闭。
|
||||
> 技术栈:Java 21 + Flyway + SQL。
|
||||
|
||||
## 任务 192:迁移规范模板
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
`docs/` 产出迁移规范模板:变更目的/影响表和数据量/锁表风险/验证 SQL/回滚步骤/上线窗口六项必填;新迁移文件头注释引用模板。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_template_exists — 模板存在
|
||||
2. test_six_fields — 六字段齐全
|
||||
3. test_template_has_example — 示例
|
||||
4. test_rollback_steps — 回滚步骤
|
||||
5. test_validation_sql — 验证 SQL 示例
|
||||
6. test_window_field — 上线窗口
|
||||
7. test_doc_committed
|
||||
8. test_template_usable — 可复制使用
|
||||
|
||||
## 任务 193:历史迁移盘点
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
盘点 db/ 下 V87+ 迁移:编号连续性、无修改历史(git 不动)、生产已执行版本核对;产出盘点报表。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_version_sequential — 编号连续
|
||||
2. test_no_legacy_modified — 历史未改
|
||||
3. test_latest_version_noted — 最新版本记录
|
||||
4. test_duplicate_version — 无重复编号
|
||||
5. test_migration_single_purpose — 单迁移单目的(抽查)
|
||||
6. test_report_committed
|
||||
7. test_checksum_stable — 校验和稳定
|
||||
8. test_repeatable
|
||||
|
||||
## 任务 194:orphan Job 巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
巡检 SQL:task_file_job 无对应 task/result;SQL 只读;输出孤儿清单。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_sql_syntax_valid — 语法有效
|
||||
2. test_sql_read_only — 只读(SELECT)
|
||||
3. test_orphan_detected — 检出
|
||||
4. test_valid_excluded — 正常排除
|
||||
5. test_join_condition — 关联条件
|
||||
6. test_no_side_effect — 无副作用
|
||||
7. test_empty_result_ok — 空结果
|
||||
8. test_documented — 文档
|
||||
|
||||
## 任务 195:orphan payload 巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 194 模式(payload 无对应任务)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 194(payload 表)。
|
||||
|
||||
## 任务 196:任务存在结果缺失巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 194 模式(SUCCESS 任务无结果)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 194。
|
||||
|
||||
## 任务 197:结果存在文件缺失巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 194 模式(resultFileUrl 对应对象不存在——SQL 先出清单,对象检查在 09/158 配合)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 194。
|
||||
|
||||
## 任务 198:已完成任务活跃 Job 巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 194 模式(终态任务仍有活跃 job)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 194。
|
||||
|
||||
## 任务 199:超保留期引用巡检 SQL
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
同 194 模式(临时文件超保留期仍有引用)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
同 194。
|
||||
|
||||
## 任务 200:巡检报表任务落地
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:194-199 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
巡检定时任务:执行 6 张报表 SQL;默认 disabled;启用后输出报表日志;失败不阻断。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_disabled_default
|
||||
2. test_enabled_runs_all — 6 报表全跑
|
||||
3. test_report_output
|
||||
4. test_failure_grace
|
||||
5. test_schedule_config
|
||||
6. test_no_delete
|
||||
7. test_dual_instance
|
||||
8. test_enabled_stable
|
||||
|
||||
## 任务 201:迁移演练
|
||||
|
||||
**所属模块**:12 Flyway **依赖**:192 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
副本库演练:flyway migrate 干净执行;验证 SQL 通过;锁表风险评估(索引类迁移在表大小场景);回滚步骤验证。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_migrate_clean — 干净迁移
|
||||
2. test_validate_sql_pass — 验证 SQL
|
||||
3. test_rollback_script — 回滚
|
||||
4. test_lock_window_estimated — 锁窗口
|
||||
5. test_checksum_ok
|
||||
6. test_idempotent_rerun
|
||||
7. test_no_legacy_touch — 不动历史
|
||||
8. test_documented
|
||||
|
||||
### 收尾验证(本模块)
|
||||
`mvn test` 相关类 + 巡检 SQL 在副本库执行通过。
|
||||
@@ -0,0 +1,315 @@
|
||||
# 13-plan — 契约测试与模块边界治理
|
||||
|
||||
> 对应 `docs/specs/13-contract-tests-and-boundaries.md`。契约测试与代码同 PR 提交;CI 追加测试阶段。
|
||||
> 技术栈:Java 21 + JUnit5 + ArchUnit + Vitest(前端)。
|
||||
|
||||
## 任务 202:Python-contract 夹具准备
|
||||
|
||||
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
录制 app_client/amazon 实际调用(/result、/items、parsed-payload、heartbeat)的真实请求报文,脱敏后入测试资源(JSON 夹具);夹具文件结构明确。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_fixture_result_exists — result 夹具
|
||||
2. test_fixture_items_exists — items 夹具
|
||||
3. test_fixture_parsed_payload — parsed-payload 夹具
|
||||
4. test_fixture_heartbeat — heartbeat 夹具
|
||||
5. test_fixture_sanitized — 脱敏(无真实凭据)
|
||||
6. test_fixture_shape_valid — 结构有效
|
||||
7. test_fixture_fields_documented — 字段说明
|
||||
8. test_fixture_reproducible — 可复录
|
||||
|
||||
## 任务 203:/result 幂等契约测试
|
||||
|
||||
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
同 submissionId 重复提交 /result:HTTP 200 + success=true;只落一次;chunkIndex/chunkTotal 语义;done=true 封口。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_result_success_contract — 200+true
|
||||
2. test_result_duplicate_idempotent — 幂等
|
||||
3. test_result_single_persist — 单次落库
|
||||
4. test_result_chunk_fields — 分片字段
|
||||
5. test_result_done_contract — 封口
|
||||
6. test_result_error_contract — 失败语义
|
||||
7. test_result_unknown_task — 未知任务
|
||||
8. test_result_fixture_replay — 夹具回放
|
||||
|
||||
## 任务 204:/items 分页语义契约测试
|
||||
|
||||
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
collectdata/publish 的 items 接口:分页参数(page/pageSize)、排序、字段结构、缺省行为与 Python Worker 拉取约定一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_items_pagination — 分页
|
||||
2. test_items_defaults — 默认值
|
||||
3. test_items_field_shape — 字段结构
|
||||
4. test_items_page_bounds — 越界处理
|
||||
5. test_items_order — 排序
|
||||
6. test_items_empty — 空页
|
||||
7. test_items_worker_order — Worker 顺序
|
||||
8. test_items_fixture_replay
|
||||
|
||||
## 任务 205:parsed-payload 契约测试
|
||||
|
||||
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
similarasin/appearancepatent 的 parsed-payload:字段结构、分页语义、submissionId 关联与 Python 读取约定一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_parsed_payload_shape
|
||||
2. test_parsed_payload_pagination
|
||||
3. test_parsed_payload_submission
|
||||
4. test_parsed_payload_empty
|
||||
5. test_parsed_payload_unknown_task
|
||||
6. test_parsed_payload_fixture_replay
|
||||
7. test_parsed_payload_status
|
||||
8. test_parsed_payload_frozen
|
||||
|
||||
## 任务 206:heartbeat 旧字段契约测试
|
||||
|
||||
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
heartbeat 接口:路径、请求/响应字段与 Python Worker 约定一致;缺字段/多余字段处理。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_heartbeat_path
|
||||
2. test_heartbeat_fields
|
||||
3. test_heartbeat_unknown_task
|
||||
4. test_heartbeat_missing_optional
|
||||
5. test_heartbeat_extra_field_tolerant — 多余字段容忍
|
||||
6. test_heartbeat_fixture_replay
|
||||
7. test_heartbeat_success
|
||||
8. test_heartbeat_frozen
|
||||
|
||||
## 任务 207:done=true 最后一批契约测试
|
||||
|
||||
**所属模块**:13 契约 **依赖**:203 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
done=true 最后一批:强制处理剩余数据、生成结果文件、任务终态;协议与 Python 端一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_done_force_process
|
||||
2. test_done_finalize_task
|
||||
3. test_done_generate_file
|
||||
4. test_done_after_partial_chunks
|
||||
5. test_done_no_pending — 无剩余
|
||||
6. test_done_repeat
|
||||
7. test_done_fixture_replay
|
||||
8. test_done_frozen
|
||||
|
||||
## 任务 208:JavaApiResponse 包装契约测试(前端)
|
||||
|
||||
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
前端契约:JavaApiResponse 结构(success/message/data);LegacyApiSuccess(msg)兼容;解包行为(复用 01 callJava 测试)固化。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_java_response_success_shape
|
||||
2. test_java_response_failure_shape
|
||||
3. test_legacy_success_shape
|
||||
4. test_unwrap_success
|
||||
5. test_unwrap_failure_throws
|
||||
6. test_null_data_shape
|
||||
7. test_extra_fields_tolerant
|
||||
8. test_snapshot_frozen
|
||||
|
||||
## 任务 209:字段兼容 schema 覆盖
|
||||
|
||||
**所属模块**:13 契约 **依赖**:208 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
核心字段 schema:user_id/task_ids(请求)、taskId/resultId/fileKey/status/taskStatus/fileStatus(响应);api-field-compat 检查接入。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_request_user_id_schema
|
||||
2. test_request_task_ids_schema
|
||||
3. test_response_task_id_schema
|
||||
4. test_response_result_id_schema
|
||||
5. test_response_file_key_schema
|
||||
6. test_response_status_schema
|
||||
7. test_compat_checker_integrated
|
||||
8. test_schema_frozen
|
||||
|
||||
## 任务 210:ArchUnit 依赖方向规则
|
||||
|
||||
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
ArchUnit 规则:Controller→Service→Mapper 单向;Controller 不依赖外部 Client 细节;task 模块规则见 212;规则测试可运行。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_controller_depends_service — 允许方向
|
||||
2. test_service_depends_mapper — 允许
|
||||
3. test_controller_to_mapper_forbidden — 禁止
|
||||
4. test_no_cycle — 无环
|
||||
5. test_rule_scope_modules — 作用域
|
||||
6. test_rule_verbose — 失败信息
|
||||
7. test_all_controllers_covered — 覆盖
|
||||
8. test_rule_stable — 稳定
|
||||
|
||||
## 任务 211:ArchUnit Controller 不访问 Mapper
|
||||
|
||||
**所属模块**:13 契约 **依赖**:210 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
强化规则:任何 Controller 不得注入/调用 Mapper;违例失败。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_no_mapper_in_controller
|
||||
2. test_violation_detected — 违例检出
|
||||
3. test_message_clear
|
||||
4. test_controller_service_ok — 允许路径
|
||||
5. test_all_controllers_covered
|
||||
6. test_no_mapper_field
|
||||
7. test_rule_in_ci
|
||||
8. test_snapshot_frozen
|
||||
|
||||
## 任务 212:ArchUnit task 模块不依赖业务模块
|
||||
|
||||
**所属模块**:13 契约 **依赖**:210 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
公共 task 模块不得 import 业务模块(similarasin/appearancepatent/...);04 的 Handler SPI 已反转依赖;规则检查通过。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_task_no_business_dep — 无业务依赖
|
||||
2. test_spi_interface_allowed — SPI 接口豁免
|
||||
3. test_violation_detected
|
||||
4. test_message_clear
|
||||
5. test_04_registry_ok — 注册表符合
|
||||
6. test_all_task_classes_covered
|
||||
7. test_rule_in_ci
|
||||
8. test_snapshot_frozen
|
||||
|
||||
## 任务 213:前端共享层导出白名单
|
||||
|
||||
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
TS 检查:页面(pages/*)禁止直接 import shared/api/http.ts 或拼 URL;只允许 import java-modules.ts 的 API 函数与 bridges;违例编译失败(lint 规则或类型守卫)。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_page_no_http_direct — 页面不直连 http
|
||||
2. test_page_no_url_concat — 不拼 URL
|
||||
3. test_page_uses_api_module — 用 API 层
|
||||
4. test_shared_internal_allowed — shared 内部允许
|
||||
5. test_bridge_allowed — bridge 允许
|
||||
6. test_violation_detected
|
||||
7. test_check_runs_in_ci
|
||||
8. test_allowlist_frozen
|
||||
|
||||
## 任务 214:progress/batch 轻量响应契约
|
||||
|
||||
**所属模块**:13 契约 **依赖**:109 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
progress/batch 契约:items/missingTaskIds 结构;task 轻量字段;file 字段(除 collectdata);前端解析一致。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_progress_batch_shape
|
||||
2. test_missing_ids_shape
|
||||
3. test_task_light_fields
|
||||
4. test_file_fields_included
|
||||
5. test_collectdata_exception — 例外模块
|
||||
6. test_frontend_parse_compat
|
||||
7. test_snapshot_frozen
|
||||
8. test_light_vs_batch_consistency
|
||||
|
||||
## 任务 215:下载 URL 格式契约
|
||||
|
||||
**所属模块**:13 契约 **依赖**:147 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
downloadUrl 契约:公开直链格式(https、bucket 包含、result/ 前缀下载域名);无签名;前端 save_file 流程兼容。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_download_url_https
|
||||
2. test_download_url_bucket
|
||||
3. test_result_prefix_endpoint
|
||||
4. test_no_signature
|
||||
5. test_frontend_save_compat
|
||||
6. test_blank_handling
|
||||
7. test_contract_frozen
|
||||
8. test_download_flow_end2end
|
||||
|
||||
## 任务 216:CI 接入测试阶段
|
||||
|
||||
**所属模块**:13 契约 **依赖**:210-215 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
.gitea/workflows/build.yml 追加:mvn test(契约+ArchUnit)、前端 vitest、契约快照比对;失败即红。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_ci_has_test_stage — 测试阶段
|
||||
2. test_ci_java_tests — Java 测试命令
|
||||
3. test_ci_frontend_tests — 前端测试
|
||||
4. test_ci_snapshot_check
|
||||
5. test_ci_fail_fast — 失败即红
|
||||
6. test_ci_cache
|
||||
7. test_ci_timeout
|
||||
8. test_ci_documented
|
||||
|
||||
## 任务 217:快照对比工具
|
||||
|
||||
**所属模块**:13 契约 **依赖**:90 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
Service 拆分前后响应一致工具:录制(输入→输出)golden;对比(输出 diff);供 05 各模块使用。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_tool_records
|
||||
2. test_tool_compares_equal
|
||||
3. test_tool_diff_detected
|
||||
4. test_tool_output_report
|
||||
5. test_tool_reusable
|
||||
6. test_tool_commits_golden
|
||||
7. test_tool_clear_error
|
||||
8. test_tool_documented
|
||||
|
||||
## 任务 218:结果文件格式契约
|
||||
|
||||
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
结果文件格式契约:文件名(*-result.xlsx 模式)、Sheet 名称、列顺序、ZIP 结构;与 Python/前端约定一致;改造(04/05)后不变。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1. test_filename_pattern
|
||||
2. test_sheet_name
|
||||
3. test_column_order
|
||||
4. test_zip_structure
|
||||
5. test_encoding_utf8
|
||||
6. test_empty_result_file
|
||||
7. test_contract_frozen
|
||||
8. test_regression_guard
|
||||
|
||||
## 任务 219:13 全量契约回归
|
||||
|
||||
**所属模块**:13 契约 **依赖**:202-218 **预估**:8-15 分钟
|
||||
|
||||
### 功能点要求
|
||||
全部契约测试(Java + 前端)+ ArchUnit + 白名单检查全绿;契约快照冻结;CI 通过。
|
||||
|
||||
### 测试用例(≥8)
|
||||
1-8:Java 契约全绿、前端契约全绿、ArchUnit 三规则、白名单、快照比对、CI 模拟、全量单测、package
|
||||
|
||||
### 验证方法
|
||||
`mvn test` 全量 + `cd frontend-vue && npm run build && npx vitest run` + CI 检查。
|
||||
|
||||
### 收尾验证(全部模块——启动性/核心功能/质量 gate)
|
||||
1. `mvn clean package -DskipTests` 产 JAR,`java -jar target/aiimage-backend-0.0.1-SNAPSHOT.jar`(本地配置)启动,curl 健康检查端点返回预期
|
||||
2. 核心页面(`/newApi/api/...` 抽样)可访问
|
||||
3. 核心交互路径:上传→解析→进度→下载最小链路真实调用非空
|
||||
4. `mvn test` 全绿(≥80% 覆盖抽查)
|
||||
5. `npm run build`(vue-tsc + vite)零错误;`npx vitest run` 全绿
|
||||
6. check_progress 脚本返回 all tasks done(exit 0)
|
||||
7. git log 验证每个 task 有对应 commit
|
||||
Reference in New Issue
Block a user