48 lines
2.3 KiB
Markdown
48 lines
2.3 KiB
Markdown
# 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로 표시하지 않는다.
|