jisangs/chocoadmin

Fork 0

Files

T

jisangs c6a5418d25 plan 생성

2026-06-09 18:37:32 +09:00

12 KiB

Raw Blame History

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 구성 계획

# 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 계획

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

테이블	설명	주요 컬럼
`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

12 KiB Raw Blame History