ITOSMPiano-BachToBasics/docs/LIBRARY-AUTH-KO.md

Bach to Basics 회원과 곡 보관함 운영

기능 범위

Bach to Basics의 기존 파일 가져오기 기능을 유지하면서 서버 곡 보관함을 추가했다. 비회원은 전체 공개 곡과 악보를 바로 연주할 수 있다. 회원은 MIDI와 악보를 올리고 공개 범위와 회원 등급을 지정할 수 있다.

공개 범위는 다음 네 단계다.

공개 범위	접근 대상
전체 공개	비회원 포함 모든 사용자
회원 공개	지정한 최소 등급 이상의 로그인 회원
지정 회원 공유	최소 등급을 만족하며 업로더가 지정한 회원
나만 보기	업로더 본인과 관리자

회원 등급은 일반 회원 1단계와 우수 회원 2단계 및 지도 회원 3단계와 관리자 4단계로 구성한다. 역할은 회원과 운영자 및 관리자로 구분한다. 등급은 곡 접근 범위에 사용하며 역할은 운영 권한에 사용한다.

회원 기능

• 회원 가입과 로그인 및 로그아웃
• 현재 비밀번호를 확인한 뒤 비밀번호 변경
• 모든 세션을 종료한 뒤 새 비밀번호로 다시 로그인
• 비밀번호와 확인 문구를 입력한 회원 탈퇴
• 탈퇴 시 본인이 올린 MIDI와 공유 정보 제거
• 관리자 화면에서 회원 등급과 역할 및 이용 상태 변경

비밀번호는 scrypt로 해시한다. 원문은 DB와 로그에 저장하지 않는다. 로그인 세션 토큰도 SHA-256 해시만 DB에 보관한다. 상태 변경 요청에는 로그인 세션과 CSRF 확인 값을 함께 검사한다.

화면 진입

학습 화면 상단에 계정 상태에 맞는 메뉴를 표시한다.

• 곡 보관함: 공개 샘플과 접근 가능한 회원 곡을 검색하고 연주한다.
• 로그인·회원가입: 비회원에게 표시한다. 창 안에서 로그인과 회원 가입을 전환한다.
• 내 계정: 로그인한 회원에게 표시한다. 비밀번호 변경과 회원 탈퇴를 관리한다.
• 관리자 패널: 관리자 권한으로 로그인했을 때만 표시한다. 회원 등급과 역할 및 이용 상태를 관리하는 화면으로 바로 이동한다.

390픽셀 모바일 화면에서는 첫 줄에 회원 메뉴를 배치하고 둘째 줄에 화면 전환 메뉴와 MIDI 장치를 배치한다. 이전 서비스 워커가 로그인과 관리자 메뉴의 오래된 화면을 계속 제공하는 문제가 있어 오프라인 캐시를 해제했다. 설치형 바로가기는 유지하며 온라인 접속 때는 항상 최신 HTML과 해시 자산을 사용한다.

연주 시작과 음표 표시

곡을 맨 처음부터 재생하면 시계를 3초 전부터 움직인다. 이 준비 시간 동안 첫 음표가 건반 쪽으로 내려오며 화면 가운데에 3부터 1까지 남은 시간을 표시한다. 실제 MIDI 음은 원래 시작 시각인 0초부터 재생하므로 첫 음을 놓치지 않고 준비할 수 있다. 중간 위치에서 다시 재생할 때는 준비 시간을 반복하지 않는다.

화면 건반을 누를 때와 MIDI 파일을 재생할 때는 같은 피아노 샘플 엔진과 현재 선택한 악기를 사용한다. 검은 건반에 대응하는 내려오는 음표는 손 구분 색상을 유지하되 흰 건반 음표보다 명도를 낮춰 구분한다.

곡과 악보 업로드

• 허용 확장자: .mid, .midi, .xml, .musicxml, .mxl, .pdf
• 최대 파일 크기: 25MB
• 회원별 최대 파일 수: 100개
• 회원별 최대 보관 용량: 500MB
• 파일 이름에서 디렉터리 요소 제거
• MIDI는 MThd 헤더 확인
• MusicXML은 안전한 XML 파서로 루트 악보 구조 확인
• MXL은 압축 경로와 내부 파일 수 및 해제 용량과 주 악보 구조 확인
• PDF는 파일 서명 확인
• 임의 저장 이름과 SHA-256 해시 기록
• 곡 제목과 아티스트 및 설명
• 난이도와 장르 및 편곡 형태
• 최대 12개 검색 태그
• 전체 공개 곡은 등급 제한 사용 불가

저장 위치는 /home/syskiller/piano/bach-to-basics/data다. SQLite DB와 MIDI 파일은 Git에 넣지 않는다. DB 파일 권한은 600이며 데이터 디렉터리는 750으로 유지한다.

검색과 버전 묶음

곡명과 아티스트 및 설명과 태그를 함께 검색한다. 장르와 난이도 및 편곡 형태와 개별 태그로 결과를 좁힐 수 있다. 같은 아티스트와 같은 제목은 한 묶음으로 표시한다. 묶음 안에서 멜로디와 반주 및 피아노 독주와 듀엣과 연습 패턴을 선택한다.

공개 샘플

Mutopia Project가 공개 도메인으로 배포하는 실제 클래식 MIDI를 전체 공개 샘플로 제공한다. 출처와 파일별 권리 표시는 THIRD_PARTY_SAMPLES.md에 기록한다.

• 미뉴에트 사장조 BWV Anh. 114: 입문 양손 편곡과 쉬운 양손 원곡
• 미뉴에트 내림마장조 WoO 82: 쉬운 양손 편곡과 중급 양손 원곡
• 엘리제를 위하여 WoO 59: 입문 양손과 쉬운 양손 및 고급 원곡

같은 제목의 난이도별 버전은 한 묶음에서 선택한다. 기본 단계별 연습곡은 모두 오른손과 왼손을 포함한 피아노 독주로 제공한다. 손별 연습은 연습 화면에서 선택한다. 공개 도메인 원곡에서 만든 단계별 연습 편곡은 scripts/build_sample_variants.mjs로 다시 만들 수 있다. 자체 제작한 약 1분 길이의 초보자용 MIDI 다섯 파일은 python backend/tools/generate_beginner_midis.py로 다시 만들 수 있다.

악보 표시

MIDI를 선택하면 서버에서 MusicXML로 변환한 뒤 AlphaTab으로 오선 악보를 표시한다. 배포 파일에는 다음 자산을 포함한다.

• Bravura SMuFL 악보 글꼴과 OFL 고지
• AlphaTab 전용 Worker와 AudioWorklet 및 코어 모듈
• .mjs 파일의 application/javascript MIME 설정

운영 환경에서는 악보 렌더링을 UI 스레드에서 처리한다. Vite 번들과 별도 Worker가 렌더링 자원을 서로 다르게 초기화해 빈 악보가 되던 문제를 피하기 위한 설정이다.

전체 화면의 가로 악보는 외부 재생 시계의 시간과 AlphaTab tick을 함께 사용해 커서를 갱신한다. 커서가 화면 너비의 약 40퍼센트 지점에 오면 악보가 부드럽게 따라간다. 확인한 AlphaTab 1.8.3을 고정해 내부 커서 경로가 예고 없이 바뀌지 않게 한다.

MIDI 변환 악보에서 C6 이상의 음이 한 마디에 두 개 이상 이어지면 8va를 적용한다. C2 이하의 연속 저음에는 8vb를 적용한다. C7 이상과 C1 이하는 한 음만 있어도 적용한다. 옥타브 기호는 표기 위치만 바꾸며 실제 재생 음높이는 유지한다.

초기 관리자

초기 관리자 아이디는 Compose 환경 변수로 지정한다. 비밀번호는 secrets/library_admin_password에서만 읽는다. DB에 같은 아이디가 없을 때만 최초 관리자를 생성한다. 컨테이너 재시작 때 기존 비밀번호를 덮어쓰지 않는다.

백업과 복구

다음 항목을 같은 시점에 백업한다.

• data/library.sqlite3
• data/midi
• secrets/library_admin_password
• 소스 저장소 Git 번들

비밀 파일은 일반 소스 백업과 분리하고 권한 600을 유지한다. SQLite를 복사하기 전에는 백엔드의 쓰기 요청을 잠시 막거나 SQLite 온라인 백업 명령을 사용한다. 단순 파일 복사 중 DB가 변경되면 일관된 백업이 아닐 수 있다.

운영 확인

배포 후 다음을 검사한다.

1. 비회원에게 공개 샘플만 표시되는지 확인한다.
2. 회원 가입과 로그인 및 로그아웃을 확인한다.
3. 비공개 곡이 다른 회원과 비회원에게 보이지 않는지 확인한다.
4. 회원 공개와 지정 공유 및 최소 등급 제한을 확인한다.
5. MIDI와 MusicXML과 MXL 및 PDF 업로드와 한글 제목 및 태그 검색을 확인한다.
6. 같은 제목의 입문과 쉬움 및 원곡 버전을 각각 불러온다. 모든 단계에서 오른손과 왼손 악보가 함께 표시되는지 확인한다.
7. 비밀번호 변경 후 기존 세션이 끝나는지 확인한다.
8. 시험 회원 탈퇴 후 계정과 업로드가 제거되는지 확인한다.
9. 모바일 화면에서 검색과 업로드 및 계정 화면이 가로로 넘치지 않는지 확인한다.
10. 전체 화면에서 50초 이상 이동한 뒤 악보 커서와 가로 스크롤이 진행 막대를 따라가는지 확인한다.
11. 고음과 저음이 많은 MIDI를 변환해 MusicXML에 8va와 8vb가 생성되는지 확인한다.