152 lines
4.7 KiB
Markdown
152 lines
4.7 KiB
Markdown
# 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 기반 실시간 점수판 |
|
||
| 일반 풀이 | 시간 제한 없음, 틀린 유형 반복 출제 |
|
||
|
||
## 화면 흐름
|
||
|
||
```
|
||
시작 화면 → 문제 유형 선택 → 게임 모드 선택 → 문제 풀이 → 결과 및 기록
|
||
```
|
||
|
||
---
|
||
|
||
## 현재 구현 상태
|
||
|
||
- 시작 화면에서 문제 수를 5개 또는 10개로 선택한 뒤 `/play` 풀이 화면으로 이동할 수 있습니다.
|
||
- 문제 수 기본값은 10개이며, `/play?count=5` 또는 `/play?count=10`으로 선택값을 전달합니다.
|
||
- 문제와 정답 수식은 KaTeX로 렌더링합니다.
|
||
- 진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
|
||
- 정답·오답 피드백은 각 항의 `계산식 = 내가 입력한 답` 형식으로 표시합니다.
|
||
- 정답 항목은 정답 색상 박스와 `○` 표시를 사용합니다.
|
||
- 오답 항목은 오답 색상 박스, 붉은색 입력값, `×`, 굵은 정답값을 함께 표시합니다.
|
||
- 결과 화면은 지금까지 푼 문제를 `문제 = 내가 입력한 답` 형식으로 다시 보여주고, 정답·오답 표시 규칙을 피드백 화면과 공유합니다.
|
||
- 키보드 흐름을 지원합니다.
|
||
- 모든 항은 하나의 input group에서 순서대로 입력
|
||
- 첫째 항 Enter → 같은 input group이 둘째 항 입력으로 전환
|
||
- 둘째 항 Enter → 제출
|
||
- 피드백 화면 → 다음 문제/결과 보기 버튼에 focus
|
||
- 다음 문제 이동 후 → input에 focus
|
||
- 결과 화면 → 다시 시작 버튼에 focus
|
||
- input group 아래에는 각 항의 입력값 버튼이 표시됩니다. 비어 있는 항은 `?`로 표시하고, 버튼을 누르면 해당 항을 초기화한 뒤 다시 입력합니다.
|
||
- 모바일 화면에서는 `-/+`와 `↵` 보조 버튼을 표시하고, input focus 후 가상 키보드가 올라오면 문제 수식이 화면 상단에 오도록 스크롤 위치를 조정합니다.
|
||
|
||
---
|
||
|
||
## 시작하기
|
||
|
||
### 사전 요구사항
|
||
|
||
- 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)/ # 게임 화면 라우트 그룹
|
||
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 시 자동 빌드·배포
|