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

420 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 兼容清单逐项核对。