diff --git a/docs/00-overview.md b/docs/00-overview.md index 8781f02..9a5e040 100644 --- a/docs/00-overview.md +++ b/docs/00-overview.md @@ -40,6 +40,7 @@ | 09-deploy-ops.md | 배포, 프록시, 인증서, 백업, 모니터링 | | 10-roadmap.md | 작업 순서와 마일스톤 | | 11-questions.md | 사용자에게 확인할 질문·요청사항 | +| 12-decisions.md | **사용자 답변으로 확정된 사항(다른 문서보다 우선)** | ## 그 밖의 자료 | 위치 | 내용 | diff --git a/docs/01-architecture.md b/docs/01-architecture.md index 2a39007..5428753 100644 --- a/docs/01-architecture.md +++ b/docs/01-architecture.md @@ -12,7 +12,7 @@ joke-app과 같은 스택을 쓴다. 이미 운영 중이고 로그인·관리 | 스타일 | 손으로 쓴 CSS 변수 한 벌(`global.css`), CSS 프레임워크 없음 | 구조 같음, 색·형태는 새로 | | 테스트 | bun test(단위·통합) + playwright-core e2e(시스템 Chrome) | 같음 | | 배포 | Docker compose(프록시 모드), NPMplus 뒤 | 같음, 포트만 2974 | -| 음원 처리 | yt-dlp + ffmpeg (서버 캐시 재생 방식일 때) | 새로 추가 | +| 음원 재생 | 브라우저 YouTube IFrame API(숨김) + 서버 기준 시각 동기화 | 새로 추가 | | 곡 수집기 | Bun 스크립트(`tools/collector`), 필요시 Python 보조(하이라이트 분석) | 새로 추가 | ## 폴더 구조 (예정) @@ -24,7 +24,7 @@ music_quiz/ │ │ ├─ src/admin/ # roles.ts, audit, settings + 노래 관리 API │ │ ├─ src/rooms/ # 방, 라운드 진행(quiz-engine), 투표 │ │ ├─ src/songs/ # 곡 조회·출제 선택·정답 판정(matcher) -│ │ ├─ src/audio/ # 음원 캐시, 클립 스트리밍 +│ │ ├─ src/sync/ # 시계 맞추기, 재생 준비·시작·일시정지 조정 │ │ └─ src/db/migrations/ │ └─ web/ │ ├─ src/pages/ # Home, Room, Game, Admin/* @@ -67,20 +67,23 @@ music_quiz/ | `typing` | 입력 중 on/off | | `hint` | 힌트 요청(Ctrl+I) | | `skip` | 스킵 투표 토글(Ctrl+K) | -| `audioReady` | 이번 문제 음원 준비 완료 보고 | +| `audioReady` / `stall` | 이번 문제 음원 준비 완료 / 재생 중 버퍼링 보고 | +| `replay` | 다시듣기 투표 토글(Ctrl+R) | +| `ping` | 시계 맞추기 | 서버 → 클라이언트 | t | 내용 | |---|---| | `room` / `patch` | 방 정보, 변경분 | -| `round` | 문제 시작(번호, 모드, 재생 시작 시각, 길이, 음원 토큰 또는 가사 일부) | +| `prepare` / `play` / `pause` | 문제 준비(영상 ID·시작 위치), 모두 같은 시각에 재생, 버퍼링 대기 일시정지 | +| `round` | 문제 진행 정보(번호, 모드, 제한 시간, 가사 일부) | | `hint` | 힌트 공개(초성 등) | | `vote` | 스킵/힌트 투표 현황 | -| `answer` | 정답자, 정답(제목-가수), 점수 변화 | +| `answer` | 정답 줄 + 5줄 블록 한 덩어리(seq), 정답자, 정답(제목-가수), 점수 변화 | | `chat` / `typing` | 채팅, 입력 중 목록 | | `result` | 게임 종료 결과 | ## 메모리·디스크 예산 (8GB 규칙) - 앱 컨테이너 상한 `mem_limit: 1g` (예상 사용 200~400MB) - 수집기·하이라이트 분석은 `systemd-run --user --scope -p MemoryMax=2G`로 따로 실행, 곡 단위로 스트리밍 처리 -- 음원 캐시는 디스크 상한(기본 5GB, 관리자 설정)을 두고 오래 안 쓴 것부터 지운다. .9 남은 용량이 이미 140GB라 원본 전체 보관은 하지 않는다 (11-questions.md 참고) +- 음원은 브라우저가 유튜브에서 직접 재생하므로 서버 음원 캐시 없음 (12 문서 Q1) diff --git a/docs/04-room-settings.md b/docs/04-room-settings.md index 52b21c4..3e1cbb4 100644 --- a/docs/04-room-settings.md +++ b/docs/04-room-settings.md @@ -12,12 +12,14 @@ | └ 보고맞출시간 (가사보고) | 30초, 60초, 90초, 120초, 150초, 무제한 | 무제한 | | 장르 (복수) | 아래 목록 | 전체 | | 연도 | 범위 슬라이더 + 시작/끝 선택 상자 | 전체(가장 오래된 곡 ~ 올해) | -| 난이도 | 별 10개, 왼쪽부터 채움 | 3 (Q7) | +| 난이도 | 별 10개, 왼쪽부터 채움 — N단계 곡만 | 3 (Q7) | | 정답방식 | 제목만 / 가수만 / 제목+가수(순서 무관) | 제목만 | -| 정답인식 | 띄어쓰기 · 숫자 · 특수문자 각각 켜기/끄기 | 모두 끔 (Q2) | -| 힌트공개 | 없음, 15초, 30초, 45초, 60초 | 없음 | +| 정답인식 | 띄어쓰기 · 숫자 · 특수문자 각각 켜기/끄기 | **모두 켬** (Q2) | +| 힌트공개 | 없음, 15초, 30초, 45초, 60초, 직접선택 | 없음 | +| └ 힌트인원(이상) (직접선택일 때) | 1명, 2명, 1/3명, 1/2명, 2/3명, 전체 | 1/3명 (Q3) | | 스킵인원(이상) | 없음, 1명, 2명, 1/3명, 1/2명, 2/3명, 전체 | 1/3명 | -| 문제 수 (제안) | 10, 20, 30, 50, 100 | 30 (Q8) | +| 다시듣기인원(이상) (듣기 모드) | 없음, 1명, 2명, 1/3명, 1/2명, 2/3명, 전체 | 1/3명 (Q4) | +| 문제 수 | 10, 20, 30, 50, 100, 무제한(조건에 맞는 곡 수) | 30 (Q8) | | 방 공개 (제안) | 공개 / 비공개(코드·링크로만) / 비밀번호 | 공개 | ## 모드 @@ -95,17 +97,20 @@ - 별 색: 1~3 겨자 / 4~6 주황 / 7~8 빨강 / 9~10 보라 (03 문서) - 마우스를 올리면 그 단계 이름·설명 미리보기, 누르면 확정 -- **선택 의미(제안)**: 별 N개 = "N단계까지(1~N)" 출제. 옆에 "이 단계만" 토글을 두면 N단계 곡만 (Q7) +- **선택 의미(확정)**: 별 N개 = **N단계 곡만** 출제. 한 곡이 장르·연도 기준에 따라 여러 단계를 가질 수 있어서 같은 곡이 다른 단계 방에도 나올 수 있다 (12 문서 Q7) ## 정답방식 · 정답인식 - 정답방식: 제목만 / 가수만 / 제목+가수 — 제목+가수는 **순서 상관없이** 한 줄에 둘 다 (05 문서 판정 규칙) - 정답인식: 버튼 3개, 누를 때마다 켜짐/꺼짐 - - **켜짐 = 그 요소까지 정확히 쳐야 정답**, 꺼짐 = 무시하고 비교 (해석 확인: Q2) + - **켜짐 = 그 요소까지 정확히 쳐야 정답**, 꺼짐 = 무시하고 비교 (확정: Q2), 기본은 셋 다 켬 - 대소문자는 항상 무시 ## 힌트공개 -- 문제 시작 후 그 시간이 지나면 초성 힌트 자동 공개. 없음 = 자동 공개 안 함 -- Ctrl+I 힌트 요청 규칙은 05 문서·Q3 +- 15~60초: 문제 시작 후 그 시간이 지나면 초성 힌트 자동 공개. 없음 = 힌트 없음 +- **직접선택**: 자동 공개 없이 힌트 투표(Ctrl+I)가 **힌트인원** 이상이면 공개 (12 문서 Q3) + +## 다시듣기인원(이상) +- 듣기 모드에서 다시듣기 투표(Ctrl+R)가 이 인원 이상이면 모두 같이 같은 구간을 처음부터 다시 듣는다. 없음 = 다시듣기 불가 (12 문서 Q4) ## 스킵인원(이상) - 글자 오른쪽 위에 동그라미 속 느낌표 아이콘 ⓘ(!) — 마우스를 올리면 말풍선: @@ -114,5 +119,6 @@ ## 설정 저장 - 방 설정은 방이 살아있는 동안 유지, `다시 하기`도 같은 설정 +- `이어풀기`: 같은 설정 + 이번 퀴즈에서 나온 곡 제외 + 점수 이어서. `퀴즈 저장/불러오기`로 나중에 이어서 할 수 있음 (12 문서 Q8) - 개인 "최근 설정 불러오기"(로그인 사용자): 방 만들 때 내가 마지막에 쓴 설정으로 시작 - 관리자는 사이트 기본 설정(새 방의 기본값)과 잠금(특정 항목 고정)을 바꿀 수 있음 diff --git a/docs/05-game-flow.md b/docs/05-game-flow.md index 15b3781..e11d0f5 100644 --- a/docs/05-game-flow.md +++ b/docs/05-game-flow.md @@ -9,12 +9,13 @@ - 방 설정(모드·장르·연도·난이도·가수)에 맞는 곡을 DB에서 고른다. 유튜브 주소가 확인된 곡만(가사 모드는 가사가 있는 곡만) - 같은 게임 안에서 중복 없음, 같은 방에서 최근 3게임에 나온 곡은 뒤로 미룬다 - 같은 가수가 연달아 나오지 않게 섞는다(가수노래 맞추기 모드 제외) +- 문제 수 "무제한"이면 조건에 맞는 곡을 모두 출제. 이어풀기·불러오기면 이미 나온 곡은 빼고 뽑는다 - 조건에 맞는 곡이 문제 수보다 적으면 시작 전에 "조건에 맞는 곡이 N곡뿐이에요"라고 알려주고 그대로 시작/설정 변경 선택 -### 2) 문제 준비 (최대 5초) -- 서버가 다음 곡 음원을 미리 준비(현재 문제 진행 중에 다음 2곡을 미리 받아 둠) -- 클라이언트는 음원을 받아 재생 준비 후 `audioReady` 보고 -- 전원 준비 또는 5초 경과 시 시작(늦은 사람은 늦게 들어온 만큼 건너뛰고 재생) +### 2) 문제 준비 (최대 15초) +- 서버가 `prepare{videoId, startSec}` 전송 → 각자 숨긴 유튜브 플레이어에 음소거로 불러 시작 위치까지 버퍼링 후 `audioReady` 보고 (12 문서 Q1) +- 전원 준비되면 `play{startAt}`로 모두 같은 순간 시작. 15초가 지나도 안 된 사람은 준비되는 즉시 현재 위치로 합류 +- 재생 중 누군가 버퍼링하면 모두 일시정지 후 같은 위치에서 재개(문제당 최대 10초) - 화면: "3번째 문제" 카드 + 3·2·1 카운트 ### 3) 문제 진행 @@ -24,7 +25,7 @@ | 가수노래 맞추기 | 위와 같음 + 상단에 "선택한 가수" 표시 | 정답 / 스킵 / 제한 시간 | | 가사보고 맞추기 | 음악 없이 가사 카드(제목 단어는 ○로 가림), 남은 시간 막대 | 정답 / 스킵 / 보고맞출시간 | -- **듣고맞출시간**이 1초~1분이면 그만큼만 재생하고 멈춘다. 재생이 끝나도 문제는 계속(채팅으로 계속 맞힐 수 있음). `다시 듣기` 버튼으로 같은 구간을 본인만 다시 들을 수 있다(최대 3회, 11-questions.md Q4) +- **듣고맞출시간**이 1초~1분이면 그만큼만 재생하고 멈춘다. 재생이 끝나도 문제는 계속(채팅으로 계속 맞힐 수 있음). `다시듣기`(Ctrl+R) 투표가 다시듣기인원 이상이면 **모두 같이** 같은 구간을 처음부터 다시 듣는다(횟수 제한 없음, 제한 시간은 다시 센다 — 12 문서 Q4) - **끝까지**면 곡이 끝날 때까지 재생, 곡이 끝나면 문제 종료 - 문제 하나의 최대 시간(제한 시간): 짧은 클립 모드 기본 60초, 끝까지 모드는 곡 길이, 관리자 설정에서 변경 @@ -37,7 +38,7 @@ ### 5) 결과 - 순위, 점수, 맞힌 곡 수, 가장 빨리 맞힌 곡 - 이번 게임 곡 목록(유튜브 링크 `https://youtu.be/ID` 포함) — 몰랐던 노래 다시 듣기 -- `다시 하기`(같은 설정으로 대기실 복귀), `나가기` +- `이어풀기`(나온 곡 빼고 점수 이어서 바로 시작), `다시 하기`(같은 설정으로 대기실 복귀), `퀴즈 저장`, `나가기` (12 문서 Q8) ## 정답 판정 ### 정규화 (서버·클라이언트 공용, `packages/shared/answer.ts`) @@ -49,7 +50,7 @@ - **띄어쓰기** 끔 → 공백 무시 (`사건의지평선` = `사건의 지평선`) - **숫자** 끔 → 숫자 무시, 켬 → 숫자까지 정확히 (`24시간이 모자라`) - **특수문자** 끔 → `!?.,'"()-~·…♡` 등 무시 (`Bubble Pop!` = `bubble pop`) - - (해석은 11-questions.md Q2에서 확인) + - 기본값은 셋 다 켬 = 엄격 (12 문서 Q2) 6. **빈 비교 키 방지** — 숫자·특수문자를 지우면 정답이 사라지는 곡이 실제로 있다(`0+0`, `160`, `365`, `3! 4!`, `11:11`, `24시간이 모자라`의 `24` 등) - 정답 후보마다 비교 키를 만들 때, 지운 뒤 **키가 비거나 한글·영문이 하나도 남지 않으면** 그 후보는 숫자를 보존하고, 그래도 비면 특수문자까지 보존한 키를 쓴다 (`0+0` → 숫자 보존 `00` → 그래도 모호하면 원문 `0+0`) - 채팅 쪽도 같은 규칙을 후보별로 똑같이 적용해서 비교한다(후보가 숫자를 보존했으면 채팅도 숫자를 보존) @@ -69,13 +70,13 @@ - 오타 허용(유사도 판정)은 하지 않는다 — 유즈맵처럼 정확히 쳐야 맞음. 단, 관리자 별칭으로 흔한 표기 차이를 흡수 ## 점수 -- 기본: 먼저 맞힌 1명 +1점 (유즈맵 방식) +- 먼저 맞힌 1명만 +1점 (유즈맵 방식, Q5 확정) - 동점이면 맞힌 문제의 평균 정답 시간이 짧은 사람이 위 -- (선택) 추가 규칙은 11-questions.md Q5 ## 힌트 -- **자동 공개**: 방 설정 "힌트공개" 시간(15/30/45/60초)이 지나면 공개. "없음"이면 자동 공개 안 함 -- **Ctrl+I 요청**: 누르면 힌트 투표 1표. 스킵과 같은 인원 기준을 넘으면 즉시 공개 (11-questions.md Q3) +- **자동 공개**: 방 설정 "힌트공개" 시간(15/30/45/60초)이 지나면 공개 +- **직접선택**: 힌트 투표(Ctrl+I / 힌트 버튼)가 "힌트인원" 이상이면 즉시 공개. 화면 아래 스킵 인원 옆에 `힌트 0/3` 표시 +- 직접선택이 아닐 때 Ctrl+I: "없음"이면 "힌트가 꺼져 있어요", 시간 공개면 "힌트는 N초 뒤에 공개돼요" 안내 (12 문서 Q3) - 힌트 내용(단계별) 1. 초성: `ㄱ (ㄱ) - ㅅㄱㅇㄴㅂ` (정답방식에 해당하는 부분만, 띄어쓰기 유지) 2. (가사 모드) 가사 2줄 더 공개 diff --git a/docs/06-chat.md b/docs/06-chat.md index c0bd985..bc15cda 100644 --- a/docs/06-chat.md +++ b/docs/06-chat.md @@ -26,13 +26,16 @@ joke-app은 말풍선이지만, 빠르게 많이 오가는 정답 채팅에는 ## 지연 없는 전송 - 보내는 즉시 내 화면에 먼저 표시(낙관적 표시), 서버 확인이 오면 확정 — 체감 지연 0 -- 서버는 받은 채팅을 **정답 판정과 동시에** 바로 방 전체에 중계(별도 큐·지연 없음) -- 도배 방지는 지연 대신 토큰 버킷(초당 6회, 순간 12회)으로만 막고, 넘치면 그 줄만 거절하고 안내 +- 서버는 받은 채팅을 **정답 판정과 동시에** 바로 방 전체에 중계(별도 큐·묶음 전송·지연 없음). 묶어서 보내는 건 "입력 중" 표시뿐 +- 모든 채팅·정답 메시지에 방 단위 순번 `seq`. 화면은 순번대로 그리고, 아직 확인 안 된 내 말은 **항상 맨 아래**에 둔다(확인되면 순번 자리로) +- 도배 방지는 **기본 꺼짐**. 관리자 사이트 설정에서 켜면 토큰 버킷(기본 초당 6회, 순간 12회)으로만 막고, 넘치면 그 줄만 거절하고 안내 (12 문서) - WebSocket 한 연결로 처리, 메시지 크기 200자 제한(joke-app `CHAT_MAX`) - 정답 판정 순서는 **서버 도착 순서**가 기준(동시에 맞히면 먼저 도착한 사람) ## 정답 표시 (스타크래프트 방식) 누군가 정답을 치면 채팅에 그 줄을 정답 색(초록 굵게)으로 표시하고, 바로 아래에 **공백 5줄**을 넣고 그 가운데(3번째 줄)에 정답을 크게 보여준다. + +**정답 줄과 블록은 한 덩어리**: 서버는 정답 채팅을 `chat`으로 따로 보내지 않고 정답 줄 + 블록을 `answer` 메시지 하나로 보낸다. 화면도 한 항목으로 그린다. 그래서 정답 판정 직전에 누가 채팅을 쳐도 정답 줄과 공백 사이에 끼어들 수 없고, **공백 바로 위 줄은 항상 정답 줄**이다. ``` 철수 : sg워너비 광 ← 정답 줄(초록 + ✔) ← 공백 1 @@ -51,12 +54,13 @@ joke-app은 말풍선이지만, 빠르게 많이 오가는 정답 채팅에는 |---|---| | Ctrl + I | 힌트 요청 | | Ctrl + K | 스킵 투표 (다시 누르면 취소) | +| Ctrl + R | 다시듣기 투표 (듣기 모드, 새로고침 대신) | | Enter | 전송 | | Esc | 입력 지우기 | | ↑ | 내가 마지막에 보낸 말 다시 불러오기 | -- 브라우저 기본 동작(Ctrl+K = 주소창 검색, Ctrl+I = 기울임 등)은 게임 화면에서만 막는다(`preventDefault`) -- 화면에 버튼도 같이 둔다: `힌트 (Ctrl+I)` `스킵 (Ctrl+K)` — 휴대폰은 버튼으로 +- 브라우저 기본 동작(Ctrl+K = 주소창 검색, Ctrl+I = 기울임, Ctrl+R = 새로고침)은 게임 화면에서만 막는다(`preventDefault`) +- 화면에 버튼도 같이 둔다: `힌트 (Ctrl+I)` `스킵 (Ctrl+K)` `다시듣기 (Ctrl+R)` — 휴대폰은 버튼으로 ## 채팅 내용 보호 - 비속어 필터(사이트 설정 금칙어), 방장 채팅 끄기 옵션은 두지 않음(채팅이 곧 입력이라) diff --git a/docs/07-song-database.md b/docs/07-song-database.md index f777adc..07f9815 100644 --- a/docs/07-song-database.md +++ b/docs/07-song-database.md @@ -74,6 +74,7 @@ | 10 | 최하위 3~5% | - **실제 플레이로 보정**: 출제 20회 이상인 곡은 정답률·평균 정답 시간을 보고 단계가 안 맞으면 관리자에게 조정 제안(통계 메뉴에서 승인) - 관리자가 손으로 고정한 난이도는 자동 계산이 덮어쓰지 않음 +- **기준별 단계(Q7)**: 같은 곡이라도 전체 기준과 장르·연대 기준에서 단계가 다를 수 있어 `song_levels`에 기준별로 저장한다. 방에서 N단계를 고르면 해당 기준 중 하나라도 N단계인 곡이 출제 후보(12 문서) ## 연도·장르 분류 - 연도: 멜론 발매일(없으면 지니·벅스, 그래도 없으면 첫 차트 진입 연도) @@ -86,7 +87,7 @@ songs(id PK, melon_id UNIQUE, title, artist_display, release_date, year, duration_ms, youtube_id, youtube_status /*matched|candidate|none|dead*/, youtube_score, mv_youtube_id, highlight_ms, highlight_source /*admin|heatmap|analysis|rule*/, - popularity, difficulty_auto, difficulty_manual, hidden, note, + embeddable, popularity, difficulty_auto, difficulty_manual, hidden, note, created_at, updated_at, deleted_at) artists(id PK, melon_artist_id, name, name_en, kind /*solo|group|unit*/, gender, debut_year) song_artists(song_id, artist_id, role /*main|feat*/, PK(song_id, artist_id)) @@ -94,6 +95,7 @@ artist_aliases(artist_id, alias, PK(artist_id, alias)) song_aliases(song_id, alias, part /*title|artist*/, source /*auto|admin|machugi*/) genres(id PK, name, grp /*region|style|theme*/, sort, hidden) song_genres(song_id, genre_id, source) +song_levels(song_id, scope /*all|genre:|decade:<1990>*/, level, source /*auto|admin*/, PK(song_id, scope)) lyrics(song_id PK, text, source, fetched_at) chart_entries(id PK, source, chart, period, rank, raw_title, raw_artist, raw_ref, song_id, fetched_at) song_sources(song_id, source, ref) -- 예: sta 맵 이름, 노라보세, 마추기 퀴즈 ID @@ -106,5 +108,5 @@ collect_jobs(id PK, kind, params_json, status, progress, log, started_at, finish - 출제 조회 속도를 위해 `(year)`, `(difficulty)`, `song_genres(genre_id)`, `(youtube_status)` 색인 ## 저작권·운영 메모 -- 음원 파일은 재생용 캐시로만 두고(상한 있음), 가사는 퀴즈 표시용 일부만 화면에 노출 +- 음원 파일은 저장하지 않고(유튜브 플레이어로 재생), 가사는 퀴즈 표시용 일부만 화면에 노출 - 지인용 비공개 성격의 사이트로 운영(검색엔진 차단 `noindex`), 외부 사이트 데이터는 요청 속도 제한을 지키고 원본을 재배포하지 않음 diff --git a/docs/08-youtube-playback.md b/docs/08-youtube-playback.md index d73ff59..22fff0a 100644 --- a/docs/08-youtube-playback.md +++ b/docs/08-youtube-playback.md @@ -19,9 +19,11 @@ | 일반 유튜브 검색 `아이유 Love wins all` | 상위 6개에 Topic 없음(MV·라이브만) → YT Music 노래 검색이 꼭 필요한 경우 | | yt-dlp `https://youtu.be/VO88htcm09E` (광) | 채널 `SG Wannabe - Topic`, 설명 `Provided to YouTube by Genie Music`, 길이 237초, **가장 많이 다시 본 구간 75.8초**(후렴) | | yt-dlp `JleoAppaxi0` (Love wins all MV) | 가장 많이 다시 본 구간 161.5초 | +| `ytm_cookie.txt`로 YT Music 노래 검색 `아이유 Love wins all` | HTTP 200, 로그인 상태, 노래 결과 1위 `Wu5FY8J6P8Q` Love wins all (4:32) ✔ | +| oEmbed 퍼가기 확인 `Wu5FY8J6P8Q`, `VO88htcm09E`, `GXNHaLIhyMY` | 모두 200(퍼가기 허용) ✔ | ### 매칭 순서 (`tools/collector/youtube-match.ts`) -1. **YT Music 노래 검색**(music_bot_v2 방식, 쿠키 인증) `"{가수} {제목}"` → 노래 결과의 `videoId` +1. **YT Music 노래 검색**(music_bot_v2 방식, 사용자가 준 `ytm_cookie.txt` 쿠키 인증 — 봇 쿠키와 분리) `"{가수} {제목}"` → 노래 결과의 `videoId` - `music.youtube.com/watch?v=ID` 주소를 `www.youtube.com/watch?v=ID`로 바꾸고 최종 저장은 **`https://youtu.be/ID`** 2. 못 찾으면 **일반 유튜브 검색** `"{가수} {제목}"`, `"{가수} - Topic {제목}"` → 채널명이 `- Topic`으로 끝나는 결과 우선 3. 그래도 없으면 **Lavalink `ytsearch:`** 결과 중 `author`가 `- Topic`으로 끝나는 것 @@ -31,13 +33,13 @@ - 길이가 멜론 곡 길이와 ±5초 +20, ±15초 초과 −30 - `MV`, `Live`, `커버`, `cover`, `MR`, `inst`, `노래방`, `1시간`, `가사`, `lyrics`, `sped up`, `remix`(원곡이 리믹스가 아닐 때) −40 5. 최고 점수 ≥ 80 → 자동 확정(`matched`), 50~79 → `candidate`(관리자 확인 대기), 그 아래 → `none` -6. 확정된 주소는 Lavalink `loadtracks`로 한 번 더 재생 가능 확인(지역 제한·삭제 영상 걸러냄), 주 1회 재확인 +6. 확정된 주소는 Lavalink `loadtracks`로 한 번 더 재생 가능 확인(지역 제한·삭제 영상 걸러냄) + **oEmbed로 퍼가기 허용 확인**(IFrame 재생이라 필수), 주 1회 재확인 ### 요청 속도 - 곡당 검색 1~3회, 2초 간격, 하루 최대 3,000곡. 차단 신호(HTTP 429, 봇 확인 페이지) 보이면 자동 중단 후 다음 날 재개 ## 2. 재생 방식 -두 가지 중 하나를 고른다 (11-questions.md Q1). **A안 추천**. +**확정: B안(숨긴 IFrame 플레이어) + 서버 기준 동기화**. 자세한 동기화 규칙은 12-decisions.md Q1. 아래 A안은 검토 기록으로만 남긴다. ### A안: 서버 음원 캐시 + 구간 스트리밍 (추천) - 서버가 `yt-dlp`로 해당 곡 음원만 받아(opus/m4a, 곡당 3~5MB) 디스크 캐시에 두고, 문제마다 필요한 구간만 `ffmpeg`로 잘라 일회용 주소(`/api/audio/{토큰}`)로 보낸다 @@ -48,16 +50,20 @@ - 모두 같은 순간에 시작(서버 기준 시각에 맞춰 재생) - 단점: 서버가 음원을 받는 시간(곡당 2~5초, 다음 곡을 미리 받아서 감춤), 디스크 사용(캐시 상한 5GB ≈ 1,200곡, 오래 안 쓴 것부터 삭제), 유튜브 차단 대응 필요(music_bot_v2의 쿠키·poToken 갱신 방식 재사용) -### B안: 유튜브 플레이어(IFrame)를 화면 뒤에 숨겨서 재생 -- 장점: 서버 부담 없음, 구현 간단 -- 단점: 위 A안 장점이 전부 반대(영상 ID 노출, 광고, 버퍼링으로 1초 모드 부정확, 일부 영상은 퍼가기 금지) +### B안: 유튜브 플레이어(IFrame)를 화면 뒤에 숨겨서 재생 — 채택 +- 장점: 서버 부담 없음, 음원 캐시 디스크 불필요 +- 약점과 대응 + - 영상 ID 노출 → 준비 단계에만 전송, 방 상태에 미포함(완전 차단은 불가, 사용자 감수) + - 광고 → 준비 단계에서 음소거로 먼저 재생해 광고를 흘려보내고, 실제 곡이 재생되기 시작한 뒤에야 `audioReady` + - 버퍼링·1초 모드 오차 → 서버 시각 기준 시작·정지, 버퍼링 시 모두 일시정지 후 재개, 1초마다 위치 보정 + - 퍼가기 금지 영상 → 매칭 때 oEmbed(`https://www.youtube.com/oembed?url=https://youtu.be/ID`)가 401이면 제외, 재생 오류 101/150이면 건너뛰고 "재생 불가" 표시 ## 3. 재생 위치 "처음부터 / 하이라이트부터" 하이라이트 = 그 곡에서 가장 유명한 부분(대개 후렴). 곡마다 `highlight_ms`를 저장한다. 구하는 순서 1. **유튜브 "가장 많이 다시 본 구간"** — 조회수가 충분한 영상은 `yt-dlp`가 재생 구간별 인기도(heatmap)를 준다. 가장 높은 구간 시작점을 쓴다(MV와 Topic 영상 길이가 같으면 MV 쪽 heatmap도 활용) -2. **음원 분석** — 캐시된 음원으로 반복 구간(후렴) 찾기(크로마 자기유사도 방식, Python `librosa`, 곡당 1~2초, 메모리 300MB 이하) +2. **음원 분석** — (관리자가 일괄 실행할 때만) 음원을 잠깐 받아 반복 구간(후렴) 찾기(크로마 자기유사도 방식, Python `librosa`, 곡당 1~2초, 메모리 300MB 이하) 3. **관리자 지정** — 관리자 노래 편집 화면에서 미리듣기 중 "지금 위치를 하이라이트로" 버튼 4. 셋 다 없으면 곡 길이의 30% 지점(대부분 첫 후렴 근처) diff --git a/docs/09-deploy-ops.md b/docs/09-deploy-ops.md index fc60c56..7e03b62 100644 --- a/docs/09-deploy-ops.md +++ b/docs/09-deploy-ops.md @@ -4,8 +4,8 @@ ``` 인터넷 → NPMplus (192.168.10.3:443, mquiz.tkrmagid.kr, Let's Encrypt) → 192.168.10.9:2974 → 컨테이너 music_quiz-app:3000 (Bun) - ├─ /data/app.db (SQLite, WAL) - └─ /data/audio-cache (음원 캐시, 상한 5GB) + └─ /data/app.db (SQLite, WAL) + ↘ 음악은 각자 브라우저의 유튜브 플레이어가 재생(서버 음원 캐시 없음) ↘ Lavalink 192.168.10.6:2333 (유튜브 검색·재생 가능 확인, 읽기 전용 사용) ``` - 위치: .9 `/home/claude/projects/music_quiz` (joke-app과 같은 방식) @@ -24,8 +24,7 @@ | `DISCORD_CLIENT_SECRET` | 비밀 저장소에서 주입 | | `SUPERADMIN_DISCORD_IDS` | `293719842274541579,1352267557213573160` | | `LAVALINK_URL` / `LAVALINK_PW` | music_bot_v2 설정 재사용 | -| `YT_COOKIE_PATH` | (A안일 때) 유튜브 쿠키 파일 경로 | -| `AUDIO_CACHE_MAX_GB` | `5` | +| `YT_COOKIE_PATH` | `/run/secrets/ytm_cookie.txt` (호스트 `/home/claude/.config/music_quiz/ytm_cookie.txt`를 읽기 전용 연결) | ## 프록시 · 인증서 - DNS: `mquiz.tkrmagid.kr` → CNAME `tkrmagid.kr` (이미 등록돼 있음 확인) @@ -34,12 +33,12 @@ ## 백업 - 매일 새벽 SQLite `VACUUM INTO` 스냅샷 → 7일 보관(.9) + 주 1회 Nextcloud `/claude/music_quiz/`로 복사 -- 음원 캐시는 백업하지 않음(다시 받으면 됨) ## 모니터링 - `/healthz`(DB·디스크·Lavalink 연결 상태), 컨테이너 healthcheck -- 관리자 대시보드에 수집 작업 실패, 유튜브 차단 신호, 캐시 사용량 표시 +- 관리자 대시보드에 수집 작업 실패, 유튜브 차단 신호, 쿠키 만료 표시 - 주 1회 유튜브 주소 재확인(삭제·지역제한 감지 → "재생 불가"로 표시 후 재매칭) ## 디스크 -- .9 남은 공간이 약 140GB(권장 150GB 이상보다 적음). 음원 캐시는 상한 5GB로 시작, 늘리려면 Q15 결정에 따름 +- .9 남은 공간 약 140GB(72% 사용). 음원 캐시가 없어서 이 프로젝트는 DB 정도만 쓴다 +- 용량이 부족해지면(남은 공간 50GB 미만) `~/disk-low-cleanup.sh`가 다시 받으면 되는 캐시(pip·uv·npm·bun 캐시, `~/.tmp` 3일 지난 파일, 도커 빌드 캐시)만 지운다. 모델·프로젝트·DB·실행 중인 작업은 건드리지 않는다 (12 문서) diff --git a/docs/10-roadmap.md b/docs/10-roadmap.md index 71cad6c..6f113fb 100644 --- a/docs/10-roadmap.md +++ b/docs/10-roadmap.md @@ -4,14 +4,14 @@ | 단계 | 내용 | 끝났다고 보는 기준 | |---|---|---| -| **0. 설계** (지금) | md 문서, 아이콘, 예시 화면, 보고서.pdf | 사용자 확인 + 질문 답변 | +| 0. 설계 ✔ | md 문서, 아이콘, 예시 화면, 보고서.pdf, 답변 반영(12 문서) | 사용자 답변 완료(2026-10-18) | | 1. 뼈대 | joke-app에서 auth·세션·관리자·DB·UI 키트 가져오기, 봇 코드 제거, 새 색·아이콘 적용 | 디스코드 로그인 → 아이콘 보이는 동의 화면 → 로그인 성공(e2e), 슈퍼어드민 2명 관리자 접근 | | 2. 배포 먼저 | Docker, 2974 포트, NPMplus, 인증서 | https://mquiz.tkrmagid.kr 에서 로그인 실제 확인 | | 3. 노래 DB 1차 | sta_songs 803곡 + 노라보세 8,572곡 가져오기, 멜론 정보, 유튜브 Topic 매칭 | 곡 9천+, 유튜브 확정률 90%+, 관리자 노래 목록에서 확인 | | 4. 방·로비 | 방 목록, 방 만들기, 인원 무제한, 방 설정 전체(04 문서) | 설정 변경이 모두에게 즉시 반영, "조건에 맞는 곡 N곡" 정확 | -| 5. 게임 핵심 | 라운드 진행, 음원 재생(Q1 방식), 정답 판정, 점수, 결과 | 3명 동시 e2e로 30문제 끝까지, 정답 판정 단위 테스트 | +| 5. 게임 핵심 | 라운드 진행, 숨긴 유튜브 플레이어 동기화 재생(준비·동시 시작·버퍼링 일시정지), 정답 판정, 점수, 결과, 이어풀기·저장/불러오기 | 3명 동시 e2e로 30문제 끝까지, 정답 판정 단위 테스트 | | 6. 채팅 | 가운데 아래 큰 채팅, 입력 중, 5줄 정답 블록, 단축키 | 체감 지연 없음(로컬 왕복 < 50ms), Ctrl+I/K 동작 | -| 7. 힌트·스킵·모드 | 초성 힌트, 스킵 투표, 가수노래·가사 모드, 하이라이트 | 모드 3종 e2e | +| 7. 힌트·스킵·모드 | 초성 힌트(시간/직접선택 투표), 스킵·다시듣기 투표, 가수노래·가사 모드, 하이라이트 | 모드 3종 e2e | | 8. 관리자 완성 | 노래 CRUD·필터·후보 확인·하이라이트 지정, 수집 작업 UI, 통계, 사용자/관리자 | 관리자 e2e(joke-app admin.e2e 확장) | | 9. 수집 확장 | 멜론·지니·벅스 연도별/실시간, 유튜브·스포티파이 플레이리스트, 노래방 차트, 난이도 계산 | 곡 1만+, 난이도 분포 확인 | | 10. 다듬기 | 휴대폰 화면, 다크 테마, 접근성 검사, 부하 테스트(100명 방) | axe 위반 0, 100명 방에서 채팅 지연 < 200ms | diff --git a/docs/11-questions.md b/docs/11-questions.md index c3c2f1b..fee469b 100644 --- a/docs/11-questions.md +++ b/docs/11-questions.md @@ -1,5 +1,7 @@ # 11. 질문 · 요청사항 +> **2026-10-18 답변 완료 — 확정 내용은 12-decisions.md를 보세요.** 아래는 질문 당시 기록입니다. + 답을 주시지 않은 항목은 **추천안(★)** 으로 진행합니다. 번호만 골라서 답해 주셔도 됩니다. (예: "Q1 A, Q7 2번, 나머지 추천대로") ## 해주셔야 하는 일 diff --git a/docs/12-decisions.md b/docs/12-decisions.md new file mode 100644 index 0000000..f187534 --- /dev/null +++ b/docs/12-decisions.md @@ -0,0 +1,102 @@ +# 12. 확정 사항 (2026-10-18 사용자 답변) + +11-questions.md 질문에 대한 사용자 답변과, 답변을 구현으로 옮길 때의 해석을 적는다. 다른 문서와 다르면 **이 문서가 우선**이다. +답이 없던 항목(Q9, Q11~Q19)은 추천안(★)으로 진행한다. + +## 한눈에 +| # | 결정 | 영향 문서 | +|---|---|---| +| Q1 | **B안: 숨긴 유튜브 플레이어(IFrame)** 로 재생. 대신 모두 같은 순간에 듣고, 버퍼링으로 한 명이 못 듣는 일이 없게 한다 | 08 | +| Q2 | 정답인식 켜짐 = 그 요소까지 정확히 쳐야 정답. **기본값: 띄어쓰기·숫자·특수문자 모두 켬** | 04, 05 | +| Q3 | 힌트공개에 **직접선택** 추가(60초 뒤). 직접선택이면 **힌트인원** 설정이 생기고 투표로 공개 | 04, 05 | +| Q4 | **다시듣기 투표**(모두 같이 다시 듣기), 단축키 **Ctrl+R**, 설정에 **다시듣기인원** | 04, 05, 06 | +| Q5 | 먼저 맞힌 1명만 +1 | 05 | +| Q6 | 재생위치 기본값: 처음부터 | 04 | +| Q7 | 별 N개 = **N단계 곡만**. 한 곡이 장르·연도에 따라 여러 단계를 가질 수 있음 | 04, 07 | +| Q8 | 문제 수 추가. 최대는 **무제한(조건에 맞는 곡 수)**. 끝나면 **이어풀기**, 퀴즈 **저장·불러오기** | 04, 05 | +| Q9 | 알아서 → 추천안(같은 묶음 "또는", 다른 묶음 "그리고") | 04 | +| Q10 | 기본 정답방식은 제목만, 방 설정이 제목+가수면 그대로 | 04 | +| 채팅 | 도배 방지 **기본 꺼짐**(관리자가 켬). 채팅은 무조건 실시간. 정답 줄과 5줄 블록 사이에 다른 말이 끼지 않게 | 06 | +| 쿠키 | 유튜브 뮤직 검색은 사용자가 준 `ytm_cookie.txt` 사용 (music_bot_v2 쿠키와 분리) | 08, 09 | +| .9 용량 | 부족하면 필요 없거나 오래된 캐시 파일 삭제(작업 중인 것 제외) | 09 | + +## Q1. 재생: 숨긴 IFrame + 동기화 +사용자 요구: "클라이언트가 부담하는 대신 다른 사람들과 실시간 동기화, 버퍼링 때문에 한 명이 노래를 못 듣는 경우가 없게" + +- **시계 맞추기**: 접속 직후와 30초마다 ping 5회로 서버 시각 차이(`offset`)를 잰다(왕복 시간 가장 짧은 값 사용) +- **준비 단계(문제마다)**: 서버가 `prepare{videoId, startSec}` 를 보냄 → 클라이언트는 숨긴 플레이어에 곡을 **음소거로** 불러 `startSec`로 옮긴 뒤 실제로 재생이 시작되면(광고가 있으면 광고가 끝난 뒤) 멈추고 `audioReady` 보고 + - 모두 준비되면 서버가 `play{startAt}`(서버 시각, 지금+600ms)을 보냄 → 모두 같은 순간에 음소거 풀고 재생 + - 준비 대기는 최대 15초. 그때까지 안 된 사람은 화면에 "음원 준비 중"으로 표시하고, 준비되는 즉시 지금 위치로 건너뛰어 합류 +- **재생 중 버퍼링**: 클라이언트가 0.5초 넘게 버퍼링하면 `stall` 보고 → 서버가 **모두 일시정지** → 그 사람이 다시 준비되면 새 `play{startAt, atSec}`로 모두 같은 위치에서 재개 + - 한 문제에서 이렇게 멈출 수 있는 총 시간은 10초(관리자 설정). 넘으면 그 사람만 따라잡기 방식으로 바뀌고 다른 사람은 멈추지 않음 +- **오차 보정**: 1초마다 `getCurrentTime()`과 기대 위치를 비교해 0.3초 넘게 어긋나면 그 위치로 이동 +- **재생 길이**: 1초~1분은 서버가 정한 시각에 각자 멈춤(시계 보정 기준). 서버도 같은 시각을 기준으로 진행 +- **정답 노출 줄이기**: 플레이어는 화면 밖에 숨기고 제목 표시 없음. 영상 ID는 준비 단계에서만 보내고 방 상태에는 넣지 않는다. (개발자도구로 보는 것까지는 막을 수 없음 — 사용자가 감수하기로 함) +- **퍼가기 금지 영상**: 노래 DB 매칭 때 oEmbed로 퍼가기 가능 여부를 확인해 안 되는 영상은 쓰지 않는다(07·08). 재생 중 오류 코드 101/150이 오면 그 곡은 건너뛰고 관리자 "재생 불가"로 표시 +- 서버 음원 캐시(A안)는 만들지 않는다 → yt-dlp·ffmpeg·음원 캐시 디스크 상한 항목은 하이라이트 분석용 일회성 처리 외에는 없음 + +## Q2. 정답인식 기본값 +- 켜짐 = 그 요소까지 똑같이 쳐야 정답, 꺼짐 = 무시하고 비교 +- 새 방 기본값: **띄어쓰기 켬, 숫자 켬, 특수문자 켬**(가장 엄격). 대소문자는 항상 무시 +- 엄격 모드라도 관리자 별칭으로 흔한 표기 차이(`광` / `광 (狂)`, 괄호 속 영어 제목 등)는 흡수한다 — 정답 후보 만들기 규칙(05)은 그대로 + +## Q3. 힌트 +- 힌트공개 선택지: 없음 / 15초 / 30초 / 45초 / 60초 / **직접선택** +- **직접선택**일 때만 방 설정에 **힌트인원(이상)** 이 보인다. 선택지는 스킵인원과 같음(1명, 2명, 1/3, 1/2, 2/3, 전체), 기본 1/3 +- 게임 화면 아래 투표 줄: `스킵 1/3` 옆에 `힌트 0/3` 을 같이 표시(직접선택일 때만) +- 힌트 버튼·Ctrl+I 동작 + - 직접선택: 내 힌트 표 토글, 기준을 넘으면 모두에게 공개 + - 없음: 누르면 "이 방은 힌트가 꺼져 있어요" 안내(버튼은 흐리게) + - 15~60초: 누르면 "힌트는 N초 뒤에 공개돼요"(남은 초), 공개된 뒤면 "이미 공개된 힌트예요" + +## Q4. 다시듣기 투표 +- 듣기 모드(듣고맞추기·가수노래)에서 문제 진행 중 **다시듣기 표**를 모아 기준을 넘으면 **모두 같이** 같은 구간을 처음부터 다시 듣는다(동기화 방식 그대로) +- 단축키 **Ctrl+R**(게임 화면에서는 새로고침 대신 다시듣기, `preventDefault`), 버튼 `다시듣기 (Ctrl+R)` +- 방 설정 **다시듣기인원(이상)**: 없음 / 1명 / 2명 / 1/3 / 1/2 / 2/3 / 전체, 기본 1/3 +- 다시 들으면 표는 초기화되고, 또 모으면 또 들을 수 있다(문제당 횟수 제한 없음) +- 짧은 클립(1초~1분)이면 문제 제한 시간을 다시 들은 시각부터 다시 센다. "끝까지"면 다시 들은 시각 + 곡 길이까지 +- 투표 줄 표시: `스킵 1/3 · 힌트 0/3 · 다시듣기 2/3` +- 가사보고 모드에서는 다시듣기 없음(버튼 숨김) + +## Q7. 난이도 N단계만 + 단계 중복 +- 별 N개 = 정확히 N단계 곡만 출제 +- 한 곡이 여러 단계를 가질 수 있다. 예) 어떤 발라드가 전체 기준으로는 5단계지만 발라드 안에서는 2단계, 90년대 곡 안에서는 3단계 +- 저장: `song_levels(song_id, scope, level)` — `scope` 는 `all`(전체), `genre:<장르ID>`, `decade:<1990>` 처럼 기준을 적는다 +- 출제 판정: 방에서 고른 장르·연도에 해당하는 기준(`all` + 고른 장르들 + 고른 연도 범위가 걸치는 10년 단위) 중 **어느 하나라도 단계가 N이면** 출제 후보 + - 그래서 같은 곡이 3단계 방에도, 5단계 방에도 나올 수 있다(사용자 설명대로 "단계가 중복되는 노래") +- 관리자 노래 편집에서 기준별 단계를 보고 고칠 수 있게 한다. 자동 계산은 `all` 먼저, 곡이 충분히 쌓인 장르·연대부터 기준별로 계산 +- (해석이 다르면 알려 주세요 — 예: "단계를 범위로 저장" 등) + +## Q8. 문제 수 · 이어풀기 · 저장/불러오기 +- 문제 수 선택지: 10 / 20 / 30 / 50 / 100 / **무제한(N곡)** — N은 지금 조건에 맞는 곡 수를 실시간 표시. 기본 30 + - 무제한 = 조건에 맞는 곡을 다 낼 때까지(또는 방장이 끝낼 때까지) +- **이어풀기**(결과 화면 버튼, 방장): 같은 설정으로 바로 이어서 시작, **이번 퀴즈에서 나온 곡은 모두 빼고** 출제. 점수는 이어서 쌓인다. (`다시 하기`는 점수 0부터, 나온 곡 제외 없음) + - 남은 곡이 없으면 "조건에 맞는 곡을 모두 풀었어요" +- **저장**: 방장이 대기실·결과 화면(또는 게임 중 일시정지)에서 `퀴즈 저장` → 이름을 붙여 방장 계정에 저장. 저장 내용: 방 설정, 지금까지 나온 곡 목록, 참가자별 점수(계정 기준), 진행 문제 수 + - 디스코드 로그인 사용자만 저장 가능(게스트는 안내), 계정당 최대 20개, 오래된 것부터 지우지는 않고 직접 삭제 +- **불러오기**: 대기실에서 방장이 `퀴즈 불러오기` → 목록에서 선택 → 설정·나온 곡 목록·점수가 복원되고, 시작하면 나온 곡을 빼고 이어서 출제. 그 방에 다시 들어온 참가자는 저장된 점수를 이어받는다 + +## Q10. 가수노래 맞추기 정답방식 +- 새 방 기본은 "제목만". 방장이 정답방식을 "제목+가수"로 해 두면 가수노래 모드에서도 그대로 제목+가수 + +## 채팅 (사용자 추가 요구) +- **도배 방지 기본 꺼짐**. 관리자 사이트 설정에 `채팅 도배 방지` 켜기/끄기와 수치(초당 횟수, 순간 횟수)를 둔다 +- **무조건 실시간**: 서버는 채팅을 받는 즉시 정답 판정과 중계를 한 번에 처리한다(대기열·묶음 전송·지연 없음). 묶어서 보내는 건 "입력 중" 표시뿐 +- **정답 블록이 끊기지 않게** + - 정답이면 서버는 `chat`을 따로 보내지 않고 **정답 줄 + 공백 5줄 블록을 한 덩어리 메시지(`answer`)** 로 보낸다 → 그 사이에 다른 메시지가 들어갈 자리가 없음 + - 모든 채팅·정답 메시지에 방 단위 순번(`seq`)을 붙이고, 화면은 순번대로 그린다 + - 내가 보낸 말은 바로 화면에 보이되(지연 0) **확정 전에는 항상 맨 아래 "보내는 중" 자리**에 둔다. 서버 확인이 오면 순번 자리에 들어간다 → 정답이 내 말보다 먼저 서버에 도착했으면 내 말은 블록 아래로 간다 + - 결과: 공백 블록 바로 위 줄이 항상 정답 줄 + +## 유튜브 뮤직 쿠키 +- 사용자가 준 `ytm_cookie.txt` 를 호스트 비밀 위치 `/home/claude/.config/music_quiz/ytm_cookie.txt`(권한 600)에 보관. 리포에는 넣지 않는다 +- 쓰는 곳: 노래 수집기의 YT Music 노래 검색(music_bot_v2 방식 `SAPISIDHASH`), 관리자 "곡 추가" 자동 채우기. 컨테이너에는 읽기 전용으로 연결(`YT_COOKIE_PATH`) +- music_bot_v2 쿠키와는 분리해서 쓴다 → 차단돼도 봇에는 영향 없음 +- 쿠키 만료(로그인 필요 응답) 감지 시 관리자 대시보드에 "쿠키 갱신 필요" 표시 + +## .9 용량 +- 이미 있는 것: `docker-disk-guard.sh`(남은 공간 50GB 미만이면 도커 빌드 캐시·이름 없는 이미지 삭제), `disk85-alert.sh`(85% 이상 알림) +- 추가: `disk-low-cleanup.sh` — 남은 공간이 50GB 미만일 때 다시 받으면 되는 **캐시만** 지운다 + - 지움: pip·uv·npm·bun 설치 캐시, `~/.tmp` 의 3일 지난 파일, 도커 빌드 캐시 + - 안 지움: 모델(huggingface 등), 브라우저(playwright), 프로젝트 폴더, DB·백업, 실행 중인 설치 작업이 있으면 그 캐시 +- Q1이 B안이라 음원 캐시가 없어 이 프로젝트가 쓰는 디스크는 DB 정도(수백 MB)