# KBX v13 — Canonical Field Dictionary Governance

## 목적

KBX Field Dictionary는 화면을 동적으로 생성하는 Low-code 엔진이 아니다.
동일한 업무 개념이 Vue, FastEndpoints, Excel, Audit, AI에서 서로 다른 이름/타입으로 분화되는 것을 막는 **구조적 계약**이다.

핵심 경계:

```text
Field Dictionary
= Key / Label / Alias / Type / Length / Precision / Lookup / Import / Export / Sensitive

Domain
= 현재 상태에서 수정 가능한가 / 재고가 충분한가 / 어떤 전이가 허용되는가
```

## Single Source

```text
contracts/fields/kbx.fields.json
```

생성물:

```text
packages/kbx-contracts/src/generated/fieldCatalog.ts
backend/Shared/Contracts/Generated/KbxFieldCatalog.g.cs
generated/field-manifest.json
```

TypeScript와 C# 파일에는 동일 Source SHA256이 기록된다.

## Canonical Key 규칙

- camelCase
- 동일 개념은 동일 Key
- 표시 Label은 화면 문맥에 따라 변경 가능
- DB column name과 FieldKey는 동일할 필요 없음
- Read Model 전용/local interaction field는 무조건 Canonical로 승격하지 않음

현재 예:

```text
orderQty
customerId
customerCode
itemId
itemCode
warehouseId
warehouseCode
availableQty
pickedQty
shippedQty
```

## 승격 판단

`generated/field-adoption-report.json`이 반복되는 local field를 후보로 제시한다.
다음 조건을 함께 만족할 때 Canonical로 승격한다.

1. 동일한 의미인가?
2. 동일한 변화 이유를 가지는가?
3. 동일 UX/API/Excel 계약을 가져야 하는가?

v13에서는 반복 관찰된 다음을 승격했다.

- ownerName
- exceptionCount
- occurredAt
- referenceNo
- specification

## Excel

업무 Import Definition에서 Label/Alias/Type/길이/정밀도를 복제하지 않는다.

Frontend:

```ts
kbxImportField('orderQty')
```

Backend:

```csharp
ImportFieldDefinitionFactory.FromKbxField(KbxFieldKeys.OrderQty)
```

업무별 Import Definition은 **어떤 Field를 사용하는지**만 선택하고, 구조 메타데이터는 Dictionary에서 가져온다.

## Zod

Field Dictionary로부터 다음만 재사용한다.

- required text의 기본 구조
- maxLength
- numeric type
- lookup/entity selection의 기본 구조

다음은 생성하지 않는다.

```text
출고완료 주문 수정 금지
재고 8개인데 10개 출고 금지
구매확정 이후 단가수정 금지
```

이 규칙은 Server/Domain 책임이다.

## Sensitive

`sensitive=true`이면 `masking` metadata가 필수다.

현재 예:

```text
receiverName -> name
phone        -> phone
postalCode   -> address
address1     -> address
address2     -> address
```

이 metadata는 표시/AI/Export 정책의 근거가 될 수 있으나 권한 검증을 대체하지 않는다.

## 변경 규칙

- 신규 Field: Minor
- Field 제거/rename: Major
- dataType/precision/scale/lookupEntity/sensitive 변경: Major 후보
- Label/Alias 변경: Mapping Risk가 있는 Patch
- rename은 즉시 삭제보다 구 Key deprecation + migration을 우선

## 금지

- 화면별 동일 Field를 다른 내부 Key로 재정의
- Excel Definition에 Alias/Precision 복사
- AI가 존재하지 않는 FieldKey 생성
- Field Metadata에 Domain State Machine 삽입
- 모든 Local Read Model Field를 성급히 Canonical로 승격
