Add development spec to README

Spec covers the .exe installer (5 step pages), management site (Node + Express + EJS), pack JSON schema, and manifest.json layout. Implementation will follow this spec. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-09 21:23:30 +09:00
parent cd79378f3c
commit 42a7cf3426
1 changed files with 356 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,356 @@
-# Minecraft Server Pack Easy Installer
+# 마인크래프트 음악퀴즈 간편설치기 + 관리 사이트 개발 명세서
+
+## 프로젝트 개요
+
+마인크래프트 음악퀴즈를 `.exe` 하나로 간편하게 설치할 수 있는 설치기와, 음악퀴즈 정보를 관리하는 웹사이트를 개발한다.
+
+### 핵심 컨셉
+- 이 프로젝트는 `%appdata%\.mc_custom` 폴더를 생성하여 모드 적용 및 서버 실행을 독립적으로 관리한다.
+- 음악퀴즈 정보는 **`manifest.json`** 으로 중앙 관리한다.
+
+### .mc_custom 폴더 구조
+
+```
+%appdata%\.mc_custom\
+├── mods/          ← 모드 (.jar) 저장 및 자동 적용
+├── resourcepacks/ ← 리소스팩 (.zip) 저장 및 자동 적용
+├── saves/         ← 월드 저장
+├── config/        ← 모드 설정 파일
+├── screenshots/   ← 스크린샷
+└── options.txt    ← 게임 설정
+```
+
+- 마인크래프트 런처 프로필의 `gameDir`을 `%appdata%\.mc_custom`으로 설정하면, 마인크래프트가 이 폴더를 기준으로 모든 파일을 읽고 저장한다.
+- 버전 파일과 assets는 기존 `%appdata%\.minecraft`를 그대로 사용한다.
+
+---
+
+## 파트 1. 간편설치기 (`.exe`)
+
+> 설치기는 아래 단계를 순서대로 페이지 단위로 진행한다. 각 번호 = 1페이지.
+
+### 1단계: 음악퀴즈 선택
+
+- 음악퀴즈사이트(아래 파트 2 참고)에서 `manifest.json`을 가져와 등록된 음악퀴즈 목록을 표시한다.
+- 사용자가 설치할 음악퀴즈를 선택한다.
+
+---
+
+### 2단계: 싱글 / 멀티 선택
+
+- 싱글 또는 멀티 중 하나를 선택하는 화면을 표시한다.
+- **멀티 선택 시**: 3단계(서버 설치)를 거친 후 4단계로 진행한다.
+- **싱글 선택 시**: 3단계를 건너뛰고 4단계로 바로 진행한다.
+
+---
+
+### 3단계: 서버 관련 설정
+
+- 2단계에서 **멀티**를 선택한 경우에만 진입한다. 싱글 선택 시 이 단계 전체를 건너뛴다.
+- 3단계의 각 소항목(3-1 ~ 3-5)은 완료되어도 자동으로 다음으로 넘어가지 않으며, 사용자가 **확인 버튼**을 눌러야 다음 소항목으로 진행된다.
+
+#### 3-1. 서버 설치 경로 설정
+
+- 서버를 생성할 폴더 경로를 사용자가 직접 지정한다.
+- **경로에 한글이 포함되면 안 된다.** 한글 포함 시 경고 메시지를 표시하고 다음 단계로 진행 불가.
+
+#### 3-2. JDK 확인 / 설치
+
+- 폴더 선택 UI로 JDK 경로를 지정할 수 있다.
+- JDK 자동 탐색 우선순위:
+  1. 시스템 환경변수 (`JAVA_HOME` 등)
+  2. 로컬 환경변수
+  3. `C:\Program Files\Java` (JDK 기본 설치 경로)
+- 위 경로에서 JDK가 발견되면 해당 경로를 기본값으로 자동 설정한다.
+- JDK가 없으면 설치를 안내한다.
+
+#### 3-3. 서버 다운로드 및 설치
+- 처음 파일 다운로드는 자동으로 시작
+
+##### 3-3-1. 파일 다운로드
+- JSON의 `packPath` 필드 값을 `도메인/file/` 뒤에 붙여 서버 파일 다운로드 URL을 구성한다.
+  - 예: `packPath`가 `music-quiz/files`이면 → `도메인/file/music-quiz/files`
+  - 해당 경로의 모든 파일을 순서대로 다운로드한다.
+
+##### 3-3-2. 설치 로그
+- 다른 프로그램 설치 화면처럼 실시간 로그를 표시하는 로그 뷰어를 제공한다.
+
+##### 3-3-3. EULA 동의
+- 설치 중간에 Minecraft EULA 동의 화면을 표시하고, 사용자가 직접 동의해야 다음 단계로 진행된다.
+- 음악퀴즈 내에 `eula.txt`가 포함되어 있으면 **삭제하고** 새로 동의를 받는다.
+
+##### 3-3-4. 램 검사 로직
+
+> 아래 기준은 모두 JSON의 서버 램 필드(`serverMinRam`, `serverMaxRam`)를 사용한다.
+
+```
+유저 시스템 램 >= serverMaxRam   →   serverMaxRam으로 설정
+유저 시스템 램 >= serverMinRam   →   serverMinRam으로 설정 (경고 메시지 표시)
+유저 시스템 램 < serverMinRam    →   "플레이 불가" 메시지 출력 후 설치 중단
+```
+
+- 서버 실행 시 `-Xmx`에 `serverMaxRam`, `-Xms`에 `serverMinRam` 값을 JVM 인자로 사용한다.
+
+#### 3-4. 서버 설정
+
+- **로컬 웹서버**를 띄워 브라우저에서 서버 설정 파일을 GUI로 편집할 수 있게 한다.
+- 메모장으로 수정해야 했던 파일들을 설명과 함께 편리하게 수정 가능:
+  - `bukkit.yml`
+  - `server.properties`
+  - 기타 설정 파일
+- 수정 후 "적용" 버튼으로 실제 파일에 반영한다.
+
+#### 3-5. 서버 포트포워딩 설정
+
+1. **이미 포트포워딩 되어 있는 경우** (UPnP 포함): 외부 접속 주소를 화면에 표시하고 다음 단계로 진행.
+2. **포트포워딩 안 된 경우 → UPnP 시도**:
+   - UPnP로 포트 개방 가능 여부 확인
+   - 가능하면 자동으로 개방 후 외부 접속 테스트
+   - 접속 확인되면 다음 단계로 진행 가능
+3. **UPnP 불가 시**: "직접 포트포워딩을 해주세요." 메시지를 안내와 함께 표시.
+
+---
+
+### 4단계: 유저 클라이언트 설정
+- 음악퀴즈 JSON 파일에 명시된 클라이언트 설정을 기반으로 설치한다.
+
+#### 4-1. 모드 플랫폼 설치
+- JSON 파일의 `platform.type`에 명시된 플랫폼 이름을 화면에 표시하고, **설치** / **건너뛰기** 버튼으로 사용자가 직접 선택한다.
+  - `vanilla`가 아닌 경우: `platform.downloadUrl`을 기반으로 다운로드 후 설치한다.
+  - **건너뛰기** 선택 시: 플랫폼 설치 없이 바닐라로 진행한다.
+
+#### 4-2. 설치설정 설정
+- `%appdata%\.minecraft\launcher_profiles.json`에 프로필을 추가한다.
+  - 이미 동일한 이름의 프로필이 있으면 새로 만들지 않고 기존 프로필을 수정한다.
+- **`gameDir`을 `%appdata%\.mc_custom`으로 설정한다.**
+  - 이 설정으로 인해 모드, 리소스팩, 세이브 등 모든 파일이 `.mc_custom` 기준으로 읽히고 저장된다.
+- 램 설정(`javaArgs`)을 JSON의 서버 램 필드 기준으로 적용한다.
+  - `-Xmx`에 `serverMaxRam`, `-Xms`에 `serverMinRam` 값을 사용한다.
+- 플랫폼(Forge 등) 설치 버전을 `lastVersionId`로 설정한다.
+
+```json
+// launcher_profiles.json 프로필 예시
+{
+  "음악퀴즈": {
+    "name": "음악퀴즈",
+    "type": "custom",
+    "gameDir": "%appdata%\\.mc_custom",
+    "lastVersionId": "1.20.1-forge-47.2.0",
+    "javaArgs": "-Xmx4G -Xms2G"
+  }
+}
+```
+
+#### 4-3. 모드 및 리소스팩 설치
+- JSON 파일에 명시된 모드와 리소스팩을 다운로드하여 `.mc_custom` 하위 폴더에 저장한다.
+- 다운로드 진행 상황을 실시간 로그 뷰어로 표시한다. (다른 프로그램 설치 화면과 동일한 형태)
+
+| 파일 종류 | 저장 경로 |
+|-----------|-----------|
+| 모드 (`.jar`) | `%appdata%\.mc_custom\mods\` |
+| 리소스팩 (`.zip`) | `%appdata%\.mc_custom\resourcepacks\` |
+
+- 이미 동일한 파일명이 존재하면 덮어쓴다.
+- 다운로드 완료 후 마인크래프트 실행 시 자동으로 적용된다. (별도 설정 불필요)
+
+---
+
+### 5단계: 완료 페이지
+
+- 멀티로 진행해서 서버도 설치했다면:
+  - **서버 폴더 열기** 버튼
+  - **바탕화면에 서버 실행 바로가기 만들기** 토글 (기본값: ON)
+  - **서버 바로 실행** 토글 (기본값: ON)
+- 마인크래프트 런처 실행 토글 (기본값: ON)
+
+---
+
+## 파트 2. 음악퀴즈 관리 웹사이트
+
+> **기술 스택: Node.js + TypeScript + Express + EJS**
+
+### 라우팅 구조
+
+| 경로 | 설명 |
+|------|------|
+| `/` | 메인 페이지 (음악퀴즈 목록) |
+| `/manifest.json` | manifest.json 파일 직접 접근 |
+| `/file/` | 음악퀴즈 파일 제공 경로 |
+| `/op` | 관리자 로그인 페이지 |
+| `/op/dashboard` | 관리자 대시보드 |
+| `/op/dashboard/:packName` | 음악퀴즈 JSON 편집 페이지 |
+
+---
+
+### 메인 페이지 (`/`)
+
+- `manifest.json`에 등록된 음악퀴즈를 **가로 한 줄 목록(카드) 형식**으로 표시한다.
+
+---
+
+### 관리자 인증 (`/op`)
+
+- `/op` 하위 모든 경로는 로그인 없이 접근 불가 (미들웨어로 처리).
+- 로그인 화면: 아이디 + 비밀번호 입력.
+- 계정 정보는 **`account.json`** 파일에 저장.
+  - `account.json`은 **서버 내부에서만 접근 가능**, 외부 HTTP 요청으로 절대 노출되지 않아야 함.
+- 로그인 성공 시 `/op/dashboard`로 리다이렉트.
+
+#### account.json 예시 구조
+```json
+[
+  {
+    "id": "admin",
+    "password": "admin"
+  }
+]
+```
+
+---
+
+### 관리자 대시보드 (`/op/dashboard`)
+
+#### 공통 레이아웃 (메뉴바)
+- **왼쪽**: 로고 + "관리자 페이지" 텍스트 → 클릭 시 `/op/dashboard`로 이동
+- **오른쪽**: 로그인한 아이디 표시 → 클릭 시 드롭다운 메뉴 표시
+  - 드롭다운 항목: **로그아웃** 버튼
+
+#### 음악퀴즈 목록
+- `/manifest` 폴더 안의 JSON 파일들을 가져와 **가로 한 줄 카드 형식**으로 표시.
+- 카드 클릭 → `/op/dashboard/:packName` 으로 이동하여 JSON 편집 시작.
+
+#### 음악퀴즈 추가 버튼
+- `/manifest/` 폴더 안에 새 JSON 파일 생성.
+  - 기본 이름: `new.json`
+  - 이미 존재하면: `new2.json`, `new3.json` ... 순으로 증가.
+- 생성과 동시에 `manifest.json`에도 자동 등록.
+
+#### 음악퀴즈 삭제 버튼
+- 버튼 클릭 시:
+  - 목록 카드에 **체크박스** 표시
+  - 버튼 아래 **취소** / **확인** 버튼 표시
+- 확인 클릭 시 체크된 JSON 파일 삭제 + `manifest.json`에서도 자동 제거.
+
+---
+
+### 음악퀴즈 편집 페이지 (`/op/dashboard/:packName`)
+
+- 해당 JSON 파일의 내용을 GUI 폼으로 편집한다.
+- **JSON 파일 이름 변경** 기능 제공.
+  - 이름 변경 후 적용 클릭 시 현재 브라우저 URL의 `:packName` 부분도 자동 변경 (리다이렉트).
+
+---
+
+## 파트 3. 음악퀴즈 JSON 구조 및 편집 항목
+
+> `/manifest/*.json` 파일의 구조. 관리자 편집 페이지에서 아래 항목들을 GUI로 수정 가능.
+
+### JSON 필드 정의
+
+| 필드명 | 타입 | 설명 |
+|--------|------|------|
+| `name` | `string` | 음악퀴즈 이름 |
+| `mcVersion` | `string` | 마인크래프트 버전 (스냅샷 제외한 정식 릴리즈만) |
+| `platform` | `object` | 모드 플랫폼 정보 (아래 참고) |
+| `platform.type` | `string` | 플랫폼 종류 (`vanilla` / `forge` / `fabric` / `neoforge` 등) |
+| `platform.downloadUrl` | `string` | 플랫폼 설치파일 다운로드 URL (바닐라면 생략) |
+| `mods` | `array` | 설치할 모드 목록 (아래 참고) |
+| `mods[].name` | `string` | 모드 이름 |
+| `mods[].downloadUrl` | `string` | 모드 다운로드 URL |
+| `resourcepacks` | `array` | 설치할 리소스팩 목록 |
+| `resourcepacks[].name` | `string` | 리소스팩 이름 |
+| `resourcepacks[].downloadUrl` | `string` | 리소스팩 다운로드 URL |
+| `serverMinRam` | `number` | 서버 최소 램 (MB 단위) |
+| `serverMaxRam` | `number` | 서버 최대 램 (MB 단위) |
+| `clientMinRam` | `number` | 유저(클라이언트) 최소 램 (MB 단위) |
+| `clientRecommendedRam` | `number` | 유저(클라이언트) 권장 램 (MB 단위) |
+| `packPath` | `string` | 서버 파일 경로 (`/file/` 이후의 경로, 멀티 전용) |
+
+### JSON 예시
+```json
+{
+  "name": "음악퀴즈 v1",
+  "mcVersion": "1.20.1",
+  "platform": {
+    "type": "forge",
+    "downloadUrl": "https://example.com/forge-installer.jar"
+  },
+  "mods": [
+    {
+      "name": "ExampleMod",
+      "downloadUrl": "https://example.com/examplemod.jar"
+    }
+  ],
+  "resourcepacks": [
+    {
+      "name": "ExampleResourcePack",
+      "downloadUrl": "https://example.com/resourcepack.zip"
+    }
+  ],
+  "serverMinRam": 2048,
+  "serverMaxRam": 8192,
+  "clientMinRam": 4096,
+  "clientRecommendedRam": 8192,
+  "packPath": "music-quiz/files"
+}
+```
+
+### 편집 UI 항목별 비고
+
+| 항목 | UI 형태 | 비고 |
+|------|---------|------|
+| `mcVersion` | 드롭다운 | Mojang API에서 정식 릴리즈만 가져와 표시, 스냅샷 제외 |
+| `platform.type` | 드롭다운 | `vanilla` 선택 시 `downloadUrl` 입력란 숨김 |
+| `mods` | 동적 목록 | 항목 추가 / 삭제 가능 |
+| `resourcepacks` | 동적 목록 | 항목 추가 / 삭제 가능 |
+| 램 관련 필드 | 숫자 입력 | MB 단위, `clientMinRam` ≤ `clientRecommendedRam` 유효성 검사 |
+| `packPath` | 텍스트 입력 | `/file/` 이후 경로만 입력 |
+
+---
+
+## 파트 4. manifest.json 구조
+
+> 사이트 루트의 `manifest.json`. 설치기와 메인 페이지가 이 파일을 읽는다.
+
+```json
+{
+  "packs": [
+    {
+      "name": "음악퀴즈 이름",
+      "file": "new"
+    }
+  ]
+}
+```
+
+- `file`: `/manifest/` 폴더 안의 JSON 파일 이름 (확장자 제외).
+- 음악퀴즈 추가/삭제 시 자동으로 이 파일도 업데이트된다.
+
+---
+
+## 디렉토리 구조 (웹사이트)
+
+```
+project-root/
+├── manifest.json          # 음악퀴즈 목록 (외부 접근 가능)
+├── account.json           # 관리자 계정 정보 (외부 접근 절대 불가)
+├── /manifest/             # 음악퀴즈 JSON 파일 저장 폴더
+│   ├── new.json
+│   └── music-quiz.json
+├── /file/                 # 서버 파일 제공 경로 (멀티 전용)
+├── /src/                  # TypeScript 소스
+│   ├── app.ts
+│   ├── routes/
+│   │   ├── index.ts       # 메인 페이지
+│   │   └── op.ts          # 관리자 라우트
+│   └── middleware/
+│       └── auth.ts        # /op 인증 미들웨어
+└── /views/                # EJS 템플릿
+    ├── index.ejs
+    ├── op/
+    │   ├── login.ejs
+    │   ├── dashboard.ejs
+    │   └── editor.ejs
+    └── partials/
+        └── navbar.ejs
+```