math-quiz/README.md

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)

---

문제 유형

1. 괄호 음수 분배 — 괄호 앞 음수 곱셈 시 괄호 내 부호 변경
   • 예: -2 × (3 - 6)
2. 이항 부호 변경 — 등식의 항을 이항할 때 부호 반전
   • 예: 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 시 자동 빌드·배포