Files
crawler-plugin/backend-java/docs/plans/04-plan-result-file-job-handler-registry.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

18 KiB
Raw Blame History

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
  3. test_cleanup_delegates
  4. test_on_failure_delegates
  5. test_offload_true
  6. test_owner_scoped_true
  7. 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 兼容清单逐项核对。