49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
251 lines
9.5 KiB
Markdown
251 lines
9.5 KiB
Markdown
# 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`。
|