🎮 어린이 학습 게임 놀이터 (AidenGame)

AidenGame은 초등 저학년 어린이가 스스로 반복해서 사용하면서 실제 학습 숙련도를 높이고, 학습 완료 후 게임과 현실 보상을 얻는 개인용 학습 게임 플랫폼입니다.

제품 방향 SSOT: docs/specs/product/ACTIVE_PRODUCT_SCOPE.md

🎯 현재 개발 초점

현재 최우선 개발 영역은 Math를 첫 vertical slice로 하는 curriculum-aligned skill mastery + adaptive daily learning loop입니다.

skill goal
→ 문제 풀이
→ learning evidence
→ mastery 갱신
→ adaptive next question
→ goal 완료
→ gems + free-time
→ Ocean Rescue

• 국어·수학·영어·과학의 기존 핵심 quiz reliability stabilization은 완료된 baseline입니다.
• 첫 구현 대상은 Math이며, 검증된 skill/mastery 계약만 다른 과목으로 확장합니다.
• Ocean Rescue는 학습 문제를 내부에 넣는 교육게임이 아니라 학습 완료 후 즐기는 active reward game입니다.
• Space Explorer는 계속 PAUSED_REFERENCE_ONLY입니다.
• 새로운 대형 게임, RPG식 meta progression, 새 backend API/인증 provider 확장, runtime LLM, 전체 framework/TypeScript 통일은 현재 기본 개발 목표가 아닙니다.
• child-facing 기능은 Supabase Google 로그인 후 이용할 수 있습니다. session이 없거나 확인할 수 없으면 로그인 gate가 기능을 차단합니다.

🚀 핵심 제품 surface

• Core Quiz: 국어, 수학, 영어, 과학 학습 surface
• Adaptive learning: 세부 skill mastery, spaced review, 약점 개선 + 성공 경험 균형
• Reward loop: 보석, streak, collection/unlock, 자유시간
• Ocean Rescue: 학습 목표 완료 후 이용하는 보상 게임
• Guardian: skill 성장/약점, 간단한 목표 preset, 현실 보상 상점
• Persistence: local-first, export/import backup 우선, 로그인 계정 단위 cloud sync
• Login: Supabase Google OAuth 기반 child-facing 기능 gate

📱 기준 사용 환경

• 1차 대상: 가족/개인 사용
• 초기 기준: 실제 사용하는 초등 저학년 아이의 현재 수준
• 기준 기기: Galaxy Tab S10급 Android 태블릿
• UX: landscape-first, portrait/split-screen/resize에서도 핵심 사용 가능
• 현재 runtime은 정적 웹 중심이며 필요에 따라 feature별 tooling을 다르게 사용할 수 있습니다.

🧭 현재 엔트리/라우팅

• 메인 허브: index.html
• 우주 탐험 페이지: experiments/space-explorer/index.html
• 우주 탐험 모듈 엔트리: experiments/space-explorer/main.js
• 전기 발전 실험실: experiments/electricity/index.html
• 전기 발전 실험실 3D 월드: experiments/electricity/world.js
• 전기 발전 실험실 물리 엔진: experiments/electricity/electricity-physics.js
• 자석 실험실: experiments/magnet/index.html
• 자석 실험실 물리 엔진: experiments/magnet/magnet-physics.js
• 과목별 학습: domains/{math,english,korean,science}/index.html
• 보호자 관리: domains/reward/guardian/index.html
• Ocean Rescue source/package: domains/ocean-rescue/
• Ocean Rescue production artifact: ocean-rescue/index.html
• 배포 라우팅 설정: vercel.json
• 로그인 gate: domains/auth/auth-gate.js
• 검증 진입점: 루트 verify.sh
• 주요 상태 분류:
  • Ocean Rescue | 운영중·active feature
  • Space Explorer | 배포된 artifact·PAUSED_REFERENCE_ONLY

운영 / 실험 / 레거시 경로 구분표

구분	경로	상태	용도
메인 허브	index.html	운영중	학습·보상·게임 진입점
Core Quiz 4과목	domains/{math,english,korean,science}/index.html	운영중	adaptive learning의 학습 surface
Guardian / Reward	domains/reward/guardian/index.html	운영중	성장·목표·보상 관리
Ocean Rescue	ocean-rescue/index.html	운영중·active feature	학습 완료 후 reward game
우주 탐험 실험 페이지	experiments/space-explorer/index.html	배포된 artifact·PAUSED_REFERENCE_ONLY	참고 전용
전기 발전 실험실	experiments/electricity/index.html	운영중	전기 발전 일곱 가지 실험
자석 실험실	experiments/magnet/index.html	운영중	자기장·자석 놀이 실험
과거 우주 탐험 alias	/space-explorer.html, experiments/space-explorer.html	없음	레거시 경로

과거 alias나 plan의 WP 번호를 현재 runtime entry 또는 다음 작업의 근거로 사용하지 않습니다.

🎮 Ocean Rescue toolchain

Ocean Rescue는 제품 차원에서 active feature지만, 현재 기본 구현 우선순위는 Math mastery/adaptive loop입니다. Ocean Rescue 작업이 명시적으로 선택되었을 때는 가장 가까운 feature/technical spec과 할당된 workspace/ref를 기준으로 수행합니다 (별도 지정이 없으면 최신 main).

대표 명령:

• just sync-ocean-rescue-node
• just check-ocean-rescue-toolchain
• just typecheck-ocean-rescue
• just dev-ocean-rescue
• just build-ocean-rescue
• just check-ocean-rescue-drift
• just check-ocean-rescue-rollback

제약:

• Node는 Ocean Rescue build-time/tooling boundary에 한정합니다.
• ocean-rescue/index.html은 production build pipeline이 생성하는 artifact입니다.
• generated artifact, provenance, registry identity를 손으로 우회 편집하지 않습니다.
• Vite/ESM/TypeScript migration 참고는 docs/plans/PLAN_ocean_rescue_vite_esm_typescript_migration.md를 사용하되, 그 문서가 현재 제품 우선순위를 소유하지 않습니다.

🛠️ 로컬 개발 / 검증

통합 검증 (verify.sh):

bash ./verify.sh

주요 문서:

• 실행 규약: AGENTS.md
• 제품 방향 SSOT: docs/specs/product/ACTIVE_PRODUCT_SCOPE.md
• 아키텍처·품질 경계: PROJECT_RULES.md
• 문서 권위 색인: docs/README.md
• 완료된 Core Quiz reliability 계약: docs/specs/product/CORE_QUIZ_RELIABILITY_STABILIZATION.md
• 세션 handoff: docs/agent-context/memory/MEMORY.md

📁 주요 디렉토리

• /: 사용자 runtime HTML/CSS/JS entry
• shared/: 과목/제품 공용 domain·UI 로직
• domains/: Core Quiz, reward, Ocean Rescue 등 기능 도메인
• experiments/: surface별 실험 영역. Space Explorer는 paused 상태이며, 디렉터리 전체가 동결된 것은 아니다.
• ocean-rescue/: Ocean Rescue production standalone artifact
• docs/: 제품 SSOT, feature spec, 기술 참고
• tests/: 제품·회귀 계약