🍃 Leaf Town Records (나뭇잎 마을 내전 기록소)

친구들과의 리그 오브 레전드 커스텀 게임 기록을 자동으로 집계하고 통계·랭킹·업적을 제공하는 웹 애플리케이션

배포 주소: https://leaf-town-records.vercel.app

---

1. 프로젝트 개요

왜 만들었나

친구 10~13명이 주기적으로 리그 오브 레전드 내전(커스텀 게임)을 진행하는데, 공식 전적 사이트(OP.GG 등)는 커스텀 게임을 기록하지 않는다. 매번 결과를 수기로 공유하다 보니 "누가 제일 잘해?", "나 몇 연승이야?" 같은 궁금증이 해결되지 않았다.

이를 해결하기 위해 게임 결산 스크린샷 한 장으로 전적 등록부터 통계 시각화까지 자동화한 전용 기록 시스템을 직접 설계·개발했다.

핵심 기능

기능	설명
AI 스크린샷 분석	게임 결산 화면 캡처를 업로드하면 Claude Vision이 닉네임·승패를 자동 추출
다전제 시리즈 집계	3판2선·5판3선 형식을 인식하고 개인전이 아닌 시리즈 단위로 승패 산정
통합 랭킹	점수(승 +3 / 패 -1) 기준 밀집 순위, 연승·연패 실시간 표시
플레이어 상세 통계	챔피언별 전적, 포지션별 승률, 1:1 상대전적, 시너지 분석
업적 시스템	일반·희귀·영웅·전설·신화 5등급 45종 업적, 대표업적 커스텀 설정
팀 편성	참가자 선택 → 팀 배정 → 미니게임으로 블루/레드 사이드 결정 → 공지 복사
닉네임 변경 이력 관리	닉네임 변경 시 전체 게임 기록 일괄 업데이트

---

2. 기술적 도전과 해결

2-1. AI 비전으로 스크린샷 파싱

문제: 커스텀 게임은 Riot 공식 API에 노출되지 않아 자동 수집이 불가능하다.

해결: Claude Sonnet Vision API에 결산 화면 이미지를 전송하고 JSON 구조로 파싱하도록 프롬프트를 설계했다.

[ 스크린샷 ] → Claude Vision API → { winTeam, team1: [...], team2: [...] }

• 화면 전체 색조(파란색/붉은색)를 승패 판정 기준으로 명시해 오인식 방지
• 최신 챔피언 목록을 Riot Data Dragon API에서 실시간으로 받아와 프롬프트에 주입 → 신규 챔피언 추가에 자동 대응
• 분석 결과를 바로 저장하지 않고 검수 UI 를 거쳐 오인식 수정 후 확정 → 데이터 신뢰도 확보
• 다전제 시리즈를 한 번에 분석하기 위해 게임당 순차 API 호출 후 일괄 검수

2-2. 닉네임 정규화 레이어

문제: 같은 사람이 다른 닉네임으로 기록될 수 있는 경우가 여러 가지다.

• 닉네임에 대소문자 혼용 (e.g. Shade vs shade)
• 2개월마다 무료 닉네임 변경
• 같은 사람이 주계정·부계정 두 개로 플레이

해결 1 — 정규화 키: 모든 닉네임 비교 시 normalizeId(공백제거 + 소문자) 함수를 일관 적용해 대소문자 차이를 흡수한다.

해결 2 — 닉네임 변경 일괄 업데이트: 닉네임 관리 페이지에서 "닉네임 변경"을 실행하면 저장된 전체 게임 기록을 스캔해 이전 닉네임을 새 닉네임으로 교체한다. 부계정 목록이 무한정 쌓이는 문제를 해소했다.

해결 3 — 실명 기반 통합 집계: 상대전적·시너지 통계를 집계할 때 닉네임 → 실명(realName) 변환 맵을 사전 구성하고 키로 실명을 사용한다. 주·부계정, 닉네임 변경 이전 기록이 모두 같은 사람으로 자동 합산된다.

"Shade"(주계정)  ─┐
"Shadow"(구닉네임) ─┤ → 실명 "홍길동" 으로 통합 집계
"shade"(대소문자)  ─┘

2-3. 다전제(시리즈) 단위 승패 설계

문제: 롤 내전은 3판2선·5판3선 형식이라 개인전 단위 승패로는 의미 있는 랭킹이 나오지 않는다.

해결: 날짜별로 게임 기록을 묶어 시리즈를 구성하고, 한 팀이 필요 승수(2승 또는 3승)를 달성했을 때만 isComplete = true로 처리한다. 모든 통계(승률·점수·연승·업적)는 시리즈 완료 기준으로만 산정한다.

날짜별 그룹 → 선취 승수 달성 여부 판별 → isComplete = true → 승패 집계

2-4. 업적 시스템 설계

단순 플레이 수 카운트를 넘어 관계 기반 업적(포지션 듀오, 상대 전적, 시너지)을 구현했다.

• 정글-서포터, 원딜-서포터, 탑-미드 조합별로 같은 포지션으로 함께 이긴 횟수를 별도 집계
• 포지션은 팀 배열의 인덱스(0=탑 … 4=서포터)로 추론해 별도 입력 없이 자동 감지
• computeAggregatedStats에서 주·부계정 합산 시 vsStats·withStats·positionStats·업적을 모두 병합해 통합 뷰 제공

---

3. 기술 스택

분류	기술
Framework	Next.js 16 (App Router)
Language	TypeScript
Styling	Tailwind CSS 4 + CSS Variables (다크 테마)
Database	Vercel KV (Upstash Redis — 서버리스 영구 저장)
AI	Anthropic Claude claude-sonnet-4-6 (Vision API)
외부 API	Riot Data Dragon (최신 챔피언 목록 자동 동기화)
배포	Vercel

---

4. 실행 방법

# 1. 패키지 설치
npm install

# 2. 환경 변수 설정 (.env.local)
KV_REST_API_URL=your_kv_url
KV_REST_API_TOKEN=your_kv_token
ANTHROPIC_API_KEY=your_anthropic_key

# 3. 개발 서버
npm run dev

---

5. 최신 업데이트 내역 (2026.06)

5-1. 아카츠키 테마 및 구름 비주얼 개편

• 고품격 고증 구름 SVG: 소용돌이 스월과 꼬리가 구현된 공식 아카츠키 붉은 구름 및 선명한 흰색 테두리 문양 SVG로 전면 리모델링했습니다.
• Tsukuyomi 테마 배경: 눈이 편안하면서 대비가 시크한 매트 블랙 #0c0c0e 및 딥 차콜 패널 배경 위에, 무한 츠쿠요미의 붉은 달이 비치는 은은한 광원 효과를 배경 그라디언트로 튜닝했습니다.
• 구름 스케일 애니메이션 보정: CSS keyframes의 transform 덮어쓰기 현상을 더블 컨테이너(래퍼) 구조로 분리하여 구름 찌그러짐 현상을 해결했습니다.

5-2. 챔피언 분석 기능 고도화

• 플레이 기록 팝업: 챔피언 목록의 픽률 또는 개별 챔피언 상세페이지 내의 픽률 카드를 클릭하면 해당 챔피언을 선택해 플레이했던 소환사 전적(KDA, 총 판수, 승률)을 노출하는 상세 전적 모달을 제공합니다.
• 퀵 네비게이션: 상단에 1~5티어 즉시 이동 버튼을 달아 부드러운 스크롤 이동 기능을 제공하며 UI 라벨을 콤팩트하게 다듬었습니다.
• 탑(Top) 라인 티어 분배 엄격화: 탑 포지션의 등급 기준을 타 라인보다 더 엄격하게 분배하도록 상대 백분위(1티어 상위 12% 이내, 2티어 상위 28% 이내 등)를 개별 적용하여 공정성을 제고했습니다.

5-3. 랭킹 상세정보 카드식 레이아웃 & 판수 정렬

• 챔피언 탭 개편: 텍스트 형태의 챔피언 테이블 목록을 모스트 3 챔피언 카드 강조 및 5열 반응형 그리드 뷰로 변경하여 가독성을 높였습니다.
• 판수 우선순위 정렬: 챔피언 전적을 판수(Games Played) 내림차순을 최우선 기준으로 정렬하고, 판수가 같은 경우에 한해 승리 횟수(Wins)가 높은 챔피언이 상단에 배치되도록 개선했습니다.

5-4. 캡쳐분석 자동 보정 및 밴/픽 입력 개선

• 소환사명 자동 교정: AI 분석 결과 파싱 후, 소환사 DB 목록과 띄어쓰기/대소문자 무관 대조하여 정식 소환사명으로 자동 변경합니다.
• Tab 키 세로 이동: 챔피언 입력 칸에 포커스 바인딩을 주어 Tab 및 Shift+Tab 입력 시 닉네임을 건너뛰고 챔피언명 입력 필드로만 세로 방향 신속 이동하도록 지원합니다.
• 수동 입력 보장: AI 오기입으로 인한 입력 오류를 방지하기 위해 픽한 챔피언 및 5개 밴 슬롯의 챔피언 이름을 기본 공백("")으로 초기화하여 사용자가 직접 정밀 등록할 수 있도록 최적화했습니다.
• 진영 스왑 시 밴 목록 연동: 블루/레드 진영 전체 스왑 버튼 클릭 시 5개 밴 리스트도 좌우 교차 반영되도록 동기화했습니다.
• 한글 입력(IME) 엔터 오류 수정: 한글을 입력하고 엔터를 눌러 선택할 때 composition(글자 조합 중) 상태에서의 중복 입력 현상("애니비아애" 등)을 isComposing 상태 제어로 완벽히 방지하여 편안한 Hangul 입력 속도를 보장합니다.

5-5. 모달 레이어 화면 가림(Z-Index) 현상 해결

• 모달 전체 오버레이 보장: 본문 컨테이너인 <main> 엘리먼트에 고정되어 있던 z-10 스태킹 컨텍스트를 제거하여, 대표업적 선택 모달(BadgeModal)을 비롯한 모든 모달 창(z-50)이 상단 네비게이션 헤더(z-40) 위에 잘리지 않고 완벽하게 최상단 오버레이 레이어로 렌더링되도록 수정했습니다.

5-6. 비 마을(Amegakure) 테마 배경 건물 드로잉 추가

• 배경 철탑 삽입: 비 마을 테마 활성화 시, 철골 구조와 안테나, 배관 장식들이 상세하게 묘사된 2개의 비 마을 철탑 건물을 좌측 하단(65vh) 및 우측 하단(75vh)에 배치하여 더욱 매력적인 Amegakure 테마 분위기를 재현했습니다. 뷰포트 크기 변화에 알맞게 반응형 정렬이 적용됩니다.

5-7. 나뭇잎 마을(Leaf Village) 테마 호카게 바위(Hokage Monument) 배경 픽셀 아트 분할 적용

• 16-bit 픽셀 아트 이미지 합성 및 교체: 다른 테마의 도트/레트로 스타일 일러스트와 조화를 이루기 위해 기존 호카게 바위 실사진을 16-bit 픽셀 아트 스타일의 도트 이미지(hokage_rock_pixel.png)로 변환했습니다.
• 대칭 비율 분할 배치: 동일한 픽셀 아트 이미지를 왼쪽 절반(objectPosition: "left bottom")과 오른쪽 절반(objectPosition: "right bottom")으로 분할 대칭 배치하여, 중앙의 본문 콘텐츠를 중심으로 1~7대 호카게 석상이 균형 있게 정렬됩니다.
• 눈의 피로를 낮추는 블렌딩 기법: 라이트 모드 배경(--bg: #f3f3f3) 위에서 하늘색 등 밝은 영역을 완전히 없애기 위해 흑백 필터(grayscale(100%))와 mixBlendMode: "multiply" 기법을 동일 적용했습니다.
• 부드러운 대칭 마스크 처리: 이미지의 바깥쪽 모서리에서 안쪽으로 부드럽게 소멸되도록 radial-gradient 마스킹을 씌웠습니다.

5-8. 아카츠키(Akatsuki) 테마 좌우 배경 건물(Amegakure 타워 지붕 구조물) 드로잉 추가

• Akatsuki 공식 씬 고증: Pain의 탑 꼭대기에 아카츠키 멤버들이 서 있던 독특한 철골/스톤 초승달(crescent) 모양의 지붕 구조물 2개를 좌우 대칭형태로 드로잉하여 삽입했습니다.
• 세련된 분위기 연출: 플레이트 패널 라인, 안테나 피뢰침, 아카츠키 붉은 아우라 및 테두리(var(--border-green))에 걸맞는 어두운 붉은색 외곽선 실루엣(opacity: 0.22)과 컷아웃 구멍을 입혀 매트 블랙 다크 모드에 몰입감과 미스터리함을 부여했습니다.