Files
lolympus-tournament-support/Riot-캐싱-Phase2-플랜.md
T
2026-04-25 11:49:21 -07:00

587 lines
23 KiB
Markdown

# Riot 캐싱 Phase 2 플랜
> **대상**: codex가 이어서 진행 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-25
> **선행 작업**: dakao NATS 통합, RiotAccountEnrichmentService(force=true 동기 호출, summoner/league/mastery v4) 1차 구현 완료
---
## 1. Context
dakao 카카오톡 명령(`!내전 신청 ...`) 이 들어오면 라이엇 ID를 검증·등록하고, 동시에 summoner v4 / league v4 / champion-mastery v4 데이터를 가져와 `User.riotAccounts[*]` 임베딩에 캐싱하는 1차 구현이 끝난 상태입니다.
이 플랜은 그 위에 다음을 더합니다.
1. **community별 default platform 지정** + region/by-puuid 기반 자동 보정
2. **champion-mastery top 10** 으로 좁히고 스키마를 Riot DTO 그대로
3. **league 변동 시 tierHistory 자동 누적**
4. **사용자 수동 갱신 엔드포인트 + 한가한 시간대 스케줄러**
5. **신선도 표시(API 응답에 `*FetchedAt` 노출)**
6. **무거운 필드(`championRecords`, `tiers`)는 list/find 쿼리에서 projection 으로 잘라내기**
7. **동일 puuid 동시 enrichment dedup**
8. **v4 서비스 응답 파서 단위 테스트**
비목표:
- Rate limit 글로벌 throttle (token bucket / Redis) — Phase 3
- OpenSearch / Slack 운영 알림 — Phase 3
- 백오피스 UI — 별도 트랙
---
## 2. 결정된 설계 사항
### 2.1 Riot Schema 우선 (Data Dragon 호환)
기존 `ChampionMasteryEntry`, `TierInfo`, `TierHistoryEntry` 를 Riot v4 응답 그대로 매칭하도록 재정의합니다.
**현재 (수정 전)**
```ts
export interface ChampionMasteryEntry {
championId: string; // ← Riot 은 number
championName?: string; // ← Riot 응답에 없음
level: number; // ← championLevel
points: number; // ← championPoints
}
export interface TierInfo {
queueType: string;
tier: string;
rank: string;
leaguePoints: number;
wins: number;
losses: number;
fetchedAt: Date;
}
```
**목표 (수정 후)**
```ts
// Riot Champion-Mastery-V4 DTO 그대로
export interface ChampionMasteryEntry {
puuid: string;
championId: number;
championLevel: number;
championPoints: number;
lastPlayTime?: number;
championPointsSinceLastLevel?: number;
championPointsUntilNextLevel?: number;
markRequiredForNextLevel?: number;
tokensEarned?: number;
championSeasonMilestone?: number;
milestoneGrades?: string[];
nextSeasonMilestone?: Record<string, unknown>;
}
// Riot League-V4 entries DTO + 우리 측 fetchedAt
export interface TierInfo {
leagueId: string;
queueType: string;
tier: string;
rank: string;
puuid: string;
leaguePoints: number;
wins: number;
losses: number;
veteran?: boolean;
inactive?: boolean;
freshBlood?: boolean;
hotStreak?: boolean;
miniSeries?: Record<string, unknown>;
fetchedAt: Date;
}
// 시점별 tier 스냅샷
export interface TierHistoryEntry {
queueType: string;
tier: string;
rank?: string;
leaguePoints?: number;
wins?: number;
losses?: number;
recordedAt: Date;
// 시즌 단위 통계 / peak (옵션)
season?: string;
peakTier?: string;
peakRank?: string;
}
```
`championRecords` 는 챔피언별 *집계 데이터(향후 매치 분석)* 용으로 유지하되, **mastery 원본은 더 이상 `championRecords` 에 중복 저장하지 않습니다.** mastery 자체가 이제 Riot DTO 형태이기 때문입니다.
기존 schema 의 `RiotAccount.championRecords` 와 `RiotAccount.championRecordsFetchedAt` 는 그대로 둡니다 (다른 용도).
### 2.2 community 별 default platform
```ts
export interface Community extends MongooseTimestamps {
// ...
riotPlatform?: RiotPlatformRoute; // default 'kr'
riotRegion?: RiotRegionalRoute; // default 'asia'
}
```
- platform 기본 `kr`, region 기본 `asia` 는 코드 상 fallback. 명시 지정 시 community 설정값 우선.
- enrichment / lookup 시 community 의 platform 을 사용.
- 추가로 puuid 만 있는 상황(예: 다른 community 매치 import)에서는 region/by-puuid 로 platform 보정.
### 2.3 region/by-puuid 자동 보정
> `GET https://{regional}.api.riotgames.com/riot/account/v1/region/by-game/lol/by-puuid/{puuid}` → `{ puuid, game, region }`
- 응답의 `region` 이 platform 코드 (`kr`, `na1`, …)
- 사용 시점: community 의 platform 과 puuid 의 실제 platform 이 다른지 의심될 때 (예: 처음 등록 시, summoner v4 404 발생 시)
- 새 서비스: `RiotAccountService.getRegionByPuuid(puuid, options)`
- enrichment fallback 정책: summoner v4 가 404 면 region/by-puuid 호출해서 platform 보정 후 한 번 더 시도, 그래도 실패면 failed 처리
### 2.4 mastery top 10
- 엔드포인트 변경: `/lol/champion-mastery/v4/champion-masteries/by-puuid/{puuid}/top?count=10`
- 저장 상한 10. `MASTERY_LIMIT = 10`.
- `RiotChampionMasteryService.getTopByPuuid(puuid, { platform, count })` 신규 메서드. 기존 `getByPuuid` 는 leftover/내부용으로 유지하거나 삭제 (사용처 확인 후 결정).
### 2.5 tierHistory 누적 규칙
- enrichment 가 league entries 를 갱신할 때, **queueType 별로 가장 최근 history entry 와 비교**하여 다음 중 하나라도 다르면 history 에 push:
- `tier`, `rank`
- `leaguePoints` 변화 (옵션 — 너무 잦으면 noise. 1차에선 tier/rank 변화만 추적)
- 1차 결정: **tier 또는 rank 가 변하면 push**. lp 변화는 history 에 안 남김.
- 신규 등록 시(history 비어있음)는 첫 league fetch 결과를 그대로 history 에 1건 push.
- `recordedAt = new Date()`.
- queueType 외 다른 분류는 도입하지 않음. season 추적은 별도 작업.
### 2.6 신선도 노출 (`*FetchedAt`)
API 응답(`GET /users/:id`, `/me`, `/communities/:id/matches/:id` 등)에 RiotAccount 가 포함될 때 다음 필드를 함께 노출:
- `tiers[*].fetchedAt`
- `championMasteriesFetchedAt`
- `revisionDate` (summoner)
- `championRecordsFetchedAt`
스키마 상 이미 존재하므로 변경 불필요. 단, **list 쿼리에서는 무거운 raw 필드(`championRecords`, `championMasteries[*].milestoneGrades` 등) 는 projection 으로 제외**. (2.8 참조)
### 2.7 수동 갱신 + 스케줄러
**HTTP 엔드포인트**
```
POST /users/me/riot-accounts/:puuid/refresh
Body: { force?: boolean, platform?: RiotPlatformRoute }
Auth: 본인 또는 admin
Response: EnrichResult
```
- 본인 또는 community admin 이상만 허용.
- `force = true` 면 TTL 무시.
- platform 지정 시 community default 무시.
**스케줄러**
- NestJS `@nestjs/schedule` (cron) 도입.
- 작업명: `RiotAccountRefreshScheduler`
- 실행 주기: 매일 KST 04:00 ~ 06:00 사이에 chunked 실행
- 대상 선정:
- `tiers[*].fetchedAt` 가 24h 초과 또는 비어있는 RiotAccount
- 한 batch 당 최대 200건, batch 간 5초 간격
- enrichment 호출 시 `force = false` (TTL 기반)
- per-batch try/catch + 실패 카운터 로그
- `@Cron('0 4 * * *')` 단일 트리거로 시작 → 추후 batch 분산은 Phase 3 에서 보강
### 2.8 list/find projection 정책
`apps/api/src/modules/global/database/projection.ts` 신설하여 공통 projection 상수를 모음.
```ts
// 매치 리스트, /me 등에서 RiotAccount 의 무거운 필드를 잘라낸다
export const RIOT_ACCOUNT_LIGHT_PROJECTION = {
'riotAccounts.championRecords': 0,
'riotAccounts.championRecordsFetchedAt': 0,
// championMasteries 자체는 살리되 milestoneGrades 등 무거운 nested 는 protected list 에서만 fetch
} as const;
```
- 적용 대상: `MatchService.list`, `UserController.list`, `MatchController.listMatches` 등
- 단건 조회(`getById`, `/me`) 는 풀 데이터 포함
### 2.9 동일 puuid 동시 enrichment dedup
**채택 방식**: in-memory `Map<puuid, Promise<EnrichResult>>` (단일 인스턴스 dedup)
```ts
private inFlight = new Map<string, Promise<EnrichResult>>();
public enrichRiotAccount(params): Promise<EnrichResult> {
const key = params.puuid;
const existing = this.inFlight.get(key);
if (existing) return existing;
const promise = this.doEnrich(params).finally(() => {
this.inFlight.delete(key);
});
this.inFlight.set(key, promise);
return promise;
}
```
이유:
- 카카오 신청 빈도가 낮아 분산 락까지 필요 없음.
- 동일 인스턴스 내 race(동시 신청)만 막아도 90%의 중복 호출 절감.
- 멀티 인스턴스 환경 dedup 은 Phase 3 (Redis SET NX) 에서.
**대안 비교 (참고)**
| 방식 | 장점 | 단점 |
| --- | --- | --- |
| in-memory Map | 의존성 없음, 빠름 | 멀티 인스턴스 미지원 |
| Mongo `findOneAndUpdate` 락 | 의존성 없음, 분산 가능 | 실패 시 락 만료 처리 복잡, 추가 필드 필요 |
| Redis SET NX EX | 분산 / TTL 자연스러움 | Redis 인프라 필요 |
### 2.10 v4 파서 단위 테스트
- `riot-summoner.service.spec.ts`
- `riot-league.service.spec.ts`
- `riot-champion-mastery.service.spec.ts`
각각 정상 응답 / 누락 필드 거부 / 빈 배열 / 타입 불일치 거부 케이스.
---
## 3. 실행 단계 (codex 진행 순서)
작업 단위는 PR 단위로 쪼갤 수 있도록 분리되어 있습니다. 단계 간 의존성이 있는 부분은 명시.
### Step 1. 스키마 재정의 (TierInfo / ChampionMasteryEntry / TierHistoryEntry)
**파일**: `apps/api/src/modules/global/database/schema.ts`
1. `TierInfo`, `TierHistoryEntry`, `ChampionMasteryEntry` 인터페이스 위 2.1 정의로 교체.
2. `TierInfoSubSchema`, `TierHistoryEntrySubSchema`, `ChampionMasteryEntrySubSchema` 도 동일하게 갱신.
- `championId`: `Number` 로 변경
- `championLevel`, `championPoints`: 새 필드명
- `milestoneGrades`: `[String]` (default `undefined`)
- `nextSeasonMilestone`: `Schema.Types.Mixed`
- `TierInfo` 에 `leagueId`, `puuid`, `veteran`, `inactive`, `freshBlood`, `hotStreak`, `miniSeries(Mixed)` 추가
- `TierHistoryEntry` 에 `recordedAt: { type: Date, required: true }`, `leaguePoints/wins/losses` optional
3. `Community` 에 `riotPlatform`, `riotRegion` 추가:
```ts
riotPlatform: { type: String },
riotRegion: { type: String },
```
4. `MatchParticipantSubSchema.tier` 는 새 `TierInfo` 모양을 자동으로 따라감 — 추가 변경 없음.
**Risk**: 기존 데이터가 있다면 마이그레이션 필요. 현재 dev 환경 seed 만 사용한다면 seed 재실행으로 충분. `apps/api/src/seed.ts` 도 새 필드명에 맞춰 갱신.
**테스트**: 타입체크 통과 확인.
### Step 2. RiotChampionMasteryService → top 엔드포인트로 변경
**파일**: `apps/api/src/modules/riot/riot-champion-mastery.service.ts`
1. 메서드 시그니처 변경 또는 신규:
```ts
public async getTopByPuuid(
puuid: string,
options: { platform?: RiotPlatformRoute; count?: number; signal?: AbortSignal } = {},
): Promise<RiotChampionMasteryDto[]>
```
엔드포인트: `/lol/champion-mastery/v4/champion-masteries/by-puuid/{puuid}/top`
query: `count` (default 10, max 10)
2. 기존 `getByPuuid` 사용처 grep 후 모두 `getTopByPuuid` 로 교체.
3. `riot-account-enrichment.service.ts` 에서 `MASTERY_LIMIT = 10` 으로 변경.
### Step 3. region/by-puuid 서비스 + 자동 보정
**파일**: `apps/api/src/modules/riot/riot-account.service.ts`
```ts
public async getRegionByPuuid(
puuid: string,
options: RiotAccountLookupOptions = {},
): Promise<{ puuid: string; game: string; region: RiotPlatformRoute }> {
return this.riotClientService.get(
`/riot/account/v1/region/by-game/lol/by-puuid/${encodeURIComponent(puuid)}`,
{ region: options.region ?? 'asia', signal: options.signal },
parseRegionByPuuid,
);
}
```
`riot.types.ts` 에 응답 타입 추가:
```ts
export interface RiotAccountRegionDto {
puuid: string;
game: 'lol' | string;
region: RiotPlatformRoute;
}
```
**enrichment 보정 로직**:
`RiotAccountEnrichmentService.fetchSummonerSafe` 에서 `RiotApiError && status === 404` 발생 시:
1. `getRegionByPuuid` 호출
2. 받은 platform 으로 다시 summoner 호출
3. 그래도 실패면 `failed` 처리
4. 새 platform 이 community default 와 다르면 로그(`logger.warn`) — 향후 schema 에 puuid 별 platform 저장 여부는 별도 결정
### Step 4. enrichment dedup + force/TTL 흐름 정리
**파일**: `apps/api/src/modules/riot/riot-account-enrichment.service.ts`
1. 클래스에 `private inFlight = new Map<string, Promise<EnrichResult>>()` 추가.
2. `enrichRiotAccount` 진입부에서 dedup 체크. key 는 `${userId}:${puuid}` (user 다른데 puuid 같은 케이스도 있으니 user 포함이 안전).
3. `applyMasteries` 에서 `championRecords` 채우는 코드 제거 (2.1 결정).
4. `applyLeagueEntries` 호출 직전 `tierHistory` 갱신 헬퍼 호출:
```ts
private appendTierHistoryIfChanged(
account: RiotAccount,
entries: RiotLeagueEntryDto[],
): void {
const now = new Date();
for (const e of entries) {
const last = [...account.tierHistory]
.reverse()
.find((h) => h.queueType === e.queueType);
const changed =
!last ||
last.tier !== e.tier ||
(last.rank ?? '') !== (e.rank ?? '');
if (changed) {
account.tierHistory.push({
queueType: e.queueType,
tier: e.tier,
rank: e.rank,
leaguePoints: e.leaguePoints,
wins: e.wins,
losses: e.losses,
recordedAt: now,
});
}
}
}
```
5. 위 헬퍼는 `applyLeagueEntries` 가 처음 호출되더라도 빈 history → 첫 entry push 가 자연스럽게 일어남.
### Step 5. community.platform 사용 + DakaoUserService 연결
**파일**:
- `apps/api/src/modules/dakao/dakao-user.service.ts`
- `apps/api/src/modules/dakao/handlers/match-join.handler.ts` (필요 시)
1. `resolveRiotAccount` 가 community 를 한 번 조회해서 `riotPlatform`, `riotRegion` 을 옵션으로 enrichment / Riot lookup 에 전달.
2. `RiotAccountService.getByRiotId` 에 `region` 옵션 전달 (community.riotRegion 우선, fallback `asia`).
3. enrichment 호출에도 `platform: community.riotPlatform ?? 'kr'`.
```ts
const community = await CommunityModel.findById(context.communityId)
.select({ riotPlatform: 1, riotRegion: 1 })
.lean()
.exec();
const platform = (community?.riotPlatform as RiotPlatformRoute) ?? 'kr';
const region = (community?.riotRegion as RiotRegionalRoute) ?? 'asia';
```
### Step 6. 수동 갱신 엔드포인트
**신규 파일**: `apps/api/src/modules/user/user.controller.ts` (이미 존재) 에 라우트 추가, 또는 `riot-account.controller.ts` 신설.
- 기존 `user.module.ts` / `user.controller.ts` 구조 확인 (현재 `user/user.controller.ts`, `user/user.module.ts` 존재).
- 라우트:
```ts
@Post('me/riot-accounts/:puuid/refresh')
async refreshMyRiotAccount(
@CurrentUser() me: UserDocument,
@Param('puuid') puuid: string,
@Body() body: { force?: boolean; platform?: RiotPlatformRoute },
): Promise<EnrichResult> {
if (!me) throw new UnauthorizedException();
const owns = me.riotAccounts.some((a) => a.puuid === puuid);
if (!owns) throw new ForbiddenException();
return this.enrichmentService.enrichRiotAccount({
userId: me._id,
puuid,
options: { force: body.force === true, platform: body.platform },
});
}
```
- `UserModule.imports` 에 `RiotModule` 추가 (이미 RiotModule 이 `RiotAccountEnrichmentService` export 함).
- DTO: `class-validator` 기반 `RefreshRiotAccountDto`.
### Step 7. 스케줄러
**의존성**: `pnpm --filter api add @nestjs/schedule`
**신규 파일**: `apps/api/src/modules/riot/riot-account-refresh.scheduler.ts`
```ts
@Injectable()
export class RiotAccountRefreshScheduler {
private readonly logger = new Logger(RiotAccountRefreshScheduler.name);
constructor(
private readonly connectionService: ConnectionService,
private readonly enrichment: RiotAccountEnrichmentService,
) {}
@Cron('0 4 * * *', { timeZone: 'Asia/Seoul' })
async refreshStaleAccounts() {
const UserModel = await this.connectionService.getModel('user');
const cursor = UserModel.find({
'riotAccounts.0': { $exists: true },
})
.select({ _id: 1, riotAccounts: 1, communityId: 1 })
.cursor();
let processed = 0;
for await (const user of cursor) {
for (const acc of user.riotAccounts) {
try {
await this.enrichment.enrichRiotAccount({
userId: user._id,
puuid: acc.puuid,
options: { force: false },
});
processed += 1;
if (processed % 50 === 0) {
await sleep(5000);
}
} catch (err) {
this.logger.warn(`refresh failed: ${(err as Error)?.message ?? err}`);
}
}
}
this.logger.log(`Scheduler done: processed=${processed}`);
}
}
function sleep(ms: number) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
```
`RiotModule.providers` 에 추가, `app.module.ts` 에 `ScheduleModule.forRoot()` 추가.
### Step 8. projection 적용
**신규 파일**: `apps/api/src/modules/global/database/projections.ts`
```ts
export const USER_LIGHT_PROJECTION = {
'riotAccounts.championRecords': 0,
'riotAccounts.championRecordsFetchedAt': 0,
} as const;
```
**적용 지점**:
- `MatchService.list` — 매치 자체에는 RiotAccount 가 없지만 향후 populate 시 사용
- 신규 `UserService.list` 또는 `findByCommunity` 류 — projection 적용
- `/me` 핸들러 — full 데이터 유지
- `/users/:id` 단건 조회 — full 데이터 유지
대부분의 `riotAccounts.*` 가 무거워지는 시점이 mastery top 10 + tierHistory 누적이므로, 우선 list 쿼리에만 적용.
### Step 9. v4 파서 단위 테스트
**신규 파일**:
- `apps/api/src/modules/riot/riot-summoner.service.spec.ts`
- `apps/api/src/modules/riot/riot-league.service.spec.ts`
- `apps/api/src/modules/riot/riot-champion-mastery.service.spec.ts`
각 서비스에 RiotClientService mock 주입, 정상/누락 필드/배열 비정상 케이스 검증. enrichment 의 적용 단계는 기존 `riot-account-enrichment.service.spec.ts` 에서 이미 커버 중이므로, **Step 1 변경에 따라 기존 spec 의 응답 fixture 도 새 필드명으로 갱신** 필요.
### Step 10. 회귀 테스트 / 정리
1. `npx tsc --noEmit` 통과
2. `npx jest` 전체 PASS
3. seed 재실행으로 새 스키마 정상 작동 확인
4. dakao 시나리오 수동 검증:
- 신규 카카오 사용자가 `!내전 신청 ...` 으로 등록될 때 summoner v4 가 한 번 호출되고, 응답 후 user 문서에 `tiers`, `championMasteries`(10건), `tierHistory`(1건) 가 채워지는지 확인
- 같은 사용자가 즉시 재신청하면 enrichment 가 dedup 으로 단일 호출에 합쳐지는지 로그로 확인
- 한 시즌 후 tier 가 변경된 상태에서 enrichment 가 호출되면 `tierHistory` 에 새 entry 가 push 되는지 단위 테스트
---
## 4. 변경/추가 파일 목록
### 신규
- `apps/api/src/modules/global/database/projections.ts`
- `apps/api/src/modules/riot/riot-account-refresh.scheduler.ts`
- `apps/api/src/modules/riot/riot-summoner.service.spec.ts`
- `apps/api/src/modules/riot/riot-league.service.spec.ts`
- `apps/api/src/modules/riot/riot-champion-mastery.service.spec.ts`
- (옵션) `apps/api/src/modules/user/dto/refresh-riot-account.dto.ts`
### 수정
- `apps/api/src/modules/global/database/schema.ts` — TierInfo / TierHistoryEntry / ChampionMasteryEntry / Community 재정의
- `apps/api/src/modules/riot/riot.types.ts` — DTO 타입, RiotAccountRegionDto 추가
- `apps/api/src/modules/riot/riot-account.service.ts` — `getRegionByPuuid` 추가
- `apps/api/src/modules/riot/riot-champion-mastery.service.ts` — `getTopByPuuid` 로 교체
- `apps/api/src/modules/riot/riot-account-enrichment.service.ts` — 새 스키마 적용, dedup, tierHistory 누적, 404 보정
- `apps/api/src/modules/riot/riot.module.ts` — Scheduler / region service provider 등록
- `apps/api/src/modules/dakao/dakao-user.service.ts` — community platform/region 사용
- `apps/api/src/modules/user/user.controller.ts` (또는 신설) — `/me/riot-accounts/:puuid/refresh`
- `apps/api/src/modules/user/user.module.ts` — RiotModule import
- `apps/api/src/modules/match/match.service.ts` — list 쿼리 projection
- `apps/api/src/app.module.ts` — `ScheduleModule.forRoot()`
- `apps/api/src/seed.ts` — 새 mastery / tier 필드명에 맞춰 seed 데이터 수정
- `apps/api/src/modules/riot/riot-account-enrichment.service.spec.ts` — fixture 갱신
### 의존성
- `pnpm --filter api add @nestjs/schedule`
---
## 5. 검증 체크리스트
- [ ] `pnpm --filter api exec tsc --noEmit` 통과
- [ ] `pnpm --filter api exec jest` 전체 PASS
- [ ] seed 재실행 후 user 문서 정상 (`db.user.findOne()` 으로 새 필드 확인)
- [ ] dakao `!내전 신청 <id> <기존_등록_riot_id> 미드,탑` → enrichment 캐시 hit, Riot API 호출 0회
- [ ] dakao `!내전 신청 <id> <신규_riot_id> 미드,탑` → summoner v4 1회, league v4 1회, mastery top v4 1회 호출, user 문서에 tiers/masteries/tierHistory 채워짐
- [ ] `POST /users/me/riot-accounts/:puuid/refresh { force: true }` → enrichment 수동 강제 갱신 동작
- [ ] cron 시뮬레이션 (`@Cron` 수동 트리거 또는 `node -e` 로 메서드 직접 호출) → 200건 이상 처리되어도 OOM/timeout 없이 완료
- [ ] match list API 응답 사이즈 → projection 적용으로 기존 대비 30%+ 감소 (실측)
- [ ] 동시 동일 puuid enrichment 두 번 호출 → in-flight Map 으로 1회로 합쳐짐 (단위 테스트)
---
## 6. Phase 3 으로 미루는 것 (참고)
- **분산 dedup** (Redis SET NX EX 또는 mongo 락)
- **Token bucket / Riot API rate limit** 글로벌 throttle
- **OpenSearch 인덱싱** (RiotAccount, Match 변화 로그)
- **Slack 알림** (enrichment 실패 임계 초과, scheduler 실패)
- **puuid 별 last-known platform 캐싱** (Step 3 의 보정 결과를 RiotAccount 에 영구 저장)
- **시즌 종료 시 tierHistory 의 `season` 필드 자동 채움** + peakTier 계산
- **백오피스 UI** — community.riotPlatform 설정 / 수동 갱신 트리거 / 신선도 리포트
- **NATS 기반 enrichment 분산** (현재 dakao 외 트리거가 없으므로 보류)
---
## 7. 운영 노트
- Riot personal API key 는 **개당 100req / 2분 / IP** 한도. mastery + summoner + league 가 1 user attach 당 3회. dakao 첫 신청이 폭주해도 분당 ~30명 미만이면 무탈.
- 스케줄러는 5초 간격 batch 50건 → 10분에 6000건. 대부분의 community 규모에서 충분.
- region/by-puuid 보정은 community 의 platform 이 잘못 설정된 케이스에서 운영자가 즉시 알 수 있도록 `logger.warn` 만 남김. Phase 3 에서 알림 채널로 승격.
- `championRecords` 와 `championRecordsFetchedAt` 은 비워두는 채로 schema 만 유지. mastery 와는 다른 용도(향후 매치 분석 집계)이므로 충돌 없음.