# KBX v13 — API Field Contract

## 목표

Frontend의 `field="orderQty"`, Server Validation의 `field="orderQty"`, OpenAPI 문서의 Field 식별자를 동일하게 유지한다.

## C# Attribute

```csharp
[property: KbxFieldKey(KbxFieldKeys.OrderQty)] decimal? OrderQty
```

`KbxFieldOpenApiSchemaFilter`는 Swashbuckle Schema에 다음 vendor extension을 추가한다.

```text
x-kbx-field-key
x-kbx-field-label
x-kbx-sensitive
x-kbx-masking
```

등록 예:

```csharp
builder.Services.AddSwaggerGen(options =>
{
    options.AddKbxFieldContract();
});
```

## 중요한 경계

OpenAPI extension은 구조/표시 계약을 제공한다.
다음은 OpenAPI Field Metadata로 생성하지 않는다.

- 업무 상태 전이
- 재고 가능 여부
- 권한 최종 판정
- 동시성 판정
- Domain invariant

## Validation Problem

Row 오류는 canonical key를 사용한다.

```json
{
  "field": "orderQty",
  "rowKey": "line-7",
  "code": "QUANTITY_POSITIVE",
  "message": "수량은 0보다 커야 합니다."
}
```

DB column이 `quantity`여도 사용자/API 오류 계약의 FieldKey는 `orderQty`를 사용한다.
