# KBX UI Boundary Governance v1

## 목적과 범위

이 문서는 화면 수가 수백 개로 증가하고 개발자·외부 UI 공급자·AI 코딩이 교체되어도 KBX UI 계약이 유지되도록 하는 FE 컴포넌트와 화면 템플릿의 기준 문서다.

- **WBS / Requirement / UI / Test:** `V13-FE-005` / `REQ-FE-COMP` / `UI-FOUND-05` / `T-FE-COMP-01`
- **Source:** 기존 vendor-neutral `Ks*` 컴포넌트, `frontend/src/shared/ui/` 경계, Screen Recipe/Component Manifest, `V13-FE-003`, `V13-FE-005`, `V13-FE-038` 기록
- **Assumption:** 현재 PrimeVue/AG Grid 직접 사용은 shared UI 소유 영역에 한정하고, 업무 모듈은 KBX 계약만 소비한다.
- **Unknown:** 모든 기존 화면의 tier·token debt·예외 registry 완전성은 별도 inventory가 필요하다.
- **Decision Required:** 실제 CI gate의 차단 수준, 예외 만료 시 error 전환 시점, Golden/Performance 승인 수치는 FE/UX/QA가 별도 승인한다.

## 핵심 결정

기존의 “Adapter를 사용할 것인가”라는 질문을 폐기하고 **KBX UI Boundary Policy**를 기준으로 판단한다. Adapter는 구현 수단 중 하나이며 목표가 아니다.

Vertical Slice는 업무 의미와 서버 계약을 소유하고, KBX는 화면 UX·상태·키보드·접근성·공급자 경계를 소유한다. PrimeVue와 AG Grid는 KBX Boundary 내부의 교체 가능한 공급자다.

```text
Vertical Slice (업무 의미)
        ↓
Screen Contract / Recipe
        ↓
KBX UI Boundary
  Native | PrimeVue | AG Grid
```

## Component Classification

모든 신규·변경 컴포넌트는 Component Manifest에 다음 tier를 기록한다.

| Tier | 이름 | 기준 | 예시 |
| --- | --- | --- | --- |
| L0 | Native Primitive | HTML semantics로 충분하고 popup/복합 keyboard 계약이 없음 | `KbxInput`, 단순 label/layout |
| L1 | Thin Technology Wrapper | KBX가 허용한 최소 props만 노출하고 공급자 API를 숨김 | `KbxButton`, `KbxDialog`, `KbxDrawer` |
| L2 | Controlled Component | focus, keyboard, overlay, ARIA, theme, density, state를 KBX가 통제 | Lookup 기반이 아닌 Date/Select/Tabs/Tooltip |
| L3 | Business Component | 반복되는 업무 문법과 상호작용 계약을 소유 | `KbxLookup`, `KbxSearchPanel`, `KbxCommandBar`, `KbxStatus` |
| L4 | Strong Facade | 외부 기능을 축소하는 것이 아니라 policy·normalizer·interaction contract로 고정 | `KbxDataGrid`, Excel import, barcode, bulk selection |

같은 이름의 컴포넌트라도 업무 규칙을 내부에 넣지 않는다. Grid interaction policy는 KBX, 주문·재고·신용한도 가능 여부는 해당 Domain이 소유한다.

## API와 경계 규칙

- `frontend/src/modules/**`는 PrimeVue/AG Grid를 직접 import하지 않는다.
- 업무 화면은 `.p-*`, `.ag-*`, 공급자 전용 `:deep()`, `!important`, raw color를 사용하지 않는다.
- KBX wrapper는 explicit props만 허용한다. 무제한 `$attrs` passthrough을 금지한다.
- `KbxDataGrid`는 `gridOptions`, `defaultColDef`, `rawGridApi` 같은 raw escape hatch를 노출하지 않는다. 의미 있는 `rowStatePolicy`, `clipboardPolicy`, `selectionPolicy`만 승인한다.
- 외부 공급자 차이는 Component가 아니라 Provider/Strategy로 분리한다. 데이터 공급 변화는 Provider, 행동 정책 변화는 Policy/Strategy, 업무 실행은 Command가 소유한다.
- Native HTML이 충분한 L0 영역에 공급자 wrapper를 추가하지 않는다.
- `Current UI state`와 `Server state`를 복제하지 않는다. TanStack Query는 server state, Pinia는 application/UI state의 소유자다.
- FE validation은 feedback이며 Truth는 Zod 계약·FastEndpoint·Application·Domain·DB에 있다.

## Template와 Screen Recipe

화면은 `ScreenId`, `ScreenType`, `templateCode`, `ScreenVersion`, `Component Manifest`를 명시한다. Template은 low-code 화면 정의가 아니라 검증 가능한 UX 골격이다.

- T01~T09 등 표준 Template은 loading/empty/partial/stale/warn/error/401/403/409/expired/readonly 상태와 권한·접근성·keyboard 계약을 소유한다.
- Screen Recipe는 사용 컴포넌트, command, 검색 필드, grid column, recovery policy, permission policy를 선언한다.
- 70%는 표준 Template/Schema, 20%는 승인된 Template Extension, 10%는 명시적 Local implementation을 목표로 한다. JSON으로 조건부 업무 로직을 만들지 않는다.
- 개발자는 업무 상태·예외·Command를 결정한다. Button 위치·grid defaults·color·keyboard·Lookup·Excel flow·상태 의미를 임의로 결정하지 않는다.
- Read 화면은 서버가 제공하는 UX 최적화 Projection을 사용하며 여러 업무 API를 FE에서 조합해 Source of Truth를 만들지 않는다.

## Token과 Design Debt

Theme은 Adapter가 아니라 KBX Semantic Token이 소유한다.

```text
Foundation → Semantic → State → Density → Component → Layout
```

Token 승격은 두 컴포넌트 이상에서 의미가 같거나 Design System 정책값일 때만 허용한다. 화면 한 곳의 layout literal을 무조건 token으로 만들지 않는다.

PX/색상 debt는 `policy`, `reusable`, `local-layout`, `external-compatibility`로 분류하고 파일·owner·reason·introducedVersion·targetVersion·decision(`normalize|keep-local|remove`)을 기록한다. debt count를 0으로 만들기 위한 magic token 생성을 금지한다.

## Exception Registry

Boundary 예외는 주석이나 TODO가 아니라 registry 데이터다. 최소 필드는 다음과 같다.

```json
{
  "id": "KBX-EX-0001",
  "screenId": "OMS-ORD-001",
  "type": "direct-ui|css|raw-api|local-template",
  "reason": "승인된 외부 장치 수명주기",
  "owner": "WMS",
  "introducedVersion": "1.0.0",
  "reviewAt": "2026-Q4",
  "removalTarget": "TBD",
  "status": "active"
}
```

만료된 `reviewAt`, owner 없는 예외, removal target 없는 장기 예외는 CI warning/error 정책에 따라 Gate를 막는다. 예외는 승인된 변경으로만 추가·갱신한다.

## AI Coding Governance

AI 생성은 Screen Recipe, Component Manifest, Field Dictionary, Test Contract를 입력으로 받는다. AI가 자유롭게 새 UI 정책을 만들도록 허용하지 않는다.

- Manifest에 없는 컴포넌트·props·template은 실패한다.
- PrimeVue/AG Grid 직접 import, raw supplier props, CSS leakage는 실패한다.
- AI는 composition, type, query hook, API binding, contract test를 작성할 수 있다.
- AI는 button placement, grid defaults, color, keyboard, Lookup pattern, Excel flow, state semantics를 결정할 수 없다.
- 생성 코드는 `SCAFFOLD_ONLY` 또는 승인된 구현으로 구분하며, scaffold를 구현 완료로 간주하지 않는다.

## Required Quality Gates

`pnpm validate:kbx`는 다음 검증을 하나의 governance pipeline으로 연결해야 한다.

1. `validate-ui-boundary` — 공급자 직접 import와 dependency 방향
2. `validate-css-boundary` — `.p-*`, `.ag-*`, `:deep`, `!important`, raw color
3. `validate-component-api` — explicit props와 raw API leakage
4. `validate-token-usage` — token 분류와 debt registry
5. `validate-kbx-exceptions` — owner/review/removal lifecycle
6. `validate-ai-generated-components` — Manifest/Recipe/props 존재성
7. `validate-theme-matrix` — Light/Dark × Compact/Comfortable + Touch
8. `validate-component-dependencies` — tier별 허용 의존성

Gate PASS는 정적 계약, reference harness, component test, real browser, Golden E2E, production smoke로 증거 등급을 구분한다. 실행하지 않은 등급은 PASS로 기록하지 않는다.

## Golden과 운영 기준

우선 Golden Component는 `KbxButton`, `KbxInput`, `KbxLookup`, `KbxDataGrid`, `KbxDialog`, `KbxStatus`다. 최소한 contract, accessibility, keyboard/focus, state, theme/density 증거를 갖는다.

`KbxDataGrid`는 별도 제품 roadmap으로 selection, clipboard, editing, validation, personalization, large data, server-side selection, Excel, keyboard, accessibility, performance를 계약화한다. AG Grid 업그레이드는 dependency bump가 아니라 Compatibility Release로 취급한다.

대량 선택은 `mode=filter`, query/filter token, `excludedIds`를 서버에 전달하며 대량 ID를 브라우저에 보관하지 않는다. Excel은 staging/job, 장시간 작업은 승인된 job/progress 계약을 사용한다.

## 적용 순서

1. Boundary/CSS/API leakage Gate를 고정한다.
2. 기존 token debt와 exception을 분류한다.
3. Component Manifest에 L0~L4 tier를 추가한다.
4. 여섯 Golden Component의 contract와 theme/density/keyboard evidence를 완성한다.
5. Template/Screen Recipe를 AI grounding과 CI validation에 연결한다.
6. 예외 lifecycle과 업그레이드 Compatibility Release 절차를 운영한다.

이번 문서는 정책 방향을 재설정하며, 기존 컴포넌트 런타임·공급자 선택·자동 활성화·실주문 경로를 변경하지 않는다.