19 KiB
토너먼트 결과 수집 (우회) 플랜
대상: codex 가 이어서 작업 가능한 수준의 실행 플랜 레포:
/Users/dahyeon/source/lolympus-tournament-support(pnpm workspace) 작성 기준: 2026-04-27 선행 작업:
Tournament-Code-플랜.md(코드 풀,Match.tournamentCodeIds[],Match.teamBuiltAt,TournamentCode.riotMatchId자리)Riot-소환사전적-플랜.md(Redis Stream 작업 큐 + leader election + throttle + ETA)Riot-최근경기-플랜.md(RiotRateLimiterService, RiotMatch 영구 저장)
1. Context
토너먼트 API 사용 권한이 없어 게임 종료 webhook 을 받을 수 없습니다. 우회로 다음을 구현합니다.
- 매치가
team-built으로 전환되면 결과 수집 작업이 큐에 enqueue. match-v5 by-puuid?type=tourney&startTime=teamBuiltAt폴링.- 응답
info.tournamentCode를 우리TournamentCode.code와 매칭. - 매칭된 match-v5 의 승팀/스코어/MVP 후보 / riotMatchIds 를 우리
Match.result로 변환. - 모든 게임 슬롯이
used가 되면Match.status = 'finished'자동 전환.
본 plan 은 "선행 plan 의 §6 자리만 마련" 부분을 실제 모듈로 구현합니다.
2. 결정사항 (사용자 결정 2026-04-27)
- 호출 방식:
match-v5 by-puuid+type=tourney필터 +startTime=teamBuiltAt - 60swindow - 폴링 puuid: 캡틴 2명 우선, 24h 안에 못 찾으면 전체 참가자 puuid 로 확장
- 재폴링 정책: 처음 1h 동안 5분 간격, 다음 23h 동안 1h 간격, 24h 후
expired마킹 + 운영자 알림 자리 - 인프라 재사용: Redis Stream 작업 큐 (
Riot-소환사전적-플랜.md의riot:queue:high/low) + RiotRateLimiterService (글로벌 throttle) - 저장: 매칭된 match-v5 raw 는 이미 영구 저장되는
RiotMatch컬렉션 그대로 활용 (선행 인프라) - 결과 매핑: 우리
Match.teams[].members[].userId↔ match-v5info.participants[].puuid↔User.riotAccounts[].puuid로 양 팀 결정
3. 데이터 모델 보강
3.1 Match.result 확장
// schema.ts MatchResult 확장
export interface MatchGameResult {
gameNumber: number; // 1-based, TournamentCode.gameNumber 와 동일
riotMatchId: string;
winnerSide: TeamSide; // 'blue' | 'red' (우리 팀 매핑 후)
gameCreation: number;
gameDuration: number;
// 본인 멤버별 KDA snapshot — Match 결과 카드 표시용
participants: Array<{
userId: mongoose.Types.ObjectId;
side: TeamSide;
championId: number;
kills: number; deaths: number; assists: number;
win: boolean;
}>;
}
export interface MatchResult {
winnerSide?: TeamSide; // 시리즈 최종 승팀 (BO3: 2승 한 팀). 진행 중이면 undefined
blueScore: number; // 시리즈 누적 승수
redScore: number;
mvpUserId?: mongoose.Types.ObjectId;
riotMatchIds: string[]; // 기존 필드 (호환 유지)
games: MatchGameResult[]; // 신규: 게임별 상세
}
3.2 TournamentCode.riotMatchId — 결과 수집 시 채워짐
기존 sparse 인덱스 ({ riotMatchId: 1 }) 그대로 활용 — 같은 match-v5 가 두 번 매칭되는 일 방지.
3.3 신규: TournamentResultPollState (선택)
폴링 진척 상태 추적용 별도 컬렉션 또는 Match.resultPollState 임베드:
export interface MatchResultPollState {
startedAt: Date; // 첫 enqueue 시점
lastPolledAt?: Date;
lastPollOutcome?: 'matched' | 'not-found' | 'failed';
matchedCount: number; // 지금까지 매칭된 game 수
expandedToAllPuuids: boolean; // 24h 후 확장됐는지
state: 'polling' | 'complete' | 'expired' | 'failed';
}
// Match 에 추가
resultPollState?: MatchResultPollState;
→ 별도 컬렉션 보다 임베드가 join 0회로 단순. Match 안에 둬도 1개 도큐먼트당 작은 크기.
4. 작업 큐 통합
4.1 신규 stream/job 타입
선행 plan 의 작업 큐 (riot:queue:high, riot:queue:low) 그대로 사용. 새 job 타입만 추가:
interface PollTournamentResultJob {
jobId: string;
matchId: string; // ObjectId.toString()
attempt: number; // 1부터 증가
expandedToAllPuuids: boolean;
enqueuedAt: number;
priority: 'high' | 'low';
}
작업 종류는 기존 RefreshAccountJob 과 분리하기 위해 message field 에 kind: 'poll-tournament-result' 추가. worker 가 kind 별 dispatch.
4.2 enqueue 트리거
| 시점 | 호출 위치 | priority |
|---|---|---|
team-built 전환 직후 |
auction.service.ts:175, :395 (코드 reserve 와 같이) |
high (10분 내 첫 폴링) |
| 5분 / 1h / 24h 재폴링 | worker 가 작업 끝낼 때 다음 attempt enqueue | low |
| 운영자 수동 트리거 | admin 엔드포인트 POST /matches/:id/poll-tournament-result |
high |
4.3 worker 처리 흐름
async function processPollJob(job: PollTournamentResultJob) {
const match = await MatchModel.findById(job.matchId);
if (!match || match.status === 'finished') return; // 이미 끝남
const codes = await TournamentCodeModel.find({ matchId: match._id }).sort({ gameNumber: 1 });
const unmatched = codes.filter((c) => c.state === 'reserved' && !c.riotMatchId);
if (unmatched.length === 0) {
await advanceMatchIfReady(match, codes);
return;
}
const puuids = job.expandedToAllPuuids
? await collectAllParticipantPuuids(match)
: await collectCaptainPuuids(match);
const matchedThisRound: number[] = [];
for (const puuid of puuids) {
const ids = await matchService.getMatchIdsByPuuid(puuid, {
type: 'tourney',
startTime: Math.floor((match.teamBuiltAt!.getTime() - 60_000) / 1000),
endTime: Math.floor(Date.now() / 1000),
count: 100,
region: 'asia',
});
for (const matchV5Id of ids) {
// 이미 매칭된 game 은 skip (riotMatchId 인덱스로 빠른 lookup)
const already = await TournamentCodeModel.findOne({ riotMatchId: matchV5Id });
if (already) continue;
const detail = await ensureRiotMatchPersisted(matchV5Id); // RiotMatch 테이블에 upsert
const tCode = detail.info.tournamentCode;
if (!tCode) continue;
const code = unmatched.find((c) => c.code === tCode);
if (!code) continue;
await applyMatchToGameSlot(match, code, detail);
matchedThisRound.push(code.gameNumber!);
}
}
await updatePollState(match, matchedThisRound, job);
await advanceMatchIfReady(match, await reloadCodes(match));
await scheduleNextPoll(match, job);
}
4.4 applyMatchToGameSlot — 우리 팀 매핑
async function applyMatchToGameSlot(match, code: TournamentCode, detail: RiotMatchDto) {
const { teamMapping, gameResult } = computeGameResult(match, detail);
code.state = 'used';
code.usedAt = new Date(detail.info.gameCreation);
code.riotMatchId = detail.metadata.matchId;
await code.save();
match.result = match.result ?? { blueScore: 0, redScore: 0, riotMatchIds: [], games: [] };
match.result.games.push(gameResult);
match.result.riotMatchIds = [
...new Set([...match.result.riotMatchIds, detail.metadata.matchId]),
];
if (gameResult.winnerSide === 'blue') match.result.blueScore += 1;
else match.result.redScore += 1;
await match.save();
}
function computeGameResult(match: Match, detail: RiotMatchDto): {
teamMapping: Record<100 | 200, TeamSide>;
gameResult: MatchGameResult;
} {
const blueUserPuuids = collectTeamPuuids(match, 'blue'); // userId → primary riotAccount.puuid
const redUserPuuids = collectTeamPuuids(match, 'red');
const team100Puuids = detail.info.participants.filter((p) => p.teamId === 100).map((p) => p.puuid);
const team200Puuids = detail.info.participants.filter((p) => p.teamId === 200).map((p) => p.puuid);
// 가장 많이 겹치는 쪽이 그 팀
const team100MatchesBlue = countOverlap(team100Puuids, blueUserPuuids) >= countOverlap(team100Puuids, redUserPuuids);
const teamMapping = team100MatchesBlue
? { 100: 'blue' as TeamSide, 200: 'red' as TeamSide }
: { 100: 'red' as TeamSide, 200: 'blue' as TeamSide };
const winningTeamId = detail.info.teams.find((t) => t.win)!.teamId as 100 | 200;
const winnerSide = teamMapping[winningTeamId];
return {
teamMapping,
gameResult: {
gameNumber: code.gameNumber!,
riotMatchId: detail.metadata.matchId,
winnerSide,
gameCreation: detail.info.gameCreation,
gameDuration: detail.info.gameDuration,
participants: detail.info.participants
.map((p) => {
const userId = lookupUserIdByPuuid(match, p.puuid);
if (!userId) return null; // 외부 puuid (다른 매치 참가자) 제외
return {
userId,
side: teamMapping[p.teamId as 100 | 200],
championId: p.championId,
kills: p.kills, deaths: p.deaths, assists: p.assists,
win: p.win,
};
})
.filter((p): p is NonNullable<typeof p> => p !== null),
},
};
}
팀 매핑 시 우리 멤버가 1명도 안 겹치면 (잘못된 매칭) → game slot 적용 skip + 운영자 알림 자리. 정상 케이스에선 5명 모두 일치.
4.5 advanceMatchIfReady — finished 자동 전환
async function advanceMatchIfReady(match: Match, codes: TournamentCode[]) {
if (codes.length < match.gameCount) return;
if (!codes.every((c) => c.state === 'used' && c.riotMatchId)) return;
match.status = 'finished';
// 시리즈 최종 승팀 = 우세 점수
if (match.result) {
match.result.winnerSide =
match.result.blueScore > match.result.redScore ? 'blue' :
match.result.redScore > match.result.blueScore ? 'red' : undefined;
}
match.resultPollState = { ...match.resultPollState, state: 'complete' } as any;
await match.save();
}
mvpUserId 자동 산정은 본 plan 범위 외 (Phase 후속). 현재는 운영자 수동 입력 가능 자리만 둠.
4.6 scheduleNextPoll — 재시도 cadence
function nextPollDelayMs(attempt: number, startedAt: Date): number | null {
const elapsedMs = Date.now() - startedAt.getTime();
if (elapsedMs > 24 * 3600_000) return null; // 24h 후 종료
if (elapsedMs <= 1 * 3600_000) return 5 * 60_000; // 1h 동안 5분 간격
return 60 * 60_000; // 그 후 1h 간격
}
async function scheduleNextPoll(match: Match, job: PollTournamentResultJob) {
const delay = nextPollDelayMs(job.attempt, match.resultPollState!.startedAt);
if (delay === null) {
await markExpired(match);
return;
}
await jobQueue.enqueue({
kind: 'poll-tournament-result',
matchId: match._id.toString(),
attempt: job.attempt + 1,
expandedToAllPuuids: shouldExpand(job, match),
priority: 'low',
deferUntil: Date.now() + delay, // §4.7 참고
});
}
shouldExpand: elapsedMs > 1h && matchedCount === 0 또는 elapsedMs > 24h - 1h 시점부터 모든 puuid 사용.
4.7 deferUntil — 지연 enqueue
Redis Stream 자체는 schedule 미지원. 대안:
- (a) Garnet ZSET
riot:queue:scheduled— score=실행시각ms. 별도 cron@Interval(5_000)가ZRANGEBYSCORE 0 now항목을 꺼내 stream 으로 옮김. - (b) NATS JetStream
expires/headers.Nats-Delay— JetStream 활성화 부담.
→ (a) 채택. 작은 헬퍼 RiotJobScheduler.scheduleAt(deferUntilMs, payload) 한 곳에서 관리.
4.8 만료 마킹 + 운영자 알림 자리
async function markExpired(match: Match) {
match.resultPollState = { ...match.resultPollState, state: 'expired' } as any;
await match.save();
// 알림 자리 — Phase 후속에서 dakao bot publish
this.logger.warn(`Tournament result polling expired for match ${match._id}`);
}
5. 변경 사항 (파일 단위)
5.1 백엔드
apps/api/src/modules/tournament-result/
tournament-result.module.ts
tournament-result.service.ts # processPollJob / applyMatchToGameSlot / advanceMatchIfReady
tournament-result.worker.ts # 작업 큐 dispatch (kind=poll-tournament-result)
tournament-result.controller.ts # POST /matches/:id/poll-tournament-result (admin 수동)
tournament-result.types.ts
team-mapping.util.ts # collectTeamPuuids / countOverlap / lookupUserIdByPuuid
game-result.util.ts # computeGameResult
riot-job-queue.service.ts (선행 plan):
enqueue(payload, deferUntil?)시그니처에deferUntil옵션 추가- worker 의 dispatch 에
kind === 'poll-tournament-result'분기 추가
auction.service.ts:
team-built전환 +reserveForMatch직후 →tournamentResultService.scheduleInitialPoll(match)호출
match.service.ts 의 serializeMatch:
result.games[]응답에 포함 (gameNumber 정렬)
5.2 인덱스 보강
RiotMatch 컬렉션 인덱스 추가 (선행 plan 에 없으면):
{ 'raw.info.tournamentCode': 1 }sparse — match-v5 의 tournamentCode 로 reverse lookup 가능 (디버깅/admin)
5.3 프런트
MatchDetailPage 결과 표시
apps/web/src/pages/MatchDetailPage.tsx:
- 기존
match.result단일 score 표시 →result.games[]게임별 표시:1경기 블루 ⓦ KR_xxxxx 28:14 2경기 레드 ⓦ KR_xxxxx 31:02 3경기 대기 중 최종 블루 2 - 1 레드 match.status === 'in-progress'인 동안 부분 결과 점진 표시.result.games[].participants[]로 멤버별 KDA 표시 가능.
types.ts
export interface ApiMatchGameResult {
gameNumber: number;
riotMatchId: string;
winnerSide: TeamSide;
gameCreation: number;
gameDuration: number;
participants: Array<{
userId: string;
side: TeamSide;
championId: number;
kills: number; deaths: number; assists: number;
win: boolean;
}>;
}
export interface ApiMatchResult {
winnerSide?: TeamSide;
blueScore: number;
redScore: number;
mvpUserId?: string;
riotMatchIds: string[];
games: ApiMatchGameResult[];
}
admin 수동 트리거 버튼
매치 상세에 admin 만 보이는 "결과 다시 수집" 버튼 — POST /matches/:id/poll-tournament-result 호출 → 토스트 "수집 작업이 큐에 등록되었어요".
6. 단위 테스트
team-mapping.util.spec.ts- 5명 모두 일치 → 정확한 매핑
- 4 vs 1 일치 → 다수쪽 매핑
- 0 일치 → null 반환 (skip)
game-result.util.spec.ts- winnerSide 정확
- participants 외부 puuid 제외
tournament-result.service.spec.ts- 첫 폴링: 캡틴 puuid 만 사용
- 1h 경과 + 매치 0건 → expandedToAllPuuids=true
- 24h 후 → markExpired
- 모든 game slot used → match.status=finished, winnerSide 우세 계산
- 부분 매칭 (3경기 중 1경기만) → match.status 그대로 유지, result.games 1개
riot-job-scheduler.spec.ts(deferUntil ZSET)- scheduleAt 후 cron 이 정확한 시점에 stream 으로 옮김
7. Rollout
- (PR-1)
Match.result.games[]schema 확장 +Match.resultPollState임베드 + 마이그레이션 (옛 result 호환 유지) - (PR-2)
RiotJobScheduler(deferUntil ZSET + cron) — 다른 모듈도 재사용 가능 - (PR-3)
tournament-result.service(processPollJob / applyMatchToGameSlot / scheduleNextPoll) + 단위 테스트 - (PR-4) worker dispatch 에
kind=poll-tournament-result추가 - (PR-5) auction.service
team-built전환 직후scheduleInitialPoll호출 - (PR-6) admin 수동 트리거 엔드포인트 + 권한 가드
- (PR-7) 매치 상세 결과 표시 (게임별 row + 시리즈 점수)
- (PR-8) 운영 모니터링 (폴링 attempt / 매칭 성공률 / expired 카운트)
- (Phase 후속) MVP 자동 산정 / dakao 알림 / mvpUserId 운영자 수동 입력 UI
8. 추가 고려사항
확정 (사용자 결정 2026-04-27)
type=tourney필터 사용 (Tournament-Code-플랜.md§6 결정)- 재폴링: 5분(1h) → 1h(23h) → 24h 후 expired
- puuid 확장: 24h 안 못 찾으면 캡틴 → 전체 참가자
- finished 전환: 모든 슬롯 used + riotMatchId 채워짐
- 결과 표시: in-progress 부터 부분 게임 결과 점진 표시
권장 (운영 후 확인)
- 잘못된 코드 매칭 방어 —
applyMatchToGameSlot직전에team100/200우리 멤버 합집합 ≥ 6명 이면 정상, 미만이면 skip + 운영자 알림. (예: 운영자가 코드를 외부에 유출 → 다른 사람들이 사용한 게임이 우리 매치로 잘못 들어오는 케이스) teamBuiltAt누락 가드 — 옛 매치 마이그레이션 시teamBuiltAt없을 수 있음.null이면 폴링 skip + admin 페이지 경고.- 재폴링 cadence 초기 burst — 5분 간격은 12회/h × Match-V5 list 1 + detail N = 매치당 최악 60+ calls/h. 글로벌 throttle 통과는 되지만 큰 매치 동시 진행 시 high stream 점유. low priority 로 enqueue 가 안전.
- gameNumber 순서 보존 — 운영자가 1경기/2경기/3경기 코드를 순서대로 발급한 가정. 만약 사용자가 2경기 코드를 먼저 게임에 입력하면
gameNumber와 실제 플레이 순서가 어긋남.gameCreation기준으로 후처리 정렬 필요할 수도. 일단 운영 흐름 가정 유지. - 시리즈 동점 판정 — gameCount=3 인데 1-1-pending 상황에서 마지막 매치가 expired 되면 winnerSide 미정. 운영자 수동 종료 자리 필요.
- 부분 finished UI 처리 —
result.games.length < gameCount인 동안 "남은 경기 N개" 표시. 모두 done 되면 시리즈 결과 카드. - 외부 사용자에게 노출되는 raw match-v5 id —
result.riotMatchIds가 외부에 노출되는데 puuid 같은 민감 정보는 응답 매핑 단에서 자동 제외 (이미 우리 userId 만 남기는 구조). - Phase 후속 MVP 산정 — 라인별 KDA z-score / damage share / vision score 가중 — 평점 산식과 같은 로직 재사용 가능 (
Riot-소환사전적-플랜.md§2.7.B.1). - Replays / 랭크/AI 매치 false positive —
type=tourney가 토너먼트 코드 매치만 반환하므로 false positive 거의 없음. 추가로info.tournamentCode정확 매칭이라 2중 가드.
추후 (Phase 후속)
- MVP 자동 산정
- dakao bot / discord 알림 (시리즈 종료 시)
- 운영자 수동 결과 입력 UI (폴링 expired / 잘못된 매칭 정정용)
- 결과 통계 대시보드 (우리 커뮤니티의 시즌 W-L, 멤버 KDA 누적)
9. Done 정의
Match.result.games[]+Match.resultPollStateschema 추가team-built전환 시scheduleInitialPoll호출 → 작업 큐 high 에 첫 enqueue- worker 가
match-v5 by-puuid?type=tourney&startTime=teamBuiltAt-60호출 info.tournamentCode와 우리 코드 매칭 → 해당TournamentCode.state='used',riotMatchId저장- 우리 팀(blue/red) 매핑 정확 (5명 일치 케이스 테스트)
- 부분 결과 표시:
in-progress동안 매칭된 game 만큼 result.games[] 채워지고 UI 점진 표시 - 모든 슬롯 used →
Match.status='finished',result.winnerSide자동 산정 - 24h 안 못 찾으면
resultPollState.state='expired'+ 로그 경고 - admin 수동 재시도 엔드포인트 동작
RiotJobScheduler(deferUntil ZSET) 동작 — 5분/1h 후 정확히 enqueue- 단위 테스트 통과 (team-mapping / game-result / cadence / 부분 매칭)
- Riot 429 0건 (글로벌 throttle 통과)