[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를 기준으로 하고, Notion API 명세는 요청값·응답·권한을 설명하는 문서로 동기화합니다.

담당	현재 Issue
@hywznn	#8 AI Integration 진행, #25 Reliability 준비됨, #24 AiRun은 #25 뒤, #45 DB 문서 Wiki 마무리
@chaeliki	#13 Document·File 진행, #7 Worker Link는 #13 뒤, #48 민감정보 정책 결정 대기, #15·#16 M4
@krestar	#34 PostgreSQL RLS 후속 단계 진행
공동	#9 Demo deployment, #10 Product E2E, 서로의 PR review

현재 #8·#13·#34가 진행 중이며, 바로 시작 가능한 다음 P0 작업은 #25입니다. #24는 #25, #7은 #13이 끝나야 시작할 수 있습니다. #48은 민감정보 필요성·API·권한·암호화 정책이 확정될 때까지 차단합니다. #9는 #7·#8·#24·#25, #10은 #9가 완료된 뒤 진행합니다. Raw workload는 대략적인 난이도 참고값일 뿐 담당 비율이나 완료율이 아닙니다.

진행 순서

1. 완료 기반 유지: [Foundation] Spring Boot 개발·검증 기반 정리 #3, [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23, [Repository] main 보호 규칙·필수 CI·보안 자동화 구성 #27, [Auth] 사업장 회원가입·초기 ADMIN 계정 생성 API 구현 #43
2. 현재 진행: [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8 AI Integration, [Document] 통합 문서함·파일 업로드·문서 준비도 구현 #13 Document/File, [Security] PostgreSQL RLS 기반 사업장 2차 격리 안전 도입 #34 RLS 후속 단계
3. 다음 착수: [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25 Outbox/Reliability
4. 선행 완료 후: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiRun과 [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7 Worker Link
5. 통합 단계: [Deploy] PostgreSQL·AI Runtime 기반 데모 배포 구성 #9 Demo deployment와 [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10 Product E2E
6. M4: [Import] 근로자 파일 가져오기·행 검증·재처리 구현 #14 Import, [Dashboard] 오늘 업무 대시보드 요약 API 구현 #15 Dashboard, [Settings] 사업장 설정 조회·수정 API 구현 #16 Settings, [Observability] Server Workflow·AI Runtime 경계 추적 구현 #26 Observability
7. 문서 마무리: [Tooling] Flyway 기반 DB 스키마·Migration 문서 자동 공유 구성 #45 Wiki 링크 반영 후 완료 처리

GitHub의 native blocked by는 실제 통합·병합 선행조건을 나타냅니다. 선행조건이 남아 있어도 Fake Port나 독립 domain으로 시작할 수 있는 범위는 Issue 본문과 PR에 분리해 기록합니다.

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