02 API and Contracts

API와 저장소 간 계약

Internal API

Method	Path	용도	인증
POST	/internal/v1/analyses	PLAN·ANALYZE	Internal Bearer
GET	/internal/v1/intent/status	Intent 설정·가용성·Prompt 버전	Internal Bearer
GET	/internal/v1/intent/readiness	Intent warmup/readiness	Internal Bearer
POST	/internal/v1/workflows/renewal/run	Renewal Graph 실행·재개	Internal Bearer
POST	/internal/v1/ocr/worker-documents/{id}	Stateless CLOVA OCR	Internal Bearer
POST	/internal/v1/language-assistant	구조화 다국어 안내 생성	main은 route-level Bearer 미적용

/internal/v1/language-assistant의 인증 일관성은 운영 노출 전 확인이 필요합니다. 인프라 경계만 믿고 외부에 직접 공개하지 않습니다.

Document API

기본 prefix는 /api/v1/documents입니다.

• GET /capabilities
• GET /templates
• GET /templates/{template_id}
• POST /inspect
• POST /edit
• POST /generate
• POST /generate/from-txt
• POST /convert

문서 생성 API가 반환한 파일과 Renewal 응답의 임시 경로는 영구 저장소가 아닙니다. Server가 파일을 받아 소유권·tenant 범위와 함께 영속화해야 합니다.

PLAN → ANALYZE

PLAN
→ Intent 모델 최대 1회
→ detectedIntent + workflowId + requiredFieldKeys
→ Server가 결정과 모델 메타데이터 저장
→ DB Context 조회

ANALYZE
→ plannedIntent + plannedWorkflowId 수용
→ Intent 모델 재호출 0회
→ Slot 누락 또는 Candidate 검증

핵심 규칙:

• detectedIntent와 workflowId는 역할이 다릅니다.
• Workflow ID는 WF-STY-001 같은 Knowledge canonical ID입니다.
• ANALYZE Candidate의 workflowId는 plannedWorkflowId와 같아야 합니다.
• ANALYZE의 confidence는 null, providerAttemptCount는 0입니다.
• A.X는 확률을 제공하지 않으므로 confidence=null입니다.
• A.X 선택 전 BERT 점수는 bertRoutingScore로만 보존합니다.
• evidence는 Slot이 아니며 extractedSlots에 가짜 key로 넣지 않습니다.
• MVP는 발화당 대표 Intent·Workflow 한 쌍을 처리합니다.

상세 계약: docs/analyses-contract.md

Renewal 실행

Server는 Worker·Company·Task 스냅샷, Slot, 문서 메타데이터와 승인된 OCR 결과를 전달합니다.

주요 응답:

• scenario: ask_hr | ask_worker | ocr | generate | out_of_scope
• status, outcome
• missingSlots, requestedFields
• caseSignals, progressEvents
• workerRequestMessage
• ocrResult
• generatedDocuments

develop에는 AI #44의 guideReviewRequired, guideFailureCode가 포함되어 있지만 2026-08-16 main에는 아직 없습니다. Server와 Client의 fail-closed 계약을 운영에 쓰려면 통합 후 main 배포를 확인해야 합니다.

호환성 버전

2026-08-16 main 기준:

항목	값
Analyses contract	1.1.0
Context Pack	0.2.0
Workflow Catalog	0.2.0
A.X Prompt	knowledge-25e778ad

Knowledge 0.3.0 소비 전환은 AI #51에서 관리합니다.

직렬화 규칙

• Analyses 외부 계약은 camelCase입니다.
• Renewal 요청·응답도 Pydantic alias를 통해 camelCase를 사용합니다.
• OCR 계약은 snake_case입니다.
• 예시와 실제 모델의 alias를 동시에 변경하지 말고 Server 계약 테스트와 함께 갱신합니다.