joke-app/docs/00-overview.md

00. 프로젝트 개요

1. 한 줄 정의

광고 없이 가볍고 빠른, 한국 사람에게 익숙한 보드게임을 친구·가족과 바로 즐길 수 있는 온라인 보드게임 사이트.

2. 만드는 이유

• Board Game Arena(BGA)는 게임 수가 많고 완성도가 높지만, 한국에서 많이 하는 게임(섯다, 7포커, 고스톱, 장기, 윷놀이, 원카드 등)이 없거나 찾기 어렵다.
• 광고·배너·부가 기능이 많아 페이지가 무겁고, 처음 쓰는 사람이 방을 만들고 친구를 부르기까지 단계가 많다.
• 그래서 "링크 하나 보내면 바로 같이 하는" 단순하고 가벼운 사이트를 직접 만든다.

3. 최우선 원칙 (충돌 시 위에 있는 것이 이긴다)

1. 안정성 — 게임 도중 끊겨도 진행 상태가 사라지지 않는다. 서버가 재시작해도 방과 게임이 복구된다. 잘못된 수, 조작된 요청, 숨겨진 정보 유출이 구조적으로 불가능하다.
2. 실시간성 — 수를 두면 같은 방의 모든 사람 화면에 체감 지연 없이(목표 p95 150ms 이내, 같은 국내 망 기준) 반영된다.
3. 쉬움 — 어린아이부터 어르신까지 설명 없이 방을 만들고 들어갈 수 있다. 첫 화면에서 게임 시작까지 클릭 3번 이내.
4. 가벼움 — 첫 화면 JS 150KB(gzip) 이하, 광고·추적 스크립트 없음. 게임 화면 코드는 게임별로 나눠서 필요할 때만 받는다.
5. 게임 수 — 위 네 가지를 지키는 범위에서 게임을 늘린다.

4. 범위 (Scope)

• 게임: 사용자가 지정한 포커(여러 모드), 마작, 오목, 바둑, 체스, 뱅, 섯다(여러 모드) + 한국에서 인기 있는 보드게임. 전체 목록과 순서는 games/README.md.
• 인원: 각 게임의 원래 최소/최대 인원을 그대로 따른다.
• 계정: 디스코드 로그인 또는 닉네임만 정하는 게스트. 디스코드 로그인 사용자도 닉네임을 바꿀 수 있다.
• 방: 6자리 숫자 코드, 초대 링크, 코드/링크 복사, QR, 모바일 공유 시트, 빠른 시작, 관전, 재접속.
• 기기: 모바일(세로) 우선, 태블릿·PC 모두 지원. 최신 Chrome/Safari/Edge/Samsung Internet.

5. 범위 밖 (Non-goals)

• 실제 돈, 유료 재화, 환전, 사이트 전체에서 유지되는 칩/포인트. 포커·섯다·고스톱의 칩/점수는 그 방 안에서만 쓰이고 방이 끝나면 사라진다(법적 위험 회피, 04-stability-security.md 6절).
• 광고, 결제, 친구 추천 알림, 소셜 피드.
• 네이티브 앱(초기에는 웹 + 홈 화면 추가(PWA)로 대체).
• 물리 조작이 핵심인 게임(젠가, 루핑루이, 할리갈리 컵스 등)은 제외. 이유는 games/README.md.

6. 성공 기준 (측정 가능한 목표)

항목	목표
수 반영 지연	서버 처리 p95 < 20ms, 체감 왕복 p95 < 150ms(국내)
재접속 복구	연결이 끊긴 뒤 30초 안에 돌아오면 자리와 패가 그대로
서버 재시작	진행 중이던 모든 방이 재시작 후 자동 복구, 클라이언트는 자동 재연결
동시 접속	단일 서버(4코어/8GB)에서 동시 연결 2,000, 진행 중인 방 500개를 p95 지연 목표 안에서 처리
첫 화면	4G 모바일에서 LCP < 2초, 초기 JS < 150KB gzip
쉬움	처음 온 사람이 링크를 받고 게임 자리에 앉기까지: 닉네임 입력 1번 + 버튼 1번
규칙 정확성	게임마다 규칙 테스트 + 무작위 대국 수천 판 불변식 테스트 통과

7. 문서 구성

README.md의 목차를 참고. 구현은 반드시 이 문서들을 따르고, 구현 중 결정이 바뀌면 문서를 먼저 고친 뒤 코드를 고친다.