# 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,构建 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 兼容清单逐项核对。