레이어	기술
프레임워크	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)

문제 유형

괄호 음수 분배 — 괄호 앞 음수 곱셈 시 괄호 내 부호 변경
- 예: -2 × (3 - 6)
이항 부호 변경 — 등식의 항을 이항할 때 부호 반전
- 예: 3x - 5y + 8 = -2x + 2y - 2

게임 모드

모드	설명
스피드 퀴즈	제한 시간 내 최대 문제 풀기, Redis Sorted Set 기반 실시간 점수판
일반 풀이	시간 제한 없음, 틀린 유형 반복 출제

화면 흐름

학습 내용 선택 → 숫자 괄호 준비 → 문제 풀이 → 결과 및 기록

현재 구현 상태

시작 화면(/)에서 학습 내용을 선택합니다.
- 숫자 괄호 풀기는 활성 상태이며 /number-parentheses 준비 화면으로 이동합니다.
- 분수 괄호 풀기, 실수 괄호 풀기, 미지수 괄호 풀기는 준비 중 항목으로 비활성화되어 있습니다.
숫자 괄호 준비 화면(/number-parentheses)에서 문제 수를 5개 또는 10개로 선택한 뒤 /play 풀이 화면으로 이동할 수 있습니다.
문제 수 기본값은 10개이며, /play?count=5 또는 /play?count=10으로 선택값을 전달합니다.
숫자 괄호 준비 화면의 괄호 종류는 현재 ()만 선택 가능하고 {}, []는 비활성화되어 있습니다.
문제와 정답 수식은 KaTeX로 렌더링합니다.
진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
정답·오답 피드백은 각 항의 계산식 = 내가 입력한 답 형식으로 표시합니다.
- 정답 항목은 정답 색상 박스와 ○ 표시를 사용합니다.
- 오답 항목은 오답 색상 박스, 붉은색 입력값, ×, 굵은 정답값을 함께 표시합니다.
결과 화면은 지금까지 푼 문제를 문제 = 내가 입력한 답 형식으로 다시 보여주고, 정답·오답 표시 규칙을 피드백 화면과 공유합니다.
키보드 흐름을 지원합니다.
- 모든 항은 하나의 input에서 순서대로 입력
- 첫째 항 Enter → 같은 input이 둘째 항 입력으로 전환
- 둘째 항 Enter → 제출
- 피드백 화면 → 다음 문제/결과 보기 버튼에 focus
- 다음 문제 이동 후 → input에 focus
- 결과 화면 → 다시 시작 버튼에 focus
input 아래에는 각 항의 입력값 버튼이 표시됩니다. 비어 있는 항은 ?로 표시하고, 버튼을 누르면 해당 항을 초기화한 뒤 다시 입력합니다.
터치 기반 입력 환경에서는 input focus 후 커스텀 숫자 키패드를 표시합니다.
- 키패드는 숫자, +/-, ., ⌫, ↵ 버튼을 제공합니다.
- ↵는 첫째 항에서 둘째 항으로 이동하고, 둘째 항에서 제출합니다.
- 마우스/트랙패드처럼 hover 가능한 정밀 포인터가 있는 환경은 물리 키보드 사용 환경으로 간주해 키패드를 숨깁니다.
입력 중에는 -, 1. 같은 임시 값을 허용하지만, 제출 시에는 정상적인 양의 실수 또는 음의 실수 표현만 통과합니다.

시작하기

사전 요구사항

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

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

프로젝트 구조

app/                        # Next.js App Router 루트
  (game)/                   # 게임 화면 라우트 그룹
    number-parentheses/     # 숫자 괄호 준비 화면
    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 워크플로우

다음 확장 방향

분수 괄호, 실수 괄호, 미지수 괄호는 각 문제 생성 엔진이 준비되면 시작 화면에서 활성화합니다.
{}, [] 괄호 종류는 생성 엔진과 상태/URL 파라미터 연동이 준비된 뒤 숫자 괄호 준비 화면에서 활성화합니다.

배포

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

README.md Unescape Escape

Math Quiz

기술 스택

문제 유형

게임 모드

화면 흐름

현재 구현 상태

시작하기

사전 요구사항

설치

환경변수 설정

개발 서버 실행

빌드

프로젝트 구조

다음 확장 방향

배포

README.md