---
name: mechanical-clauses
when: '幂等, 乐观锁, 软删除, 硬删除, 级联, 可恢复删除, 补偿, 并发控制, 删除策略'
scope:
  - backend
products:
  - '*'
id: ka-domain_knowledge-mechanical-clauses
asset_kind: domain_knowledge
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 幂等
  - 乐观锁
  - 软删除
  - 硬删除
  - 级联
  - 可恢复删除
  - 补偿
  - 并发控制
  - 删除策略
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: domain
status: active
---

## 业务规则
1. 幂等：同一请求多次执行结果必须一致，适用于 PUT/DELETE 接口、支付回调、消息消费等场景
2. 乐观锁：基于版本号（version 字段）的并发控制，更新时必须校验版本号，冲突时抛出业务异常而非静默覆盖
3. 软删除：标记删除（is_deleted / deleted_at）而非物理删除，适用于有审计要求或可恢复需求的数据
4. 硬删除：物理移除数据，仅适用于临时数据、可重建数据、日志明细等无审计要求的场景
5. 级联：主记录变更自动传递到子记录（如主表状态变更联动子表），必须明确级联范围，禁止无限制级联
6. 可恢复删除：删除后可在一定窗口内恢复（如回收站机制），窗口期到期后自动物理删除或归档
7. 补偿：正向操作失败时执行反向操作，用于分布式事务 saga 模式，补偿操作本身也必须幂等

## 约束条件
- 需求中出现上述条款时必须明确其在本项目中的具体实现语义，不得假设"大家都懂"
- 机械条款的选择属于裁决（团队决策），不属于需求事实，必须在需求澄清阶段确认
- 幂等字段必须建立唯一索引（如支付流水号、消息 ID），依赖数据库约束保证幂等性
- 乐观锁 version 字段禁止在 DTO 中暴露给前端，仅服务端内部使用
- 软删除的查询必须全局过滤已删除记录（MyBatis 拦截器或全局 scope），禁止每条 SQL 手动加条件
- 级联删除必须在 Entity 层配置（如 @OneToMany(cascade = CascadeType.REMOVE)），禁止在 Service 层手动循环删除

## 例外情况
- 日志明细、临时文件等可重建数据允许硬删除
- 数据迁移期间可临时绕过乐观锁，但必须记录变更并事后审计
- 性能敏感的批量操作（如定时任务清理）可绕过软删除全局过滤，但须显式声明

## 关联模式
- [[concurrency-control]] 并发控制实现模式
- [[transaction-pattern]] 事务与补偿模式
- crud-operation
