From 1f2805be23cb86f738ef0dea51280bb7eade24ee Mon Sep 17 00:00:00 2001 From: dahyeon Date: Thu, 2 Jul 2026 14:04:28 -0700 Subject: [PATCH] Add shared feature registry --- apps/api/src/shared-contract.spec.ts | 115 ++++++++++++ packages/shared/src/dto/analysis.dto.ts | 96 ++++++++++ packages/shared/src/feature-registry.ts | 221 ++++++++++++++++++++++++ packages/shared/src/index.ts | 3 +- 4 files changed, 434 insertions(+), 1 deletion(-) create mode 100644 apps/api/src/shared-contract.spec.ts create mode 100644 packages/shared/src/dto/analysis.dto.ts create mode 100644 packages/shared/src/feature-registry.ts diff --git a/apps/api/src/shared-contract.spec.ts b/apps/api/src/shared-contract.spec.ts new file mode 100644 index 0000000..38223b9 --- /dev/null +++ b/apps/api/src/shared-contract.spec.ts @@ -0,0 +1,115 @@ +import { + FEATURE_SCHEMA_VERSION, + METRICS, + VECTOR_DIMENSION, + type AnalysisRequestAcceptedDto, + type AnalysisJobStatusDto, + type AnalysisRequestDto, + type PlayerAnalysisDto, +} from '@persona-lenz/shared'; + +const MVP_1_METRIC_IDS = [ + 'kda', + 'killParticipation', + 'damageShare', + 'damagePerMin', + 'goldPerMin', + 'csPerMin', + 'visionScorePerMin', + 'wardsKilledPerMin', + 'controlWardsPlaced', + 'deathsPerMin', + 'objectiveParticipation', + 'soloKills', +]; + +describe('shared feature registry', () => { + it('defines MVP 1 vector metrics in the documented order', () => { + expect(FEATURE_SCHEMA_VERSION).toBe(1); + expect(METRICS.map((metric) => metric.id)).toEqual(MVP_1_METRIC_IDS); + expect(VECTOR_DIMENSION).toBe(12); + expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength( + VECTOR_DIMENSION, + ); + }); + + it('keeps metric ids unique and every MVP 1 metric normalizable by role', () => { + const metricIds = METRICS.map((metric) => metric.id); + + expect(new Set(metricIds).size).toBe(metricIds.length); + for (const metric of METRICS) { + expect(metric.label).toBeTruthy(); + expect(metric.kind).toBe('scalar'); + expect(metric.includeInVector).toBe(true); + expect(metric.baseline).toBeDefined(); + expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([ + 'BOTTOM', + 'JUNGLE', + 'MIDDLE', + 'TOP', + 'UTILITY', + ]); + + for (const range of Object.values(metric.baseline ?? {})) { + expect(range.min).toBeLessThan(range.max); + } + } + }); + + it('marks deaths per minute as lower-is-better for strength scoring', () => { + expect( + METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction, + ).toBe('lowerIsBetter'); + }); +}); + +describe('shared DTO contracts', () => { + it('exports request, job status, and player analysis DTO shapes', () => { + const request: AnalysisRequestDto = { + gameName: 'Hide on bush', + tagLine: 'KR1', + platform: 'kr', + matchCount: 20, + }; + const jobStatus: AnalysisJobStatusDto = { + jobId: 'job-1', + status: 'processing', + stage: 'fetch-match-details', + puuid: 'puuid-1', + progress: { fetchedMatches: 3, totalMatches: 20 }, + error: null, + }; + const accepted: AnalysisRequestAcceptedDto = { + jobId: 'job-1', + status: 'queued', + }; + const playstyle = Object.fromEntries( + MVP_1_METRIC_IDS.map((metricId) => [metricId, 0.5]), + ) as PlayerAnalysisDto['profile']['playstyle']; + const analysis: PlayerAnalysisDto = { + account: { + gameName: 'Hide on bush', + tagLine: 'KR1', + profileIconId: 1, + tiers: [], + }, + profile: { + mainRole: 'MIDDLE', + queueId: 420, + sampleGameCount: 12, + championPool: [{ championId: 103, games: 4, wins: 3 }], + playstyle, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + confidence: 0.9, + }, + strengths: [{ metricId: 'kda', value: 0.6 }], + weaknesses: [{ metricId: 'deathsPerMin', value: 0.7 }], + updatedAt: '2026-07-02T00:00:00.000Z', + }; + + expect(request.platform).toBe('kr'); + expect(accepted.status).toBe('queued'); + expect(jobStatus.progress.totalMatches).toBe(20); + expect(analysis.profile.mainRole).toBe('MIDDLE'); + }); +}); diff --git a/packages/shared/src/dto/analysis.dto.ts b/packages/shared/src/dto/analysis.dto.ts new file mode 100644 index 0000000..cf70832 --- /dev/null +++ b/packages/shared/src/dto/analysis.dto.ts @@ -0,0 +1,96 @@ +import type { MetricId, Role } from '../feature-registry'; + +export type AnalysisPlatformRoute = + | 'kr' + | 'jp1' + | 'na1' + | 'br1' + | 'la1' + | 'la2' + | 'euw1' + | 'eun1' + | 'tr1' + | 'ru' + | 'me1' + | 'oc1' + | 'sg2' + | 'tw2' + | 'vn2'; + +export type AnalysisJobStatus = + | 'queued' + | 'processing' + | 'completed' + | 'failed'; + +export interface AnalysisRequestDto { + gameName: string; + tagLine: string; + platform?: AnalysisPlatformRoute; + matchCount?: number; +} + +export interface AnalysisRequestAcceptedDto { + jobId: string; + status: Extract; +} + +export interface AnalysisJobProgressDto { + fetchedMatches: number; + totalMatches: number; +} + +export interface AnalysisJobStatusDto { + jobId: string; + status: AnalysisJobStatus; + stage?: string; + puuid?: string; + progress: AnalysisJobProgressDto; + error: string | null; +} + +export interface TierInfoDto { + queueType: string; + tier: string; + rank: string; + leaguePoints: number; + wins: number; + losses: number; + fetchedAt?: string; +} + +export interface AccountSummaryDto { + gameName: string; + tagLine: string; + profileIconId: number; + tiers: TierInfoDto[]; +} + +export interface ChampionPoolEntryDto { + championId: number; + games: number; + wins: number; +} + +export interface PlayerProfileSummaryDto { + mainRole: Role; + queueId: number; + sampleGameCount: number; + championPool: ChampionPoolEntryDto[]; + playstyle: Record; + featureSchemaVersion: number; + confidence: number; +} + +export interface MetricValueDto { + metricId: MetricId; + value: number; +} + +export interface PlayerAnalysisDto { + account: AccountSummaryDto; + profile: PlayerProfileSummaryDto; + strengths: MetricValueDto[]; + weaknesses: MetricValueDto[]; + updatedAt: string; +} diff --git a/packages/shared/src/feature-registry.ts b/packages/shared/src/feature-registry.ts new file mode 100644 index 0000000..67b870d --- /dev/null +++ b/packages/shared/src/feature-registry.ts @@ -0,0 +1,221 @@ +export const FEATURE_SCHEMA_VERSION = 1; + +export type MetricDirection = 'higherIsBetter' | 'lowerIsBetter' | 'neutral'; +export type Role = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY'; + +export const ROLES: readonly Role[] = [ + 'TOP', + 'JUNGLE', + 'MIDDLE', + 'BOTTOM', + 'UTILITY', +]; + +export interface MetricBaselineRange { + min: number; + max: number; +} + +export interface MetricDefinition { + id: string; + label: string; + direction: MetricDirection; + kind: 'scalar' | 'ratio'; + includeInVector: boolean; + baseline?: Record; +} + +const allRoles = ( + baseline: Record, +): Record => baseline; + +export const METRICS = [ + { + id: 'kda', + label: 'KDA', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.8, max: 5.0 }, + JUNGLE: { min: 1.0, max: 6.0 }, + MIDDLE: { min: 0.8, max: 6.0 }, + BOTTOM: { min: 0.9, max: 6.5 }, + UTILITY: { min: 1.0, max: 6.0 }, + }), + }, + { + id: 'killParticipation', + label: '킬 관여율', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.25, max: 0.75 }, + JUNGLE: { min: 0.45, max: 0.85 }, + MIDDLE: { min: 0.35, max: 0.8 }, + BOTTOM: { min: 0.35, max: 0.8 }, + UTILITY: { min: 0.45, max: 0.85 }, + }), + }, + { + id: 'damageShare', + label: '팀 딜 비중', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.12, max: 0.32 }, + JUNGLE: { min: 0.08, max: 0.25 }, + MIDDLE: { min: 0.18, max: 0.38 }, + BOTTOM: { min: 0.2, max: 0.42 }, + UTILITY: { min: 0.03, max: 0.18 }, + }), + }, + { + id: 'damagePerMin', + label: '분당 챔피언 피해량', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 350, max: 900 }, + JUNGLE: { min: 250, max: 750 }, + MIDDLE: { min: 450, max: 1000 }, + BOTTOM: { min: 450, max: 1050 }, + UTILITY: { min: 100, max: 450 }, + }), + }, + { + id: 'goldPerMin', + label: '분당 골드', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 300, max: 520 }, + JUNGLE: { min: 300, max: 500 }, + MIDDLE: { min: 330, max: 550 }, + BOTTOM: { min: 340, max: 580 }, + UTILITY: { min: 180, max: 380 }, + }), + }, + { + id: 'csPerMin', + label: '분당 CS', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 4.0, max: 9.0 }, + JUNGLE: { min: 4.0, max: 7.8 }, + MIDDLE: { min: 4.0, max: 9.5 }, + BOTTOM: { min: 4.5, max: 10.0 }, + UTILITY: { min: 0.0, max: 2.5 }, + }), + }, + { + id: 'visionScorePerMin', + label: '분당 시야 점수', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.3, max: 1.5 }, + JUNGLE: { min: 0.5, max: 2.0 }, + MIDDLE: { min: 0.3, max: 1.6 }, + BOTTOM: { min: 0.3, max: 1.5 }, + UTILITY: { min: 1.0, max: 4.0 }, + }), + }, + { + id: 'wardsKilledPerMin', + label: '분당 와드 제거', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.0, max: 0.2 }, + JUNGLE: { min: 0.02, max: 0.35 }, + MIDDLE: { min: 0.01, max: 0.25 }, + BOTTOM: { min: 0.01, max: 0.22 }, + UTILITY: { min: 0.03, max: 0.45 }, + }), + }, + { + id: 'controlWardsPlaced', + label: '제어 와드 설치', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0, max: 6 }, + JUNGLE: { min: 0, max: 8 }, + MIDDLE: { min: 0, max: 6 }, + BOTTOM: { min: 0, max: 5 }, + UTILITY: { min: 0, max: 10 }, + }), + }, + { + id: 'deathsPerMin', + label: '분당 사망', + direction: 'lowerIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0.0, max: 0.35 }, + JUNGLE: { min: 0.0, max: 0.32 }, + MIDDLE: { min: 0.0, max: 0.35 }, + BOTTOM: { min: 0.0, max: 0.38 }, + UTILITY: { min: 0.0, max: 0.45 }, + }), + }, + { + id: 'objectiveParticipation', + label: '오브젝트 관여', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0, max: 3 }, + JUNGLE: { min: 0, max: 5 }, + MIDDLE: { min: 0, max: 4 }, + BOTTOM: { min: 0, max: 4 }, + UTILITY: { min: 0, max: 4 }, + }), + }, + { + id: 'soloKills', + label: '솔로킬', + direction: 'higherIsBetter', + kind: 'scalar', + includeInVector: true, + // TODO: MVP 3에서 인구 percentile baseline으로 교체. + baseline: allRoles({ + TOP: { min: 0, max: 4 }, + JUNGLE: { min: 0, max: 3 }, + MIDDLE: { min: 0, max: 4 }, + BOTTOM: { min: 0, max: 3 }, + UTILITY: { min: 0, max: 1.5 }, + }), + }, +] as const satisfies readonly MetricDefinition[]; + +export type MetricId = (typeof METRICS)[number]['id']; + +export const VECTOR_METRICS = METRICS.filter( + (metric) => metric.includeInVector, +); + +export const VECTOR_DIMENSION = VECTOR_METRICS.length; diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index cb0ff5c..4479fc0 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -1 +1,2 @@ -export {}; +export * from './feature-registry'; +export * from './dto/analysis.dto';