Aggregate (애그리거트)

┌─────────────── Order Aggregate ───────────────┐
│                                               │
│   ┌──────────────────┐                        │
│   │ Order (Root)     │◄──── 외부는 여기로만    │
│   │  - id            │                        │
│   │  - status        │                        │
│   │  - shippingAddr ─┼──> Address (VO)        │
│   └───────┬──────────┘                        │
│           │ 1:N                               │
│   ┌───────▼──────────┐                        │
│   │ OrderLine        │                        │
│   │  - productId     │                        │
│   │  - unitPrice ────┼──> Money (VO)          │
│   │  - quantity  ────┼──> Quantity (VO)       │
│   └──────────────────┘                        │
└───────────────────────────────────────────────┘

// (X) OrderLine을 직접 꺼내서 수정한다
const line = await orderLineRepository.findById(lineId);
line.quantity = 100;               // 총액 한도 검사를 아무도 안 한다
await orderLineRepository.save(line);

// (O) Root를 통해서만 수정한다
const order = await orderRepository.findById(orderId);
order.changeLineQuantity(lineId, Quantity.of(100)); // 여기서 총액 한도 검사
await orderRepository.save(order);

// ordering/domain/order.ts
export class Order extends AggregateRoot {
  private static readonly MAX_TOTAL = Money.of(500_000);

  private constructor(
    readonly id: OrderId,
    readonly customerId: CustomerId,
    private status: OrderStatus,
    private lines: OrderLine[],
  ) {
    super();
  }

  // 내부 컬렉션을 그대로 내주지 않는다 (복사본 + 읽기 전용)
  get orderLines(): ReadonlyArray<OrderLine> {
    return [...this.lines];
  }

  addLine(productId: ProductId, unitPrice: Money, quantity: Quantity): void {
    this.assertModifiable();
    const newLine = OrderLine.create(productId, unitPrice, quantity);
    this.assertWithinLimit([...this.lines, newLine]);
    this.lines.push(newLine);
  }

  changeLineQuantity(lineId: OrderLineId, quantity: Quantity): void {
    this.assertModifiable();
    const changed = this.lines.map((l) =>
      l.id.equals(lineId) ? l.withQuantity(quantity) : l,
    );
    this.assertWithinLimit(changed);
    this.lines = changed;
  }

  removeLine(lineId: OrderLineId): void {
    this.assertModifiable();
    const remaining = this.lines.filter((l) => !l.id.equals(lineId));
    if (remaining.length === 0) {
      throw new EmptyOrderException(); // 라인은 1개 이상
    }
    this.lines = remaining;
  }

  totalAmount(): Money {
    return this.lines.reduce((sum, l) => sum.add(l.amount()), Money.zero());
  }

  private assertModifiable(): void {
    if (this.status !== OrderStatus.PENDING) {
      throw new OrderNotModifiableException(this.id, this.status);
    }
  }

  private assertWithinLimit(lines: OrderLine[]): void {
    const total = lines.reduce((sum, l) => sum.add(l.amount()), Money.zero());
    if (!Order.MAX_TOTAL.isGreaterThanOrEqual(total)) {
      throw new OrderLimitExceededException(total, Order.MAX_TOTAL);
    }
  }
}

flowchart TD
    A[A와 B를 하나의 Aggregate로 묶을까?] --> B{A와 B에 걸친 불변식이<br/>있나?}
    B -- 아니오 --> SEP[따로 둔다<br/>ID로 참조]
    B -- 예 --> C{그 규칙이 즉시<br/>지켜져야 하나?}
    C -- 아니오, 잠시 어긋나도 된다 --> SEP2[따로 둔다<br/>이벤트로 결과적 일관성]
    C -- 예 --> D{B의 생명주기가<br/>A에 종속되나?<br/>A가 삭제되면 B도 삭제?}
    D -- 예 --> SAME[하나의 Aggregate]
    D -- 아니오 --> E{묶으면 크기가<br/>감당할 만한가?}
    E -- 예 --> SAME
    E -- 아니오 --> REDESIGN[불변식/흐름 재설계<br/>예: 선예약]

시간 →
요청 A: 주문 #1 읽기 (version 3) ──> 라인 추가 ──> 저장 (version 4) ✓
요청 B: 주문 #1 읽기 (version 3) ──────> 라인 삭제 ──> 저장 시도 (version 3 기대) ✗ 충돌

// ordering/infrastructure/order.orm-entity.ts
@Entity('orders')
export class OrderOrmEntity {
  @PrimaryColumn('uuid') id: string;
  @VersionColumn() version: number; // TypeORM이 저장할 때마다 1씩 올린다
  // ...
}

// TypeORM의 save()는 버전 충돌을 자동으로 막지 않는다.
// 조건부 UPDATE로 직접 확인한다.
async save(order: Order): Promise<void> {
  const row = OrderMapper.toOrm(order);
  const result = await this.repo
    .createQueryBuilder()
    .update(OrderOrmEntity)
    .set({ status: row.status, version: () => 'version + 1' })
    .where('id = :id AND version = :version', { id: row.id, version: row.version })
    .execute();

  if (result.affected === 0) {
    throw new ConcurrencyConflictException(order.id);
  }
  // 라인 저장 생략
}

// (O) Aggregate Root당 하나
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

// (X) 내부 Entity용 Repository
interface OrderLineRepository { ... }

// 조회 전용: Aggregate를 거치지 않고 필요한 컬럼만 바로 읽는다
@Injectable()
export class OrderListQuery {
  constructor(private readonly dataSource: DataSource) {}

  async execute(customerId: string): Promise<OrderSummaryDto[]> {
    return this.dataSource.query(
      `SELECT o.id, o.status, o.total_amount, MIN(p.name) AS first_product_name
         FROM orders o
         JOIN order_lines l ON l.order_id = o.id
         JOIN product_snapshots p ON p.id = l.product_id
        WHERE o.customer_id = $1
        GROUP BY o.id
        ORDER BY o.created_at DESC`,
      [customerId],
    );
  }
}