Files
music_quiz/docs/02-auth-admin.md

7.3 KiB

02. 로그인 · 권한 · 관리자 페이지

로그인 (joke-app과 동일)

디스코드 OAuth2

  • 시작: GET /api/auth/discord/start?next=/r/123456
    • state 24바이트 난수 → HMAC 서명 쿠키 oauth(10분, path=/api/auth/discord)
    • https://discord.com/oauth2/authorize?client_id=1561284577564037140&response_type=code&redirect_uri=https://mquiz.tkrmagid.kr/api/auth/discord/callback&scope=identify&state=...&prompt=none
  • 콜백: GET /api/auth/discord/callback → state 검증 → 토큰 교환 → /users/@me 조회
    • 이미 연결된 계정이면 로그인(게스트 기록은 병합), 게스트 상태면 디스코드 연결 후 회원 전환, 처음이면 회원 생성(닉네임 = global_name ?? username, 12자 제한)
    • 디스코드 토큰은 저장하지 않는다. scope는 identify만
  • 디스코드 개발자 포털에 등록해야 할 Redirect URI: https://mquiz.tkrmagid.kr/api/auth/discord/callback (로컬 테스트용으로 http://localhost:5173/api/auth/discord/callback도 추가 권장)
  • 클라이언트 ID/시크릿은 deploy/.env(권한 600)에만 넣고 리포에는 절대 커밋하지 않는다. 호스트 비밀 저장소(secrets.json의 discord.com/oauth/music_quiz)에 보관해 두었다.
  • 클라이언트 자격으로 토큰 발급 테스트 완료 → ID·시크릿 정상, 앱 이름 "음악퀴즈", 앱 아이콘은 아직 비어 있음(포털에서 assets/brand/icon-discord-1024.png 업로드 필요)

게스트

  • POST /api/auth/guest {nickname} (IP당 분당 20회)
  • 닉네임 2~12자, 한글/영문/숫자/_-. , 비속어 필터
  • 로그아웃하면 게스트 계정 삭제, 하루 미사용 게스트 자동 정리
  • 게스트도 게임은 모두 가능, 관리자는 될 수 없음

세션

  • sid httpOnly 쿠키(SameSite=Lax, https면 Secure), DB에는 sha256(token)만
  • 회원 90일 / 게스트 365일, 하루 한 번 연장
  • /api/* 쓰기 요청은 Origin 검사로 CSRF 방지

권한

역할 정하는 방법 할 수 있는 것
superadmin 환경변수 SUPERADMIN_DISCORD_IDS (joke-app과 같은 값: 293719842274541579,1352267557213573160) 전부 + 사용자 관리 + 관리자 추가/삭제
admin admins 표에 디스코드 ID 등록(로그인 전에도 미리 등록 가능) 노래·수집·방·사이트 설정
user 나머지 게임
  • 요청마다 다시 계산(디스코드 연결 ID 기준). 환경변수로 정한 슈퍼어드민은 관리자 목록에 "고정"으로 보이고 삭제 불가
  • 모든 관리자 변경은 admin_audit에 변경 전/후 JSON으로 기록

관리자 페이지 /admin

joke-app 관리자와 같은 레이아웃(왼쪽 사이드 메뉴 + 오른쪽 내용, 표는 .data-table)을 쓴다.

메뉴 내용 권한
대시보드 접속자 수, 진행 중 방, 전체 곡 수, 유튜브 매칭률, 가사 보유율, 최근 수집 작업, 오늘 플레이 수 admin
노래 곡 목록 표 + 상세 편집 (아래) admin
원곡 찾기 유튜브 원곡 찾기 결과 확인·수정 (아래) admin
가수 가수 별칭(아이유 = IU = 이지은), 그룹/유닛 연결, 대표 이미지 admin
장르 장르 목록 추가·이름 변경·순서·숨김 admin
수집 출처별 수집 실행(멜론 연도별 등), 진행률·로그, 자동 실행 주기, 유튜브 매칭/하이라이트 분석 일괄 실행 admin
통계 곡별 출제 수·정답률·평균 정답 시간 → 난이도 조정 제안(승인 버튼) admin
방 진행 중 방 목록, 참가자, 강제 종료 admin
사이트 사이트 이름, 공지, 점검 모드, 금칙어, 기본 방 설정, 라운드 시간 기본값, 채팅 도배 방지, 음원 캐시 상한 admin
사용자 검색, 닉네임 변경, 정지, 강제 로그아웃, 삭제 superadmin
관리자 디스코드 ID로 추가/삭제 superadmin
기록 감사 로그(누가 언제 무엇을) admin

노래 관리 화면

  • 검색: 제목·가수·별칭 통합 검색(초성 검색 지원: "ㅅㄱㅇㅈㅍㅅ" → 사건의 지평선)
  • 필터: 장르(복수), 연도 범위, 난이도 범위, 유튜브 상태(매칭됨/후보 있음/없음/재생 불가), 가사 유무, 하이라이트 유무, 출처(멜론·지니·벅스·스타맵·노라보세 등), 활성/숨김
  • 정렬: 최근 추가, 인기도 점수, 난이도, 연도, 정답률
  • 표 열: 앨범아트 · 제목 · 가수 · 연도 · 장르 · 난이도(별) · 유튜브(▶ 미리듣기) · 하이라이트 · 가사 · 출처 수 · 정답률
  • 상세 편집(오른쪽 패널): 제목, 가수, 정답 별칭(여러 개), 연도, 장르(복수), 난이도(자동값 + 수동 고정), 유튜브 주소(https://youtu.be/ID) + 후보 목록에서 고르기 + 미리듣기, 하이라이트 시작점(미리듣기 중 "지금 위치로 지정"), 가사, 메모, 숨김
  • 추가: 제목+가수만 넣으면 자동으로 멜론 정보·유튜브 후보 채움 → 확인 후 저장
  • 일괄 작업: 선택 곡 장르/난이도 변경, 유튜브 재매칭, 숨김, 삭제(휴지통 30일 보관)
  • 가져오기/내보내기: JSON·CSV
  • 중복 정리: 제목·가수 정규화가 같은 곡 묶어서 보여주고 병합

원곡 찾기 화면 (2026-10-19)

  • 진행 상황: 지금(또는 마지막) 원곡 찾기 작업의 상태 배지(찾는 중 · 검색 실패로 잠깐 쉬는 중 · N분째 진행 없음(3분 넘게 처리한 곡이 없을 때) · 멈춘 것 같아요(작업 기록은 running인데 프로세스가 없을 때) · 끝남/멈춤/실패와 이유), 진행률, 숫자 카드(처리 N/M·남은 곡·속도(최근 10분 곡/분, 1곡에 몇 초)·지난 시간·남은 시간·끝 예상·마지막 처리), 검색 방법(유튜브 뮤직/쿠키 없는 유튜브 검색), 이번 작업 결과(확정·후보·못 찾음 수와 비율 막대), 방금 처리한 곡 8개(누르면 오른쪽 패널), 작업 기록(최근 12줄, 쉬운 말로), 지난 작업 5개, 전체 곡 중 확정 비율·아직 안 찾은 곡·다음 자동 실행 시각
    • 끝 예상은 최근 10분 속도로 계산한다(초반 느림·60초 재시도 대기가 오래 남지 않게). --deadline으로 돌린 작업은 시작 로그(start N songs via … deadline <ISO>)에서 마감을 읽어, 끝 예상이 마감보다 늦으면 "마감에 멈춰요"와 그때까지 찾을 곡 수를 보여 준다.
  • 탭: 확정 · 후보 · 못 찾음(찾아봤지만 없음, 7일 뒤 자동 재시도) · 원곡 없음(관리자 표시, 자동 찾기 제외) · 재생 불가 · 아직 안 찾음(자동 찾기 순서대로). 방금 처리된 곡이 맨 위
  • 자동 새로고침: 5초마다, 화면을 보고 있을 때만. 마우스가 목록 위에 있으면 줄이 밀리지 않게 잠깐 멈춤
  • 바로 고치기: 후보 줄의 [확정], 오른쪽 패널에서 미리듣기 · 다른 후보로 확정 · 주소 붙여넣기 · 확정 취소(→ 관리자 후보, 게임에서 빠지고 자동 찾기가 다시 확정하지 않음) · 원곡 없음으로 표시 · 다시 찾기. 처리한 곡이 탭에서 빠지면 다음 곡으로 넘어감
  • 저장은 노래 편집과 같은 경로(DB 바로 반영, 새 게임·다음 문제부터 적용), 모두 기록(감사 로그)에 남음. 제목·가수 수정은 패널의 "전체 편집"