docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案

`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
This commit is contained in:
2026-10-04 13:51:16 +08:00
parent 9e7c100389
commit b404fd2572
34 changed files with 15059 additions and 3 deletions
@@ -0,0 +1,250 @@
# 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`。