From 1ed0611b9dac547011bc4d01a0bb261f5eadeac1 Mon Sep 17 00:00:00 2001
From: jisangs <jisangs@gmail.com>
Date: Fri, 22 May 2026 16:14:00 +0900
Subject: [PATCH] =?UTF-8?q?README.md=20=ED=8C=8C=EC=9D=BC=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3d82595
--- /dev/null
+++ b/README.md
@@ -0,0 +1,127 @@
+# 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 시 자동 빌드·배포