90 lines
5.6 KiB
Markdown
90 lines
5.6 KiB
Markdown
# 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)
|