CQRS (Command Query Responsibility Segregation)

         ┌──────────────┐
요청 ──> │ 쓰기인가?    │
         └──┬────────┬──┘
     Command│        │Query
            ▼        ▼
   ┌──────────────┐ ┌──────────────┐
   │ Write Model  │ │ Read Model   │
   │ (규칙 검증)  │ │ (화면에 맞춤)│
   └──────┬───────┘ └──────┬───────┘
          ▼                ▼
       저장소            저장소
  (같을 수도, 다를 수도 있다)

// (X) 조회처럼 보이는데 상태를 바꾼다
getNextTicketNumber(): number {
  return ++this.counter;
}

// (O) 명령과 조회를 나눈다
issueTicket(): void { this.counter++; }       // Command: 반환 없음
currentTicketNumber(): number { return this.counter; } // Query: 부작용 없음

쓰기에 필요한 것 (Order Aggregate)       화면에 필요한 것 (내 주문 목록)
───────────────────────────────          ───────────────────────────────
- 주문 라인 전체                          - 주문번호
- 상태 전이 규칙                          - 대표 상품명 + "외 2건"
- 총액 한도 검증                          - 대표 상품 썸네일
- 동시성 버전                             - 총액 (포맷된 문자열)
                                          - 배송 상태 + 택배사 추적 링크
                                          - 리뷰 작성 가능 여부

flowchart LR
    L0[0단계<br/>분리 없음] --> L1[1단계<br/>코드 분리<br/>같은 DB]
    L1 --> L2[2단계<br/>읽기 전용 테이블/뷰<br/>같은 DB]
    L2 --> L3[3단계<br/>저장소 분리<br/>이벤트로 동기화]
    L3 --> L4[4단계<br/>+ Event Sourcing]

src/ordering/
├── domain/                        # 쓰기 모델
│   ├── order.ts
│   └── order.repository.ts
├── application/
│   ├── command/                   # 쓰기
│   │   ├── place-order.command.ts
│   │   ├── place-order.handler.ts
│   │   ├── cancel-order.command.ts
│   │   └── cancel-order.handler.ts
│   └── query/                     # 읽기
│       ├── get-my-orders.query.ts
│       ├── get-my-orders.handler.ts
│       └── my-order-summary.dto.ts
├── infrastructure/
└── presentation/
    └── order.controller.ts

// application/command/cancel-order.command.ts
export class CancelOrderCommand {
  constructor(
    readonly orderId: string,
    readonly requestedBy: string,
    readonly reason: string,
  ) {}
}

// application/command/cancel-order.handler.ts
@CommandHandler(CancelOrderCommand)
export class CancelOrderHandler implements ICommandHandler<CancelOrderCommand, void> {
  constructor(@Inject(ORDER_REPOSITORY) private readonly orders: OrderRepository) {}

  async execute(command: CancelOrderCommand): Promise<void> {
    const order = await this.orders.findById(OrderId.of(command.orderId));
    if (!order) throw new OrderNotFoundException(command.orderId);

    order.cancel(CustomerId.of(command.requestedBy), command.reason); // 규칙은 도메인이 지킨다
    await this.orders.save(order);
  }
}

-- 내 주문 목록 전용 읽기 테이블 (비정규화)
CREATE TABLE my_order_summaries (
  order_id         UUID PRIMARY KEY,
  customer_id      UUID NOT NULL,
  ordered_at       TIMESTAMPTZ NOT NULL,
  title            TEXT NOT NULL,       -- "무선 키보드 외 2건" 이 미리 계산되어 있다
  thumbnail_url    TEXT,
  total_amount     BIGINT NOT NULL,
  status           TEXT NOT NULL,
  can_write_review BOOLEAN NOT NULL DEFAULT false
);
CREATE INDEX ON my_order_summaries (customer_id, ordered_at DESC);

@QueryHandler(GetMyOrdersQuery)
export class GetMyOrdersHandler implements IQueryHandler<GetMyOrdersQuery> {
  constructor(private readonly dataSource: DataSource) {}

  execute(q: GetMyOrdersQuery) {
    return this.dataSource.query(
      `SELECT * FROM my_order_summaries
        WHERE customer_id = $1 ORDER BY ordered_at DESC LIMIT $2 OFFSET $3`,
      [q.customerId, q.size, (q.page - 1) * q.size],
    );
  }
}

flowchart LR
    C[Client] -->|POST /orders| CMD[Command Handler]
    CMD --> AGG[Order Aggregate]
    CMD -->|저장| WDB[(Write DB<br/>PostgreSQL)]
    CMD -->|OrderPlaced| BUS[[Message Broker<br/>Kafka / RabbitMQ]]
    BUS --> PROJ[Projector<br/>읽기 모델 갱신기]
    PROJ -->|upsert| RDB[(Read DB<br/>Elasticsearch / Redis / MongoDB)]
    C -->|GET /orders/me| QRY[Query Handler]
    QRY --> RDB

// ordering/read-model/my-order-summary.projector.ts
@Injectable()
export class MyOrderSummaryProjector {
  constructor(
    @InjectModel(MyOrderSummaryDoc.name) private readonly summaries: Model<MyOrderSummaryDoc>,
    private readonly catalog: CatalogReadClient, // 상품명, 썸네일 조회용
  ) {}

  @EventPattern('ordering.order-placed.v1')
  async onOrderPlaced(@Payload() e: OrderPlacedV1) {
    const first = await this.catalog.getProduct(e.lines[0].productId);
    await this.summaries.updateOne(
      { _id: e.orderId },
      {
        $setOnInsert: {
          customerId: e.customerId,
          orderedAt: e.occurredAt,
          title: e.lines.length > 1 ? `${first.name} 외 ${e.lines.length - 1}건` : first.name,
          thumbnailUrl: first.thumbnailUrl,
          totalAmount: e.totalAmount,
          status: 'PENDING',
          canWriteReview: false,
        },
      },
      { upsert: true }, // 같은 이벤트가 두 번 와도 결과가 같다 (멱등)
    );
  }

  @EventPattern('ordering.order-cancelled.v1')
  async onOrderCancelled(@Payload() e: OrderCancelledV1) {
    await this.summaries.updateOne({ _id: e.orderId }, { $set: { status: 'CANCELLED' } });
  }

  @EventPattern('shipping.delivered.v1')
  async onDelivered(@Payload() e: DeliveredV1) {
    await this.summaries.updateOne(
      { _id: e.orderId },
      { $set: { status: 'DELIVERED', canWriteReview: true } },
    );
  }

  @EventPattern('review.written.v1')
  async onReviewWritten(@Payload() e: ReviewWrittenV1) {
    await this.summaries.updateOne({ _id: e.orderId }, { $set: { canWriteReview: false } });
  }
}

t=0ms    POST /orders        → 주문 저장 완료, 201 응답
t=5ms    GET /orders/me      → 읽기 DB에 아직 없음
t=80ms   Projector가 반영    → 이제 보임

flowchart TD
    A[조회 요구사항이 생겼다] --> B{도메인 모델/Repository로<br/>간단히 해결되나?}
    B -- 예 --> N[CQRS 없이 진행]
    B -- 아니오 --> C[1단계: Query 핸들러에서<br/>SQL 직접 작성]
    C --> D{그래도 느린가?<br/>JOIN이 너무 많은가?}
    D -- 아니오 --> STOP1[1단계 유지]
    D -- 예 --> E[2단계: 읽기 전용 테이블]
    E --> F{다른 저장소가 필요하거나<br/>Context 경계를 엄격히 지켜야 하나?}
    F -- 아니오 --> STOP2[2단계 유지]
    F -- 예 --> G{결과적 일관성을<br/>업무적으로 허용하나?}
    G -- 아니오 --> STOP2
    G -- 예 --> H[3단계: 저장소 분리 + 이벤트]