감정 관측 운영 검증과 문서 동기화

docs/guides/architecture.md

@@ -137,6 +137,11 @@ DB readiness는 auth/admin 테이블뿐 아니라 세션 read-model 핵심 테
 `TurnContext`/`TurnResult`/`StreamEvent` dataclass가 파이프라인을 관통한다. `EvalHook`/`LogHook`은
 `Callable[[TurnContext, str], Awaitable[...]]` 타입으로 주입된다.
 
+Jev가 남기는 `client_affect_trace`는 `TurnContext`의 관리자 관측 전용 내부 필드다. 공개 `TurnResult`,
+SSE `done`, `TurnRecord` JSON, `provider_events`에는 포함하지 않는다. 성공한 내담자 append에서만
+trace insert와 `state_after` upsert를 같은 DB transaction으로 묶고, 실패 시 rollback한다. legacy·위기·실패·취소
+경로는 trace 없이 기존 상태 갱신 계약을 유지한다.
+
 ### 2.3 페르소나 메시지 빌더 — `app/services/persona.py` (L0~L6)
 
 `build_turn_messages(card, state, learner_text_masked, ...)`가 한 턴의 `EngineMessage[]`를 조립한다.
@@ -414,7 +419,8 @@ session lifecycle을 유지하며, future Node read API는 이 read-model contra
   목표를 달성해도 시간 내에는 계속 진행한다(상태머신은 채점·표시용으로만 유지).
 - `POST /sessions/{id}/turn` — 동기 경로. `prepare_turn` → `run_turn_generate` →
   학습자 발화 turn(speaker=`counselor`, 원문 `text` + `text_masked`) + 내담자 응답 turn(speaker=`client`)
-  순차 append → 상태 갱신. `EngineError`는 503으로 변환.
+  순차 append → 상태 갱신. Jev trace가 있으면 내담자 append·trace·상태 upsert를 하나의 transaction으로
+  실행하고 성공 뒤에만 in-process mirror를 갱신한다. `EngineError`는 503으로 변환.
 - `POST /sessions/{id}/stream` — SSE 경로(`run_turn_stream`). token/done/ping/error를 흘리고,
   done 시점에 학습자 발화 + 누적 내담자 응답 + 상태를 먼저 영속화하고 즉시 완료한다. fast-loop 평가는
   응답 경로 밖에서 같은 learner turn에 사후 저장한다. provider 연결이 깨끗한 EOF로 닫혀도 canonical
@@ -540,6 +546,20 @@ session lifecycle을 유지하며, future Node read API는 이 read-model contra
 - 공유 HTML과 API 도메인 `/robots.txt`는 `noindex`/`Disallow: /share/` 정책을 둔다. 공유 URL은 검색 색인용
   공개 문서가 아니라 교수자 전달용 미리보기 카드다.
 
+### 2.9.4 관리자 감정 관측 — `app/routes/admin.py` + `app/services/admin_affect.py`
+
+관리자 전용 읽기 모델이다. `GET /admin/affect/sessions`는 최근 회기의 식별자·페르소나 코드·시작/종료·trace 수만
+반환하며 learner id·이름·메일을 포함하지 않는다. `GET /admin/affect/sessions/{session_id}`는 연결된 내담자 turn의
+`app.turns.seq`를 cursor로 쓰는 페이지와 저장된 현재 9축 상태를 돌려준다. trace의 상담 왕복 번호 `turn_seq`는
+추이 축용 값으로 cursor와 다르다. 과거 trace가 없는 회기도 조회할 수 있지만 초기값이나 과거 전이를 합성하지 않는다. limit·offset·before_seq 검증은 422, 없는 회기는 404, 권한은 403,
+DB 또는 schema 계약 오류는 503이다.
+
+`app.client_affect_trace`는 migration 23의 turn/session FK cascade, `trace jsonb`, session/time index를 사용한다.
+RLS는 관리자 SELECT만 허용하며, 서버 learner context의 INSERT도 연결된 client turn과 같은 session으로 제한한다.
+learner·teacher의 SELECT/UPDATE는 허용하지 않고, 운영에서 앱이 누락 테이블을 만들지 않는다. trace v1은 실제
+provider/model·latency·token·cost, 상담 왕복 번호 `turn_seq`, policy snapshot, 당시 코드 상태 context와 고정 순서 9축의
+`before/target/after/confidence/probabilities/decision`만 보존한다. 이 값은 실제 사람의 감정 측정이나 진단이 아니다.
+
 ### 2.10 엔진 클라이언트 — `app/engine_client.py`
 
 게이트웨이 HTTP 클라이언트(호출부만). 계약:
@@ -736,6 +756,7 @@ React 19 + Vite. 라우팅은 `apps/web/src/App.tsx`(react-router-dom).
 | `/teach/session/:sessionId/review` | SessionReview(교수자 읽기 전용 회기 검토) | teacher/admin |
 | `/admin` | Admin(운영 홈) | admin |
 | `/admin/ai` | AdminAi(AI 공급자·실시간 모델·추론 강도 드롭다운, 기간별 DB 비용·토큰·계량 커버리지, provider/model 원장, 평가 캐시 효율) | admin |
+| `/admin/emotions` | AdminAffect(회기별 Jev 9축 상태·턴 trace·상태 변화 동행 관측) | admin |
 | `/admin/users` | Admin(사용자 관리) | admin |
 | `/admin/access` | Admin(접근 권한) | admin |
 | `/admin/tickets` | Admin(운영 티켓 처리 큐: 접수, 필터, 카테고리 큐, 우선순위, 수동 상태 변경 감사) | admin |
@@ -828,6 +849,9 @@ DB는 PostgreSQL 16 + pgvector(단일 SoR). 초기화 SQL은 `infra/db/init/`에
   `visible_to TEXT[]`(기본 `{client,counselor,evaluator}`), salience/is_pinned/contradicts,
   음성 paralinguistic(audio_ref/silence_ms/speech_rate/barge_in/provider_events; review는 제한된 taxonomy 칩만 파생). `turn_technique`/`turn_client_state`
   다대다, `supervisor_comment`(rationale/critique + intent_deviation JSONB), `safety_events`.
+- **내담자 감정 trace** `app.client_affect_trace` — 완료된 Jev 내담자 턴의 내부 전이 provenance. `turn_id` 기본키와
+  `session_id`는 `app.turns`/`app.sessions`를 cascade 참조하고, trace와 상태 upsert는 성공한 client append와 같은
+  transaction에 속한다. trace가 없는 과거·legacy·위기·실패·취소 턴은 추정값으로 채우지 않는다.
 - **사례개념화 제출물** `app.case_worksheet` — 회기 리뷰의 축어록 기반 자동 초안을 학습자가 편집해 저장한 JSONB.
   `session_id` 단위 upsert이며, `GET /review`에서 자동 초안보다 우선된다.
 - **교수자 검토 상태** `app.session_review_status` — 교수자/관리자의 회기 검토 상태, 메모, 검토 시각을