09 API Specification

API 명세 안내

이 페이지는 API를 어디서 확인하고, 어떤 기준으로 바꾸는지 설명합니다. 실제 API 개수와 필드 목록을 Wiki에 복사하지 않습니다.

계약의 원본

계약	원본
Server External API	Swagger · OpenAPI JSON
Server ↔ AI Runtime	fowoco/ai의 /internal/v1 OpenAPI·JSON Schema
Intent·Slot·Workflow 의미	fowoco/knowledge versioned bundle
화면 맥락·초보자 설명	Notion API 명세
사용자 흐름	Figma

문서와 코드가 다르면 현재 동작은 main의 OpenAPI와 자동 테스트를 기준으로 합니다. 계획 API는 Issue에, 구현 API는 Swagger에 둡니다.

현재 API 영역

화면·기능	Server API 그룹
Authentication & Onboarding	Auth·Signup·Password Reset·Worker Import
Today	Dashboard·Notification
업무함	Case·Task·Checklist·Approval·Audit
자연어 업무 생성	AiRun·Answer·Candidate Decision·SSE
근로자	Worker·Worker Document·OCR
문서함	Document·File·Draft·Readiness
근로자 모바일	Public Worker Link·Response·Upload
설정	Company Settings·Members

각 Controller 경로, 요청·응답 DTO, 허용 역할과 오류 코드는 Swagger에서 확인합니다.

경로 규칙

• /api/v1/**: HR 화면용 JWT 인증 API
• /public/worker-links/**: 로그인 대신 만료 Token을 사용하는 근로자 API
• /internal/v1/**: Server↔AI Runtime S2S API
• companyId는 요청 Body가 아니라 인증 Context에서 결정
• 생성·재시도·제출 같은 중복 위험 Command는 Idempotency-Key 사용
• 중요한 수정은 expected_version으로 동시성 충돌을 감지

공통 오류

HTTP	의미
400	형식·필수 헤더·필드 검증 실패
401	인증 없음·만료
403	역할 부족
404	Resource 없음 또는 타 사업장 정보 은닉
409	Version·멱등성·중복 충돌
422	형식은 맞지만 현재 업무 상태에서 실행 불가
429	Rate limit
503	AI Runtime 등 일시적 의존성 장애

오류에는 안전한 requestId와 안정적인 code만 포함하고 Stack Trace, Secret, 개인정보와 Provider 원문을 반환하지 않습니다.

공유 Swagger 실제 호출

공유 Swagger는 기본적으로 읽기 전용입니다. 다음 세 조건이 충족되면 Try it out과 Authorize가 자동 활성화됩니다.

1. HTTPS Demo Server가 배포됨
2. Server CORS에 https://fowoco.github.io가 허용됨
3. 저장소 Actions Variable SERVER_PUBLIC_URL=https://...가 등록됨

HTTP Server는 GitHub Pages에서 mixed content로 차단됩니다. Access Token은 Login 응답에서 복사해 Authorize에 넣고, Refresh·Logout Cookie 흐름은 실제 Client에서 확인합니다.

API 변경 순서

1. Issue의 화면·역할·완료 조건과 다른 팀 작업을 확인합니다.
2. Request·Response·오류·멱등성·동시성 계약을 정합니다.
3. Application Service에서 tenant와 Workflow 규칙을 구현합니다.
4. 필요한 경우에만 새 Flyway Migration을 예약합니다.
5. 정상·권한·타 사업장·중복·동시성 테스트를 작성합니다.
6. 같은 PR에서 OpenAPI와 필요한 Notion 설명을 갱신합니다.
7. CI와 Reviewer 승인을 받은 뒤 Squash Merge합니다.

관련 링크: Epic #2 · Server Roadmap · GitHub 협업 가이드