[codex] Build the live PvP room/session terminal stack

docs/pvp/README.md

@@ -0,0 +1,145 @@
+# Tokénmon PvP 문서 인덱스
+
+상태: Draft v1
+범위: 온라인 친선 PvP 초기 설계
+기준 방향: **세대별 온라인 파티 등록 + 서버 권한 전투 + 인게임 감성 6v6 싱글**
+
+## 문서 목적
+
+이 문서 세트는 Tokénmon의 온라인 PvP를 실제 구현 가능한 단위로 구조화한 상위/하위 설계 문서 모음이다.
+핵심 목표는 다음 세 가지다.
+
+1. **전투 결과 위조를 막는다.**
+2. **파티 성장 상태 위조를 최대한 막는다.**
+3. **공식 대회 느낌보다 인게임에서 NPC 트레이너를 조우한 감성에 가깝게 만든다.**
+
+이 문서 세트는 아직 구현 문서가 아니라 **설계 기준 문서**다. 이후 서버/API/클라이언트 구현은 이 문서를 기준으로 분해한다.
+
+---
+
+## 한눈에 보는 핵심 결정
+
+- 전투는 **서버 권한(server-authoritative)** 으로 처리한다.
+- 클라이언트(Claude Code)는 **기술 선택 / 교체 / 다음 포켓몬 선택** 같은 명령만 보낸다.
+- 로컬 스토리/성장은 유지하되, 온라인에서는 **세대별 등록 파티 스냅샷**을 사용한다.
+- 온라인 친선 PvP는 초기 버전에서 **싱글배틀 / 6마리 등록 / 6마리 전원 사용 / 팀 프리뷰 없음 / 1번 슬롯 선발** 로 간다.
+- **동일 종 중복 금지**를 적용한다.
+- **전설+환상 총 2마리 제한**, 그중 **restricted 1마리 제한**을 적용한다.
+- 레벨은 실제 성장을 보존하되, 배틀 계산에서는 **50 이후 압축**, **유효 레벨 상한 60**을 둔다.
+- `legendary`, `mythical`과 별개로 온라인 밸런스용 **`restricted` 개념을 따로 둔다.**
+- 세대는 현재 로컬 시스템처럼 분리되어 있으므로, 온라인도 **세대별 ruleset / party / 룸** 구조로 간다.
+
+---
+
+## 권장 읽기 순서
+
+1. [PvP 제품/게임플레이 규칙](./game-design/battle-format.md)
+2. [성장/파티 등록 구조](./game-design/progression-and-party-registration.md)
+3. [특수 포켓몬 정책](./game-design/special-pokemon-policy.md)
+4. [세대별 ruleset 구조](./game-design/generation-rules.md)
+5. [서버 아키텍처](./server/architecture.md)
+6. [Storage 인덱스](./server/storage/README.md)
+7. [HTTP / WebSocket API 계약 초안](./server/api-contract.md)
+8. [Contracts 인덱스](./server/contracts/README.md)
+9. [실시간 배틀 흐름](./server/battle-flow.md)
+10. [치트 대응 / 보안 정책](./security/anti-cheat.md)
+11. [구현 로드맵](./roadmap/rollout-plan.md)
+12. [서버 패키지 / 모듈 구조 제안](./implementation/server-package-layout.md)
+
+---
+
+## 문서 트리
+
+### 1. 게임 설계
+- [게임 설계 인덱스](./game-design/README.md)
+  - [배틀 포맷](./game-design/battle-format.md)
+  - [성장 및 파티 등록](./game-design/progression-and-party-registration.md)
+  - [전설 / 환상 / restricted 정책](./game-design/special-pokemon-policy.md)
+  - [세대별 ruleset 설계](./game-design/generation-rules.md)
+
+### 2. 서버 설계
+- [서버 설계 인덱스](./server/README.md)
+  - [서버 아키텍처](./server/architecture.md)
+  - [Storage 인덱스](./server/storage/README.md)
+    - [데이터 모델](./server/storage/data-model.md)
+    - [DB 스키마 초안](./server/storage/database-schema.md)
+  - [API 계약](./server/api-contract.md)
+  - [Contracts 인덱스](./server/contracts/README.md)
+    - [온라인 파티 등록 상세 계약](./server/contracts/party-registration.md)
+    - [친구전 룸 / 매치 성립 상세 계약](./server/contracts/room-and-match.md)
+    - [실시간 배틀 세션 상세 계약](./server/contracts/realtime-battle-session.md)
+  - [실시간 배틀 흐름](./server/battle-flow.md)
+
+### 3. 보안 / 운영
+- [보안 / 치트 대응 인덱스](./security/README.md)
+  - [치트 대응 정책](./security/anti-cheat.md)
+- [로드맵 인덱스](./roadmap/README.md)
+  - [단계별 구현 로드맵](./roadmap/rollout-plan.md)
+
+### 4. 구현 계획
+- [구현 계획 인덱스](./implementation/README.md)
+  - [PvP 초기 구현 PRD](./implementation/prd.md)
+  - [PvP 작업 분해 / TODO](./implementation/todo-breakdown.md)
+  - [서버 패키지 / 모듈 구조 제안](./implementation/server-package-layout.md)
+
+---
+
+## 문서 간 관계
+
+- [배틀 포맷](./game-design/battle-format.md)은 플레이어 경험과 경기 규칙의 기준 문서다.
+- [성장 및 파티 등록](./game-design/progression-and-party-registration.md)은 로컬 성장과 온라인 사용을 연결하는 문서다.
+- [특수 포켓몬 정책](./game-design/special-pokemon-policy.md)과 [세대별 ruleset 설계](./game-design/generation-rules.md)는 배틀 포맷의 세부 제약을 정의한다.
+- [서버 아키텍처](./server/architecture.md)는 왜 서버 권한 구조가 필요한지 설명한다.
+- [Storage 인덱스](./server/storage/README.md)는 저장 계층 하위 묶음의 출발점이다.
+- [데이터 모델](./server/storage/data-model.md)은 엔티티 개념도를 설명하고, [서버 DB 스키마 초안](./server/storage/database-schema.md)은 이를 컬럼/제약 수준으로 구체화한다.
+- [API 계약](./server/api-contract.md)은 서버 아키텍처와 스키마를 전체 입출력 표면으로 정리한 문서다.
+- [Contracts 인덱스](./server/contracts/README.md)는 Phase별 상세 계약 하위 묶음의 출발점이다.
+- [온라인 파티 등록 상세 계약](./server/contracts/party-registration.md)은 그중 Phase 1 등록/조회 계약을 필드 단위까지 세밀하게 내린 문서다.
+- [친구전 룸 / 매치 성립 상세 계약](./server/contracts/room-and-match.md)은 Phase 2의 room binding / presence / battle freeze 계약을 세밀하게 내린 문서다.
+- [실시간 배틀 세션 상세 계약](./server/contracts/realtime-battle-session.md)은 Phase 3의 WebSocket 명령/이벤트 계약을 세밀하게 내린 문서다.
+- [실시간 배틀 흐름](./server/battle-flow.md)은 실제 플레이 시퀀스를 정의한다.
+- [치트 대응 정책](./security/anti-cheat.md)은 위 모든 문서의 보안 기준 문서다.
+- [구현 로드맵](./roadmap/rollout-plan.md)은 이 설계를 어떤 순서로 구현할지 정리한 문서다.
+- [PvP 초기 구현 PRD](./implementation/prd.md)은 제품 목표와 수용 기준을 정리한 문서다.
+- [PvP 작업 분해 / TODO](./implementation/todo-breakdown.md)은 실제 개발 순서와 작업 단위를 정리한 문서다.
+- [서버 패키지 / 모듈 구조 제안](./implementation/server-package-layout.md)은 이 작업들을 현재 repo 구조 안에서 어디에 구현할지 정리한 문서다.
+
+---
+
+## 상위 결정 요약
+
+| 항목 | 결정 |
+|---|---|
+| 전투 처리 권한 | 서버 권한 |
+| 접속 방식 | Claude Code 클라이언트가 서버에 접속 |
+| 초기 대전 타입 | 친선 PvP |
+| 실시간성 | 실시간 진행 |
+| 전투 포맷 | 싱글, 6v6, 팀 프리뷰 없음 |
+| 선발 방식 | 1번 슬롯 자동 선발 |
+| 교체 | 자유 교체 가능 |
+| 기절 후 처리 | 다음 포켓몬 직접 선택 |
+| 중복 종 | 금지 |
+| 특수 포켓몬 제한 | 전설+환상 총 2, restricted 최대 1 |
+| 성장 보존 | 실제 레벨 표시 유지 |
+| 레벨 밸런싱 | 50 이후 압축, 유효 레벨 최대 60 |
+| 온라인 파티 | 세대별 등록 스냅샷 1개 활성 |
+| 재등록 | 허용 |
+| 핵심 보안 목표 | 결과 위조 / 성장 상태 위조 방지 |
+
+---
+
+## 관련 문서
+
+- 상위 문서: [Docs Home](../README.md)
+- 구현 우선순위: [구현 로드맵](./roadmap/rollout-plan.md)
+- 구현 PRD: [PvP 초기 구현 PRD](./implementation/prd.md)
+- 구현 작업 분해: [PvP 작업 분해 / TODO](./implementation/todo-breakdown.md)
+- Storage 묶음 시작점: [Storage 인덱스](./server/storage/README.md)
+- Contracts 묶음 시작점: [Contracts 인덱스](./server/contracts/README.md)
+- 등록 계약 상세: [온라인 파티 등록 상세 계약](./server/contracts/party-registration.md)
+- 룸 계약 상세: [친구전 룸 / 매치 성립 상세 계약](./server/contracts/room-and-match.md)
+- 실시간 세션 계약 상세: [실시간 배틀 세션 상세 계약](./server/contracts/realtime-battle-session.md)
+- 코드 구조 제안: [서버 패키지 / 모듈 구조 제안](./implementation/server-package-layout.md)
+- 데이터 중심 상세: [서버 데이터 모델](./server/storage/data-model.md)
+- DB 구체안: [서버 DB 스키마 초안](./server/storage/database-schema.md)
+- 보안 중심 상세: [치트 대응 정책](./security/anti-cheat.md)

docs/pvp/game-design/README.md

@@ -0,0 +1,18 @@
+# PvP 게임 설계 문서
+
+상위 문서: [PvP 문서 인덱스](../README.md)
+
+이 섹션은 Tokénmon 온라인 PvP의 **플레이 경험과 규칙**을 정의한다.
+
+## 포함 문서
+
+1. [배틀 포맷](./battle-format.md)
+2. [성장 및 파티 등록](./progression-and-party-registration.md)
+3. [전설 / 환상 / restricted 정책](./special-pokemon-policy.md)
+4. [세대별 ruleset 설계](./generation-rules.md)
+
+## 권장 읽기 순서
+
+- 먼저 [배틀 포맷](./battle-format.md)으로 플레이 감성을 본다.
+- 다음 [성장 및 파티 등록](./progression-and-party-registration.md)으로 로컬 성장과 온라인 사용의 연결 방식을 본다.
+- 그 다음 [전설 / 환상 / restricted 정책](./special-pokemon-policy.md)과 [세대별 ruleset 설계](./generation-rules.md)로 제약과 세대별 차이를 본다.

docs/pvp/game-design/battle-format.md

@@ -0,0 +1,96 @@
+# PvP 배틀 포맷
+
+상위 문서: [PvP 문서 인덱스](../README.md)
+관련 문서: [성장 및 파티 등록](./progression-and-party-registration.md), [특수 포켓몬 정책](./special-pokemon-policy.md), [실시간 배틀 흐름](../server/battle-flow.md)
+
+## 목표
+
+초기 Tokénmon PvP는 래더/대회 포맷보다 **인게임에서 갑자기 트레이너와 조우한 듯한 감성**을 우선한다.
+즉, 유저는 미리 출전 3마리를 고르고 공개 정보를 많이 보는 방식보다, **자신이 키운 풀 파티를 그대로 들고 와서 실시간으로 판단하는 경험**을 하게 된다.
+
+## 핵심 포맷
+
+- 배틀 타입: **싱글 배틀**
+- 파티 크기: **6마리 등록 / 6마리 전원 사용**
+- 선발: **1번 슬롯 자동 선발**
+- 팀 프리뷰: **없음**
+- 상대 백라인 공개: **없음**
+- 교체: **턴 중 자유 교체 가능**
+- 기절 시: **다음 포켓몬을 직접 선택**
+- 타이머: **행동 선택당 45초**
+- 중복 종: **금지**
+
+## 왜 이런 포맷인가
+
+### 1. 인게임 감성을 유지한다
+
+공식 대회식 팀 프리뷰와 선발 선택은 경쟁적으론 좋지만, Tokénmon이 주려는 감성인 “현장에서 즉시 싸움이 걸리는 느낌”과는 거리가 있다.
+초기 친선 PvP에서는 룰의 완전한 공정성보다도 **게임의 정체성 유지**가 더 중요하다.
+
+### 2. 숨은 정보가 긴장감을 만든다
+
+상대 엔트리를 모르는 상태에서 전투를 시작하면, 교체 판단과 기술 선택의 가치가 커진다.
+이 구조는 특히 친선전에서 “예상 못 한 포켓몬이 뒤에서 나온다”는 재미를 만든다.
+
+### 3. 현재 배틀 엔진 구조와도 잘 맞는다
+
+현 구조는 멀티 배틀보다 싱글 전투에 더 자연스럽게 맞는다. 따라서 초기 온라인 PvP는 싱글에 집중하는 것이 구현 난이도와 안정성 측면에서 맞다.
+
+## 레벨 정책
+
+Tokénmon은 로컬 성장의 보람을 살리고 싶기 때문에, 공식 VGC처럼 모든 포켓몬을 일괄 레벨 50으로 만드는 방향은 초기 친선 PvP와 맞지 않는다.
+
+따라서 초기 룰은 다음처럼 간다.
+
+- 화면 표시 레벨: **실제 성장 레벨 그대로 유지**
+- 배틀 계산용 유효 레벨: **50 이후 압축 적용**
+- 유효 레벨 상한: **60**
+
+이 정책은 다음 균형을 노린다.
+
+- 토큰을 많이 써서 열심히 키운 가치가 남는다.
+- 레벨 차이로 상대를 완전히 찍어누르는 문제는 줄인다.
+- 고레벨 성장의 만족감은 남기되, PvP의 재미는 망치지 않는다.
+
+구체적인 압축 공식은 추후 세부 구현에서 정하되, 룰 상 의미는 “50 이후부터는 성장 효율이 완만해지고, 60 이상은 PvP 계산상 동일 상한”이다.
+
+## 행동 규칙
+
+플레이어는 서버에 아래와 같은 종류의 행동만 보낸다.
+
+- 기술 선택
+- 교체 선택
+- 기절 후 다음 포켓몬 선택
+- 항복
+
+클라이언트는 결과를 계산하지 않는다. 실제 우선순위, 대미지, 상태 변화, 승패 판정은 모두 서버가 수행한다.
+
+## 초기 범위에서 제외하는 것
+
+- 래더 점수 시스템
+- 공개 팀 시트
+- 밴/픽 단계
+- 더블 배틀
+- 토너먼트 운영 기능
+- 관전/리플레이 공유의 완성형 버전
+
+이들은 초기 친선 PvP가 안정화된 뒤 별도 규칙 세트로 분리하는 것이 맞다.
+
+## 확정 규칙 요약
+
+| 항목 | 규칙 |
+|---|---|
+| 배틀 형식 | 싱글 |
+| 사용 마릿수 | 6 |
+| 팀 프리뷰 | 없음 |
+| 선발 | 1번 슬롯 |
+| 타이머 | 45초 |
+| 중복 종 | 금지 |
+| 레벨 표시 | 실제 레벨 |
+| 레벨 계산 | 50 이후 압축, 60 상한 |
+
+## 하위 결정이 필요한 문서
+
+- [성장 및 파티 등록](./progression-and-party-registration.md): 어떤 파티가 온라인에서 유효한가
+- [특수 포켓몬 정책](./special-pokemon-policy.md): 전설/환상/restricted 제한
+- [실시간 배틀 흐름](../server/battle-flow.md): 실제 턴 진행과 이벤트 시퀀스

docs/pvp/game-design/generation-rules.md

@@ -0,0 +1,126 @@
+# 세대별 ruleset 설계
+
+상위 문서: [PvP 문서 인덱스](../README.md)
+관련 문서: [성장 및 파티 등록](./progression-and-party-registration.md), [특수 포켓몬 정책](./special-pokemon-policy.md), [서버 데이터 모델](../server/storage/data-model.md)
+
+## 왜 세대별 ruleset이 필요한가
+
+Tokénmon은 이미 세대별 데이터와 진행 구조를 갖고 있다.
+따라서 온라인 PvP도 하나의 통합 규칙으로 뭉개기보다, **세대별 포켓몬 풀과 ruleset을 별도로 운영**하는 것이 자연스럽다.
+
+이 구조를 선택하면 다음이 가능하다.
+
+- gen1 친선전과 gen4 친선전의 메타를 분리
+- 세대별 restricted 목록 운용
+- 세대별 활성 등록 파티 1개 구조 유지
+- 향후 시즌/이벤트 룰 추가 시 확장 용이
+
+## 공통 규칙
+
+모든 세대 ruleset은 다음 기본 축을 공유한다.
+
+- 싱글 배틀
+- 6마리 등록 / 6마리 전원 사용
+- 팀 프리뷰 없음
+- 1번 슬롯 자동 선발
+- 중복 종 금지
+- 전설+환상 총 2 제한
+- restricted 최대 1
+- 레벨 50 이후 압축 / 유효 레벨 상한 60
+
+## 세대별 활성 파티
+
+플레이어는 세대마다 별도의 온라인 파티를 가진다.
+
+예:
+
+- `player A / gen1 / active_party`
+- `player A / gen4 / active_party`
+- `player A / gen9 / active_party`
+
+온라인 룸 생성 시에도 어느 세대 ruleset인지가 명확해야 한다.
+
+## 세대별 특수 포켓몬 수치 참고
+
+현재 데이터 기준 특수 포켓몬 분포는 다음과 같다.
+
+| 세대 | 포켓몬 수 | legendary | mythical |
+|---|---:|---:|---:|
+| gen1 | 151 | 4 | 1 |
+| gen2 | 100 | 5 | 1 |
+| gen3 | 135 | 8 | 2 |
+| gen4 | 112 | 9 | 5 |
+| gen5 | 156 | 9 | 4 |
+| gen6 | 72 | 3 | 3 |
+| gen7 | 88 | 11 | 5 |
+| gen8 | 96 | 11 | 1 |
+| gen9 | 120 | 11 | 1 |
+
+이 수치는 곧 restricted 규칙이 세대별로 달라져야 함을 의미한다.
+
+## restricted 시드 리스트 v0
+
+아래 목록은 초기 밸런싱 시작점이다.
+확정 영구 규칙이라기보다, **첫 친선 PvP 운영을 위한 시드 목록**으로 본다.
+
+| 세대 | restricted 시드 후보 |
+|---|---|
+| gen1 | 150 Mewtwo |
+| gen2 | 249 Lugia, 250 Ho-Oh |
+| gen3 | 382 Kyogre, 383 Groudon, 384 Rayquaza |
+| gen4 | 483 Dialga, 484 Palkia, 486 Regigigas, 487 Giratina, 493 Arceus |
+| gen5 | 643 Reshiram, 644 Zekrom, 646 Kyurem |
+| gen6 | 716 Xerneas, 717 Yveltal |
+| gen7 | 791 Solgaleo, 792 Lunala, 800 Necrozma |
+| gen8 | 888 Zacian, 889 Zamazenta, 890 Eternatus |
+| gen9 | 1007 Koraidon, 1008 Miraidon |
+
+## gen4 현재 풀 기준 메모
+
+현재 루트 데이터 기준 gen4 특수 포켓몬 풀에서는 다음 판단이 중요하다.
+
+### restricted로 두는 후보
+- Dialga
+- Palkia
+- Regigigas
+- Giratina
+- Arceus
+
+### restricted가 아닌 특수 포켓몬 예시
+- Uxie
+- Mesprit
+- Azelf
+- Heatran
+- Cresselia
+- Phione
+- Manaphy
+- Darkrai
+- Shaymin
+
+특히 Regigigas는 Tokénmon 구현 상태에서 원작의 약점이 충분히 재현되지 않는다면 restricted로 보는 편이 안전하다.
+
+## ruleset 버전 관리
+
+세대 ruleset은 정적 파일 하나로 끝내지 말고, 서버에서 **버전 관리되는 정책 데이터**로 보는 것이 좋다.
+
+예:
+
+- `tkm-friendly-gen4-v1`
+- `tkm-friendly-gen4-v2`
+- `tkm-friendly-gen9-v1`
+
+이렇게 해야 restricted 조정, 레벨 정책 수정, 예외 처리 추가가 기존 배틀 기록과 충돌하지 않는다.
+
+## 설계 결론
+
+온라인 PvP는 “한 개의 공통 모드”가 아니라 다음 구조로 본다.
+
+- 세대별 친선 ruleset
+- 세대별 restricted 목록
+- 세대별 활성 온라인 파티
+- 룸 생성 시 세대와 ruleset이 고정되는 구조
+
+## 다음 문서
+
+- [서버 데이터 모델](../server/storage/data-model.md)
+- [API 계약](../server/api-contract.md)