# 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 기반 실시간 점수판 |
| 일반 풀이 | 시간 제한 없음, 틀린 유형 반복 출제 |

## 화면 흐름

```
시작 화면 → 문제 유형 선택 → 게임 모드 선택 → 문제 풀이 → 결과 및 기록
```

---

## 시작하기

### 사전 요구사항

- Node.js 20+
- pnpm
- Docker (MariaDB, Redis 실행용)

### 설치

```bash
pnpm install
```

### 환경변수 설정

`.env.example`을 참고하여 `.env.local` 파일을 생성합니다.

```bash
cp .env.example .env.local
```

```env
DATABASE_URL=mysql://user:pass@mariadb:3306/mathgame
REDIS_URL=redis://redis:6379
NEXTAUTH_SECRET=your-secret
```

### 개발 서버 실행

```bash
pnpm dev
```

`http://localhost:3000`에서 확인합니다.

### 빌드

```bash
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 시 자동 빌드·배포