Saga Pattern (사가 패턴)

여행 예약 = 항공권 + 호텔 + 렌터카

1. 항공권 예약    ✓
2. 호텔 예약      ✓
3. 렌터카 예약    ✗ (매진)

→ 여행 전체를 포기해야 한다
→ 호텔 예약 취소 (보상)
→ 항공권 예약 취소 (보상)

BEGIN;
  INSERT INTO orders ...;          -- 주문 생성
  UPDATE stocks SET qty = qty - 1; -- 재고 차감
  INSERT INTO payments ...;        -- 결제 기록
COMMIT;  -- 하나라도 실패하면 전부 ROLLBACK

주문 서비스 ── orders DB
재고 서비스 ── stocks DB
결제 서비스 ── payments DB + 외부 PG

성공 흐름:   T1 ──> T2 ──> T3 ──> T4  완료

T3 실패:     T1 ──> T2 ──> T3 ✗
                    │      │
             C1 <── C2 <───┘   (완료된 것을 역순으로 보상)

sequenceDiagram
    participant O as 주문 서비스
    participant I as 재고 서비스
    participant P as 결제 서비스

    O->>O: 주문 생성 (PENDING)
    O-)I: OrderCreated
    I->>I: 재고 예약
    I-)P: StockReserved
    P->>P: 결제 시도
    alt 결제 성공
        P-)O: PaymentApproved
        O->>O: 주문 확정 (CONFIRMED)
    else 결제 실패
        P-)I: PaymentFailed
        I->>I: 재고 예약 해제 (보상)
        P-)O: PaymentFailed
        O->>O: 주문 취소 (보상)
    end

// inventory/application/order-events.consumer.ts
@Controller()
export class InventorySagaParticipant {
  constructor(private readonly stocks: StockService) {}

  @EventPattern('ordering.order-created.v1')
  async onOrderCreated(@Payload() e: OrderCreatedV1) {
    try {
      await this.stocks.reserve(e.data.orderId, e.data.lines); // outbox로 StockReserved 발행
    } catch (err) {
      if (err instanceof OutOfStockException) {
        await this.stocks.publishReservationFailed(e.data.orderId, err.message);
        return;
      }
      throw err; // 일시적 오류는 재시도
    }
  }

  @EventPattern('payment.payment-failed.v1')
  async onPaymentFailed(@Payload() e: PaymentFailedV1) {
    await this.stocks.release(e.data.orderId); // 보상: 멱등하게 구현
  }
}

stateDiagram-v2
    [*] --> ORDER_CREATED
    ORDER_CREATED --> STOCK_RESERVED: StockReserved
    ORDER_CREATED --> CANCELLING: StockReservationFailed
    STOCK_RESERVED --> PAYMENT_APPROVED: PaymentApproved
    STOCK_RESERVED --> COMPENSATING_STOCK: PaymentFailed
    PAYMENT_APPROVED --> COMPLETED: OrderConfirmed
    COMPENSATING_STOCK --> CANCELLING: StockReleased
    CANCELLING --> CANCELLED: OrderCancelled
    COMPLETED --> [*]
    CANCELLED --> [*]

CREATE TABLE order_saga (
  saga_id     UUID PRIMARY KEY,
  order_id    TEXT NOT NULL UNIQUE,
  state       TEXT NOT NULL,
  data        JSONB NOT NULL,           -- 단계 진행에 필요한 데이터 (금액, 라인 등)
  version     INT  NOT NULL DEFAULT 0,  -- 동시 응답 처리 시 낙관적 락
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  deadline_at TIMESTAMPTZ               -- 타임아웃 감지용
);

// ordering/saga/place-order.saga.ts
type SagaState =
  | 'ORDER_CREATED'
  | 'STOCK_RESERVED'
  | 'PAYMENT_APPROVED'
  | 'COMPENSATING_STOCK'
  | 'CANCELLING'
  | 'COMPLETED'
  | 'CANCELLED';

type Reply =
  | { type: 'StockReserved' }
  | { type: 'StockReservationFailed'; reason: string }
  | { type: 'PaymentApproved'; transactionId: string }
  | { type: 'PaymentFailed'; reason: string }
  | { type: 'StockReleased' }
  | { type: 'OrderConfirmed' }
  | { type: 'OrderCancelled' };

type Command = { target: 'inventory' | 'payment' | 'ordering'; type: string; payload: object };

// 순수 로직: 상태 + 응답 → 다음 상태 + 보낼 명령. 테스트하기 쉽다
export function transition(
  state: SagaState,
  reply: Reply,
  data: { orderId: string; amount: number; lines: object[] },
): { next: SagaState; commands: Command[] } {
  switch (state) {
    case 'ORDER_CREATED':
      if (reply.type === 'StockReserved')
        return {
          next: 'STOCK_RESERVED',
          commands: [{ target: 'payment', type: 'ApprovePayment', payload: { orderId: data.orderId, amount: data.amount } }],
        };
      if (reply.type === 'StockReservationFailed')
        return {
          next: 'CANCELLING',
          commands: [{ target: 'ordering', type: 'CancelOrder', payload: { orderId: data.orderId, reason: reply.reason } }],
        };
      break;

    case 'STOCK_RESERVED':
      if (reply.type === 'PaymentApproved')
        return {
          next: 'PAYMENT_APPROVED',
          commands: [{ target: 'ordering', type: 'ConfirmOrder', payload: { orderId: data.orderId } }],
        };
      if (reply.type === 'PaymentFailed')
        return {
          next: 'COMPENSATING_STOCK',
          commands: [{ target: 'inventory', type: 'ReleaseStock', payload: { orderId: data.orderId } }],
        };
      break;

    case 'PAYMENT_APPROVED':
      if (reply.type === 'OrderConfirmed') return { next: 'COMPLETED', commands: [] };
      break;

    case 'COMPENSATING_STOCK':
      if (reply.type === 'StockReleased')
        return {
          next: 'CANCELLING',
          commands: [{ target: 'ordering', type: 'CancelOrder', payload: { orderId: data.orderId, reason: 'PAYMENT_FAILED' } }],
        };
      break;

    case 'CANCELLING':
      if (reply.type === 'OrderCancelled') return { next: 'CANCELLED', commands: [] };
      break;
  }

  // 예상하지 못한 응답 (중복, 순서 뒤바뀜): 상태를 바꾸지 않고 무시
  return { next: state, commands: [] };
}

// 재고 서비스: 멱등한 예약과 해제
async reserve(orderId: string, lines: Line[]) {
  const existing = await this.reservations.findByOrderId(orderId);
  if (existing?.status === 'RESERVED') return this.replyReserved(orderId);   // 중복 명령
  if (existing?.status === 'RELEASED') return this.replyFailed(orderId, 'ALREADY_CANCELLED'); // 해제가 먼저 옴
  // ... 실제 예약
}

async release(orderId: string) {
  const existing = await this.reservations.findByOrderId(orderId);
  if (!existing) {
    // 예약이 아직 안 왔는데 해제가 먼저 왔다 → 해제 기록을 남겨 이후 예약을 막는다
    await this.reservations.markReleased(orderId);
    return this.replyReleased(orderId);
  }
  if (existing.status === 'RELEASED') return this.replyReleased(orderId); // 중복
  // ... 실제 해제
}