던플 개발기 (12): 대시보드 — 랭킹·무버스·실시간 채널·인기 점수

flowchart LR
  B["브라우저 / market-web SSR"] -->|"REST /api/v1"| BFF[market-bff]
  BFF -->|"gRPC MarketQueryService"| API[market-api]
  API -->|"집계 read model"| AGG[("hourly / daily<br/>aggregates")]
  API -->|"랭킹 스냅샷"| SNAP[("popularity_ranking_snapshot")]
  CRON["market-cron<br/>recalculate-popularity"] -->|"3분마다 top-100 기록"| SNAP
  X["네오플 Open API"] -. "호출 없음" .- API

// apps/market-bff/src/app/dashboard/dashboard.controller.ts
@ApiTags('dashboard')
@Controller()
export class DashboardController implements OnModuleInit {
  @Get('home')
  async home(@Query('window') window?: string): Promise<HomeDashboardDto> {
    const normalized = normalizeWindow(window);
    const response = await firstValueFrom(
      this.query.getHomeDashboard({
        window: windowToProto(normalized),
        popularLimit: 0, // 0 = 서버 기본값 사용
        moverLimit: 0,
      })
    );
    return mapHomeDashboard(response, normalized);
  }
  // popular-items(커서 페이지네이션), market-movers, market-chart …
}

// libs/market/data-access/.../prisma-market-dashboard.repository.ts
const WINDOW_AGG_TABLE: Record<RankingWindow, Prisma.Sql> = {
  '24h': Prisma.raw('item_market_hourly_aggregates'), // 24h → 시간 버킷
  '7d': Prisma.raw('item_market_daily_aggregates'), // 7d  → 일 버킷
};

-- getMoverCandidates: 창 집계를 접어 시세 변화율 후보를 뽑는다
WITH w AS (
  SELECT
    a.item_id AS item_id,
    (ARRAY_AGG(a.sold_average_unit_price ORDER BY a.bucket_start DESC)
       FILTER (WHERE a.sold_average_unit_price IS NOT NULL))[1] AS current_price,
    (ARRAY_AGG(a.sold_average_unit_price ORDER BY a.bucket_start ASC)
       FILTER (WHERE a.sold_average_unit_price IS NOT NULL))[1] AS reference_price,
    SUM(a.sold_count) AS sample_count
  FROM item_market_hourly_aggregates a
  WHERE a.bucket_start >= $since
    AND <synthetic id 제외>
  GROUP BY a.item_id
)
SELECT item_id, current_price, reference_price, sample_count
FROM w
WHERE current_price  IS NOT NULL           -- 시세가 있어야 하고
  AND reference_price IS NOT NULL           -- 비교 대상도 있어야 하고
  AND sample_count  >= $minSampleCount      -- 표본이 충분해야 하고
  AND reference_price >= $minReferencePrice -- 분모(기준가)가 너무 작지 않아야 한다
ORDER BY (current_price - reference_price) / NULLIF(reference_price, 0) $dir
LIMIT $limit

// libs/market/domain/src/lib/market-mover.ts
export function computePriceChange(
  input: PriceChangeInput,
  thresholds: PriceChangeThresholds = DEFAULT_PRICE_CHANGE_THRESHOLDS
): PriceChange | null {
  const { currentUnitPrice, referenceUnitPrice, sampleCount } = input;
  if (currentUnitPrice === null || referenceUnitPrice === null) return null;
  if (sampleCount < thresholds.minSampleCount) return null; // 표본 하한
  if (referenceUnitPrice < thresholds.minReferencePrice) return null; // 분모 하한
  const rate = (currentUnitPrice - referenceUnitPrice) / referenceUnitPrice;
  return { rate, currentUnitPrice, referenceUnitPrice };
}

// libs/market/realtime/src/lib/protocol.ts
export const clientMessageSchema = z.discriminatedUnion('action', [
  z.object({ action: z.literal('subscribe-items'), itemIds }), // 보이는 행 일괄 구독
  z.object({ action: z.literal('unsubscribe-items'), itemIds }),
  z.object({ action: z.literal('subscribe-dashboard') }), // 랭킹/공급자 신호
  z.object({ action: z.literal('unsubscribe-dashboard') }),
  z.object({ action: z.literal('heartbeat') }),
  /* … 단건 subscribe/unsubscribe … */
]);
 
/** 대시보드 read model이 바뀌었다는 신호. 리스트 데이터는 싣지 않는다. */
export interface DashboardUpdatedMessage {
  readonly type: 'market.dashboard.updated';
  readonly reason: 'popularity' | 'provider'; // 랭킹 재계산 / 공급자 상태 변경
  readonly occurredAt: string;
}

// apps/realtime-gateway/src/app/gateway.ts (핵심만)
} else if (event.eventType === 'market.popularity.recalculated') {
  // 랭킹 재계산 → 대시보드 채널 새로고침 신호
  hub.onDashboardSignal('popularity', new Date());
} else if (event.eventType === 'provider.status.changed') {
  hub.onDashboardSignal('provider', new Date());
}

sequenceDiagram
  participant Cron as market-cron
  participant Kafka
  participant GW as realtime-gateway
  participant Web as 브라우저
  participant BFF as market-bff
  Cron->>Kafka: market.popularity.recalculated
  Kafka->>GW: 이벤트 소비
  GW->>Web: market.dashboard.updated (리스트 없음, reason=popularity)
  Web->>BFF: 대시보드 REST 재조회 (query invalidate)
  BFF-->>Web: 새 랭킹 스냅샷
  Note over Web: rank 변화 → FLIP 애니메이션

// apps/market-web/src/entities/dashboard/model/dashboard-patch.ts
export function applyPricePatch<T extends PricedRow>(row: T, patch: ItemPricePatch): T {
  // 다른 아이템이거나, 행보다 오래된 patch면 같은 참조 반환(리렌더 skip)
  if (row.itemId !== patch.itemId || isOlderThanRow(patch, row)) return row;
  return {
    ...row,
    // 매물(경매장): 최신 분 버킷이 권위 — 통째로 교체. 없으면 비워서 "—"
    listingPriceSummary: {
      ...(patch.listingPriceSummary.lowestUnitPrice !== undefined
        ? { lowestUnitPrice: patch.listingPriceSummary.lowestUnitPrice }
        : {}),
      listingCount: patch.listingPriceSummary.listingCount,
      totalQuantity: patch.listingPriceSummary.totalQuantity,
    },
    // 시세(체결): 최신 대표가만 merge. 창 집계(평균·등락폭·총액)는 REST 값 유지
    soldPriceSummary: {
      ...row.soldPriceSummary,
      ...(patch.soldPriceSummary.latestUnitPrice !== undefined
        ? { latestUnitPrice: patch.soldPriceSummary.latestUnitPrice }
        : {}),
    },
    lastUpdatedAt: patch.observedAt,
  };
}

// apps/market-web/src/widgets/popular-ranking-table/lib/use-flip-rows.ts
rows.forEach((row) => {
  const id = row.dataset['flipId']; // 안정적 itemId
  const top = row.getBoundingClientRect().top; // 새 위치 측정
  next.set(id, top);
  if (prefersReducedMotion) return; // 모션 없으면 위치만 추적
  const prevTop = previous.current.get(id);
  if (prevTop === undefined) return;
  const delta = prevTop - top; // 이동 거리
  if (Math.abs(delta) < 1) return;
  row.animate([{ transform: `translateY(${delta}px)` }, { transform: 'translateY(0)' }], {
    duration: 240,
    easing: 'ease-out',
  });
});

// libs/market/domain/src/lib/ranking-movement.ts
export function computeRankMovement(currentRank, currentScore, previous) {
  if (previous === null) return { rankDirection: 'new', rankDelta: null /* … */ }; // 직전 스냅샷에 없던 신규
  const rankDelta = previous.rank - currentRank; // 양수면 위로 올라감(1위 방향)
  const rankDirection = rankDelta > 0 ? 'up' : rankDelta < 0 ? 'down' : 'same';
  return { previousRank: previous.rank, rankDelta, rankDirection /* … */ };
}

// libs/market/domain/src/lib/full-popularity-score.ts (정규화 핵심)
function percentileRanks(values: readonly number[]): number[] {
  const n = values.length;
  if (n === 0) return [];
  return values.map((value) => {
    let strictlyLess = 0;
    for (const other of values) if (other < value) strictlyLess += 1;
    return strictlyLess / (n - 1); // 최소=0, 최대=1, 활동 없는 신호는 0
  });
}
// 각 신호를 log1p → percentileRank로 정규화한 뒤, 가중합으로 최종 점수.
// log1p는 순서를 보존하므로 순위를 바꾸지 않고 파이프라인만 일관되게 유지한다.

flowchart TB
  S["윈도우 신호 읽기<br/>조회·구독·수량·금액·변동성·매물변경"] --> L["log1p 압축"]
  L --> P["모집단 대비 백분위 정규화 (0~1)"]
  P --> W["가중합"]
  W --> SORT["점수 내림차순 정렬"]
  SORT --> TOP["top-100 스냅샷 기록 (최근 3배치 유지)"]
  TOP --> MOVE["직전 스냅샷과 비교 → rank 등락"]

// apps/market-web/src/entities/favorite/model/favorites.ts
export const FAVORITES_STORAGE_KEY = 'dunplay:market:v1:favorites';
export const MAX_FAVORITES = 20;
// 같은 문서 내 다른 훅이 다시 읽도록 커스텀 이벤트를 쏜다.
// 네이티브 'storage' 이벤트는 *다른* 탭에서만 발생하기 때문.
export const FAVORITES_EVENT = 'dunplay:favorites-changed';
 
export function toggleFavorite(item: FavoriteItem): FavoriteItem[] {
  const current = readFavorites();
  const next = isFavorited(item.itemId, current)
    ? current.filter((f) => f.itemId !== item.itemId)
    : [{ itemId: item.itemId, name: item.name }, ...current].slice(0, MAX_FAVORITES);
  return persist(next); // 최신 우선, 중복 제거, 20개 상한
}

dashboard read endpoints (task 0807):
  GET /api/v1/home                                        → 2xx JSON
  GET /api/v1/popular-items?window=24h&limit=10           → 2xx JSON
  GET /api/v1/market-movers?direction=up&window=24h&limit=5 → 2xx JSON
  GET /api/v1/market-chart?range=30d&metric=soldTotalGold → 2xx JSON