5.6 KiB
5.6 KiB
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)