diff --git a/apps/api/app/config.py b/apps/api/app/config.py index eb8b437..a413d15 100644 --- a/apps/api/app/config.py +++ b/apps/api/app/config.py @@ -84,6 +84,14 @@ class Settings(BaseSettings): default=0.0, validation_alias="ADMIN_USAGE_BUDGET_USD", ) + evaluator_fast_model: str = Field( + default="", + validation_alias="EVALUATOR_FAST_MODEL", + ) + evaluator_deep_model: str = Field( + default="", + validation_alias="EVALUATOR_DEEP_MODEL", + ) # ── 외부 LLM 키 (게이트웨이가 못 받을 때 직접 폴백, PII 마스킹 후만) ── anthropic_api_key: str = Field(default="", validation_alias="ANTHROPIC_API_KEY") diff --git a/apps/api/app/services/evaluator.py b/apps/api/app/services/evaluator.py index 6501399..9385b67 100644 --- a/apps/api/app/services/evaluator.py +++ b/apps/api/app/services/evaluator.py @@ -13,7 +13,7 @@ MASTERPLAN §2.3 (평가 AI 2-tier 루프): 후보로 제시하고 *근거(rationale)* 를 요구한다. LLM 출력은 enum 으로 안전 파싱(미지값은 버림). - intent_deviation('의도와 다른 부분')은 1급 시민 → SupervisorComment(critique) 형식과 정합: {dimension, expected, actual, severity}. - - engine_client.generate(tier='feedback', structured_schema=...) 로 LLM 평가. 엔진 장애·파싱 + - engine_client.generate(structured_schema=...) 로 LLM 평가. 엔진 장애·파싱 실패는 *비치명적* — orchestrator 의 eval_hook 가 None 으로 흡수(상담 루프를 막지 않음). - 결과는 pydantic 모델로 반환. orchestrator 가 주입형으로 부르는 async 함수 evaluate_turn(...) / evaluate_session(...) 을 export. @@ -31,6 +31,7 @@ from typing import TYPE_CHECKING, Any, Optional from pydantic import BaseModel, Field +from ..config import settings from ..engine_client import ( EngineClient, EngineError, @@ -67,6 +68,11 @@ _APPROPRIATENESS = ("pos", "warn", "neutral") _SEVERITY = ("minor", "moderate", "major") +def _configured_model(value: str | None) -> str | None: + model = (value or "").strip() + return model or None + + def _parse_technique(raw: str) -> Optional[Technique]: s = (raw or "").strip() return _TECHNIQUE_BY_KO.get(s) or _TECHNIQUE_BY_CODE.get(s) @@ -641,6 +647,7 @@ async def evaluate_turn( ai_role="evaluator", messages=build_fast_messages(ctx, client_reply), structured_schema=_fast_schema(), + model=_configured_model(settings.evaluator_fast_model), max_tokens=900, temperature=0.2, # 평가는 보수적·재현적으로 session_id=ctx.session_id, @@ -717,6 +724,7 @@ async def evaluate_session( distribution=distribution, ), structured_schema=_deep_schema(), + model=_configured_model(settings.evaluator_deep_model), max_tokens=2048, temperature=0.3, session_id=session_id, diff --git a/apps/api/app/test_evaluator_model_routing.py b/apps/api/app/test_evaluator_model_routing.py new file mode 100644 index 0000000..e59dee5 --- /dev/null +++ b/apps/api/app/test_evaluator_model_routing.py @@ -0,0 +1,117 @@ +"""Regression tests for evaluator low-cost model routing.""" + +from __future__ import annotations + +import unittest +from typing import Any + +from .config import settings +from .engine_client import GenerateResponse +from .services import evaluator, orchestrator, persona, state_machine + + +def _initial_state() -> state_machine.SessionState: + return state_machine.init_state( + params=persona.P1.openness_params(), + ) + + +def _turn_context() -> orchestrator.TurnContext: + return orchestrator.prepare_turn( + session_id="evaluator-model-session", + case_id="evaluator-model-case", + card=persona.P1, + state=_initial_state(), + learner_text="요즘 학교 가는 게 너무 부담돼요.", + theory_mode="humanistic", + ) + + +class CaptureEvaluatorEngine: + def __init__(self) -> None: + self.requests: list[Any] = [] + + async def generate(self, req: Any) -> GenerateResponse: + self.requests.append(req) + loop = req.metadata.get("loop") + if loop == "fast": + structured = { + "techniques": [], + "client_state_read": [], + "appropriateness": "neutral", + "rapport_signal": 0.0, + "intent_deviations": [], + } + else: + structured = { + "strengths": [], + "improvements": [], + "alternative_utterances": [], + "intent_deviations": [], + } + return GenerateResponse( + text="", + model=req.model or "gateway-default", + provider="fake-provider", + structured=structured, + ) + + +class EvaluatorModelRoutingTest(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + self._fast_model = settings.evaluator_fast_model + self._deep_model = settings.evaluator_deep_model + settings.evaluator_fast_model = "" + settings.evaluator_deep_model = "" + + async def asyncTearDown(self) -> None: + settings.evaluator_fast_model = self._fast_model + settings.evaluator_deep_model = self._deep_model + + async def test_fast_evaluator_uses_configured_model_override(self) -> None: + settings.evaluator_fast_model = "cheap-fast" + engine = CaptureEvaluatorEngine() + + result = await evaluator.evaluate_turn( + _turn_context(), + "괜찮아요.", + engine=engine, # type: ignore[arg-type] + ) + + self.assertIsNone(result.error) + self.assertEqual(len(engine.requests), 1) + self.assertEqual(engine.requests[0].ai_role, "evaluator") + self.assertEqual(engine.requests[0].model, "cheap-fast") + + async def test_deep_evaluator_uses_configured_model_override(self) -> None: + settings.evaluator_deep_model = "cheap-deep" + engine = CaptureEvaluatorEngine() + + result = await evaluator.evaluate_session( + session_id="evaluator-model-session", + stage="라포", + masked_turns=[ + {"speaker": "counselor", "text": "천천히 이야기해줘도 괜찮아요."}, + {"speaker": "client", "text": "잘 모르겠어요."}, + ], + engine=engine, # type: ignore[arg-type] + ) + + self.assertIsNone(result.error) + self.assertEqual(len(engine.requests), 1) + self.assertEqual(engine.requests[0].ai_role, "evaluator") + self.assertEqual(engine.requests[0].model, "cheap-deep") + + async def test_blank_model_settings_keep_gateway_default_routing(self) -> None: + settings.evaluator_fast_model = " " + settings.evaluator_deep_model = "" + engine = CaptureEvaluatorEngine() + + await evaluator.evaluate_turn( + _turn_context(), + "괜찮아요.", + engine=engine, # type: ignore[arg-type] + ) + + self.assertEqual(len(engine.requests), 1) + self.assertIsNone(engine.requests[0].model) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index db7693a..301c636 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,6 +1,6 @@ # Vignette Handoff -> Updated: 2026-06-27 15:54 KST. 새 세션은 이 문서와 `docs/DESIGN_CONCEPT.md`를 먼저 읽고 이어가면 된다. +> Updated: 2026-06-27 16:16 KST. 새 세션은 이 문서와 `docs/DESIGN_CONCEPT.md`를 먼저 읽고 이어가면 된다. ## 현재 상태 @@ -13,13 +13,13 @@ - 앱 배포 소스 commit: `6bd91b0d` (`현재 작업 상태 저장`) - 최신 Cloudflare Pages production deploy: `2a58ca49`, source `6bd91b0d` + dirty worktree, branch `main` - Google OAuth 허용 이메일 도메인: `hs.ac.kr`, `twentyoz.kr` -- 최신 백엔드 회귀: `python -m pytest app/ -q` → `119 passed` +- 최신 백엔드 회귀: `python -m pytest app/ -q` → `122 passed` - X1 재귀학습 export 1차: `scripts/export-recursive-dataset.py` 기본 read-only dry-run, `--write-dataset` 명시 시에만 `ds.*` write, approved export는 steward/legal/IAA gate 없으면 거부. - C1 사례개념화 워크시트 1차: `SessionReviewResponse.caseWorksheet`와 리뷰 화면 read-only 카드가 축어록 근거 기반 초안을 제공한다. 편집·DB 저장, 임상 루브릭, AI 추출/채점은 후속. - C3 이론모드 1차: `theory_mode`가 세션·평가·생성 프롬프트까지 흐르고, `build_turn_messages`는 인간중심/CBT/통합 프레이밍을 엔진 메시지에 넣는다. CBT 체인·이론부합 루브릭·명시적 선택 UI는 후속. - H2 평가 정규화: 턴 평가의 대안발화도 `app.alternative_utterance`에 적재하고 리뷰 hydrate 시 `alternative_utterances`로 복원한다. -- X2 예산 경고: `ADMIN_USAGE_BUDGET_USD`가 0보다 크면 `/admin/usage`가 budget 상태(ok/warn/exceeded)를 반환하고 `/admin`이 예산 배너를 표시한다. 0 또는 미설정이면 disabled. -- H4 LLM call audit: 상담 생성(generate/stream)과 fast/deep 평가의 외부 LLM 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency metadata만 적재한다. prompt/completion 본문은 저장하지 않는다. 실제 운영 `/turn` 후 live row 확인은 아직 필요하다. +- X2 예산 경고/저비용 평가 라우팅: `ADMIN_USAGE_BUDGET_USD`가 0보다 크면 `/admin/usage`가 budget 상태(ok/warn/exceeded)를 반환하고 `/admin`이 예산 배너를 표시한다. `EVALUATOR_FAST_MODEL`/`EVALUATOR_DEEP_MODEL`을 설정하면 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달한다. 비우면 기존 gateway default 라우팅을 유지한다. +- H4 LLM call audit: 상담 생성(generate/stream)과 fast/deep 평가의 외부 LLM 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency metadata만 적재한다. prompt/completion 본문은 저장하지 않는다. 로컬 dev-login 실제 `/turn` smoke에서 `audit.llm_call_log`가 8→11로 3행 증가했다. - M3 인증 claim 1차: Google/SAML/dev-login이 설정 기반 cohort map과 SAML cohort claim을 `cohort_ids`로 넘기고, 관리 사용자 `external_id`는 provider subject 기반(`google:`/`saml:`/`dev:`)으로 저장한다. 운영 SAML 서명검증·기관 claim schema·deprovisioning audit은 후속. - Google OAuth 진단 1차: provider callback error는 `access_denied`/`provider_error`로 분리하고, 로그인 화면은 실패 reason code를 함께 표시한다. 실제 Google 계정 완료 proof는 아직 owner 로그인/storageState가 필요하다. - `frontenddesign` 스킬은 현재 세션의 사용 가능 스킬 목록에 없었다. 대신 `docs/DESIGN_CONCEPT.md`를 SSOT로 사용했다. @@ -29,6 +29,7 @@ - `GET /personas`는 이제 인증 필요다. 검증 당시 로컬 `http://127.0.0.1:8000/personas`와 현재 공개 `https://api-vignette.chanpaca.net/personas` 모두 비로그인 401 확인 완료. - 로컬 웹이 `http://127.0.0.1:5175`처럼 다른 Vite 포트로 떠도 로그인은 `로컬 테스트 계정으로 계속` 버튼을 사용한다. Google OAuth 버튼은 로컬에서는 disabled로 둔다. 현재 OAuth callback이 공개 API로 돌아가기 때문에 로컬 Google OAuth는 로컬 세션에 붙을 수 없다. - 현재 확인용 프로세스는 `127.0.0.1:9099` engine gateway, `127.0.0.1:8001` prod public API, `127.0.0.1:8000` dev API, `127.0.0.1:8010` Tailnet dev API, `127.0.0.1:5173` Vite web, `cloudflared` tunnel 1개다. Tailnet URL은 `https://alpaca-home.taile93291.ts.net/login`이며 dev-login까지 검증됐다. +- `scripts/dev-up.ps1 -NoGateway -NoWeb`는 이제 gateway/web stale 정리를 건너뛰고 지정 `-ApiPort`의 API만 재기동한다. 검증 당시 8000 API-only 재기동 후 8001/8010/5173/9099/20241 listener가 보존됐다. - Docker `vignette-dev-db`는 실행 중이고 DB는 accepting connections다. 단, 기존 컨테이너라 healthcheck가 없고 `POSTGRES_USER=vignette` 기반이다. `vignette_app` role은 NOBYPASSRLS로 존재하지만 현재 API startup DDL이 owner 권한을 요구하므로 런타임 app-role 전환은 마이그레이션 owner/런타임 role 분리 후 진행한다. - 공개 런타임 재기동 스크립트: - start: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-public-runtime.ps1` diff --git a/docs/dev_dashboard.html b/docs/dev_dashboard.html index b2576c9..87e046a 100644 --- a/docs/dev_dashboard.html +++ b/docs/dev_dashboard.html @@ -286,7 +286,7 @@
Full Playwright 72 통과 - Backend pytest 118 통과 + Backend pytest 122 통과 Layout 시각게이트 7/7 accept Pages prod 2a58ca49 Public API prod OK @@ -449,6 +449,7 @@

1차 적용(2026-06-27): 온화한 이미지 요소 보드는 구현 참고용으로만 두고, 앱 배경에는 전용 래스터 텍스처 `apps/web/public/design-elements/clinical-paper-ambient.png`를 연결했다. 보드·타일셋·누끼 시트 형태 이미지는 직접 UI 배경으로 쓰지 않는다.

2차 적용(2026-06-27): 생성된 관리자/설정/리뷰 시안 기준으로 admin 역할의 상단바·사이드바를 어두운 운영 콘솔 크롬으로 전환했고, 관리자 사용자 관리 행을 조밀한 운영 테이블 밀도로 낮췄다. 회기 리뷰는 헤더·인사이트 카드·피드백 스테이지에 따뜻한 래스터 질감과 낮은 채도 틴트를 적용했다.

3차 적용(2026-06-27): 상담 세션 시작/진행 화면을 시안 기준의 어두운 상담 스테이지로 재정렬했다. 시작 전 화면은 내담자 무대·브리핑·진행 초점 3영역으로 유지하고, 진행 중 화면은 어두운 캔버스 위에 중앙 스테이지와 자막/컨트롤을 배치한다.

+

4차 적용(2026-06-27): 교수 콘솔은 시안의 triage 콘솔 구조에 맞춰 KPI를 전폭 6칸으로 재배치하고, 종료 회기 검토 큐와 최근 회기 기록을 첫 화면 2열 핵심 영역으로 올렸다. 성장 추적·페르소나 저작·검수 보조 큐는 하단 보조 업무로 낮췄고, 교수자 사이드바는 좁은 teal rail로 전환했다.

래스터만 사용이미지 생성 도구 산출물은 PNG 기반 시안이다. SVG·벡터·와이어프레임·로고 시트로 해석하지 않는다.
기능 우선메인 라우트의 실제 액션과 정보 구조를 먼저 반영한다. 장식은 기능을 가리지 않는 수준에서만 쓴다.
@@ -553,11 +554,11 @@
-
현재

① PDF: 고성능(Claude·GPT=내담자발화·실시간평가)/저비용 한국어(Solar=단순응답·사후요약) 2단계 + 캐싱 90%절감. 현재 claude_cli 단일 — 벤더중립 인터페이스는 있음. ② PDF는 Node.js 우선(팀 보유기술·5개월 일정)/Spring 대안. 현재 Python/FastAPI — 재작성은 일정·인력 리스크.

권고

2-tier는 ENGINE_MODE 라우팅으로 점진 도입. 백엔드 언어는 소유자 결정(팀 역량·유지보수 vs 재작성 비용).

+
현재

① PDF: 고성능(Claude·GPT=내담자발화·실시간평가)/저비용 한국어(Solar=단순응답·사후요약) 2단계 + 캐싱 90%절감. 현재 client AI는 claude_cli 기본 라우팅, fast/deep evaluator는 EVALUATOR_FAST_MODEL/EVALUATOR_DEEP_MODEL 설정 시 모델 override를 gateway에 전달한다. 벤더중립 인터페이스와 L0~L2 cache hint/session reuse는 있음. ② PDF는 Node.js 우선(팀 보유기술·5개월 일정)/Spring 대안. 현재 Python/FastAPI — 재작성은 일정·인력 리스크.

권고

2-tier는 evaluator 모델 override 이후 client AI/요약 모델 정책과 semantic cache로 점진 도입. 백엔드 언어는 소유자 결정(팀 역량·유지보수 vs 재작성 비용).

- -
현재

페르소나 격리(캐릭터 붕괴 버그)·RAG 비차단(세션생성 블로킹 회귀)·역린/misconduct·init_state 파라미터객체·데드코드(LogHook·tier·RMS)·OAuth state 복구·X1 dataset export dry-run — 백엔드 118/118 + E2E 42(데스크27·모바일11·아바타4) + 시각게이트 7/7 통과. 스택 라이브(web·api·gateway·voice·RAG).

다음

남은 원천문서 갭과 임상 콘텐츠 적재를 순서대로 닫는다.

+ +
현재

페르소나 격리(캐릭터 붕괴 버그)·RAG 비차단(세션생성 블로킹 회귀)·역린/misconduct·init_state 파라미터객체·데드코드(LogHook·tier·RMS)·OAuth state 복구·X1 dataset export dry-run — 백엔드 122 + E2E 42(데스크27·모바일11·아바타4) + 시각게이트 7/7 통과. 스택 라이브(web·api·gateway·voice·RAG).

다음

남은 원천문서 갭과 임상 콘텐츠 적재를 순서대로 닫는다.

@@ -591,20 +592,20 @@
현재

POST/GET/PUT /personas/drafts를 추가해 teacher/admin이 페르소나 카드를 draft로 생성·조회·편집하고 review 상태로 올릴 수 있다. 교수 콘솔에는 JSON 초안 패널과 검수 큐의 편집 불러오기를 연결했다. 승인된 카드만 학습자 catalog에 노출되는 기존 경계는 유지.

검증

pytest app/test_persona_review.py -q 19 passed, pytest app/ -q 119 passed, npm run check:api-types, npm run typecheck, npm run build passed.

잔여

P4~P7 실제 임상 콘텐츠 적재, JSON 대신 항목형 저작 UI, 루브릭·이론 콘텐츠 외부화는 후속. 임상팀이 제공하지 않은 페르소나 내용을 임의 생성하지 않는다.

- -
현재

정규식 폴백에 한국어 고위험 패턴 추가: 구체 날짜(2001.4.18→[DATE])·금액(1200원→[MONEY])·행정구역 주소(서울시 강남구 역삼동→[ADDR]). 상담 생성(generate/stream)·fast/deep 평가의 외부 LLM 호출 직후 audit.llm_call_log에 provider/model/token/cost/inference_geo/latency만 적재한다. prompt/completion 본문은 저장하지 않는다. 검증: 마스킹/감사 5 passed, 관련 회귀 27 passed, 전체 API 119 passed.

잔여

이름/기관명은 NER 필요(Presidio ko 모델·spaCy ko, 무거움 — TODO 명시), 실제 운영 로그인 /turn 후 live DB row proof, 미성년/guardian 동의 수집·게이트·철회.

+ +
현재

정규식 폴백에 한국어 고위험 패턴 추가: 구체 날짜(2001.4.18→[DATE])·금액(1200원→[MONEY])·행정구역 주소(서울시 강남구 역삼동→[ADDR]). 상담 생성(generate/stream)·fast/deep 평가의 외부 LLM 호출 직후 audit.llm_call_log에 provider/model/token/cost/inference_geo/latency만 적재한다. prompt/completion 본문은 저장하지 않는다. 로컬 dev-login 실제 /turn smoke에서 audit.llm_call_log가 8→11로 3행 증가했다. 검증: 마스킹/감사 5 passed, 관련 회귀 27 passed, 전체 API 122 passed.

잔여

이름/기관명은 NER 필요(Presidio ko 모델·spaCy ko, 무거움 — TODO 명시), 미성년/guardian 동의 수집·게이트·철회. 공개 Google OAuth 실제 /turn proof는 별도 운영 게이트.

현재

M1: voice learner turn의 audio_ref, silence_ms, speech_rate, barge_in을 리뷰 API nonverbal 이벤트로 파생하고, 회기 리뷰 축어록에 침묵·발화 속도·끼어듦·음성 입력 칩으로 표시한다. 한숨·울음 감지와 live 마이크/STT/TTS 실측은 아직 별도다. M2: case_profile을 learner-persona 안정 case로 upsert하고, session_no를 트랜잭션 안에서 원자 증가시키며, 시작/턴/voice 경로가 직전 session_summary 기반 seed recall을 사용한다. episodic embedding writer와 case_digest/pinned_fact 실적재는 후속. M3: Google/SAML/dev-login이 AUTH_EMAIL_COHORT_MAP/AUTH_DOMAIN_COHORT_MAP 및 SAML cohort claim을 cohort_ids로 전달하고, DB app_user.external_id는 provider subject(google:/saml:/dev:) 기반으로 저장한다.

권고

M1 한숨·울음/억양 등 provider 이벤트 보존, M2 session_summary digest/pinned_fact 압축·embedding writer·case_profile trajectory 갱신, M3 운영 SAML 서명검증·기관 claim schema/test tenant·deprovisioning audit는 외부 IdP 협의 후 진행.

- -
현재

X1: scripts/export-recursive-dataset.py와 app.services.dataset_export로 masked-text JSONL dry-run, PII scan, κ/ICC 계산, approved export 게이트를 구현했다. 기본은 technical_dry_run이고 ds.* write는 --write-dataset 명시 시에만 수행한다. X2: app.turns의 provider/model/tokens/cost를 최근 7일 기준으로 집계하는 GET /admin/usage를 추가했고, 운영 콘솔 /admin에 누적 비용·입출력 토큰·계량 커버리지·provider/model breakdown과 ADMIN_USAGE_BUDGET_USD 기반 예산 경고(ok/warn/exceeded)를 표시한다. DB 미가용 dev에서는 runtime store로 fallback하지만 prod에서는 fail-closed한다. L1: doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박.

권고

X1 approved export·골든셋 승격은 steward/legal 승인, reviewer disposition, IAA 게이트(κ≥0.6/ICC≥0.75) 이후만 진행한다. X2 후속은 캐싱·저비용 모델 분기, L1은 스택 정합 또는 변경사유 거버넌스 기록.

+ +
현재

X1: scripts/export-recursive-dataset.py와 app.services.dataset_export로 masked-text JSONL dry-run, PII scan, κ/ICC 계산, approved export 게이트를 구현했다. 기본은 technical_dry_run이고 ds.* write는 --write-dataset 명시 시에만 수행한다. X2: app.turns의 provider/model/tokens/cost를 최근 7일 기준으로 집계하는 GET /admin/usage를 추가했고, 운영 콘솔 /admin에 누적 비용·입출력 토큰·계량 커버리지·provider/model breakdown과 ADMIN_USAGE_BUDGET_USD 기반 예산 경고(ok/warn/exceeded)를 표시한다. EVALUATOR_FAST_MODEL/EVALUATOR_DEEP_MODEL 설정 시 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달하고, 비워두면 기존 default 라우팅을 유지한다. DB 미가용 dev에서는 runtime store로 fallback하지만 prod에서는 fail-closed한다. L1: doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박.

권고

X1 approved export·골든셋 승격은 steward/legal 승인, reviewer disposition, IAA 게이트(κ≥0.6/ICC≥0.75) 이후만 진행한다. X2 후속은 semantic cache·장기 비용 추이/한도 정책·운영 모델별 비용 검증, L1은 스택 정합 또는 변경사유 거버넌스 기록.

-

즉시 착수 가능(내부 코드, 외부 합의 불요)

+

즉시 착수 가능(내부 코드, 외부 합의 불요)

소유자 결정 / 외부(임상팀·기관) 의존

판독 한계 (정직성)

@@ -616,7 +617,7 @@
-
현재

게이트웨이(9099 claude_cli)+API(8000, DB 미가용 시 in-memory degraded)+웹(5173)을 커맨드라인 기준 정리 후 결정론적 기동(--reload 워처 불안정 회피, uvicorn 있는 python 자동 해석). Docker가 사용 가능하면 vignette-dev-db healthcheck/pg_isready/role safety를 점검하고, compose infra\.env 필수값 누락도 경고한다. dev-login + seed 페르소나. 로그 .devlogs/(gitignore). 검증: 3포트 health OK + 실제 AI 턴 생성·회기리뷰 동작.

비고

AI 턴은 로컬 claude CLI 사용(사용량 발생). 진입점 http://localhost:5173. dev-down.ps1은 기본적으로 DB 컨테이너를 보존하고, -Db 지정 시 함께 중지한다. 기존 vignette-dev-db는 accepting connections이나 healthcheck가 없고, vignette_app은 NOBYPASSRLS로 존재하지만 현재 API startup DDL은 owner 권한이 필요해 런타임 app-role 분리는 후속이다. 주의(무DB 한정): DB 없이 degraded면 페르소나가 source:seed_fallback·degraded:true라 프론트 isUsablePersona가 막아 "회기 시작" 버튼이 비활성 → UI 세션 시작엔 실제 Postgres(127.0.0.1:55432)가 필요.

+
현재

게이트웨이(9099 claude_cli)+API(8000, DB 미가용 시 in-memory degraded)+웹(5173)을 커맨드라인 기준 정리 후 결정론적 기동(--reload 워처 불안정 회피, uvicorn 있는 python 자동 해석). Docker가 사용 가능하면 vignette-dev-db healthcheck/pg_isready/role safety를 점검하고, compose infra\.env 필수값 누락도 경고한다. -NoGateway/-NoWeb는 해당 컴포넌트 정리도 건너뛰고, API 정리는 지정 -ApiPort만 대상으로 한다. dev-login + seed 페르소나. 로그 .devlogs/(gitignore). 검증: 3포트 health OK + 실제 AI 턴 생성·회기리뷰 동작, API-only 재기동 후 8001/8010/5173/9099/20241 보존.

비고

AI 턴은 로컬 claude CLI 사용(사용량 발생). 진입점 http://localhost:5173. dev-down.ps1은 기본적으로 DB 컨테이너를 보존하고, -Db 지정 시 함께 중지한다. 기존 vignette-dev-db는 accepting connections이나 healthcheck가 없고, vignette_app은 NOBYPASSRLS로 존재하지만 현재 API startup DDL은 owner 권한이 필요해 런타임 app-role 분리는 후속이다. 주의(무DB 한정): DB 없이 degraded면 페르소나가 source:seed_fallback·degraded:true라 프론트 isUsablePersona가 막아 "회기 시작" 버튼이 비활성 → UI 세션 시작엔 실제 Postgres(127.0.0.1:55432)가 필요.

@@ -719,7 +720,7 @@
CHECK
LLMEngine 정규화 계약 고정

gateway SSE token/done/error와 generate cost 계약은 회귀화했다. claude_cli와 Messages API 폴백 동일성 검증은 남아 있다.

산출물

token, done, error, cost 이벤트 계약과 contract test

검증

stream error 미저장 + stream/generate client turn telemetry 저장

DONE
상주 claude -p 엔진풀 실증

session_id가 살아 있는 gateway session을 재사용하고 missing session은 ephemeral로 닫히는 구조를 회귀화했고, live 게이트웨이(9099)로 실측까지 마쳤다. probe-engine-gateway.py가 단일 session_id로 2회 reused stream을 돌려 TTFT 1667–4199ms, cost 누적 0.068→0.123(turns 1→2), engine=claude_p, model=opus-4-8을 측정했다.

산출물

engine_gateway/test_gateway_model.py, scripts/probe-engine-gateway.py, live probe JSON

검증

session reuse 7 tests OK; live probe 2 reused streams, TTFT/cost 실측, session_id 재사용 확인

-
CHECK
마스킹 게이트 + LLM call audit

current turn, recall, pinned fact, recent turns가 Presidio/가명처리 후에만 engine request로 들어가게 막았다. 외부 LLM 호출은 audit.llm_call_log에 provider/model/token/cost/inference_geo/latency metadata만 남기고 prompt/completion 본문은 저장하지 않는다. 실제 운영 로그인 /turn 후 live DB row proof는 남아 있다.

산출물

app/test_orchestrator_masking.py, app/test_evaluation_persistence.py, session_persistence.record_llm_call_audit

검증

phone/email/RRN raw 값이 generate/stream payload에 없음, 감사 payload 본문 미포함, 관련 회귀 27 passed, 전체 API 119 passed

+
DONE
마스킹 게이트 + LLM call audit

current turn, recall, pinned fact, recent turns가 Presidio/가명처리 후에만 engine request로 들어가게 막았다. 외부 LLM 호출은 audit.llm_call_log에 provider/model/token/cost/inference_geo/latency metadata만 남기고 prompt/completion 본문은 저장하지 않는다.

산출물

app/test_orchestrator_masking.py, app/test_evaluation_persistence.py, session_persistence.record_llm_call_audit

검증

phone/email/RRN raw 값이 generate/stream payload에 없음, 감사 payload 본문 미포함, 관련 회귀 27 passed, 전체 API 122 passed, 로컬 live /turn smoke 후 audit.llm_call_log 8→11

CHECK
P1 상담 완주 플로우

통제된 UI E2E로 P1 선택, SSE 상담, 종료, 회기말 리뷰 피드백을 한 번에 통과시켰다. 실제 운영 로그인 proof는 P0 blocker와 함께 남아 있다.

산출물

e2e/session-mvp.spec.ts, turn telemetry 저장 경로

검증

chromium-single-run P1 MVP UI E2E 1 passed

CHECK
저항 엔진 정량 검증

공감 발화와 조언점프 발화 5턴 세트를 순수 상태머신 회귀 테스트로 비교했다. DB 쿼리 기반 운영 증거는 남아 있다.

산출물

app/test_state_machine_resistance.py

검증

공감 시 탐색 전이/개방도 상승, 조언점프 시 라포 단계 유지/개방도 0

CHECK
음성 왕복 1턴 PoC

Session UI 마이크 버튼 경로에서 synthetic getUserMedia/MediaRecorder로 실제 /voice/ws를 열고 audio_start, binary chunk, audio_end, transcript, reply, TTS 재생 상태까지 검증했다. 물리 마이크, 공개 WSS, live STT/TTS provider 증거는 아직 별도다.

산출물

apps/web/e2e/voice-success.spec.ts, controlled OpenAI/engine providers, browser voice UI probe

검증

npx playwright test e2e/voice-success.spec.ts --project=chromium-single-run 2 passed

@@ -769,7 +770,7 @@
DONE
레이아웃 감사팀 / 전면 레이아웃 개선

서브에이전트 전담으로 1차 overflow/clipping 수리 후 2차 전면 재설계를 진행했고, 이번 라운드에서 7개 권장 너비 시각 수용까지 닫았다. 세션, 학습자 홈/리뷰, 교수 콘솔, 관리자, 설정 화면을 작업 화면 기준으로 재배치했고, 과한 빈칸·튀어나감·버튼/텍스트 잘림·모바일 테이블 사용성을 줄였다. 엄격한 시각 게이트 + 화면별 적대적 시각 재검수에서 7개 화면 모두 accept(critical/major 0, 회귀 0)를 받아 DONE으로 닫는다.

산출물

docs/ops/layout-redesign-handoff-2026-06-26.md, page-by-page redesign patches, apps/web/e2e/layout-visual-gate.spec.ts

검증

npm run typecheck OK, 엄격 시각 게이트 7 passed, layout focused E2E desktop/mobile 54 passed, 적대적 시각 재검수 7/7 accept·회귀 0.

DONE
엄격한 레이아웃 시각 게이트 구축 · 병렬 수정 · 적대적 재검수

핸드오프가 요구한 7개 권장 너비(390/720/861/900/1024/1280/1440) 시각 수용을 자동 게이트로 고정했다. 7개 재설계 화면을 각 너비에서 렌더링해 가로 overflow 0, 컨트롤 하드클립/텍스트클립 0을 강제하고 화면당 7장 총 49장 풀페이지 스크린샷을 남긴다. 화면별 1에이전트 병렬 시각 리뷰로 49장 직접 판독 → 6개 병렬 수정 에이전트(파일 비중첩)가 결함 수정 → 화면별 적대적 재검수로 해소·무회귀 확정.

산출물

apps/web/e2e/layout-visual-gate.spec.ts, node_modules/.tmp/layout-gate/*.png 49장, 2× workflow(review/verify)·6× fix agent

검증

게이트 7 passed(재스크린샷). 해소된 핵심 결함: 학습자홈 1280/1440 3열 가운데 컬럼 붕괴(critical → 2열 분기 상향 + word-break:keep-all), 교수 'API 404' raw 배너 제거, 리뷰 빈상태 위계 역전, 관리자 스켈레톤, 설정 와이드 좌측 데드존 제거, 세션 모바일 44px 터치타깃. 적대적 재검수 7/7 accept, regression 0.

DONE
레이아웃 cosmetic minor 폴리시 일괄 처리

적대적 재검수 잔여 cosmetic minor를 5개 병렬 폴리시 에이전트로 처리했다. 학습자홈 헬퍼문구 고아 글자, 세션 1024 일시정지 아이콘 정리 + 보내기 버튼 대비 강화, 설정 2x2 칩 행 높이 균일, 교수 검토 큐 카드 갭 제거, 관리자 2열 높이 동기화를 적용했다.

산출물

page-by-page polish patches(LearnerHome/Session/Settings/Professor/Admin)

검증

npm run typecheck OK, 시각 게이트 7 passed, 레이아웃 E2E desktop/mobile 54 passed, session-layout 8/8 — 회귀 0.

-
MINOR
잔여(비차단) — 공용 셸 단일 항목 → 처리

축소 사이드바 세로 구분선이 본문 전체 높이까지 닿지 않던 건을 components/shell/shell.css에서 처리했다. .vg-nav border-right 제거 후 .vg-shell__body 컨테이너 배경 하어라인으로 본문 그리드 전체 높이 구분선을 그리고, 그리드·구분선 폭을 --nav-cur로 동기화. learner-home 로딩 스켈레톤 밀도도 실제 카드 구조 모사로 보강했다.

판정

구현 완료. 검증: npm run typecheck PASS + vite build PASS. 전 페이지 시각 회귀 게이트는 web+api+DB 스택으로 이 워크스테이션 미실행 — 스택 가용 시 1회 시각 확인 권장.

+
DONE
잔여(비차단) — 공용 셸 단일 항목 → 처리

축소 사이드바 세로 구분선이 본문 전체 높이까지 닿지 않던 건을 components/shell/shell.css에서 처리했다. .vg-nav border-right 제거 후 .vg-shell__body 컨테이너 배경 하어라인으로 본문 그리드 전체 높이 구분선을 그리고, 그리드·구분선 폭을 --nav-cur로 동기화. learner-home 로딩 스켈레톤 밀도도 실제 카드 구조 모사로 보강했다.

판정

구현 완료. 검증: npm run typecheck PASS + vite build PASS. 전 페이지 시각 회귀 게이트는 web+api+DB 스택으로 이 워크스테이션 미실행 — 스택 가용 시 1회 시각 확인 권장.

검증 실행 상세 표

요약하지 않고 실행 범위, 명령, 결과를 행 단위로 남긴다.

@@ -777,7 +778,8 @@ - + + diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md index f4e3275..a8ce953 100644 --- a/docs/guides/local-development.md +++ b/docs/guides/local-development.md @@ -33,7 +33,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-up.ps1 - 진입점 **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`(UI만), `-NoWeb`(API만), `-NoDb`(DB 컨테이너 보장 건너뜀). +- 옵션: `-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' 별칭이 diff --git a/docs/guides/source-docs-and-gaps.md b/docs/guides/source-docs-and-gaps.md index eb436d4..6174e9d 100644 --- a/docs/guides/source-docs-and-gaps.md +++ b/docs/guides/source-docs-and-gaps.md @@ -62,7 +62,7 @@ | **H1** | 계약 평가 KPI(자기효능감·기술숙련도·수련만족도 사전사후) 수집·집계 전무 | `자기효능감/사전사후/수련만족/실험통제군` grep 0건. Phase3 KPI도 report shape만, 계산 코드 0줄. (분석) | 3척도 pre-post 폼·실험/통제군 배정·자동누적 대시보드·추이 시각화·검정 계산 코드. (κ/ICC·환각률은 doc4 미명시 → 평가설계 확정.) | doc4(20명 실험/통제군·단회기 50분·3척도 pre-post) | | **H2** | 턴별 회기 리뷰 fast-loop 1차 가동·골든셋/2열 UI 잔여 | `make_eval_hook`이 submit/voice 생성 경로에 주입되고, stream은 `_evaluate_stream_turn`으로 fast-loop 평가를 붙인다. 결과는 `feedback_scores`, `alternative_utterance` 등 정규화 테이블에 적재·hydrate된다. | 회기리뷰 UI 좌(축어록 타임라인+비언어)/우(기법·적절성·대안반응·이론) 2열 고도화, 원천 축어록 few-shot 골든셋 적재. | doc2·doc5(골드 포맷) | | **H3** | 임상팀 콘텐츠 입력 경로(페르소나 저작 CRUD) 부재 + P4~P7 미적재 | personas 라우트에 검수 승인/반려만, draft 생성·편집 API 없음. `persona_repository.py`는 in-code `SEED_PERSONAS`(P1~P3)만 materialize, 외부 JSON 미로드 ✓. | 페르소나 저작 CRUD(draft→review) + P4~P7 적재, 루브릭·이론 콘텐츠를 임상팀 편집 가능 데이터로 외부화. | doc3(R&R)·doc4(페르소나=전문가 산출물) | -| **H4** | PII 마스킹 한국어 공백 + 외부전송 관측 live proof 잔여 | Presidio `language='en'` 고정이라 이름/기관명은 NER 보강이 필요하지만, 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐다. 외부 LLM 호출은 상담 생성(generate/stream)·fast/deep 평가 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재하도록 연결했고, prompt/completion 본문은 저장하지 않는다. `consent_at` 컬럼만 있고 동의 수집/게이트/철회 엔드포인트는 아직 없다. | 한국어 이름/기관 NER 추가, 실제 운영 로그인 `/turn` 후 `audit.llm_call_log` row 실측, 미성년/guardian 동의 수집·게이트·철회. | doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보) | +| **H4** | PII 마스킹 한국어 이름/기관 NER + 동의 게이트 잔여 | Presidio `language='en'` 고정이라 이름/기관명은 NER 보강이 필요하지만, 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐다. 외부 LLM 호출은 상담 생성(generate/stream)·fast/deep 평가 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재하도록 연결했고, prompt/completion 본문은 저장하지 않는다. 로컬 dev-login 실제 `/turn` smoke에서 `audit.llm_call_log` 3행 증가를 확인했다. `consent_at` 컬럼만 있고 동의 수집/게이트/철회 엔드포인트는 아직 없다. | 한국어 이름/기관 NER 추가, 미성년/guardian 동의 수집·게이트·철회. 공개 Google OAuth 실제 `/turn` proof는 별도 운영 게이트. | doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보) | ### Medium+ (6) — M1~M3, X1~X2, L1 @@ -72,7 +72,7 @@ | **M2** | 다회기 종단 케이스 아크·교차회기 사례개념화 부분 구동 | 1차로 `(persona_id, learner_id)` 안정 `case_profile` upsert, 원자적 `session_no`, 직전 `session_summary` 기반 seed recall, voice/REST/SSE recall cache 주입을 연결했다. `case_digest`/`pinned_fact` 실적재, episodic embedding writer, trajectory 갱신은 아직 없다. | case_state 런타임 보강, pinned_fact·case_digest 압축/갱신, 접수면접→다회기 연속성·자기개념 진화 실증. | | **M3** | SSO claim 매핑·식별자 안정성 1차 완료·운영 IdP 감사 미연결 | Google/SAML/dev-login이 `AUTH_EMAIL_COHORT_MAP`·`AUTH_DOMAIN_COHORT_MAP` 및 SAML cohort claim을 `cohort_ids`로 전달하고, `app_user.external_id`는 provider subject(`google:`/`saml:`/`dev:`) 기반으로 저장한다. 운영 SAML 서명검증, 기관 claim schema/test tenant, deprovisioning audit은 아직 없다. | 한신 IdP 확정 후 SAML 서명검증, claim→role/cohort/institution_user_id 매핑 표 실연동, role변경/삭제 audit, deprovisioning evidence. | | **X1** | 재귀학습·데이터셋 export 파이프라인 1차 구현 | `scripts/export-recursive-dataset.py`와 `app.services.dataset_export`로 masked-text JSONL dry-run, PII scan, kappa/ICC 계산, approved export 게이트를 구현했다. 기본은 `technical_dry_run`이며 실제 승인 export·골든셋 승격은 데이터 steward/legal review와 IAA 통과가 필요하다. | 파일럿 evidence에서 reviewer disposition, steward/legal 승인, gold annotation 라운드 적재 후 `approved_for_recursive_learning_seed` 승격 검증. | -| **X2** | AI API 비용 관측·예산 경고 1차 완료·최적화 미구현 | 턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱·저비용 모델 분기는 아직 없다. | 캐싱, 저비용 모델 분기, 장기 비용 추이/한도 정책. | +| **X2** | AI API 비용 관측·예산 경고 1차 완료·평가 저비용 라우팅 1차 완료 | 턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. `EVALUATOR_FAST_MODEL`/`EVALUATOR_DEEP_MODEL` 설정 시 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달하고, 비워두면 기존 gateway default 라우팅을 유지한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱은 L0~L2 cache hint와 gateway session reuse까지만 연결돼 있고 semantic cache·장기 한도 정책은 아직 없다. | semantic cache, 장기 비용 추이/한도 정책, 운영 모델별 비용 검증. | | **L1** | 기술스택 신청서-구현 불일치 및 단기일정 산출물 압박 | doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박. | 스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영. | > X2 근거: doc3 회의록이 'AI API 비용'을 운영 리스크로 명시. @@ -90,7 +90,7 @@ - **C3 1차 완료**: `theory_mode`가 세션·평가·생성 프롬프트까지 흐른다. 후속은 임상팀 CBT 체인·이론부합 루브릭·명시적 선택 UI. - **H2 1차 완료**: `make_eval_hook`과 stream 평가가 턴 파이프라인에 붙고 정규화 테이블로 적재·복원된다. 대안발화도 `app.alternative_utterance`로 정규화한다. 후속은 2열 리뷰 UI·골든셋. - **H3**: 페르소나 저작 CRUD(draft→review) + P4~P7 로드 경로. -- **H4(부분)·X1·X2**: 마스킹 한국어 정규식 보강과 외부 LLM 호출 metadata-only `audit.llm_call_log` 적재 경로, dry-run JSONL export·PII scan·IAA 계산 1차는 완료했다. `ds.*` write는 `--write-dataset` 명시 시에만 수행한다. X2 비용 관측·예산 경고 1차는 완료했고 캐싱·저비용 모델 분기는 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속. +- **H4(부분)·X1·X2**: 마스킹 한국어 정규식 보강과 외부 LLM 호출 metadata-only `audit.llm_call_log` 적재 경로, dry-run JSONL export·PII scan·IAA 계산 1차는 완료했다. `ds.*` write는 `--write-dataset` 명시 시에만 수행한다. X2 비용 관측·예산 경고와 evaluator fast/deep 모델 override 1차는 완료했고 semantic cache·장기 한도 정책은 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속. ### B. 소유자 결정 / 외부(임상팀·기관) 의존 diff --git a/docs/ops/backlog-2026-06-26.md b/docs/ops/backlog-2026-06-26.md index 7bc9b2f..1ffab34 100644 --- a/docs/ops/backlog-2026-06-26.md +++ b/docs/ops/backlog-2026-06-26.md @@ -27,7 +27,6 @@ - [ ] **음성 캐스케이드 live** — 실제 Deepgram STT / OpenAI TTS provider 키, 물리 마이크, 공개 WSS 50분 양방향 실측. provider 키/하드웨어 부재로 미실행(백엔드 계약·UI synthetic 경로는 단위/E2E로 증명됨). - [ ] **claude_cli ↔ Messages API 폴백 동일성** — `ANTHROPIC_API_KEY`가 있어야 Messages API 경로를 돌려 동일성 검증 가능. claude_cli 경로는 게이트웨이 probe로 live 실측 완료. - [ ] **저항엔진 openness 곡선 DB 실증** — fast-loop 평가의 `client_state_read` → `app.turn_client_state` 적재 경로는 추가됨. 다만 dev DB 실데이터/다수 실턴(real LLM) 기반 openness 곡선 증거는 아직 필요. 현재는 `app.test_state_machine_resistance` 단위테스트와 `app.test_evaluation_persistence` 매핑 테스트로 1차 증명. -- [ ] **마스킹 게이트 운영 외부-send live proof** — 상담 생성(generate/stream)과 fast/deep 평가 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재하는 경로를 추가했다. prompt/completion 본문은 저장하지 않는다. 남은 증거는 실제 운영 로그인 `/turn` 후 live DB row를 확인하는 것이다. 현재는 `app.test_orchestrator_masking`로 generate/stream payload에 phone/email/RRN 부재와 감사 payload의 본문 미포함을 증명. - [ ] **재부팅 후 watchdog smoke** — `watch-public-runtime.ps1` + Scheduled Task가 재부팅 후 엔진/API/터널을 복구하고 public `/turn`이 통과하는지 실측. 재부팅 불가로 미실행(parser/ check-only 경로는 확인됨). 2026-06-27 점검에서 아직 DNS가 없는 `api-vnet.18ka.net`은 기본 watchdog 검사에서 제외했고, 개통 후 `-AdditionalPublicHealthUrls`로 명시 추가하도록 runbook을 보강했다. - [ ] **상주 엔진풀 RSS 실측** — probe로 TTFT/세션재사용/cost는 live 확인. 프로세스 RSS(메모리)는 별도 OS 계측 항목으로 남김. @@ -74,7 +73,7 @@ - C1 사례개념화 워크시트 1차: `SessionReviewResponse.caseWorksheet`와 리뷰 화면 read-only 카드가 탐색 11항목·호소 5영역·인지삼제/감정·보호/방해·생물심리사회 목표 초안을 축어록 근거 기반으로 제공한다. 편집·DB 저장, 임상 루브릭, AI 추출/채점, 교수자 검수는 후속. **검증: `pytest app/test_session_turn_persistence.py -q` 15 passed, `pytest app/ -q` 119 passed, `npm run check:api-types`, `npm run typecheck`, `npm run build`, `session-review.spec.ts` 1 passed.** - C3 이론모드 1차: `theory_mode`가 `TurnContext`/sessions/voice/evaluator뿐 아니라 `build_turn_messages`의 엔진 메시지까지 전달된다. 프론트는 `persona.theory_target` 기준으로 시작해 `humanistic` 하드코딩을 제거했다. CBT 체인·이론부합 루브릭·명시적 선택 UI는 후속. **검증: `pytest app/test_orchestrator_masking.py app/test_session_turn_persistence.py -q` 20 passed, `pytest app/ -q` 119 passed.** - M3 인증 claim 1차: Google/SAML/dev-login이 `AUTH_EMAIL_COHORT_MAP`·`AUTH_DOMAIN_COHORT_MAP` 및 SAML cohort claim을 `cohort_ids`로 전달하고, DB `app_user.external_id`는 provider subject(`google:`/`saml:`/`dev:`) 기반으로 저장한다. 운영 SAML 서명검증, 기관 claim schema/test tenant, deprovisioning audit은 후속. **검증: `pytest app/test_auth_providers.py -q` 22 passed, `pytest app/ -q` 119 passed.** -- X2 예산 경고 1차: `ADMIN_USAGE_BUDGET_USD` 설정값을 기준으로 `GET /admin/usage`가 `budget.status=disabled|ok|warn|exceeded`, 사용률, 잔여 예산을 반환하고 관리자 콘솔이 예산 상태 배너를 표시한다. 80% 이상 warn, 100% 이상 exceeded. 캐싱·저비용 모델 분기는 후속. **검증: `pytest app/test_runtime_policy.py -q` 20 passed, `pytest app/ -q` 119 passed, `npm run check:api-types`, `npm run typecheck`.** -- H4 LLM call audit 1차: 상담 생성(generate/stream)·fast-loop 평가·deep-loop 평가의 외부 LLM 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency metadata만 적재한다. prompt/completion 본문은 저장하지 않고 감사 실패는 상담 루프를 막지 않는다. 실제 운영 `/turn` row proof는 B2에 남긴다. **검증: `pytest app/test_orchestrator_masking.py app/test_evaluation_persistence.py app/test_session_turn_persistence.py -q` 27 passed, `pytest app/ -q` 119 passed.** +- X2 예산 경고/저비용 평가 라우팅 1차: `ADMIN_USAGE_BUDGET_USD` 설정값을 기준으로 `GET /admin/usage`가 `budget.status=disabled|ok|warn|exceeded`, 사용률, 잔여 예산을 반환하고 관리자 콘솔이 예산 상태 배너를 표시한다. 80% 이상 warn, 100% 이상 exceeded. `EVALUATOR_FAST_MODEL`/`EVALUATOR_DEEP_MODEL` 설정 시 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달하고, 비워두면 기존 gateway default 라우팅을 유지한다. semantic cache·장기 한도 정책은 후속. **검증: `pytest app/test_evaluator_model_routing.py app/test_runtime_policy.py -q` 23 passed, `pytest app/ -q` 122 passed, `npm run check:api-types`, `npm run typecheck`.** +- H4 LLM call audit 1차: 상담 생성(generate/stream)·fast-loop 평가·deep-loop 평가의 외부 LLM 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency metadata만 적재한다. prompt/completion 본문은 저장하지 않고 감사 실패는 상담 루프를 막지 않는다. 로컬 dev-login 실제 `/turn` smoke에서 `audit.llm_call_log`가 8→11로 3행 증가했다(session `2460d56c-a9cb-4a40-a175-9575d510a5e9`). 공개 Google OAuth 실제 `/turn` proof는 별도 B2 항목에 남긴다. **검증: `pytest app/test_orchestrator_masking.py app/test_evaluation_persistence.py app/test_session_turn_persistence.py -q` 27 passed, `pytest app/ -q` 119 passed.** - 공개/로컬/Tailnet 로그인 복구: public API 530 원인은 prod에서 개발 전용 `VIGNETTE_VOICE_POC_SAMPLE_TTS=true`가 fail-close된 것과 DB `app.admin_engine_config` 기본 행 부재였다. `scripts/start-public-runtime.ps1`는 public prod 기동 시 샘플 TTS를 강제로 끄고, 운영 DB에는 `claude_cli`/`127.0.0.1:9099` engine config 행을 복구했다. 추가로 dev/Tailnet에서는 public OAuth callback이 로컬/Tailnet 세션으로 붙지 않으므로 Google 버튼과 직접 시작 URL을 `local_oauth_unavailable`로 차단하고 dev-login만 사용한다. public OAuth state는 HttpOnly 쿠키에 묶인 HMAC 서명 토큰으로 복구해 API 재시작 뒤 콜백이 `invalid_state`로 떨어지지 않는다. callback 실패는 비밀값 없는 reason/status로 남기고, 로그인 화면도 token/state/provider/identity 실패 메시지와 reason code를 분리한다. **검증: `https://vignette.chanpaca.net/login` 200 + `index-BzQmv-jU.js`, `https://api-vignette.chanpaca.net/health` prod/db/engine true, public Google auth redirect 302 + HttpOnly state cookie, provider callback error → `/login?oauth=access_denied`, local/Tailnet Google direct는 각 origin의 `/login?oauth=local_oauth_unavailable`, local auth E2E 7 passed, Tailnet auth/dev-login E2E 2 passed.** - Docker dev DB 안전장치: `scripts/dev-up.ps1`가 `vignette-dev-db` healthcheck/pg_isready/role safety를 점검하고, 새 컨테이너 생성 시 `vignette_owner`와 앱 role을 분리해 healthcheck를 붙인다. `infra\.env` compose 필수값 누락도 사전 경고한다. `scripts/dev-down.ps1`은 기본 DB 보존, `-Db` 지정 시 컨테이너 중지로 정리했다. **검증: 현재 Docker DB accepting connections, `vignette_app:false:false`, 기존 컨테이너 healthcheck 없음. 추가 확인 결과 기존 DB는 `POSTGRES_USER=vignette` 기반이고 API startup DDL이 owner 권한을 요구해 런타임 app-role 전환은 마이그레이션 owner/런타임 role 분리 후 진행해야 한다.** diff --git a/docs/ops/source-docs-gap-analysis-2026-06-26.md b/docs/ops/source-docs-gap-analysis-2026-06-26.md index 3711799..b4f964b 100644 --- a/docs/ops/source-docs-gap-analysis-2026-06-26.md +++ b/docs/ops/source-docs-gap-analysis-2026-06-26.md @@ -22,7 +22,7 @@ | H2 턴별 평가 1차 가동 | `make_eval_hook`이 submit/voice에 주입되고 stream 평가도 붙어 정규화 적재·복원 ✓ | | H3 페르소나 저작 경로 부재 | `persona_repository.py`는 in-code `SEED_PERSONAS`(P1~P3)만 materialize, draft CRUD·외부 JSON 로드 **없음** ✓ | -그 외 항목(H1 KPI 수집, H4 한국어 이름/기관 NER와 live proof, M1~M2, X1~X2, L1)은 분석 결과이며 착수 전 코드 재확인 권고. M3은 1차 구현 후 재검증 완료. doc4 KPI 범위(κ/ICC·환각률)는 신청서 본문 미명시 — 별도 평가설계 문서 근거 가능성(과대해석 금지). +그 외 항목(H1 KPI 수집, H4 한국어 이름/기관 NER와 동의 게이트, M1~M2, X1~X2, L1)은 분석 결과이며 착수 전 코드 재확인 권고. M3은 1차 구현 후 재검증 완료. doc4 KPI 범위(κ/ICC·환각률)는 신청서 본문 미명시 — 별도 평가설계 문서 근거 가능성(과대해석 금지). --- @@ -74,10 +74,10 @@ - **현재상태**(✓직접검증): personas 라우트에 검수 승인/반려만, draft 생성·편집 API 없음. persona_repository는 in-code SEED(P1~P3)만, 외부 JSON 미로드. - **권고**: 페르소나 저작 CRUD(draft→review)와 P4~P7 적재, 루브릭·이론 콘텐츠를 임상팀 편집 가능 데이터로 외부화. -### [high] H4. PII 마스킹 한국어 공백 + 외부전송 live proof 잔여 +### [high] H4. PII 마스킹 한국어 이름/기관 NER + 동의 게이트 잔여 - **근거**: doc1/2/5(실명·날짜·장소·금액·미성년·자살시도 다수), doc4(IRB·개인정보) -- **현재상태**(재검증): Presidio language='en' 고정으로 이름/기관명은 NER 보강이 필요하다. 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐고, 상담 생성(generate/stream)·fast/deep 평가 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재한다. prompt/completion 본문은 저장하지 않는다. consent_at 컬럼만, 동의 수집/게이트/철회 엔드포인트 전무. -- **권고**: 한국어 이름/기관 NER 추가, 실제 운영 로그인 `/turn` 후 `audit.llm_call_log` row 실측, 미성년/guardian 동의 수집·하드게이트·철회. +- **현재상태**(재검증): Presidio language='en' 고정으로 이름/기관명은 NER 보강이 필요하다. 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐고, 상담 생성(generate/stream)·fast/deep 평가 호출 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재한다. prompt/completion 본문은 저장하지 않는다. 로컬 dev-login 실제 `/turn` smoke에서 `audit.llm_call_log` 3행 증가를 확인했다. consent_at 컬럼만, 동의 수집/게이트/철회 엔드포인트 전무. +- **권고**: 한국어 이름/기관 NER 추가, 미성년/guardian 동의 수집·하드게이트·철회. 공개 Google OAuth 실제 `/turn` proof는 별도 운영 게이트. ### [medium] M1. 비언어/준언어 임상 이벤트 캡처·태깅 부재 - **근거**: doc1/2/5(침묵 초·한숨·울음·떨림을 1급 단서) @@ -98,10 +98,10 @@ - **현재상태**: `scripts/export-recursive-dataset.py`와 `app.services.dataset_export`로 masked-text JSONL dry-run, PII scan, kappa/ICC 계산, approved export 게이트를 구현했다. 기본 산출물은 `technical_dry_run`이며 실제 승인 export·골든셋 승격은 데이터 steward/legal review와 IAA 통과가 필요하다. - **권고**: 파일럿 evidence에서 reviewer disposition, steward/legal 승인, gold annotation 라운드 적재 후 `approved_for_recursive_learning_seed` 승격 검증. -### [medium/추적] X2. AI API 비용 관측·예산 경고 1차 완료·최적화 미구현 +### [medium/추적] X2. AI API 비용 관측·예산 경고·평가 저비용 라우팅 1차 완료 - **근거**: doc3(회의록이 'AI API 비용'을 운영 리스크로 명시) -- **현재상태**: 1차로 턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱·저비용 모델 분기는 아직 없다. -- **권고**: 캐싱, 저비용 모델 분기, 장기 비용 추이/한도 정책. +- **현재상태**: 1차로 턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. `EVALUATOR_FAST_MODEL`/`EVALUATOR_DEEP_MODEL` 설정 시 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달하고, 비워두면 기존 gateway default 라우팅을 유지한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱은 L0~L2 cache hint와 gateway session reuse까지만 연결돼 있다. +- **권고**: semantic cache, 장기 비용 추이/한도 정책, 운영 모델별 비용 검증. ### [low] L1. 기술스택 신청서-구현 불일치 및 단기일정 산출물 압박 - **근거**: doc4(Spring Boot 3/Node.js·TimescaleDB vs 실제 FastAPI/Python), doc3(20주) @@ -115,8 +115,8 @@ - C3 1차 완료: `theory_mode`가 세션·평가·생성 프롬프트까지 흐른다. 후속은 임상팀 CBT 체인·이론부합 루브릭·명시적 선택 UI. - H2 1차 완료: `make_eval_hook`과 stream 평가가 턴 파이프라인에 붙고 정규화 테이블로 적재·복원된다. 대안발화도 `app.alternative_utterance`로 정규화한다. 후속은 2열 리뷰 UI·골든셋. - H3: 페르소나 저작 CRUD + P4~P7 로드 경로. -- H4(부분): 한국어 이름/기관 NER, 운영 로그인 `/turn` 후 llm_call_log row 실측, 동의 게이트. -- X1: dry-run JSONL export·PII scan·IAA 계산 1차 완료. `ds.*` write는 `--write-dataset` 명시 시에만 수행한다. X2 비용 관측·budget alert 1차는 완료했고 캐싱·저비용 모델 분기는 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속. +- H4(부분): 한국어 이름/기관 NER, 동의 게이트. LLM call audit 적재와 로컬 live row proof는 완료. +- X1: dry-run JSONL export·PII scan·IAA 계산 1차 완료. `ds.*` write는 `--write-dataset` 명시 시에만 수행한다. X2 비용 관측·budget alert와 evaluator 모델 override 1차는 완료했고 semantic cache·장기 한도 정책은 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속. ### B. 소유자 결정 / 외부(임상팀·기관) 의존 - **임상팀(구훈정·어유경) 산출물**: C1 채점 루브릭·항목 확정, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩 — 콘텐츠는 doc3 R&R상 임상팀 소유. 코드는 구조를 선제 구축하되 임상 문안과 평가기준은 외부 정의로 받는다. diff --git a/scripts/dev-up.ps1 b/scripts/dev-up.ps1 index 77637ec..27da3ba 100644 --- a/scripts/dev-up.ps1 +++ b/scripts/dev-up.ps1 @@ -227,12 +227,16 @@ function Ensure-DevDb { } Write-Host '[1/4] 기존 스택 정리...' -Stop-Stale 'engine_gateway\.gateway' 'gateway' -Stop-Stale 'app\.main:app' 'api' -Stop-Stale 'vite' 'web' -Stop-ListenerByPort 9099 'gateway' +if (-not $NoGateway) { + Stop-Stale 'engine_gateway\.gateway' 'gateway' + Stop-ListenerByPort 9099 'gateway' +} +Stop-Stale ('app\.main:app.*--port\s+{0}' -f $ApiPort) 'api' Stop-ListenerByPort $ApiPort 'api' -Stop-ListenerByPort 5173 'web' +if (-not $NoWeb) { + Stop-Stale 'vite.*--port\s+5173' 'web' + Stop-ListenerByPort 5173 'web' +} Start-Sleep -Seconds 2 if (-not $NoDb) {
Web typechecknpm run typecheckPassed
API typegen SSOTnpm run check:api-typesPassed; FastAPI OpenAPI → src/lib/api.gen.ts stale check
Backend pytestpython -m pytest app/ -q119 passed
Backend pytestpython -m pytest app/ -q122 passed
X2 evaluator model routingpython -m pytest app/test_evaluator_model_routing.py app/test_runtime_policy.py -q23 passed; fast/deep evaluator model override and blank-default routing covered
C1 case worksheetpython -m pytest app/test_session_turn_persistence.py -q / session-review.spec.ts14 passed; session review exposes transcript-grounded caseWorksheet and UI evidence jump
M3 auth claim mappingpython -m pytest app/test_auth_providers.py -q22 passed; Google/SAML cohort maps, provider external_id, provider error reason covered
CrisisGate 109python -m pytest app/test_session_turn_persistence.py app/test_voice_ws.py -q20 passed; real crisis stops before engine, returns 109 resource, safety event DB insert payload covered