vignette/docs/guides/local-development.md

# 로컬 개발 실행 가이드

Vignette(AI 심리상담 시뮬레이션 훈련 플랫폼)를 로컬에서 띄워서 테스트하기 위한 단계별 가이드다.
주 환경은 **Windows 11 + PowerShell**을 기준으로 하되, 셸 차이가 중요한 곳은 별도로 표시한다.

- 작업 디렉터리(저장소 루트): `D:\workspace\vignette`
- 모노레포 구성
  - `apps/api` — FastAPI 백엔드 (Python)
  - `apps/api/engine_gateway` — AI 턴 생성용 엔진 게이트웨이(별도 프로세스, 포트 9099)
  - `apps/web` — React 19 + Vite 프런트엔드
  - `infra` — Docker Compose 스택(pgvector pg16 + api + web + rag + proxy)
  - `scripts` — 운영/점검 스크립트

핵심 구성요소: 학습자(상담수련생)가 AI 내담자 페르소나와 회기를 진행하고, 종료 후 회기 리뷰 피드백을 받는다.
백엔드는 페르소나 엔진 · 오케스트레이터 · 저항엔진 · 마스킹 게이트 · 음성 캐스케이드 · 회기 리뷰를 소유하고,
실제 AI 발화 생성은 `engine_gateway`(ENGINE_MODE 라우팅)가 담당한다. 단일 SoR은 Postgres16+pgvector이며,
DB가 없으면 인메모리 degraded 폴백으로 기동한다.

---

## 0. 가장 빠른 경로 — 한 커맨드 (권장)

게이트웨이(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).
- 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`(기존 gateway 보존), `-NoWeb`(기존 web 보존, API만 재기동), `-NoDb`(DB 컨테이너 보장 건너뜀).
- `-NoGateway`/`-NoWeb`를 쓰면 해당 컴포넌트의 stale 정리도 건너뛰고, API 정리는 지정한 `-ApiPort` listener만 대상으로 한다. public `8001`, Tailnet `8010`, local `8000`을 나눠 띄운 상태에서 API-only 재기동할 때 다른 포트를 건드리지 않는다.
- `dev-down.ps1`은 기본적으로 DB 컨테이너를 보존한다. 컨테이너도 멈추려면 `-Db`를 명시한다.

> 스크립트는 uvicorn이 설치된 python을 자동 해석한다(시스템에 복수 python 공존 시 'python' 별칭이
> uvicorn 없는 인터프리터를 가리킬 수 있음 — 이 함정 때문에 명시 해석함).

### 0.1 Tailscale PC/모바일 접속

같은 Tailnet에 로그인한 장비에서는 아래 명령으로 Tailnet 전용 HTTPS 접속점을 켠다.

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-tailscale-runtime.ps1
```

- 현재 머신의 접속 주소: **https://alpaca-home.taile93291.ts.net**
- 이 경로는 `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` 안내로 되돌린다.

### 수동 기동(대안)

DB·엔진 없이도 UI/로그인/페르소나/세션 생성까지는 동작한다(턴 생성만 불가).

1. **API** — `apps/api`에서
   `python -m uvicorn app.main:app --host 127.0.0.1 --port 8000`
2. **웹** — `apps/web`에서 `npm run dev` → http://localhost:5173
3. (선택) **엔진 게이트웨이** — `apps/api`에서
   `python -m uvicorn engine_gateway.gateway:app --host 127.0.0.1 --port 9099`
   (실제 AI 턴 생성을 하려면 필요. `claude` CLI 설치+로그인 전제)

아래에서 각 단계를 자세히 설명한다.

---

## 1. 사전 준비

- **Python 3.11** (운영 스크립트가 Python 3.11 기준). 가상환경 권장.
- **Node.js**(최신 LTS) + npm — `apps/web`용.
- (선택) **Docker Desktop** — `infra/docker-compose.yml` 전체 스택을 띄울 때만.
- (선택) **`claude` CLI** — `ENGINE_MODE=claude_cli`로 실제 턴 생성을 할 때. 설치 후 로그인되어 있어야 한다.

### Python 의존성 설치 (`apps/api`)

```powershell
# 저장소 루트에서
python -m venv .venv
.\.venv\Scripts\Activate.ps1          # PowerShell 활성화
python -m pip install -r apps\api\requirements.txt
```

`apps/api/requirements.txt`는 `fastapi`, `uvicorn[standard]`, `asyncpg`, `pydantic`,
`pydantic-settings`, `python-multipart`, `httpx`, `sse-starlette`를 포함한다.
엔진 게이트웨이도 `fastapi`+`uvicorn`만 쓰므로 위 설치로 함께 충족된다.
(Presidio PII 마스킹은 선택 의존성이라 기본 제외 — 없으면 정규식 폴백으로 자동 degrade.)

### 웹 의존성 설치 (`apps/web`)

```powershell
cd apps\web
npm install
```

---

## 2. API 서버 실행 (FastAPI)

### 2.1 환경설정(.env 자동 로드)

설정은 전부 env 주입이며 `pydantic-settings`가 **작업 디렉터리의 `.env`를 자동 로드**한다
(`apps/api/app/config.py`의 `SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")`).
즉 **`apps/api` 디렉터리에서 uvicorn을 실행**하면 `apps/api/.env`가 자동 반영된다.

로컬 dev에서 중요한 키(이미 `apps/api/.env`에 셋업되어 있거나, 없으면 `.env.example` 참고):

| 키 | 로컬 dev 값 | 의미 |
| --- | --- | --- |
| `ENVIRONMENT` | `dev` | dev여야 DB 폴백·dev-login·seed 폴백이 허용됨 |
| `DATABASE_URL` | `postgresql://...@127.0.0.1:55432/vignette` | 미연결 시 degraded 폴백(dev 한정) |
| `ENGINE_URL` | `http://127.0.0.1:9099` | 엔진 게이트웨이 베이스 URL |
| `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`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.

### 2.2 실행

```powershell
cd apps\api
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

기동 로그에 `Application startup complete.`가 뜨면 정상이다.
프록시(아래 웹)는 `/api` 프리픽스를 제거해 이 8000 포트로 붙는다.

### 2.3 seed 페르소나로 띄우기 (선택)

기본값은 seed 미적재(`AUTO_SEED_PERSONAS=false`)다. 내장 페르소나(P1~P3)를 메모리/DB에 올려서
바로 회기를 만들고 싶으면 실행 전에 두 플래그를 켠다.

```powershell
cd apps\api
$env:AUTO_SEED_PERSONAS = "true"
$env:ALLOW_SEED_PERSONA_FALLBACK = "true"
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

`main.py` lifespan은 `settings.auto_seed_personas`가 켜져 있을 때만 `materialize_seed_personas()`를 호출한다.
(또는 `apps/api/.env`에 두 키를 `true`로 적어도 된다.)

### 2.4 DB 없이 degraded 기동 (정상 동작)

DB 연결이 안 되어도 dev에서는 그대로 기동한다. `main.py` lifespan이 풀 초기화 예외를 잡고
`store` 인메모리 폴백으로 degraded 기동하며, 다음 경고를 남긴다.

```
DB 풀 초기화 실패 — store 인메모리 폴백으로 degraded 기동: ...
```

이때 `/health`는 다음과 같이 응답한다(DB·엔진 미가용이면 `status: degraded`).

```json
{ "status": "degraded", "db": false, "engine": false, "environment": "dev", "engine_mode": "claude_cli", ... }
```

> 중요: dev에서 `db: false`는 **버그가 아니라 의도된 폴백**이다. 실제 DB가 필요하면 Postgres16+pgvector를
> `DATABASE_URL`이 가리키는 곳(로컬 dev는 `127.0.0.1:55432`)에 띄우면 된다. `ENVIRONMENT`가 dev가 아니면
> 폴백하지 않고 그대로 실패한다.

헬스 체크:

```powershell
Invoke-RestMethod http://127.0.0.1:8000/health
# 또는
curl.exe http://127.0.0.1:8000/health
```

---

## 3. dev 로그인 (로컬/E2E용 서버 로그인)

프로덕션 경로는 Google OIDC지만, 로컬에서는 dev-login으로 쿠키 세션을 바로 발급받을 수 있다.
조건: `ENVIRONMENT=dev` **그리고** `AUTH_DEV_LOGIN_ENABLED=true`, 그리고 요청 Origin/Host가 로컬이어야 한다
(`routes/auth.py`의 `_dev_login_available`). 충족 못 하면 `404 dev login is disabled`.

- 엔드포인트: `POST /auth/dev-login`
- 본문: `{ "email": ..., "role": "learner|teacher|admin", "display_name": ... }`
- `role` 기본값은 `learner`.
- 성공 시 `__Host-vignette_sid` 쿠키(및 dev 전용 `vignette_sid` 쿠키)를 세팅한다.

> 주의(이메일 도메인): dev-login도 `validate_google_identity_domain`을 거치므로 **이메일 도메인이
> `AUTH_ALLOWED_EMAIL_DOMAINS`에 있어야 한다**. 예: `learner@hs.ac.kr`. 다른 도메인이면
> `403 email domain is not allowed`.

### 3.1 PowerShell(권장) — Invoke-RestMethod + 세션 쿠키

PowerShell의 `curl`은 `Invoke-WebRequest` 별칭이라 JSON 본문·쿠키 다루기가 번거롭다.
PowerShell에서는 `Invoke-RestMethod`가 가장 깔끔하다.

```powershell
$body = '{"email":"learner@hs.ac.kr","role":"learner","display_name":"테스트 학습자"}'
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/auth/dev-login `
  -ContentType 'application/json' -Body $body -SessionVariable s

# 발급된 쿠키로 현재 사용자 확인
Invoke-RestMethod -Uri http://127.0.0.1:8000/auth/me -WebSession $s
```

### 3.2 curl.exe(셸 무관) — JSON 본문은 파일로

Windows에서 따옴표 이스케이프 사고를 피하려면 본문을 파일에 넣고 `--data-binary @file`로 보낸다.
(PowerShell에서는 반드시 `curl.exe`라고 적어 별칭이 아닌 실제 curl을 호출한다.)

```powershell
# body.json 작성
'{"email":"learner@hs.ac.kr","role":"learner","display_name":"테스트 학습자"}' |
  Out-File -Encoding ascii body.json

# 쿠키 저장(-c) + 본문은 파일(@)로
curl.exe -i -X POST http://127.0.0.1:8000/auth/dev-login `
  -H "Content-Type: application/json" --data-binary "@body.json" -c cookies.txt

# 저장한 쿠키(-b)로 재호출
curl.exe http://127.0.0.1:8000/auth/me -b cookies.txt
```

### 3.3 웹 UI

`apps/web`의 로그인 화면(`Login.tsx`)에 dev-login 경로가 있다. 웹을 띄운 상태(5173)에서
프록시를 통해 `/api/auth/dev-login`으로 동일하게 동작한다.

> 로컬/Tailnet 테스트는 dev-login을 사용한다. Google OAuth는 공개 도메인
> `https://vignette.chanpaca.net`에서만 실제 계정 흐름으로 검증한다.

---

## 4. 웹(프런트엔드) 실행

```powershell
cd apps\web
npm run dev
```

- 접속: http://localhost:5173
- 프록시: `apps/web/vite.config.ts`가 `/api` → `http://127.0.0.1:8000`로 보내며 **`/api` 프리픽스를 제거**한다.
  (`changeOrigin: true`, `ws: true`로 쿠키·WebSocket 전달.) 따라서 브라우저의 `/api/auth/me`는 백엔드의
  `/auth/me`에 도달한다.
- API가 8000에서 떠 있어야 프록시가 의미가 있다(2장 먼저 실행).

기타 웹 스크립트(`apps/web`):

```powershell
npm run typecheck   # tsc -b
npm run build       # tsc -b && vite build
npm run e2e         # Playwright (web + api + DB 스택 필요)
```

---

## 5. 엔진 게이트웨이 (AI 턴 생성)

`ENGINE_MODE=claude_cli`에서는 실제 발화 생성을 `engine_gateway`가 담당한다.
이 게이트웨이는 로컬 `claude -p`(Opus 4.8) 상주 프로세스 풀로, **컨테이너 밖(호스트)에서** 9099 포트로 실행한다.
회기 1개 = `claude -p` 프로세스 1개로 컨텍스트·프롬프트 캐시를 재사용한다.

### 5.1 실행

```powershell
cd apps\api
python -m uvicorn engine_gateway.gateway:app --host 127.0.0.1 --port 9099
```

관련 환경변수(`gateway.py`):
- `CLAUDE_BIN` — claude 실행 파일 경로(기본 `claude`). PATH에 없으면 절대경로 지정.
- `ENGINE_MODEL` — 비우면 CLI 기본(Opus 4.8), `ENGINE_FALLBACK_MODEL`, `SESSION_BUDGET_USD` 등.

### 5.2 헬스/레디 확인

게이트웨이는 두 가지 점검 엔드포인트를 제공한다.

- `GET /health` — 얕은 프로세스 liveness. `{"ok": true, "engine": "claude_p", ...}`
- `GET /ready` — **실제로 1회 생성**을 돌려 `claude -p` 인증/동작까지 증명(성공 200, 실패 503).
  설치는 됐지만 로그인 안 된 상태를 여기서 잡는다.

```powershell
Invoke-RestMethod http://127.0.0.1:9099/health
Invoke-RestMethod http://127.0.0.1:9099/ready
```

API의 `/health`는 게이트웨이의 `/ready`를 호출(404면 `/health`로 폴백)해 `engine` 필드를 채운다
(`engine_client.health_detail`). 즉 게이트웨이가 떠 있어도 `claude`가 인증 안 됐으면 `/ready`가 503이라
API `/health`의 `engine: false`가 된다.

### 5.3 프로빙 스크립트 (선택)

이미 떠 있는 게이트웨이의 스트리밍 TTFT/지연/세션 재사용을 측정한다.

```powershell
python scripts\probe-engine-gateway.py --base-url http://127.0.0.1:9099
python scripts\probe-engine-gateway.py --json     # 기계 판독용
```

기본 base-url은 `ENGINE_URL` 또는 `http://127.0.0.1:9099`. 이 스크립트는 실제 세션을 만들어 생성 호출을
하므로(예산 소모) 자격증명은 넘기지 않고 **이미 떠 있는** 게이트웨이에만 붙는다.

> 게이트웨이가 없을 때: API `/health`의 `engine: false`이고 **턴 생성은 실패**한다. 다만
> UI/네비게이션/로그인/페르소나 조회/세션 생성(in-memory)은 정상 동작한다.

---

## 6. (선택) Docker Compose 전체 스택

DB까지 포함한 통합 실행은 `infra/docker-compose.yml`(db pgvector pg16 + api + web + rag + proxy)을 쓴다.
Docker Desktop이 필요하고, `infra/.env`(템플릿: `infra/.env.example`)에 `POSTGRES_PASSWORD`,
`APP_DB_PASSWORD`, `SESSION_SECRET`, OAuth/OpenAI 키 등을 채워야 한다.

```powershell
cd infra
docker compose up -d db        # DB만
docker compose up -d           # 전체
```

엔진 게이트웨이(9099)는 컴포즈 밖 호스트에서 돌리고, api 컨테이너는
`ENGINE_URL=http://host.docker.internal:9099`로 호출한다(compose 기본값).

---

## 7. 테스트

```powershell
# 백엔드 (apps/api)
cd apps\api
python -m pytest app\ -q              # 현재 113 pass
python -m pytest engine_gateway\ -q   # 7 pass

# 웹 (apps/web)
cd apps\web
npm run typecheck
npm run build
npm run e2e                           # Playwright — web+api+DB 스택 필요
```

---

## 8. 트러블슈팅

- **포트 충돌(8000/5173/9099)**: 점유 프로세스 확인 후 종료.
  ```powershell
  Get-NetTCPConnection -LocalPort 8000 | Select-Object OwningProcess
  Stop-Process -Id <PID> -Force
  ```
  또는 uvicorn `--port`를 바꾼다(웹 프록시는 8000 가정이므로 바꾸면 `vite.config.ts` target도 함께 조정).

- **`/health`의 `db: false`**: dev에서는 정상 degraded 폴백(인메모리 store). 실제 DB가 필요하면
  `DATABASE_URL` 대상(로컬 dev `127.0.0.1:55432`)에 Postgres16+pgvector를 띄운다. `ENVIRONMENT`가 dev가
  아니면 폴백하지 않고 기동이 실패한다.

- **`/health`의 `engine: false` / 턴 생성 실패**: 게이트웨이(9099)가 안 떠 있거나 `claude` CLI가
  인증 안 됨. 게이트웨이 `GET /ready`의 `detail`을 보고 원인을 확인한다. 게이트웨이를 먼저 실행하라.

- **dev-login이 404 (`dev login is disabled`)**: `ENVIRONMENT=dev` + `AUTH_DEV_LOGIN_ENABLED=true`인지,
  요청이 로컬 Origin/Host인지 확인. `apps/api`에서 uvicorn을 실행해 `.env`가 로드됐는지도 확인.

- **dev-login이 403 (`email domain is not allowed`)**: 이메일 도메인이
  `AUTH_ALLOWED_EMAIL_DOMAINS`에 없음. `learner@hs.ac.kr` 같은 허용 도메인을 쓴다.

- **`/auth/me`가 401**: 쿠키가 전달되지 않음. curl은 `-c`/`-b`로 쿠키를 저장·재사용하고,
  PowerShell은 `-SessionVariable`/`-WebSession`을 쓴다. 브라우저는 프록시(5173) 경유로 호출해야
  `__Host-` 쿠키가 동일 출처로 붙는다.

- **PowerShell에서 `curl`이 이상하게 동작**: PowerShell `curl`은 `Invoke-WebRequest` 별칭이다.
  실제 curl을 쓰려면 `curl.exe`로 호출하고, JSON 본문은 `--data-binary "@body.json"`처럼 파일로 넘긴다.

- **한글/공백 경로**: 경로에 공백·한글이 있으면 큰따옴표로 감싼다. `.env`/JSON 파일은 UTF-8(또는 ascii)로 저장.