plan 생성

2026-06-09 18:37:32 +09:00
parent 5dd7375aad
commit c6a5418d25
3 changed files with 1249 additions and 0 deletions
@@ -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와 전용 계정으로 접속
+