🎮 정착지원국
평화로운 게임마을 — 게임 멘토링 클래스 · 수강 신청 · 선생님 관리 · 졸업면담
수달반 🦦 · 사자반 🦁 · 여우반 🦊 — 함께 성장하는 게임 클래스
🌍 프로덕션: ow-school.vercel.app · 📦 저장소: github.com/zyansuh/ow_school
목차
- 프로젝트 소개
- 사이트 이용자 역할
- 주요 기능
- 배정 이력 · 트랜잭션 일관성
- 사용 기술
- 아키텍처 · 소스 구조
- 빠른 시작
- 배포 · CI
- Prisma 마이그레이션 · 인덱스
- Discord 연동 · Bot DM
- 포인트 · 반 안내
- API 레퍼런스
- 데이터 모델 · DB 운영
- 운영 스크립트
- 개발 규칙
- 트러블슈팅
- 최근 변경 요약
📖 이 프로젝트는?
정착지원국(브랜드명: 평화로운 게임마을, SITE_NAME / SITE_TAGLINE)은 Discord 커뮤니티 기반 게임 멘토링 프로그램 운영용 풀스택 웹 앱입니다.
| 구분 | 설명 |
|---|
| 프론트 | Next.js App Router · React 19 · Tailwind (다크 테마 고정) |
| 백엔드 | 동일 Next.js 프로젝트의 Route Handlers (app/api/) |
| 인증 | NextAuth.js v5 + Discord OAuth2 |
| DB | PostgreSQL (Neon) + Prisma ORM |
| 배포 | Vercel (Cron으로 Discord 일괄 동기화) |
이용자별 기능
| 역할 | 대표 경로 | 할 수 있는 것 |
|---|
| 마을주민 | /, /mypage | 반·선생님 둘러보기, 커뮤니티 참여 |
| 학생 | /apply, /interview | 수강 신청, 졸업면담, 담당 선생님 배정 |
| 선생님 | /teacher | 담당 학생 관리, 통계 |
| 관리자 | /admin | 전체 운영·역할·졸업·Discord 동기화 |
👥 사이트 이용자 역할
관리자는 /admin/users에서 역할을 수동 지정할 수 있습니다. User.siteRole이 비어 있으면 자동 분류가 적용됩니다.
역할 정의
| 표시 | DB 값 | 자동 분류 우선순위 (siteRole이 비어 있을 때) |
|---|
| 관리자 | admin | AdminRole 행 존재 |
| 선생님 | teacher | 선생님 관리 등록(Teacher.discordUserId / 닉 매칭) 우선 · Discord 역할(신입반 주임교사 등, /admin/teachers에서 편집) |
| 학생 | student | ① status=active && teacherId 있음 (가입 기간과 무관, 재학 배정 유지) → ② Discord 서버 가입 2달 미만 (guildJoinedAt) |
| 마을주민 | resident | 위 조건 없음 · 졸업(graduated)·퇴교(withdrawn)는 status≠active라 ①에 걸리지 않음 |
핵심: 담당 선생님이 배정된 재학생은 가입 후 2달이 지나도 자동으로 마을주민으로 떨어지지 않습니다.
명시적 siteRole(예: resident)이 있으면 자동 분류보다 항상 우선합니다.
역할 해석 흐름
flowchart TD
A[User] --> B{siteRole 수동 지정?}
B -->|예| C[siteRole 그대로 사용]
B -->|아니오| D{AdminRole?}
D -->|예| E[admin]
D -->|아니오| F{Teacher.discordUserId 등록?}
F -->|예| G[teacher]
F -->|아니오| H{Teacher.discord 닉 매칭?}
H -->|예| G
H -->|아니오| I{Discord 선생님 역할?}
I -->|예| G
I -->|아니오| J{status=active AND teacherId?}
J -->|예| K[student]
J -->|아니오| L{가입 2달 미만?}
L -->|예| K
L -->|아니오| M[resident]
Discord 선생님 역할 (관리자 설정)
/admin/teachers 상단에서 Discord 역할명·우선순위를 직접 입력·저장합니다 (SiteSetting 키 teacher_discord_roles).
| 기본 역할명 | 우선순위 | 의미 |
|---|
신입반 주임교사 | 1 | 주임 |
신입반 교사 | 2 | 일반 교사 |
신입반 보조교사 | 3 | 보조 |
신입반교사 | 2 | 레거시(공백 없음) 호환 |
- Discord 서버 역할명과 글자 단위 동일해야 매칭됩니다 (공백 포함).
- 수강 신청·선생님 카드·배정은 Discord 역할만으로 동작하지 않고, 선생님 관리에 등록된
Teacher 레코드만 사용합니다.
- 사이트 역할
teacher 자동 분류는 등록된 사람 우선, Discord 역할은 보조입니다.
구현 · 검증
| 파일 | 역할 |
|---|
src/lib/users/role.ts | getUserRole, inferUserRole, isActiveAssignedStudentCandidate, isStudentUser |
src/lib/teacher/discord-roles.ts | Discord 선생님 역할 기본값·SiteSetting CRUD |
src/lib/teacher/recruiting.ts | 비활성 vs 모집마감 분리 |
src/lib/discord/guild-tenure.ts | guildJoinedAt, 2달 기준 isStudentByGuildTenure |
src/lib/users/display.ts | 관리자 화면 displayNickname 우선 표시 |
# DB 없이 역할 분류 순수 함수 검증 (케이스 1–12)
node scripts/verify-user-role.mjs
# 실제 Neon DB 유저에 현행 정책 적용 집계 (읽기 전용)
node scripts/verify-role-policy-db.mjs
# 비활성 vs 모집마감 분리 검증
node scripts/verify-recruiting.mjs
참고
guildJoinedAt은 Discord Member API joined_at 동기화 값. 없으면 최초 로그인일(createdAt) 을 보조 기준으로 사용.- 학생 관리(
/admin/students)·홈 통계의 “학생 수”는 student 역할만 집계 (마을주민 제외). status·teacherId를 역할 판별에 쓰므로 User 조회 시 해당 필드를 빼면 안 됩니다.
- 메인 홈 통계(학생 수·선생님 인원·졸업생 수·클래스 카드 인원)는 DB에서 자동 집계하여 표시합니다 (
src/lib/home/stats.ts, class-stats.ts). ISR 캐시 60~120초.
- 관리자로
siteRole=admin 지정 시 AdminRole 부여, 다른 역할로 변경 시 AdminRole 해제.
- Admin / Teacher 판별은
active+teacherId보다 항상 앞에 있어, 관리자·선생님이 실수로 배정돼도 student로 떨어지지 않습니다.
✨ 주요 기능
🌟 공개 · 일반 사용자
| 기능 | 경로 | 설명 |
|---|
| 메인 | / | Hero → 공지사항 → 클래스 소개 → 하단 인원 통계 카드 (ISR revalidate: 60) |
| 반별 | /classes/[slug] | overwatch · pubg · valorant — TeacherCard, 수강 신청 링크 |
| 선생님 목록 | /teachers | /#classes로 리다이렉트 (메인 반 섹션) |
| 선생님 상세 | /teachers/[id] | 프로필, MBTI, 담당 학생, 신청 CTA |
| 수강 신청 | /apply?class={slug} | 닉네임, Discord, 플레이 시간, 담당 선생님 |
| 졸업면담 | /interview | 제출·수정, 졸업/동호회 포인트 |
| 졸업후기 | /graduation | 졸업후기 FAB (홈 등) |
| 마이페이지 | /mypage | 프로필, 서버 닉 변경, 신청·면담 내역, Discord 새로고침 |
| 로그인 | /login | Discord OAuth |
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
