던플 개발기 (15): 원시값을 타입으로 — branded types와 DTO→Model seam

readonly totalSoldGold?: number;  // 시세 총액 (골드)
readonly listingCount: number;    // 매물 개수

// 골드를 표시해야 하는 자리에 개수를 넣었지만 컴파일러는 침묵합니다
formatGold(row.listingPriceSummary.listingCount);
 
// 등락률(0~100대 숫자)로 총액을 계산해도 타입은 통과합니다
const total = mover.priceChangeRate * quantity;

flowchart TB
  subgraph before["브랜딩 이전: 전부 number / string"]
    G1["totalSoldGold : number"]
    C1["listingCount : number"]
    R1["priceChangeRate : number"]
    I1["itemId : string"]
    A1["auctionNo : string"]
  end
  before --> X["컴파일러: 모양이 같으니 서로 자유롭게 대입 가능<br/>→ 골드 자리에 개수를 넣어도 통과"]

// apps/market-web/src/shared/api/market-bff/brand.ts
type Brand<T, Name extends string> = T & { readonly __brand: Name };
 
/** Integer Gold (the game currency). Frontend Gold is always an integer. */
export type Gold = Brand<number, 'Gold'>;
 
/**
 * The single Gold conversion point: truncates fractional gold to an integer
 * (never rounds up), matching how the UI displays it.
 */
export function toGold(value: number): Gold {
  return Math.trunc(value) as Gold;
}

/** A catalog item id (the BFF/Neople item key). */
export type ItemId = Brand<string, 'ItemId'>;
export function toItemId(value: string): ItemId {
  return value as ItemId;
}
 
/** An auction listing/sale id (the Neople `auctionNo`). */
export type AuctionId = Brand<string, 'AuctionId'>;
export function toAuctionId(value: string): AuctionId {
  return value as AuctionId;
}

export interface TerminalPriceSummary {
  readonly lowestListingUnitPrice?: Gold; // 골드 → 브랜딩
  readonly highestListingUnitPrice?: Gold; // 골드 → 브랜딩
  readonly averageListingUnitPrice?: Gold; // 골드 → 브랜딩
  readonly listingCount: number; // 개수 → number 그대로
  readonly observedTotalQuantity: number; // 수량 → number 그대로
  readonly latestSaleUnitPrice?: Gold; // 골드 → 브랜딩
  readonly soldAverageUnitPrice?: Gold; // 골드 → 브랜딩
  readonly isTruncated: boolean;
}

flowchart TB
  trusted["신뢰하는 BFF 응답<br/>(fetch 결과)"] -->|"as &lt;Dto&gt; 캐스트 한 번"| b1["branded DTO"]
  raw["raw wire 값<br/>(realtime 프레임 · route param)"] -->|"toGold / toItemId / toAuctionId"| b2["branded 값"]
  b1 --> use["이후 앱 전체는 branded 타입으로만 다룸"]
  b2 --> use

// shared/lib/realtime/realtime-message.ts — raw wire를 브랜딩하는 유일한 생성자
return {
  itemId: toItemId(message.itemId),
  observedAt: message.observedAt,
  freshness: (message.freshness ?? 'NO_DATA') as Freshness,
  version: message.version,
  listingPriceSummary: {
    ...(listing.averageUnitPrice !== undefined
      ? { averageUnitPrice: toGold(listing.averageUnitPrice) }
      : {}),
    ...(listing.lowestUnitPrice !== undefined
      ? { lowestUnitPrice: toGold(listing.lowestUnitPrice) }
      : {}),
    listingCount: listing.listingCount ?? 0,
  },
  // ...
};

// libs/item/domain/src/lib/item-id.ts — 외부 입력을 검증하고 브랜딩
export type ItemId = string & { readonly __brand: 'ItemId' };
 
export function toItemId(value: string): ItemId {
  const trimmed = value.trim();
  if (trimmed.length === 0) {
    throw new InvalidItemIdError(value);
  }
  return trimmed as ItemId;
}

// shared/api/market-bff/market-bff.ts — wire DTO (전송 모양)
/** Catalog item as returned by the BFF `/items` endpoint (wire DTO). */
export interface MarketItemDto {
  readonly itemId: ItemId;
  readonly name: string;
  readonly rarity?: string;
  readonly itemType?: string;
  readonly itemTypeDetail?: string;
  readonly imageUrl?: string;
}

// entities/item/model/item.types.ts — 도메인 Model + 단일 seam
export interface MarketItem {
  readonly itemId: ItemId;
  readonly name: string;
  readonly rarity?: string;
  readonly itemType?: string;
  readonly itemTypeDetail?: string;
  readonly imageUrl?: string;
}
 
/**
 * Map the wire DTO to the domain model. A structural pass-through today; this is
 * the single seam where future normalization will live (e.g. mapping a
 * game-internal itemType to a user-facing category) without touching consumers.
 */
export function toMarketItem(dto: MarketItemDto): MarketItem {
  return { ...dto };
}

// features/item-search/api/items.api.ts — 경계에서 DTO를 Model로
export async function searchItems(query: string): Promise<MarketItem[]> {
  const trimmed = query.trim();
  if (trimmed.length === 0) {
    return [];
  }
  const { data } = await http.get<MarketItemDto[]>('/items', {
    params: { query: trimmed },
  });
  return data.map(toMarketItem); // ← seam을 통과시킨다
}

flowchart LR
  wire["BFF JSON 응답<br/>(raw wire)"] --> mint
  subgraph shared["shared/api · 데이터 접근 경계"]
    mint["fetch + as MarketItemDto 캐스트<br/>(id·gold 필드 브랜딩)"]
    dto["MarketItemDto"]
    mint --> dto
  end
  dto --> mapper
  subgraph entity["entities/item · 도메인"]
    mapper["toMarketItem (seam)"]
    model["MarketItem (Model)"]
    mapper --> model
  end
  model --> feat["features · widgets · UI"]

// entities/market-price/model/terminal-view-model.ts
import type { Gold, TerminalSnapshot } from '@/shared/api/market-bff';
 
/** "<itemType> · <itemTypeDetail>" 분류 문자열; 둘 다 없으면 빈 문자열. */
export function terminalClassification(item: {
  readonly itemType?: string;
  readonly itemTypeDetail?: string;
}): string {
  return [item.itemType, item.itemTypeDetail]
    .filter((part): part is string => Boolean(part))
    .join(' · ');
}
 
/** 첫 수집 이전인지("준비 중" 상태) 판정. */
export function isTerminalPreparing(snapshot: TerminalSnapshot): boolean {
  return !snapshot.freshness.hasCompletedCollection;
}
 
/**
 * 차트 구간의 평균 매물가 등락(첫 → 마지막 값 기준)과 방향.
 * 값 있는 구간이 둘 미만이거나 기준이 0이면 null.
 */
export function terminalPriceChange(
  snapshot: TerminalSnapshot
): { readonly percent: number; readonly up: boolean } | null {
  const valued = snapshot.chart.points
    .map((point) => point.listingAverageUnitPrice ?? point.listingMinUnitPrice)
    .filter((value): value is Gold => value !== undefined);
  const first = valued[0];
  const last = valued[valued.length - 1];
  if (first === undefined || last === undefined || first === 0) {
    return null;
  }
  const percent = ((last - first) / first) * 100;
  return { percent, up: percent >= 0 };
}

// widgets/terminal-view/ui/terminal-view.tsx — 계산 대신 파생 호출만
const change = terminalPriceChange(snapshot);
const classification = terminalClassification(item);
const preparing = isTerminalPreparing(snapshot);

flowchart LR
  snap["TerminalSnapshot DTO"] --> deriv
  subgraph mp["entities/market-price/model · 도메인"]
    deriv["terminalClassification<br/>terminalPriceChange<br/>isTerminalPreparing"]
  end
  deriv --> facts["준비된 도메인 사실<br/>분류 문자열 · 등락(percent·up) · 준비중 여부"]
  facts --> widget["terminal-view 위젯<br/>(계산 없이 렌더만)"]