🎮 어린이 학습 게임 놀이터 (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-nodejust check-ocean-rescue-toolchainjust typecheck-ocean-rescuejust dev-ocean-rescuejust build-ocean-rescuejust check-ocean-rescue-driftjust 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 entryshared/: 과목/제품 공용 domain·UI 로직domains/: Core Quiz, reward, Ocean Rescue 등 기능 도메인experiments/: surface별 실험 영역. Space Explorer는 paused 상태이며, 디렉터리 전체가 동결된 것은 아니다.ocean-rescue/: Ocean Rescue production standalone artifactdocs/: 제품 SSOT, feature spec, 기술 참고tests/: 제품·회귀 계약
