IIS Core Engine

IIS 전체 서비스에서 게임 생성, 수정, 검수, 퍼블리시를 처리하는 FastAPI 백엔드입니다.

운영 연결점

• 공개 포털: https://iis-arcade-portal.jeonsavvy.workers.dev/
• 이 저장소 자체는 공개 프론트엔드를 배포하지 않는 백엔드 런타임입니다. 실제 Core Engine base URL은 운영 비밀/인프라 설정에서 관리하고 README에 노출하지 않습니다.

운영 smoke check는 포털 BFF → Core Engine API, /healthz, /api/v1/health, 세션 생성/조회, 승인된 퍼블리시 경로를 staging 또는 승인된 운영 창에서 확인합니다.

이 저장소가 맡는 책임

• 세션 기반 게임 제작 API 제공
• 프롬프트 실행과 비동기 run 상태 관리
• 이슈 제기, 수정안 생성, 수정 반영 흐름 관리
• 퍼블리시 승인과 공개 메타데이터 기록
• iis-games-archive 저장소 GitOps 동기화
• 런타임 health와 세션 스키마 일치 여부 검증

빠른 시작

python3.11 -m venv .venv311
source .venv311/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env
./scripts/run_api.sh

기본 확인 경로:

• GET /healthz
• GET /api/v1/health
• GET /api/v1/sessions

요청 처리 흐름

1. 포털이 세션을 생성합니다.
2. 사용자가 프롬프트를 보내면 run이 큐잉되고 상태가 기록됩니다.
3. 코드 생성, 비주얼 검수, 플레이 테스트 결과가 세션 이벤트와 대화 기록에 남습니다.
4. 사용자는 이슈를 등록하고 수정안을 검토한 뒤 반영할 수 있습니다.
5. 퍼블리시 승인 후 HTML, 공개 메타데이터, 썸네일, 아카이브 저장소가 함께 갱신됩니다.

세션 접근 범위

• 세션은 생성 시 user_id 를 함께 기록합니다.
• creator 는 본인 세션만 조회/복원/수정할 수 있습니다.
• master_admin 는 전체 세션을 조회하고 운영실에서 관리할 수 있습니다.
• 포털은 Core Engine 세션 읽기/쓰기 요청에 actor header를 함께 전달합니다.

왜 Vertex를 사용하나

이 저장소에서 AI는 단순 문장 생성기가 아니라, 세션 기반 제작 흐름의 핵심 처리 계층입니다.

• GDD, 분석 계약, 계획 계약, 디자인 계약처럼 구조화된 결과 를 만들어야 합니다.
• 실제 게임 HTML과 퍼블리시용 텍스트처럼 자유 형식 결과 도 함께 다뤄야 합니다.
• 실행 중 특정 모델 경로가 흔들릴 때를 대비해 preview / pro / flash 경로를 순차 fallback 하도록 구성했습니다.

즉, Vertex는 한 번의 응답을 받기 위한 선택이 아니라, 구조화된 생성 + 텍스트 생성 + 세션 운영 fallback 을 한 흐름으로 맞추기 위한 구성입니다.

주요 API 범위

Health

• GET /healthz
• GET /api/v1/health

Sessions

• POST /api/v1/sessions
• GET /api/v1/sessions
• GET /api/v1/sessions/{session_id}
• DELETE /api/v1/sessions/{session_id}
• POST /api/v1/sessions/{session_id}/cancel
• GET /api/v1/sessions/{session_id}/conversation
• GET /api/v1/sessions/{session_id}/events
• POST /api/v1/sessions/{session_id}/plan-draft
• POST /api/v1/sessions/{session_id}/prompt
• GET /api/v1/sessions/{session_id}/runs/{run_id}
• POST /api/v1/sessions/{session_id}/runs/{run_id}/cancel

Issue review

• POST /api/v1/sessions/{session_id}/issues
• GET /api/v1/sessions/{session_id}/issues/latest
• POST /api/v1/sessions/{session_id}/issues/{issue_id}/propose-fix
• POST /api/v1/sessions/{session_id}/issues/{issue_id}/apply-fix

Publish and game admin

• POST /api/v1/sessions/{session_id}/approve-publish
• POST /api/v1/sessions/{session_id}/publish
• GET /api/v1/sessions/{session_id}/publish-thumbnail-candidates
• DELETE /api/v1/games/{game_id}

핵심 환경변수

전체 샘플은 .env.example 에 있습니다.

변수	설명
APP_ENV	production 여부를 결정합니다.
INTERNAL_API_TOKEN	포털이 호출하는 내부 Bearer 토큰입니다.
SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY	세션, 메타데이터, 스토리지 접근에 사용합니다.
SUPABASE_STORAGE_BUCKET	퍼블리시 결과를 올리는 버킷입니다.
PUBLIC_GAMES_BASE_URL	공개 산출물 URL fallback 기준입니다.
PUBLIC_PORTAL_BASE_URL	퍼블리시 후 플레이 URL을 만들 때 사용합니다.
VERTEX_PROJECT_ID / VERTEX_LOCATION	Vertex 호출 기본 설정입니다.
GEMINI_PRO_MODEL / GEMINI_FLASH_MODEL	생성 작업 모델 이름입니다.
GITHUB_TOKEN / GITHUB_ARCHIVE_REPO	아카이브 저장소 커밋에 사용합니다.
TELEGRAM_BOT_TOKEN / TELEGRAM_ALLOWED_CHAT_IDS	출시 알림 전송에 사용합니다.
PLAYWRIGHT_REQUIRED	퍼블리시 전 런타임 검증 강제 여부입니다.
HTTP_TIMEOUT_SECONDS / HTTP_MAX_RETRIES	외부 호출 정책입니다.

운영 인프라 관점

• 세션, 공개 메타데이터, 스토리지는 Supabase 를 사용합니다.
• 공개 포털은 Cloudflare Workers에서 제공되고, 이 저장소는 그 뒤에서 동작하는 백엔드 런타임을 담당합니다.
• 백엔드 배포는 AWS EC2 기반 원격 서버 에 SSH로 배포하는 흐름을 사용합니다.
• 퍼블리시된 공개 정적 결과물은 직접 이 저장소에 남기지 않고 iis-games-archive 와 공개 스토리지 경로로 분리합니다.

Supabase SQL 파일 정리 기준

현재 운영 경로 기준 주요 파일:

• 기본 스키마: supabase/schema.sql
• 세션 전환 기준 스키마: supabase/session_first_big_bang.sql
• 세션 협업/용량/퍼블리시 업그레이드:
  • supabase/session_async_collab_upgrade.sql
  • supabase/session_capacity_upgrade.sql
  • supabase/session_publish_copy_upgrade.sql
  • supabase/app_role_creator_upgrade.sql
• 공개 카탈로그/자산/로그 보조 스키마:
  • supabase/public_catalog_upgrade.sql
  • supabase/asset_registry.sql
  • supabase/log_retention.sql

보존 중인 이력성 파일:

• supabase/modular_gen_core.sql
• supabase/pipeline_v2_breaking.sql
• supabase/pipeline_v2_repair.sql

이 세 파일은 현재 기본 부트스트랩 경로에는 포함하지 않지만, 과거 운영 이력 추적과 복구 근거를 위해 저장소에 유지합니다.

검증

ruff check app tests
mypy
python -m compileall -q app tests
PYTHONPATH=. pytest -q -s

배포와 운영 문서

• CI: .github/workflows/backend-ci.yml
• 배포: .github/workflows/deploy-backend.yml
• 원격 배포 스크립트: scripts/deploy_remote.sh
• systemd 템플릿: deploy/systemd/iis-core-api.service.tmpl
• 운영 문서:
  • docs/ubuntu-arm-server-runbook.md
  • docs/scaffold-v3-migration.md
  • docs/telegram-operations.md

이 저장소는 포털 화면을 직접 배포하지 않습니다. 백엔드 API, 세션 처리, 퍼블리시 경로, 외부 연동이 이 저장소의 실제 배포 대상입니다.

공개 저장소 기준

• 비밀값은 .env 에만 두고 커밋하지 않습니다.
• 퍼블리시 결과물은 이 저장소에 직접 저장하지 않고 iis-games-archive 로 보냅니다.
• 포털이 사용하는 내부 API 계약은 유지하되, 운영 전용 자격증명은 코드에 넣지 않습니다.

License

MIT