# backend-integration

## 목적 / 책임

`nomadcode-core`와 기타 NomadCode 인프라의 API 경계를 담당한다. API base URL, health check, task 호출, settings/integration snapshot을 관리하며 현재 일부는 placeholder 상태다.

## 포함 경로

- `src/api/client.ts` : API base URL, URL builder, fetch wrapper, health check
- `src/api/tasks.ts` : task 타입, list API, create/enqueue placeholder
- `src/api/settings.ts` : settings snapshot과 integration status placeholder
- `src/routes/SettingsPage.tsx` : server/integration 상태 화면
- `src/components/settings/` : integration status와 settings section UI
- `.env.example` : Vite API base URL 예시

## 제외 경로

- `src/api/projects.ts` : project inventory mock은 project-workspace
- `src/stores/agentStore.ts`, `src/components/agent/` : agent-workspace
- `src/app/router.tsx`, `src/layout/` : ui-shell

## 주요 구성 요소

- `getApiBaseUrl` : `VITE_NOMADCODE_API_BASE_URL` fallback 처리
- `apiFetch` : JSON API fetch wrapper
- `getServerHealth` : core health 상태 확인
- `listTasks` : `/api/tasks` 조회
- `getSettingsSnapshot` : server/integration 화면용 snapshot
- `IntegrationStatus` : integration row action과 status 표시

## 유지할 패턴

- API URL은 `buildApiUrl` 또는 `apiFetch`를 통해 생성한다.
- 새 서버 호출은 응답 타입을 먼저 정의하고 TanStack Query에서 사용할 수 있는 Promise API로 노출한다.
- 실제 인증이 추가되면 `apiFetch`에 header 주입 경계를 만들고 각 호출에 하드코딩하지 않는다.
- placeholder를 실제 API로 바꿀 때 loading, error, staleTime, retry 정책을 화면에서 점검한다.

## 다른 도메인과의 경계

- **agent-workspace**: agent/task 실행 화면은 backend-integration의 task API 함수를 호출한다.
- **project-workspace**: project action에서 task를 만들 때 backend-integration의 task 경계를 사용한다.
- **ui-shell**: top bar health badge는 health API를 표시하지만 fetch 구현은 backend-integration에 둔다.

## 금지 사항

- API base URL을 컴포넌트에 직접 문자열로 흩어놓지 않는다.
- settings 화면의 mock 값을 실제 연결 완료 상태로 단정하지 않는다.
- fetch 실패를 조용히 삼키고 성공 UI로 표시하지 않는다.