계약 문서 드리프트 정리 — messaging·internal API·ai_server 가이드

[Jaeho-Site]

왜

docs/messaging.md 는 AI↔Core 계약의 SSOT 인데, 구현이 앞서가면서 문서가 뒤처졌다. 프론트가 실제로 소비 중인 필드(highlights[])가 문서에 없고, 반대로 문서에는 코드에 존재하지 않는 필드(voiceAnalysis)가 남아 있었다. 이 상태로는 문서를 보고 연동하면 틀린다.

원칙: ai/ 의 Pydantic 모델이 정본 — 문서를 코드에 맞췄다. 코드·설정·스키마 변경은 0줄.

무엇

docs/messaging.md

• §1·§4: infra/rabbitmq/definitions.json 에 이미 정의·가동 중인 큐들을 정식 표에 편입 — ai.generate.feedback/core.callback.feedback("추가 예정" 표기였음), ai.analyze.voice/core.callback.voice/core.callback.tts(표에 누락) + 대응 DLQ 5개. *(예정)* 표기 제거.
• §5.7: GeneratedQuestion 에 jobCategory·targetEvidence·expectedSignal 반영 (model/messages/questions.py 기준). expectedSignal 은 라이브 비노출(정답 유출 방지) 주석 포함.
• §5.9: FollowupCallbackPayload 에 존재하지 않는 voiceAnalysis 블록 삭제.
• §5.9c/5.9d 신설: 음성 파이프라인(analyze.voice → callback.voice)이 문서 어디에도 없어서 AnalyzeVoiceRequest/VoiceCallbackPayload 실스키마로 문서화. 피드백의 voiceAnalysisSummary 롤업 관계도 명시.
• §5.11: 프론트(FeedbackReport.tsx)가 소비 중인 highlights[] 추가.
• §10: internal API 표에 POST /api/internal/embeddings/search·POST /api/internal/ai-logs 추가.

docs/api-conventions.md

• §2.6 + §10 부록에 같은 internal API 2건 추가 — 요청/응답 스키마는 core/client.py 와 Core 컨트롤러(InternalEmbeddingSearchController, InternalAiLogController) 기준. 검색 실패 시 빈 결과 폴백(non-fatal), ai-logs 는 202 fire-and-forget 임을 명시.

ai/src/ai_server/CLAUDE.md

• 존재하지 않는 chain/parsers/·rag/pgvector_client.py·storage/keys.py·analyzer/feedback_generator.py 참조 제거, 실제 파일명으로 정정 (chunker.py, repository_analyzer.py, model/messages/ 패키지, messaging/consumers/ 구조).
• 미기재 모듈 core/·observability/ 추가. voice/ "(Phase 2)"·runner "(도입 예정)" 라벨을 실구현 상태로 갱신하고 §3 lifespan 예시를 MessagingRuntime 실제 패턴으로 교체.

검증

• 문서-only: git diff --stat 3개 파일 (md), 코드·설정·스키마 0줄.
• 스키마 항목은 전부 코드 대조: model/messages/{questions,followup,feedback,voice}.py, core/client.py, definitions.json, Core 내부 컨트롤러 2개.

남은 드리프트 (이번 범위 밖)

• ai/CLAUDE.md(상위) §2 트리에도 rag/ (계획)·voice/ (Phase 2) 라벨이 남아 있음.
• messaging.md §5.10 generate.feedback 예시가 voiceAnalysisSummary·domainQuestionCounts 등 신필드 미반영.