# 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*