19 KiB
19 KiB
원천문서·갭 로드맵 가이드
한신대 산학협력(구훈정 교수) 원천문서 5종과 거기서 도출된 **갭(부족분)**의 인덱스/로드맵을 한 장으로 정리한 가이드다. 갭 항목의 상세 근거는
docs/ops/source-docs-gap-analysis-2026-06-26.md에, 상태·결론의 권위 기준(SSOT)은docs/dev_dashboard.html의 "원천문서 갭 분석" 섹션에 있다. 이 가이드는 그 두 산출물을 요약·링크한다.
0. 이 문서를 읽는 법 (3분)
- 무엇인가: Vignette(AI 심리상담 시뮬레이션 훈련 플랫폼)가 산학협력 원천문서가 요구하는 임상 사양 대비 어디가 비어 있는지를 심각도(critical/high/medium+)로 분류한 인덱스다.
- 왜 있는가: 어떤 갭이 "코드만 고치면 되는 것"이고, 어떤 갭이 "임상팀/기관/소유자 결정이 선행돼야 하는 것"인지 구분해 착수 순서를 정하기 위함이다.
- 권위 순서(SSOT):
docs/dev_dashboard.html→ "원천문서 갭 분석 (2026-06-26)" 섹션 = 상태·결론의 단일 진실원천(SSOT).docs/ops/source-docs-gap-analysis-2026-06-26.md= 그 SSOT 항목의 상세 근거(원천문서 요지·항목별 근거·검증 메모).- 이 가이드 = 위 둘의 요약 + 빠른 진입 인덱스.
- 핵심 R&R 한 줄: 콘텐츠(워크시트 문항·채점 루브릭·이론 프롬프트·위기 스크립트·골든셋)는 임상팀(구훈정·어유경) 소유, 기술팀은 "편집 가능한 구조"만 선제 구축한다. (출처: doc3 회의록 R&R)
원천 산출물 바로가기
| 산출물 | 경로 | 역할 |
|---|---|---|
| 갭 상세 분석 | docs/ops/source-docs-gap-analysis-2026-06-26.md |
원천문서 요지·항목별 근거·직접검증 메모·판독 한계 |
| SSOT 대시보드 | docs/dev_dashboard.html (# "원천문서 갭 분석" 섹션) |
상태·우선순위의 권위 기준, 갭 요약 카드 |
| 데이터 거버넌스 게이트 | docs/ops/hanshin-data-governance-gate.md |
H4/M3 관련 거버넌스 |
| 백로그 | docs/ops/backlog-2026-06-26.md |
실행 작업 목록 |
| 레이아웃 핸드오프 | docs/ops/layout-redesign-handoff-2026-06-26.md |
UI 재설계 맥락 |
1. 원천문서 5종 (한신대 산학협력 · 구훈정 교수)
5종 문서를 PDF로 변환해 시각 정독(에이전트 1/문서)하고 Vignette 코드베이스 4개 도메인을 교차 조사한 뒤, 1차 종합 → 적대적 비평 → 최종 재구성한 결과다(워크플로우 source-docs-gap-analysis, 에이전트 12, 토큰 약 1.11M).
| ID | 문서 | 핵심 함의(Vignette 그라운드 트루스) |
|---|---|---|
| doc1 | 청소년·대학생 사례 워크북(3·4장) | 첫 회기 축어록→사례개념화→목표·전략 표준 분석틀 + 두 사례(비자발 청소년/자발 대학생). 페르소나 완성형 스펙, openness 곡선 정량 근거, 위기 프로토콜, 다회기 아크(2~10회기), 회기리뷰 주석 포맷의 기준점. |
| doc2 | 인간중심접근 사례·프로토콜(4장) | 미혼모 3회기 상담의 인간중심 사례개념화 정답지. theory_mode=humanistic 1급 필드, 공감·반영 정확도 기반 openness, 회기리뷰 채점 루브릭의 직접 근거. |
| doc3 | 산학협력 회의록(2026-06-08) | 3주체(임상팀 구훈정·어유경 / 트웬티온스 / 사업단 김시윤) 협력·거버넌스 확정. R&R: 콘텐츠·평가기준=임상팀 소유, 구현=기술팀. 평가 루브릭은 임상팀이 외부 정의·수정 가능해야 함. AI API 비용을 운영 리스크로 명시. |
| doc4 | 산학협력 신청서(공식 계약) | 기간(2026.5.18~9.30, 20주)·예산·평가지표·산출물·서약의 권위 원천. humanistic+CBT 2종 필수 이론을 '단계적 프롬프트 체인'으로 계약, 3척도 사전사후·20명 실험/통제군·단회기 50분, 9월 저작권 등재, IRB 100% 준수. 기술스택 명시(Spring Boot 3/Node.js·TimescaleDB — 실제 FastAPI/Python과 불일치). |
| doc5 | 사례개념화 워크북(3장, 상호작용 분석 추가본) | 비자발 청소년(자살사고) 축어록(상1~63)에 기법 코딩. 회기리뷰 루브릭·기법 코딩 택소노미(κ/ICC 스킴)·페르소나 사양·종결 규칙의 직접 근거. |
주의(doc4 KPI 범위): κ/ICC·환각률은 신청서 본문에 미명시('정량 신뢰도 확보' 수준). 계약 확정 지표로 단정하지 말 것 — 별도 평가설계 문서로 확정 필요.
2. 갭 로드맵 — 심각도 우선순위
심각도 분류: critical 3 / high 4 / medium+ 6. C1의 "구조 전무"는 1차로 해소됐고, 편집·저장·임상 루브릭·AI 채점은 계속 추적한다. ✓는 작성자가 코드 grep으로 직접 재확인한 항목, (분석)은 분석 결과로 착수 전 코드 1차 재확인 권고.
Critical (3)
| ID | 갭 | 현재상태 | 권고 | 근거 |
|---|---|---|---|---|
| C1 | 사례개념화·치료계획 산출물 구조 1차 구현·고도화 필요 | SessionReviewResponse.caseWorksheet와 리뷰 화면 read-only 카드가 축어록 근거 기반 초안을 제공한다. CCD는 숨은 정답키이고, 현재 워크시트는 저장형 학습자 제출물은 아님. |
편집·DB 저장형 워크시트, AI 축어록 초안 추출 고도화, 규칙 기반 채점, 교수자 검수 플로우. 루브릭은 임상팀 외부 정의 가능하게 외부화. | doc1·doc4·doc5 |
| C2 | 위기개입 프로토콜·생명유지서약·에스컬레이션 1차 배선 완료·임상 고도화 필요 | 실제 자해·자살 신호는 LLM/엔진 호출 전 중단하고 109 리소스와 conversation_stopped를 REST/SSE/voice 응답에 싣는다. crisis.risk_level은 상태머신 ideation_observed로 전달하고, escalate 시 app.safety_events detail 적재 및 교수자 대시보드 안전 알림 큐로 연결한다. |
남은 것은 임상팀 콘텐츠: 비밀보장 예외고지→단계적 탐색→생명유지서약 스크립트, 실시간 push/메일 알림 정책, 위기탐색 누락 시 회기리뷰 감점 루브릭. | doc1·doc5(핵심 시나리오)·doc4(IRB 전제) |
| C3 | 이론모드 1차 배선 완료·CBT 콘텐츠/선택 UI 잔여 | TurnContext/prepare_turn/sessions/voice/evaluator에 theory_mode가 전달되고, build_turn_messages도 인간중심·CBT·통합 이론 프레이밍을 엔진 메시지에 넣는다. 프론트는 persona.theory_target 기준으로 시작해 기존 humanistic 하드코딩을 제거했다. |
임상팀이 확정한 CBT 단계 프롬프트 체인, 이론부합 채점 루브릭, 학습자/교수자용 명시적 이론 선택 UI. 현재는 페르소나 설계 이론 자동 선택이다. | doc4(humanistic+CBT 필수)·doc2/doc5 |
High (4)
| ID | 갭 | 현재상태 | 권고 | 근거 |
|---|---|---|---|---|
| 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) 2차 구현·임상 검수 잔여 | draft 생성·조회·편집·검수요청 API와 교수 콘솔 JSON 초안 패널은 연결됐다. persona_repository.py는 in-code SEED_PERSONAS(P1data/personas/P4.jsonP7.json을 PersonaCard로 합쳐 materialize_seed_personas()와 seed fallback catalog에 포함한다. |
JSON 대신 항목형 저작 UI, 루브릭·이론 콘텐츠 외부화, P4~P7 포함 임상팀 최종 검수/서면 evidence 확보. | doc3(R&R)·doc4(페르소나=전문가 산출물) |
| 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행 증가를 확인했다. app_user.consent_at 기반 학습자 동의 수락/철회 엔드포인트와 회기 시작·voice dev persona 시작 하드게이트를 추가했고, 프론트 세션 시작 전 동의 UI와 E2E 동의 seed를 연결했다. |
한국어 이름/기관 NER 추가, 미성년/guardian 및 법무 검토가 필요한 서명 동의서/개인정보 고지 evidence 확보. 공개 Google OAuth 실제 /turn proof는 별도 운영 게이트. |
doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보) |
Medium+ (6) — M1M3, X1X2, L1
| ID | 갭 | 현재상태 | 권고 |
|---|---|---|---|
| M1 | 비언어/준언어 임상 이벤트 캡처·태깅 부재 | voice.py는 EOT용 silence_ms만, 침묵·한숨·울음 타임스탬프 이벤트 캡처·리뷰 표시 전무. 서버 RMS 힌트 프론트 미사용(dead). (분석) |
침묵·한숨·울음을 타임스탬프 메타 이벤트로 보존·시각화, '침묵 견디기'를 역량 지표화, 페르소나 의도적 침묵·비유창 한국어 렌더링. |
| 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차 완료·평가 저비용 라우팅 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 비용'을 운영 리스크로 명시.
3. R&R — 누가 무엇을 소유하는가
원칙(doc3 회의록): 콘텐츠는 임상팀 소유, 코드는 "편집 가능 구조"만 선제 구축. 코드와 콘텐츠를 한 PR에 섞지 말 것 — 구조(스키마·폼·주입 경로)는 기술팀이 먼저 만들되, 그 안에 들어갈 임상 문안은 임상팀이 데이터로 채운다.
A. 즉시 착수 가능 (내부 코드, 외부 합의 불요)
- C1 1차 완료:
caseWorksheet응답 구조와 리뷰 화면 read-only 워크시트 카드. 후속은 저장형 입력 폼·임상 루브릭·AI 추출/채점. - C2 1차 완료: 위기 신호는 엔진 전 중단, 109 안내,
safety_events적재, 교수자 알림 큐,ideation_observed전달까지 배선했다. 후속은 임상 스크립트·서약 문안·감점 루브릭. - C3 1차 완료:
theory_mode가 세션·평가·생성 프롬프트까지 흐른다. 후속은 임상팀 CBT 체인·이론부합 루브릭·명시적 선택 UI. - H2 1차 완료:
make_eval_hook과 stream 평가가 턴 파이프라인에 붙고 정규화 테이블로 적재·복원된다. 대안발화도app.alternative_utterance로 정규화한다. 후속은 2열 리뷰 UI·골든셋. - H3 2차 완료: 페르소나 저작 CRUD(draft→review)와 P4~P7 저장소 JSON 로드 경로가 붙었다. 후속은 항목형 저작 UI, 루브릭·이론 콘텐츠 외부화, 임상팀 최종 검수 evidence.
- H4(부분)·X1·X2: 마스킹 한국어 정규식 보강, 외부 LLM 호출 metadata-only
audit.llm_call_log적재 경로, 학습자 동의 수락/철회/회기 시작 하드게이트 골격은 완료했다. 한국어 이름/기관 NER와 guardian/legal 서명 evidence는 후속이다. 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. 소유자 결정 / 외부(임상팀·기관) 의존
- 임상팀(구훈정·어유경) 산출물: C1 채점 루브릭·항목 확정, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩. → 코드는 구조를 선제 구축하되 임상 문안과 평가기준은 외부 정의로 받는다.
- 소유자 평가설계 결정: H1 실험/통제군 배정·3척도 문항·50분 흐름. κ/ICC·환각률 목표는 doc4 미명시 → 평가설계 문서 확정.
- 기관(한신 IT) 의존: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, deprovisioning 거버넌스 증거.
- 거버넌스 결정: L1 스택 정합성 처리 방향, 저작권 등재 문서화 수준, IP 협의.
4. 작업 시작 절차 (체크리스트)
특정 갭(예: C2)에 착수하기 전에:
- SSOT 확인:
docs/dev_dashboard.html의 "원천문서 갭 분석" 섹션에서 해당 항목의 최신 상태/우선순위를 본다. - 상세 근거 확인:
docs/ops/source-docs-gap-analysis-2026-06-26.md의 동일 ID 항목에서 근거·권고·소유 구분(A/B)을 본다. - 코드 1차 재확인:
(분석)표기 항목은 착수 전 grep으로 현재상태를 직접 재확인한다(아래 예시). - 소유 구분 판정: 콘텐츠가 필요한가? → 임상팀 핸드오프 선행. 구조/배선만인가? → 즉시 착수(섹션 3-A).
- 검증 게이트 통과: 변경 후 표준 테스트를 돌린다(아래 명령).
코드 재확인 grep 예시 (저장소 루트 D:/workspace/vignette)
# C1: 사례개념화 워크시트 1차 구조와 잔여 저장/채점 경로 확인
rg -n "caseWorksheet|ReviewCaseWorksheet|사례개념화 워크시트|cognitive_triad|인지삼제|4사분면" apps
# C2: escalate 시 safety_events 적재 여부
rg -n "safety_events|escalate|ideation_observed" apps/api/app/services/orchestrator.py
# C3: 이론모드 스레딩과 생성 프롬프트 주입 확인
rg -n "theory_mode|THEORY_MODE_GUIDANCE|sessionApi.start\\(personaCode" apps
# H2: eval_hook 정의와 주입
rg -n "make_eval_hook" apps/api/app
# H3: 페르소나 seed/materialize 로드 경로
rg -n "SEED_PERSONAS|load_file_personas|built_in_personas|materialize_seed_personas" apps/api/app/persona_repository.py
검증 명령 (변경 후)
# 백엔드 (작업 디렉터리 apps/api)
python -m pytest app/ -q # 현재 118 pass
python -m pytest engine_gateway/ -q # 현재 7 pass
# 프론트 (작업 디렉터리 apps/web)
npm run typecheck
npm run build # vite
npm run e2e # Playwright — web+api+DB 스택 필요
로컬 기동: API는
apps/api에서python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload(pydantic-settings가apps/api/.env자동 로드, DB 미가용 시 in-memory degraded 폴백). 웹은apps/web에서npm run dev(http://localhost:5173,/api→127.0.0.1:8000 프록시). AI 턴 생성은ENGINE_MODE=claude_cli일 때 engine_gateway가 포트 9099에 떠 있어야 한다.
5. 판독 한계 (정직성)
- 핵심 축어록 2단 표(doc5 상1~63, doc2 3회기 표)는 txt 추출 시 일부 누락 — PDF 시각 판독이 1차 근거.
- OCR 잔재·오탈자 존재(doc1·doc5). 의미는 시각 보정했으나 일부 표현 불확실.
- doc4 κ/ICC·환각률은 신청서 본문 미명시 — 계약 확정 지표로 단정 금지.
- doc4/doc3 행정 불일치(참여교수 1명 vs 2명, 서식 연도 '2025' 오기, 연구책임자 표기 불일치, 트웬티온스 성명 공란).
- '현재상태'는 grep/코드 사실 기반 적대적 비평 인용에서 시작했으나, C1·C2·C3·H2·H3·M3은 구현 후 재검증 완료 기준이다. 그 외(H1·H4·M1·M2·X1·X2·L1)는 착수 전 코드 1차 재확인 권고.
변경 이력
- 2026-06-26: 초판.
docs/ops/source-docs-gap-analysis-2026-06-26.md와 SSOT 대시보드 "원천문서 갭 분석" 섹션을 요약·인덱스화.