`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
9.5 KiB
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)
- test_audit_covers_all_modules — 覆盖全部业务模块
- test_audit_classification — 分类完整(必须/可移出)
- test_audit_result_endpoints — /result 方法都在清单
- test_audit_python_facing — Python 回调相关标记
- test_audit_priority_order — 按收益排序
- test_audit_no_code_change — 本任务零代码变更
- test_audit_documented — 文档产出
- test_audit_repeatable — 可重复执行
TDD 流程
- 写审计脚本/测试(断言清单文件存在且字段齐全)→ RED
- 产出清单 → GREEN
- 文档校验
任务 125:similarasin 纯计算移出事务
所属模块:07 事务 依赖:124 预估:8-15 分钟
功能点要求
similarasin 的 /result 提交事务内纯计算段(分组/百分比/校验)抽为无事务方法,在写库前调用;输出与现状一致。
测试用例(≥8)
- test_pure_compute_outside_tx — 计算在事务外
- test_compute_result_same — 结果一致
- test_tx_persistence_kept — 落库仍在事务内
- test_failure_rollback — 落库失败回滚(计算无副作用)
- test_compute_idempotent — 计算幂等
- test_compute_repeat_safe — 重复调用安全
- test_no_tx_annotation_moved — 移动的方法无事务注解
- test_behavior_snapshot — 快照一致
TDD 流程
- 测试断言事务边界(TransactionSynchronization 观察)→ RED
- 重构 → GREEN
mvn test -Dtest=SimilarAsinTaskServiceTest通过
任务 126:similarasin DTO 组装移出写事务
所属模块:07 事务 依赖:124 预估:8-15 分钟
功能点要求
结果回传的 DTO/VO 组装移到事务提交后(afterCompletion 或事务外);不影响落库字段。
测试用例(≥8)
- test_dto_assembly_after_tx — 组装在事务后
- test_assembled_fields_same — 字段一致
- test_tx_commit_then_assembly — 先提交后组装
- test_rollback_no_assembly — 回滚不组装
- test_assembly_error_safe — 组装错误不影响事务
- test_response_built_ok — 响应正常构造
- test_assembly_no_db_read — 组装不读库
- test_snapshot_same — 快照一致
任务 127:similarasin 临时文件清理挂 afterCommit
所属模块:07 事务 依赖:124 预估:8-15 分钟
功能点要求
事务完成后的临时文件清理改挂 TransactionSynchronization.afterCommit;回滚不清理(文件保留);清理异常不阻断。
测试用例(≥8)
- test_cleanup_after_commit — 提交后清理
- test_cleanup_no_rollback — 回滚不清理
- test_cleanup_error_swallowed — 异常吞掉
- test_cleanup_order — 在提交后
- test_cleanup_retryable — 失败可重试
- test_cleanup_tx_done — 事务状态已结束
- test_cleanup_idempotent — 幂等
- 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)
- test_result_200_after_persist — 落库后 200
- test_result_success_true — success=true
- test_result_persist_fail_no_200 — 落库失败不 200
- test_result_timing_order — 顺序断言
- test_result_retry_after_failure — 失败后重试
- test_result_chunk_then_ack — 分片先落库
- test_result_ack_then_response — 响应在 ACK 后
- test_result_contract_frozen — 契约快照
任务 133:回滚语义不变测试
所属模块:07 事务 依赖:125-131 预估:8-15 分钟
功能点要求
落库异常 → 完整回滚(任务状态、结果、payload 不变);纯计算无副作用;重试安全。
测试用例(≥8)
- test_rollback_full — 完整回滚
- test_rollback_status_unchanged — 状态不变
- test_rollback_payload — payload 不变
- test_rollback_retry — 重试安全
- test_rollback_compute_noop — 计算无副作用
- test_rollback_error_raised — 异常抛出
- test_rollback_partial_write — 部分写入也回滚
- test_rollback_consistency — 与改造前一致
任务 134:done=true 封口时机不变测试
所属模块:07 事务 依赖:125-131 预估:8-15 分钟
功能点要求
done=true 最后一批:强制处理未满批数据、生成结果文件的时机不变;封口语义不变。
测试用例(≥8)
- test_done_finalizes — 封口触发
- test_done_after_last_chunk — 最后一批后
- test_done_processes_remainder — 处理剩余
- test_done_generates_file — 生成结果
- test_done_idempotent — 重复 done 安全
- test_done_timing — 时机断言
- test_done_no_double — 不重复生成
- test_done_contract — 契约快照
任务 135:任务状态成功时机不变测试
所属模块:07 事务 依赖:125-131 预估:8-15 分钟
功能点要求
任务状态变 SUCCESS 的时机(结果文件生成完成判断)不变;fileReady/downloadUrl 含义不变。
测试用例(≥8)
- test_success_timing — 成功时机
- test_success_after_file — 文件生成后
- test_file_ready_semantics — fileReady 语义
- test_download_url_semantics — downloadUrl 语义
- test_success_no_file — 无文件不成功
- test_success_state_transition — 状态迁移
- test_success_observable — 前端可观测
- test_success_contract — 契约快照
任务 136:事务外清理异常不阻断
所属模块:07 事务 依赖:127 预估:8-15 分钟
功能点要求
afterCommit 清理抛异常:记录日志+指标,不影响响应;不重试成循环。
测试用例(≥8)
- test_cleanup_error_logged — 日志记录
- test_cleanup_error_response_ok — 响应不受影响
- test_cleanup_error_no_retry_loop — 不循环
- test_cleanup_error_tx_committed — 事务已提交
- test_cleanup_error_metric — 指标记录
- test_cleanup_error_next_time — 下次仍可清理
- test_cleanup_error_partial — 部分清理成功
- test_cleanup_error_integration — 集成
任务 137:重复提交幂等测试
所属模块:07 事务 依赖:132-135 预估:8-15 分钟
功能点要求
同 submissionId 重复提交 /result:幂等接受(成功返回,不重复落库);不同内容冲突拒绝。
测试用例(≥8)
- test_duplicate_same_id_ok — 同 id 幂等
- test_duplicate_no_double_persist — 不重复落库
- test_duplicate_success_true — 返回成功
- test_duplicate_diff_content_reject — 内容不同拒绝
- test_duplicate_chunk_conflict — chunk 冲突
- test_duplicate_after_done — 封口后重复
- test_duplicate_many — 多次重复
- test_duplicate_contract — 契约快照
任务 138:事务时长性能对比基准
所属模块:07 事务 依赖:125-131 预估:8-15 分钟
功能点要求
改造前后 /result 事务耗时基准对比(纯计算移出后的时间下降);记录基准数据。
测试用例(≥8)
- test_tx_duration_recorded — 耗时记录
- test_tx_duration_before_after — 前后对比
- test_tx_improved_or_equal — 不劣化
- test_tx_measure_repeatable — 可重复
- test_tx_load_200_chunks — 200 分片负载
- test_tx_no_regression — 无回退
- test_tx_benchmark_documented — 基准文档
- 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。