01 Architecture and Ownership

아키텍처와 역할 경계

전체 흐름

Client/Rule Event
→ Server
→ AI PLAN: 대표 Intent·Workflow와 필요한 Context 결정
→ Server: 같은 회사 범위 DB 조회·대상 후보 확정
→ AI ANALYZE: PLAN 결정 재사용, Slot·Context 검증
→ Server: Case·Task 생성 및 실행 이력 저장
→ AI Renewal: 안내·OCR 결과 병합·문서 초안 분기
→ Server/Client: HR 검토·승인·파일 저장·후속 실행

AI 내부 구성

구성	책임	현재 구현
Analyses Pipeline	PLAN/ANALYZE, Intent·Workflow·Slot 검증	구현됨
Intent Agent	고정 Stub 또는 HF BERT + 선택 A.X	환경변수 기반 opt-in
Renewal Graph	Rule Supervisor, ask_hr/ask_worker/ocr/generate 분기	구현됨
Language Assistant	표준·쉬운 한국어와 대상 언어 생성	Provider 구성 시 동작
OCR API	CLOVA Template OCR와 필드 정규화	Provider 구성 시 동작
Renewal OCR Bridge	Server가 전달한 OCR 필드 병합	구현됨, 값이 없으면 Stub 폴백
Document Engine	HWP/HWPX 검사·편집·생성·변환	구현됨, 템플릿별 실패는 Stub 메타 반환 가능
Runtime Store	Renewal 재개용 상태	현재 프로세스 메모리 기반

책임 경계

AI

• HR 발화에서 대표 Intent와 canonical Workflow 선택
• 필요한 Server Context key 반환
• PLAN 결정을 재사용해 누락 Slot과 실행 후보 검증
• Renewal Graph 분기와 Case Signal 반환
• Language/OCR/Document Provider 호출 및 안전한 실패 결과 반환
• 문서 입력값과 임시 생성 결과 반환

Server

• Worker·Company·Case·Task·Document 원본 관리
• tenant/권한/인증과 내부 Bearer Token 관리
• 대상 Worker 검색과 다중 후보 선택 처리
• PLAN 결과·모델 경로·감사 로그 영속화
• OCR 결과 검토·암호화·State 병합
• 생성 파일 영속화, 승인, 링크 발급, 후속 Workflow 재호출

Knowledge

• Intent 정의와 canonical Workflow ID
• Workflow별 필수·선택 Slot
• 공식 출처, 사용자 표시명, Gold Case
• 계약 버전과 호환성 기준

Client와 HR

• 분석 근거와 후보 표시
• 모호한 대상·다중 후보 선택
• 안내문·문서 초안 검토
• 실제 제출·결과·증빙 등록

중요한 비소유 영역

AI가 하지 않는 일:

• Server PostgreSQL 직접 접근
• 근로자 후보 자동 확정
• OCR 민감정보의 원본 DB 자동 덮어쓰기
• 법적 체류 상태 또는 해고 판단 확정
• 근로자 안내 자동 발송
• 정부기관 자동 제출
• 최종 승인

주요 코드 위치

영역	경로
FastAPI 조립	app/main.py
Dependency 조립	app/api/dependencies.py
Analyses	app/agents/pipeline.py
Intent	app/agents/intent/
Renewal Graph	app/agents/workflow_graph/
Language	app/agents/language/
OCR	app/ocr/
Documents	app/documents/