chocoadmin
chocomae(mouse-typing) 서비스의 관리자 기능을 독립 Next.js 서비스로 분리한 웹 애플리케이션이다.
기술 스택
| 구분 | 기술 |
|---|---|
| 프레임워크 | Next.js 16 (App Router) |
| 언어 | TypeScript |
| 패키지 매니저 | pnpm |
| UI / CSS | Tailwind CSS v4 + shadcn/ui (Base UI) |
| Table | TanStack Table v8 |
| ORM | Prisma v7 (MariaDB adapter) |
| 인증 | NextAuth.js v5 (admin 테이블 기반) |
| 유효성 검증 | Zod v4 |
| 이메일 | Nodemailer |
| DB | MariaDB 10.11 (기존 chocomae DB 공유) |
구현된 기능
- 관리자 로그인 (기존
admin테이블 / MariaDBPASSWORD()호환) - 마에스트로 전체 목록 — 검색(이름·이메일·ID), 상태/계정유형 필터, 페이지네이션
- 마에스트로 상세 보기 — 기본 정보, 연장/업그레이드 이력, 처리 로그
- 연장 신청 목록 — 승인 / 취소 (트랜잭션 +
maestro_log) - 업그레이드 신청 목록 — 승인 / 거절 (트랜잭션 +
maestro_log) - 비인증 접근 차단 (
proxy.ts, API routeauth()검사) - 구조화 로깅 — API 처리 시간·결과, DB 쿼리 pretty 출력, slow query 감지, 비밀번호 컬럼 마스킹 (
Password) - 동시 승인 방지 — 연장/업그레이드 승인·취소·거절 시 조건부 원자 UPDATE로 이중 처리 차단
개발 환경 설정
1. 의존성 설치
pnpm install
2. 환경변수 설정
cp .env.example .env.local
.env.local을 열어 실제 값으로 교체한다.
DATABASE_URL="mysql://USER:PASSWORD@127.0.0.1:3306/chocomae"
AUTH_SECRET="..."
NEXTAUTH_SECRET="..."
AUTH_URL="http://localhost:3000"
NEXTAUTH_URL="http://localhost:3000"
3. DB 연결 확인
pnpm db:check
4. 개발 서버 실행
pnpm dev
http://localhost:3000 에서 확인한다.
환경변수 전체 목록
| 변수 | 필수 | 설명 |
|---|---|---|
DATABASE_URL |
✅ | MariaDB 연결 문자열 (mysql://...) |
AUTH_SECRET |
✅ | NextAuth 세션 암호화 키 |
NEXTAUTH_SECRET |
✅ | NextAuth 호환용 (동일 값) |
AUTH_URL |
✅ | 서비스 기본 URL |
NEXTAUTH_URL |
✅ | NextAuth 호환용 (동일 값) |
APP_ENV |
— | local | stage | production — 미설정 시 debug 레벨 기본값 |
LOG_LEVEL |
— | debug | info | warn | error — production 권장: info |
DB_SLOW_QUERY_MS |
— | slow query 임계값(ms), 기본 1000 — 초과 시 warn 로그 |
MAIL_FROM_NAME |
— | 발송자 이름 (Phase 11) |
MAIL_FROM_ADDRESS |
— | 발송자 주소 (Phase 11) |
MAIL_BCC_ADDRESS |
— | BCC 주소 (Phase 11) |
MAIL_SMTP_HOST |
— | SMTP 호스트 (Phase 11) |
MAIL_SMTP_PORT |
— | SMTP 포트 (Phase 11) |
MAIL_SMTP_SECURE |
— | TLS 여부 (Phase 11) |
MAIL_SMTP_USER |
— | SMTP 인증 계정 (Phase 11) |
MAIL_SMTP_PASSWORD |
— | SMTP 인증 비밀번호 (Phase 11) |
MAIL_SEND_ENABLED |
— | true | false 발송 활성화 (Phase 11) |
MAIL_OVERRIDE_TO |
— | 설정 시 모든 메일 수신인을 이 주소로 고정 — local/stage 테스트용 (Phase 11) |
배포 (Synology NAS Docker)
# 이미지 빌드 및 컨테이너 시작
docker compose up -d --build
docker-compose.yml의 environment 섹션에 위 환경변수를 설정한다. TZ: Asia/Seoul은 두 compose 파일에 이미 포함되어 있다. 상세 절차는 docs/deployment.md를 참고한다.
프로젝트 구조
chocoadmin/
├── app/
│ ├── (auth)/login/ # 관리자 로그인
│ ├── (admin)/ # 인증 필요 화면
│ │ ├── maestros/ # 마에스트로 목록·상세
│ │ ├── extension-requests/
│ │ └── upgrade-requests/
│ └── api/ # API routes
├── components/
│ ├── data-table/ # TanStack Table 기반 테이블
│ ├── forms/
│ └── ui/ # shadcn/ui 컴포넌트
├── lib/
│ ├── db.ts # Prisma Client 싱글톤 (SQL/결과 로깅 포함)
│ ├── logger.ts # 공통 로거 (debug/info/warn/error)
│ ├── errors.ts # ApiError 공통 에러 클래스
│ ├── api-handler.ts # API route 래퍼 (auth, 타이밍, 에러 처리)
│ ├── constants.ts # 상태값 상수
│ ├── maestros.ts # 마에스트로 DB 쿼리
│ ├── extension-requests.ts
│ └── upgrade-requests.ts
├── prisma/
│ └── schema.prisma # DB introspection 결과
├── docs/
│ ├── business-rules.md # 기존 서비스 비즈니스 규칙 조사
│ ├── deployment.md
│ └── plan/project-plan.md # 전체 개발 계획
├── auth.ts # NextAuth 설정
├── proxy.ts # 미인증 접근 차단 미들웨어
└── .env.example
문서
docs/plan/project-plan.md— 전체 개발 단계 계획docs/business-rules.md— 기존 chocomae 비즈니스 규칙docs/deployment.md— NAS 배포 절차docs/phase/phase9.md— 로그 정책 및 Docker 로그 운영 절차