던플 개발기 (13): 시세 총액 vs 매물 총액 — 가격 용어를 다시 설계하다

// market_query.proto — 경매장 매물("경매장 매물") 측 요약
message ListingPriceSummary {
  // 경매장 평균가 — deprecated: 평균가는 조작 가능해 UI에 노출하지 않는다. 비교에는
  // lowest_unit_price(경매장 최저가)와 시세(SoldPriceSummary)를 사용한다.
  optional double average_unit_price = 1 [deprecated = true];
  // 경매장 최저가.
  optional int64 lowest_unit_price = 2;
  // 관측된 매물 row 수 (총량 아님).
  int64 listing_count = 3;
  // 경매장 매물 총량 — Σ(매물 수량). "경매장 매물 총액"은 lowest_unit_price ×
  // total_quantity. listing_count로 대체하지 않는다.
  int64 total_quantity = 4;
}

flowchart TD
  subgraph L["경매장 매물 (listing-side)"]
    LR["auction_listings_current<br/>현재 걸려 있는 호가"] --> LMIN["경매장 최저가<br/>lowest_unit_price"]
    LR --> LQTY["매물 총량<br/>Σ quantity = total_quantity"]
    LMIN --> LTOT["매물 총액<br/>= 최저가 × 매물 총량"]
    LQTY --> LTOT
  end
  subgraph S["시세 (sold-side)"]
    SR["auction_sales<br/>실제 체결 이력"] --> SAVG["시세 평균<br/>average_unit_price"]
    SR --> STOT["시세 총액<br/>= Σ (unit_price × quantity)"]
    SAVG --> SCHG["등락폭<br/>시세 평균 기준"]
  end
  LTOT -.->|절대 섞지 않음| X(( ))
  STOT -.->|절대 섞지 않음| X

// market_query.proto — 시세("시세") 측 요약. auction_sales 집계에서만 파생.
// latest_unit_price는 가장 최근 대표 체결가, average_unit_price는 시세 평균,
// change_rate(등락폭)는 window 내 부호 있는 변화율(시세 평균 기준),
// total_sold_gold(시세 총액)는 window 내 거래 총액, total_quantity(총판매량)는
// window 내 체결 수량이다.
message SoldPriceSummary {
  optional int64 latest_unit_price = 1;
  optional double average_unit_price = 2;
  optional double change_rate = 3;
  optional int64 total_sold_gold = 4;
  int64 total_quantity = 5;
}

// market-bff · dashboard.dto.ts — REST 계약도 두 요약으로 분리
export class ListingPriceSummaryDto {
  /** @deprecated 경매장 평균가 — 조작 우려로 UI 미노출. lowestUnitPrice/시세를 사용. */
  averageUnitPrice?: number;
  lowestUnitPrice?: number; // 경매장 최저가 (best ask)
  listingCount!: number; // 관측된 row 수, 총량 아님
  totalQuantity!: number; // 경매장 매물 총량 (Σ quantity)
}
 
export class SoldPriceSummaryDto {
  latestUnitPrice?: number; // 시세
  averageUnitPrice?: number; // 시세 평균
  changeRate?: number; // 등락폭 (시세 평균 기준)
  totalSoldGold?: number; // 시세 총액
  totalQuantity!: number; // 총판매량
}

message MarketMover {
  // ...
  ListingPriceSummary listing_price_summary = 5; // context 용으로만 실림
  SoldPriceSummary sold_price_summary = 6;
  // window 내 부호 있는 변화율 (상승은 양수, 하락은 음수) — sold 기준.
  double price_change_rate = 7;
}

flowchart LR
  A["PostgreSQL<br/>auction_sales · minute aggregates"] --> B["Prisma repository<br/>getMarketWideTotalsChart 등<br/>(raw SQL)"]
  B --> C["read model port<br/>MarketDashboardReadPort"]
  C --> D["application use case<br/>GetMarketTotalsChart /<br/>GetListingTotalRanking"]
  D --> E["gRPC transport mapper<br/>domain → proto"]
  E --> F["market_query.proto<br/>MarketTotalsChartPoint ·<br/>ListingTotalRankingItem"]
  F --> G["market-bff<br/>REST DTO 매핑"]
  G --> H["market-web widget<br/>totals chart · ranking table"]

// market-application · market-dashboard-read.port.ts
export interface MarketDashboardReadPort {
  /**
   * Market-wide totals points … per bucket, the active-listing total value
   * (경매장 매물 총액) and the completed-sale total value (시세 총액). Gaps are
   * absent, never zero-filled.
   */
  getMarketWideTotalsChart(query: MarketWideTotalsChartQuery): Promise<MarketWideTotalsPoint[]>;
 
  /**
   * Top items by current auction-listing total value (매물 총액), descending.
   * Listing-side only; items with no listings observed since the query's
   * recency floor are excluded.
   */
  getListingTotalRanking(query: ListingTotalRankingQuery): Promise<ListingTotalRankingEntry[]>;
}

// 홈 hero 차트의 한 점: 두 시리즈를 같은 날짜 bucket에 정렬.
// auction_listing_total_amount(경매장 매물 총액) = Σ 최저가 × 매물 총량;
// sold_market_total_amount(시세 총액) = Σ total sold gold. gap bucket에서는
// 어느 쪽이든 absent — 0으로 채우지 않는다. 두 총액을 절대 섞지 않는다.
message MarketTotalsChartPoint {
  int64 bucket_start_epoch_ms = 1;
  optional int64 auction_listing_total_amount = 2;
  optional int64 sold_market_total_amount = 3;
  int64 contributing_item_count = 4;
}

flowchart TD
  BAD["folded aggregate를 그냥 SUM<br/>→ 3분마다 재관측이 중복 합산<br/>→ ~1000×/day 과다 계상"] -->|"시총 22조 · 실거래 31조 😵"| FIX
  FIX["소스에서 다시 계산"]
  FIX --> M["매물 총액 = 아이템별 bucket 내<br/>최신 minute 스냅샷의<br/>최저가 × 매물 총량<br/>(시점 시가총액, 합산 아님)"]
  FIX --> SD["시세 총액 = bucket 내 실제<br/>auction_sales row의<br/>Σ 단가 × 수량<br/>(dedupe된 원본)"]
  M -->|"시총 ~280억"| OK["현실적인 값"]
  SD -->|"실거래 ~450~980억"| OK

-- prisma-market-dashboard.repository.ts · getMarketWideTotalsChart (요약)
WITH listing AS (
  SELECT
    per_item.bucket_start AS bucket_start,
    SUM(per_item.last_listing_min::double precision
        * per_item.last_observed_qty::double precision)
      FILTER (WHERE per_item.last_listing_min IS NOT NULL) AS listing_total
  FROM (
    SELECT
      m.item_id,
      -- 아이템별 bucket 내 "최신" 스냅샷의 최저가 · 매물 총량
      (ARRAY_AGG(m.listing_min_unit_price ORDER BY m.bucket_start DESC)
         FILTER (WHERE m.listing_min_unit_price IS NOT NULL))[1] AS last_listing_min,
      (ARRAY_AGG(m.observed_total_quantity ORDER BY m.bucket_start DESC)
         FILTER (WHERE m.listing_min_unit_price IS NOT NULL))[1] AS last_observed_qty
    FROM item_market_minute_aggregates m
    WHERE m.bucket_start >= ${'{since}'}
    GROUP BY m.item_id, /* date_trunc(grain) */
  ) per_item
  GROUP BY per_item.bucket_start
),
sold AS (
  SELECT /* date_trunc(grain) */ AS bucket_start,
    SUM(s.unit_price::double precision * s.quantity::double precision) AS sold_total
  FROM auction_sales s
  WHERE s.sold_at >= ${'{since}'}
  GROUP BY /* date_trunc(grain) */
)
SELECT listing.bucket_start, listing.listing_total AS "auctionListingTotalAmount",
       sold.sold_total AS "soldMarketTotalAmount"
FROM listing LEFT JOIN sold ON listing.bucket_start = sold.bucket_start
ORDER BY listing.bucket_start ASC

// synthetic-item-filter.ts
export const SYNTHETIC_ITEM_ID_PREFIXES = ['seed-', 'integration-item-'] as const;
 
/** raw-SQL WHERE 절용 predicate. prefix는 사용자 입력이 아니라 하드코딩 리터럴이라
 *  인젝션 표면이 없다. */
export function notSyntheticItemIdSql(itemIdColumn: Prisma.Sql): Prisma.Sql {
  return Prisma.sql`${itemIdColumn} NOT LIKE 'seed-%' AND ${itemIdColumn} NOT LIKE 'integration-item-%'`;
}

// market-web · shared/lib/format/gold.ts
function truncOrNull(value: number | null | undefined): number | null {
  if (value === null || value === undefined || !Number.isFinite(value)) {
    return null;
  }
  return Math.trunc(value); // 절대 반올림하지 않는다
}
 
const TRILLION = 1_0000_0000_0000; // 조
const HUNDRED_MILLION = 1_0000_0000; // 억
const TEN_THOUSAND = 1_0000; // 만