jisangs/math-quiz

Fork 0

Files

T

jisangs f3d051cdd1 미지수 괄호 문제 풀이 추가

2026-05-29 23:47:10 +09:00

5.9 KiB

Raw Blame History

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` → `/play`)

준비 화면에서 문제 수 5 / 10을 선택하고 연습을 시작합니다. 기본값은 10.
괄호 종류는 현재 ()만 선택 가능하고 {}, []는 비활성화되어 있습니다.
풀이 화면에서 두 항을 직접 숫자로 입력합니다.
- 모든 항은 하나의 input에서 순서대로 입력하며, 첫째 항 Enter → 둘째 항 전환, 둘째 항 Enter → 제출.
- input 아래 항 버튼 그룹에서 현재 입력 중인 항을 표시하고, 버튼을 누르면 해당 항을 초기화해 다시 입력합니다.
- 터치 환경에서는 커스텀 숫자 키패드(숫자, +/-, ., ⌫, ↵)가 표시되며, 정밀 포인터가 있는 환경(마우스/트랙패드)에서는 숨깁니다.

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

준비 화면 구성은 숫자 괄호와 동일합니다.
풀이 화면에서 두 항을 보기 중에서 선택합니다.
- 각 항의 보기는 정답 계수의 절대값을 기준으로 음수/양수 두 개를 제공합니다.
- 첫째 항 선택 후 자동으로 둘째 항 보기로 focus가 이동합니다.
- 두 항 선택 완료 후 정답 확인 버튼이 활성화되며 버튼에 focus가 이동합니다.

시작하기

사전 요구사항

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/           # 숫자 괄호 준비 화면
    variable-parentheses/         # 미지수 괄호 준비 화면
      play/                       # 미지수 괄호 풀이 화면
    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 시 자동 빌드·배포

5.9 KiB Raw Blame History Unescape Escape