Add shared feature registry

This commit is contained in:
dahyeon committed 2026-07-02 14:04:28 -07:00
1 parent 34ae20476f
commit 1f2805be23
4 files changed
+434 -1

No files matched your search

+115
View File
@@ -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');
});
});
+96
View File
@@ -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<AnalysisJobStatus, 'queued' | 'processing'>;
}
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<MetricId, number>;
featureSchemaVersion: number;
confidence: number;
}
export interface MetricValueDto {
metricId: MetricId;
value: number;
}
export interface PlayerAnalysisDto {
account: AccountSummaryDto;
profile: PlayerProfileSummaryDto;
strengths: MetricValueDto[];
weaknesses: MetricValueDto[];
updatedAt: string;
}
+221
View File
@@ -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<Role, MetricBaselineRange>;
}
const allRoles = (
baseline: Record<Role, MetricBaselineRange>,
): Record<Role, MetricBaselineRange> => 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;
+2 -1
View File
@@ -1 +1,2 @@
export {};
export * from './feature-registry';
export * from './dto/analysis.dto';