plan 생성

2026-06-09 18:37:32 +09:00
parent 5dd7375aad
commit c6a5418d25
3 changed files with 1249 additions and 0 deletions
@@ -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*
@@ -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와 전용 계정으로 접속
@@ -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*