현재 작업 전체 반영

docs/guides/local-development.md

@@ -20,18 +20,21 @@ DB가 없으면 인메모리 degraded 폴백으로 기동한다.
 
 ## 0. 가장 빠른 경로 — 한 커맨드 (권장)
 
-게이트웨이(9099)+API(8000)+웹(5173)을 한 번에 깔끔히 (재)기동한다. 기존/고아 프로세스를
-커맨드라인 기준으로 정리한 뒤 결정론적으로 띄운다(`--reload` 워처 불안정 회피).
+게이트웨이(9099)+API(8000)+웹(5173)을 한 번에 깔끔히 (재)기동한다. Docker가 사용 가능하면
+`vignette-dev-db` Postgres(pgvector) 컨테이너도 보장하고 health/role을 점검한다. 기존/고아
+프로세스는 커맨드라인 기준으로 정리한 뒤 결정론적으로 띄운다(`--reload` 워처 불안정 회피).
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-up.ps1
 # 종료: powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-down.ps1
+# DB 컨테이너까지 멈출 때만: powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-down.ps1 -Db
 ```
 
 - 진입점 **http://localhost:5173** → 로그인 페이지에서 **dev-login**(아무 `@hs.ac.kr`, role learner/teacher/admin).
-- DB 없이 in-memory degraded로 뜨고, seed 페르소나(P1~P3)·AI 턴 생성까지 동작.
+- Docker가 있으면 기본적으로 `127.0.0.1:55432` DB 컨테이너를 사용한다. 새 컨테이너 생성 시 `POSTGRES_USER=vignette_owner`, API용 앱 role은 `DATABASE_URL` 사용자로 분리해 RLS 검증 기반을 보존한다. Docker가 없거나 `-NoDb`를 쓰면 in-memory degraded로 뜬다.
 - 로그는 `.devlogs/`(gitignore). 코드 수정 후에는 dev-up을 다시 실행해 재기동(reload 미사용).
-- 옵션: `-NoGateway`(UI만), `-NoWeb`(API만).
+- 옵션: `-NoGateway`(UI만), `-NoWeb`(API만), `-NoDb`(DB 컨테이너 보장 건너뜀).
+- `dev-down.ps1`은 기본적으로 DB 컨테이너를 보존한다. 컨테이너도 멈추려면 `-Db`를 명시한다.
 
 > 스크립트는 uvicorn이 설치된 python을 자동 해석한다(시스템에 복수 python 공존 시 'python' 별칭이
 > uvicorn 없는 인터프리터를 가리킬 수 있음 — 이 함정 때문에 명시 해석함).
@@ -48,6 +51,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-tailscale-runt
 - 이 경로는 `tailscale serve`로 `https://alpaca-home.taile93291.ts.net` → 로컬 web `127.0.0.1:5173`을 연결한다.
 - API는 Tailnet 전용으로 `127.0.0.1:8010`에 뜨고, Vite proxy는 `VITE_API_PROXY_TARGET`으로 이 포트를 본다. 기존 8000 reloader 잔류와 충돌하지 않기 위해 분리했다.
 - dev-login은 `AUTH_DEV_LOGIN_EXTRA_ORIGINS`에 Tailnet origin이 들어간 경우에만 dev 환경에서 열린다. prod에서는 열리지 않는다.
+- Tailnet/로컬 dev에서는 Google OAuth를 사용하지 않는다. OAuth redirect URI가 공개 API callback으로 고정된 동안에는 콜백이 로컬/Tailnet 세션이 아니라 공개 API 세션으로 돌아가므로, 로그인 화면은 Google 버튼을 비활성화하고 직접 `/api/auth/login?provider=google`을 열어도 `local_oauth_unavailable` 안내로 되돌린다.
 
 ### 수동 기동(대안)
 
@@ -112,6 +116,8 @@ npm install
 | `ENGINE_MODE` | `claude_cli` | 엔진 provider 라우팅 |
 | `AUTH_DEV_LOGIN_ENABLED` | `true` | dev-login 엔드포인트 활성화 |
 | `AUTH_ALLOWED_EMAIL_DOMAINS` | `["hs.ac.kr","twentyoz.kr"]` | 로그인 허용 이메일 도메인(dev-login 포함 검증) |
+| `AUTH_EMAIL_COHORT_MAP` | `{}` | 특정 이메일을 cohort id로 매핑한다. 값은 comma-separated 문자열도 허용 |
+| `AUTH_DOMAIN_COHORT_MAP` | `{}` | 이메일/Google hosted domain을 cohort id로 매핑한다. Google/SAML/dev-login 세션 `cohort_ids`에 반영 |
 | `VIGNETTE_VOICE_POC_SAMPLE_TTS` | `false` | P1 무참조 샘플 음성을 `/voice/ws` TTS에 연결하는 개발 전용 플래그. 마이크/STT는 `OPENAI_API_KEY` 필요, 프로덕션 금지 |
 
 > 참고: 프로세스 환경변수(`$env:KEY`)는 `.env`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.
@@ -222,6 +228,9 @@ curl.exe http://127.0.0.1:8000/auth/me -b cookies.txt
 `apps/web`의 로그인 화면(`Login.tsx`)에 dev-login 경로가 있다. 웹을 띄운 상태(5173)에서
 프록시를 통해 `/api/auth/dev-login`으로 동일하게 동작한다.
 
+> 로컬/Tailnet 테스트는 dev-login을 사용한다. Google OAuth는 공개 도메인
+> `https://vignette.chanpaca.net`에서만 실제 계정 흐름으로 검증한다.
+
 ---
 
 ## 4. 웹(프런트엔드) 실행
@@ -320,7 +329,7 @@ docker compose up -d           # 전체
 ```powershell
 # 백엔드 (apps/api)
 cd apps\api
-python -m pytest app\ -q              # 현재 98 pass
+python -m pytest app\ -q              # 현재 113 pass
 python -m pytest engine_gateway\ -q   # 7 pass
 
 # 웹 (apps/web)