代码是副产物，理论才是主业——重读 Peter Naur 的经典论文

# 创建项目目录和 ADR 目录
mkdir -p my-project/docs/adr
cd my-project

# 安装 adr-tools（macOS 可用 brew，Linux 可从 GitHub 下载）
# brew install adr-tools
# 或直接用下面的手动方式

<!-- docs/adr/0001-use-event-driven-order-state.md -->
# ADR 0001: 采用事件驱动管理订单状态

## 状态
已接受

## 背景
订单状态从"待支付"到"已发货"需要经过多个中间状态。
之前的做法是在 Order 模型上直接修改 status 字段，
导致状态转换逻辑散落在多个服务中，难以追踪非法跳转。

## 决策
采用事件驱动模式：每次状态变更发布一个 OrderStateChangedEvent，
由 OrderStateMachine 趈费事件并校验转换合法性。

## 理由
1. 状态转换规则集中在一处，新接手的人读 StateMachine 就能理解全图。
2. 事件可被其他服务订阅（如通知服务），无需耦合。
3. 非法跳转在事件消费层被拦截，不会写入数据库。

## 后果
- 增加了一个 Event bus 组件，运维复杂度上升。
- 调试时需要追踪事件链路，日志必须包含 event_id。

# order_state_machine.py
"""ADR 0001 的落地实现：事件驱动的订单状态机"""

from enum import Enum
from dataclasses import dataclass
from typing import Optional

class OrderStatus(Enum):
    PENDING_PAYMENT = "pending_payment"
    PAID = "paid"
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    REFUNDING = "refunding"

# 合法转换表——这就是"理论"的核心：哪些跳转是允许的
VALID_TRANSITIONS = {
    OrderStatus.PENDING_PAYMENT: [OrderStatus.PAID, OrderStatus.REFUNDING],
    OrderStatus.PAID: [OrderStatus.SHIPPED, OrderStatus.REFUNDING],
    OrderStatus.SHIPPED: [OrderStatus.DELIVERED],
    OrderStatus.DELIVERED: [OrderStatus.REFUNDING],
    OrderStatus.REFUNDING: [OrderStatus.PAID],  # 退款后恢复
}

@dataclass
class OrderStateChangedEvent:
    order_id: str
    from_status: OrderStatus
    to_status: OrderStatus
    reason: Optional[str] = None

class OrderStateMachine:
    """消费事件，校验并执行状态转换"""

    def can_transition(self, from_status: OrderStatus, to_status: OrderStatus) -> bool:
        return to_status in VALID_TRANSITIONS.get(from_status, [])

    def handle_event(self, event: OrderStateChangedEvent) -> OrderStatus:
        if not self.can_transition(event.from_status, event.to_status):
            raise ValueError(
                f"非法状态跳转: {event.from_status.value} -> {event.to_status.value}"
                f" (order={event.order_id})"
            )
        print(f"[OK] order={event.order_id} "
              f"{event.from_status.value} -> {event.to_status.value}")
        return event.to_status

# 使用示例
if __name__ == "__main__":
    machine = OrderStateMachine()

    # 合法跳转
    e1 = OrderStateChangedEvent("ORD-001", OrderStatus.PENDING_PAYMENT, OrderStatus.PAID)
    machine.handle_event(e1)

    # 非法跳转——会被拦截
    e2 = OrderStateChangedEvent("ORD-001", OrderStatus.PENDING_PAYMENT, OrderStatus.SHIPPED)
    try:
        machine.handle_event(e2)
    except ValueError as err:
        print(f"[BLOCKED] {err}")

[OK] order=ORD-001 pending_payment -> paid
[BLOCKED] 非法状态跳转: pending_payment -> shipped (order=ORD-001)