🎮 정착지원국

평화로운 게임마을 — 게임 멘토링 클래스 · 수강 신청 · 선생님 관리 · 졸업면담

수달반 🦦 · 사자반 🦁 · 여우반 🦊 — 함께 성장하는 게임 클래스

🌍 프로덕션: ow-school.vercel.app · 📦 저장소: github.com/zyansuh/ow_school

---

목차

1. 프로젝트 소개
2. 사이트 이용자 역할
3. 주요 기능
4. 배정 이력 · 트랜잭션 일관성
5. 사용 기술
6. 아키텍처 · 소스 구조
7. 빠른 시작
8. 배포 · CI
9. Prisma 마이그레이션 · 인덱스
10. Discord 연동 · Bot DM
11. 포인트 · 반 안내
12. API 레퍼런스
13. 데이터 모델 · DB 운영
14. 운영 스크립트
15. 개발 규칙
16. 트러블슈팅
17. 최근 변경 요약

---

📖 이 프로젝트는?

정착지원국(브랜드명: 평화로운 게임마을, 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 ↗