nomadcode/packages/contracts/notes/flutter-core-api-candidates.md

Flutter/Core API Contract Candidates

이 문서는 source schema가 아니라 Flutter-first 전환 중 공유 계약 후보를 모으는 compatibility note다. 실제 Go core 구현(services/core)과 향후 작성될 Flutter 클라이언트(apps/mobile) 간의 인터페이스 정합성을 보장하기 위한 임시 계약 후보이며, 단일 source-of-truth 스키마가 정의되기 전까지의 과도기적 스펙을 정의한다.

API 안정성 레벨 정의

• 안정 (Stable): 인터페이스와 데이터 포맷이 고정되어 있어 즉시 연동에 사용할 수 있음.
• 후보 (Candidate): 연동 후보 스펙으로, 실연동 과정에서 필드가 추가되거나 변경될 수 있음.

---

1. 공통 및 인프라 API

1.1 GET /healthz

• 설명: 서비스 헬스 체크.
• 인증: 없음 (Public)
• 안정성 수준: 안정 (Stable)
• Response Shape (Status 200 OK):

  {
    "status": "ok"
  }
  

1.2 GET /readyz

• 설명: 서비스 및 데이터베이스 준비 상태 체크.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Response Shape (Status 200 OK):

  {
    "status": "ready"
  }
  

  (Status 503 Service Unavailable):

  {
    "error": "database is not ready"
  }
  

---

2. 태스크 관리 API (Tasks API)

2.1 POST /api/tasks

• 설명: 새로운 태스크 생성.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Request Shape:

  {
    "title": "Task Title",
    "source": "source_identifier",
    "payload": {},
    "metadata": {},
    "external": {
      "provider": "plane",
      "id": "external-task-id",
      "url": "https://...",
      "metadata": {}
    }
  }
  

• Response Shape (Status 201 Created):

  {
    "id": "task-uuid-string",
    "status": "pending",
    "external_provider": "plane",
    "external_id": "external-task-id"
  }
  

2.2 GET /api/tasks

• 설명: 태스크 목록 조회.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Query Parameters:
  • limit (Optional, 기본값 20, 양의 정수)
• Response Shape (Status 200 OK):

  [
    {
      "id": "task-uuid-string",
      "title": "Task Title",
      "source": "source_identifier",
      "status": "pending",
      "payload": {},
      "result": {},
      "error": null,
      "created_at": "2026-05-24T12:00:00Z",
      "updated_at": "2026-05-24T12:00:00Z",
      "external_provider": "plane",
      "external_id": "external-task-id",
      "external_url": "https://...",
      "external_metadata": {},
      "metadata": {}
    }
  ]
  

2.3 GET /api/tasks/{id}

• 설명: 단일 태스크 세부 정보 조회.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Response Shape (Status 200 OK):

  {
    "id": "task-uuid-string",
    "title": "Task Title",
    "source": "source_identifier",
    "status": "pending",
    "payload": {},
    "result": {},
    "error": null,
    "created_at": "2026-05-24T12:00:00Z",
    "updated_at": "2026-05-24T12:00:00Z",
    "external_provider": "plane",
    "external_id": "external-task-id",
    "external_url": "https://...",
    "external_metadata": {},
    "metadata": {}
  }
  

2.4 POST /api/tasks/{id}/enqueue

• 설명: 태스크를 큐에 진입시켜 실행 대기 상태로 변경.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Response Shape (Status 200 OK):

  {
    "id": "task-uuid-string",
    "status": "queued"
  }
  

---

3. 외부 연동 API (Integrations API)

3.1 POST /api/integrations/plane/tasks

• 설명: Plane 워크아이템 정보를 기반으로 새로운 태스크 생성.
• 인증: Basic Auth
• 안정성 수준: 안정 (Stable)
• Request Shape:

  {
    "workspace_slug": "my-workspace",
    "project_id": "project-uuid-string",
    "work_item_id": "work-item-id-string",
    "state_id": "state-uuid-string",
    "external_url": "https://...",
    "comment": "Optional comment"
  }
  

• Response Shape (Status 201 Created):

  {
    "id": "task-uuid-string",
    "status": "pending",
    "external_provider": "plane",
    "external_id": "work-item-id-string"
  }
  

---

4. Workspace / Project Metadata 계약 후보

Important

Workspace/Project Metadata 상태: 현재 Go core 백엔드에 이와 관련한 별도의 Source-of-Truth 저장소나 전용 테이블 구조가 존재하지 않으며, API 명세 또한 완전히 확정되지 않았습니다. 아래는 Flutter 앱과 코어 간 향후 연동을 대비한 계약 후보 필드 목록입니다.

4.1 Workspace Metadata 후보 스펙

• 설명: 에이전트 작업 공간(Workspace)에 대한 설정 및 상태 메타데이터.
• 후보 필드:
  • workspace_id: 작업 공간 고유 식별자 (UUID)
  • workspace_slug: 작업 공간의 URL 친화적 식별자 (예: nomadcode-dev)
  • name: 작업 공간 표시 이름 (예: NomadCode Dev Workspace)
  • owner_id: 소유자 고유 식별자
  • created_at: 생성 시각 (ISO 8601)
  • updated_at: 최종 변경 시각 (ISO 8601)
  • status: 현재 상태 (예: active, archived, suspended)
  • settings: 작업 공간에 특화된 동적 설정 JSON 오브젝트 (예: 자동 스케줄링 옵션, 알림 채널 정보 등)

4.2 Project Metadata 후보 스펙

• 설명: 작업 공간 내 세부 프로젝트(Project) 정보.
• 후보 필드:
  • project_id: 프로젝트 고유 식별자 (UUID)
  • workspace_id: 해당 프로젝트가 속한 Workspace 식별자
  • name: 프로젝트 표시 이름 (예: Flutter client consolidation)
  • description: 프로젝트 세부 설명
  • provider: 연동 플랫폼 식별자 (예: plane, github)
  • external_project_id: 연동 플랫폼 측 프로젝트 ID
  • status: 프로젝트 상태 (예: active, paused)