docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案

`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
This commit is contained in:
2026-10-04 13:51:16 +08:00
parent 9e7c100389
commit b404fd2572
34 changed files with 15059 additions and 3 deletions
@@ -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 兼容清单逐项核对。