jisangs/chocoadmin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plan 생성

Browse Source
This commit is contained in:
Jisang Park
2026-06-09 18:37:32 +09:00
parent 5dd7375aad
commit c6a5418d25
3 changed files with 1249 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plan/project-plan-claudecode.md
+339
View File
@@ -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*