085460b5e0
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
143 lines
7.2 KiB
Markdown
143 lines
7.2 KiB
Markdown
# 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).
|
|
|
|
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`, `rag`, `proxy`=Caddy) 및 `.env.example` |
|
|
| `scripts/` | 운영 스크립트(PowerShell/Python): 공개 런타임 기동·감시, 엔진 게이트웨이 프로브, Postgres RLS 감사 등 |
|
|
|
|
---
|
|
|
|
## 2. 빠른 시작 (로컬 dev)
|
|
|
|
주 개발 환경은 **Windows 11 + PowerShell**. 아래는 PowerShell 기준 최소 명령이다.
|
|
(엔진 게이트웨이가 없어도 UI·로그인·페르소나·세션 생성(in-memory)·네비게이션은 동작하며,
|
|
실제 AI 턴 생성만 실패한다. DB가 없어도 인메모리 degraded로 기동된다.)
|
|
|
|
### 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
|
|
```
|
|
|
|
- 기동 로그에 `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 관련 문구 금지.
|