`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
18 KiB
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)
- test_interface_methods_present — 6 方法签名齐全
- test_cleanup_default_noop — 默认空实现
- test_on_failure_default_noop — 默认空实现
- test_offload_default_false — 默认 false
- test_owner_scoped_default_false — 默认 false
- test_process_returns_boolean — boolean 返回类型
- test_module_type_identity — moduleType 唯一标识
- test_javadoc_contract — 契约文档注释齐全(模块类型对应表)
TDD 流程
- 写接口 + 编译测试(实现类模拟)→ 类不存在 RED
- 实现接口 → GREEN
mvn test通过
任务 58:注册表容器与唯一性校验
所属模块:04 注册表 依赖:57 预估:8-15 分钟
功能点要求
ResultFileJobHandlerRegistry:构造时收集 List,构建 moduleType→handler Map;重复 moduleType 抛 IllegalStateException(含模块名);提供 resolve(moduleType) 与 moduleTypes()。
测试用例(≥8)
- test_register_all_handlers — 全部注册
- test_resolve_existing — 解析已知模块
- test_resolve_unknown_throws — 未知模块抛异常
- test_duplicate_module_type_throws — 重复注册抛 IllegalStateException
- test_duplicate_error_message — 错误消息含模块名
- test_module_types_listed — 枚举全部模块
- test_empty_registry_ok — 空注册表可解析(抛错)
- test_resolve_case_sensitive — 大小写敏感
TDD 流程
- 写测试(先 mock handler)→ RED
- 实现注册表 → GREEN
mvn test -Dtest=ResultFileJobHandlerRegistryTest通过
任务 59:启动校验(fail-fast)
所属模块:04 注册表 依赖:58 预估:8-15 分钟
功能点要求
Spring 启动时校验:TaskFileJobConfig 的每个 moduleType 有且仅有一个 Handler;缺注册(如新增模块未配 Handler)启动失败并给出缺失清单。
测试用例(≥8)
- test_startup_all_modules_covered — 全部 moduleType 覆盖
- test_startup_missing_handler_fails — 缺注册启动失败
- test_startup_missing_message_lists — 错误消息列缺失模块
- test_startup_duplicate_fails — 双注册失败
- test_startup_config_source — 从 TaskFileJobConfig 枚举
- test_startup_no_handler_new_module — 新模块无 handler 失败
- test_startup_valid_no_error — 合法配置启动通过
- 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)
- test_module_type — 正确
- test_process_delegates — 委托调用
- test_process_returns_true — true
- test_cleanup_calls_delete_latest — 清理调用
- test_cleanup_args — taskId/moduleType/scopeKey 参数
- test_offload_false — 不支持异步
- test_owner_scoped_false — 非 owner scoped
- test_process_null_job_guarded — 空 job 安全
TDD 流程
- 写测试 mock Service → RED
- 实现 Handler → GREEN
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)
- test_module_type_constant — 用 MODULE_TYPE 常量
- test_process_delegates
- test_cleanup_delegates — cleanupResultFileJob
- test_owner_scoped_true — true
- test_process_true
- test_cleanup_no_delete_latest — 不走 payload.deleteLatest
- test_offload_false
- 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)
- test_module_type
- test_process_delegates
- test_cleanup_delete_latest_and_service — 两处清理都调
- test_on_failure_delegates — handleResultFileJobFailure
- test_on_failure_args — job+message 参数
- test_owner_scoped_true
- test_process_true
- 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)
- test_module_type
- test_process_delegates
- test_cleanup_delete_latest
- test_finalize_after_success_order — 顺序:成功后再 finalize
- test_finalize_called_once — 只调一次
- test_finalize_false_result — 非成功不 finalize
- test_owner_scoped_false
- 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)
- test_module_type
- test_process_boolean_true — true 情况
- test_process_boolean_false — false(等待异步)
- test_cleanup_delegates
- test_offload_true
- test_owner_scoped_true
- test_false_means_waiting — false 语义与 Worker defer 对应
- 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)
- test_module_type
- test_process_true / 3. test_process_false
- test_cleanup_delegates
- test_on_failure_delegates
- test_offload_true
- test_owner_scoped_true
- 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)
- test_module_type
- test_process_delegates
- test_result_url_brand_special — brand resolveResultObjectKey 仍走公共路径
- test_cleanup_delegates
- test_offload_false
- test_owner_scoped_false
- test_null_job_guarded
- test_no_delete_latest — brand 不走 payload.deleteLatest
任务 72:COLLECT_DATA Handler
所属模块:04 注册表 依赖:57-59 预估:8-15 分钟
moduleType="COLLECT_DATA";process→collectDataService.processResultFileJob;cleanup 为空(原无分支)。
测试用例(≥8)
- test_module_type
- test_process_delegates
- test_process_true
- test_cleanup_noop — 无清理
- test_offload_false
- test_owner_scoped_false
- test_null_job_guarded
- 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)
- test_dispatch_resolves_handler — 注册表查找
- test_dispatch_known_module — 已知模块行为一致
- test_dispatch_unknown_throws — 未知模块 IllegalArgumentException
- test_dispatch_unknown_message — 消息含模块名
- test_dispatch_all_13_modules — 13 模块各委托正确
- test_dispatch_null_job — 空 job 安全
- test_dispatch_no_longer_branch — 无 if/else 残留(静态检查)
- test_dispatch_integration_process — process 全链路
TDD 流程
- 测试先断言 dispatch 行为(对现有实现 GREEN 基线)→ 改为注册表后仍 GREEN
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)
- test_cleanup_shop_data_crawl_both — 两处清理
- test_cleanup_delete_latest_modules — deleteLatest 模块组
- test_cleanup_appearance — cleanupResultFileJob
- test_cleanup_similar — cleanupResultFileJob
- test_cleanup_publish — cleanupResultFileJob
- test_cleanup_delete_brand — cleanupResultFileJob
- test_cleanup_collect_data_noop — 无清理
- 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)
- test_on_failure_shop_data_crawl — 回调
- test_on_failure_similar — 回调
- test_on_failure_others_noop — 其余无操作
- test_on_failure_unknown_ignored — 未知模块安全
- test_on_failure_idempotent — 重复调用安全
- test_on_failure_error_swallowed — 回调抛错不中断
- test_on_failure_args_passed — job+message 传递
- test_exhausted_finalize_flow — 重试耗尽全流程
任务 76:coze offload 判定改 handler
所属模块:04 注册表 依赖:60-72 预估:8-15 分钟
process() 中 APPEARANCE_PATENT/SIMILAR_ASIN 的 cozeTaskExecutor offload 判定改 handler.supportsAsyncOffload();offload 失败回退内联逻辑保持。
测试用例(≥8)
- test_offload_modules_detected — offload 模块识别
- test_offload_executes_on_coze_executor — 线程池执行
- test_offload_failure_fallback — 提交失败回退内联
- test_offload_other_modules_inline — 非 offload 内联
- test_offload_only_async_modules — 仅异步模块
- test_offload_no_duplicate_execution — 不回退重复执行
- test_offload_heartbeat_started — 心跳启动
- test_offload_integration — 全链路
任务 77:owner-scoped 判定改 handler
所属模块:04 注册表 依赖:60-72 预估:8-15 分钟
isOwnerScopedJob 改 handler.isOwnerScoped();owner 解析(scopeKey :owner: 标记)保留公共逻辑;非本实例跳过逻辑保持。
测试用例(≥8)
- test_owner_scoped_modules — 4 个 owner 模块
- test_owner_scoped_other_owner_skip — 他实例跳过
- test_owner_scoped_self_process — 本实例处理
- test_owner_scope_parse — :owner: 解析
- test_owner_scope_blank — 空 scope 视为本实例
- test_owner_non_scoped_modules — 非 owner 模块不受影响
- test_owner_unknown_instance_id — 未配置实例
- test_owner_integration — 全链路
任务 78:模块映射快照测试
所属模块:04 注册表 依赖:73 预估:8-15 分钟
功能点要求
快照断言:13 个 moduleType → Handler 类 → 原 Service 方法一一对应;与 04 spec §3 映射表一致;新增模块类型未映射即失败。
测试用例(≥8)
- test_snapshot_all_13_mapped — 13 全映射
- test_snapshot_shop_match_delegate — 委托方法名快照
- test_snapshot_appearance_boolean — 返回类型快照
- test_snapshot_publish_owner — owner 标记快照
- test_snapshot_failure_callbacks — onFailure 回调快照
- test_snapshot_no_extra_modules — 无多余映射
- test_snapshot_mapping_frozen — JSON 快照文件比对
- test_snapshot_new_module_fails — 新 moduleType 快照失败
任务 79:行为等价对比测试
所属模块:04 注册表 依赖:73-77 预估:8-15 分钟
功能点要求
同一 Job 序列(成功/失败/重试耗尽/异步等待/owner 跳过)改造前后产生相同状态迁移与依赖调用;用 mock 记录调用序列对比。
测试用例(≥8)
- test_equiv_success_job — 成功序列一致
- test_equiv_failed_job — 失败序列一致
- test_equiv_retry_exhausted — 重试耗尽一致
- test_equiv_async_wait — 异步等待一致
- test_equiv_owner_skip — owner 跳过一致
- test_equiv_orphan_failure — 孤儿失败一致
- test_equiv_call_sequence — 依赖调用顺序一致
- 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)
- test_orphan_task_not_found_en — 英文文案
- test_orphan_result_not_found_en
- test_orphan_cn_messages — 中文文案
- test_orphan_mark_permanent — markFailedPermanent
- test_non_orphan_mark_failed — 普通失败
- test_non_business_exception — 非业务异常
- test_retry_exhausted_after_orphan — 耗尽后终态
- test_orphan_no_requeue — 孤儿不重排
任务 81:卡死扫描/重试耗尽路径测试
所属模块:04 注册表 依赖:73 预估:8-15 分钟
resetStuckRunningJobsDetailed:超时卡死 job 重置;耗尽 job 走 finalizeRetryExhausted;消息默认文案("文件生成任务运行超时")。
测试用例(≥8)
- test_stuck_reset — 超时重置
- test_stuck_exhausted_finalize — 耗尽 finalize
- test_stuck_default_message — 默认文案
- test_stuck_custom_message — 自定义文案
- test_stuck_heartbeat_timeout — 心跳超时边界
- test_stuck_scan_interval — 调度间隔配置
- test_stuck_no_reset_active — 活跃 job 不重置
- test_stuck_idempotent — 重复扫描安全
任务 82:特殊规则回归(WITHDRAW/coze defer)
所属模块:04 注册表 依赖:78-81 预估:8-15 分钟
WITHDRAW markSuccess 后 tryFinalizeTask;coze 模块 dispatch 返回 false → touchRunning(owner)或 deferRunning;状态与时机与原实现完全一致。
测试用例(≥8)
- test_withdraw_finalize_after_success — 成功后 finalize
- test_withdraw_no_finalize_failed — 失败不 finalize
- test_coze_false_owner_touch — owner 路径 touchRunning
- test_coze_false_defer — 非 owner deferRunning
- test_coze_false_no_mark_failed — 等待不标记失败
- test_coze_true_mark_success — 完成后 markSuccess
- test_withdraw_finalize_once — 只一次
- test_special_rules_integration — 全链路
收尾验证(本模块)
mvn test 全量 + mvn clean package -DskipTests 通过;04 spec §4 兼容清单逐项核对。