jisangs/chocoadmin

Fork 0

Files

T

jisangs c6a5418d25 plan 생성

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

16 KiB

Raw Blame History

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. 핵심 개발 방향

기존 chocomae DB를 그대로 사용한다.
관리자 UI와 서버 로직만 신규 Next.js 서비스로 분리한다.
운영 DB 스키마를 임의 변경하지 않고, 기존 테이블과 상태값을 우선 존중한다.
관리자 액션은 반드시 서버 사이드에서 권한 검증, 트랜잭션, 로그 기록을 거친다.
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 접근 방식 추천

Prisma
- 장점: 타입 안정성, 마이그레이션/스키마 관리 경험이 좋고 개발 속도가 빠름
- 주의: 기존 MariaDB 스키마를 introspection해서 사용하는 방식이 적합함
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 기록

승인 처리 초안:

maestro_extension.Status = 1인지 확인한다.
트랜잭션을 시작한다.
maestro_extension.Status를 3으로 변경한다.
maestro.AccountType, AvailableActivateDateTime, ActivateStatus 갱신 규칙을 기존 서비스에서 확인해 동일하게 적용한다.
maestro_log에 처리 기록을 남긴다.
트랜잭션을 커밋한다.

취소 처리 초안:

maestro_extension.Status = 1인지 확인한다.
트랜잭션을 시작한다.
maestro_extension.Status를 2로 변경한다.
maestro_log에 취소 기록을 남긴다.
트랜잭션을 커밋한다.

7.5 마에스트로 업그레이드 신청 목록

목표: maestro_upgrade의 업그레이드 요청을 검토하고 승인 또는 거절 처리한다.

주요 기능:

업그레이드 신청 목록 조회
요청 상태별 필터
현재 계정 종류와 요청 계정 종류 비교 표시
요청일 기준 정렬
업그레이드 승인
업그레이드 거절
처리 후 maestro_log 기록

승인 처리 초안:

maestro_upgrade.Status = 1인지 확인한다.
트랜잭션을 시작한다.
maestro_upgrade.Status를 3으로 변경한다.
maestro.AccountType을 RequestedAccountType으로 변경한다.
필요 시 PlayerCount 정책을 기존 서비스에서 확인해 반영한다.
maestro_log에 처리 기록을 남긴다.
트랜잭션을 커밋한다.

거절 처리 초안:

maestro_upgrade.Status = 1인지 확인한다.
트랜잭션을 시작한다.
maestro_upgrade.Status를 2로 변경한다.
maestro_log에 거절 기록을 남긴다.
트랜잭션을 커밋한다.

8. 애플리케이션 구조 제안

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. 보안 계획

관리자 로그인은 서버 세션 기반으로 구현한다.
관리자 비밀번호 저장 방식은 기존 admin.Password 구조를 확인한 뒤 개선 가능성을 검토한다.
운영 DB 접속 정보는 저장소에 커밋하지 않는다.
승인/취소/거절 같은 변경 액션은 CSRF 또는 서버 액션 보호를 적용한다.
관리자 액션은 maestro_log에 기록한다.
운영 DB 직접 수정 기능은 최소화한다.
승인/거절 API는 중복 처리 방지를 위해 현재 상태를 조건으로 검사한다.
모든 변경 작업은 트랜잭션으로 처리한다.

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. 우선 확인이 필요한 질문

기존 mouse-typing 관리자 코드에서 연장 승인 시 정확히 며칠/몇 개월을 연장하는가?
업그레이드 승인 시 PlayerCount를 즉시 변경하는가, 아니면 AccountType만 변경하는가?
admin.Password는 평문, 해시, 자체 암호화 중 어떤 방식인가?
운영 MariaDB가 외부 접속을 허용할 수 있는 네트워크 구조인가?
관리자 계정은 기존 admin 테이블을 그대로 사용할 것인가, 신규 인증 테이블을 둘 것인가?
운영 초기에 읽기 전용 모드로 먼저 배포한 뒤 변경 기능을 켤 것인가?

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와 전용 계정으로 접속

16 KiB Raw Blame History

choco-admin 개발 작업 계획

1. 프로젝트 개요

2. 핵심 개발 방향

3. 기술 스택 제안

기본 스택

DB 접근 방식 추천

4. CSS Framework 추천

1순위: Tailwind CSS + shadcn/ui

2순위: Mantine

3순위: Chakra UI

5. Table 라이브러리 추천

1순위: TanStack Table

2순위: AG Grid Community

3순위: Mantine React Table

6. DB 기준 관리자 대상 테이블

주요 테이블

주요 상태값

7. 주요 관리자 화면 계획

7.1 공통 레이아웃

7.2 마에스트로 전체 목록

7.3 마에스트로 상세 정보 보기

7.4 마에스트로 연장 신청 목록

7.5 마에스트로 업그레이드 신청 목록

8. 애플리케이션 구조 제안

9. Docker 개발/운영 계획

개발 환경

운영 환경

Docker 구성 초안

10. 보안 계획

11. 개발 단계별 작업 계획

Phase 0. 기존 관리자 기능 조사

Phase 1. 프로젝트 초기화

Phase 2. DB 연결 및 타입 구성

Phase 3. 인증과 관리자 세션

Phase 4. 마에스트로 목록/상세 화면

Phase 5. 연장 신청 관리

Phase 6. 업그레이드 신청 관리

Phase 7. 운영 배포 준비

Phase 8. 검증 및 안정화

12. 우선 확인이 필요한 질문

13. 추천 MVP 범위

14. 최종 추천 조합

16 KiB

Raw Blame History