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 테이블 / MariaDB PASSWORD() 호환)
• 마에스트로 전체 목록 — 검색(이름·이메일·ID), 상태/계정유형 필터, 페이지네이션
• 마에스트로 상세 보기 — 기본 정보, 연장/업그레이드 이력, 처리 로그
• 연장 신청 목록 — 승인 / 취소 (트랜잭션 + maestro_log)
• 업그레이드 신청 목록 — 승인 / 거절 (트랜잭션 + maestro_log)
• 비인증 접근 차단 (proxy.ts, API route auth() 검사)
• 구조화 로깅 — API 처리 시간·결과, DB 쿼리 pretty 출력, slow query 감지, 비밀번호 마스킹

개발 환경 설정

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)

배포 (Synology NAS Docker)

# 이미지 빌드 및 컨테이너 시작
docker compose up -d --build

docker-compose.yml의 environment 섹션에 위 환경변수를 설정한다. 상세 절차는 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 로그 운영 절차