Math - 산수 모험 앱

덧셈, 뺄셈, 곱셈, 나눗셈을 스테이지 방식으로 연습하는 어린이용 산수 앱입니다. Kotlin Multiplatform(KMP)과 Compose Multiplatform 기반으로 iOS와 Android에서 공유 UI/게임 로직을 사용합니다.

프로젝트 구조

math-app/
├── android/
│   ├── app/                        # Android 앱 진입점
│   └── shared/
│       └── src/
│           ├── commonMain/         # 공유 UI, 게임 로직, 상태 관리
│           ├── androidMain/        # Android 플랫폼 구현
│           └── iosMain/            # iOS 플랫폼 구현
├── ios/
│   ├── Math.xcodeproj/
│   └── Math/                       # iOS 앱 진입점 및 키보드 브리지
├── htmls/                          # 기능/UX 기획 산출물
├── design-system.css               # 디자인 시스템 참고 파일
└── README.md

주요 기능

온보딩과 캐릭터

• 첫 실행 시 온보딩 화면 제공
• 곰돌이, 토끼, 여우, 부엉이 중 학습 캐릭터 선택
• 선택한 캐릭터가 홈, 스테이지 맵, 결과 화면, 리포트에 반영

홈과 학습 플로우

• 홈 화면에서 하트, 누적 포인트, 코인 잔액, 오늘의 퀘스트, 연산별 진행률 확인
• 하단 탭으로 홈 / 진행상황 / 보물 상자 / 캐릭터 이동
• 설정 화면에서 언어, 다크 모드, 학습 관리 옵션, 진척도 초기화 지원

온보딩
  └─ 캐릭터 선택
      └─ 홈
          ├─ 오늘의 퀘스트 → 게임 → 홈
          ├─ 연산 선택 → 스테이지 맵 → 게임 → 결과
          │   ├─ 다시 하기
          │   ├─ 다음 단계로
          │   └─ 홈으로
          ├─ 진행상황
          ├─ 보물 상자
          ├─ 캐릭터 꾸미기 → 상점
          └─ 설정

스테이지 구성

• 4가지 연산: 덧셈 / 뺄셈 / 곱셈 / 나눗셈
• 연산당 20스테이지, 총 80스테이지
• 난이도 10단계가 객관식/주관식으로 나뉘어 구성
  • 홀수 스테이지: 객관식
  • 짝수 스테이지: 주관식 입력
• 각 스테이지는 10문제로 구성
• 1스테이지는 기본 해금, 스테이지 완료 시 다음 스테이지 해금
• 최고 별 기록만 저장되어 재도전해도 기존 기록이 하락하지 않음

문제와 입력 방식

• 연산과 스테이지에 따라 문제 범위 자동 조정
• 3-2-1-시작 카운트다운 후 게임 시작
• 객관식 스테이지는 4지선다 선택 방식
• 주관식 스테이지는 커스텀 숫자 키패드 사용
• Android/iPad 하드웨어 키보드 입력 지원
• 가로/세로 화면에 맞춘 반응형 게임 레이아웃

평가와 보상

3-스타 평가

스테이지 결과는 첫 시도 정답 수와 평균 풀이 시간을 기준으로 평가합니다.

등급	조건
⭐⭐⭐	첫 시도 10/10 정답 + 평균 6초 이하
⭐⭐	첫 시도 8개 이상 정답
⭐	스테이지 완료

포인트 보상

획득 별과 스테이지 구간에 따라 포인트를 지급합니다.

스테이지 구간	1⭐	2⭐	3⭐
1~6단계	100	110	120
7~14단계	150	165	180
15~20단계	200	220	240

코인 보상

코인은 상점에서 아이템 구매에 사용되는 별도 화폐입니다. 스테이지 완료 시 별 수와 구간에 따라 지급됩니다.

스테이지 구간	1⭐	2⭐	3⭐
1~6단계	5	10	15
7~14단계	8	16	24
15~20단계	12	24	36

퀘스트 수행 중에는 코인이 약 1.5배 지급되며, 일일 퀘스트 완료 시 보너스 25코인을 추가로 받습니다.

하트 시스템

• 최대 하트 15개
• 일반 스테이지 시작 시 하트 1개 소모
• 5분마다 하트 1개 자동 충전
• 앱을 닫아둔 동안 지난 시간도 반영해 재실행 시 하트 자동 회복
• 하트가 부족하면 스테이지를 시작할 수 없음

일일 퀘스트

• 매일 자정 기준으로 10문제 목표 퀘스트 생성
• 학습자의 진행 상황을 바탕으로 퀘스트 유형 자동 선택
  • 진행 중인 연산 이어가기 (60%)
  • 별 1개를 받은 약한 스테이지 복습 (30%)
  • 아직 시작하지 않은 연산 소개 (10%)
• 홈 카드에 진행률 표시 ("N개만 더! 💪" 형태)
• 퀘스트 완료 시 코인 보너스 25개 추가 지급

상점 및 캐릭터 꾸미기

캐릭터 꾸미기 탭과 상점을 통해 스테이지에서 획득한 코인으로 아이템을 구매하고 캐릭터를 꾸밀 수 있습니다.

아이템 종류

카테고리	아이템 예시	슬롯
머리 장식	👑 왕관, 🎩 모자, 🎀 리본, 🌸 꽃, ⭐ 별	1개
뱃지	🏅 메달, 💎 다이아, 🔥 불꽃, 🌟 별빛	1개
배경	🌈 무지개, 🌙 밤하늘, 🌊 바다, 🌺 봄	1개
결과 효과	🎉 파티, ✨ 반짝임, 🎈 풍선	1개

구매와 장착 플로우

미보유 아이템과 보유 아이템의 동작을 명확히 분리합니다.

상태	버튼	동작
미보유 (코인 충분)	구매하기	확인 다이얼로그 → 구매 후 장착 여부 선택
미보유 (코인 부족)	코인 부족	비활성화
보유 중	장착하기	코인 차감 없이 즉시 장착
장착 중	장착 중	탭하면 해제

구매 확정 후 자동 장착되지 않으며, "나중에 / 장착하기" 선택으로 장착 시점을 결정합니다.

학습 리포트와 보상 콘텐츠

진행상황

• 오늘 푼 문제 수, 정확도, 연속 학습일 표시
• 주간 학습량 막대 차트 제공 (요일별 정확한 슬롯에 기록)
• 배지 수집 현황 제공

배지

• 첫 스테이지 클리어
• 별 3개 획득
• 별 3개 10회 달성
• 모든 스테이지 클리어
• 7일 연속 학습
• 모든 연산 도전

보물 상자

• 누적 포인트에 따라 레벨 진행 (최대 10레벨)
• 포인트 기준으로 9종 보물 컬렉션 해금
• 다음 레벨까지 필요한 포인트 표시

다국어와 테마

• 5개 언어 지원: 한국어, English, 中文(繁體), 中文(简体), 日本語
• 기기 언어 기반 초기 언어 설정
• 앱 내 언어 변경 지원
• 라이트/다크 모드 지원
• 공통 색상과 그라디언트를 AppColors 디자인 시스템으로 관리

실행 방법

Android

Android Studio에서 android/ 폴더를 열거나, 커맨드라인으로 실행합니다.

cd android
./gradlew :app:assembleDebug

빌드된 APK 위치:

android/app/build/outputs/apk/debug/app-debug.apk

요구사항:

• Android Studio 또는 JDK 17+
• Android SDK 34
• minSdk 26

iOS

1. Xcode에서 ios/Math.xcodeproj 열기
2. 시뮬레이터 또는 실제 기기 선택
3. Cmd + R로 빌드 및 실행

요구사항:

• Xcode 15.0 이상
• iOS 17.0 이상

기술 스택

• Kotlin Multiplatform
• Compose Multiplatform
• Material 3
• Android Gradle Plugin
• Swift 기반 iOS 앱 엔트리