IIS Games Archive

IIS 전체 서비스에서 공개 가능한 정적 게임 산출물만 보관하는 아카이브 저장소입니다.

이 저장소가 맡는 책임

• games/<slug>/ 형태의 공개 정적 파일 저장
• manifest/games.json 인덱스 유지
• 허용 파일 범위와 파일 크기 제한 검증
• Core Engine 퍼블리시 결과의 최종 공개 저장소 역할 수행

이 저장소는 애플리케이션 서버가 아니라 공개 정적 자산 저장소입니다.

운영 노출 범위

• 독립 앱 URL은 없습니다.
• 공개 사용자는 https://iis-arcade-portal.jeonsavvy.workers.dev/ 포털의 artifact proxy를 통해 산출물을 봅니다.

운영 smoke check는 포털의 공개 게임 화면에서 archive 산출물이 원본 URL 직접 노출 없이 로드되는지 확인합니다.

현재 구조

• games/<slug>/... : 공개 게임 산출물
• manifest/games.json : 전체 게임 인덱스
• manifest/schema.json : manifest 계약
• scripts/archive_guard.py : allowlist와 manifest 검증기
• .github/workflows/archive-guard.yml : CI 검증

허용 파일 계약

허용 경로:

• games/<game_slug>/**/*
• manifest/games.json
• manifest/schema.json
• scripts/archive_guard.py
• scripts/.gitignore
• AGENTS.md
• LICENSE
• README.md
• .env.example
• .github/workflows/archive-guard.yml

허용 확장자:

• .html
• .css
• .js
• .json
• .png
• .jpg
• .jpeg
• .webp
• .avif
• .svg
• .gif
• .mp3
• .ogg
• .wav
• .woff2

추가 규칙:

• 숨김 파일 경로 금지
• .., // 경로 금지
• 파일당 최대 5MB

Manifest 계약

manifest/games.json 은 단일 인덱스입니다.

필수 루트 키:

• schema_version
• generated_at
• games[]

각 게임 항목 규칙:

• slug
• name
• genre
• path
• created_at
• path 는 반드시 games/<slug>/index.html

저장소에 있는 모든 games/*/index.html 은 manifest에 정확히 1회만 등록되어야 합니다.

Core Engine과의 연동

iis-core-engine/app/services/github_service.py 가 아래 순서로 이 저장소를 갱신합니다.

1. 원격 main 기준으로 저장소를 동기화합니다.
2. manifest/games.json 을 갱신합니다.
3. games/<slug>/ 파일을 쓰거나 삭제합니다.
4. scripts/archive_guard.py all 을 실행합니다.
5. 검증 통과 시 커밋과 푸시를 진행합니다.

자동 커밋 메시지 규칙:

• 추가/갱신: feat: archive <game_slug>
• 삭제: chore: delete archive <game_slug>

왜 별도 저장소로 두었나

이 저장소는 제품 소스코드 저장소가 아니라, 공개 가능한 정적 산출물만 남기는 저장소 입니다.

• 제작 중인 코드와 공개 중인 결과물을 분리할 수 있습니다.
• allowlist와 manifest 계약으로 공개 범위를 명확하게 제한할 수 있습니다.
• 코어 엔진이나 포털의 내부 소스, 로그, 비밀값이 공개 산출물 경로에 섞이지 않게 유지할 수 있습니다.

실제 생성과 퍼블리시 처리는 Core Engine 쪽에서 수행하고, 이 저장소는 그 결과를 공개 가능한 형태로 보존하는 마지막 기록 계층 역할을 맡습니다.

검증

python3 scripts/archive_guard.py all
PYTHONDONTWRITEBYTECODE=1 python3 -B -m compileall -q scripts

공개 저장소 기준

• 런타임 비밀값은 없습니다.
• 코어 엔진이나 포털 소스코드는 여기에 저장하지 않습니다.
• 내부 프롬프트, 운영 로그, 자격증명 파일은 허용하지 않습니다.

License

MIT