BlockSeasons/docs/firebase-hosting-guide.md

Firebase Hosting 시즌 배포 가이드 (오너용)

앱은 시작할 때마다 CONTENT_BASE_URL/manifest.json을 확인하고, 새 시즌 팩을 SHA256 검증 후 내려받습니다. 호스팅은 정적 파일 서버이기만 하면 되며, Firebase Hosting 무료 플랜이면 충분합니다.

1회 설정 (약 15분)

1. https://console.firebase.google.com → 프로젝트 추가 → 이름 block-seasons → Google Analytics 사용 설정 (이후 분석 연동에 사용).
2. 터미널에서:

   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 ...):

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 체크리스트).