Math Quiz
중학교 2학년 대상 수학 실수 유형 반복 연습 교육용 게임 서비스.
문제 생성은 AI 없이 자체 알고리즘 엔진으로 처리합니다.
기술 스택
| 레이어 | 기술 |
|---|---|
| 프레임워크 | Next.js 14 (App Router) + TypeScript 5 |
| 스타일 | Tailwind CSS 3 |
| 상태 관리 | Zustand |
| 수식 렌더링 | KaTeX |
| 애니메이션 | Framer Motion |
| 인증 | NextAuth.js 4 |
| ORM | Prisma (MariaDB 11) |
| 캐시 | Redis 7 |
| 유효성 검증 | Zod |
| 패키지 매니저 | pnpm |
| 테스트 | Vitest (단위) / Playwright (E2E) |
문제 유형
- 괄호 음수 분배 — 괄호 앞 음수 곱셈 시 괄호 내 부호 변경
- 예:
-2 × (3 - 6)
- 예:
- 이항 부호 변경 — 등식의 항을 이항할 때 부호 반전
- 예:
3x - 5y + 8 = -2x + 2y - 2
- 예:
게임 모드
| 모드 | 설명 |
|---|---|
| 스피드 퀴즈 | 제한 시간 내 최대 문제 풀기, Redis Sorted Set 기반 실시간 점수판 |
| 일반 풀이 | 시간 제한 없음, 틀린 유형 반복 출제 |
화면 흐름
시작 화면 → 문제 유형 선택 → 게임 모드 선택 → 문제 풀이 → 결과 및 기록
현재 구현 상태
- 시작 화면에서
/play풀이 화면으로 이동할 수 있습니다. /play에서 괄호 앞 음수 분배 문제 10개를 풉니다.- 문제와 정답 수식은 KaTeX로 렌더링합니다.
- 진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
- 키보드 흐름을 지원합니다.
- 새 문제 시작 시 첫째 항 입력 칸에 focus
- 첫째 항 Enter → 둘째 항 입력 칸으로 이동
- 둘째 항 Enter → 제출
- 피드백 화면 → 다음 문제/결과 보기 버튼에 focus
- 결과 화면 → 다시 시작 버튼에 focus
시작하기
사전 요구사항
- Node.js 20+
- pnpm
- Docker (MariaDB, Redis 실행용)
설치
pnpm install
환경변수 설정
.env.example을 참고하여 .env.local 파일을 생성합니다.
cp .env.example .env.local
DATABASE_URL=mysql://user:pass@mariadb:3306/mathgame
REDIS_URL=redis://redis:6379
NEXTAUTH_SECRET=your-secret
개발 서버 실행
pnpm dev
http://localhost:3000에서 확인합니다.
빌드
pnpm build
pnpm start
프로젝트 구조
app/ # Next.js App Router 루트
(game)/ # 게임 화면 라우트 그룹
select-type/ # 문제 유형 선택
select-mode/ # 게임 모드 선택
play/ # 문제 풀이
api/
auth/ # NextAuth.js 핸들러
problem/ # 문제 생성 API
record/ # 풀이 기록 저장 API
layout.tsx
page.tsx # 시작 화면
components/
math/ # KaTeX 수식 컴포넌트
game/ # 게임 UI 컴포넌트
lib/
engine/ # 문제 생성 알고리즘 엔진
prisma.ts # Prisma Client 싱글턴
redis.ts # Redis Client 싱글턴
store/
gameStore.ts # Zustand 전역 게임 상태
prisma/
schema.prisma # MariaDB 모델 정의
.gitea/workflows/deploy.yml # CI/CD 워크플로우
배포
- 플랫폼: Synology NAS + Docker Compose + Nginx Proxy Manager
- CI/CD:
.gitea/workflows/deploy.yml—main브랜치 push 시 자동 빌드·배포