개선관리 요구사항과 Google 로그인을 완료

docs/guides/local-development.md

@@ -177,10 +177,10 @@ npm install
 | `ENGINE_GATEWAY_SHARED_SECRET` | 빈 값 | 선택 인증. NAS/원격 preview에서는 API와 gateway에 동일한 32자 이상 비-placeholder 값을 설정. 빈 값은 기존 로컬 9099 호환 |
 | `VIGNETTE_LIVE_CLIENT_PROVIDER` | `claude_cli` | 실시간 내담자 AI 전용 lane. 관리자에서 선택한 evaluator/review 공급자와 분리해 회기별 Claude 상주 세션을 재사용 |
 | `AUTH_DEV_LOGIN_ENABLED` | `true` | dev-login 엔드포인트 활성화 |
-| `AUTH_ALLOWED_EMAIL_DOMAINS` | `["hs.ac.kr","twentyoz.kr"]` | 기본 로그인 허용 이메일 도메인(dev-login 포함 검증). `/admin/users`에 미리 등록된 정확한 이메일은 도메인 밖이어도 예외로 로그인 가능 |
+| `AUTH_ALLOWED_EMAIL_DOMAINS` | `["hs.ac.kr","twentyoz.kr"]` | dev-login·SAML 조직 정책용 도메인 목록. Google OIDC는 이 목록을 적용하지 않고 provider-verified 이메일을 모두 허용 |
 | `AUTH_SUPER_ADMIN_EMAILS` | `["yunchan@twentyoz.kr","hoonjungkoo@hs.ac.kr"]` | 학습자·교수자·관리자 공간 접근과 승인 상태를 부여할 슈퍼 관리자 이메일 |
-| `AUTH_APPROVED_EMAILS` | `[]` | 신규 외부 로그인 시 pending 없이 바로 승인할 이메일 allowlist |
-| `AUTH_NEW_USER_DEFAULT_STATUS` | `pending` | Google/SAML 신규 사용자의 기본 승인 상태. `dev:` 로그인은 로컬/E2E 편의를 위해 자동 승인 |
+| `AUTH_APPROVED_EMAILS` | `[]` | SAML/dev 등 비-Google 신규 로그인에서 pending 없이 바로 승인할 이메일 allowlist |
+| `AUTH_NEW_USER_DEFAULT_STATUS` | `pending` | SAML 등 비-Google 신규 사용자의 기본 승인 상태. Google은 항상 approved, `dev:` 로그인은 로컬/E2E 편의를 위해 자동 승인 |
 | `AUTH_EMAIL_COHORT_MAP` | `{}` | 특정 이메일을 cohort id로 매핑한다. 값은 comma-separated 문자열도 허용 |
 | `AUTH_DOMAIN_COHORT_MAP` | `{}` | 이메일/Google hosted domain을 cohort id로 매핑한다. Google/SAML/dev-login 세션 `cohort_ids`에 반영 |
 | `VIGNETTE_MELOTTS_TTS_URL` | `http://127.0.0.1:9883` | 로컬 MeloTTS 한국어 사이드카. `scripts/start-melotts.ps1`로 띄운다 |
@@ -356,20 +356,25 @@ C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\mainta
 - `role` 기본값은 `learner`.
 - 성공 시 `__Host-vignette_sid` 쿠키(및 dev 전용 `vignette_sid` 쿠키)를 세팅한다.
 - dev-login 사용자는 로컬/E2E 흐름 유지를 위해 `account_status=approved`로 생성된다.
-- Google/SAML 신규 사용자는 기본적으로 `account_status=pending`이며, 승인 전에는 `/pending` 화면만 볼 수 있다.
+- Google OIDC 신규 사용자는 provider가 이메일을 검증하면 도메인·사전등록 없이 learner·`approved`로 생성된다.
+  기존 pending Google 계정도 로그인 시 approved로 승격하지만 suspended 계정은 그대로 차단한다.
+- SAML 등 비-Google 신규 사용자는 기본적으로 `account_status=pending`이며, 승인 전에는 `/pending` 화면만 볼 수 있다.
   관리자 콘솔 `/admin/users`의 가입 승인 탭에서 `approved`로 바꾸면 역할 홈에 접근한다.
   DB가 연결되어 있으면 pending 생성 시 `app.notification_event`/`app.notification_delivery`에 가입 승인
   메일 큐가 생긴다. `NOTIFICATION_EMAIL_PROVIDER=disabled`인 로컬 기본값에서는 실제 메일은 발송하지 않는다.
+- 관리자 콘솔의 외부 연구참여자 사전등록은 `POST /admin/users`에서 항상 `pending`으로만 생성한다.
+  생성 요청으로 즉시 승인할 수 없고, 관리자가 승인 큐에서 별도 `PATCH /admin/users/{user_id}`를 보내야
+  `approved`가 된다. exact-email 사전등록이지 공개 무제한 회원가입이 아니다.
 - 신규 사용자 또는 온보딩 미완료 사용자는 로그인 직후 `/onboarding`에서 닉네임, 자기소개,
   선택 아바타 이미지, 이름, 소속, 학과, 학년/직위, 전화번호, 주소/수령지와 약관·개인정보
   동의를 저장해야 역할 홈으로 이동한다. 학습자 회기 시작은 온보딩 완료와 동의가 모두 있어야 한다.
 - 프로필 아바타 업로드는 API 작업 디렉터리 기준 `USER_UPLOAD_DIR`(기본 `uploads`) 아래
   `profile-avatars/`에 저장되고, `/uploads/profile-avatars/...` URL로 서빙된다.
 
-> 주의(이메일 도메인): dev-login도 기본적으로 `validate_google_identity_domain`을 거치므로
+> 주의(이메일 도메인): 이 제한은 dev-login·SAML 조직 정책에만 적용된다. dev-login은
 > 이메일 도메인이 `AUTH_ALLOWED_EMAIL_DOMAINS`에 있어야 한다. 예: `learner@hs.ac.kr`.
 > 단, 관리자가 `/admin/users`에 미리 등록한 정확한 이메일은 도메인 밖이어도 로그인할 수 있다.
-> 미등록 외부 도메인은 계속 `403 email domain is not allowed`.
+> Google OIDC는 provider-verified 이메일이면 도메인과 사전등록 여부를 묻지 않는다.
 
 ### 3.1 메일 알림 큐 확인/처리
 
@@ -470,6 +475,24 @@ DB 없이 CLI shape만 확인하려면:
 py -3.11 scripts\sync-persona-sources.py --help
 ```
 
+### 3.6 개선관리 migration 17과 프로토콜 레지스트리
+
+새 Postgres volume은 `infra/db/init/`의 번호순 init으로 migration 17까지 적용한다. 이미 존재하는 DB는
+애플리케이션 역할이 startup에서 테이블을 만들지 않으므로 owner DSN으로 한 번 적용해야 한다.
+
+```powershell
+cd D:\workspace\vignette
+psql.exe "$env:VIGNETTE_OWNER_DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction `
+  -f infra\db\init\17_improvement_workbook_contracts.sql
+```
+
+`protocol_registry.ensure_protocol_tables()`는 readiness `SELECT`만 실행한다. 계약이 없으면 migration 17을
+적용하라는 오류로 fail-closed하며 app-role DDL fallback은 없다. 적용 후 admin dev-login으로
+`GET /admin/protocols`, `POST /admin/protocols`, `POST /admin/protocols/{id}/activate`,
+`POST /admin/protocols/{id}/retire`를 사용할 수 있다. lifecycle은 `draft → active → retired`이고,
+활성화는 라이선스·`external_llm_ok` 검증과 evaluator-only RAG 색인이 한 트랜잭션에서 성공해야 끝난다.
+라이선스 C/D는 외부 LLM 사용을 허용할 수 없다.
+
 ---
 
 ## 4. 웹(프런트엔드) 실행
@@ -540,9 +563,11 @@ Invoke-RestMethod 'http://127.0.0.1:9099/ready?provider=codex_cli&model=gpt-5.6-
 Invoke-RestMethod 'http://127.0.0.1:9099/v1/capabilities?provider=codex_cli&force=true' -Headers $headers
 ```
 
-API의 `/health`는 현재 DB 설정의 provider/model/reasoning_effort를 게이트웨이 `/ready`에 전달하고
-(구형 게이트웨이는 `/health`로 폴백) `engine` 필드를 채운다. 따라서 프로세스만 떠 있고 선택한 CLI/API가
-미인증이거나 모델 조합을 실행할 수 없으면 API `/health`의 `engine: false`가 된다.
+API의 `/health`는 현재 DB 설정의 provider/model/reasoning_effort와
+`VIGNETTE_LIVE_CLIENT_PROVIDER` 전용 내담자 lane을 각각 게이트웨이 `/ready`로 확인한다
+(구형 게이트웨이는 `/health`로 폴백). 기본 evaluator 조합이 준비됐더라도 live-client 공급자가 준비되지
+않으면 `status=degraded`, `engine=false`다. 따라서 프로세스만 떠 있고 선택한 CLI/API가 미인증이거나
+어느 필수 모델 조합도 실행할 수 없으면 준비 완료로 보지 않는다.
 
 ### 5.3 프로빙 스크립트 (선택)
 
@@ -610,8 +635,8 @@ RAG 임베딩/리랭커 의존성은 기본 이미지에 설치하지 않는다.
 ```powershell
 # 백엔드 (apps/api)
 cd apps\api
-python -m pytest app/ -q              # 백엔드 기준선 432 pass
-python -m pytest engine_gateway\ -q   # 현재 44 pass
+python -m pytest app/ -q              # 2026-08-28 전체 실행 1002 passed
+python -m pytest engine_gateway\ -q   # 2026-08-28 전체 실행 68 passed
 
 # 웹 (apps/web)
 cd apps\web
@@ -636,7 +661,15 @@ npm run e2e                           # Playwright — web+api+DB 스택 필요
   아니면 폴백하지 않고 기동이 실패한다.
 
 - **`/health`의 `engine: false` / 턴 생성 실패**: 게이트웨이(9099)가 안 떠 있거나 `claude` CLI가
-  인증 안 됨. 게이트웨이 `GET /ready`의 `detail`을 보고 원인을 확인한다. 게이트웨이를 먼저 실행하라.
+  인증 안 됐거나 기본 evaluator/live-client 중 하나가 준비되지 않음. 게이트웨이 `GET /ready`의 `detail`과
+  `VIGNETTE_LIVE_CLIENT_PROVIDER`를 함께 확인한다. 게이트웨이를 먼저 실행하라.
+
+- **SSE가 token 뒤 조용히 끝나고 턴이 저장되지 않음**: gateway의 구조화 `done` 없이 EOF가 온 경우다.
+  서버는 `client_stream_incomplete`로 fail-closed하며 provider `[DONE]`만으로 성공 처리하지 않는다.
+  게이트웨이 로그와 `/ready`를 확인하고 재시도하라.
+
+- **프로토콜 레지스트리 readiness 실패 / migration 17 요구**: app-role로 DDL을 시도하지 않는다.
+  기존 DB에 owner DSN으로 `17_improvement_workbook_contracts.sql`을 적용한 뒤 API를 다시 기동한다.
 
 - **dev-login이 404 (`dev login is disabled`)**: `ENVIRONMENT=dev` + `AUTH_DEV_LOGIN_ENABLED=true`인지,
   요청이 로컬 Origin/Host인지 확인. `apps/api`에서 uvicorn을 실행해 `.env`가 로드됐는지도 확인.