Home

FOWOCO Server Wiki

FOWOCO 서버는 E-9 외국인근로자를 고용한 사업장의 HR·총무 업무를 검토 가능하고 복구 가능한 Workflow로 운영하는 Spring Boot 백엔드입니다.

AI는 판단자가 아니라 보조자입니다. AI 결과는 권한·상태·사람 승인·증빙·감사 규칙 안에서만 사용하며, 장애 때 가짜 성공 결과를 만들지 않습니다.

처음 왔다면

1. MVP 로드맵에서 지금 시작할 Issue와 선행 관계를 봅니다.
2. API 카탈로그에서 46개 API와 소유 Issue를 찾습니다.
3. 백엔드 아키텍처와 신뢰성·관측성에서 모듈·비동기 실행·복구 원칙을 확인합니다.
4. 로컬 개발 가이드로 현재 서버를 실행합니다.
5. Issue의 완료 조건을 읽고 branch와 담당자를 정합니다.
6. 결론 전 질문·비교는 Discussions, 구현이 확정된 일은 Issue에 남깁니다.
7. 데모 전에는 데모 배포 가이드와 GitHub 협업 가이드를 확인합니다.

현재 구현 상태

2026-07-21 기준 목표 API는 46개입니다. 구현된 기능 API는 GET /health 1개이며 나머지 45개는 계획 상태입니다.

PR #22로 Java 17·Spring Boot 4.1, Security 기본 차단, Swagger, Flyway, 공통 오류와 request_id, H2/PostgreSQL 테스트, CI까지 개발 기반은 완료했습니다. Entity·JWT·Worker·Task·AI·Audit 기능은 아직 구현 전이므로 현재 동작은 코드·테스트·Swagger를 우선 확인합니다.

핵심 링크

• MVP Epic #2
• Architecture ADR #23
• M3 Milestone
• M4 Milestone
• Server Roadmap · 팀원 전용
• 서버 Issues
• 서버 Discussions
• Notion API 상세 명세
• Knowledge 저장소

MVP 대표 흐름

HR 로그인 → 근로자 등록 → AI Run 생성(202) → 상태 조회
→ Structured Output 검증 → 후보 확정 → HR 승인
→ 근로자 보안 링크 → 응답·문서 → 증빙·완료 → 감사 이력

대표 입력:

응웬반A 체류연장 준비하고 여권 사본도 요청해줘

기대 결과는 체류연장과 여권 사본 요청 후보 2개입니다. HR이 후보를 확정하고 현재 버전을 승인하기 전에는 근로자에게 전달되지 않습니다.

문서 목록

• 01. MVP 로드맵
• 02. 백엔드 아키텍처
• 03. 도메인과 Workflow
• 04. AI Adapter
• 05. 보안과 개인정보
• 06. 로컬 개발 가이드
• 07. 데모 배포 가이드
• 08. GitHub 협업 가이드
• 09. API 카탈로그
• 10. 신뢰성·관측성
• 용어집

변하지 않는 원칙

• 사업장 데이터는 인증 Context의 company_id로 격리합니다.
• 근로자는 로그인하지 않고 만료·회전·폐기 가능한 보안 링크만 사용합니다.
• 실제 민감식별자와 원본 문서를 AI에 보내지 않습니다.
• AI 호출은 DB에 남는 비동기 Run으로 관리하고 실패 시 가짜 결과를 만들지 않습니다.
• AI 원본과 HR 수정본을 구분하며 중요 변경 뒤에는 재승인합니다.
• 상태 변경과 후속 event는 유실·중복 처리에 안전해야 합니다.
• 모든 중요한 행동과 Agent 배포 단위, request_id, trace_id를 기록합니다.
• 최종 데모는 외부 LLM API 또는 Cloud Endpoint를 사용합니다.