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