메일 알림 시스템 추가

docs/guides/local-development.md

@@ -142,6 +142,8 @@ npm install
 | `EVALUATOR_SEMANTIC_CACHE_ENABLED` | `true` | fast/deep evaluator structured 결과 인메모리 캐시 활성화. 원문 prompt/completion은 저장하지 않음 |
 | `EVALUATOR_SEMANTIC_CACHE_TTL_SECONDS` | `900` | evaluator cache TTL(초). 0 이하면 비활성 |
 | `EVALUATOR_SEMANTIC_CACHE_MAX_ENTRIES` | `256` | evaluator cache LRU 최대 엔트리 수. 0 이하면 비활성 |
+| `NOTIFICATION_EMAIL_PROVIDER` | `disabled` | 운영 메일 provider. 실제 발송은 `smtp`와 `SMTP_*` 설정이 있을 때만 수행 |
+| `SMTP_HOST` / `SMTP_FROM_EMAIL` | 빈 값 | `NOTIFICATION_EMAIL_PROVIDER=smtp`일 때 필요한 SMTP 호스트와 발신 주소 |
 
 > 참고: 프로세스 환경변수(`$env:KEY`)는 `.env`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.
 
@@ -266,6 +268,8 @@ C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\mainta
 - dev-login 사용자는 로컬/E2E 흐름 유지를 위해 `account_status=approved`로 생성된다.
 - Google/SAML 신규 사용자는 기본적으로 `account_status=pending`이며, 승인 전에는 `/pending` 화면만 볼 수 있다.
   관리자 콘솔 `/admin/users`의 가입 승인 탭에서 `approved`로 바꾸면 역할 홈에 접근한다.
+  DB가 연결되어 있으면 pending 생성 시 `app.notification_event`/`app.notification_delivery`에 가입 승인
+  메일 큐가 생긴다. `NOTIFICATION_EMAIL_PROVIDER=disabled`인 로컬 기본값에서는 실제 메일은 발송하지 않는다.
 - 신규 사용자 또는 온보딩 미완료 사용자는 로그인 직후 `/onboarding`에서 닉네임, 자기소개,
   선택 아바타 이미지, 이름, 소속, 학과, 학년/직위, 전화번호, 주소/수령지와 약관·개인정보
   동의를 저장해야 역할 홈으로 이동한다. 학습자 회기 시작은 온보딩 완료와 동의가 모두 있어야 한다.
@@ -277,7 +281,24 @@ C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\mainta
 > 단, 관리자가 `/admin/users`에 미리 등록한 정확한 이메일은 도메인 밖이어도 로그인할 수 있다.
 > 미등록 외부 도메인은 계속 `403 email domain is not allowed`.
 
-### 3.1 PowerShell(권장) — Invoke-RestMethod + 세션 쿠키
+### 3.1 메일 알림 큐 확인/처리
+
+가입 승인과 교수자 회기 검토 알림은 상태 원본이 아니라 보조 알림이다. 원본 상태는 각각
+`app.app_user.account_status`, `app.session_review_status`이고, 메일 전송 상태만
+`app.notification_delivery`에 남는다.
+
+```powershell
+cd D:\workspace\vignette
+# SMTP 설정이 준비된 환경에서 큐를 한 번 처리
+python scripts\run-notification-worker.py --limit 25
+```
+
+관리자 API에서도 `GET /admin/notifications`로 최근 delivery를 보고,
+`POST /admin/notifications/process`로 한 번 처리할 수 있다. `POST /admin/notifications/test`는 관리자
+수신자에게 테스트 메일 이벤트를 만들고 같은 큐로 즉시 처리한다. 메일 본문에는 축어록이나 평가 전문을 넣지 않고,
+`/admin/users`, `/teach/session/:sessionId/review`, `/admin` 링크만 제공한다.
+
+### 3.2 PowerShell(권장) — Invoke-RestMethod + 세션 쿠키
 
 PowerShell의 `curl`은 `Invoke-WebRequest` 별칭이라 JSON 본문·쿠키 다루기가 번거롭다.
 PowerShell에서는 `Invoke-RestMethod`가 가장 깔끔하다.
@@ -291,7 +312,7 @@ Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/auth/dev-login `
 Invoke-RestMethod -Uri http://127.0.0.1:8000/auth/me -WebSession $s
 ```
 
-### 3.2 curl.exe(셸 무관) — JSON 본문은 파일로
+### 3.3 curl.exe(셸 무관) — JSON 본문은 파일로
 
 Windows에서 따옴표 이스케이프 사고를 피하려면 본문을 파일에 넣고 `--data-binary @file`로 보낸다.
 (PowerShell에서는 반드시 `curl.exe`라고 적어 별칭이 아닌 실제 curl을 호출한다.)
@@ -309,7 +330,7 @@ curl.exe -i -X POST http://127.0.0.1:8000/auth/dev-login `
 curl.exe http://127.0.0.1:8000/auth/me -b cookies.txt
 ```
 
-### 3.3 웹 UI
+### 3.4 웹 UI
 
 `apps/web`의 로그인 화면(`Login.tsx`)에 dev-login 경로가 있다. 웹을 띄운 상태(5173)에서
 프록시를 통해 `/api/auth/dev-login`으로 동일하게 동작한다.
@@ -317,7 +338,7 @@ curl.exe http://127.0.0.1:8000/auth/me -b cookies.txt
 > 로컬/Tailnet 테스트는 dev-login을 사용한다. Google OAuth는 공개 도메인
 > `https://vignette.chanpaca.net`에서만 실제 계정 흐름으로 검증한다.
 
-### 3.4 라이브 코칭 source pack RAG 색인
+### 3.5 라이브 코칭 source pack RAG 색인
 
 `data/kb/live_coaching_workbook_0615.json`와 `data/kb/live_coaching_sources/*.json`는 라이브 코칭의
 기본 근거 source pack이다. API가 DB와 연결된 상태라면 관리자 dev-login 쿠키로 같은 자료를 RAG KB에도