From 56c273779e1802a4172531c28d5002e242b4d0a2 Mon Sep 17 00:00:00 2001
From: th-kim0823 <th.kim0823@navercorp.com>
Date: Mon, 27 Apr 2026 20:20:19 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20=EC=83=88=20?=
 =?UTF-8?q?=ED=9D=90=EB=A6=84=20+=20URL=20+=20topics=20=EC=84=A4=EB=AA=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 1-6 흐름 갱신 (팀편성 → 안내 → 해킹 → 발표 → 투표 → 시상)
모바일 투표 QR URL 명시 (/?mode=vote)
topics.categories + settings.current_stage 데이터 구조 설명 추가

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 54 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 14a1a14..a1a1325 100644
--- a/README.md
+++ b/README.md
@@ -3,48 +3,47 @@
 35명 (34명 참가 + 1명 진행요원) / 7팀 / 3분야 (재미·완성도·실용성) 투표 앱.
 **DB 없이 단일 JSON 파일** (`hackathon.json`)에 모든 데이터.
 
-## 흐름
+## 흐름 (행사 진행)
 
-1. `assign_teams.py` 실행 → `hackathon.json` 생성 (people 배정)
-2. `app.py` 실행 → 본인 이름 + 사번 입력 → 다른 6팀에 3분야 투표
-3. 어드민에서 마감 → 시상식 reveal
-4. 결과 자동 archive (`results_<ts>.json`)
+1. **Stage 1 — 팀 편성 + 안내** (큰 화면 `/`)
+2. **Stage 2 — 예시 주제** (큰 화면 `/`, 어드민이 "다음 stage →")
+3. **해킹** (앱 외부, 2시간)
+4. **발표**
+5. **Stage 3 — 투표** (큰 화면에 QR, 모바일 → `/?mode=vote`)
+6. **시상** (`/?mode=ceremony&token=mlops2026`)
 
-## 실행 — Docker
+## 실행 — Docker (한 줄)
 
 ```bash
-# 1. 팀 배정 (호스트에서 1회)
-python3 assign_teams.py
-
-# 2. .env (1회)
-cp .env.example .env
-# ADMIN_TOKEN을 강한 토큰으로 변경
-# 빠르게: python3 -c "import secrets; print(secrets.token_urlsafe(16))"
-
-# 3. 컨테이너
 docker compose up -d --build
-
-# 종료
-docker compose down
 ```
 
+첫 부팅 시 `entrypoint.sh`가 `assign_teams.py`를 자동 실행해서 `./data/hackathon.json` 시드 생성. 이후 부팅은 기존 데이터 보존.
+
+```bash
+docker compose down   # 종료 (데이터 보존)
+```
+
+**ADMIN_TOKEN**: `mlops2026` (외우기 쉬운 고정값). 변경하려면 `docker-compose.yml`의 `ADMIN_TOKEN:` 값 직접 수정 후 `docker compose up -d --build`.
+
 ## URL
 
 ```bash
 ./show-urls.sh   # localhost + LAN IP 포함 모든 URL 출력
 ```
 
-- 투표: `http://<서버>:8501/`
-- 어드민: `http://<서버>:8501/?mode=admin&token=<TOKEN>`
-- 시상식: `http://<서버>:8501/?mode=ceremony&token=<TOKEN>`
+- 큰 화면: `http://<서버>:8501/`
+- 모바일 투표 (QR target): `http://<서버>:8501/?mode=vote`
+- 어드민: `http://<서버>:8501/?mode=admin&token=mlops2026`
+- 시상식: `http://<서버>:8501/?mode=ceremony&token=mlops2026`
+- JSON 원본: `http://<서버>:8501/?mode=raw&token=mlops2026`
 
 macOS 빠른 열기:
 ```bash
-TOKEN=$(grep ADMIN_TOKEN .env | cut -d= -f2)
-open "http://localhost:8501/?mode=admin&token=${TOKEN}"
+open "http://localhost:8501/?mode=admin&token=mlops2026"
 ```
 
-## 데이터 파일 — `hackathon.json`
+## 데이터 파일 — `./data/hackathon.json`
 
 ```json
 {
@@ -65,9 +64,12 @@ open "http://localhost:8501/?mode=admin&token=${TOKEN}"
 ```
 
 - 호스트에서 직접 편집 가능 (jq, vi 등). 앱이 매 요청 reload — 핫리로드.
-- 단일 파일 read-write mount. atomic write (tmp + rename).
+- `./data/` 디렉터리 read-write mount. atomic write (tmp + rename).
 - 행사 전 명단 변경: `people[*].team` 값만 바꾸면 즉시 반영.
-- `assign_teams.py` 재실행 시 `people`만 갱신. votes/titles/tie_breaks 보존.
+- 어드민 페이지 또는 `?mode=raw&token=...`에서 JSON 다운로드 가능.
+- 시드 재생성: `rm data/hackathon.json && docker compose up -d` (entrypoint 자동 실행).
+- `topics.categories` 4 카테고리 × 10 items. 어드민에서 form / JSON 둘 다 편집.
+- `settings.current_stage` ∈ {"intro","topics","vote"} — 어드민에서 stage 컨트롤.
 
 ## 운영 흐름