diff --git a/docs/firebase-hosting-guide.md b/docs/firebase-hosting-guide.md new file mode 100644 index 0000000..96fb5f5 --- /dev/null +++ b/docs/firebase-hosting-guide.md @@ -0,0 +1,66 @@ +# Firebase Hosting 시즌 배포 가이드 (오너용) + +앱은 시작할 때마다 `CONTENT_BASE_URL/manifest.json`을 확인하고, 새 시즌 팩을 +SHA256 검증 후 내려받습니다. 호스팅은 정적 파일 서버이기만 하면 되며, +Firebase Hosting 무료 플랜이면 충분합니다. + +## 1회 설정 (약 15분) + +1. https://console.firebase.google.com → **프로젝트 추가** → 이름 `block-seasons` + → Google Analytics **사용 설정** (이후 분석 연동에 사용). +2. 터미널에서: + ```bash + npm install -g firebase-tools + firebase login + cd "/Volumes/Macintosh 2nd/Project/My_Game_Project/BlockSeasons" + firebase init hosting + # → Use an existing project → block-seasons + # → public 디렉터리: deploy + # → single-page app: No / 자동 빌드: No + ``` +3. 생성된 호스팅 도메인(예: `https://block-seasons.web.app`)을 Claude에게 + 알려주세요 — 앱의 `CONTENT_BASE_URL` 기본값(lib/main.dart)을 그 도메인으로 + 맞추고, `flutterfire configure`를 함께 진행해 Firebase Analytics 백엔드도 + 연결합니다. + +## 시즌 배포 (매 시즌 약 1분) + +새 시즌 팩을 생성한 뒤(`dart run tool/stage_generator/generate.dart ...`): + +```bash +cd "/Volumes/Macintosh 2nd/Project/My_Game_Project/BlockSeasons" +dart run tool/make_manifest.dart + +rm -rf deploy/content && mkdir -p deploy/content/seasons +cp content/manifest.json deploy/content/ +for d in content/season_*/; do + id=$(basename "$d") + mkdir -p "deploy/content/seasons/$id" + cp "$d/pack.json" "deploy/content/seasons/$id/" +done + +firebase deploy --only hosting +``` + +배포 직후 모든 유저의 **다음 콜드 스타트**에서 새 시즌이 나타납니다. +앱 업데이트·스토어 심사가 필요 없습니다. + +## 동작 방식 요약 (참고) + +- `manifest.json`: 시즌 목록 + 버전 + SHA256. `tool/make_manifest.dart`가 생성. +- 클라이언트: 버전이 다른 팩만 다운로드 → SHA256 일치 시에만 원자적으로 캐시 + 교체. 검증 실패·오프라인·서버 오류는 전부 조용히 무시되고 기존 캐시 또는 + 번들 시즌 1로 동작. +- 시즌 1은 앱에 번들되어 있어 인터넷이 한 번도 연결되지 않아도 게임이 + 완전히 동작합니다 (E2E 검증 완료: docs/screenshots/sim_offline_fallback.png). +- 원격 시즌 등장 검증: docs/screenshots/sim_remote_season2.png ("SEASON 2 · + 여름 파도"가 로컬 서버 배포만으로 등장). + +## 주의 + +- `pack.json`을 수정하면 반드시 `make_manifest.dart`를 다시 실행해 SHA256을 + 갱신해야 합니다 (불일치 시 클라이언트가 팩을 거부). +- 시즌 팩에 새 필수 필드를 도입하는 스키마 변경 시 `schemaVersion`을 올리면 + 구버전 앱은 그 팩을 무시합니다 (크래시 없음). +- `minAppBuild` 필드는 아직 클라이언트가 강제하지 않습니다 — 앱 버전 의존 + 콘텐츠를 배포하기 전에 강제 로직을 추가해야 합니다 (Phase 7 체크리스트). diff --git a/docs/screenshots/sim_offline_fallback.png b/docs/screenshots/sim_offline_fallback.png new file mode 100644 index 0000000..3cc5e1a Binary files /dev/null and b/docs/screenshots/sim_offline_fallback.png differ diff --git a/docs/screenshots/sim_remote_season2.png b/docs/screenshots/sim_remote_season2.png new file mode 100644 index 0000000..e191b40 Binary files /dev/null and b/docs/screenshots/sim_remote_season2.png differ