# KBX API Contract Governance v14

## 1. 목적

API Route, Method, Permission, 성공 Status, Idempotency와 Error discriminator가 Frontend/Backend에서 독립적으로 변하는 문제를 막는다.

## 2. Source of Truth

`contracts/api/kbx.api.json`

Operation은 최소 다음을 가진다.

```text
id
method
path
permission
kind
idempotency
successStatuses
```

`source`는 Reference Foundation의 FastEndpoint 위치를 추적하기 위한 정보다.

## 3. 생성물

```text
contracts/api/kbx.api.json
        ↓
generated/api-manifest.json
        ↓
packages/kbx-contracts/src/generated/apiCatalog.ts
backend/Shared/Contracts/Generated/KbxApiCatalog.g.cs
contracts/api/openapi.kbx.json
```

Source SHA가 TS/C# Catalog에서 일치해야 한다.

## 4. Web 사용법

업무 모듈은 다음을 직접 사용하지 않는다.

```text
axios
fetch
'/api/...'
```

대신:

```ts
kbxApi.request<OrderSearchResponse>(
  'oms.orders.search',
  { query: filter },
)
```

화면이 URL과 HTTP Method를 소유하지 않게 한다.

## 5. Idempotency

```text
none
supported
required
```

`required` Operation은 안정적인 Idempotency Key 없이 Client가 호출할 수 없다.

중요: Retry할 때는 새 Key를 생성하지 않고 최초 Key를 재사용한다.

## 6. FastEndpoints parity

`validate-api-governance.mjs`는 Backend의 실제:

```text
Get/Post/Put/Patch/Delete
Route
Permissions(...)
```

을 스캔하고 Contract와 양방향 비교한다.

- Backend에만 존재 → FAIL
- Contract에만 존재 → FAIL
- Permission 불일치 → FAIL

## 7. OpenAPI

`KbxApiContractOperationFilter`는 실제 Swashbuckle 문서에 다음을 추가한다.

```text
operationId
x-kbx-permission
x-kbx-idempotency
x-kbx-kind
```

`KbxProblemOpenApiOperationFilter`는 표준 Problem response family를 노출한다.

## 8. DTO Shape 검증

Reference Foundation에는 실행 가능한 .NET Host/Solution이 없으므로 실제 Request/Response Property Schema 비교는 여기서 통과했다고 간주하지 않는다.

Host Repository에서는 실제 Swashbuckle OpenAPI를 생성하고 `validate-live-openapi.mjs`를 Mandatory Gate로 사용한다.

이는 Contract 이름만 비교하고 실제 DTO Shape drift를 놓치는 것을 방지하기 위한 2단계 검증이다.

## 9. 금지

- Screen에서 Route 문자열 작성
- Screen마다 Axios Error parsing
- LLM이 임의 API URL 생성
- POST 실패를 무조건 자동 Retry
- Idempotency가 없는 강한 Mutation 자동 Retry
- 404/403을 화면마다 서로 다른 문구로 해석
