plan 생성

docs/plan/project-plan-claudecode.md

@@ -0,0 +1,339 @@
+# choco-admin 프로젝트 계획서
+
+## 1. 프로젝트 개요
+
+| 항목 | 내용 |
+|---|---|
+| 서비스명 | choco-admin |
+| 목적 | chocomae 웹 서비스(mouse-typing)의 관리자 기능을 독립 웹 서비스로 분리 |
+| 기존 서비스 경로 | `/Users/jisangs/work/jinaju/git/web/mouse-typing` |
+| 신규 서비스 경로 | `/Users/jisangs/work/jinaju/git/web/choco-admin` |
+| 사용 DB | 기존 chocomae DB (MariaDB 10.11.13) 그대로 사용 |
+
+---
+
+## 2. 기술 스택
+
+| 구분 | 기술 |
+|---|---|
+| 런타임 | Node.js (LTS 버전) |
+| 프레임워크 | Next.js 15 (App Router) |
+| 언어 | TypeScript |
+| DB 클라이언트 | `mysql2` (MariaDB 호환) |
+| 인증 | NextAuth.js v5 (기존 `admin` 테이블 활용) |
+| 환경변수 관리 | `.env.local` / `.env.production` |
+
+---
+
+## 3. CSS Framework 추천
+
+관리자 화면은 주로 표(Table)와 폼(Form) 중심이므로, 빠른 개발과 유지보수성을 모두 고려한 3가지를 추천합니다.
+
+### 3-1. Tailwind CSS + shadcn/ui ⭐ 추천
+
+- **Tailwind CSS**: 유틸리티 클래스 기반으로 CSS 파일을 직접 작성할 일이 거의 없음
+- **shadcn/ui**: Tailwind 기반의 복사-붙여넣기형 컴포넌트 라이브러리. Button, Table, Dialog, Form 등 관리자 UI에 필요한 컴포넌트가 이미 갖춰져 있음
+- **장점**: Next.js App Router와 궁합이 뛰어남. 번들 사이즈가 작고, 컴포넌트 코드를 직접 소유하므로 커스터마이징이 자유로움
+- **단점**: 초기 세팅이 다소 필요함
+
+### 3-2. Ant Design (antd)
+
+- React 생태계에서 오랫동안 검증된 전통적인 관리자 UI 라이브러리
+- Table, Form, Modal, DatePicker 등 관리자 페이지에 필요한 컴포넌트가 모두 내장되어 있음
+- **장점**: 별도 CSS 작업 없이 완성도 높은 UI를 빠르게 구성 가능
+- **단점**: 번들 사이즈가 크고, 기본 디자인 톤에서 벗어나는 커스터마이징이 어려움
+
+### 3-3. Mantine
+
+- shadcn/ui보다 더 완결된 형태의 컴포넌트 세트 제공 (100개 이상)
+- 자체 훅(hook) 라이브러리도 포함되어 있어 복잡한 상태 관리 없이 폼·테이블 구현 가능
+- **장점**: 문서가 잘 정리되어 있고 TypeScript 지원이 뛰어남
+- **단점**: antd처럼 디자인 자유도가 shadcn/ui보다 낮음
+
+> **최종 추천: Tailwind CSS + shadcn/ui**
+> Next.js 공식 생태계와 가장 잘 맞고, 장기적인 유지보수 측면에서 가장 유리합니다.
+
+---
+
+## 4. Table 라이브러리 추천
+
+관리자 화면은 목록 조회, 검색, 정렬, 페이지네이션, 인라인 액션 버튼이 핵심이므로 아래 3가지를 추천합니다.
+
+### 4-1. TanStack Table (React Table v8) ⭐ 추천
+
+- Headless 방식(스타일 미포함)으로, Tailwind/shadcn과 조합해 완전한 커스터마이징 가능
+- 정렬, 필터, 페이지네이션, 행 선택, 컬럼 고정 등 필요한 기능을 필요한 만큼만 추가
+- **shadcn/ui DataTable**: TanStack Table + shadcn 조합의 공식 예제가 제공되어 빠른 시작 가능
+- **장점**: 번들 사이즈 최소, 자유도 최대, Next.js App Router 완벽 호환
+- **단점**: 기능을 직접 조립해야 하므로 초기 설정 비용이 있음
+
+### 4-2. AG Grid (Community Edition)
+
+- 대용량 데이터에 특화된 고성능 그리드 라이브러리
+- 정렬, 필터, 그룹핑, 엑셀 내보내기, 인라인 편집 등 풍부한 기능이 내장
+- 무료 Community Edition으로도 관리자 기능 구현에 충분
+- **장점**: 기능이 가장 풍부하고 성능이 뛰어남
+- **단점**: 번들 사이즈가 크고, 스타일 커스터마이징에 별도 CSS 작업이 필요
+
+### 4-3. MUI DataGrid (Free tier)
+
+- Material UI 기반의 데이터 그리드
+- 정렬, 필터, 페이지네이션, 컬럼 재배치가 내장
+- **장점**: Material UI 생태계와 자연스럽게 통합, 사용법이 직관적
+- **단점**: Tailwind와 함께 사용 시 스타일 충돌 이슈가 발생할 수 있음. 고급 기능은 Pro 유료 플랜 필요
+
+> **최종 추천: TanStack Table + shadcn/ui DataTable**
+> shadcn/ui와 세트로 사용하면 코드 통일성이 높고, 필요한 기능만 붙일 수 있어 관리 부담이 적습니다.
+
+---
+
+## 5. 개발 환경 및 배포 환경
+
+### 5-1. 개발 환경
+
+| 항목 | 내용 |
+|---|---|
+| 플랫폼 | Synology NAS (DS920+, 20GB RAM) - Docker |
+| DB (개발) | localhost MariaDB |
+| 실행 방법 | `docker compose up` |
+| 포트 | 3001 (기존 mouse-typing과 충돌 방지) |
+
+### 5-2. 서비스 환경
+
+| 항목 | 내용 |
+|---|---|
+| 플랫폼 | Synology NAS (DS920+) - Docker |
+| DB (서비스) | AWS EC2 MariaDB (chocomae 서비스와 동일 인스턴스) |
+| 접근 방식 | NAS에서 AWS EC2 DB에 직접 연결 (보안그룹 인바운드 규칙에 NAS 외부 IP 허용 필요) |
+
+### 5-3. docker-compose.yml 구성 계획
+
+```yaml
+# docker-compose.yml (개발용)
+services:
+  choco-admin:
+    build: .
+    ports:
+      - "3001:3000"
+    environment:
+      - NODE_ENV=development
+      - DB_HOST=host.docker.internal
+      - DB_PORT=3306
+      - DB_NAME=chocomae
+      - DB_USER=...
+      - DB_PASS=...
+    volumes:
+      - .:/app
+      - /app/node_modules
+      - /app/.next
+```
+
+### 5-4. Dockerfile 계획
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+CMD ["npm", "start"]
+```
+
+---
+
+## 6. 데이터베이스 주요 테이블 정리
+
+스키마: [`docs/db-reference/schema.sql`](./db-reference/schema.sql)
+
+| 테이블 | 설명 | 주요 컬럼 |
+|---|---|---|
+| `maestro` | 마에스트로(강사) 계정 | `MaestroID`, `Name`, `Email`, `AccountType`, `ActivateStatus`, `AvailableActivateDateTime` |
+| `maestro_extension` | 마에스트로 연장 신청 | `MaestroExtensionID`, `MaestroID`, `AccountType`, `RequestedDateTime`, `Status` |
+| `maestro_upgrade` | 마에스트로 업그레이드 신청 | `MaestroUpgradeID`, `MaestroID`, `RegisteredAccountType`, `RequestedAccountType`, `RequestedDateTime`, `Status` |
+| `maestro_log` | 마에스트로 처리 이력 | `MaestroLogID`, `MaestroID`, `Type`, `LogDateTime`, `Remark` |
+| `admin` | 관리자 계정 | `AdminID`, `Name`, `Password`, `Email`, `AccountType`, `ActivateStatus` |
+| `player` | 학생 계정 | `PlayerID`, `MaestroID`, `Name`, `EnterCode` |
+
+### AccountType 코드표
+
+| 값 | 의미 |
+|---|---|
+| 1 | 20명 (1만원) |
+| 2 | 50명 (2만원) |
+| 3 | 100명 (3만원) |
+| 4 | 500명 (4만원) |
+| 5 | 1,000명 (5만원) |
+
+### ActivateStatus 코드표 (maestro)
+
+| 값 | 의미 |
+|---|---|
+| 0 | 미승인 |
+| 1 | 체험 |
+| 2 | 활성화 |
+| 100 | 등록취소 |
+
+### Status 코드표 (maestro_extension / maestro_upgrade)
+
+| 값 | 의미 |
+|---|---|
+| 1 | 요청 |
+| 2 | 취소 |
+| 3 | 연장/업그레이드 적용 |
+
+---
+
+## 7. 주요 화면 목록 및 API 설계
+
+### 7-1. 화면 구조 (Next.js App Router)
+
+```
+app/
+├── (auth)/
+│   └── login/              # 관리자 로그인
+├── (admin)/
+│   ├── layout.tsx          # 공통 사이드바 + 헤더
+│   ├── maestro/
+│   │   ├── page.tsx        # 마에스트로 전체 목록
+│   │   └── [id]/
+│   │       └── page.tsx    # 마에스트로 상세 정보
+│   ├── extension/
+│   │   └── page.tsx        # 연장 신청 목록 + 승인/취소
+│   └── upgrade/
+│       └── page.tsx        # 업그레이드 신청 목록 + 승인/거절
+└── api/
+    ├── auth/[...nextauth]/
+    ├── maestro/
+    │   ├── route.ts        # GET: 목록 조회
+    │   └── [id]/route.ts   # GET: 상세, PATCH: 상태 변경
+    ├── extension/
+    │   ├── route.ts        # GET: 목록 조회
+    │   └── [id]/route.ts   # PATCH: 승인/취소
+    └── upgrade/
+        ├── route.ts        # GET: 목록 조회
+        └── [id]/route.ts   # PATCH: 승인/거절
+```
+
+### 7-2. 화면별 기능 명세
+
+#### [1] 마에스트로 전체 목록 (`/maestro`)
+
+- 전체 마에스트로 목록 표시
+- 검색: 이름, 이메일
+- 필터: ActivateStatus (미승인 / 체험 / 활성화 / 등록취소)
+- 정렬: 가입일, 만료일
+- 컬럼: ID / 이름 / 이메일 / 계정유형 / 상태 / 인원수 / 사용가능일 / 상세보기
+
+#### [2] 마에스트로 상세 정보 (`/maestro/[id]`)
+
+- 기본 정보 (이름, 이메일, 계정 유형, 상태, 만료일)
+- 플레이어(학생) 목록
+- 연장 신청 이력
+- 업그레이드 신청 이력
+- 관리자 처리 로그
+
+#### [3] 연장 신청 목록 (`/extension`)
+
+- 연장 신청 목록 표시 (기본: Status=1 요청 건만)
+- 필터: 상태 (요청 / 취소 / 적용)
+- 컬럼: 신청ID / 마에스트로명 / 계정유형 / 신청일시 / 상태 / 승인버튼 / 취소버튼
+- 승인 시: `maestro.ActivateStatus = 2`, `maestro.AvailableActivateDateTime` 1년 연장, `maestro_extension.Status = 3`
+- 취소 시: `maestro_extension.Status = 2`
+
+#### [4] 업그레이드 신청 목록 (`/upgrade`)
+
+- 업그레이드 신청 목록 표시 (기본: Status=1 요청 건만)
+- 필터: 상태 (요청 / 취소 / 적용)
+- 컬럼: 신청ID / 마에스트로명 / 현재등급 / 요청등급 / 신청일시 / 상태 / 승인버튼 / 거절버튼
+- 승인 시: `maestro.AccountType` 변경, `maestro_upgrade.Status = 3`
+- 거절 시: `maestro_upgrade.Status = 2`
+
+---
+
+## 8. 개발 단계 계획
+
+### Phase 1. 프로젝트 초기화 및 환경 구성
+
+- [ ] Next.js 15 + TypeScript 프로젝트 생성
+- [ ] Tailwind CSS + shadcn/ui 설치 및 설정
+- [ ] TanStack Table 설치
+- [ ] mysql2 설치 및 DB 연결 유틸리티 작성
+- [ ] docker-compose.yml 작성 (개발용)
+- [ ] `.env.local` 환경변수 구성
+- [ ] NextAuth.js v5 설치 및 `admin` 테이블 기반 로그인 구현
+
+### Phase 2. 공통 레이아웃 및 인증
+
+- [ ] 로그인 페이지 (`/login`)
+- [ ] 인증 미들웨어 (비로그인 시 `/login` 리다이렉트)
+- [ ] 공통 레이아웃 (사이드바 네비게이션, 상단 헤더)
+
+### Phase 3. 마에스트로 관리
+
+- [ ] 마에스트로 전체 목록 페이지 + API
+- [ ] 마에스트로 상세 정보 페이지 + API
+
+### Phase 4. 연장 신청 관리
+
+- [ ] 연장 신청 목록 페이지 + API
+- [ ] 연장 승인 / 취소 기능 + API
+
+### Phase 5. 업그레이드 신청 관리
+
+- [ ] 업그레이드 신청 목록 페이지 + API
+- [ ] 업그레이드 승인 / 거절 기능 + API
+
+### Phase 6. 배포 환경 구성
+
+- [ ] Dockerfile (프로덕션용) 작성
+- [ ] docker-compose.prod.yml 작성 (Synology NAS용)
+- [ ] AWS EC2 DB 보안그룹 인바운드 설정 (NAS 외부 IP 허용)
+- [ ] Synology NAS Container Manager에서 배포 테스트
+
+---
+
+## 9. 디렉토리 구조 (목표)
+
+```
+choco-admin/
+├── app/
+│   ├── (auth)/
+│   │   └── login/
+│   ├── (admin)/
+│   │   ├── layout.tsx
+│   │   ├── maestro/
+│   │   ├── extension/
+│   │   └── upgrade/
+│   └── api/
+├── components/
+│   ├── ui/                 # shadcn/ui 컴포넌트
+│   ├── data-table/         # TanStack Table 공통 컴포넌트
+│   └── layout/             # 사이드바, 헤더
+├── lib/
+│   ├── db.ts               # mysql2 연결 풀
+│   └── utils.ts
+├── types/
+│   └── index.ts            # DB 타입 정의
+├── docs/
+│   └── db-reference/
+│       └── schema.sql
+├── docker-compose.yml
+├── docker-compose.prod.yml
+├── Dockerfile
+├── .env.local              # (gitignore)
+└── .env.production         # (gitignore)
+```
+
+---
+
+## 10. 보안 고려사항
+
+- 관리자 전용 서비스이므로 외부 노출을 최소화 (NAS 내부 포트 또는 VPN 기반 접근 권장)
+- `admin.Password`는 해시 검증 방식으로 NextAuth 연동 (기존 암호화 방식 확인 필요)
+- DB 연결 정보는 `.env` 파일로 관리하며 Git에 포함하지 않음
+- AWS EC2 보안그룹에서 MariaDB 포트(3306)를 NAS IP로만 허용
+
+---
+
+*작성일: 2026-05-26*

docs/plan/project-plan-codex.md

@@ -0,0 +1,501 @@
+# choco-admin 개발 작업 계획
+
+## 1. 프로젝트 개요
+
+`choco-admin`은 기존 `chocomae` 웹 서비스의 관리자 페이지와 관리자 기능만 독립 분리하는 신규 관리자 웹 서비스이다.
+
+- 기존 서비스명: `chocomae`
+- 기존 서비스 개발 디렉토리: `/Users/jisangs/work/jinaju/git/web/mouse-typing`
+- 신규 서비스명: `choco-admin`
+- 신규 서비스 개발 디렉토리: `/Users/jisangs/work/jinaju/git/web/choco-admin`
+- 개발 목표: 기존 `mouse-typing` 서비스의 관리자 기능을 Next.js 기반 독립 서비스로 재구성
+- 기존 운영 환경: AWS EC2 `t3a.medium` 인스턴스 1개
+- 신규 개발/운영 플랫폼: Synology NAS Docker
+- 보유 NAS: Synology DS920+, RAM 20GB
+
+## 2. 핵심 개발 방향
+
+1. 기존 `chocomae` DB를 그대로 사용한다.
+2. 관리자 UI와 서버 로직만 신규 Next.js 서비스로 분리한다.
+3. 운영 DB 스키마를 임의 변경하지 않고, 기존 테이블과 상태값을 우선 존중한다.
+4. 관리자 액션은 반드시 서버 사이드에서 권한 검증, 트랜잭션, 로그 기록을 거친다.
+5. Synology NAS Docker에서 개발과 운영을 모두 재현 가능하게 구성한다.
+
+## 3. 기술 스택 제안
+
+### 기본 스택
+
+- Runtime: Node.js LTS
+- Framework: Next.js App Router
+- Language: TypeScript
+- Database: MariaDB
+- DB Access: Prisma 또는 Drizzle ORM
+- Auth: NextAuth/Auth.js 또는 자체 세션 기반 인증
+- Validation: Zod
+- Package Manager: pnpm
+- Container: Docker, Docker Compose
+
+### DB 접근 방식 추천
+
+1. Prisma
+   - 장점: 타입 안정성, 마이그레이션/스키마 관리 경험이 좋고 개발 속도가 빠름
+   - 주의: 기존 MariaDB 스키마를 introspection해서 사용하는 방식이 적합함
+
+2. Drizzle ORM
+   - 장점: SQL에 가까운 제어, 가벼움, 서버 액션/API Route와 잘 맞음
+   - 주의: 기존 DB 테이블 정의를 직접 코드로 옮기는 작업이 필요함
+
+권장안: 초기 개발 생산성과 유지보수를 고려하면 Prisma를 우선 검토하고, 기존 DB 쿼리를 세밀하게 제어해야 하는 구간만 raw SQL을 병행한다.
+
+## 4. CSS Framework 추천
+
+관리자 서비스는 표, 검색, 필터, 상세 보기, 승인/거절 액션이 중심이므로 화려한 랜딩 페이지보다 유지보수성과 일관성이 중요하다.
+
+### 1순위: Tailwind CSS + shadcn/ui
+
+- 장점: Next.js와 궁합이 좋고, 관리자 화면에 필요한 버튼, 입력, 다이얼로그, 탭, 폼 구성이 빠름
+- 장점: 컴포넌트 코드를 프로젝트 안에서 직접 소유하므로 장기 유지보수에 유리함
+- 단점: Tailwind 클래스에 익숙해지는 시간이 필요함
+- 추천 이유: `choco-admin`처럼 작은 팀/개인 프로젝트에서 빠르게 만들고 나중에 고치기 좋음
+
+### 2순위: Mantine
+
+- 장점: 컴포넌트가 풍부하고 Form, Modal, Table 주변 UI를 빠르게 만들기 좋음
+- 장점: 테마 시스템과 훅이 잘 갖춰져 있음
+- 단점: 디자인을 많이 커스터마이징하면 프레임워크 스타일에 묶일 수 있음
+- 추천 이유: 관리자 도구를 빠르게 안정적인 UI로 완성하기 좋음
+
+### 3순위: Chakra UI
+
+- 장점: 접근성, 컴포넌트 API, 테마 관리가 안정적임
+- 장점: Next.js 프로젝트에서 사용 사례가 많음
+- 단점: 대량 데이터 테이블은 별도 라이브러리 조합이 필요함
+- 추천 이유: 익숙한 컴포넌트 기반 개발을 선호할 때 적합함
+
+최종 권장안: `Tailwind CSS + shadcn/ui`를 기본 UI 프레임워크로 사용한다.
+
+## 5. Table 라이브러리 추천
+
+관리자 화면은 마에스트로 목록, 연장 신청, 업그레이드 신청처럼 대부분 표 기반으로 운영되므로 정렬, 필터, 검색, 페이지네이션, 행 선택, 컬럼 표시 제어, 액션 버튼 확장이 쉬워야 한다.
+
+### 1순위: TanStack Table
+
+- 장점: headless 방식이라 UI 프레임워크와 자유롭게 결합 가능
+- 장점: 서버 사이드 페이지네이션, 정렬, 필터링을 구현하기 좋음
+- 장점: shadcn/ui의 Data Table 패턴과 잘 맞음
+- 단점: 직접 조립해야 하는 부분이 있어 초기 구현량이 있음
+- 추천 이유: 관리자 기능이 늘어날 가능성이 높은 `choco-admin`에 가장 유연함
+
+### 2순위: AG Grid Community
+
+- 장점: 엑셀 같은 고급 그리드 기능이 강함
+- 장점: 컬럼 리사이즈, 고정 컬럼, 복잡한 필터 등 고급 기능이 풍부함
+- 단점: UI가 무겁고, 일부 기능은 Enterprise 라이선스가 필요함
+- 추천 이유: 향후 대량 데이터 운영 도구가 필요해질 때 적합함
+
+### 3순위: Mantine React Table
+
+- 장점: Mantine을 CSS/UI 프레임워크로 선택할 경우 통합 경험이 좋음
+- 장점: TanStack Table 기반이라 기능 확장성이 좋음
+- 단점: Mantine 생태계에 묶임
+- 추천 이유: Mantine을 선택하는 경우 가장 빠르게 관리자 표를 만들 수 있음
+
+최종 권장안: `TanStack Table + shadcn/ui Data Table` 조합을 사용한다.
+
+## 6. DB 기준 관리자 대상 테이블
+
+스키마 파일: `/Users/jisangs/work/jinaju/git/web/choco-admin/docs/db-reference/schema.sql`
+
+### 주요 테이블
+
+- `admin`: 관리자 계정
+- `maestro`: 마에스트로 계정
+- `maestro_extension`: 마에스트로 연장 신청
+- `maestro_upgrade`: 마에스트로 업그레이드 신청
+- `maestro_log`: 마에스트로 관련 처리 로그
+- `player`: 마에스트로에 속한 학생/플레이어
+
+### 주요 상태값
+
+`maestro.ActivateStatus`
+
+- `0`: 미승인
+- `1`: 체험
+- `2`: 활성화
+- `100`: 등록취소
+
+`maestro.AccountType`
+
+- `1`: 20명
+- `2`: 50명
+- `3`: 100명
+- `4`: 500명
+- `5`: 1000명
+
+`maestro_extension.Status`
+
+- `1`: 요청
+- `2`: 취소
+- `3`: 연장 적용
+
+`maestro_upgrade.Status`
+
+- `1`: 요청
+- `2`: 취소
+- `3`: 업그레이드 적용
+
+## 7. 주요 관리자 화면 계획
+
+### 7.1 공통 레이아웃
+
+- 로그인 화면
+- 좌측 사이드바
+- 상단 관리자 정보 영역
+- 공통 검색/필터 패턴
+- 공통 확인 다이얼로그
+- 처리 성공/실패 토스트
+- 접근 권한 없는 경우 안내 화면
+
+### 7.2 마에스트로 전체 목록
+
+목표: 전체 마에스트로 계정을 검색, 필터링, 확인할 수 있는 운영 화면을 만든다.
+
+주요 기능:
+
+- 전체 목록 조회
+- 이름, 이메일, `MaestroID` 검색
+- 계정 종류 필터
+- 활성 상태 필터
+- 가입/약관 동의/사용 가능 기간 기준 정렬
+- 학생 수 표시
+- 상세 화면 이동
+
+표 주요 컬럼:
+
+- `MaestroID`
+- `Name`
+- `Email`
+- `AccountType`
+- `ActivateStatus`
+- `PlayerCount`
+- `AvailableActivateDateTime`
+- `AcceptClausesDateTime`
+- `AllowEditEnterCode`
+
+### 7.3 마에스트로 상세 정보 보기
+
+목표: 특정 마에스트로의 계정 상태와 관련 신청 이력을 한 화면에서 확인한다.
+
+주요 기능:
+
+- 기본 계정 정보
+- 현재 계정 종류/활성 상태 표시
+- 학생 수 및 플레이어 목록 요약
+- 최근 연장 신청 이력
+- 최근 업그레이드 신청 이력
+- 처리 로그 표시
+
+확장 후보 기능:
+
+- 계정 상태 수동 변경
+- 학생 목록 상세 조회
+- 입장번호 변경 허용 여부 수정
+
+단, 확장 후보 기능은 기존 관리자 기능과 운영 정책 확인 후 별도 구현한다.
+
+### 7.4 마에스트로 연장 신청 목록
+
+목표: `maestro_extension`의 연장 요청을 검토하고 승인 또는 취소 처리한다.
+
+주요 기능:
+
+- 연장 신청 목록 조회
+- 요청 상태별 필터
+- 요청일 기준 정렬
+- 마에스트로 정보 함께 표시
+- 연장 승인
+- 연장 취소
+- 처리 후 `maestro_log` 기록
+
+승인 처리 초안:
+
+1. `maestro_extension.Status = 1`인지 확인한다.
+2. 트랜잭션을 시작한다.
+3. `maestro_extension.Status`를 `3`으로 변경한다.
+4. `maestro.AccountType`, `AvailableActivateDateTime`, `ActivateStatus` 갱신 규칙을 기존 서비스에서 확인해 동일하게 적용한다.
+5. `maestro_log`에 처리 기록을 남긴다.
+6. 트랜잭션을 커밋한다.
+
+취소 처리 초안:
+
+1. `maestro_extension.Status = 1`인지 확인한다.
+2. 트랜잭션을 시작한다.
+3. `maestro_extension.Status`를 `2`로 변경한다.
+4. `maestro_log`에 취소 기록을 남긴다.
+5. 트랜잭션을 커밋한다.
+
+### 7.5 마에스트로 업그레이드 신청 목록
+
+목표: `maestro_upgrade`의 업그레이드 요청을 검토하고 승인 또는 거절 처리한다.
+
+주요 기능:
+
+- 업그레이드 신청 목록 조회
+- 요청 상태별 필터
+- 현재 계정 종류와 요청 계정 종류 비교 표시
+- 요청일 기준 정렬
+- 업그레이드 승인
+- 업그레이드 거절
+- 처리 후 `maestro_log` 기록
+
+승인 처리 초안:
+
+1. `maestro_upgrade.Status = 1`인지 확인한다.
+2. 트랜잭션을 시작한다.
+3. `maestro_upgrade.Status`를 `3`으로 변경한다.
+4. `maestro.AccountType`을 `RequestedAccountType`으로 변경한다.
+5. 필요 시 `PlayerCount` 정책을 기존 서비스에서 확인해 반영한다.
+6. `maestro_log`에 처리 기록을 남긴다.
+7. 트랜잭션을 커밋한다.
+
+거절 처리 초안:
+
+1. `maestro_upgrade.Status = 1`인지 확인한다.
+2. 트랜잭션을 시작한다.
+3. `maestro_upgrade.Status`를 `2`로 변경한다.
+4. `maestro_log`에 거절 기록을 남긴다.
+5. 트랜잭션을 커밋한다.
+
+## 8. 애플리케이션 구조 제안
+
+```text
+choco-admin/
+  app/
+    login/
+    maestros/
+      page.tsx
+      [maestroId]/
+        page.tsx
+    extension-requests/
+      page.tsx
+    upgrade-requests/
+      page.tsx
+    api/
+  components/
+    layout/
+    data-table/
+    forms/
+    dialogs/
+  lib/
+    auth/
+    db/
+    validators/
+    constants/
+  docs/
+    db-reference/
+      schema.sql
+    project-plan.md
+  prisma/
+    schema.prisma
+  docker/
+  docker-compose.yml
+  Dockerfile
+```
+
+## 9. Docker 개발/운영 계획
+
+### 개발 환경
+
+- Synology NAS Docker에서 Next.js 컨테이너 실행
+- 개발 DB는 `localhost` MariaDB 사용
+- `.env.local`로 DB 접속 정보 관리
+- 개발 DB는 운영 DB 덤프에서 민감 정보를 제거한 샘플 데이터 사용 권장
+
+### 운영 환경
+
+- Synology NAS Docker에서 `choco-admin` 컨테이너 실행
+- 운영 DB는 기존 AWS EC2 MariaDB에 접속
+- AWS 보안 그룹에서 Synology NAS 공인 IP만 MariaDB 접속 허용
+- DB 계정은 관리자 서비스 전용 계정으로 분리
+- 최소 권한 원칙 적용
+- 운영 배포 시 환경변수는 Synology Container Manager 또는 `.env.production`으로 관리
+
+### Docker 구성 초안
+
+- `Dockerfile`: Next.js production build
+- `docker-compose.yml`: app service 정의
+- `healthcheck`: HTTP 상태 확인 엔드포인트 사용
+- `restart: unless-stopped`
+- 로그는 Docker 기본 로그 또는 Synology 로그 수집 방식 사용
+
+## 10. 보안 계획
+
+1. 관리자 로그인은 서버 세션 기반으로 구현한다.
+2. 관리자 비밀번호 저장 방식은 기존 `admin.Password` 구조를 확인한 뒤 개선 가능성을 검토한다.
+3. 운영 DB 접속 정보는 저장소에 커밋하지 않는다.
+4. 승인/취소/거절 같은 변경 액션은 CSRF 또는 서버 액션 보호를 적용한다.
+5. 관리자 액션은 `maestro_log`에 기록한다.
+6. 운영 DB 직접 수정 기능은 최소화한다.
+7. 승인/거절 API는 중복 처리 방지를 위해 현재 상태를 조건으로 검사한다.
+8. 모든 변경 작업은 트랜잭션으로 처리한다.
+
+## 11. 개발 단계별 작업 계획
+
+### Phase 0. 기존 관리자 기능 조사
+
+- 기존 `mouse-typing` 코드에서 관리자 라우트와 처리 로직 조사
+- 연장 승인 시 `AvailableActivateDateTime` 계산 방식 확인
+- 업그레이드 승인 시 `PlayerCount`와 `AccountType` 처리 방식 확인
+- 기존 `admin.Password` 검증 방식 확인
+- 기존 로그 기록 형식 확인
+
+완료 기준:
+
+- 기존 관리자 처리 규칙을 문서화한다.
+- 신규 서비스에서 재현해야 할 비즈니스 규칙을 확정한다.
+
+### Phase 1. 프로젝트 초기화
+
+- Next.js + TypeScript 프로젝트 생성
+- ESLint, Prettier 설정
+- Tailwind CSS + shadcn/ui 설정
+- 기본 레이아웃 구성
+- 환경변수 구조 정의
+- Dockerfile, docker-compose 초안 작성
+
+완료 기준:
+
+- 로컬 또는 Synology Docker에서 기본 페이지가 실행된다.
+
+### Phase 2. DB 연결 및 타입 구성
+
+- MariaDB 연결 설정
+- Prisma introspection 또는 Drizzle schema 작성
+- DB 연결 헬퍼 구현
+- 상태값 상수화
+- 공통 날짜/계정 종류 표시 유틸 작성
+
+완료 기준:
+
+- 개발 DB에서 `maestro`, `maestro_extension`, `maestro_upgrade` 조회가 가능하다.
+
+### Phase 3. 인증과 관리자 세션
+
+- 로그인 화면 구현
+- 관리자 계정 검증
+- 세션 생성/만료 처리
+- 보호 라우트 처리
+- 로그아웃 구현
+
+완료 기준:
+
+- 로그인하지 않은 사용자는 관리자 화면에 접근할 수 없다.
+- 로그인한 관리자만 목록과 상세 화면에 접근할 수 있다.
+
+### Phase 4. 마에스트로 목록/상세 화면
+
+- 마에스트로 목록 API 또는 서버 액션 구현
+- TanStack Table 기반 목록 화면 구현
+- 검색, 필터, 정렬, 페이지네이션 구현
+- 상세 화면 구현
+- 상세 화면에서 연장/업그레이드/로그 요약 표시
+
+완료 기준:
+
+- 운영자가 마에스트로를 빠르게 검색하고 상세 정보를 확인할 수 있다.
+
+### Phase 5. 연장 신청 관리
+
+- 연장 신청 목록 구현
+- 상태 필터와 검색 구현
+- 승인/취소 확인 다이얼로그 구현
+- 승인/취소 서버 액션 구현
+- 트랜잭션과 로그 기록 적용
+
+완료 기준:
+
+- 요청 상태의 연장 신청을 승인 또는 취소할 수 있다.
+- 중복 처리와 이미 처리된 건의 재처리가 방지된다.
+
+### Phase 6. 업그레이드 신청 관리
+
+- 업그레이드 신청 목록 구현
+- 현재/요청 계정 비교 표시
+- 승인/거절 확인 다이얼로그 구현
+- 승인/거절 서버 액션 구현
+- 트랜잭션과 로그 기록 적용
+
+완료 기준:
+
+- 요청 상태의 업그레이드 신청을 승인 또는 거절할 수 있다.
+- 처리 결과가 마에스트로 계정에 정확히 반영된다.
+
+### Phase 7. 운영 배포 준비
+
+- Synology NAS Docker Compose 운영 설정 작성
+- 운영 환경변수 정리
+- AWS EC2 MariaDB 접근 보안 그룹 설정 가이드 작성
+- 백업/롤백 절차 작성
+- 관리자 액션 테스트 체크리스트 작성
+
+완료 기준:
+
+- Synology NAS에서 운영 컨테이너를 실행할 수 있다.
+- 운영 DB 연결 전 점검 항목이 문서화된다.
+
+### Phase 8. 검증 및 안정화
+
+- 주요 화면 수동 테스트
+- 승인/취소/거절 트랜잭션 테스트
+- 권한 없는 접근 테스트
+- Docker 재시작 테스트
+- 운영 DB read-only 리허설 후 실제 변경 기능 활성화
+
+완료 기준:
+
+- 핵심 관리자 업무가 신규 서비스에서 안정적으로 수행된다.
+
+## 12. 우선 확인이 필요한 질문
+
+1. 기존 `mouse-typing` 관리자 코드에서 연장 승인 시 정확히 며칠/몇 개월을 연장하는가?
+2. 업그레이드 승인 시 `PlayerCount`를 즉시 변경하는가, 아니면 `AccountType`만 변경하는가?
+3. `admin.Password`는 평문, 해시, 자체 암호화 중 어떤 방식인가?
+4. 운영 MariaDB가 외부 접속을 허용할 수 있는 네트워크 구조인가?
+5. 관리자 계정은 기존 `admin` 테이블을 그대로 사용할 것인가, 신규 인증 테이블을 둘 것인가?
+6. 운영 초기에 읽기 전용 모드로 먼저 배포한 뒤 변경 기능을 켤 것인가?
+
+## 13. 추천 MVP 범위
+
+1차 MVP는 아래 기능까지만 포함한다.
+
+- 관리자 로그인
+- 마에스트로 전체 목록
+- 마에스트로 상세 정보 보기
+- 연장 신청 목록
+- 연장 승인/취소
+- 업그레이드 신청 목록
+- 업그레이드 승인/거절
+- 관리자 액션 로그 기록
+- Docker 기반 실행
+
+MVP 이후 확장 후보:
+
+- 관리자 계정 관리
+- 마에스트로 상태 직접 변경
+- 학생 목록 상세 관리
+- 데이터 내보내기 CSV
+- 처리 통계 대시보드
+- 감사 로그 전용 화면
+
+## 14. 최종 추천 조합
+
+- Framework: Next.js App Router
+- Language: TypeScript
+- UI/CSS: Tailwind CSS + shadcn/ui
+- Table: TanStack Table
+- DB: MariaDB 기존 `chocomae` DB
+- ORM: Prisma 우선 검토
+- Validation: Zod
+- Runtime/Deploy: Docker on Synology NAS
+- 운영 DB 연결: AWS EC2 MariaDB에 제한된 IP와 전용 계정으로 접속
+

docs/plan/project-plan.md

@@ -0,0 +1,409 @@
+# choco-admin 프로젝트 계획서
+
+## 1. 프로젝트 개요
+
+| 항목 | 내용 |
+|---|---|
+| 서비스명 | choco-admin |
+| 목적 | chocomae 웹 서비스(mouse-typing)의 관리자 기능을 독립 웹 서비스로 분리 |
+| 기존 서비스 경로 | `/Users/jisangs/work/jinaju/git/web/mouse-typing` |
+| 신규 서비스 경로 | `/Users/jisangs/work/jinaju/git/web/choco-admin` |
+| 기존 운영 환경 | AWS EC2 t3a.medium 인스턴스 1개 |
+| 사용 DB | 기존 chocomae DB (MariaDB 10.11.13) 그대로 사용 |
+
+---
+
+## 2. 핵심 개발 방향
+
+1. 기존 `chocomae` DB를 그대로 사용한다. DB 스키마는 임의로 변경하지 않는다.
+2. 관리자 UI와 서버 로직만 신규 Next.js 서비스로 분리한다.
+3. 기존 테이블 구조와 상태값을 그대로 존중하고, 기존 서비스의 비즈니스 규칙을 먼저 파악한 뒤 동일하게 구현한다.
+4. 승인·취소·거절 같은 변경 액션은 반드시 서버 사이드에서 권한 검증 → 트랜잭션 → 로그 기록 순서로 처리한다.
+5. 중복 처리 방지를 위해 모든 변경 API는 현재 상태를 조건으로 먼저 검사한다.
+
+---
+
+## 3. 기술 스택
+
+| 구분 | 기술 |
+|---|---|
+| 런타임 | Node.js LTS |
+| 프레임워크 | Next.js 15 (App Router) |
+| 언어 | TypeScript |
+| 패키지 매니저 | pnpm |
+| UI / CSS | Tailwind CSS + shadcn/ui |
+| Table | TanStack Table (React Table v8) |
+| DB 클라이언트 | mysql2 (MariaDB 호환) |
+| ORM | Prisma (기존 DB introspection 방식으로 활용) |
+| 유효성 검증 | Zod |
+| 인증 | NextAuth.js v5 (기존 `admin` 테이블 활용) |
+| 환경변수 관리 | `.env.local` / `.env.production` |
+
+### Prisma vs Drizzle ORM
+
+두 가지 모두 MariaDB를 지원하나, 이 프로젝트에서는 **Prisma**를 우선 사용한다.
+
+- 기존 DB를 `prisma db pull`(introspection)로 그대로 가져올 수 있어 초기 세팅이 빠름
+- TypeScript 타입 자동 생성으로 컬럼명 오타를 컴파일 단계에서 잡을 수 있음
+- 세밀한 SQL 제어가 필요한 구간은 `$queryRaw` / `$executeRaw`로 raw SQL 병행 가능
+
+---
+
+## 4. 개발 환경 및 배포 환경
+
+### 4-1. 개발 환경
+
+| 항목 | 내용 |
+|---|---|
+| 하드웨어 | 맥미니 |
+| IDE | IntelliJ IDEA |
+| 실행 방법 | IntelliJ 터미널에서 `pnpm dev` |
+| 포트 | 3001 (기존 mouse-typing과 충돌 방지) |
+| DB (개발) | 맥미니 로컬 MariaDB (`localhost:3306`) |
+| 환경변수 | `.env.local` |
+
+### 4-2. 배포(서비스) 환경
+
+| 항목 | 내용 |
+|---|---|
+| 플랫폼 | Synology NAS DS920+ (RAM 20GB) — Docker |
+| 실행 방법 | Synology Container Manager (`docker compose up`) |
+| DB (서비스) | AWS EC2 MariaDB (chocomae 서비스와 동일 인스턴스) |
+| DB 접근 | AWS 보안그룹에서 NAS 외부 IP만 3306 포트 허용 |
+| DB 계정 | choco-admin 전용 최소 권한 계정으로 분리 |
+| 환경변수 | `.env.production` 또는 Container Manager 환경변수 설정 |
+
+### 4-3. Dockerfile / docker-compose (배포용)
+
+```dockerfile
+# Dockerfile
+FROM node:22-alpine
+RUN corepack enable && corepack prepare pnpm@latest --activate
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+CMD ["pnpm", "start"]
+```
+
+```yaml
+# docker-compose.yml
+services:
+  choco-admin:
+    build: .
+    ports:
+      - "3001:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=mysql://USER:PASS@AWS_EC2_HOST:3306/chocomae
+      - NEXTAUTH_SECRET=...
+      - NEXTAUTH_URL=http://NAS_IP:3001
+    restart: unless-stopped
+```
+
+---
+
+## 5. 데이터베이스 주요 테이블
+
+스키마: [`docs/db-reference/schema.sql`](./db-reference/schema.sql)
+
+| 테이블 | 설명 | 주요 컬럼 |
+|---|---|---|
+| `maestro` | 마에스트로(강사) 계정 | `MaestroID`, `Name`, `Email`, `AccountType`, `ActivateStatus`, `AvailableActivateDateTime`, `PlayerCount` |
+| `maestro_extension` | 연장 신청 | `MaestroExtensionID`, `MaestroID`, `AccountType`, `RequestedDateTime`, `Status` |
+| `maestro_upgrade` | 업그레이드 신청 | `MaestroUpgradeID`, `MaestroID`, `RegisteredAccountType`, `RequestedAccountType`, `RequestedDateTime`, `Status` |
+| `maestro_log` | 처리 이력 로그 | `MaestroLogID`, `MaestroID`, `Type`, `LogDateTime`, `Remark` |
+| `admin` | 관리자 계정 | `AdminID`, `Name`, `Password`, `Email`, `AccountType`, `ActivateStatus` |
+| `player` | 학생 계정 | `PlayerID`, `MaestroID`, `Name`, `EnterCode` |
+
+### 상태값 코드표
+
+**`maestro.AccountType`**
+
+| 값 | 의미 |
+|---|---|
+| 1 | 20명 (1만원) |
+| 2 | 50명 (2만원) |
+| 3 | 100명 (3만원) |
+| 4 | 500명 (4만원) |
+| 5 | 1,000명 (5만원) |
+
+**`maestro.ActivateStatus`**
+
+| 값 | 의미 |
+|---|---|
+| 0 | 미승인 |
+| 1 | 체험 |
+| 2 | 활성화 |
+| 100 | 등록취소 |
+
+**`maestro_extension.Status` / `maestro_upgrade.Status`**
+
+| 값 | 의미 |
+|---|---|
+| 1 | 요청 |
+| 2 | 취소/거절 |
+| 3 | 적용 완료 |
+
+---
+
+## 6. 애플리케이션 구조
+
+```
+choco-admin/
+├── app/
+│   ├── (auth)/
+│   │   └── login/
+│   │       └── page.tsx          # 관리자 로그인
+│   ├── (admin)/
+│   │   ├── layout.tsx            # 공통 사이드바 + 헤더
+│   │   ├── maestros/
+│   │   │   ├── page.tsx          # 마에스트로 전체 목록
+│   │   │   └── [maestroId]/
+│   │   │       └── page.tsx      # 마에스트로 상세 정보
+│   │   ├── extension-requests/
+│   │   │   └── page.tsx          # 연장 신청 목록 + 승인/취소
+│   │   └── upgrade-requests/
+│   │       └── page.tsx          # 업그레이드 신청 목록 + 승인/거절
+│   └── api/
+│       ├── auth/[...nextauth]/
+│       ├── maestros/
+│       │   ├── route.ts          # GET: 목록
+│       │   └── [id]/route.ts     # GET: 상세, PATCH: 상태 변경
+│       ├── extension-requests/
+│       │   └── [id]/route.ts     # PATCH: 승인/취소
+│       └── upgrade-requests/
+│           └── [id]/route.ts     # PATCH: 승인/거절
+├── components/
+│   ├── ui/                       # shadcn/ui 컴포넌트
+│   ├── data-table/               # TanStack Table 공통 컴포넌트
+│   ├── layout/                   # 사이드바, 헤더
+│   ├── forms/
+│   └── dialogs/                  # 승인/취소 확인 다이얼로그
+├── lib/
+│   ├── db.ts                     # Prisma Client 싱글톤
+│   ├── auth.ts                   # NextAuth 설정
+│   ├── validators/               # Zod 스키마
+│   └── constants.ts              # 상태값 상수
+├── types/
+│   └── index.ts
+├── prisma/
+│   └── schema.prisma             # DB introspection 결과
+├── docs/
+│   └── db-reference/
+│       └── schema.sql
+├── .env.local                    # gitignore
+├── .env.production               # gitignore
+├── Dockerfile
+└── docker-compose.yml
+```
+
+---
+
+## 7. 주요 화면 기능 명세
+
+### 7-1. 공통 레이아웃
+
+- 로그인 화면 (미인증 시 `/login` 리다이렉트)
+- 좌측 사이드바 네비게이션
+- 공통 확인 다이얼로그 (승인/취소/거절 전 확인)
+- 처리 성공/실패 토스트 알림
+
+### 7-2. 마에스트로 전체 목록 (`/maestros`)
+
+- 전체 목록 조회 (서버 사이드 페이지네이션)
+- 검색: 이름, 이메일, MaestroID
+- 필터: ActivateStatus (미승인 / 체험 / 활성화 / 등록취소)
+- 필터: AccountType (20명 / 50명 / 100명 / 500명 / 1,000명)
+- 정렬: 가입일, 사용 가능일
+- 컬럼: ID / 이름 / 이메일 / 계정 유형 / 상태 / 학생 수 / 사용 가능일 / 상세보기
+
+### 7-3. 마에스트로 상세 정보 (`/maestros/[maestroId]`)
+
+- 기본 계정 정보 (이름, 이메일, 계정 유형, 상태, 만료일, 약관 동의일)
+- 플레이어(학생) 목록 요약
+- 연장 신청 이력
+- 업그레이드 신청 이력
+- 관리자 처리 로그 (`maestro_log`)
+
+### 7-4. 연장 신청 목록 (`/extension-requests`)
+
+- 연장 신청 목록 조회 (기본 필터: Status=1 요청 건)
+- 필터: 상태 (요청 / 취소 / 적용)
+- 컬럼: 신청ID / 마에스트로명 / 계정유형 / 신청일시 / 상태 / 승인 / 취소
+
+**승인 처리 순서:**
+1. `maestro_extension.Status = 1` 인지 확인 (중복 처리 방지)
+2. 트랜잭션 시작
+3. `maestro_extension.Status → 3`
+4. `maestro.AvailableActivateDateTime` 연장, `maestro.ActivateStatus → 2` (기존 서비스 로직 확인 후 동일 적용)
+5. `maestro_log` 기록
+6. 트랜잭션 커밋
+
+**취소 처리 순서:**
+1. `maestro_extension.Status = 1` 인지 확인
+2. 트랜잭션 시작
+3. `maestro_extension.Status → 2`
+4. `maestro_log` 기록
+5. 트랜잭션 커밋
+
+### 7-5. 업그레이드 신청 목록 (`/upgrade-requests`)
+
+- 업그레이드 신청 목록 조회 (기본 필터: Status=1 요청 건)
+- 필터: 상태 (요청 / 취소 / 적용)
+- 컬럼: 신청ID / 마에스트로명 / 현재등급 / 요청등급 / 신청일시 / 상태 / 승인 / 거절
+
+**승인 처리 순서:**
+1. `maestro_upgrade.Status = 1` 인지 확인 (중복 처리 방지)
+2. 트랜잭션 시작
+3. `maestro_upgrade.Status → 3`
+4. `maestro.AccountType → RequestedAccountType` 변경 (PlayerCount 갱신 정책은 기존 서비스 확인 후 동일 적용)
+5. `maestro_log` 기록
+6. 트랜잭션 커밋
+
+**거절 처리 순서:**
+1. `maestro_upgrade.Status = 1` 인지 확인
+2. 트랜잭션 시작
+3. `maestro_upgrade.Status → 2`
+4. `maestro_log` 기록
+5. 트랜잭션 커밋
+
+---
+
+## 8. 보안 고려사항
+
+1. 관리자 로그인은 NextAuth 서버 세션 기반으로 구현한다.
+2. 기존 `admin.Password` 저장 방식(평문/해시/자체 암호화)을 먼저 확인한 뒤 동일 방식 또는 해시 업그레이드를 결정한다.
+3. 승인·취소·거절 액션은 Next.js Server Action 또는 API Route에서 CSRF 보호를 적용한다.
+4. DB 연결 정보는 `.env` 파일로 관리하며 Git에 커밋하지 않는다.
+5. 배포 DB 계정은 choco-admin 전용 계정으로 분리하고 최소 권한(SELECT + 필요한 테이블만 UPDATE)을 적용한다.
+6. AWS EC2 보안그룹에서 MariaDB 포트(3306)를 NAS 외부 IP로만 허용한다.
+7. 관리자 전용 서비스이므로 외부에 직접 노출하지 않고 VPN 또는 NAS 내부 포트로 접근하는 방식을 권장한다.
+
+---
+
+## 9. 개발 단계 계획
+
+### Phase 0. 기존 관리자 코드 조사
+
+> 기존 서비스 비즈니스 규칙을 파악해 재현 실수를 방지한다.
+
+- [ ] `mouse-typing` 관리자 라우트와 처리 로직 분석 (`src/web/admin/`, `src/web/server/admin/`)
+- [ ] 연장 승인 시 `AvailableActivateDateTime` 계산 방식 확인 (몇 개월/년 연장인지)
+- [ ] 업그레이드 승인 시 `PlayerCount` 갱신 여부 확인
+- [ ] `admin.Password` 검증 방식 확인 (평문 / MD5 / bcrypt 등)
+- [ ] `maestro_log` 기록 형식(`Type`, `Remark`) 확인
+- [ ] 조사 결과를 `docs/business-rules.md`에 문서화
+
+### Phase 1. 프로젝트 초기화
+
+- [ ] `pnpm create next-app` (Next.js 15, TypeScript, App Router, Tailwind CSS)
+- [ ] shadcn/ui 초기화 (`pnpm dlx shadcn@latest init`)
+- [ ] TanStack Table 설치 (`pnpm add @tanstack/react-table`)
+- [ ] Prisma 설치 및 MariaDB introspection (`pnpm add prisma`, `prisma db pull`)
+- [ ] Zod 설치 (`pnpm add zod`)
+- [ ] NextAuth.js v5 설치
+- [ ] ESLint / Prettier 설정
+- [ ] `.env.local` 환경변수 구조 정의
+- [ ] IntelliJ에서 `pnpm dev` 실행 확인
+
+### Phase 2. DB 연결 및 타입 구성
+
+- [ ] Prisma Client 싱글톤 (`lib/db.ts`)
+- [ ] 상태값 상수 정의 (`lib/constants.ts`)
+- [ ] 공통 유틸 작성 (날짜 포맷, AccountType 레이블 변환 등)
+- [ ] 개발 DB에서 `maestro`, `maestro_extension`, `maestro_upgrade` 조회 확인
+
+### Phase 3. 인증 및 공통 레이아웃
+
+- [ ] 로그인 페이지 (`/login`)
+- [ ] NextAuth Credentials Provider — `admin` 테이블 기반 검증
+- [ ] 인증 미들웨어 (`middleware.ts`) — 비로그인 시 `/login` 리다이렉트
+- [ ] 공통 레이아웃 (`(admin)/layout.tsx`) — 사이드바, 헤더
+- [ ] 로그아웃 기능
+
+### Phase 4. 마에스트로 목록 및 상세
+
+- [ ] 마에스트로 목록 API (`GET /api/maestros`) — 검색·필터·페이지네이션 포함
+- [ ] TanStack Table 기반 목록 화면
+- [ ] 마에스트로 상세 API (`GET /api/maestros/[id]`)
+- [ ] 상세 화면 — 연장/업그레이드 이력, 학생 목록 요약, 처리 로그
+
+### Phase 5. 연장 신청 관리
+
+- [ ] 연장 신청 목록 API + 화면
+- [ ] 승인/취소 확인 다이얼로그 (shadcn/ui AlertDialog)
+- [ ] 승인 API (`PATCH /api/extension-requests/[id]`) — 트랜잭션 + maestro_log
+- [ ] 취소 API — 트랜잭션 + maestro_log
+
+### Phase 6. 업그레이드 신청 관리
+
+- [ ] 업그레이드 신청 목록 API + 화면
+- [ ] 승인/거절 확인 다이얼로그
+- [ ] 승인 API (`PATCH /api/upgrade-requests/[id]`) — 트랜잭션 + maestro_log
+- [ ] 거절 API — 트랜잭션 + maestro_log
+
+### Phase 7. 배포 환경 구성
+
+- [ ] Dockerfile (프로덕션용 pnpm 빌드)
+- [ ] `docker-compose.yml` (Synology NAS Container Manager용)
+- [ ] AWS EC2 보안그룹 인바운드 설정 (NAS IP → 3306 허용)
+- [ ] Synology NAS에서 컨테이너 실행 테스트
+- [ ] 운영 DB read-only 리허설 후 변경 기능 활성화
+
+### Phase 8. 검증 및 안정화
+
+- [ ] 승인/취소/거절 트랜잭션 시나리오 테스트
+- [ ] 중복 처리 방지 (이미 처리된 건 재처리 시 에러 확인)
+- [ ] 비인증 접근 차단 확인
+- [ ] Docker 재시작 후 정상 동작 확인
+
+---
+
+## 10. MVP 범위
+
+**1차 MVP (위 Phase 0~7):**
+- 관리자 로그인
+- 마에스트로 전체 목록 및 상세 정보 보기
+- 연장 신청 목록 / 승인 / 취소
+- 업그레이드 신청 목록 / 승인 / 거절
+- 관리자 액션 로그 기록
+- Docker 기반 NAS 배포
+
+**MVP 이후 확장 후보:**
+- 마에스트로 상태 직접 변경
+- 학생 목록 상세 관리
+- 데이터 내보내기 (CSV)
+- 처리 통계 대시보드
+- 감사 로그 전용 화면
+- 관리자 계정 관리
+
+---
+
+## 11. 구현 전 확인이 필요한 사항
+
+기존 `mouse-typing` 서비스 코드(`src/web/server/admin/`)에서 반드시 확인해야 할 비즈니스 규칙들이다.
+
+1. 연장 승인 시 `AvailableActivateDateTime`을 정확히 얼마나 연장하는가? (1년? 계정 유형별 다름?)
+: 계정 유형별로 차이 없고, 1년 연장
+2. 업그레이드 승인 시 `PlayerCount`를 즉시 변경하는가, 아니면 `AccountType`만 변경하는가?
+: AccountType만 변경
+3. `admin.Password`는 어떤 방식으로 저장/검증되는가? (평문, MD5, bcrypt 등)
+: MariaDB의 Password() 함수를 이용해서 저장/검증됨
+4. `maestro_log`의 `Type` 컬럼에 어떤 값들이 사용되는가? (`Remark` 형식 포함)
+: 다음과 같은 값들이 사용됨
+* add_maestro
+* update_maestro
+* add_maestro
+* register_maestro
+* update_maestro_name
+* extension_maestro
+* upgrade_maestro
+* update_maestro_email
+5. 운영 MariaDB가 외부 IP 접속을 허용할 수 있는 네트워크 구조인가?
+: 외부 IP 접속을 허용하고 있다
+
+---
+
+*작성일: 2026-05-26*