# 01. 구조와 기술 스택 ## 결정 joke-app과 같은 스택을 쓴다. 이미 운영 중이고 로그인·관리자·채팅·실시간 방이 검증돼 있어서, 같은 틀 위에 음악퀴즈만 새로 얹는 게 가장 빠르고 안전하다. | 영역 | 선택 | joke-app과 관계 | |---|---|---| | 런타임 | Bun 1.3 + TypeScript 5.9, Bun workspaces | 같음 | | 서버 | Hono 4 (HTTP) + Bun.serve WebSocket `/ws`, zod 4 검증 | 같음 | | DB | bun:sqlite (WAL), 번호 붙은 SQL 마이그레이션 | 같음 | | 웹 | React 19 + Vite 8 + react-router + zustand, Pretendard | 같음 | | 스타일 | 손으로 쓴 CSS 변수 한 벌(`global.css`), CSS 프레임워크 없음 | 구조 같음, 색·형태는 새로 | | 테스트 | bun test(단위·통합) + playwright-core e2e(시스템 Chrome) | 같음 | | 배포 | Docker compose(프록시 모드), NPMplus 뒤 | 같음, 포트만 2974 | | 음원 재생 | 브라우저 YouTube IFrame API(숨김) + 서버 기준 시각 동기화 | 새로 추가 | | 곡 수집기 | Bun 스크립트(`tools/collector`), 필요시 Python 보조(하이라이트 분석) | 새로 추가 | ## 폴더 구조 (예정) ``` music_quiz/ ├─ apps/ │ ├─ server/ # Hono + WS + 게임 진행 │ │ ├─ src/auth/ # joke-app에서 가져옴 (discord.ts, sessions.ts, users.ts) │ │ ├─ src/admin/ # roles.ts, audit, settings + 노래 관리 API │ │ ├─ src/rooms/ # 방, 라운드 진행(quiz-engine), 투표 │ │ ├─ src/songs/ # 곡 조회·출제 선택·정답 판정(matcher) │ │ ├─ src/sync/ # 시계 맞추기, 재생 준비·시작·일시정지 조정 │ │ └─ src/db/migrations/ │ └─ web/ │ ├─ src/pages/ # Home, Room, Game, Admin/* │ ├─ src/components/ # ChatPanel, StarRating, YearRange, ArtistPicker, ... │ └─ src/styles/global.css ├─ packages/shared/ # 프로토콜(zod), 정답 정규화 함수(서버·클라 공용), 장르/난이도 상수 ├─ tools/collector/ # 차트·플레이리스트 수집, 유튜브 매칭, 분류 ├─ data/seed/ # sta_songs.json 등 초기 데이터 ├─ deploy/ # Dockerfile, docker-compose.proxy.yml, npmplus 설정 ├─ assets/brand/ # 아이콘 └─ docs/ # 이 문서들 ``` ## joke-app에서 가져올 것 - `auth/discord.ts`, `auth/sessions.ts`, `auth/users.ts` — 디스코드 OAuth(state 서명 쿠키), `sid` 세션 쿠키, 게스트 로그인/병합 - `admin/roles.ts` — `SUPERADMIN_DISCORD_IDS` + `admins` 표, 감사 기록(`admin_audit`) - `ws/rate-limit.ts`, `db/index.ts`, 마이그레이션 001~003(사용자·세션·관리자·게스트 정리) - 웹: `ChatPanel`/`ChatMessage`, `useTypingSignal`(입력 중 신호), `Sheet`, `Toasts`, `SiteHeader`, `NicknameForm`, `SchemaForm`(관리자 자동 폼), 관리자 레이아웃(`.admin-layout`, `.data-table`) - 프로토콜 방식: `{t: ...}` JSON 메시지 + zod 판별 유니온, 방 상태 브로드캐스트 ## 가져오지 않을 것 (컴퓨터 대결 제거) - `packages/shared/src/bots.ts`, `packages/games/src/bots/*`, 서버 `rooms/bots.ts`·`bot-profile.ts`·`luck*.ts`·`ai/*` - 프로토콜 `addBot/removeBot/botLevel`, 설정 `botChat`, "컴퓨터와 연습" 타일, `/api/quick/*`, `docker-compose.ai.yml` - 보드게임 엔진(`cards.ts`, `grid.ts`, `betting.ts`)과 게임 카탈로그 - `BotActivity.tsx`는 사람 "입력 중" 표시 부분만 남긴다 ## 바뀌는 점 - **인원 무제한**: joke-app은 좌석(seats) 배열 + 최대 32명. 음악퀴즈는 좌석 개념 없이 `players` 목록으로 관리하고 상한을 두지 않는다. 서버 보호용 상한만 관리자 설정에 두되 기본값은 "없음". - **방 상태 전송**: 인원이 많아도 버티도록 전체 상태 대신 변경분만 보낸다(joke-app `view-patch.ts` 활용). 점수판은 점수 변동분만, 채팅은 개별 메시지로. - **게임 진행**: 턴제 엔진 대신 시간 기반 라운드 진행기(`quiz-engine`)를 서버에 둔다. 서버 시계가 기준이고 클라이언트는 `serverNow` 보정값으로 카운트다운을 그린다. ## 실시간 메시지 (초안) 클라이언트 → 서버 | t | 내용 | |---|---| | `join` / `leave` | 방 입장/퇴장 | | `config` | (방장) 방 설정 변경 | | `ready` / `start` / `kick` / `host` | 준비, 시작, 강퇴, 방장 넘기기 | | `chat` | 채팅 = 정답 입력 (서버가 정답 판정) | | `typing` | 입력 중 on/off | | `hint` | 힌트 요청(Ctrl+I) | | `skip` | 스킵 투표 토글(Ctrl+K) | | `audioReady` / `stall` | 이번 문제 음원 준비 완료 / 재생 중 버퍼링 보고 | | `replay` | 다시듣기 투표 토글(Ctrl+R) | | `ping` | 시계 맞추기 | 서버 → 클라이언트 | t | 내용 | |---|---| | `room` / `patch` | 방 정보, 변경분 | | `prepare` / `play` / `pause` | 문제 준비(영상 ID·시작 위치), 모두 같은 시각에 재생, 버퍼링 대기 일시정지 | | `round` | 문제 진행 정보(번호, 모드, 제한 시간, 가사 일부) | | `hint` | 힌트 공개(초성 등) | | `vote` | 스킵/힌트 투표 현황 | | `answer` | 정답 줄 + 5줄 블록 한 덩어리(seq), 정답자, 정답(제목-가수), 점수 변화 | | `chat` / `typing` | 채팅, 입력 중 목록 | | `result` | 게임 종료 결과 | ## 메모리·디스크 예산 (8GB 규칙) - 앱 컨테이너 상한 `mem_limit: 1g` (예상 사용 200~400MB) - 수집기·하이라이트 분석은 `systemd-run --user --scope -p MemoryMax=2G`로 따로 실행, 곡 단위로 스트리밍 처리 - 음원은 브라우저가 유튜브에서 직접 재생하므로 서버 음원 캐시 없음 (12 문서 Q1)