---
name: state-transition
when: '状态机, 状态流转, 状态变更, 状态转换, 审批流, 工单状态, 订单状态, 流程引擎'
scope:
  - backend
products:
  - '*'
id: ka-pattern-state-transition
asset_kind: pattern
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: pattern
status: active
---

## 决策规则
- 仅列出状态列表不够，每个状态转换必须定义：触发条件、守卫条件、失败/回滚动作
- 金额、库存、配额、计数器等并发敏感节点默认需要并发控制
- 并发敏感操作必须显式声明：并发控制方式（乐观锁/悲观锁/幂等键/去重表）、重试策略、重复提交处理、用户可见失败反馈
- 跨模块或跨服务状态变更必须显式声明最终一致性和补偿策略
- 集成测试必须覆盖：至少一次成功转换、一次守卫失败、一次失败恢复或升级路径
- 状态流转必须通过状态机框架（如 Spring Statemachine）或显式流转表校验，禁止硬编码 if-else
- 每次状态变更必须记录流转日志（原状态→新状态、操作人、时间、原因）
- 并发状态变更必须使用乐观锁或分布式锁，防止状态覆盖
- 状态流转失败必须返回明确的错误原因，告知用户当前状态和允许的下一步操作
- 状态定义必须包含初始状态和终态，禁止出现无法流转的"悬挂状态"

## 验收项
- [AC-01] 状态转换有触发条件、守卫条件、回滚动作
- [AC-02] 并发敏感操作有显式并发控制声明
- [AC-03] 跨服务状态变更有补偿策略
- [AC-04] 集成测试覆盖成功和失败路径
- [AC-05] 状态机校验（非硬编码）
- [AC-06] 状态变更审计日志
- [AC-07] 并发状态变更防护
- [AC-08] 无悬挂状态
