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

9.5 KiB
Raw Blame History

07-plan — 保守缩短事务边界

对应 docs/specs/07-transaction-boundary.md。硬约束:Python /result 成功确认时机、done=true 封口、状态成功时机、回滚语义全部不变。 技术栈:Java 21 + Spring Transaction。

任务 124:@Transactional 方法审计清单

所属模块:07 事务 依赖:无 预估:8-15 分钟

功能点要求

扫描 modules 下全部 @Transactional 方法,产出审计清单:方法/事务内代码段分类(必须事务内:落库/状态/锁;可移出:纯计算/DTO 组装/日志/清理);文档产出,不改代码。

测试用例(≥8)

  1. test_audit_covers_all_modules — 覆盖全部业务模块
  2. test_audit_classification — 分类完整(必须/可移出)
  3. test_audit_result_endpoints — /result 方法都在清单
  4. test_audit_python_facing — Python 回调相关标记
  5. test_audit_priority_order — 按收益排序
  6. test_audit_no_code_change — 本任务零代码变更
  7. test_audit_documented — 文档产出
  8. test_audit_repeatable — 可重复执行

TDD 流程

  1. 写审计脚本/测试(断言清单文件存在且字段齐全)→ RED
  2. 产出清单 → GREEN
  3. 文档校验

任务 125:similarasin 纯计算移出事务

所属模块:07 事务 依赖:124 预估:8-15 分钟

功能点要求

similarasin 的 /result 提交事务内纯计算段(分组/百分比/校验)抽为无事务方法,在写库前调用;输出与现状一致。

测试用例(≥8)

  1. test_pure_compute_outside_tx — 计算在事务外
  2. test_compute_result_same — 结果一致
  3. test_tx_persistence_kept — 落库仍在事务内
  4. test_failure_rollback — 落库失败回滚(计算无副作用)
  5. test_compute_idempotent — 计算幂等
  6. test_compute_repeat_safe — 重复调用安全
  7. test_no_tx_annotation_moved — 移动的方法无事务注解
  8. test_behavior_snapshot — 快照一致

TDD 流程

  1. 测试断言事务边界(TransactionSynchronization 观察)→ RED
  2. 重构 → GREEN
  3. mvn test -Dtest=SimilarAsinTaskServiceTest 通过

任务 126:similarasin DTO 组装移出写事务

所属模块:07 事务 依赖:124 预估:8-15 分钟

功能点要求

结果回传的 DTO/VO 组装移到事务提交后(afterCompletion 或事务外);不影响落库字段。

测试用例(≥8)

  1. test_dto_assembly_after_tx — 组装在事务后
  2. test_assembled_fields_same — 字段一致
  3. test_tx_commit_then_assembly — 先提交后组装
  4. test_rollback_no_assembly — 回滚不组装
  5. test_assembly_error_safe — 组装错误不影响事务
  6. test_response_built_ok — 响应正常构造
  7. test_assembly_no_db_read — 组装不读库
  8. test_snapshot_same — 快照一致

任务 127:similarasin 临时文件清理挂 afterCommit

所属模块:07 事务 依赖:124 预估:8-15 分钟

功能点要求

事务完成后的临时文件清理改挂 TransactionSynchronization.afterCommit;回滚不清理(文件保留);清理异常不阻断。

测试用例(≥8)

  1. test_cleanup_after_commit — 提交后清理
  2. test_cleanup_no_rollback — 回滚不清理
  3. test_cleanup_error_swallowed — 异常吞掉
  4. test_cleanup_order — 在提交后
  5. test_cleanup_retryable — 失败可重试
  6. test_cleanup_tx_done — 事务状态已结束
  7. test_cleanup_idempotent — 幂等
  8. test_cleanup_integration — 全链路

任务 128:appearancepatent 事务收缩

所属模块:07 事务 依赖:124 预估:8-15 分钟

同 125-127 模式(注意双事务路径:persistSubmittedChunk + completeSubmittedChunk 两段不变)。

测试用例(≥8)

1-8:计算移外、双事务路径不变、落库保留、回滚一致、清理时机、幂等、快照一致、集成。

任务 129:shopdatacrawl 事务收缩

所属模块:07 事务 依赖:124 预估:8-15 分钟

同 125 模式。

测试用例(≥8)

同 125(shopdatacrawl 特有:items 分页写入路径)。

任务 130:publish 事务收缩

所属模块:07 事务 依赖:124 预估:8-15 分钟

同 125 模式(publish 特有:RustFS 分片合并路径不动)。

测试用例(≥8)

同 125(publish:分片合并后落库仍在事务内)。

任务 131:collectdata 事务收缩

所属模块:07 事务 依赖:124 预估:8-15 分钟

同 125 模式。

测试用例(≥8)

同 125。

任务 132:/result 成功确认时机不变测试

所属模块:07 事务 依赖:125-131 预估:8-15 分钟

功能点要求

/result 返回 HTTP 200 + success=true 在结果分片可靠落库之后;未落库前不返回成功;事务失败返回错误。

测试用例(≥8)

  1. test_result_200_after_persist — 落库后 200
  2. test_result_success_true — success=true
  3. test_result_persist_fail_no_200 — 落库失败不 200
  4. test_result_timing_order — 顺序断言
  5. test_result_retry_after_failure — 失败后重试
  6. test_result_chunk_then_ack — 分片先落库
  7. test_result_ack_then_response — 响应在 ACK 后
  8. test_result_contract_frozen — 契约快照

任务 133:回滚语义不变测试

所属模块:07 事务 依赖:125-131 预估:8-15 分钟

功能点要求

落库异常 → 完整回滚(任务状态、结果、payload 不变);纯计算无副作用;重试安全。

测试用例(≥8)

  1. test_rollback_full — 完整回滚
  2. test_rollback_status_unchanged — 状态不变
  3. test_rollback_payload — payload 不变
  4. test_rollback_retry — 重试安全
  5. test_rollback_compute_noop — 计算无副作用
  6. test_rollback_error_raised — 异常抛出
  7. test_rollback_partial_write — 部分写入也回滚
  8. test_rollback_consistency — 与改造前一致

任务 134:done=true 封口时机不变测试

所属模块:07 事务 依赖:125-131 预估:8-15 分钟

功能点要求

done=true 最后一批:强制处理未满批数据、生成结果文件的时机不变;封口语义不变。

测试用例(≥8)

  1. test_done_finalizes — 封口触发
  2. test_done_after_last_chunk — 最后一批后
  3. test_done_processes_remainder — 处理剩余
  4. test_done_generates_file — 生成结果
  5. test_done_idempotent — 重复 done 安全
  6. test_done_timing — 时机断言
  7. test_done_no_double — 不重复生成
  8. test_done_contract — 契约快照

任务 135:任务状态成功时机不变测试

所属模块:07 事务 依赖:125-131 预估:8-15 分钟

功能点要求

任务状态变 SUCCESS 的时机(结果文件生成完成判断)不变;fileReady/downloadUrl 含义不变。

测试用例(≥8)

  1. test_success_timing — 成功时机
  2. test_success_after_file — 文件生成后
  3. test_file_ready_semantics — fileReady 语义
  4. test_download_url_semantics — downloadUrl 语义
  5. test_success_no_file — 无文件不成功
  6. test_success_state_transition — 状态迁移
  7. test_success_observable — 前端可观测
  8. test_success_contract — 契约快照

任务 136:事务外清理异常不阻断

所属模块:07 事务 依赖:127 预估:8-15 分钟

功能点要求

afterCommit 清理抛异常:记录日志+指标,不影响响应;不重试成循环。

测试用例(≥8)

  1. test_cleanup_error_logged — 日志记录
  2. test_cleanup_error_response_ok — 响应不受影响
  3. test_cleanup_error_no_retry_loop — 不循环
  4. test_cleanup_error_tx_committed — 事务已提交
  5. test_cleanup_error_metric — 指标记录
  6. test_cleanup_error_next_time — 下次仍可清理
  7. test_cleanup_error_partial — 部分清理成功
  8. test_cleanup_error_integration — 集成

任务 137:重复提交幂等测试

所属模块:07 事务 依赖:132-135 预估:8-15 分钟

功能点要求

同 submissionId 重复提交 /result:幂等接受(成功返回,不重复落库);不同内容冲突拒绝。

测试用例(≥8)

  1. test_duplicate_same_id_ok — 同 id 幂等
  2. test_duplicate_no_double_persist — 不重复落库
  3. test_duplicate_success_true — 返回成功
  4. test_duplicate_diff_content_reject — 内容不同拒绝
  5. test_duplicate_chunk_conflict — chunk 冲突
  6. test_duplicate_after_done — 封口后重复
  7. test_duplicate_many — 多次重复
  8. test_duplicate_contract — 契约快照

任务 138:事务时长性能对比基准

所属模块:07 事务 依赖:125-131 预估:8-15 分钟

功能点要求

改造前后 /result 事务耗时基准对比(纯计算移出后的时间下降);记录基准数据。

测试用例(≥8)

  1. test_tx_duration_recorded — 耗时记录
  2. test_tx_duration_before_after — 前后对比
  3. test_tx_improved_or_equal — 不劣化
  4. test_tx_measure_repeatable — 可重复
  5. test_tx_load_200_chunks — 200 分片负载
  6. test_tx_no_regression — 无回退
  7. test_tx_benchmark_documented — 基准文档
  8. test_tx_bound_reasonable — 上界合理

任务 139:07 全量回归

所属模块:07 事务 依赖:132-138 预估:8-15 分钟

功能点要求

07 全部契约测试(132-135)+ 各模块事务重构测试全绿;mvn test 无回归。

测试用例(≥8)

1-8:契约 4 项全绿、幂等全绿、回滚全绿、各模块重构测试、全量单测、package、契约快照、git diff 范围

验证方法

mvn test + mvn clean package -DskipTests。