# 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()` 호환, 로그인 실패 5회 → 15분 잠금)
- 마에스트로 전체 목록 — 검색(이름·이메일·ID), 상태/계정유형 필터, 페이지네이션
- 마에스트로 상세 보기 — 기본 정보, 연장/업그레이드 이력, 처리 로그
- 마에스트로 정보 수정 — 이름, 이메일, 상태, 계정유형, 만료일, 엔터코드 허용 여부 (`PATCH /api/maestros/[id]`)
- 마에스트로 암호 초기화 — 관리자가 `123456`으로 초기화 (트랜잭션 + `maestro_log`)
- 수강생 목록 — 서버사이드 페이지네이션 (`GET /api/maestros/[id]/students`)
- 연장 신청 목록 — 승인 / 취소 (트랜잭션 + `maestro_log` + 이메일 발송)
- 업그레이드 신청 목록 — 승인 / 거절 (트랜잭션 + `maestro_log` + 이메일 발송)
- 관리자 주도 연장/업그레이드 신청 등록 — 마에스트로 상세 화면에서 직접 등록 (이메일 미발송)
- 비인증 접근 차단 (`proxy.ts`, API route `auth()` 검사)
- 구조화 로깅 — API 처리 시간·결과, DB 쿼리 pretty 출력, slow query 감지, 비밀번호 컬럼 마스킹 (`Password`)
- 동시 승인 방지 — 연장/업그레이드 승인·취소·거절 시 조건부 원자 UPDATE로 이중 처리 차단
- 이메일 자동 발송 — 연장/업그레이드 승인 후 Nodemailer로 발송, 실패 시 UI 경고 표시

## 개발 환경 설정

### 1. 의존성 설치

```bash
pnpm install
```

### 2. 환경변수 설정

```bash
cp .env.example .env.local
```

`.env.local`을 열어 실제 값으로 교체한다.

```env
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 연결 확인

```bash
pnpm db:check
```

### 4. 개발 서버 실행

```bash
pnpm dev
```

[http://localhost:3000](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)

```bash
# 스테이지 배포
bash scripts/deploy-stage.sh

# 운영 배포 (yes 입력 확인 필요)
bash scripts/deploy-production.sh
```

각 스크립트는 `git pull` → `proxy-network` 확인 → `docker compose up -d --build --remove-orphans` → `docker exec npm nginx -s reload` 순으로 실행된다.

`docker-compose.yml`의 `environment` 섹션에 위 환경변수를 설정한다. `TZ: Asia/Seoul`은 두 compose 파일에 이미 포함되어 있다. 상세 절차는 [`docs/deployment.md`](docs/deployment.md)를 참고한다.

## 프로젝트 구조

```
chocoadmin/
├── app/
│   ├── (auth)/login/          # 관리자 로그인
│   ├── (admin)/               # 인증 필요 화면
│   │   ├── MobileNav.tsx      # 모바일 슬라이드인 사이드바 (햄버거·오버레이·X 버튼)
│   │   ├── nav-config.ts      # 내비게이션 항목 공유 설정
│   │   ├── maestros/          # 마에스트로 목록·상세
│   │   ├── extension-requests/
│   │   └── upgrade-requests/
│   └── api/                   # API routes
│       └── maestros/[id]/
│           ├── route.ts              # PATCH — 마에스트로 정보 수정
│           ├── students/route.ts     # GET — 수강생 목록 (페이지네이션)
│           ├── extension-requests/   # POST — 관리자 주도 연장 신청
│           ├── upgrade-requests/     # POST — 관리자 주도 업그레이드 신청
│           └── reset-password/       # POST — 암호 초기화
├── 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, 타이밍, 에러 처리)
│   ├── mail.ts                # Nodemailer 이메일 발송
│   ├── constants.ts           # 상태값 상수
│   ├── maestros.ts            # 마에스트로 DB 쿼리
│   ├── extension-requests.ts
│   └── upgrade-requests.ts
├── scripts/
│   ├── deploy-stage.sh        # 스테이지 배포 스크립트
│   └── deploy-production.sh   # 운영 배포 스크립트
├── 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/plan/project-plan.md) — 전체 개발 단계 계획
- [`docs/business-rules.md`](docs/business-rules.md) — 기존 chocomae 비즈니스 규칙
- [`docs/deployment.md`](docs/deployment.md) — NAS 배포 절차
- [`docs/phase/phase9.md`](docs/phase/phase9.md) — 로그 정책 및 Docker 로그 운영 절차