[EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP

[hywznn]

한 줄 목표

FOWOCO Server가 HR의 요청을 복구 가능한 AI Run → 검증된 후보 → 사람 승인 → 근로자 보안 링크 → 증빙·완료·감사로 연결하는 MVP를 완성합니다.

대표 흐름: “응웬반A 체류연장 준비하고 여권 사본도 요청해줘” → 후보 2개 → HR이 채택한 후보만 Task 생성 → 별도 승인 후 근로자에게 전달

처음 보는 분을 위한 핵심

Server는 AI 모델이 아니라 업무 운영과 통제의 최종 책임자입니다. AI는 후보를 제안할 뿐 Task 상태, 승인, 발송, 완료를 직접 바꾸지 못합니다.

React Client / Worker Public Link
             ↓
Spring Boot Server ── POST /internal/v1/analyses ──→ AI Runtime
  인증·tenant·DB                                    Prompt·Agent·Model
  Task·승인·감사                                    Structured Output
             ↑                                             ↓
             └──── 검증된 후보·버전·오류 ───── Knowledge Bundle

저장소별 책임

저장소	소유하는 것	소유하지 않는 것
server	인증, 사업장 격리, Worker/Document/Task, Task Workflow, 승인·증빙·감사, Worker Link, 영속 AiRun, 멱등성·업무 재시도	Prompt, Provider SDK, 모델 선택
ai	내부 AI Runtime API, Prompt, Agent Pipeline, Provider/Model Adapter, Structured Output 생성, 한 attempt 안의 Provider retry	운영 DB, Task 상태, 승인·발송
knowledge	Intent/Domain/Slot, Workflow Catalog, Context Pack, 공식 근거, Guardrail, Golden Case를 immutable bundle로 배포	운영 API, 운영 DB

세 저장소 경계의 상세 기준은 Repository Boundaries Wiki와 #23을 따릅니다.

API 계약 기준

• Client·Worker Public API: server OpenAPI가 최종 기준이며 외부 prefix는 /api/v1입니다.
• Server → AI Runtime: ai 저장소의 /internal/v1 OpenAPI가 계약 원본입니다.
• Knowledge: Runtime REST API가 아니라 exact version과 checksum을 가진 release bundle입니다.
• Notion은 초보자용 설명·예제 mirror, Figma는 사용자 흐름의 기준입니다.
• POST /tasks/analyze는 구현하지 않고 영속 resource인 POST /api/v1/ai-runs를 사용합니다.
• 후보 결정 API는 POST /api/v1/ai-runs/{aiRunId}/candidate-decisions입니다. 후보 채택은 Task 생성이지 승인·발송이 아닙니다.

상태를 섞지 않기

개념	예	소유자
AiRun 기술 상태	QUEUED, RUNNING, RETRYING, SUCCEEDED, FAILED	Server
분석 결과	NEEDS_INFO, REVIEW_REQUIRED	AI가 제안, Server가 검증·저장
Task 업무 상태	DRAFT → NEEDS_INFO → READY_FOR_REVIEW → APPROVED → 대기 → COMPLETED	Server

NEEDS_INFO나 낮은 신뢰도는 시스템 장애가 아닙니다. 정상 분석 결과로 저장하고 HR에게 다음 행동을 안내합니다.

현재 역할 분담

실제 작업과 담당자 확인은 GitHub Issue·Project를 기준으로 합니다.

담당	현재 Issue
@hywznn	#24·#77/PR #82, #83 Case, #85 Task 범위
@chaeliki	#7/PR #76, #80 Document, #84 Worker 날짜·비자정보, #15·#16 M4
@krestar	#34 PostgreSQL RLS 후속 단계
공동	#9 Demo deployment, #10 Product E2E, 서로의 PR review

현재 #56과 #74는 완료되었습니다. #76과 #82가 병합 전 검토 단계이며, 실제 AI Runtime 성공 경로는 fowoco/ai#6 계약 반영 뒤 확인합니다.

진행 순서

1. 완료 기반 유지: [Foundation] Spring Boot 개발·검증 기반 정리 #3, [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8/[AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25, [Repository] main 보호 규칙·필수 CI·보안 자동화 구성 #27, [Auth] 사업장 회원가입·초기 ADMIN 계정 생성 API 구현 #43, [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74
2. feat: 근로자 보안 링크(Worker Link) 발급, 안내, 문서제출, 응답제출 구현 #76 수정·리뷰·V11 병합
3. AI Runtime 계약 확인 후 #82를 최신 main에 맞춰 V12/V14·PostgreSQL·실제 smoke 재검증
4. [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 candidate decision → [Case][P0] Case·Workflow Snapshot·업무함 Projection 구현 #83 Case → [Task][P0] 업무 유형·대상 범위 확장 #85 Task 연결
5. [Worker][P0] E-9 업무용 4개 날짜·비자정보 확장 #84 Worker 기준일과 [Document][P0] 문서 상세 조회·상태 표현·HWP/HWPX 업로드 보완 #80 Document 상세·상태 보완
6. [Deploy] PostgreSQL·AI Runtime 기반 데모 배포 구성 #9 Demo deployment와 [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10 Product E2E
7. M4: [Import] 근로자 파일 가져오기·행 검증·재처리 구현 #14, [Dashboard] 오늘 업무 대시보드 요약 API 구현 #15, [Settings] 사업장 설정 조회·수정 API 구현 #16, [Observability] Server Workflow·AI Runtime 경계 추적 구현 #26, [Auth] 비밀번호 재설정·가입 약관 동의 이력 구현 #55

대표 데모는 한 근로자의 3년 만료 요청이 재계약·취업활동기간 연장·체류기간 연장 세 Task로 이어지는 흐름으로 고정합니다.

M3 완료 조건

• 역할·사업장 격리와 개인정보 최소화가 API·통합 테스트로 검증됩니다.
• 복합 요청이 비동기 AiRun에서 두 후보로 분해되고 핵심값이 보존됩니다.
• Server가 AI Runtime 응답을 다시 검증하고 실패 시 가짜 후보를 만들지 않습니다.
• HR이 채택하고 승인한 현재 Task version만 근로자에게 전달됩니다.
• Worker Link 만료·회전·폐기, 응답·파일 제출, 완료 증빙이 동작합니다.
• 서버 재시작·중복 요청·event handler 실패 뒤에도 중복 Task가 생기지 않습니다.
• backend/agent/model/prompt/contextPack/workflowCatalog/contract version과 requestId, latencyMs, parsing error를 안전하게 추적합니다.
• LM Studio 없이 HTTPS demo 환경에서 Product E2E와 장애 시나리오가 통과합니다.

이번 MVP에서 하지 않는 것

• AI의 자동 승인·자동 발송·법률/노무 최종 판단
• Knowledge를 Runtime API로 운영하거나 Server에서 YAML을 임의 복제하는 것
• Server에 OpenAI/Gemini/LM Studio SDK를 직접 넣는 것
• Kafka·Kubernetes·Blue/Green Agent Router의 실제 운영 구현

빠른 링크

• Server Roadmap Project
• M3 Milestone
• Notion API 명세
• Server Wiki