Vignette 저장소 README

Vignette — AI 심리상담 시뮬레이션 훈련 플랫폼. 한신대학교 산학협력(구훈정 교수) 프로젝트. 상담 수련생(학습자)이 AI 내담자 페르소나와 회기를 진행하고, 백그라운드 평가 엔진이 회기 리뷰 피드백을 제공한다. "임상 비네트(사례 삽화)"로 안전하게 연습한다는 의미에서 Vignette.

핵심 구성: 페르소나 엔진(persona_repository, SEED P1~P3) · 이론모드(humanistic 등) · 오케스트레이터(services/orchestrator.py, prepare_turn/run_turn_generate, eval_hook/log_hook 주입형) · 저항엔진(state_machine openness) · 마스킹 게이트(PII, Presidio + 정규식) · 음성 캐스케이드(STT/TTS, voice.py) · 회기 리뷰(evaluator.py deep-loop + make_eval_hook fast-loop) · 평가 KPI(SUS·자기효능감·κ/ICC·환각률) · 재귀학습(ds.* 스키마) · 데이터/SSO 거버넌스(saml.py, auth allowlist) · 회기 리뷰 공유 URL(공개 토큰 + Open Graph/요약 카드) · SEO/GEO 정적 메타(robots.txt, sitemap.xml, llms.txt).

AI 턴 생성 엔진은 별도 서비스인 engine_gateway(포트 9099)가 담당하며 ENGINE_MODE로 백엔드를 고른다(claude_cli / claude_api / openai / solar). 저장소(SoR)는 PostgreSQL 16 + pgvector 단일 출처, 미가용 시 store.py 인메모리 degraded 폴백.

---

1. 모노레포 구조

경로	설명
apps/api/	FastAPI/Python 백엔드. 오케스트레이터·페르소나·저항엔진·마스킹·음성·평가·인증. 엔진 게이트웨이(apps/api/engine_gateway/) 포함
apps/web/	React 19 + Vite 프론트엔드(3역할: 관리자/교수자/학습자). Playwright E2E
docs/	설계·운영 문서. docs/dev_dashboard.html이 SSOT(단일 진실 공급원)
infra/	Docker Compose 스택(db=pgvector pg16, api, web, proxy=Caddy) 및 .env.example
scripts/	운영 스크립트(PowerShell/Python): 공개 런타임 기동·감시, 엔진 게이트웨이 프로브, Postgres RLS 감사 등

---

2. 빠른 시작 (로컬 dev)

주 개발 환경은 Windows 11 + PowerShell. 아래는 PowerShell 기준 최소 명령이다. (엔진 게이트웨이가 없어도 UI·로그인·페르소나·세션 생성(in-memory)·네비게이션은 동작하며, 실제 AI 턴 생성만 실패한다. DB가 없어도 인메모리 degraded로 기동된다.)

2-1. API 백엔드

cd apps\api
# 로컬 dev 기본값 복사 (pydantic-settings가 apps/api/.env 를 자동 로드)
Copy-Item ..\..\.env.example .env
# (선택) seed 페르소나가 필요하면 기동 전에 환경변수 설정
$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

• 기동 로그에 Application startup complete 가 뜨면 정상. DB 연결 실패 시 store 인메모리 degraded로 기동되고 GET /health 는 {"status":"degraded","db":false,...} 를 반환한다.
• dev 로그인 활성 조건: .env 에 ENVIRONMENT=dev, AUTH_DEV_LOGIN_ENABLED=true (루트 .env.example 기본값에 이미 포함).

2-2. Web 프론트엔드

cd apps\web
npm install
npm run dev    # http://localhost:5173

• Vite dev 서버는 /api 요청을 http://127.0.0.1:8000 으로 프록시하고 /api 프리픽스를 제거한다 (예: /api/auth/dev-login → 백엔드 /auth/dev-login).

2-3. dev-login 으로 진입

웹 UI의 로그인 화면에서 dev-login 경로로 들어가거나, 직접 호출한다.

# 웹 프록시 경유 (web dev 서버가 떠 있을 때)
curl -X POST http://localhost:5173/api/auth/dev-login `
  -H "Content-Type: application/json" `
  -d '{"email":"learner@hs.ac.kr","role":"learner","display_name":"테스트 학습자"}'

• 요청 바디: email(필수), role(learner | teacher | admin, 기본 learner), display_name(선택).
• 성공 시 __Host-vignette_sid 세션 쿠키가 발급된다.
• 로그인 후 신규 사용자 또는 온보딩 미완료 사용자는 /onboarding에서 닉네임, 자기소개, 선택 아바타 이미지, 이름, 소속, 학과, 학년/직위, 전화번호, 주소/수령지와 약관·개인정보 동의를 완료해야 역할 홈과 학습 회기 시작이 열린다.

2-4. (선택) AI 턴 생성용 엔진 게이트웨이

ENGINE_MODE=claude_cli 인 경우 호스트에서 게이트웨이를 9099 포트로 띄운다(claude CLI 사용).

cd apps\api
uvicorn engine_gateway.gateway:app --host 0.0.0.0 --port 9099

게이트웨이가 없으면 GET /health 의 engine:false 이고 턴 생성만 실패한다.

2-5. 테스트 / 검증

# 백엔드
cd apps\api;  python -m pytest app/ -q          # 백엔드 기준선 178 pass
python -m pytest engine_gateway/ -q             # 현재 23 pass
# 프론트엔드
cd apps\web;  npm run typecheck                 # tsc -b
npm run build                                   # tsc -b && vite build
npm run e2e                                     # Playwright (web + api + DB 스택 필요)

2-6. (선택) Docker Compose 전체 스택

cd infra
Copy-Item .env.example .env    # 실제 시크릿은 .env 에만
docker compose up -d           # db(pgvector pg16) + api + web + proxy(Caddy)

Docker Desktop이 필요하다. RAG 모델 의존성까지 API 이미지에 넣을 때만 INSTALL_RAG=true를 infra/.env에 둔다. 다른 환경에 심기 전에는 저장소 루트에서 python scripts\check-deploy-preflight.py --env-file infra\.env를 먼저 실행해 고정 의존성, 라이브 코칭 data/kb source pack, 운영 env를 확인한다.

---

3. 주요 문서

문서	용도
docs/dev_dashboard.html	SSOT(단일 진실 공급원) — 상태·검증 증거·결정 필요·로드맵의 권위 기준
docs/ops/backlog-2026-06-26.md	운영 백로그(B1 코스메틱 · B2 환경제약 · B3 소유자결정 · B4 외부거버넌스). 대시보드와 일치
docs/guides/source-docs-and-gaps.md	원천문서·갭 로드맵 요약(대시보드 상태와 동기화)
docs/ops/source-docs-gap-analysis-2026-06-26.md	원천문서 갭 분석 상세 근거
docs/guides/local-development.md	로컬 개발 환경 구축·실행 상세 가이드
docs/guides/architecture.md	시스템 아키텍처(엔진/오케스트레이터/저항/마스킹/음성/평가/데이터) 상세
docs/guides/testing.md	테스트·검증(pytest, typecheck, Playwright E2E 게이트) 가이드
AGENTS.md	작업·에이전트 운영 지침의 원본(OS 선파악, 증거 정직성, SSOT 동기화). CLAUDE.md / AGENT.md는 호환성 진입점

참고 설계 문서: docs/MASTERPLAN.md(마스터플랜) · docs/HANDOFF.md(인수인계) · docs/DEPLOYMENT.md(배포) · docs/DESIGN_CONCEPT.md(디자인 컨셉) · docs/MEMORY_KNOWLEDGE_PERSONA_DESIGN.md(메모리·지식·페르소나).

---

4. 핵심 운영 원칙

1. OS를 먼저 파악하고 시작한다(최우선). 주 환경은 Windows 11 + PowerShell. POSIX를 가정하지 말고 경로·인코딩·도구 가용성을 먼저 확정한다(한글·공백 경로 주의, 파일 출력은 -Encoding utf8). 자세한 내용은 AGENTS.md 규칙 0.
2. 가짜 증거로 DONE 표기 금지. 실증 불가/외부 의존/소유자 결정 항목은 docs/ops/backlog-*.md 에 분류·추적하고, 변경 후 검증(typecheck / pytest / E2E 게이트)을 실제로 돌려 결과를 그대로 보고한다.
3. docs/dev_dashboard.html 이 SSOT. 새 발견·작업 결과·상태 변경은 별도 문서로만 남기지 말고 대시보드에 반영·동기화한다. 백로그가 대시보드와 어긋나면 대시보드를 기준으로 맞춘다.
4. 소유자(윤찬) 단독 결정 사안은 임의로 정하지 않는다(월권 금지).
5. 모든 소통·주석·커밋 메시지는 한글. 커밋 메시지에 Co-Authored-By / Claude 관련 문구 금지.