From cfbc74d8820a6ff46389fa6ecaa64b831c8e78d1 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Fri, 3 Jul 2026 02:44:00 -0700 Subject: [PATCH] Show all metric insights with descriptions --- .../analysis/analysis-read.service.spec.ts | 14 +++++- .../modules/analysis/analysis-read.service.ts | 1 - apps/api/src/shared-contract.spec.ts | 3 +- apps/api/test/app.e2e-spec.ts | 32 ++++++++++--- apps/web/src/App.css | 47 ++++++++++++++----- apps/web/src/lib/format.ts | 29 +++++++++++- apps/web/src/pages/DashboardPage.tsx | 32 +++++++++++-- docs/PLAN.md | 6 +-- packages/shared/src/feature-registry.ts | 40 ++++++++++++++++ 9 files changed, 171 insertions(+), 33 deletions(-) diff --git a/apps/api/src/modules/analysis/analysis-read.service.spec.ts b/apps/api/src/modules/analysis/analysis-read.service.spec.ts index c777c3d..5292327 100644 --- a/apps/api/src/modules/analysis/analysis-read.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-read.service.spec.ts @@ -144,15 +144,25 @@ describe('AnalysisReadService', () => { (metric) => metric.metricId === 'deathWithShutdownBountyGivenRate', ), ).toBe(false); - expect(analysis.strengths).toEqual([ + expect(analysis.strengths).toHaveLength(12); + expect(analysis.weaknesses).toHaveLength(12); + expect(analysis.strengths.slice(0, 3)).toEqual([ { metricId: 'deathsPerMin', value: 0.1 }, { metricId: 'kda', value: 0.8 }, { metricId: 'killParticipation', value: 0.7 }, ]); - expect(analysis.weaknesses).toEqual([ + expect(analysis.strengths.at(-1)).toEqual({ + metricId: 'wardsKilledPerMin', + value: 0.1, + }); + expect(analysis.weaknesses.slice(0, 3)).toEqual([ { metricId: 'wardsKilledPerMin', value: 0.1 }, { metricId: 'visionScorePerMin', value: 0.2 }, { metricId: 'controlWardsPlaced', value: 0.2 }, ]); + expect(analysis.weaknesses.at(-1)).toEqual({ + metricId: 'deathsPerMin', + value: 0.1, + }); }); }); diff --git a/apps/api/src/modules/analysis/analysis-read.service.ts b/apps/api/src/modules/analysis/analysis-read.service.ts index 6c3a01d..c3ca696 100644 --- a/apps/api/src/modules/analysis/analysis-read.service.ts +++ b/apps/api/src/modules/analysis/analysis-read.service.ts @@ -201,7 +201,6 @@ export class AnalysisReadService { ? right.score - left.score : left.score - right.score, ) - .slice(0, 3) .map(({ metricId, value }) => ({ metricId, value })); } diff --git a/apps/api/src/shared-contract.spec.ts b/apps/api/src/shared-contract.spec.ts index be10a1c..a9c3899 100644 --- a/apps/api/src/shared-contract.spec.ts +++ b/apps/api/src/shared-contract.spec.ts @@ -185,7 +185,8 @@ describe('shared feature registry', () => { expect(new Set(metricIds).size).toBe(metricIds.length); for (const metric of METRICS) { - expect(metric.label).toBeTruthy(); + expect(metric.label.trim()).toBeTruthy(); + expect(metric.description.trim()).toBeTruthy(); expect(metric.baseline).toBeDefined(); expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([ 'BOTTOM', diff --git a/apps/api/test/app.e2e-spec.ts b/apps/api/test/app.e2e-spec.ts index 820a55f..dacd2f6 100644 --- a/apps/api/test/app.e2e-spec.ts +++ b/apps/api/test/app.e2e-spec.ts @@ -353,7 +353,7 @@ describe('AppController (e2e)', () => { queueId: 420, featureSchemaVersion: FEATURE_SCHEMA_VERSION, }); - expect(responseBody).toEqual({ + expect(responseBody).toMatchObject({ account: { gameName: 'Hide on bush', profileIconId: 1, @@ -392,18 +392,36 @@ describe('AppController (e2e)', () => { queueId: 420, sampleGameCount: 12, }, - strengths: [ + updatedAt: '2026-07-02T00:00:00.000Z', + }); + expect(responseBody.strengths).toHaveLength(12); + expect(responseBody.weaknesses).toHaveLength(12); + expect(responseBody.strengths).toEqual( + expect.arrayContaining([ { metricId: 'deathsPerMin', value: 0.1 }, { metricId: 'kda', value: 0.8 }, { metricId: 'killParticipation', value: 0.7 }, - ], - weaknesses: [ + { metricId: 'wardsKilledPerMin', value: 0.1 }, + ]), + ); + expect(responseBody.weaknesses).toEqual( + expect.arrayContaining([ { metricId: 'wardsKilledPerMin', value: 0.1 }, { metricId: 'visionScorePerMin', value: 0.2 }, { metricId: 'controlWardsPlaced', value: 0.2 }, - ], - updatedAt: '2026-07-02T00:00:00.000Z', - }); + { metricId: 'deathsPerMin', value: 0.1 }, + ]), + ); + expect(responseBody.strengths.slice(0, 3)).toEqual([ + { metricId: 'deathsPerMin', value: 0.1 }, + { metricId: 'kda', value: 0.8 }, + { metricId: 'killParticipation', value: 0.7 }, + ]); + expect(responseBody.weaknesses.slice(0, 3)).toEqual([ + { metricId: 'wardsKilledPerMin', value: 0.1 }, + { metricId: 'visionScorePerMin', value: 0.2 }, + { metricId: 'controlWardsPlaced', value: 0.2 }, + ]); }); it('/api/players/:puuid/analysis/latest (GET) returns 404 without a profile', async () => { diff --git a/apps/web/src/App.css b/apps/web/src/App.css index 15f7a95..ee172a3 100644 --- a/apps/web/src/App.css +++ b/apps/web/src/App.css @@ -361,36 +361,58 @@ .metric-card-list { display: grid; - grid-template-columns: repeat(3, minmax(0, 1fr)); + grid-template-columns: 1fr; gap: 10px; margin-top: 16px; } .metric-card { min-width: 0; - min-height: 94px; - display: flex; - flex-direction: column; - justify-content: space-between; - gap: 12px; + display: grid; + gap: 8px; border: 1px solid var(--border); border-radius: 8px; background: var(--surface-soft); padding: 14px; } -.metric-card span { - color: var(--text-muted); - font-size: 13px; +.metric-card-heading { + min-width: 0; + display: flex; + align-items: start; + justify-content: space-between; + gap: 12px; +} + +.metric-card-heading h3 { + min-width: 0; + margin: 0; + font-size: 15px; line-height: 1.35; } -.metric-card strong { +.metric-card-heading strong { + flex: 0 0 auto; color: var(--text-strong); - font-size: 24px; + font-size: 22px; line-height: 1; } +.metric-card p { + margin: 0; + color: var(--text-muted); + font-size: 13px; + line-height: 1.45; +} + +.metric-card > span { + color: var(--text-muted); + font-size: 12px; + font-weight: 700; + line-height: 1.35; + text-transform: uppercase; +} + .champion-list { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); @@ -640,8 +662,7 @@ min-height: auto; } - .summary-stat-grid, - .metric-card-list { + .summary-stat-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } } diff --git a/apps/web/src/lib/format.ts b/apps/web/src/lib/format.ts index e416a8c..940f650 100644 --- a/apps/web/src/lib/format.ts +++ b/apps/web/src/lib/format.ts @@ -1,4 +1,9 @@ -import { METRICS, type MetricId, type Role } from '@persona-lenz/shared'; +import { + METRICS, + type MetricDefinition, + type MetricId, + type Role, +} from '@persona-lenz/shared'; export const ROLE_LABELS: Record = { BOTTOM: '원딜', @@ -22,6 +27,9 @@ export const STAGE_LABELS: Record = { const metricLabelById = new Map( METRICS.map((metric) => [metric.id, metric.label]), ); +const metricDefinitionById = new Map( + METRICS.map((metric) => [metric.id, metric]), +); export function formatPercent(value: number): string { return `${Math.round(value * 100)}%`; @@ -31,6 +39,25 @@ export function getMetricLabel(metricId: MetricId): string { return metricLabelById.get(metricId) ?? metricId; } +export function getMetricDescription(metricId: MetricId): string { + return ( + metricDefinitionById.get(metricId)?.description ?? + '정규화된 플레이스타일 지표입니다.' + ); +} + +export function getMetricDirectionLabel(metricId: MetricId): string { + const direction = metricDefinitionById.get(metricId)?.direction; + + if (direction === 'lowerIsBetter') { + return '낮을수록 좋음'; + } + if (direction === 'higherIsBetter') { + return '높을수록 좋음'; + } + return '참고 지표'; +} + export function getStageLabel(stage?: string): string { if (!stage) { return '작업 상태 확인'; diff --git a/apps/web/src/pages/DashboardPage.tsx b/apps/web/src/pages/DashboardPage.tsx index 79cbf55..dbf4466 100644 --- a/apps/web/src/pages/DashboardPage.tsx +++ b/apps/web/src/pages/DashboardPage.tsx @@ -33,6 +33,8 @@ import { import { formatPercent, formatTier, + getMetricDescription, + getMetricDirectionLabel, getMetricLabel, ROLE_LABELS, } from '../lib/format'; @@ -251,8 +253,16 @@ export function DashboardPage() {
- - + +
@@ -310,20 +320,32 @@ function SummaryStat({ label, value }: { label: string; value: string }) { } function MetricInsightList({ + description, title, values, }: { + description: string; title: string; values: MetricValueDto[]; }) { return (
-

{title}

+
+
+

{title}

+

{description}

+
+ {values.length} metrics +
{values.map((metricValue) => (
- {getMetricLabel(metricValue.metricId)} - {formatPercent(metricValue.value)} +
+

{getMetricLabel(metricValue.metricId)}

+ {formatPercent(metricValue.value)} +
+

{getMetricDescription(metricValue.metricId)}

+ {getMetricDirectionLabel(metricValue.metricId)}
))}
diff --git a/docs/PLAN.md b/docs/PLAN.md index f8678a8..780f5ef 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -547,13 +547,13 @@ stage 5. build-profile : 최근 N게임 feature를 confidence 가중 평균 "featureSchemaVersion": 1, "confidence": 0.93 }, - "strengths": [ { "metricId": "killParticipation", "value": 0.71 } ], // direction 반영 상위 3개 - "weaknesses": [ { "metricId": "visionScorePerMin", "value": 0.22 } ], // direction 반영 하위 3개 + "strengths": [ { "metricId": "killParticipation", "value": 0.71 } ], // direction 반영 전체 지표, 강점 순 정렬 + "weaknesses": [ { "metricId": "visionScorePerMin", "value": 0.22 } ], // direction 반영 전체 지표, 약점 순 정렬 "updatedAt": "..." } ``` -강점/약점 판정: direction이 `lowerIsBetter`인 지표는 (1 - value)로 뒤집어 정렬에 사용. profile이 없으면 404. +강점/약점 판정: direction이 `lowerIsBetter`인 지표는 (1 - value)로 뒤집어 정렬에 사용. 응답은 계산 가능한 모든 registry 지표를 포함하며, 대시보드는 label/description과 함께 표시한다. profile이 없으면 404. --- diff --git a/packages/shared/src/feature-registry.ts b/packages/shared/src/feature-registry.ts index 51c1b52..7b206c3 100644 --- a/packages/shared/src/feature-registry.ts +++ b/packages/shared/src/feature-registry.ts @@ -19,6 +19,7 @@ export interface MetricBaselineRange { export interface MetricDefinition { id: string; label: string; + description: string; direction: MetricDirection; kind: 'scalar' | 'ratio'; includeInVector: boolean; @@ -41,6 +42,7 @@ export const METRICS = [ { id: 'kda', label: 'KDA', + description: '킬과 어시스트를 사망 대비 얼마나 안정적으로 만들었는지 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -56,6 +58,7 @@ export const METRICS = [ { id: 'killParticipation', label: '킬 관여율', + description: '팀 킬 중 직접 관여한 비율로, 교전 합류와 영향력을 나타냅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -71,6 +74,7 @@ export const METRICS = [ { id: 'damageShare', label: '팀 딜 비중', + description: '팀 전체 챔피언 피해량 중 본인이 차지한 비중입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -86,6 +90,7 @@ export const METRICS = [ { id: 'damagePerMin', label: '분당 챔피언 피해량', + description: '게임 시간 대비 적 챔피언에게 넣은 피해량입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -101,6 +106,7 @@ export const METRICS = [ { id: 'goldPerMin', label: '분당 골드', + description: '분당 획득 골드로 성장 속도와 자원 확보 능력을 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -116,6 +122,7 @@ export const METRICS = [ { id: 'csPerMin', label: '분당 CS', + description: '분당 미니언과 몬스터 처치량으로 기본 성장 안정성을 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -131,6 +138,7 @@ export const METRICS = [ { id: 'visionScorePerMin', label: '분당 시야 점수', + description: '게임 시간 대비 시야 확보와 시야 기여도를 나타냅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -146,6 +154,7 @@ export const METRICS = [ { id: 'wardsKilledPerMin', label: '분당 와드 제거', + description: '상대 시야를 얼마나 꾸준히 지웠는지 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -161,6 +170,7 @@ export const METRICS = [ { id: 'controlWardsPlaced', label: '제어 와드 설치', + description: '제어 와드를 통한 주요 지역 시야 장악 기여도입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -176,6 +186,7 @@ export const METRICS = [ { id: 'deathsPerMin', label: '분당 사망', + description: '게임 시간 대비 사망 빈도입니다. 낮을수록 안정적인 지표입니다.', direction: 'lowerIsBetter', kind: 'scalar', includeInVector: true, @@ -191,6 +202,7 @@ export const METRICS = [ { id: 'objectiveParticipation', label: '오브젝트 관여', + description: '드래곤, 전령, 바론, 포탑 등 주요 오브젝트 관여도를 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -206,6 +218,7 @@ export const METRICS = [ { id: 'soloKills', label: '솔로킬', + description: '아군 도움 없이 만든 킬로 라인전 압박과 개인 교전력을 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -221,6 +234,7 @@ export const METRICS = [ { id: 'goldDiffAt10', label: '10분 골드 차이', + description: '10분 시점 상대 라이너와의 골드 격차입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -236,6 +250,7 @@ export const METRICS = [ { id: 'goldDiffAt14', label: '14분 골드 차이', + description: '14분 시점 상대 라이너와의 골드 격차입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -251,6 +266,7 @@ export const METRICS = [ { id: 'csDiffAt10', label: '10분 CS 차이', + description: '10분 시점 상대 라이너와의 CS 격차입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -266,6 +282,7 @@ export const METRICS = [ { id: 'xpDiffAt10', label: '10분 경험치 차이', + description: '10분 시점 상대 라이너와의 경험치 격차입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -281,6 +298,7 @@ export const METRICS = [ { id: 'deathsBefore14', label: '14분 전 사망', + description: '라인전 구간인 14분 전 사망 횟수입니다. 낮을수록 안정적입니다.', direction: 'lowerIsBetter', kind: 'scalar', includeInVector: true, @@ -296,6 +314,7 @@ export const METRICS = [ { id: 'killParticipationBefore14', label: '14분 전 킬 관여율', + description: '14분 전 팀 킬에 얼마나 관여했는지 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -311,6 +330,7 @@ export const METRICS = [ { id: 'earlyWardsPerMin', label: '초반 분당 와드', + description: '초반 구간의 분당 와드 설치량으로 라인전 시야 습관을 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -326,6 +346,7 @@ export const METRICS = [ { id: 'objectivePreWardRate', label: '오브젝트 전 와드율', + description: '주요 오브젝트 전 사전 시야를 준비한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: true, @@ -340,6 +361,7 @@ export const METRICS = [ { id: 'eliteObjectiveParticipationRate', label: '에픽 오브젝트 관여율', + description: '드래곤, 전령, 바론 등 에픽 오브젝트에 관여한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: true, @@ -354,6 +376,7 @@ export const METRICS = [ { id: 'isolationTendency', label: '고립 성향', + description: '아군과 떨어진 위치에서 플레이한 정도입니다. 낮을수록 팀과 가깝습니다.', direction: 'lowerIsBetter', kind: 'scalar', includeInVector: true, @@ -369,6 +392,7 @@ export const METRICS = [ { id: 'teamfightFirstEngagementParticipationRate', label: '한타 첫 교전 관여율', + description: '한타가 열리는 첫 구간에 얼마나 빠르게 관여했는지 봅니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: true, @@ -383,6 +407,7 @@ export const METRICS = [ { id: 'teamfightCleanupKillParticipationRate', label: '한타 마무리 관여율', + description: '한타 후반 추격, 정리 킬, 마무리 과정의 관여율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: true, @@ -397,6 +422,7 @@ export const METRICS = [ { id: 'deathWithShutdownBountyGivenRate', label: '현상금 사망률', + description: '현상금을 가진 상태에서 사망한 비율입니다. 낮을수록 좋습니다.', direction: 'lowerIsBetter', kind: 'ratio', includeInVector: true, @@ -411,6 +437,7 @@ export const METRICS = [ { id: 'ccTimePerMinute', label: '분당 군중제어 시간', + description: '분당 적에게 제공한 군중제어 시간으로 교전 제어력을 봅니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: true, @@ -426,6 +453,7 @@ export const METRICS = [ { id: 'objectiveFightOpeningParticipationRate', label: '오브젝트 교전 개시 관여율', + description: '오브젝트 주변 교전이 시작될 때 관여한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -434,6 +462,7 @@ export const METRICS = [ { id: 'objectiveFightOpeningConvertedToObjectiveRate', label: '오브젝트 교전 개시 전환율', + description: '오브젝트 교전 개시가 실제 오브젝트 획득으로 이어진 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -442,6 +471,7 @@ export const METRICS = [ { id: 'preObjectivePitPresenceRate', label: '오브젝트 전 강가 선점률', + description: '오브젝트 등장 전 강가와 둥지 주변에 먼저 자리 잡은 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -450,6 +480,7 @@ export const METRICS = [ { id: 'preObjectivePickParticipationRate', label: '오브젝트 전 픽 관여율', + description: '오브젝트 직전 상대를 먼저 끊어낸 상황에 관여한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -458,6 +489,7 @@ export const METRICS = [ { id: 'deathFollowedByTeamLossRate', label: '사망 후 팀 손실률', + description: '본인 사망 뒤 팀이 오브젝트나 구조물을 잃은 비율입니다. 낮을수록 좋습니다.', direction: 'lowerIsBetter', kind: 'ratio', includeInVector: false, @@ -466,6 +498,7 @@ export const METRICS = [ { id: 'deathTradedForTeamAdvantageRate', label: '이득 교환 사망률', + description: '사망했지만 팀이 킬, 오브젝트, 구조물 이득을 얻은 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -474,6 +507,7 @@ export const METRICS = [ { id: 'deathWhileIsolatedFromNearestAllyRate', label: '고립 사망률', + description: '가장 가까운 아군과 멀리 떨어진 상태에서 사망한 비율입니다. 낮을수록 좋습니다.', direction: 'lowerIsBetter', kind: 'ratio', includeInVector: false, @@ -482,6 +516,7 @@ export const METRICS = [ { id: 'earlyDeficitRecoveryRate', label: '초반 열세 복구율', + description: '초반 불리함 이후 골드나 오브젝트 흐름을 회복한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -490,6 +525,7 @@ export const METRICS = [ { id: 'laneLeadConversionRate', label: '라인 리드 전환율', + description: '라인전 우위를 오브젝트, 포탑, 팀 이득으로 전환한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -498,6 +534,7 @@ export const METRICS = [ { id: 'roamConvertedToTeamAdvantageRate', label: '로밍 이득 전환율', + description: '로밍이 킬, 오브젝트, 구조물 이득으로 이어진 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -506,6 +543,7 @@ export const METRICS = [ { id: 'shutdownGoldCollectedPerGame', label: '게임당 현상금 획득 골드', + description: '게임당 상대 현상금을 회수해 얻은 평균 골드입니다.', direction: 'higherIsBetter', kind: 'scalar', includeInVector: false, @@ -521,6 +559,7 @@ export const METRICS = [ { id: 'platePresenceParticipationRate', label: '플레이트 위치 관여율', + description: '포탑 플레이트 압박이나 방어 상황에 위치해 관여한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false, @@ -529,6 +568,7 @@ export const METRICS = [ { id: 'objectiveBountyComebackParticipationRate', label: '오브젝트 현상금 역전 관여율', + description: '오브젝트 현상금을 활용한 역전 흐름에 관여한 비율입니다.', direction: 'higherIsBetter', kind: 'ratio', includeInVector: false,