minecraft_launcher/docs/admin-site.md

# 관리 사이트 운영 가이드

음악퀴즈 정의(`/manifest/*.json`), 음악·사진 목록(`/file/list/*.json`), 데이터팩 출력을 한 곳에서 관리하는 Express + EJS 사이트입니다.

## 실행

```bash
npm install
cp .env.example .env   # 처음 한 번만. 운영 도메인이면 SITE_BASE_URL 만 바꾸면 됩니다.
npm start              # 기본 포트 3000.
```

배포 시에는 시스템 서비스(systemd 등) 로 등록해 두면 됩니다.

### 환경변수 (`.env`)

| 키 | 기본값 | 설명 |
| --- | --- | --- |
| `PORT` | `3000` | Express 서버 listen 포트. |
| `HOST` | `127.0.0.1` | 바인드 주소. 외부 노출하려면 `0.0.0.0`. |
| `SESSION_SECRET` | dev secret | `/op` 세션 쿠키 서명 키. 운영에서는 반드시 임의값으로 교체. |
| `SITE_BASE_URL` | `http://127.0.0.1:3000` | 설치기 두 종이 첫 화면에서 자동으로 채우는 manifest 호스트. 운영 도메인으로 바꿔두면 manifest URL 도 자동으로 따라갑니다. |
| `MANIFEST_URL` | — | 특별히 다른 경로를 쓰고 싶을 때만 지정. 비우면 `${SITE_BASE_URL}/manifest.json`. |
| `MUSIC_CONCURRENCY` | (자동) | 리소스팩 설치기 yt-dlp 동시 다운로드 수(1~8). |

`.env` 는 `.gitignore` 로 제외되어 있습니다. 새 환경을 셋업할 때 `.env.example` 을 복사해서 시작하세요. 쉘에서 직접 환경변수를 지정한 경우에는 `.env` 값을 덮어쓰지 않습니다.

#### 설치기 `.exe` 빌드에도 적용됨

`npm run dist:win` 으로 만든 설치기 `.exe` 도 빌드 시점의 `.env` 를 함께 가져갑니다 (`electron-builder` 의 `extraResources` 로 `resources/.env` 에 배포). 런타임에서는 `process.resourcesPath/.env` → `<프로젝트 루트>/.env` 순으로 찾기 때문에:

- 운영자가 `SITE_BASE_URL=https://mq.example.com` 으로 `.env` 를 설정해 두고 빌드 → 최종 사용자가 받은 `.exe` 가 그 도메인의 `manifest.json` 을 자동으로 받아옴.
- 빌드 이후라도 설치된 폴더(`resources/.env`) 를 텍스트 편집기로 고치면 도메인을 바꿀 수 있음.
- 빌드 시점에 `.env` 가 없으면 단순히 빠진 채로 패키징되고, 코드 기본값(`http://127.0.0.1:3000`) 이 그대로 사용됩니다.

## 도메인 / 경로 구성

| 경로 | 내용 |
| --- | --- |
| `/` | 음악퀴즈 카드 한 줄 목록(공개). 카드 클릭 시 해당 음악퀴즈 페이지. |
| `/manifest.json` | 사이트 루트 매니페스트(공개). 설치기가 첫 화면에서 로드. |
| `/file/...` | 정적 파일 호스팅. `servers/`, `maps/`, `mods/<폴더>/`, `resourcepacks/`, `platforms/`, `list/`. |
| `/op` | 관리자 로그인. 미들웨어로 `/op/*` 전체를 보호. |
| `/op/dashboard` | 음악퀴즈 카드 목록 + 추가/삭제 + 편집 진입. |
| `/op/dashboard/:packKey` | 음악퀴즈 정의(JSON) 편집기. |
| `/op/list` | 카드 목록(음악·사진 편집 진입). |
| `/op/list/:packKey` | 음악퀴즈의 음악·사진 목록 편집(드래그/우클릭). |
| `/op/datapack` | 데이터팩 mcfunction 출력. |
| `/op/datapack/:packKey/generate` | 텍스트 한 덩어리로 mcfunction 반환. |

## 계정

`account.json` 에 정의합니다(루트 디렉터리). **외부 HTTP 로 절대 노출되지 않도록 라우팅에서 제외돼 있습니다.**

```json
[
  { "id": "admin", "password": "비번" }
]
```

> 운영 환경에서는 평문 비밀번호 대신 해시를 쓰도록 추후 보강할 여지가 있습니다.

## 대시보드 (`/op/dashboard`)

- 상단 메뉴: 좌측 로고 = 대시보드로 이동, 우측 아이디 드롭다운에 **로그아웃**.
- 상단 버튼: `[음악목록 수정]` → `/op/list`, `[데이터팩 수정]` → `/op/datapack`.
- 카드 목록: `manifest.json` 의 음악퀴즈를 가로 한 줄 카드로 표시.
- **음악퀴즈 추가** — `/manifest/new.json` 생성. 이미 있으면 `new2.json`, `new3.json` … 으로 증가. 동시에 `manifest.json` 갱신.
- **음악퀴즈 삭제** — 카드에 체크박스가 뜨고, 확인 시 선택한 JSON 과 매니페스트 항목을 삭제.

## 음악퀴즈 정의 편집 (`/op/dashboard/:packKey`)

폼 필드:

| 필드 | 설명 |
| --- | --- |
| 음악퀴즈 이름 | 사용자에게 보이는 표시명. |
| JSON 파일 이름 | URL 키. 영문/숫자/`_`/`-` 만 허용. 변경 시 파일명 + 매니페스트가 동시에 갱신되며 URL 도 새 키로 리다이렉트. |
| 마인크래프트 버전 | Mojang 공식 API 에서 정식 릴리즈만 드롭다운으로 표시. |
| 모드 플랫폼 | `vanilla` / `forge` / `fabric` / `neoforge`. |
| 플랫폼 설치파일 URL | `forge` / `neoforge` 용. 도메인 없이 입력하면 `/file/platforms/<파일명>` 으로 해석. |
| Fabric Loader 버전 | `fabric` 선택 시 자동 표시. Fabric Meta API 에서 선택한 mcVersion 의 로더 목록을 가져옴. 설치기는 최신 fabric-installer 로 CLI 자동 설치. |
| 서버 최소/최대 램 (MB) | 설치기 RAM 검사 및 `run.bat` 의 `-Xms/-Xmx`. |
| 클라이언트 최소/권장 램 (MB) | 사용자 PC 요구치 + 마인크래프트 런처 JVM 인수에 사용. |
| 맵 파일 (.zip) | `/file/maps/` 아래 zip 파일명. `.mc_custom/saves/` 로 압축 해제. |
| 서버 파일 (.zip) | `/file/servers/` 아래 zip. 멀티 전용. |
| 모드 폴더 이름 | `/file/mods/<폴더>/` 아래 모든 `.jar` 자동 다운로드. 빈 값이면 받지 않음. |
| 리소스팩 (.zip) | `/file/resourcepacks/` 아래 zip 파일명. |

저장 시 `clientMinRam ≤ clientRecommendedRam` 검증이 들어갑니다.

## 음악·사진 목록 편집 (`/op/list/:packKey`)

상단 탭: **음악목록** / **사진목록**.

### 음악목록 탭

- `[목록 저장]`, `[목록 초기화]`.
- 플레이리스트 주소 + `[플레이리스트 불러오기]`. 확인 팝업에서 동의해야 기존 순서를 덮어씀.
- 항목 표시: 좌측 번호 배지, 썸네일, 제목 / 가수 / 길이.
- 드래그로 순서 변경. 우클릭: **수정** / **삭제**.
- **수정** → 새 유튜브 주소를 입력하면 yt-dlp 가 메타데이터를 가져와 자동 채움.

### 사진목록 탭

- `[목록 저장]`, `[목록 초기화]`, 플레이리스트 불러오기는 동일.
- 카드 그리드(반응형) 로 표시. 우클릭에서 수정/삭제. 수정 팝업은 [유튜브 주소] / [이미지 주소] 토글.

저장 포맷은 `/file/list/<packKey>.json` (README 데이터 포맷 참고).

> yt-dlp 메타데이터/플레이리스트 조회를 위해 서버에 yt-dlp 가 설치되어 있어야 합니다. ([`yt-dlp-setup.md`](yt-dlp-setup.md))

## 데이터팩 (`/op/datapack`)

- `[음악퀴즈 선택]` → 팝업에서 음악퀴즈 선택.
- "총 N개의 음악을 찾았습니다." 와 `[데이터팩 출력]` 버튼.
- 출력 클릭 시 코드 영역에 mcfunction(임시 포맷) + 복사 버튼. 실제 포맷은 추후 확정.

```
# === musicquiz: <pack name> ===
# 총 N곡 / 사진 M장
say [musicquiz] 데이터팩 초기화
# 곡별 placeholder. 실제 포맷 확정되면 교체 예정.
# 1. <title> - <artist> (<duration>s)
```

## 파일 업로드 / 정리 운영

| 카테고리 | 위치 | 비고 |
| --- | --- | --- |
| 서버 zip | `file/servers/<이름>.zip` | EULA / `run.bat` 포함 권장. 설치기가 `run.bat` 에 UPnP/JVM 후처리 자동 주입. |
| 맵 zip | `file/maps/<이름>.zip` | 압축 해제 시 `.mc_custom/saves/` 아래에 풀림. |
| 모드 jar | `file/mods/<폴더>/...jar` | 해당 폴더의 `index.json` 이 자동 생성됩니다. 신규 jar 를 넣은 뒤에는 사이트가 인덱스를 다시 만들도록 한 번 호출. |
| 리소스팩 zip | `file/resourcepacks/<이름>.zip` | — |
| 플랫폼 설치 jar | `file/platforms/<이름>.jar` | forge/neoforge 용. fabric 은 사이트에 둘 필요 없음(자동 다운로드). |

## 보안 주의

- `account.json` 은 라우팅에서 차단되어 있으나, 디스크 권한도 운영자만 접근 가능하게 두는 것이 안전합니다.
- 관리자 비밀번호는 충분히 강하게 설정.
- 모든 `/op/*` 라우트는 세션 기반 인증 미들웨어를 거칩니다. 세션 만료 시 자동으로 로그인 페이지로 리다이렉트.