KArtSell.Aegis/docs/CURRENT/KBX_UI_BOUNDARY_GOVERNANCE.md

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 내부의 교체 가능한 공급자다.

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이 소유한다.

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 데이터다. 최소 필드는 다음과 같다.

{
  "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 절차를 운영한다.

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