키즈에듀

4~5세 아이가 그림을 보고 직접 조작하며 배우는 React 웹앱입니다. 로그인이나 백엔드 없이 실행되며, 학습 기록과 작품은 이 기기의 브라우저에 저장됩니다.

실행

Node.js 22 이상, pnpm 9.

pnpm install --frozen-lockfile
pnpm dev
pnpm typecheck
pnpm lint
pnpm test
pnpm build

처음 E2E 테스트를 실행하기 전에는 pnpm exec playwright install chromium으로 브라우저를 설치합니다. pnpm preview로 프로덕션 빌드를 확인할 수 있습니다. 배포 서버는 SPA 경로를 index.html로 연결해야 합니다.

콘텐츠

숫자 1~50, 한글 자모 24개, 영어 알파벳 26개와 게임 30종을 제공합니다. 음성 합성·마이크·TTS 기반 게임은 사용하지 않습니다. 효과음은 설정에서 끌 수 있고, 모든 진행과 정답 판정은 소리 없이 가능합니다. 학습 시간 제한 설정은 제거했습니다. 우주 비행과 두더지 잡기의 라운드 타이머는 게임 규칙입니다.

새로운 게임	활동	난이도·콘텐츠
꼬마 장보기	물건을 담고 빼며 수량과 덧셈 익히기	14가지 음식, 수량 1~5에서 두 묶음 합산까지
동물 탐험대	그림과 특징을 관찰해 동물 무리 분류하기	동물 20종, 포유류·새·파충류, 특징 설명
그림 단어 공방	글자 조각을 순서대로 이어 단어 완성하기	그림 단어 56종, 한글·영어, 전체 힌트→첫 글자→방해 조각
규칙 정원	반복되는 묶음을 찾아 다음 그림 고르기	탈것·동물·음식 주제, AB, ABB, ABC, AABB 패턴
반짝 우주 비행	세 갈래 길에서 별 수집·운석 피하기	속도 3단계, 터치·방향키, 일시정지, 30초 라운드
상상 마을 놀이터	탈것 22종과 동물 20종으로 자유롭게 꾸미기	마을·공사장 포함 배경 5종, 15자리, 지우개·되돌리기·자동 저장
출동! 탈것 마을	그림자와 역할을 보고 알맞은 탈것 고르기	경찰차·자동차·중장비 등 22종, 선택지 2/3/4개
맛있는 음식 만들기	햄버거·피자·샌드위치·팬케이크를 주문에 맞춰 만들기	재료 18종, 레시피 23종, 주문 3/4/5개, 메뉴 선택·자유 요리
톡! 톡! 달마치기	힘 게이지에 맞춰 블록을 쳐내고 달마 지키기	난이도별 5/7/9개 블록, 터치·방향키, 일시정지·재도전
팡팡! 미니게임 축제	세 버튼으로 색깔 맞추기·로켓 연타·순서 입력	A/S/D·터치, 미션 3개, 20/25/30초, 일시정지
색칠하기 / 자유 그리기	동물·탈것·자연·음식·장난감 도안을 칠하거나 그림 스탬프로 자유롭게 꾸미기	도안 40종·스탬프 6종, 되돌리기·다시 실행, 완성 작품 보기

탐험형 학습 게임은 6/8/10개의 문제로 구성됩니다. 음식 만들기는 3/4/5개 주문을 완성하며, 자유 요리에서는 재료를 최대 10개까지 마음대로 쌓습니다. 오답은 이유와 힌트를 보고 다시 시도하며, 첫 시도에 맞힌 문제 수가 별 보상에 반영됩니다. 기존 매칭 게임에도 실제 그림과 수량 카드를 적용했습니다.

기존 음성 전제 게임인 풍선 터뜨리기·빠르기 도전은 제거했습니다. 이전의 /games/balloon, /games/speed-quiz, /games/quiz, /games/speak 주소는 게임 목록으로 이동합니다.

데이터와 보상

• progress-store: 글자별 학습 완료·시도 횟수와 닉네임.
• gamification-store: 별·출석·스티커·게임 기록. completeGame이 완료 기록과 보상을 함께 저장하고 실행 ID로 중복 지급을 막습니다.
• playground-store: 탈것·동물 놀이터 작품. 기존 동물 작품도 유지됩니다. 보호자 설정의 데이터 초기화에 포함됩니다.
• sticker-rules: 학습·별·레벨·출석·게임 달성 조건. 모든 게임 보상은 현재 제공 중인 게임 목록을 기준으로 판정합니다.
• 홈은 완료된 숫자 항목 수를 50개 기준으로 표시합니다. 날짜는 기기 현지 날짜를 사용합니다.
• 따라쓰기는 자유롭게 쓰고 확인하는 연습입니다. 필체·획순의 정확도를 채점하지 않습니다. 같은 학습 항목을 다시 완료해도 별은 중복 지급하지 않습니다.

에셋

Kenney의 Animal Pack, Animal Pack Remastered, Space Shooter Remastered, Racing Pack, Food Kit에서 선택한 CC0 그림을 로컬에 포함했습니다. 음식 14종과 탈것·스티커 그림 42종(트로피 포함), 햄버거 재료 9종 및 완성 그림은 확대해도 선명한 자체 SVG로 제작했습니다. 스티커북은 항목에 맞는 실제 그림을 표시합니다. 탈것·햄버거 원본은 scripts/generate-play-assets.mjs에서 다시 생성할 수 있습니다. 출처·라이선스는 public/assets/kenney/CREDITS.txt와 각 하위 폴더의 LICENSE*.txt, 자체 그림 설명은 public/assets/illustrations/CREDITS.txt에 있습니다.

색칠 도안·그리기 스탬프·추가 메뉴 그림은 Twemoji v16.0.1에서 가져왔습니다. © Twitter, Inc. 및 기여자, CC BY 4.0. 원본은 public/assets/twemoji/, 출처·수정 내용은 해당 폴더의 CREDITS.md, 라이선스 전문은 LICENSE-GRAPHICS에 있습니다. 색칠용으로 SVG 도형을 경로로 변환하고 칠할 영역을 지정했습니다. python3 scripts/build-coloring-artwork.py로 로컬 원본에서 도안 데이터를 다시 생성할 수 있습니다. 새 요리 재료 SVG 9종은 이 프로젝트에서 제작했습니다.

게임 완료 시 전체 화면 색종이·빛줄기·별 연출을 표시하며, 동작 줄이기 설정을 존중합니다. 색칠한 작품은 결과 화면에서 감상할 수 있고, 도안별 작품의 영구 저장은 제공하지 않습니다. 미니게임 축제는 빠샤빠샤의 세 버튼 미니게임 형식을 참고한 자체 콘텐츠입니다.

외부 이미지 CDN 없이 작동하며, PWA 서비스 워커가 그림을 미리 저장합니다. 오프라인 사용은 온라인에서 프로덕션 앱을 한 번 열고 캐시 설치를 마친 뒤 가능합니다. 개발 서버에서는 PWA 오프라인 기능을 검증할 수 없습니다.

검증과 운영

.github/workflows/ci.yml에서 린트·실제 프로젝트 타입 검사·빌드·Chromium E2E를 실행합니다. 게임 타이머 테스트는 Playwright 가상 시간을 이용합니다. e2e/discovery-content.spec.ts에 신규 콘텐츠, 보상 저장, 중복 지급, 숫자 진도, 작품 저장 회귀 테스트가 있습니다.

기존 prd.md, qa_report.md, change_plan.md, pr_description.md는 과거 기획·작업 기록입니다. 현재 기능과 다를 수 있습니다. 브라우저 저장소를 지우면 기록이 사라지며, 서버 백업·기기 간 동기화는 제공하지 않습니다.

배포 후 이전 화면에서 사라진 페이지 파일을 요청하면 page-load-recovery가 서비스 워커 업데이트를 확인하고 경로별 한 번만 새로고침합니다. 재시도도 실패하면 안내 화면을 보여 주며 다른 메뉴로 이동할 수 있습니다. 학습 저장소는 지우지 않습니다. e2e/page-load-recovery.spec.ts는 파일 로딩 실패·재시도·오프라인·일반 오류를 검증하며, 빌드와 미리보기 서버 실행 후 RECOVERY_TEST_URL=http://127.0.0.1:4173 pnpm exec playwright test e2e/page-load-recovery.spec.ts로 배포용 파일에서도 실행할 수 있습니다.