Repository Boundaries and Contracts

저장소 경계와 계약

이 문서는 FOWOCO에서 어느 저장소가 무엇을 소유하는지 정하는 기준 문서입니다. 같은 기능을 여러 저장소에 복사하지 않고 계약으로 연결하는 것이 목적입니다.

한 문장 책임

저장소	한 문장 책임	소유하지 않는 것
server	인증된 HR 업무의 상태·승인·증빙·감사·전달을 영속적으로 운영	Prompt, 모델 선택, Provider SDK, 지식 원문 편집
ai	versioned Knowledge를 이용해 요청을 해석하고 구조화된 후보를 반환	HR 권한, Task 승인, Worker Link, 업무 DB의 최종 상태
knowledge	검증된 Context Pack·Workflow Catalog·Intent·용어를 immutable bundle로 배포	사용자 요청 처리, DB 상태 변경, Provider 호출
client	사용자 화면과 입력·검토·승인 UX 제공	권한의 최종 판정, Workflow 우회
infra	서비스 간 네트워크·Secret·배포·공통 관측 기반 운영	각 서비스의 Domain 규칙

실행 구조

flowchart TB
  U["HR / Admin / Viewer"] --> C["Client"]
  C -->|"/api/v1/**"| S["Server"]
  S --> D[("PostgreSQL")]
  S --> F["FileStorage Port"]
  subgraph AI["AI Runtime 내부"]
    A["Internal Analysis API"] --> ORCH["Agent Pipeline"]
    ORCH --> L["LLM Provider"]
  end
  S -->|"AiRuntimeClient · POST /internal/v1/analyses"| A
  K["Versioned Knowledge Bundle"] --> A
  K -. "동일 버전의 Workflow snapshot" .-> S

Loading

Knowledge는 런타임 DB처럼 수정하지 않습니다. context_pack_version, workflow_catalog_version으로 식별되는 산출물을 AI Runtime과 Server가 정확한 버전으로 읽습니다.

계약의 소유자

계약	원본 소유자	소비자	변경 규칙
Authenticated REST OpenAPI /api/v1/**	server	client	하위 호환 또는 명시적 API version 변경
Worker Link Token public API	server	Worker 화면	token 범위의 최소 정보만 반환
Internal AI OpenAPI /internal/v1/**	ai	server	Contract test와 compatibility 확인 후 배포
AI Structured Output JSON Schema	ai	server	Server도 응답 수신 시 재검증
Context Pack·Intent·용어	knowledge	ai	immutable release와 version pinning
Workflow Catalog의 Server projection	knowledge	server, ai	동일 catalog version의 read-only 산출물
Task Workflow 상태 전이	server	client, 운영자	Domain test와 Audit 규칙 동시 변경
Event envelope·내구성·재시도 상태	server	Server 내부 handler	DB transaction과 멱등성 보장

Notion은 사람이 읽기 쉬운 설명과 예시를 제공하지만 실행 계약의 원본을 대신하지 않습니다.

Server가 구현하는 AI 경계

Server에는 다음만 둡니다.

• AiRuntimeClient Port
• 개발·테스트용 FakeAiRuntimeClient
• 통합 환경용 RemoteAiRuntimeClient
• Service-to-Service 인증과 timeout·circuit breaker·bulkhead
• 요청 최소화·민감정보 제거의 최종 방어선
• Internal API response의 JSON Schema와 핵심값 재검증
• AiRun 실행 상태, idempotency, retry command, Audit
• AI Runtime이 돌려준 agent_version, model_*, prompt_version, context_pack_version, workflow_catalog_version, latency_ms, error_code 저장

Server에 다음 코드를 만들지 않습니다.

• OpenAiClient, GeminiClient, LmStudioClient 같은 Provider 구현
• Prompt template과 Prompt 조립기
• 모델 routing·fallback·sampling parameter
• Knowledge 원문, embedding, RAG index 생성
• 모델 응답을 후보로 만드는 Agent Pipeline

서로 다른 세 가지 상태

상태를 하나의 enum으로 합치면 책임이 뒤섞입니다.

구분	소유자	값
Task Workflow	Server	DRAFT, NEEDS_INFO, READY_FOR_REVIEW, APPROVED, WAITING_WORKER, WAITING_EXTERNAL, COMPLETED, CANCELLED
AiRun 실행	Server	QUEUED, RUNNING, RETRYING, SUCCEEDED, FAILED
AI 업무 판정	AI 계약, Server 검증	NEEDS_INFO, REVIEW_REQUIRED

예를 들어 AiRun=SUCCEEDED이면서 outcome=NEEDS_INFO일 수 있습니다. 호출은 성공했지만 업무에 필요한 정보가 부족하다는 뜻입니다.

버전과 추적

모든 AiRun은 최소한 다음 정보를 남깁니다.

backend_version
agent_version
model_provider / model_name / model_version
prompt_version
context_pack_version
workflow_catalog_version
request_id / trace_id
latency_ms
parsing_error / error_code

Server는 이 값을 직접 만들어 Provider를 제어하는 것이 아니라, 배포 설정과 AI Runtime 응답에서 받은 값을 검증해 기록합니다.

변경 절차

1. 의미·정책 변경이면 knowledge에서 새 bundle version을 만듭니다.
2. Prompt·모델·Structured Output 변경이면 ai에서 contract와 evaluation을 갱신합니다.
3. Server External API·권한·Task 상태 변경이면 server에서 OpenAPI와 Domain test를 갱신합니다.
4. 소비 저장소에서 Contract test를 먼저 통과시킵니다.
5. staging에서 정확한 version 조합으로 smoke/evaluation을 통과시킵니다.
6. 배포한 version 조합을 기록하고 문제가 있으면 이전 조합으로 되돌립니다.

Issue를 어디에 만들까요?

요청 예시	저장소	이유
“AI가 여권 요청과 체류연장을 분리하지 못함”	ai, 필요 시 knowledge	해석·지식 품질 문제
“후보 승인 전 Worker Link가 발급됨”	server	승인·Workflow guard 문제
“체류연장 필수서류 목록이 틀림”	knowledge	검증된 업무 규칙 문제
“OpenAI timeout을 다른 모델로 fallback”	ai	Provider orchestration 문제
“AI Runtime timeout 때 Run을 재처리하고 싶음”	server	영속 실행과 사용자 command 문제
“버튼에서 후보 두 개를 선택하고 싶음”	client	검토 UX 문제

한 변경이 여러 저장소에 걸리면 저장소별 Issue를 만들고 서로 링크합니다. 하나의 Issue에 모든 구현을 섞지 않습니다.

반드시 지킬 금지선

• AI Runtime이 Server DB에 직접 접속하지 않습니다.
• Knowledge bundle이 사용자별 개인정보를 포함하지 않습니다.
• Client가 Task 상태를 임의로 덮어쓰지 않습니다.
• Server가 AI 결과를 HR 승인 없이 근로자에게 보내지 않습니다.
• Server와 AI가 같은 Prompt/Schema 파일을 각각 복사해 관리하지 않습니다.
• 장애 시 Fake 응답을 실제 AI 성공처럼 반환하지 않습니다.