# 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) |

---

## 학습 유형

| 유형 | 상태 | 답변 방식 |
|---|---|---|
| 숫자 괄호 풀기 | ✅ 구현 완료 | 직접 입력 |
| 미지수 괄호 풀기 | ✅ 구현 완료 | 보기 선택 |
| 분수 괄호 풀기 | 준비 중 | — |
| 실수 괄호 풀기 | 준비 중 | — |

## 화면 흐름

```
학습 내용 선택(/) → 준비 화면 → 문제 풀이 → 결과
```

---

## 현재 구현 상태

### 공통

- 시작 화면(`/`)에서 학습 내용을 선택합니다. `숫자 괄호 풀기`, `미지수 괄호 풀기`가 활성 상태이고 분수·실수 괄호는 준비 중으로 비활성화되어 있습니다.
- 문제와 정답 수식은 KaTeX로 렌더링합니다.
- 진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
- 정답·오답 피드백은 `계산식 = 내가 입력한(고른) 답` 형식으로 표시합니다.
  - 정답은 정답 색상 박스와 `○` 표시, 오답은 오답 색상 박스, 붉은색 답, `×`, 굵은 정답값을 표시합니다.
- 결과 화면은 전체 문제를 `문제 = 내가 입력한(고른) 답` 형식으로 나열하며, 피드백과 같은 색상·기호 규칙을 사용합니다.
- 피드백 화면 진입 시 다음 진행 버튼에, 결과 화면 진입 시 다시 시작 버튼에 자동으로 focus가 이동합니다.

### 숫자 괄호 풀기 (`/number-parentheses` → `/number-parentheses/play`)

- 준비 화면에서 문제 수 5 / 10을 선택하고 연습을 시작합니다. 기본값은 10.
- 괄호 종류는 현재 `()`만 선택 가능하고 `{}`, `[]`는 비활성화되어 있습니다.
- 풀이 화면에서 두 항을 직접 숫자로 입력합니다.
  - 모든 항은 하나의 input에서 순서대로 입력하며, 첫째 항 Enter → 둘째 항 전환, 둘째 항 Enter → 제출.
  - input 위 우상단의 progress 표시에서 각 항의 진행 상태를 보여줍니다. 입력 전에는 괄호 안 원래 항 값, 입력 중/입력 후에는 사용자가 입력한 값을 표시합니다.
  - 터치 환경에서는 커스텀 숫자 키패드(숫자, `+/-`, `.`, `⌫`, `↵`)가 표시되며, 정밀 포인터가 있는 환경(마우스/트랙패드)에서는 숨깁니다.

### 미지수 괄호 풀기 (`/variable-parentheses` → `/variable-parentheses/play`)

- 준비 화면 구성은 숫자 괄호와 동일합니다.
- 풀이 화면에서 두 항을 보기 중에서 선택합니다.
  - 각 항의 보기는 정답 계수의 절대값을 기준으로 음수/양수 두 개를 제공합니다.
  - 첫째 항 선택 후 자동으로 둘째 항 보기로 focus가 이동합니다.
  - 둘째 항을 선택하면 별도 `정답 확인` 버튼 없이 즉시 피드백 화면으로 전환됩니다.
  - 입력 항 progress 표시는 선택 전에는 괄호 안 원래 항 값, 선택 후에는 고른 보기 값을 표시합니다.

---

## 시작하기

### 사전 요구사항

- 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
```

`pnpm build`는 Next.js standalone 산출물에 필요한 정적 파일 복사까지 함께 처리합니다.

---

## 프로젝트 구조

```
app/                              # Next.js App Router 루트
  (game)/                         # 게임 화면 라우트 그룹
    number-parentheses/           # 숫자 괄호 준비 화면
      play/                       # 숫자 괄호 풀이 화면
    variable-parentheses/         # 미지수 괄호 준비 화면
      play/                       # 미지수 괄호 풀이 화면
  api/
    auth/                         # NextAuth.js 핸들러
    problem/                      # 문제 생성 API
    record/                       # 풀이 기록 저장 API
  layout.tsx
  page.tsx                        # 시작 화면 (학습 내용 선택)
components/
  math/                           # KaTeX 수식 컴포넌트
  game/                           # 게임 UI 컴포넌트
lib/
  engine/                         # 문제 생성 알고리즘 엔진
    parenthesis-sign.ts           # 숫자 괄호 엔진
    variable-parenthesis.ts       # 미지수 괄호 엔진
  input-device.ts                 # 입력 장치 감지 미디어 쿼리
  prisma.ts                       # Prisma Client 싱글턴
  redis.ts                        # Redis Client 싱글턴
store/
  gameStore.ts                    # 숫자 괄호 Zustand 전역 상태
  variableGameStore.ts            # 미지수 괄호 Zustand 전역 상태
prisma/
  schema.prisma                   # MariaDB 모델 정의
.gitea/workflows/deploy.yml       # CI/CD 워크플로우
```

---

## 다음 확장 방향

- 분수 괄호, 실수 괄호는 각 문제 생성 엔진이 준비되면 시작 화면에서 활성화합니다.
- `{}`, `[]` 괄호 종류는 생성 엔진과 상태/URL 파라미터 연동이 준비된 뒤 준비 화면에서 활성화합니다.
- 스피드 퀴즈 모드, 풀이 기록 저장, 로그인 기능은 DB/Redis/NextAuth 연동 후 추가합니다.

---

## 배포

- **플랫폼**: Synology NAS + Docker Compose + Nginx Proxy Manager
- **CI/CD**: `.gitea/workflows/deploy.yml` — `main` 브랜치 push 시 자동 빌드·배포