대시보드 폴드아웃/드릴다운 정리 + 페르소나 역린·misconduct 반응 + 게이트웨이 격리·RAG 비차단 수정

SSOT 대시보드: - 한신대 기술분석 PDF(19쪽) 정합성 분석 + 이번 세션 발견 섹션 추가 - 섹션 폴드아웃(접기)·상단 목차(드릴다운)·모두 펼치기/접기 — 내용 보존, 레이아웃만 정리 페르소나 반응 강화('저항·반응 조절' 핵심 차별): - PersonaCard.triggers(역린) 필드 + CCD 핵심상처 파생 역린 블록 - L0에 무례·모욕·조롱 시 현실적 동맹 균열 반응 지침 버그·성능 수정(라이브/E2E로 포착): - 게이트웨이 페르소나 격리: --append-system-prompt를 --system-prompt(교체)로 + --exclude-dynamic-system-prompt-sections (내담자 캐릭터 붕괴·개발맥락 누출 차단) - RAG: 임베더 동기 로드(약 7-13초)를 _warm_rag_caches 백그라운드 warm으로(세션 생성 블로킹 회귀 수정) - voice TTS RMS 데드힌트 제거, init_state OpennessParams 파라미터객체화 - 한국어 PII(날짜·금액·주소) 마스킹 보강 - 레이아웃 시각 게이트: 폼 컨트롤 값 스크롤 오탐 제외(7/7) 검증: 백엔드 84/84, E2E 42(데스크톱 27·모바일 11·아바타 4), 시각 게이트 7/7
2026-06-27 02:30:46 +09:00 · 2026-06-27 02:30:46 +09:00 · 085460b5e0
commit 085460b5e0
parent cb2aebd76c
327 changed files with 31226 additions and 1829 deletions
--- a/README.md
+++ b/README.md
@ -1,46 +1,143 @@
-# Vignette
+# Vignette 저장소 README

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

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

-```
-vignette/
-├ apps/
-│  ├ web/    React 19 프론트엔드 (3역할: 관리자/교수자/학습자, 추후 RN 네이티브)
-│  └ api/    FastAPI 백엔드 (엔진 어댑터·상태머신·가드레일·RAG)
-├ infra/     Docker Compose (web·api·postgres·voice gateway)
-└ docs/      설계 문서 (SoT)
-```
+---

-## 핵심 설계 (docs/)
+## 1. 모노레포 구조

-| 문서 | 내용 |
+| 경로 | 설명 |
 |---|---|
-| `docs/MASTERPLAN.md` | 시스템 마스터플랜 (아키텍처·로드맵·스택) |
-| `docs/redteam/REDTEAM_FINDINGS.md` | 적대검증 40결함 |
-| `docs/redteam/MASTERPLAN_REVISIONS.md` | 재설계 패치 (claude -p 1급 엔진 복원 등) |
-| `docs/MEMORY_KNOWLEDGE_PERSONA_DESIGN.md` | 메모리·지식·페르소나 (회기 간 연속성) |
-| `docs/DESIGN_CONCEPT.md` | 디자인 컨셉 (토큰·아바타·화면) |
-| `docs/mockups/` | 화면 레이아웃 시안 (HTML) |
+| `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`, `rag`, `proxy`=Caddy) 및 `.env.example` |
+| `scripts/` | 운영 스크립트(PowerShell/Python): 공개 런타임 기동·감시, 엔진 게이트웨이 프로브, Postgres RLS 감사 등 |

-## 확정 스택
+---

- **엔진**: 로컬 Opus 4.8 `claude -p` 상주 멀티턴 풀(`--input-format stream-json`), Anthropic Messages API 폴백
- **프론트**: React 19 + SSE (pnpm/Turborepo 모노레포, 추후 React Native)
- **백엔드**: FastAPI + SSE 스트리밍
- **DB**: NAS PostgreSQL 16 + pgvector
- **RAG**: BGE-M3 + 하이브리드 + Contextual Retrieval + BGE-reranker-v2-m3
- **음성**: OpenAI 캐스케이드(STT→LLM→TTS), 멀티보이스 + 페르소나
- **인증**: OAuth 2.1 (BFF, 3역할 RBAC, visible_to 정보비대칭)
- **배포**: Docker Compose, chanpaca.net 외부노출(교수 테스트)
+## 2. 빠른 시작 (로컬 dev)

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

-① 심리상담사 AI(선택) ② 가상 내담자 AI ③ 백그라운드 평가/교수 AI — 정보 비대칭을 DB `visible_to`가 강제.
+### 2-1. API 백엔드

-## 상태
+```powershell
+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
+```

-설계 완료, 구현 착수 단계 (Phase 0 기반정렬 → P1 텍스트 상담 MVP → P2 음성+3역할 → P3 파일럿).
+- 기동 로그에 `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 프론트엔드
+
+```powershell
+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 경로로 들어가거나, 직접 호출한다.
+
+```powershell
+# 웹 프록시 경유 (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` 세션 쿠키가 발급된다.
+
+### 2-4. (선택) AI 턴 생성용 엔진 게이트웨이
+
+`ENGINE_MODE=claude_cli` 인 경우 호스트에서 게이트웨이를 9099 포트로 띄운다(claude CLI 사용).
+
+```powershell
+cd apps\api
+uvicorn engine_gateway.gateway:app --host 0.0.0.0 --port 9099
+```
+
+게이트웨이가 없으면 `GET /health` 의 `engine:false` 이고 턴 생성만 실패한다.
+
+### 2-5. 테스트 / 검증
+
+```powershell
+# 백엔드
+cd apps\api;  python -m pytest app/ -q          # 현재 약 77 pass
+python -m pytest engine_gateway/ -q             # 약 7 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 전체 스택
+
+```powershell
+cd infra
+Copy-Item .env.example .env    # 실제 시크릿은 .env 에만
+docker compose up -d           # db(pgvector pg16) + api + web + rag + proxy(Caddy)
+```
+
+Docker Desktop이 필요하다.
+
+---
+
+## 3. 주요 문서
+
+| 문서 | 용도 |
+|---|---|
+| **`docs/dev_dashboard.html`** | **SSOT(단일 진실 공급원)** — 상태·검증 증거·결정 필요·로드맵의 권위 기준 |
+| `docs/ops/backlog-2026-06-26.md` | 운영 백로그(B1 코스메틱 · B2 환경제약 · B3 소유자결정 · B4 외부거버넌스). 대시보드와 일치 |
+| `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 게이트) 가이드 |
+| `CLAUDE.md` / `AGENT.md` | 작업·에이전트 운영 지침(OS 선파악, 증거 정직성, SSOT 동기화) |
+
+참고 설계 문서: `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`). 자세한 내용은 `CLAUDE.md` / `AGENT.md` 규칙 0.
+2. **가짜 증거로 DONE 표기 금지.** 실증 불가/외부 의존/소유자 결정 항목은
+   `docs/ops/backlog-*.md` 에 분류·추적하고, 변경 후 검증(typecheck / pytest / E2E 게이트)을
+   실제로 돌려 결과를 그대로 보고한다.
+3. **`docs/dev_dashboard.html` 이 SSOT.** 새 발견·작업 결과·상태 변경은 별도 문서로만 남기지 말고
+   대시보드에 반영·동기화한다. 백로그가 대시보드와 어긋나면 대시보드를 기준으로 맞춘다.
+4. **소유자(윤찬) 단독 결정 사안은 임의로 정하지 않는다(월권 금지).**
+5. 모든 소통·주석·커밋 메시지는 한글. 커밋 메시지에 Co-Authored-By / Claude 관련 문구 금지.