도메인 주도 설계(DDD)를 다시 정리하기

flowchart LR
  subgraph Sales["판매 컨텍스트"]
    S["Order =<br/>결제 후의 구매 의사"]
  end
  subgraph Logistics["물류 컨텍스트"]
    L["Order =<br/>출하 지시된 배송 물품"]
  end
  N["같은 Order라도 의미가 달라도 된다"]

  S -.-> N
  L -.-> N

  classDef context fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef note fill:#ffffff,stroke:#94a3b8,color:#334155,stroke-dasharray: 5 5
  class S,L context
  class N note

flowchart LR
  E1["🟧 견적 요청됨"] --> E2["🟧 견적 작성됨"] --> E3["🟧 견적 발송됨"]
  E3 --> C2["🟦 커맨드<br/>견적 승인하기"] --> E4["🟧 견적 승인됨"] --> E5["🟧 주문 접수됨"]
  E3 --> C1["🟦 커맨드<br/>견적 취소하기"] --> E6["🟧 견적 취소됨"]
  A1["🟪 애그리게이트<br/>견적서"] -.이벤트를 일으키는 본체.-> E2
  R1["🟨 규칙<br/>승인된 견적만 주문으로 전환할 수 있다"] -.제약.-> E5

  classDef event fill:#fdba74,stroke:#ea580c,color:#7c2d12
  classDef command fill:#bfdbfe,stroke:#2563eb,color:#1e3a8a
  classDef aggregate fill:#ddd6fe,stroke:#7c3aed,color:#4c1d95
  classDef rule fill:#fde68a,stroke:#ca8a04,color:#713f12
  class E1,E2,E3,E4,E5,E6 event
  class C1,C2 command
  class A1 aggregate
  class R1 rule

// ❌ 그냥 문자열
const email: string = "user@example.com";

// ✅ Value Object
class Email {
  constructor(private readonly value: string) {
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      throw new Error("유효하지 않은 이메일 주소입니다");
    }
  }
  equals(other: Email): boolean {
    return this.value === other.value;
  }
  toString(): string {
    return this.value;
  }
}

class User {
  constructor(
    public readonly id: UserId,
    private name: UserName,
    private email: Email,
  ) {}

  changeEmail(newEmail: Email): void {
    this.email = newEmail;
  }

  equals(other: User): boolean {
    return this.id.equals(other.id);
  }
}

// 애그리거트 루트
class Order {
  private items: OrderItem[] = [];

  constructor(
    public readonly id: OrderId,
    private readonly userId: UserId,
  ) {}

  // 애그리거트 내부의 정합성은 애그리거트 루트가 지킨다.
  addItem(product: Product, quantity: number): void {
    if (this.items.length >= 100) {
      throw new Error("주문당 항목 수 제한을 초과했습니다");
    }
    this.items.push(new OrderItem(product.id, quantity, product.price));
  }

  totalPrice(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal()),
      Money.zero(),
    );
  }
}

// Domain 계층: 인터페이스만 정의한다.
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

// Infrastructure 계층: 구현은 바깥에 둔다.
class PostgresOrderRepository implements OrderRepository {
  async findById(id: OrderId): Promise<Order | null> { /* ... */ }
  async save(order: Order): Promise<void> { /* ... */ }
}

// 이메일 중복 여부는 User 혼자 판단할 수 없다.
class UserDuplicationChecker {
  constructor(private readonly userRepository: UserRepository) {}

  async exists(email: Email): Promise<boolean> {
    return (await this.userRepository.findByEmail(email)) !== null;
  }
}

flowchart TB
  Start["그 로직은..."] --> Q1{"단일 객체의 상태만 바꾸는가?"}
  Q1 -- YES --> E["Entity 메서드"]
  Q1 -- NO --> Q2{"여러 애그리거트를 가로질러 판단하는가?"}
  Q2 -- YES --> D["Domain Service"]
  Q2 -- NO --> Q3{"리포지토리나 외부 서비스가 필요한가?"}
  Q3 -- YES --> D
  Q3 -- NO --> Q4{"명사보다 동사로 표현하는 편이 자연스러운가?"}
  Q4 -- YES --> D
  Q4 -- NO --> V["Entity / Value Object"]

  classDef question fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef answer fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
  class Q1,Q2,Q3,Q4 question
  class E,D,V answer

class Order {
  private status: OrderStatus;
  private items: OrderItem[];

  // ✅ 자신의 상태 전이는 스스로 지킨다.
  cancel(): void {
    if (this.status === OrderStatus.SHIPPED) {
      throw new Error("이미 발송된 주문은 취소할 수 없습니다");
    }
    this.status = OrderStatus.CANCELLED;
  }

  // ✅ 자신의 데이터만으로 계산하는 로직
  totalPrice(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal()),
      Money.zero(),
    );
  }

  // ✅ 자신의 불변 조건을 확인
  addItem(item: OrderItem): void {
    if (this.items.length >= 100) throw new Error("상한을 초과했습니다");
    this.items.push(item);
  }
}

// ✅ 두 애그리거트를 가로지르는 "송금" 로직
class TransferService {
  transfer(from: Account, to: Account, amount: Money): void {
    from.withdraw(amount);
    to.deposit(amount);
    // "송금"이라는 개념은 어느 한 계좌에도 속하지 않는다
  }
}

// ✅ 리포지토리가 필요한 "중복 검사"
class UserDuplicationChecker {
  constructor(private readonly userRepository: UserRepository) {}
  async exists(email: Email): Promise<boolean> {
    return (await this.userRepository.findByEmail(email)) !== null;
  }
}

// ❌ 이렇게 되면 안 된다
class OrderService {
  cancel(order: Order): void {
    if (order.status === "SHIPPED") throw new Error(/* ... */);
    order.status = "CANCELLED";  // setter 로 덮어씀
  }
  totalPrice(order: Order): Money { /* items 를 돌며 합계를 계산 */ }
  addItem(order: Order, item: OrderItem): void { /* ... */ }
}
class Order {
  status: string;
  items: OrderItem[];
  // getter / setter 만 있음 ← 빈혈 도메인 모델
}

class OrderPlaced {
  constructor(
    public readonly orderId: OrderId,
    public readonly userId: UserId,
    public readonly occurredAt: Date,
  ) {}
}

flowchart TB
  P["Presentation 계층<br/>UI / API"]
  A["Application 계층<br/>유스케이스"]
  D["Domain 계층<br/>모델 / 비즈니스 규칙<br/>핵심"]
  I["Infrastructure 계층<br/>DB / 외부 API"]

  P --> A --> D
  I --> D

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef domain fill:#c7d2fe,stroke:#4338ca,color:#1e1b4b
  class P,A,I layer
  class D domain

// ✅ 좋은 Controller: 그냥 전달만 한다
@Controller("orders")
class OrderController {
  constructor(private readonly placeOrder: PlaceOrderUseCase) {}

  @Post()
  async create(@Body() body: PlaceOrderRequest): Promise<OrderResponse> {
    // 1. 요청 모양을 정리한다(DTO 로 변환)
    const command = new PlaceOrderCommand(
      body.userId,
      body.items.map(i => ({ productId: i.productId, quantity: i.quantity })),
    );

    // 2. 유스케이스에 위임
    const result = await this.placeOrder.execute(command);

    // 3. 응답 모양으로 정리해 반환
    return OrderResponse.from(result);
  }
}

// ✅ 좋은 Application Service: 흐름만 조율한다
class PlaceOrderUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly productRepository: ProductRepository,
    private readonly orderRepository: OrderRepository,
    private readonly inventoryService: InventoryService,  // Domain Service
    private readonly transactionManager: TransactionManager,
    private readonly eventPublisher: EventPublisher,
  ) {}

  async execute(command: PlaceOrderCommand): Promise<OrderResult> {
    return this.transactionManager.run(async () => {
      // 1. 필요한 애그리거트를 조회
      const user = await this.userRepository.findById(command.userId);
      if (!user) throw new UserNotFoundError(command.userId);

      const products = await this.productRepository.findByIds(
        command.items.map(i => i.productId),
      );

      // 2. 도메인에 처리를 맡긴다(비즈니스 규칙은 Domain 내부)
      const order = Order.place(user, products, command.items);

      // 3. 도메인 서비스를 호출한다(여러 애그리거트를 가로지르는 판단)
      await this.inventoryService.reserve(order);

      // 4. 영속화
      await this.orderRepository.save(order);

      // 5. 도메인 이벤트 발행
      await this.eventPublisher.publishAll(order.pullEvents());

      return OrderResult.from(order);
    });
  }
}

// ❌ 안티패턴: Application 계층으로 비즈니스 규칙이 새고 있다
class PlaceOrderUseCase {
  async execute(command: PlaceOrderCommand) {
    // ❌ 재고 체크를 여기서 판단 → 도메인 지식 유출
    if (product.stock < command.quantity) {
      throw new Error("재고가 부족합니다");
    }
    // ❌ 합계 금액 계산을 여기서 수행 → Order 의 책임
    const total = command.items.reduce((s, i) => s + i.price * i.quantity, 0);
    // ❌ 상태 판단을 여기서 수행 → Order 의 책임
    if (user.status === "BLOCKED") throw new Error("계정이 정지되었습니다");

    await this.orderRepository.save({ /* ... */ });
  }
}

sequenceDiagram
  participant Browser
  participant Presentation as Presentation / OrderController
  participant Application as Application / PlaceOrderUseCase
  participant Domain as Domain / Order.place(...)
  participant Infrastructure as Infrastructure / Repository 구현

  Browser->>Presentation: POST /orders
  Presentation->>Application: PlaceOrderCommand 전달
  Note over Application: 트랜잭션 시작
  Application->>Infrastructure: userRepository.findById()
  Application->>Infrastructure: productRepository.findByIds()
  Infrastructure-->>Application: User / Product 애그리거트
  Application->>Domain: Order.place(user, products, items)
  activate Domain
  Domain->>Domain: 비즈니스 규칙 검증
  Domain->>Domain: 불변 조건 확인
  Domain->>Domain: OrderPlaced 이벤트 생성
  Domain-->>Application: Order 애그리거트와 OrderPlaced
  deactivate Domain
  Application->>Domain: inventoryService.reserve(order)
  Domain-->>Application: 재고 예약 결과
  Application->>Infrastructure: orderRepository.save(order)
  Application->>Infrastructure: eventPublisher.publishAll(...)
  Infrastructure-->>Application: 영속화 완료
  Note over Application: 트랜잭션 커밋
  Application-->>Presentation: OrderResult
  Presentation-->>Browser: 201 Created

// Domain 계층
class Order { /* 비즈니스 로직을 가진 애그리거트 */ }

// Application 계층: 입력 / 출력 DTO
class PlaceOrderCommand { /* 요청용 */ }
class OrderResult { /* 응답용 */ }

// Presentation 계층: HTTP 용 타입
class PlaceOrderRequest { /* JSON 스키마 */ }
class OrderResponse { /* 응답 JSON */ }

src/
├── controllers/
│   ├── user.controller.ts
│   ├── order.controller.ts
│   └── product.controller.ts
├── services/
│   ├── user.service.ts
│   ├── order.service.ts
│   └── product.service.ts
├── repositories/
│   ├── user.repository.ts
│   ├── order.repository.ts
│   └── product.repository.ts
└── entities/
    ├── user.entity.ts
    ├── order.entity.ts
    └── product.entity.ts

src/
├── contexts/                      ← Bounded Context 단위로 구성
│   ├── ordering/                  ← 주문 컨텍스트
│   │   ├── domain/
│   │   │   ├── order.ts           (Entity / Aggregate Root)
│   │   │   ├── order-item.ts
│   │   │   ├── order-id.ts        (Value Object)
│   │   │   ├── order-status.ts
│   │   │   ├── order.repository.ts(interface 만)
│   │   │   └── events/
│   │   │       └── order-placed.ts
│   │   ├── application/
│   │   │   ├── place-order.usecase.ts
│   │   │   └── cancel-order.usecase.ts
│   │   ├── infrastructure/
│   │   │   ├── postgres-order.repository.ts
│   │   │   └── stripe-payment.gateway.ts
│   │   └── presentation/
│   │       ├── order.controller.ts
│   │       └── dto/
│   │           ├── place-order.request.ts
│   │           └── order.response.ts
│   ├── catalog/                   ← 상품 카탈로그 컨텍스트
│   │   └── (같은 구조)
│   └── shipping/                  ← 배송 컨텍스트
│       └── (같은 구조)
├── shared-kernel/                 ← 모든 컨텍스트가 공유하는 Value Object
│   ├── money.ts
│   ├── email.ts
│   └── user-id.ts
└── shared/                        ← 횡단 기술 기반
    ├── logger.ts
    ├── transaction-manager.ts
    └── event-bus.ts

ordering/domain/
├── order/
│   ├── order.ts                   (애그리거트 루트)
│   ├── order-item.ts
│   ├── order-id.ts
│   ├── order-status.ts
│   ├── order.repository.ts
│   └── events/
│       ├── order-placed.ts
│       └── order-cancelled.ts
├── customer/
│   ├── customer.ts
│   └── customer.repository.ts
└── services/
    └── pricing.service.ts          (Domain Service)

monorepo/
├── apps/
│   ├── web/                       (Next.js 프런트엔드)
│   ├── api/                       (백엔드 API)
│   └── admin/                     (관리 화면)
├── packages/
│   ├── ordering-context/          ← 패키지로 묶인 Bounded Context
│   ├── catalog-context/
│   ├── shipping-context/
│   └── shared-kernel/
└── package.json

[프런트엔드 고유의 관심사]
- 라우팅
- 화면 상태(로딩, 오류, 선택 중 등)
- 폼 유효성 검사(UX 용)
- 애니메이션
- 반응형 재렌더링

flowchart TB
  R["Pages / Routes 계층<br/>Next.js 의 app/, pages/ 등"]
  C["Components 계층<br/>UI 컴포넌트 / 시각적 책임"]
  V["ViewModel / Hooks 계층<br/>화면 상태와 유스케이스 호출"]
  A["Application 계층<br/>유스케이스 / API 클라이언트"]
  D["Domain 계층<br/>프런트엔드의 최소 도메인 모델"]

  R --> C --> V --> A --> D

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef domain fill:#c7d2fe,stroke:#4338ca,color:#1e1b4b
  class R,C,V,A layer
  class D domain

// Domain 계층: 백엔드와 같은 도메인 규칙을 얇게 유지한다
class Order {
  constructor(
    public readonly id: string,
    public readonly status: OrderStatus,
    public readonly items: OrderItem[],
  ) {}

  // UI 에서 "취소 버튼을 눌러도 되는가?" 판단은 여기에 모은다
  canCancel(): boolean {
    return this.status === "PENDING" || this.status === "CONFIRMED";
  }

  totalPrice(): number {
    return this.items.reduce((s, i) => s + i.price * i.quantity, 0);
  }
}

// Application 계층: API 를 호출하는 유스케이스
class PlaceOrderUseCase {
  constructor(private readonly api: OrderApiClient) {}

  async execute(items: CartItem[]): Promise<Order> {
    const response = await this.api.placeOrder({ items });
    return Order.fromResponse(response);
  }
}

// ViewModel / Hooks 계층: 화면 상태를 관리
function useOrderForm() {
  const [items, setItems] = useState<CartItem[]>([]);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const placeOrder = useMemo(() => new PlaceOrderUseCase(orderApi), []);

  const submit = async () => {
    setIsSubmitting(true);
    try {
      await placeOrder.execute(items);
    } catch (e) {
      setError(formatError(e));
    } finally {
      setIsSubmitting(false);
    }
  };

  return { items, setItems, isSubmitting, error, submit };
}

// Components 계층: 겉모양에만 집중
function OrderForm() {
  const { items, isSubmitting, error, submit } = useOrderForm();
  return (
    <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
      {/* JSX */}
    </form>
  );
}

flowchart TB
  Browser["브라우저"]
  BFF["BFF<br/>Next.js API Routes / Hono 등<br/>화면에 최적화된 엔드포인트"]
  Ordering["주문 서비스"]
  Catalog["카탈로그 서비스"]
  Inventory["재고 서비스"]
  Response["화면에 맞게 가공한 응답"]

  Browser --> BFF
  BFF --> Ordering
  BFF --> Catalog
  BFF --> Inventory
  Ordering --> BFF
  Catalog --> BFF
  Inventory --> BFF
  BFF --> Response --> Browser

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef service fill:#e0e7ff,stroke:#4f46e5,color:#312e81
  classDef output fill:#ffffff,stroke:#94a3b8,color:#334155
  class Browser,BFF layer
  class Ordering,Catalog,Inventory service
  class Response output

App/
├── Domain/
│   ├── Entities/
│   │   ├── Recipe.swift
│   │   └── Ingredient.swift
│   ├── ValueObjects/
│   │   └── CookingTime.swift
│   ├── Repositories/
│   │   └── RecipeRepository.swift   (protocol / interface)
├── Application/
│   └── UseCases/
│       └── SearchRecipeUseCase.swift
├── Infrastructure/
│   ├── Repositories/
│   │   ├── CoreDataRecipeRepository.swift  (로컬 DB)
│   │   └── ApiRecipeRepository.swift       (원격 API)
│   ├── Storage/
│   │   └── KeyValueStore.swift
│   └── Sync/
│       └── RecipeSyncService.swift
└── Presentation/
    ├── ViewModels/
    │   └── RecipeListViewModel.swift
    └── Views/
        └── RecipeListView.swift            (SwiftUI)

// Domain 계층: 여러 저장소 대상을 추상화
protocol RecipeRepository {
    func find(id: RecipeId) async throws -> Recipe?
    func save(_ recipe: Recipe) async throws
}

// Infrastructure 계층: 로컬 + 원격을 합성
class HybridRecipeRepository: RecipeRepository {
    let local: CoreDataRecipeRepository
    let remote: ApiRecipeRepository

    func find(id: RecipeId) async throws -> Recipe? {
        // 오프라인이어도 로컬에서 가져올 수 있다
        if let cached = try await local.find(id: id) {
            return cached
        }
        let remote = try await remote.find(id: id)
        if let recipe = remote {
          try await local.save(recipe)  // 캐시 갱신
        }
        return remote
    }
}

shared/
└── domain/                        ← Web 과 Mobile 이 공통 사용
    ├── recipe.ts
    └── recipe.repository.ts
apps/
├── web/
│   └── infrastructure/
│       └── api-recipe.repository.ts
└── mobile/
    └── infrastructure/
        └── sqlite-recipe.repository.ts  (offline first)

// ✅ 설정 화면 갱신은 이 정도면 충분하다
class UpdateSiteSettingsHandler {
  constructor(private readonly db: Database) {}

  async execute(input: UpdateSiteSettingsInput): Promise<void> {
    await this.db.siteSettings.update({
      where: { id: 1 },
      data: input,
    });
  }
}

src/contexts/
├── ordering/                ← 풀 DDD
│   ├── domain/
│   ├── application/
│   ├── infrastructure/
│   └── presentation/
├── inventory/               ← 풀 DDD
│   └── (위와 같음)
├── catalog/                 ← 경량 DDD(Entity 는 두되 Service 는 최소)
│   └── (간략판)
└── admin/                   ← CRUD 기반
  ├── handlers/            (얇은 핸들러만)
    └── controllers/

// 쓰기 작업은 애그리거트를 거친다(엄격)
class CancelOrderUseCase {
  async execute(orderId: OrderId): Promise<void> {
    const order = await this.orderRepository.findById(orderId);
    order.cancel();                    // 도메인 규칙
    await this.orderRepository.save(order);
  }
}

// 읽기 전용 쿼리는 생 SQL 도 괜찮다(화면 최적화)
class OrderListQuery {
  async findForAdmin(filter: AdminFilter): Promise<OrderListView[]> {
    return this.db.raw(`
      SELECT o.id, o.status, u.name AS user_name, p.name AS product_name, ...
      FROM orders o
      JOIN users u ON ...
      JOIN order_items oi ON ...
      WHERE ...
    `);
  }
}