# SDD: Control Plane Resource API

## 위치

- Milestone: [Milestone 문서](../../../phase/platform-foundation/milestones/control-plane-resource-api.md)
- Phase: [PHASE.md](../../../phase/platform-foundation/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
  - 없음

## 문제 / 비목표

- 문제: domain schema와 service scaffold는 있으나 운영 UI·CLI·worker가 공유할 project-scoped resource lifecycle, 오류, 페이지네이션과 동시성 계약이 없다.
- 비목표:
  - 외부 identity provider 연동과 세분화된 RBAC
  - online retrieve·answer data plane
  - UI 구현

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/platform-foundation/milestones/control-plane-resource-api.md) | 관리 resource 범위와 project boundary |
| Code | [Control Plane 앱](../../../../apps/control-plane/) | HTTP 진입점과 composition root |
| Schema | [초기 제어 상태 스키마](../../../../db/migrations/00001_initial.sql) | project와 초기 resource identity |
| User Decision | 없음 | project-scoped 관리 경계를 초기 표준선으로 사용한다 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| active | 비활성화 가능한 구성 resource 생성과 validation이 성공함 | disabled | resource revision |
| disabled | 명시적 비활성화가 revision 조건과 함께 성공함 | active | mutation audit |

이 공통 상태는 source·knowledge base 같은 구성 resource에만 적용한다. dataset·workflow·evaluation·release의 세부 상태는 각 수명주기 SDD가 소유하며 공통 API가 임의로 합치지 않는다.

## Interface Contract

- 계약 원문: `api/openapi/`에 versioned management API를 게시하고 구현 시 source of truth로 사용한다.
- 입력:
  - `project_id`: 모든 project-owned resource route와 query의 필수 scope. project 자체는 격리 root identity로 다룬다.
  - `Idempotency-Key`: 생성과 명령형 mutation의 replay identity
  - `If-Match` 또는 동등한 `revision`: optimistic concurrency 조건
  - cursor, filter와 bounded page size
- 출력:
  - stable resource identity, revision과 lifecycle state
  - opaque next cursor
  - stable error code, message, correlation identity와 retryability
- 금지:
  - project-owned resource에 project scope 없는 목록·변경 요청을 허용하지 않는다.
  - offset pagination을 공개 안정 계약으로 사용하지 않는다.
  - stale revision을 last-write-wins로 덮어쓰지 않는다.
  - 같은 idempotency key의 다른 payload를 성공 replay로 처리하지 않는다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `project-boundary` | 서로 다른 두 project와 resource | 교차 project read·write | 존재 여부를 누출하지 않고 거부한다 |
| S02 | `resource-lifecycle` | 지원 resource 종류 | create·get·list·update·disable | 공통 identity·revision 의미로 동작한다 |
| S03 | `api-consistency` | 여러 page와 stale revision | list·update | cursor는 안정적으로 이어지고 stale write는 conflict가 된다 |
| S04 | `mutation-idempotency` | 동일 key의 동일·상이 payload | mutation replay | 동일 payload는 같은 결과, 상이 payload는 conflict가 된다 |
| S05 | `management-contract` | 관리 API schema | 계약 게시 | 소비자가 versioned OpenAPI로 요청·오류를 생성·검증한다 |
| S06 | `lifecycle-tests` | resource와 project matrix | contract suite 실행 | 상태 전이와 cross-project negative case가 통과한다 |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | cross-project negative integration test | `agent-task/m-control-plane-resource-api/...` | `project-boundary` deny evidence |
| S02 | resource lifecycle contract matrix | `agent-task/m-control-plane-resource-api/...` | `resource-lifecycle` API evidence |
| S03 | cursor·stale revision test | `agent-task/m-control-plane-resource-api/...` | `api-consistency` pagination·conflict evidence |
| S04 | idempotency replay·mismatch test | `agent-task/m-control-plane-resource-api/...` | `mutation-idempotency` replay evidence |
| S05 | OpenAPI validation·compatibility check | `agent-task/m-control-plane-resource-api/...` | `management-contract` artifact |
| S06 | lifecycle and isolation suite | `agent-task/m-control-plane-resource-api/...` | `lifecycle-tests` PASS evidence |

## Cross-repo Dependencies

- 없음

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] project boundary와 도메인별 lifecycle 책임을 분리했다.
- [x] 사용자 리뷰가 필요한 항목이 없다.

## 사용자 리뷰 이력

- 없음

## 작업 컨텍스트

- 표준선: project-scoped identity, cursor pagination, optimistic concurrency, stable error, idempotent mutation
- 후속 SDD: [내구성 있는 Workflow Runtime](../../workflow-automation/durable-workflow-runtime/SDD.md), [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md)