From c6a5418d253d129012cb0404cf89be609f49baa7 Mon Sep 17 00:00:00 2001 From: jisangs Date: Tue, 9 Jun 2026 18:37:32 +0900 Subject: [PATCH] =?UTF-8?q?plan=20=EC=83=9D=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plan/project-plan-claudecode.md | 339 ++++++++++++++++++ docs/plan/project-plan-codex.md | 501 +++++++++++++++++++++++++++ docs/plan/project-plan.md | 409 ++++++++++++++++++++++ 3 files changed, 1249 insertions(+) create mode 100644 docs/plan/project-plan-claudecode.md create mode 100644 docs/plan/project-plan-codex.md create mode 100644 docs/plan/project-plan.md diff --git a/docs/plan/project-plan-claudecode.md b/docs/plan/project-plan-claudecode.md new file mode 100644 index 0000000..73e23be --- /dev/null +++ b/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* diff --git a/docs/plan/project-plan-codex.md b/docs/plan/project-plan-codex.md new file mode 100644 index 0000000..ff6246d --- /dev/null +++ b/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와 전용 계정으로 접속 + diff --git a/docs/plan/project-plan.md b/docs/plan/project-plan.md new file mode 100644 index 0000000..94bfda1 --- /dev/null +++ b/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*