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

251 lines
9.5 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.
# 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`。