nomadcode/agent-ops/rules/domain/web/backend-integration/rules.md

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로 표시하지 않는다.