DDD 이론 6: Entity와 Value Object 심화

🎭 철학적 관점: 테세우스의 배

// TypeScript Entity 기본 클래스
abstract class Entity<T> {
  protected readonly _id: T;

  constructor(id: T) {
    this._id = id;
  }

  get id(): T {
    return this._id;
  }

  equals(other: Entity<T>): boolean {
    if (other === null || other === undefined) {
      return false;
    }
    if (this === other) {
      return true;
    }
    // 식별자 기반 동등성
    return this._id === other._id;
  }
}

// 구체적인 Entity 구현
class Order extends Entity<OrderId> {
  private _status: OrderStatus;
  private _items: OrderItem[];
  private _totalAmount: Money;

  constructor(id: OrderId) {
    super(id);
    this._status = OrderStatus.DRAFT;
    this._items = [];
    this._totalAmount = Money.zero(Currency.KRW);
  }

  // 비즈니스 메서드들...
  addItem(item: OrderItem): void {
    this._items.push(item);
    this.recalculateTotal();
  }

  confirm(): void {
    if (this._items.length === 0) {
      throw new EmptyOrderError();
    }
    this._status = OrderStatus.CONFIRMED;
  }
}

💵 현실 세계의 Value Object: 지폐

                    ┌─────────────────────────┐
                    │   새로운 도메인 개념    │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │ 고유 식별자가 필요한가? │
                    └───────────┬─────────────┘
                                │
              ┌─────────────────┼─────────────────┐
              │ Yes             │                 │ No
              ▼                 │                 ▼
    ┌─────────────────┐        │       ┌─────────────────┐
    │ 생명주기 추적이 │        │       │ 속성이 같으면   │
    │   필요한가?     │        │       │ 같은 것인가?    │
    └────────┬────────┘        │       └────────┬────────┘
             │                 │                │
    ┌────────┼────────┐        │       ┌────────┼────────┐
    │ Yes    │        │ No     │       │ Yes    │        │ No
    ▼        │        ▼        │       ▼        │        ▼
┌────────┐   │   ┌────────┐    │   ┌────────┐   │   ┌────────┐
│ Entity │   │   │ 재검토 │    │   │ Value  │   │   │ 재검토 │
│        │   │   │ 필요   │    │   │ Object │   │   │ 필요   │
└────────┘   │   └────────┘    │   └────────┘   │   └────────┘
             │                 │                │
             └─────────────────┴────────────────┘

Primitive Obsession은 도메인 개념을 표현할 때 기본 타입(string, number, boolean)을 과도하게 사용하는 코드 스멜입니다.

interface User {
  id: string;           // UUID? 숫자?
  email: string;        // 유효한 이메일?
  phoneNumber: string;  // 어떤 형식?
  balance: number;      // 통화는? 음수 가능?
  birthDate: string;    // 어떤 포맷?
  status: string;       // 어떤 값이 가능?
}

// 문제점
const user: User = {
  id: "",               // 빈 문자열 허용
  email: "not-email",   // 유효하지 않은 이메일
  phoneNumber: "abc",   // 잘못된 전화번호
  balance: -1000,       // 음수 잔액?
  birthDate: "invalid", // 잘못된 날짜
  status: "whatever"    // 정의되지 않은 상태
};

interface User {
  id: UserId;
  email: Email;
  phoneNumber: PhoneNumber;
  balance: Money;
  birthDate: BirthDate;
  status: UserStatus;
}

// 컴파일 타임에 오류 감지
const user: User = {
  id: UserId.generate(),
  email: Email.of("user@example.com"),
  phoneNumber: PhoneNumber.korean("010-1234-5678"),
  balance: Money.won(10000),
  birthDate: BirthDate.of(1990, 1, 15),
  status: UserStatus.ACTIVE
};

// 잘못된 값은 생성 자체가 불가능
Email.of("invalid"); // throws InvalidEmailError

// Entity 생명주기 패턴
class Order {
  private _id: OrderId;
  private _status: OrderStatus;
  private _items: OrderItem[];
  private _createdAt: Date;
  private _updatedAt: Date;
  private _version: number;  // Optimistic Locking

  // 팩토리 메서드: 새 Entity 생성
  static create(customerId: CustomerId, address: Address): Order {
    const order = new Order();
    order._id = OrderId.generate();
    order._status = OrderStatus.DRAFT;
    order._items = [];
    order._createdAt = new Date();
    order._updatedAt = new Date();
    order._version = 0;
    
    // 도메인 이벤트 발행
    order.addDomainEvent(new OrderCreatedEvent(order._id, customerId));
    
    return order;
  }

  // 재구성: DB에서 로드
  static reconstitute(props: OrderProps): Order {
    const order = new Order();
    order._id = props.id;
    order._status = props.status;
    order._items = props.items;
    order._createdAt = props.createdAt;
    order._updatedAt = props.updatedAt;
    order._version = props.version;
    return order;
  }

  // 상태 변경 메서드
  confirm(): void {
    if (this._status !== OrderStatus.DRAFT) {
      throw new InvalidOrderStateError('Only draft orders can be confirmed');
    }
    if (this._items.length === 0) {
      throw new EmptyOrderError();
    }
    
    this._status = OrderStatus.CONFIRMED;
    this._updatedAt = new Date();
    
    this.addDomainEvent(new OrderConfirmedEvent(this._id));
  }

  cancel(reason: CancellationReason): void {
    if (!this._status.canBeCancelled()) {
      throw new InvalidOrderStateError('Order cannot be cancelled');
    }
    
    this._status = OrderStatus.CANCELLED;
    this._updatedAt = new Date();
    
    this.addDomainEvent(new OrderCancelledEvent(this._id, reason));
  }
}

// Repository 인터페이스 (도메인 레이어)
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  findByCustomerId(customerId: CustomerId): Promise<Order[]>;
  save(order: Order): Promise<void>;
  delete(order: Order): Promise<void>;
}

// Repository 구현 (인프라 레이어)
class TypeORMOrderRepository implements OrderRepository {
  constructor(
    private readonly dataSource: DataSource,
    private readonly mapper: OrderMapper
  ) {}

  async findById(id: OrderId): Promise<Order | null> {
    const entity = await this.dataSource
      .getRepository(OrderEntity)
      .findOne({
        where: { id: id.value },
        relations: ['lineItems']
      });
    
    return entity ? this.mapper.toDomain(entity) : null;
  }

  async save(order: Order): Promise<void> {
    const entity = this.mapper.toEntity(order);
    await this.dataSource.getRepository(OrderEntity).save(entity);
    
    // 도메인 이벤트 발행
    await this.publishDomainEvents(order);
  }
}

// Mapper: 도메인 ↔ 영속성 변환
class OrderMapper {
  toDomain(entity: OrderEntity): Order {
    return Order.reconstitute({
      id: OrderId.from(entity.id),
      status: OrderStatus.from(entity.status),
      items: entity.lineItems.map(item => 
        OrderItem.create(
          ProductId.from(item.productId),
          Quantity.of(item.quantity),
          Money.of(item.unitPriceAmount, Currency.from(item.unitPriceCurrency))
        )
      ),
      createdAt: entity.createdAt,
      updatedAt: entity.updatedAt,
      version: entity.version
    });
  }

  toEntity(order: Order): OrderEntity {
    const entity = new OrderEntity();
    entity.id = order.id.value;
    entity.status = order.status.value;
    entity.lineItems = order.items.map(item => {
      const lineItem = new OrderLineItemEntity();
      lineItem.productId = item.productId.value;
      lineItem.quantity = item.quantity.value;
      lineItem.unitPriceAmount = item.unitPrice.amount;
      lineItem.unitPriceCurrency = item.unitPrice.currency.code;
      return lineItem;
    });
    return entity;
  }
}

┌─────────────────────────────────────────────────────────────────┐
│                    주문 도메인 모델                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  [Entity]                        [Value Object]                  │
│  ┌─────────────┐                 ┌─────────────┐                │
│  │   Order     │────────────────►│   Money     │                │
│  │  (주문)     │                 │  (금액)     │                │
│  └──────┬──────┘                 └─────────────┘                │
│         │                                                        │
│         │ contains                ┌─────────────┐                │
│         ▼                         │  Address    │                │
│  ┌─────────────┐                 │  (배송지)   │                │
│  │ OrderItem   │◄────────────────└─────────────┘                │
│  │ (주문항목)  │                                                 │
│  │ [VO]        │                 ┌─────────────┐                │
│  └─────────────┘                 │  Quantity   │                │
│                                  │  (수량)     │                │
│  [Entity]                        └─────────────┘                │
│  ┌─────────────┐                                                 │
│  │  Customer   │                 ┌─────────────┐                │
│  │  (고객)     │────────────────►│   Email     │                │
│  └─────────────┘                 └─────────────┘                │
│                                                                  │
│  [Entity]                        ┌─────────────┐                │
│  │  Product    │                 │  Discount   │                │
│  │  (상품)     │                 │  (할인)     │                │
│  └─────────────┘                 └─────────────┘                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

class Order {
  private _id: OrderId;
  private _customerId: CustomerId;
  private _items: OrderItem[];
  private _shippingAddress: Address;
  private _status: OrderStatus;
  private _discount?: Discount;
  private _createdAt: Date;
  private _updatedAt: Date;

  // 비즈니스 상수
  private static readonly MINIMUM_ORDER_AMOUNT = Money.won(10000);
  private static readonly FREE_SHIPPING_THRESHOLD = Money.won(50000);
  private static readonly SHIPPING_FEE = Money.won(3000);

  private constructor() {}

  // 팩토리 메서드
  static create(customerId: CustomerId, shippingAddress: Address): Order {
    const order = new Order();
    order._id = OrderId.generate();
    order._customerId = customerId;
    order._items = [];
    order._shippingAddress = shippingAddress;
    order._status = OrderStatus.DRAFT;
    order._createdAt = new Date();
    order._updatedAt = new Date();
    return order;
  }

  // 주문 항목 추가
  addItem(item: OrderItem): void {
    this.ensureModifiable();
    
    const existingIndex = this._items.findIndex(
      i => i.productId.equals(item.productId)
    );
    
    if (existingIndex >= 0) {
      // 기존 항목이 있으면 수량 합산
      const existing = this._items[existingIndex];
      this._items[existingIndex] = OrderItem.create(
        existing.productId,
        existing.productName,
        existing.quantity.add(item.quantity),
        existing.unitPrice
      );
    } else {
      this._items.push(item);
    }
    
    this._updatedAt = new Date();
  }

  // 할인 적용
  applyDiscount(discount: Discount): void {
    this.ensureModifiable();
    this._discount = discount;
    this._updatedAt = new Date();
  }

  // 주문 확정
  confirm(): void {
    this.ensureModifiable();
    
    if (this._items.length === 0) {
      throw new EmptyOrderError();
    }
    
    if (this.subtotal.isLessThan(Order.MINIMUM_ORDER_AMOUNT)) {
      throw new MinimumOrderAmountError(Order.MINIMUM_ORDER_AMOUNT);
    }
    
    this._status = OrderStatus.CONFIRMED;
    this._updatedAt = new Date();
  }

  // 주문 취소
  cancel(reason: string): void {
    if (!this._status.canBeCancelled()) {
      throw new OrderCannotBeCancelledError(this._status);
    }
    
    this._status = OrderStatus.CANCELLED;
    this._updatedAt = new Date();
  }

  // 계산된 속성들
  get subtotal(): Money {
    return this._items.reduce(
      (sum, item) => sum.add(item.lineTotal),
      Money.zero()
    );
  }

  get discountAmount(): Money {
    if (!this._discount) return Money.zero();
    return this._discount.applyTo(this.subtotal);
  }

  get shippingFee(): Money {
    const afterDiscount = this.subtotal.subtract(this.discountAmount);
    return afterDiscount.isGreaterThanOrEqual(Order.FREE_SHIPPING_THRESHOLD)
      ? Money.zero()
      : Order.SHIPPING_FEE;
  }

  get totalAmount(): Money {
    return this.subtotal
      .subtract(this.discountAmount)
      .add(this.shippingFee);
  }

  // 상태 검증
  private ensureModifiable(): void {
    if (this._status !== OrderStatus.DRAFT) {
      throw new OrderNotModifiableError(this._status);
    }
  }

  // Getters
  get id(): OrderId { return this._id; }
  get customerId(): CustomerId { return this._customerId; }
  get items(): readonly OrderItem[] { return [...this._items]; }
  get shippingAddress(): Address { return this._shippingAddress; }
  get status(): OrderStatus { return this._status; }
  get discount(): Discount | undefined { return this._discount; }

  // Entity 동등성
  equals(other: Order): boolean {
    return this._id.equals(other._id);
  }
}

// 주문 생성 및 처리 예시
async function createOrderUseCase(
  customerId: string,
  items: Array<{ productId: string; quantity: number }>,
  shippingAddress: AddressDto,
  couponCode?: string
): Promise<OrderDto> {
  // 1. Value Object 생성 (유효성 검증 포함)
  const customer = CustomerId.from(customerId);
  const address = Address.korean({
    city: shippingAddress.city,
    district: shippingAddress.district,
    street: shippingAddress.street,
    detail: shippingAddress.detail,
    zipCode: shippingAddress.zipCode
  });

  // 2. Order Entity 생성
  const order = Order.create(customer, address);

  // 3. 상품 정보 조회 및 주문 항목 추가
  for (const item of items) {
    const product = await productRepository.findById(
      ProductId.from(item.productId)
    );
    
    if (!product) {
      throw new ProductNotFoundError(item.productId);
    }

    order.addItem(OrderItem.create(
      product.id,
      product.name,
      Quantity.of(item.quantity),
      product.price
    ));
  }

  // 4. 쿠폰 적용 (선택적)
  if (couponCode) {
    const coupon = await couponRepository.findByCode(couponCode);
    if (coupon && coupon.isValid()) {
      order.applyDiscount(coupon.toDiscount());
    }
  }

  // 5. 주문 확정
  order.confirm();

  // 6. 저장
  await orderRepository.save(order);

  // 7. DTO 반환
  return OrderDto.from(order);
}

// 실행 예시
const orderDto = await createOrderUseCase(
  'cust-123',
  [
    { productId: 'prod-1', quantity: 2 },
    { productId: 'prod-2', quantity: 1 }
  ],
  {
    city: '서울시',
    district: '강남구',
    street: '테헤란로 123',
    detail: '456호',
    zipCode: '06234'
  },
  'WELCOME10'
);

console.log(orderDto);
// {
//   id: 'ord-abc123',
//   status: 'CONFIRMED',
//   items: [...],
//   subtotal: '₩45,000',
//   discount: '₩4,500',
//   shippingFee: '₩3,000',
//   total: '₩43,500'
// }