Files

875 lines
61 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# persona-lenz — 플레이스타일 벡터 기반 LoL 개인 분석 앱 실행 플랜
작성일: 2026-07-02
이 문서는 Codex(또는 다른 코딩 에이전트)가 추가 질문 없이 구현에 착수할 수 있도록 작성된 실행 플랜이다.
아이디어 원본은 `docs/archive/lol_playstyle_mentor_app_codex_context.md`에 보존되어 있으며, **스택·아키텍처가 원본과 다른 부분은 항상 이 문서가 우선한다** (원본: pgvector/Python worker/Next.js → 확정: MongoDB Atlas/BullMQ/Vite-React).
---
## 1. 프로젝트 개요와 제약
### 1.1 한 줄 설명
> Riot API의 Match History / Timeline 데이터로 유저의 플레이스타일을 벡터화하고, 나와 비슷하게 플레이하지만 더 높은 티어인 유저를 찾아 비교해주며, 스타일에 맞는 챔피언 추천과 개선 피드백을 제공하는 LoL 학습 도구.
단순 전적 검색 사이트가 아니다. 핵심은 **데이터 정제 + feature engineering + vector search + 근거 기반 설명 생성**이다.
### 1.2 앱이 답해야 하는 질문
- 나는 어떤 스타일의 플레이어인가? 강점/약점은 무엇인가?
- 나와 비슷한데 더 높은 티어인 유저는 누구이고, 어떤 지표에서 차이가 나는가?
- 내 스타일에 맞는 챔피언은 무엇인가?
- 다음 게임에서 바로 시도할 수 있는 개선 행동은 무엇인가?
### 1.3 만들지 말아야 할 것 (금지 사항)
- 단순 KDA/승률 전적 검색 사이트
- MMR/ELO 계산기 ("당신의 숨겨진 MMR은 X입니다" 류 — Riot 정책 위반)
- 실시간 게임 중 정보 제공/의사결정 강제 오버레이
- Raw match JSON을 LLM에 통째로 던져 그럴듯한 코칭 문장을 생성하는 앱
### 1.4 Riot 정책 제약 (구현 시 상시 준수)
- Riot API key는 **서버 전용**. 코드/클라이언트 번들/git에 절대 포함하지 않는다. `SecretService`(Infisical) 경유로만 접근.
- 구조는 반드시 `Frontend → Backend → Riot API`.
- 실시간 게임 중 숨겨진 정보 제공 금지, 플레이어 의사결정 강제 표현 지양.
- Riot과 공식 제휴/승인된 것처럼 보이지 않게 하고, 법적 고지 문구를 서비스에 표시 (§9.4).
- 공식 문서 참조: https://developer.riotgames.com/apis , https://developer.riotgames.com/policies/general
### 1.5 LLM 사용 원칙 (MVP 5)
LLM은 **분석 엔진이 아니라 설명 엔진**이다. 백엔드가 계산한 metric/evidence JSON만 입력으로 받아 사람이 읽기 쉬운 피드백을 생성한다. 없는 지표를 만들어내면 안 되고, 모든 피드백은 metricId와 연결되어야 한다.
---
## 2. 확정 기술 스택과 아키텍처
| 레이어 | 기술 |
| ----------- | --------------------------------------------------------------------------------------------------- |
| Runtime | Node.js 26 |
| Backend | NestJS 11 (`apps/api`) — HTTP API + BullMQ 프로세서 동거 (단일 프로세스) |
| Frontend | Vite + React (`apps/web`) |
| DB | **MongoDB Atlas** (환경별 dbName 분리 — T0.2 참조). 벡터 검색은 Atlas Vector Search `$vectorSearch` |
| Queue/Cache | Redis + BullMQ |
| 공유 코드 | `packages/shared` (DTO, feature registry) |
| Secret | Infisical (`SECRET_SOURCE=infisical`, `project.yaml`에 projectId 있음) |
| 패키지 관리 | pnpm workspace 모노레포 |
### 2.1 데이터 흐름
```text
web (Riot ID 입력)
→ api: POST /api/analysis/request
→ BullMQ 큐 'analysis' (Redis)
→ 프로세서: Riot API 수집 → Atlas 저장 → feature 추출 → profile 생성
→ web: 잡 폴링 → 완료 시 GET /api/players/:puuid/analysis/latest → 대시보드
```
### 2.2 필요한 시크릿 (Infisical dev 환경에 등록 — 사용자가 수행)
- `RIOT_API_KEY` — Riot 개발자 포털 development key
- `MONGODB_CONNECTION_STRING` — Atlas 클러스터 SRV 연결 문자열
- `REDIS_URL` (또는 기존 `REDIS_ENDPOINT`/`REDIS_PASSWORD / REDIS_USERID` 조합 — `RedisModule`이 둘 다 지원)
- `ADMIN_API_TOKEN` — 운영용 백그라운드 잡 enqueue endpoint 보호용 bearer token
- `MONGODB_AUTO_INDEX=true` (dev만 — 스키마 선언 인덱스 자동 생성. prod는 인덱스 수동 생성)
로컬 인프라: MongoDB는 Atlas를 그대로 사용하므로 로컬 컨테이너 불필요. Redis가 로컬에 없으면 `compose.dev.yaml`(redis 단일 서비스)을 추가해 사용한다.
### 2.3 확장 시 분리 지점 (지금은 하지 않음)
- BullMQ 프로세서를 `apps/worker`로 분리 (큐 이름/잡 계약은 그대로 유지되도록 설계)
- rate limiter를 인메모리 → Redis 기반으로 전환 (§6.3)
---
## 3. Phase 0 — 선행 정리 작업
`apps/api/src/modules/global/database/`는 타 프로젝트(lolympus)에서 **스타일 참고용**으로 복사된 상태였다. 스타일(패턴)은 계승하고 도메인 내용물은 교체한다.
> **상태: T0.1~T0.3은 Claude가 구현 완료** (lolympus 파일 삭제, ConnectionService 수정, §4 스키마 8종 + 레지스트리 + 테스트). Codex는 **T0.4부터** 시작한다.
### T0.1 lolympus 도메인 파일 삭제 — 완료
- 삭제: `database/schema.ts`, `database/migrations/` 전체, `database/dev-seeds/` 전체, `database/auction-redis-schema.spec.ts`
- `database/connection.service.spec.ts`는 새 스키마 레지스트리에 맞게 재작성하거나 일단 삭제 후 T0.3에서 재작성
- 유지: `database/connection.service.ts`, `database/database.module.ts`, `database/types.d.ts`(ModelDefinition 타입 — 새 구조에 맞게 조정)
### T0.2 ConnectionService 수정 — 완료
`connection.service.ts`에서:
- `resolveMongoDbName`: `lolympus` → `persona-lenz`, `lolympus-staging` → `persona-lenz-staging`, `lolympus-dev` → `persona-lenz-dev`
- `resolveMongoAppName`: `lolympus-api:*` → `persona-lenz-api:*`
- `applyMongoosePerformancePlugin` import 제거 (observability 모듈은 이 레포에 없음. 필요해지면 나중에 도입)
- `tournamentModelDefinitions`/`TournamentModelTypes` 네이밍을 `modelDefinitions`/`ModelTypes`로 일반화
### T0.3 스키마 파일 구조 (agent-friendly 개선) — 완료
lolympus는 2,400줄 단일 `schema.ts`였다. 에이전트가 작은 단위로 안전하게 편집할 수 있도록 **컬렉션별 파일로 분리**했다:
```text
apps/api/src/modules/global/database/
connection.service.ts # 유지·수정 (T0.2)
database.module.ts # 유지
types.ts # ModelDefinition 타입
schemas/
common.ts # MongooseTimestamps, TeamPosition, TierInfo, NormalizationMethod
account.schema.ts
riot-match.schema.ts
player-match-feature.schema.ts
player-profile.schema.ts
analysis-job.schema.ts
metric-baseline.schema.ts
recommendation.schema.ts
champion-style-profile.schema.ts
index.ts # modelDefinitions 배열 + ModelTypes 맵 조립
```
파일당 규칙 (lolympus 스타일 계승):
- interface 정의 → SubSchema → 메인 `Schema` → `schema.index(...)` 선언을 한 파일에 콜로케이션
- 컬렉션명은 snake_case 단수 (`collection: 'riot_match'` 등), timestamps: true
- `HydratedDocument<T>` 타입 export
- `index.ts`의 `modelDefinitions`에 등록하면 `ConnectionService.getModel('riotMatch')`처럼 typed로 꺼내 쓸 수 있어야 한다
**완료 기준**: `pnpm --filter api build` 통과, `connection.service` 단위 테스트(레지스트리에 모든 모델이 등록되는지) 통과.
### T0.4 AppModule 배선
- `GlobalModule`에 `DatabaseModule`, `RedisModule` 등록 (현재 SecretModule만 등록되어 있음)
- 기본 NestJS 보일러플레이트(`app.controller/service`)는 헬스체크(`GET /api/health`)로 교체
- `main.ts`: global prefix `/api`, CORS는 사용하지 않고 web의 vite proxy로 처리 (§9.1)
---
## 4. MongoDB 스키마 설계 (MVP 1~4를 견디는 설계 — **구현 완료**)
> 이 섹션의 스키마는 Claude가 `apps/api/src/modules/global/database/schemas/`에 이미 구현했다. MVP 2(§11)·MVP 3(§12)의 요구사항 — timeline 파생물, `$vectorSearch` filter용 비정규화, percentile baseline, seed 계정 구분 — 을 미리 반영해 **이후 단계에서 스키마 마이그레이션 없이 필드가 채워지기만** 하도록 설계했다. Codex는 이 스키마를 수정하지 말고 사용한다 (변경이 필요하면 이유를 명시하고 사용자 확인).
모든 벡터 필드는 `number[]`이며 길이/순서는 `packages/shared`의 feature registry(§5)가 결정한다. 저장 시 `featureSchemaVersion`을 함께 기록해 registry 변경 시 재계산 대상을 식별한다.
공용 타입은 `schemas/common.ts`: `MongooseTimestamps`, `TeamPosition`(TOP/JUNGLE/MIDDLE/BOTTOM/UTILITY), `TierInfo`(+SubSchema), `NormalizationMethod`. Riot 라우팅 타입은 `modules/riot/riot.types.ts`(이미 생성됨 — T3에서 client가 여기에 추가된다).
인덱스는 mongoose 스키마에 선언되어 있고 `MONGODB_AUTO_INDEX=true`일 때만 자동 생성된다(ConnectionService 기본 autoIndex=false). **dev 환경 Infisical에 `MONGODB_AUTO_INDEX=true`를 넣고, prod는 인덱스 확정 후 수동 생성**한다.
### 4.1 `account`
```ts
interface Account extends MongooseTimestamps {
puuid: string; // unique index
gameName: string;
tagLine: string;
platformRoute: RiotPlatformRoute; // 'kr' 등
regionalRoute: RiotRegionalRoute; // 'asia' 등
profileIconId: number;
summonerLevel: number;
tiers: TierInfo[]; // league-v4 결과. queueType별 최신 스냅샷
tiersFetchedAt?: Date;
matchIdsFetchedAt?: Date;
lastAnalyzedAt?: Date;
// ---- MVP 3: 고티어 seed pool ----
isSeed: boolean; // default false. league-v4 리그 목록에서 수집된 계정
seedSource?: "challenger" | "grandmaster" | "master";
seedAddedAt?: Date;
lastSeedCollectedAt?: Date; // seed 수집 스케줄러가 다음 대상 선정에 사용
}
```
- index: `{ puuid: 1 }` unique, `{ gameName: 1, tagLine: 1 }`, `{ isSeed: 1, lastSeedCollectedAt: 1 }`
### 4.2 `riot_match` — lolympus 설계 계승 (검증된 구조)
```ts
interface RiotMatch extends MongooseTimestamps {
matchId: string; // unique index. 예: KR_7123456789
gameCreation: number;
gameDuration: number;
gameVersion?: string;
queueId?: number;
participantPuuids: string[];
raw: Record<string, unknown>; // Match-V5 원본 전체
timeline?: Record<string, unknown>; // MVP 2에서 채움
timelineFetchedAt?: Date;
fetchedAt: Date;
}
```
- index: `{ matchId: 1 }` unique, `{ participantPuuids: 1, gameCreation: -1 }`, `{ participantPuuids: 1, queueId: 1, gameCreation: -1 }`
### 4.3 `player_match_feature`
```ts
interface LaneOpponentRef {
puuid: string;
championId: number;
}
interface PlayerMatchFeature extends MongooseTimestamps {
matchId: string;
puuid: string;
queueId: number;
role: TeamPosition | "UNKNOWN"; // participant.teamPosition. 빈 값이면 'UNKNOWN' + confidence 감점
championId: number;
gameCreation: number;
gameDurationSec: number;
win: boolean;
patch: string; // gameVersion 앞 두 마디. 예: '26.13'
features: Record<string, number>; // metricId → 정규화 전 raw 값
normalized: Record<string, number>; // metricId → 0~1 정규화 값
vector: number[]; // registry 순서대로 normalized 값
featureSchemaVersion: number;
normalizationMethod: NormalizationMethod; // 'registry-baseline' | 'population-percentile'
confidence: number; // 0~1. remake/짧은 게임/role 불명 시 감점
// ---- MVP 2: timeline ----
timelineProcessed: boolean; // default false. timeline 지표 반영 여부 (재계산 대상 식별)
laneOpponent?: LaneOpponentRef; // diff 지표의 비교 대상
derived?: Record<string, unknown>; // 스칼라가 아닌 파생물: deathEvents[{t,x,y,zone}] 등
}
```
- index: `{ matchId: 1, puuid: 1 }` unique, `{ puuid: 1, queueId: 1, gameCreation: -1 }`, `{ featureSchemaVersion: 1, timelineProcessed: 1 }`(재계산 스캔), `{ role: 1, patch: 1, gameCreation: -1 }`(baseline 집계)
### 4.4 `player_profile`
`$vectorSearch`는 같은 컬렉션의 필드로만 filter할 수 있으므로, 검색 필터에 필요한 값(tier, isSeed 등)을 profile build 시점에 `account`에서 **비정규화**해 저장한다 (§12.3).
```ts
interface ChampionPoolEntry {
championId: number;
games: number;
wins: number;
}
interface PlayerProfile extends MongooseTimestamps {
puuid: string;
queueId: number; // MVP 1은 420 고정
mainRole: TeamPosition;
roleDistribution: Partial<Record<TeamPosition, number>>; // 게임 수 비율 0~1
sampleGameCount: number;
championPool: ChampionPoolEntry[]; // games 내림차순. re-rank의 championPoolSim에 사용
profile: Record<string, number>; // metricId → 집계된 0~1 값
vector: number[];
featureSchemaVersion: number;
normalizationMethod: NormalizationMethod;
confidence: number;
patches: string[]; // 집계에 포함된 패치 목록
lastMatchAt?: Date; // 집계에 포함된 가장 최근 게임 시각. recency re-rank용
// ---- MVP 3: $vectorSearch filter용 비정규화 (build 시점 account.tiers에서 복사) ----
tier?: string; // RANKED_SOLO_5x5 기준. 'MASTER' 등
division?: string; // 'I'~'IV'
leaguePoints?: number;
isSeed: boolean; // default false
}
```
- index: `{ puuid: 1, queueId: 1 }` unique, `{ isSeed: 1, mainRole: 1, tier: 1 }`(운영 조회용)
- **Atlas Vector Search 인덱스는 MVP 3에서 생성** (§12.3에 정의 JSON). MVP 1~2는 필드 저장만.
### 4.5 `analysis_job`
유저 분석뿐 아니라 MVP 2~3의 백그라운드 잡(재계산·seed 수집·baseline 계산)도 같은 컬렉션으로 추적한다.
```ts
type AnalysisJobType =
| "user-analysis" // MVP 1
| "feature-recompute" // MVP 2 (§11.4)
| "seed-collection" // MVP 3 (§12.1)
| "baseline-computation"; // MVP 3 (§12.2)
type AnalysisJobStatus = "queued" | "processing" | "completed" | "failed";
interface AnalysisJob extends MongooseTimestamps {
jobId: string; // unique. BullMQ job id와 동일하게
jobType: AnalysisJobType; // default 'user-analysis'
puuid?: string; // user-analysis는 resolve-account 후 채움. seed-collection은 처음부터
gameName?: string; // user-analysis에서만 사용
tagLine?: string;
platformRoute: RiotPlatformRoute;
queueId: number;
requestedMatchCount: number;
status: AnalysisJobStatus;
stage?: string; // 'resolve-account' | 'fetch-match-ids' | ...
progress: { fetchedMatches: number; totalMatches: number };
error?: string;
completedAt?: Date;
}
```
- index: `{ jobId: 1 }` unique, `{ puuid: 1, status: 1 }`, `{ jobType: 1, status: 1, createdAt: -1 }`
### 4.6 `metric_baseline` (MVP 3 — §12.2)
metricId × role × cohort × patch 조합별 인구 분위값. 정규화 v2(percentile rank)의 근거 데이터.
```ts
interface MetricBaseline extends MongooseTimestamps {
metricId: string;
role: TeamPosition;
cohort: "MASTER_PLUS" | "ALL";
patch: string; // '26.13' 또는 'ALL'
featureSchemaVersion: number;
sampleCount: number;
percentileBreakpoints: number[]; // p5~p95, 5% 간격 19개. 정규화 = 선형 보간 percentile rank
computedAt: Date;
}
```
- index: `{ metricId: 1, role: 1, cohort: 1, patch: 1, featureSchemaVersion: 1 }` unique
### 4.7 `recommendation` (MVP 3~5 공용 결과 캐시)
```ts
type RecommendationType =
| "similar-player" // MVP 3
| "champion-recommendation" // MVP 4
| "llm-feedback"; // MVP 5
interface Recommendation extends MongooseTimestamps {
puuid: string;
queueId: number;
type: RecommendationType;
featureSchemaVersion: number;
profileUpdatedAt: Date; // 어떤 프로필 기준으로 생성됐는지 — 프로필 갱신 시 stale 판정
result: Record<string, unknown>; // type별 결과 구조 (DTO는 shared에 정의)
evidence: Record<string, unknown>; // 근거 지표 스냅샷 (LLM 입력·UI 근거 표시)
generatedAt: Date;
}
```
- index: `{ puuid: 1, queueId: 1, type: 1, generatedAt: -1 }`
### 4.8 `champion_style_profile` (MVP 4)
```ts
interface ChampionStyleProfile extends MongooseTimestamps {
championId: number;
role: TeamPosition;
patch: string; // '26.13' 또는 'ALL'
source: "manual-taxonomy" | "derived-from-matches";
style: Record<string, number>; // metricId → 0~1
vector: number[];
featureSchemaVersion: number;
sampleGameCount?: number; // derived일 때만
}
```
- index: `{ championId: 1, role: 1, patch: 1, featureSchemaVersion: 1 }` unique
---
## 5. Feature Registry (`packages/shared`)
api(추출/집계)와 web(레이더 차트 축 라벨/순서)이 **같은 정의를 import**한다. 벡터 차원의 단일 진실 공급원.
### 5.1 구조
```ts
// packages/shared/src/feature-registry.ts
export const FEATURE_SCHEMA_VERSION = 1; // MVP 2에서 2로 bump (§11)
export type MetricDirection = "higherIsBetter" | "lowerIsBetter" | "neutral";
export type Role = "TOP" | "JUNGLE" | "MIDDLE" | "BOTTOM" | "UTILITY";
// 주의: DB 스키마의 TeamPosition(apps/api .../schemas/common.ts)과 값이 같아야 한다
export interface MetricDefinition {
id: string; // 예: 'killParticipation'
label: string; // UI 표시용 한국어 라벨
direction: MetricDirection; // 강점/약점 판정용. 벡터 값 자체는 반전하지 않는다
// scalar: 매치당 값 하나. ratio: 매치엔 {id}Numerator/{id}Denominator 저장,
// rate는 profile builder가 Σ분자/Σ분모로 계산 (§11.3)
kind: "scalar" | "ratio";
// 유사도 벡터·레이더 차트 포함 여부. insight 지표(§11.6~7)는 false
includeInVector: boolean;
// role별 min-max clipping baseline. 정규화: clamp((raw - min) / (max - min), 0, 1)
// ratio 지표는 rate가 이미 0~1이므로 baseline 생략 가능
baseline?: Record<Role, { min: number; max: number }>;
}
export const METRICS: MetricDefinition[] = [
/* 아래 5.2 순서대로. MVP 1은 전부 kind: 'scalar', includeInVector: true */
];
export const VECTOR_DIMENSION = METRICS.filter(
(metric) => metric.includeInVector,
).length;
```
### 5.2 MVP 1 지표 (12차원, match detail만으로 계산)
Match-V5 응답의 `info.participants[]`에는 `challenges` 객체(사전 계산 지표)가 포함된다. **challenges 필드가 있으면 우선 사용하고, 없으면 수동 계산으로 fallback**한다 (오래된 매치엔 일부 필드가 없을 수 있음).
| # | metricId | 계산식 (participant p, 분 = gameDuration/60) | challenges 대응 필드 |
| --- | ------------------------ | ------------------------------------------------ | ------------------------------------ |
| 1 | `kda` | (kills + assists) / max(deaths, 1) | `challenges.kda` |
| 2 | `killParticipation` | (kills + assists) / max(teamKills, 1) | `challenges.killParticipation` |
| 3 | `damageShare` | totalDamageDealtToChampions / 팀 합계 | `challenges.teamDamagePercentage` |
| 4 | `damagePerMin` | totalDamageDealtToChampions / 분 | `challenges.damagePerMinute` |
| 5 | `goldPerMin` | goldEarned / 분 | `challenges.goldPerMinute` |
| 6 | `csPerMin` | (totalMinionsKilled + neutralMinionsKilled) / 분 | — |
| 7 | `visionScorePerMin` | visionScore / 분 | `challenges.visionScorePerMinute` |
| 8 | `wardsKilledPerMin` | wardsKilled / 분 | — |
| 9 | `controlWardsPlaced` | 게임당 제어 와드 설치 수 | `challenges.controlWardsPlaced` |
| 10 | `deathsPerMin` | deaths / 분 (direction: lowerIsBetter) | — |
| 11 | `objectiveParticipation` | (dragon + baron + riftHerald takedown) / 게임 | `challenges.dragonTakedowns` 등 합산 |
| 12 | `soloKills` | 게임당 솔로킬 수 (공격성 proxy) | `challenges.soloKills` |
### 5.3 정규화와 그 한계 (문서화 필수)
- MVP 1: role별 baseline min-max clipping → 0~1. baseline 상수는 registry에 하드코딩하며 초기값은 대략적인 상식값으로 시작한다 (예: MIDDLE `csPerMin` min 4.0 / max 9.5, UTILITY `csPerMin` min 0 / max 2.5). 각 baseline에 `// TODO: MVP 3에서 인구 percentile로 교체` 주석을 남긴다.
- 원본 아이디어 문서 §6.4의 "role-specific percentile" 정규화는 비교 인구 데이터가 필요하므로 **MVP 3(고티어 pool 수집)에서 교체**한다.
- direction이 `lowerIsBetter`인 지표도 벡터에는 정규화 값을 그대로 저장한다 (플레이스타일 벡터는 "좋음"이 아니라 "성향 강도"를 표현). 강점/약점 판정 시에만 direction을 사용한다.
### 5.4 DTO
`packages/shared/src/dto/`에 API 요청/응답 타입 정의: `AnalysisRequestDto`, `AnalysisJobStatusDto`, `PlayerAnalysisDto` (§8의 스펙과 1:1). web은 이 타입으로 fetch 응답을 다룬다.
---
## 6. Riot 모듈 (`apps/api/src/modules/riot`)
### 6.1 `riot.types.ts`
```ts
export type RiotPlatformRoute = 'kr' | 'jp1' | 'na1' | 'euw1' | /* 필요 시 확장 */;
export type RiotRegionalRoute = 'asia' | 'americas' | 'europe' | 'sea';
export function toRegionalRoute(platform: RiotPlatformRoute): RiotRegionalRoute;
```
MVP 1은 `kr`/`asia`만 실사용하지만 타입은 위처럼 잡는다.
### 6.2 `riot-api.client.ts`
fetch 기반, API key는 `SecretService.get('RIOT_API_KEY')`. 메서드:
| 메서드 | endpoint | route |
| --------------------------------------------- | ----------------------------------------------------------- | -------- |
| `getAccountByRiotId(gameName, tagLine)` | `/riot/account/v1/accounts/by-riot-id/{gameName}/{tagLine}` | regional |
| `getSummonerByPuuid(puuid)` | `/lol/summoner/v4/summoners/by-puuid/{puuid}` | platform |
| `getLeagueEntriesByPuuid(puuid)` | `/lol/league/v4/entries/by-puuid/{puuid}` | platform |
| `getMatchIds(puuid, { queue, start, count })` | `/lol/match/v5/matches/by-puuid/{puuid}/ids` | regional |
| `getMatch(matchId)` | `/lol/match/v5/matches/{matchId}` | regional |
| `getMatchTimeline(matchId)` | `/lol/match/v5/matches/{matchId}/timeline` (MVP 2) | regional |
구현 시 실제 endpoint 경로는 Riot Developer Portal API Reference에서 재확인한다. 404(계정 없음)는 도메인 에러로 매핑해 API 응답에서 사용자 친화적으로 처리.
**Development key는 24시간마다 만료된다.** 401/403 응답은 재시도하지 말고 "API key 만료/무효" 도메인 에러로 매핑해 잡을 즉시 실패시키고, 에러 메시지에 키 갱신(개발자 포털 → Infisical `RIOT_API_KEY` 업데이트) 안내를 담는다.
### 6.3 Rate limiter
- development key 기준: 20 req/1s, 100 req/2min — 두 윈도우를 모두 지키는 인메모리 토큰버킷/슬라이딩 윈도우를 클라이언트 내부에 내장
- 429 응답 시 `Retry-After` 헤더를 존중해 대기 후 재시도 (최대 3회, exponential backoff)
- 5xx는 짧은 backoff 후 재시도, 4xx(429 제외)는 즉시 실패
- 단일 프로세스 전제의 인메모리 구현. **worker 분리 시 Redis 기반(기존 `RedisService` 활용)으로 교체해야 함을 주석으로 명시**
### 6.4 수집 캐시 규칙
- 이미 `riot_match`에 존재하는 matchId는 **재호출 금지** (저장 전 `exists` 확인)
- account/summoner/league는 `account` 문서의 `*FetchedAt`이 일정 시간(예: 1시간) 이내면 재호출 생략
---
## 7. Analysis 파이프라인 (`apps/api/src/modules/analysis`)
### 7.1 의존성 추가
- `bullmq`, `@nestjs/bullmq` 를 `apps/api`에 추가
- BullMQ는 자체 Redis 연결(ioredis)을 관리한다 — 기존 `RedisModule`(node-redis)과 **별개 연결**로 공존시킨다. 연결 옵션은 SecretService의 `REDIS_URL`에서 파싱해 BullMQ `connection`에 전달하는 factory를 만든다.
### 7.2 큐와 잡
큐 이름 `analysis`, 잡 하나가 전체 파이프라인을 순차 실행한다 (스테이지별 잡 분리는 하지 않는다 — MVP에선 단순함 우선). 각 스테이지 진입/진행 시 `analysis_job` 문서를 갱신한다.
```text
stage 1. resolve-account : account-v1 → puuid, summoner-v4, league-v4 → account upsert, job.puuid 기록
stage 2. fetch-match-ids : match-v5 ids (queue=420, count=요청값[기본 20, 최대 50])
stage 3. fetch-match-details: 미보유 matchId만 상세 조회 → riot_match 저장
제외: gameDuration < 300초(remake), queueId ≠ 420
진행률 progress.fetchedMatches/totalMatches 갱신
stage 4. extract-features : 각 매치에서 해당 puuid participant 추출 → §5 registry 기반 계산
→ player_match_feature upsert (featureSchemaVersion 포함)
confidence: 기본 1.0, teamPosition 빈 값이면 0.5, 20분 미만 게임 0.8
stage 5. build-profile : 최근 N게임 feature를 confidence 가중 평균으로 집계
mainRole = teamPosition 최빈값, championPool 집계
→ player_profile upsert, account.lastAnalyzedAt 갱신
완료: status=completed / 실패: status=failed + error 기록 (스테이지 단위 try/catch)
```
### 7.3 중복 요청 처리
동일 (gameName, tagLine)에 대해 `queued`/`processing` 상태의 잡이 이미 있으면 새 잡을 만들지 않고 기존 jobId를 반환한다.
### 7.4 멱등성과 엣지 케이스
- 모든 스테이지는 **재실행해도 안전**해야 한다 (BullMQ 재시도 대비): riot_match는 존재 확인 후 스킵, feature/profile은 upsert. BullMQ `attempts`는 2로 시작
- **랭크 게임이 없는 계정**: stage 2에서 matchId 0건이면 잡을 `failed`가 아니라 `completed`로 끝내되 profile을 만들지 않고, 결과 API가 "분석할 랭크 게임이 없음"을 반환하도록 한다
- **표본 부족** (유효 게임 5건 미만): profile은 생성하되 confidence를 크게 감점 (예: `sampleGameCount / 5` 상한 1.0)하고, 프론트에 "표본 부족" 경고를 표시한다
- 개별 매치 조회 실패는 잡 전체를 실패시키지 않는다 — 해당 matchId만 건너뛰고 progress에 반영, 마지막에 성공 매치 수 기준으로 진행
---
## 8. REST API (`apps/api`)
전역 prefix `/api`. DTO는 `packages/shared`에서 import.
### 8.1 `POST /api/analysis/request`
```jsonc
// 요청
{ "gameName": "Hide on bush", "tagLine": "KR1", "platform": "kr", "matchCount": 20 }
// 응답 202
{ "jobId": "...", "status": "queued" }
```
검증: gameName/tagLine 필수(공백 트림, 길이 제한 — Riot ID 규격 gameName 3~16자·tagLine 3~5자 안팎), matchCount 1~50 clamp, platform 기본 `kr`. NestJS 전역 `ValidationPipe` + class-validator DTO로 처리하고, 알 수 없는 필드는 strip한다.
### 8.2 `GET /api/analysis/jobs/:jobId`
```jsonc
{
"jobId": "...",
"status": "processing",
"stage": "fetch-match-details",
"puuid": "...", // resolve 후부터 포함 — web이 완료 시 이 값으로 결과 조회
"progress": { "fetchedMatches": 12, "totalMatches": 20 },
"error": null,
}
```
### 8.3 `GET /api/players/:puuid/analysis/latest`
```jsonc
{
"account": { "gameName": "...", "tagLine": "...", "profileIconId": 1234, "tiers": [ ... ] },
"profile": {
"mainRole": "MIDDLE",
"queueId": 420,
"sampleGameCount": 18,
"championPool": [ { "championId": 103, "games": 6, "wins": 4 } ],
"playstyle": { "kda": 0.62, "killParticipation": 0.71, ... }, // metricId → 0~1
"featureSchemaVersion": 1,
"confidence": 0.93
},
"strengths": [ { "metricId": "killParticipation", "value": 0.71 } ], // direction 반영 전체 지표, 강점 순 정렬
"weaknesses": [ { "metricId": "visionScorePerMin", "value": 0.22 } ], // direction 반영 전체 지표, 약점 순 정렬
"updatedAt": "..."
}
```
강점/약점 판정: direction이 `lowerIsBetter`인 지표는 (1 - value)로 뒤집어 정렬에 사용. 응답은 계산 가능한 모든 registry 지표를 포함하며, 대시보드는 label/description과 함께 표시한다. profile이 없으면 404.
---
## 9. Frontend (`apps/web`)
### 9.1 셋업
- Vite React 템플릿 잔재(hero.png, 데모 App.tsx 등) 정리
- 의존성 추가: `react-router-dom`, `recharts`, `@persona-lenz/shared`(workspace)
- `vite.config.ts`에 dev proxy: `/api` → `http://localhost:3000` (API에 CORS 설정 불필요)
- `@persona-lenz/shared`는 dist 소비 원칙을 유지한다. 현재 shared dist가 CommonJS로 빌드되므로 Vite dev 환경에서는 `optimizeDeps.include: ['@persona-lenz/shared']`로 사전 번들링해 브라우저 ESM named import 오류를 피한다.
### 9.2 화면 (3개)
1. **홈 `/`**: gameName + tagLine 입력 폼 → `POST /api/analysis/request` → `/analysis/:jobId`로 이동
2. **진행 `/analysis/:jobId`**: 2초 간격 폴링. stage/진행률 표시. `completed`가 되면 응답의 puuid로 `/players/:puuid`로 이동. `failed`면 에러와 재시도 버튼. 재시도는 홈에서 저장한 직전 `AnalysisRequestDto`를 `sessionStorage`에서 찾아 새 `POST /api/analysis/request`를 보낸다. 저장값이 없으면 홈으로 이동해 다시 입력하게 한다.
3. **대시보드 `/players/:puuid`**:
- 계정 요약 (Riot ID, 티어, mainRole, 분석 게임 수. 표본 부족 시 경고 배지 — §7.4)
- **레이더 차트** (recharts `RadarChart`): 축 순서/라벨은 shared feature registry의 `METRICS` 순서·`label` 사용, 값은 `profile.playstyle`
- 강점/약점 Top 3 카드 (metricId → registry label로 표시)
- championPool 요약 — championId → 이름/이미지는 **Data Dragon 정적 CDN**(`ddragon.leagueoflegends.com`)에서 web이 직접 fetch (API key 불필요·정책상 허용). 버전 목록 → 최신 버전 champion.json을 로드해 매핑, localStorage 캐시. 캐시는 best-effort로만 사용하며 storage 제한/쿼터 오류가 나도 CDN fetch 자체는 계속 시도한다.
### 9.3 스타일
MVP 1은 기능 검증이 목적이므로 과한 디자인 시스템 도입 없이 단정한 다크 테마 CSS 정도로 유지한다.
### 9.4 Riot 법적 고지 (푸터에 상시 표시)
> persona-lenz is not endorsed by Riot Games and does not reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. Riot Games and all associated properties are trademarks or registered trademarks of Riot Games, Inc.
외부 Data Dragon 이미지 요청에 `/players/:puuid` 경로가 referrer로 전달되지 않도록 web HTML에 `Referrer-Policy: no-referrer`에 해당하는 `<meta name="referrer" content="no-referrer" />`를 둔다.
### 9.5 MVP 1 구현 상태
- T0.4~T6 구현은 완료됐다. 각 작업은 커밋 단위로 분리되어 있으며 주요 커밋은 §10 표에 기록한다.
- T6 web 수동 E2E는 Codex 환경에서 임시 mock API + headless Chrome CDP로 검증했다: 홈, 진행, 실패 재시도 버튼, 대시보드 데스크톱, 대시보드 모바일, 콘솔 에러 없음. 실 Riot 계정 E2E는 §10.0의 MongoDB/Redis/Infisical 시크릿 체크리스트가 완료된 환경에서 §10.2 순서로 별도 실행해야 한다.
- MVP 1 결과 URL은 현재 스펙대로 `/players/:puuid`를 사용한다. PUUID는 안정적인 식별자이므로 공개 공유 URL/분석 로그/외부 referrer 정책을 바꾸는 단계에서는 opaque analysis id 또는 share token으로 교체할지 별도 제품 결정을 해야 한다.
---
## 10. 작업 순서와 검증
각 작업은 "빌드 통과 + 테스트 통과 + 커밋" 단위로 마무리한다. 커밋 메시지는 영어 명령형 한 줄.
### 10.0 시작 전 체크리스트
**사용자(사람)가 먼저 해야 하는 것** — 이것 없이는 E2E가 안 되지만, T0.4~T5 구현·단위 테스트는 진행 가능:
- [ ] MongoDB Atlas dev 클러스터 생성 (M0 가능)
- [ ] Infisical dev 환경에 등록: `RIOT_API_KEY`, `MONGODB_CONNECTION_STRING`, `REDIS_URL`, `MONGODB_AUTO_INDEX=true`
- [ ] 현재 작업 트리를 베이스 커밋으로 고정 (스키마·문서·의존성이 미커밋 상태)
**Codex 개발 환경 노트**:
- Infisical에 접근할 수 없는 환경에서는 `SECRET_SOURCE=env`로 실행하면 `SecretService`가 process.env를 그대로 사용한다 (`NODE_ENV=dev SECRET_SOURCE=env nest start` + 로컬 env 주입). 단위 테스트는 시크릿 불필요
- `@persona-lenz/shared`는 **dist를 통해 소비**된다 (`main: ./dist/index.js`). shared 수정 후 api/web에 반영하려면 `pnpm --filter @persona-lenz/shared build` 필요. 워치 개발 시 shared에 `tsc --watch`를 병행하거나 매 변경 후 재빌드
- shared에는 테스트 러너가 없다. registry 단위 테스트는 shared에 jest를 추가하거나, 간단히 **api의 jest에서 shared를 import한 spec**으로 작성해도 된다 (후자 권장 — 셋업 최소화)
| 순서 | 작업 | 완료 기준 |
| -------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
| ~~T0.1~3~~ | ~~Phase 0 정리 (§3)~~ + ~~DB 스키마 8종 (§4)~~ | **완료 — Claude가 구현** (스키마·레지스트리·테스트 포함) |
| ~~T0.4~~ | ~~AppModule 배선 (§3)~~ | **완료 — `34ae204`**. `pnpm build` 전체 통과, `GET /api/health` 200 |
| ~~T1~~ | ~~shared: feature registry + DTO (§5)~~ | **완료 — `1f2805b`**. shared 빌드 통과, registry 단위 테스트 |
| ~~T3~~ | ~~riot 모듈: client + rate limiter (§6)~~ | **완료 — `256d776`**. rate limiter/client fetch mock 테스트 |
| ~~T4~~ | ~~analysis 파이프라인 + BullMQ 배선 (§7)~~ | **완료 — `770c198`**. feature extraction/profile aggregation 테스트 |
| ~~T5~~ | ~~REST API 3종 (§8)~~ | **완료 — `e1164e0`**. e2e(supertest): 요청 검증, 404 케이스, Riot mock |
| ~~T6~~ | ~~web 3화면 (§9)~~ | **완료 — `ad1a775`**. `pnpm --filter web build` 통과, mock API 수동 E2E |
| ~~T7~~ | ~~문서 갱신~~ | **완료 — 본 문서 갱신**. MVP 1 실제 구현 상태와 차이점 반영 |
### 10.1 Feature extraction 테스트 fixture
- 개발 중 실제 Match-V5 응답 1건을 `apps/api/test/fixtures/match-v5-sample.json`으로 저장 (dev key로 1회 조회. **응답에 API key는 포함되지 않지만 puuid 등이 있으므로 fixture는 커밋 전 내용 확인**)
- fixture 기반으로 12개 지표 계산값을 스냅샷/명시값으로 검증. challenges 필드가 없는 케이스(필드 삭제한 사본)도 fallback 경로 테스트
### 10.2 수동 E2E 시나리오 (최종 검증)
1. §10.0 체크리스트(Infisical 시크릿 4종 포함) 완료 확인 → `pnpm start:api:dev` + `pnpm start:web:dev`
2. 실계정 Riot ID 입력 → 진행 화면에서 스테이지 전환 확인
3. 완료 후 대시보드: 레이더 차트 12축 렌더, 강점/약점 카드, championPool 표시
4. 같은 계정 재요청 시: 기존 잡 재사용(진행 중일 때) 또는 riot_match 재호출 없이 빠르게 완료(캐시 확인)
---
## 11. MVP 2 상세 — Timeline 기반 지표
DB 스키마가 이 단계를 미리 견디도록 상세화한 스펙이다. 구현은 MVP 1 완료 후 착수한다.
### 11.0 실데이터 검증 결과 (2026-07-02, `docs/archive/timeline-data.json`)
실제 KR 랭크 게임 타임라인 1건으로 필드를 검증했다. **이 파일을 `apps/api/test/fixtures/`로 복사해 timeline feature 테스트 fixture로 사용한다.**
확인된 것 (지표 설계에 사용 가능):
- `info.frames[]` 60초 간격. `participantFrames`: `position`, `totalGold`, `currentGold`, `xp`, `level`, `minionsKilled`, `jungleMinionsKilled`, **`timeEnemySpentControlled`**(누적 CC 시간), `damageStats`(누적 딜/탱), `championStats`
- `CHAMPION_KILL`: `position`, `bounty`, **`shutdownBounty`**, `killStreakLength`, `assistingParticipantIds`(**null 가능**), **`victimDamageReceived[]`**(가해자 `participantId`별 피해 내역 → killer/assist가 아니어도 damage contributor 판정 가능), `victimTeamfightDamageDealt/Received`
- `ELITE_MONSTER_KILL`: `position`, `killerId`, `killerTeamId`, `monsterType/SubType`, `bounty`
- `BUILDING_KILL`(position/laneType/towerType), `TURRET_PLATE_DESTROYED`(position/laneType, killerId 0 가능), `CHAMPION_SPECIAL_KILL`(KILL_FIRST_BLOOD 등), `DRAGON_SOUL_GIVEN`, **`OBJECTIVE_BOUNTY_PRESTART/FINISH`**(teamId — 열세 신호), `ITEM_PURCHASED/SOLD/DESTROYED/UNDO`, `SKILL_LEVEL_UP`, `GAME_END`
- `info.participants[]`에서 participantId(1~10) ↔ puuid 매핑
제약 (모든 지표 설계가 따라야 함):
1. **프레임이 60초 간격**이라 위치 기반 "presence/roam" 지표는 게임당 표본이 1~2 프레임 수준 → 매치 단위 값은 노이즈. 비율(rate) 지표는 반드시 §11.3의 분자/분모 누적 방식을 쓴다
2. **WARD_PLACED/WARD_KILL에 좌표가 없다** → 와드 위치 기반 지표 불가, 시간 창 근사만 가능
3. **리스폰/생존 인원 추적 데이터가 없다** → "인원 수 우위/열세" 판정은 부활 시간 추정이 필요해 부정확. 인원 조건이 들어간 지표는 채택하지 않는다 (골드 diff로 대체)
4. 임의 시점의 타 플레이어 위치는 앞뒤 프레임 선형 보간 근사
5. `assistingParticipantIds`가 null인 킬 존재 → 관여 판정은 항상 killer ∪ assists ∪ damage contributor(victimDamageReceived) 순으로 폭넓게
### 11.1 Timeline 수집
- `getMatchTimeline(matchId)` 결과를 `riot_match.timeline`에 저장 (`timelineFetchedAt` 기록, 미보유분만 호출)
- 분석 잡의 stage 3(fetch-match-details)에 timeline 조회를 추가 — 매치당 호출이 2배가 되므로 rate limit 예산에 반영
### 11.2 라인 상대(lane opponent) 매칭
- 상대 팀에서 같은 `teamPosition`인 participant를 라인 상대로 지정 → `player_match_feature.laneOpponent`에 저장
- 상대를 특정할 수 없으면(teamPosition 비정상) laneOpponent 없이 diff 지표를 결측 처리하고 confidence 0.7 이하로 감점
### 11.3 지표 2계층 구조: vector 지표 vs insight 지표
지표를 전부 유사도 벡터에 넣으면 희귀 이벤트 기반의 노이즈 축이 코사인 유사도를 오염시킨다. 두 계층으로 나눈다:
- **vector 지표** (`includeInVector: true`): 게임마다 안정적으로 관측되는 핵심 스타일 축. 벡터·레이더 차트·유사 유저 탐색에 사용
- **insight 지표** (`includeInVector: false`): 희귀 이벤트 기반 비율. 강점/약점 분석, 유사 유저와의 gap 비교, LLM evidence에 사용. 벡터에는 미포함
**ratio 지표 저장 규칙**: 게임당 발생 횟수가 적은 비율 지표는 매치 단위 rate가 0/1로 튄다. 매치의 `features`에는 `{metricId}Numerator` / `{metricId}Denominator`로 **횟수만** 저장하고, rate는 profile builder가 `Σ분자/Σ분모`로 계산해 `profile`에 저장한다. registry의 `kind: 'scalar' | 'ratio'`가 이를 결정한다 (§5.1).
### 11.4 공통 빌딩 블록 (구현 순서상 지표보다 먼저)
지표들이 공유하는 파생 구조. `derived`에 저장해 재사용·검증·MVP 5 evidence에 쓴다.
- **fightCluster**: CHAMPION_KILL 이벤트를 시간 ≤15초, 거리 ≤3000 기준으로 연결(transitive)해 묶은 교전. 참여자 = killer ∪ assists ∪ victim ∪ victimDamageReceived의 챔피언 participantId. opener = 첫 킬의 killer/assists/최대 피해 기여자. cleanup = 마지막 킬 ±5초 관여자. 3킬 이상이면 teamfight로 분류
- **objectiveWindow**: 드래곤/전령/바론 `ELITE_MONSTER_KILL` 시각 t 기준 `[t-120s, t+30s]`. 스폰 시각 계산(패치 의존)이 필요 없도록 처치 시각 기준으로 정의
- **advantageEvent 점수**: 창 내 팀 이득 비교용 가중치 상수 `ADVANTAGE_EVENT_WEIGHTS` — 킬 1.0, 플레이트 0.5, 타워 1.5, 드래곤/전령 1.5, 바론 3.0 (registry 옆에 정의, 튜닝 대상)
- **맵 존 상수**: SR 좌표 (0,0)~(약 15000,15000). 존: 양 팀 base, 라인 축 3개(축 ±1500), 강가 밴드, 정글 사분면 4개, 오브젝트 pit(드래곤/바론 반경 ~2500). 데스 위치 분류·roam 판정·pit presence에 공용
- **roamFrame**: 8~14분 프레임 중 내 위치가 (배정 라인 존 ∪ 우리 base) 밖인 프레임. **JUNGLE role은 roam 지표 전체를 결측 처리** (정글은 원래 전맵이 활동 영역)
- **derived 저장물**: `deathEvents: [{t, x, y, zone, shutdownBountyGiven, nearestAllyDistanceApprox}]`, `fightClusters` 요약, `objectiveWindows` 요약
### 11.5 vector 지표 (timeline 14개, MVP 1의 12개와 합쳐 `FEATURE_SCHEMA_VERSION = 2`, 총 26차원)
| # | metricId | kind | 계산 |
| --- | --------------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| 13 | `goldDiffAt10` | scalar | 10분 프레임에서 라인 상대와 totalGold 차이 |
| 14 | `goldDiffAt14` | scalar | 14분 프레임 동일 |
| 15 | `csDiffAt10` | scalar | (minionsKilled + jungleMinionsKilled) 차이 @10분 |
| 16 | `xpDiffAt10` | scalar | xp 차이 @10분 |
| 17 | `deathsBefore14` | scalar | t < 14분 CHAMPION_KILL 중 victimId == 나 |
| 18 | `killParticipationBefore14` | scalar | 14분 이전 (킬+어시) / 팀 킬 |
| 19 | `earlyWardsPerMin` | scalar | 14분 이전 WARD_PLACED(creatorId == 나) / 14 |
| 20 | `objectivePreWardRate` | ratio | objectiveWindow(우리 팀 처치) 중 `[t-60s, t]`에 내 와드 설치가 있었던 비율 (시간 근사) |
| 21 | `eliteObjectiveParticipationRate` | ratio | 우리 팀 ELITE_MONSTER_KILL 중 내가 killer/assist인 비율 |
| 22 | `isolationTendency` | scalar | 8~20분 프레임에서 가장 가까운 아군과의 평균 거리 (스플릿 성향) |
| 23 | `teamfightFirstEngagementParticipationRate` | ratio | teamfight fightCluster 중 내가 opener에 포함된 비율 — 교전을 여는 성향 |
| 24 | `teamfightCleanupKillParticipationRate` | ratio | teamfight fightCluster 중 내가 cleanup에 포함된 비율 — 마무리/추격 성향 |
| 25 | `deathWithShutdownBountyGivenRate` | ratio | 내 사망 중 `shutdownBounty > 0`으로 상대에게 현상금을 준 비율 — 리드 상태 리스크 관리 |
| 26 | `ccTimePerMinute` | scalar | `timeEnemySpentControlled` 최종 누적값 / 게임 분 — CC/유틸리티 기여 |
23~26은 원안 검토에서 승격한 것: 매 게임 안정적으로 관측되고(교전은 게임당 수 회, 사망·CC는 상시), 스타일 축으로서 해석이 명확하다. 특히 25는 `shutdownBounty` 필드가 실데이터에 확인되어 정확·단순하게 계산된다.
### 11.6 insight 지표 1차 (MVP 2에서 함께 구현, 벡터 미포함 — 별도 표기 없으면 kind: ratio)
| metricId | 분모 / 분자 | 해석 · 비고 |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `objectiveFightOpeningParticipationRate` | objectiveWindow 내 첫 fightCluster 수 / 그중 내가 opener인 수 | 오브젝트 타이밍에 물꼬를 트는 성향 (원안 2·6 통합) |
| `objectiveFightOpeningConvertedToObjectiveRate` | 내가 opener였던 objectiveWindow 교전 수 / 그중 이후 90초 내 우리 팀이 해당 오브젝트를 획득한 수 | 싸움을 열어 오브젝트로 연결 (원안 3) |
| `preObjectivePitPresenceRate` | 우리 팀 objectiveWindow 수 / 그중 처치 전 90초 프레임에서 내 위치가 pit·강가 반경 내였던 수 | 오브젝트 선점 포지셔닝 (원안 10). 프레임 1~2개 근사 |
| `preObjectivePickParticipationRate` | 우리 팀 objectiveWindow 수 / 그중 처치 전 120초 내 적 처형에 내가 관여한 수 | 오브젝트 전에 숫자 우위 창출 (원안 7 재정의 — 스폰 시각 불필요) |
| `deathFollowedByTeamLossRate` | 내 사망 수 / 그중 이후 60초 내 상대 advantageEvent 점수 > 우리 점수인 수 | 내 죽음이 팀 손해로 번지는 정도 (원안 11 단순화 — 가중합 Index 대신 비율) |
| `deathTradedForTeamAdvantageRate` | 내 사망 수 / 그중 ±30초 내 우리 advantageEvent 점수 > 상대 점수인 수 | 죽었지만 팀 이득을 만든 사망 (원안 16) |
| `deathWhileIsolatedFromNearestAllyRate` | 내 사망 수 / 그중 사망 시점(프레임 보간) 최근접 아군 거리 > 4000인 수 | 고립사 비율 (원안 17). 보간 근사 명시 |
| `earlyDeficitRecoveryRate` | goldDiffAt10 < -500인 게임 수 / 그중 20분 diff ≥ 0으로 복구한 게임 수 | 초반 열세 복구 (원안 13 단순화 — 게임당 0/1, 프로필 합산) |
| `laneLeadConversionRate` | goldDiffAt10 > +500인 게임 수 / 그중 10~20분 우리 팀 첫 타워 또는 첫 오브젝트에 내가 관여한 게임 수 | 라인 리드를 팀 이득으로 전환 (원안 8 단순화) |
| `roamConvertedToTeamAdvantageRate` | roamFrame 에피소드 수 / 그중 이후 90초 내 내가 관여한 advantageEvent 발생 수 | 로밍의 실효성 (원안 9). 60초 프레임 해상도 한계 명시 |
| `shutdownGoldCollectedPerGame` | 게임당 내가 killer인 킬의 shutdownBounty 합 (**kind: scalar**) | 현상금 사냥 성향 — vector 지표 25(`deathWithShutdownBountyGivenRate`)의 쌍 |
| `platePresenceParticipationRate` | 우리 팀 TURRET_PLATE_DESTROYED 수 / 그중 직전 프레임 내 위치가 해당 라인 존 내였던 수 | 플레이트 관여 — killerId가 0인 플레이트가 있어 위치 근사가 유일한 방법 |
| `objectiveBountyComebackParticipationRate` | OBJECTIVE_BOUNTY 활성(우리 팀 열세 공식 신호) 구간의 우리 팀 advantageEvent 수 / 그중 내 관여 수 | comeback_resilience 축 — Riot 공식 열세 신호를 데이터 근거로 사용 |
### 11.7 insight 지표 2차 (백로그 — 1차 안정화 후)
| metricId | 요약 | 비고 |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `lateCarryPickoffParticipationRate` | 20분 이후 적 딜러 상위 2명(프레임 damageStats 기준) 사망 중 내가 killer/assist/damage contributor | 원안 4 수정 — "고립" 조건은 보간 근사라 제외 |
| `pickoffConvertedToMajorObjectiveRate` | 위 pickoff 후 90초 내 우리 팀 바론/드래곤/타워 획득 비율 | 원안 5 |
| `deficitFightInitiationWinRate` | 직전 프레임 팀 골드 diff < -1000에서 내가 opener인 fightCluster 중 킬 교환 우위로 끝난 비율 | 원안 1 단순화 — 인원/오브젝트 압박 판정 제외(§11.0 제약 3) |
| `crossMapTradeAnswerRate` | 상대 오브젝트/타워 획득 후 90초 내 우리 팀 반대편 이득에 내가 관여한 비율 | 원안 15 |
| `sidePressureConvertedToMapAdvantageRate` | 14~25분 사이드 고립 프레임 묶음 중 90초 내 팀 이득으로 연결된 비율 | 원안 12 단순화 — "적 2명 근접"은 보간 근사로만 |
| `preObjectiveGroupingRate` | objectiveWindow 전 90초 프레임에서 팀 중심(아군 평균 위치)과 거리 < 2500인 비율 | 원안 19 — pitPresence(선점)와 구분되는 합류 타이밍 |
| `roamLaneResourceLossIndex` | roam 에피소드 전후 2분 내 CS/XP 증가량을 라인 상대와 비교한 손실 평균 | 원안 14 — roam 판정 위 이중 근사라 2차 |
| `visionActionConvertedToTeamAdvantageRate` | 내 WARD_PLACED/WARD_KILL 후 90초 내 우리 팀 advantageEvent 발생 비율 | 원안 22 — 와드 좌표 없음, 시간 근사 |
### 11.8 원안 대비 조정 내역 (검토 근거 기록)
- **기각: `postRecallTempoReturnToMapScore`** — 귀환 proxy(ITEM_PURCHASED 묶음)가 사망 후 구매와 구분되지 않고, 합성 가중합이라 설명 곤란. 필요해지면 "사망이 아닌데 base 존에서 구매" 조건으로 재설계
- **기각: 인원 우위/열세 조건 전반** — 리스폰 추적 데이터가 없어 부활 시간 추정이 필요 (§11.0 제약 3). 골드 diff 조건으로 대체
- **합성 Score/Index → 단순 비율로 분해** (`earlyLaneLeadConvertedToMidGameAdvantageScore`, `earlyDeficitRecoveredByMidGameScore`, `deathCausedFollowUpTeamLossIndex`, `sideLanePressureConvertedToMapAdvantageScore`): 임의 가중합은 percentile 정규화·근거 제시(§14)와 충돌한다. 가중치가 필요한 부분은 `ADVANTAGE_EVENT_WEIGHTS` 상수 하나로 수렴
- **통합**: 원안 2+6 → `objectiveFightOpeningParticipationRate`, 원안 7 → 처치 시각 기준 재정의(스폰 시각은 패치 의존이라 회피)
- **승격**: 교전 opener/cleanup, shutdown 사망, CC 시간은 vector 지표로 (관측 빈도·해석 명확성 기준)
### 11.9 버전 bump와 재계산
- registry에 지표 추가 → `FEATURE_SCHEMA_VERSION` 2로 bump. 레이더 차트는 vector 지표 26축이 아니라 **UI 그룹(라인전/교전/오브젝트/시야/리스크) 단위로 묶어 표시**하는 것을 권장
- `analysis_job.jobType = 'feature-recompute'` 잡: `player_match_feature` 중 `featureSchemaVersion < 2` 또는 `timelineProcessed = false`인 문서를 대상으로 재계산 → 이후 해당 puuid들의 `player_profile` 재빌드
- timeline이 없는 오래된 매치는 MVP 2 지표를 결측으로 두고 confidence로 반영 (수집 불가능한 과거 데이터를 억지로 채우지 않는다)
---
## 12. MVP 3 상세 — 고티어 pool · percentile 정규화 · 유사 유저 탐색
> **컨셉 (2026-07-03 재정의)**: 이 기능은 "멘토 매칭"이 아니라 **나와 플레이스타일이 비슷한 유저 찾기**다. 목적은 따라 할 상위 티어 유저를 지정해주는 것이 아니라, "스타일은 비슷한데 왜 저 유저는 점수(티어)가 더 높거나/낮은가"라는 인사이트를 주는 것. 따라서 후보를 티어로 거르지 않고 유사도 중심으로 랭킹하며, 티어 관계(tierComparison)와 지표 우위(양방향)를 함께 제공한다. seed pool(§12.1)은 필터 조건이 아니라 **비교 후보군의 주 공급원**이다.
### 12.1 고티어 seed pool 수집
- league-v4 `challengerleagues|grandmasterleagues|masterleagues /by-queue/RANKED_SOLO_5x5`(platform route)로 엔트리 확보
- 초기 목표 pool: **150명** (Challenger 50 / GM 50 / Master 무작위 50), 각 최근 **30게임**
- rate limit 예산 (dev key 100req/2min): 유저당 약 1(ids) + 30×2(detail+timeline) ≈ 61 호출 → 150명 ≈ 9,150 호출 ≈ 3~4시간. 단 **고티어끼리는 같은 매치에 자주 등장하므로 `riot_match` 중복 제거로 실호출이 크게 줄어든다.** 백그라운드로 하룻밤 돌리는 전제. production key 승인 시 확대
- `account`에 `isSeed: true`, `seedSource`(challenger/grandmaster/master), `seedAddedAt`, `lastSeedCollectedAt` 기록
- 별도 저우선순위 BullMQ 큐 `seed-collection`(concurrency 1)로 수집. 유저 분석 잡(`analysis`)이 항상 우선하도록 rate limiter를 공유
- seed 유저도 **동일한 파이프라인**(stage 3~5)으로 `player_match_feature`/`player_profile` 생성 — 별도 코드 경로를 만들지 않는다
- 운영 트리거: `POST /api/admin/seed-collection/request` with `Authorization: Bearer <ADMIN_API_TOKEN>`. body 예시:
```json
{
"platform": "kr",
"sourceLimits": {
"challenger": 0,
"grandmaster": 50,
"master": 0
}
}
```
`sourceLimits`를 생략하면 challenger/grandmaster/master 각각 기본 50명, 특정 source를 끄려면 명시적으로 `0`을 보낸다.
- **스토리지 예산 주의**: timeline 원본은 경기당 약 2MB(실측 2.3MB)라 seed 수집(중복 제거 후 수천 경기)이면 수 GB로 Atlas M0(512MB)를 초과한다. MVP 1~2(개인 계정 수십 경기)는 M0로 충분하지만, **MVP 3 착수 전에 ① 클러스터 상향 또는 ② feature 추출 완료 후 `riot_match.timeline` 원본 삭제(derived만 보존) 정책을 결정**해야 한다. ②를 대비해 재계산 잡은 timeline 부재를 결측으로 처리하도록 이미 설계되어 있다(§11.9)
### 12.2 Percentile 정규화 도입 (§5.3 TODO 해소)
- `metric_baseline` 컬렉션(§4.6)에 metricId × role × cohort × patch별 **분위값 19개**(p5~p95, 5% 간격)를 저장
- 계산: `jobType = 'baseline-computation'` 잡이 seed 유저들의 `player_match_feature.features`(raw 값)를 집계해 생성. cohort는 `MASTER_PLUS`부터, 데이터가 쌓이면 `ALL` 추가
- 정규화 v2: raw 값 → breakpoints 선형 보간으로 percentile rank(0~1). registry의 min-max baseline은 **cold start fallback**으로 유지
- 적용 결과는 `normalizationMethod: 'population-percentile'`로 기록. 유저 프로필과 seed 프로필이 **같은 baseline으로 정규화됐을 때만** 벡터 비교가 유효하므로, baseline 전환 시 전체 `player_match_feature` 재정규화 + `player_profile` 재빌드 잡을 돌린다
### 12.3 Atlas Vector Search 인덱스
`player_profile` 컬렉션에 생성 (Atlas UI 또는 Admin API). **numDimensions는 생성 시점의 `VECTOR_DIMENSION`(MVP 2 완료 기준 26 — vector 지표만, insight 지표 제외)과 일치**시키고, 차원이 바뀌면 인덱스를 재생성한다:
```json
{
"name": "player_profile_vector_index",
"type": "vectorSearch",
"fields": [
{ "type": "vector", "path": "vector", "numDimensions": 26, "similarity": "cosine" },
{ "type": "filter", "path": "mainRole" },
{ "type": "filter", "path": "queueId" },
{ "type": "filter", "path": "tier" },
{ "type": "filter", "path": "isSeed" },
{ "type": "filter", "path": "sampleGameCount" },
{ "type": "filter", "path": "featureSchemaVersion" }
]
}
```
filter로 쓰는 필드(tier, isSeed 등)가 `player_profile`에 **비정규화되어 있어야** `$vectorSearch` 단계에서 join 없이 거를 수 있다 — §4.4 스키마가 이를 전제한다.
### 12.4 유사 유저 탐색 파이프라인
```text
1. 내 player_profile 조회 (없으면 404)
2. $vectorSearch:
queryVector = 내 vector, numCandidates = 200, limit = 50
filter: { mainRole: eq 내 mainRole, queueId: eq 420,
sampleGameCount: gte 20, featureSchemaVersion: eq 현재 버전 }
※ tier/isSeed 필터 없음 — "비슷한 유저"가 목적이므로 어느 티어든 후보.
(인덱스의 tier/isSeed filter 필드는 유지 — 추후 옵션 필터용)
3. 앱 레벨 re-rank (Top 50 → Top K):
final = 0.70 * styleSim # $vectorSearch score (cosine) — 유사도가 랭킹을 지배
+ 0.18 * championPoolSim # 양쪽 championPool 상위 5개 Jaccard
+ 0.12 * recencyScore # lastMatchAt 지수 감쇠 (half-life 14일)
- lowSamplePenalty # sampleGameCount < 30이면 0.1
(tierScore 없음 — 티어는 랭킹 요소가 아니라 인사이트. mainRole은 filter로 보장)
4. 각 유사 유저에 대해 비교 계산:
- tierComparison: 내 tier 대비 higher | same | lower | unknown
- 비슷한 지표 Top 3: |내 profile[m] - 상대 profile[m]| 최소
- 상대가 앞서는 지표 Top 3 (strongerMetrics): direction 반영 gap 최대 (lowerIsBetter는 반전)
- 내가 앞서는 지표 Top 3 (weakerMetrics): 위와 대칭 — 상대가 나보다 낮은 티어일 때의 인사이트
5. recommendation 컬렉션에 캐시 (type: 'similar-player', profileUpdatedAt 기록)
→ 내 프로필이 갱신되면 stale로 보고 재계산
```
### 12.5 API / UI
- `GET /api/players/:puuid/similar-players?limit=10` — 캐시 있으면 캐시, stale이면 재계산
- 응답 항목: similarityScore, finalScore, Riot ID(표시용), tier, tierComparison, mainRole, mainChampions(top 3), sampleGameCount, similarMetrics[3], strongerMetrics[3], weakerMetrics[3]
- 대시보드에 "나와 비슷한 플레이어" 테이블 추가. 화법: "따라 하라"가 아니라 "나와 비슷한 이 유저는 이런 지표에서 차이가 난다" 유지 (§1.3, §14). 상대가 높은 티어면 strongerMetrics가, 낮은 티어면 weakerMetrics가 인사이트의 중심
- 유저 Riot ID 표시는 공개 데이터이지만, 표시 형식은 전적 사이트 관례 수준으로 유지
---
## 13. MVP 4~5 로드맵 (개요 — 착수 시 상세화)
### MVP 4: 챔피언 추천
- 챔피언 스타일 벡터: 초기엔 수동 taxonomy(주요 챔피언 ~60개), 이후 seed 유저 match data 기반 자동화. **스키마는 `champion_style_profile`(§4.8)로 이미 준비됨**
- Fit(현 스타일 유사) / Growth(약점 보완) / Stretch(폭 확장) 3종 추천 + 근거(유사도, 유사 유저 pool 등장 빈도) 표시. 결과는 `recommendation`(type: 'champion-recommendation')에 캐시
- Data Dragon 연동 (챔피언 이름/이미지, 패치별 static data)
### MVP 5: LLM 피드백
- `FeedbackGenerator` 인터페이스로 provider 추상화 (provider는 이 시점에 결정)
- 입력: 백엔드가 만든 evidence JSON만 (user profile 지표, 유사 유저와의 gap Top-N, `derived`의 데스 위치 요약). raw match JSON 입력 금지
- 출력: strict JSON schema 검증. 모든 피드백 항목은 metricId 참조 필수, 검증 실패/LLM 장애 시 rule-based fallback 문장 사용. 결과는 `recommendation`(type: 'llm-feedback')에 캐시
- 화법 규칙: 비난 금지, "다음 5게임에서 실험할 행동" 형태, 실시간 지시·MMR 추정 표현 금지
---
## 14. 부록: 원본 문서에서 계승하는 판단 기준
- **데이터 품질이 AI보다 중요하다.** feature extraction이 틀리면 앱 전체 신뢰가 무너진다. 파이프라인 안정화가 항상 우선.
- **비교군 설계가 핵심이다.** 전체 평균이 아니라 같은 포지션·유사 챔피언·비슷한 패치·충분한 sample size 기준으로 비교한다.
- **결과는 항상 근거와 함께.** "운영이 약합니다"(X) → "10분 골드 리드 게임에서 첫 전령 관여율이 유사 유저 그룹보다 낮습니다"(O).
- **추천은 단정하지 않는다.** "이 챔피언을 해야 티어가 오릅니다"(X) → "현재 스타일과 잘 맞을 가능성이 높은 후보입니다. 다음 10게임에서 비교해보세요"(O).