kjh2064
31b36ba226
Consolidates KBX UI Boundary Governance framework with component manifest, screen recipe registry, AI component gate, and exception lifecycle validation. Evidence (evidence/V13-FE-005/*.log, 55+ files): - Full frontend regression: 70 files / 180 tests PASS - UI boundary gate: 37 files / 0 failures / 6 raw-color warnings (DEBT tracked) - Component manifest validation: 0 failures - Screen recipe governance: 0 failures - AI component gate: 17 feature files / 23 known exports / 0 failures - Accessibility E2E: 22 passed - Production build: PASS (>500 kB chunk warning V13-FE-038 DECISION_REQUIRED) - TypeCheck: PASS - KBX validators: All 5 PASS (failures=0) Added: 19 files (6 validator scripts, 6 test specs, 4 slice notes, 3 registries) Modified: 9 files (CI workflow, WBS tracker, E2E specs, FE setup, Layout, TS configs) Outstanding per V13-FE-005 note: AI prop-level validation, exception lifecycle, browser/visual/AT/performance evidence. No completion overclaim. AGENTS.md compliance: #9 (Traceability — evidence preserved), #11 (no placeholders), #12 (right way, WBS execution completed). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
138 lines
8.8 KiB
Markdown
138 lines
8.8 KiB
Markdown
# 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 절차를 운영한다.
|
||
|
||
이번 문서는 정책 방향을 재설정하며, 기존 컴포넌트 런타임·공급자 선택·자동 활성화·실주문 경로를 변경하지 않는다.
|