# KBX v33 Standard Traceability

## 1. Business UX/AX Standard 대응

| 표준 요구 | v33 구현 |
|---|---|
| Predictable Layout | T01~T09 기존 Surface 계약 유지 + stateCapabilities 명시 |
| Explicit State | `idle/loading/refreshing/empty/error/permission` 구분 |
| Audit by Default | T02/T03 `dirty/conflict/audit` 책임 유지 |
| Exception Driven | Home에서 실패·부분완료 작업과 중요 알림 우선 노출 |
| Keyboard | idle 복구 Action을 `조회 F3` 문법으로 연결 |
| Permission | Screen/Command/Workflow/Bulk/WMS UI가 Permission Host 자동 소비 |
| Error Recovery | idle/error의 명시적 복구 Action, refreshing 시 기존 Context 유지 |
| Reproducibility | `data-template-state`, `data-access`, 기존 `data-kbx-surface` 유지 |

## 2. Design System 대응

| 계약 | v33 구현 |
|---|---|
| Loading/Empty/Error Contract | `idle` 추가로 최초 진입 오해 제거 |
| Permission UX | Host 기반 화면/명령/Workflow/Bulk Action 동기화 |
| Unsaved / Conflict | T02/T03 stateCapabilities에 명시 |
| Job | T08 stateCapabilities에 명시 |
| Network | T09 stateCapabilities에 명시 |
| Color-independent state | Home critical 상태도 텍스트+건수 병행 |
| Component Versioning | 변경된 공통 Component SemVer 갱신 |

## 3. Reference Screens 대응

| Reference 패턴 | 적용 |
|---|---|
| OMS 주문관리 | 조회 전 상태와 실제 0건 결과 분리 |
| ERP 품목관리 | 조회 목록 idle + 기존 Dirty/Conflict/Audit 유지 |
| ERP 재고현황 | Master/Detail 최초 조회 idle |
| WMS 작업 Queue | idle → 조회 → Exception-driven Queue |
| Home/Application Shell | 실패·중요 알림·미저장 우선 업무 Navigation |

## 4. Implementation Contract 대응

| 구현 계약 | v33 구현 |
|---|---|
| KBX가 UX를 결정 | Template state/permission 표현을 `@kbx/ui`에 집중 |
| Backend가 업무 가능성을 결정 | Server Permission/Domain Validation 최종 책임 유지 |
| Public API 제한 | `KbxPermissionHostKey`만 공통 Host로 추가 |
| Screen Definition | `stateCapabilities`는 Template Manifest에 두고 Domain Rule은 넣지 않음 |
| Permission | App Shell granted permission → Host → shared component로 전달 |
| Testability | v33 static Gate + state matrix contract test + navigation hardening test |
| Reproducibility | bounded persisted preference + sanitized v2→v3 migration |

## 5. 변경 파일 중심 추적

### Contracts
- `packages/kbx-contracts/src/ui.ts`
- `packages/kbx-contracts/src/screen.ts`
- `packages/kbx-contracts/src/catalog.ts`

### Shared UI
- `KbxDataState.vue`
- `KbxTemplateStateBoundary.vue`
- `KbxScreenFrame.vue`
- `KbxCommandBar.vue`
- `KbxWorkflowBar.vue`
- `KbxBulkActionBar.vue`
- `KbxWmsMobilePage.vue`
- `permission/host.ts`
- `registry/templateManifest.ts`
- `registry/componentManifest.ts`
- `catalog/componentCatalog.ts`

### Shell / Navigation
- `KbxHomePage.vue`
- `KbxAppFrame.vue`
- `workspaceStore.ts`
- `navigationSecurity.ts`

### Golden / Reference Adoption
- OMS Order List
- OMS Claims
- ERP Item Master
- ERP Inventory
- Common UX Metrics
- WMS Work Queue

### Validation
- `validate-template-navigation-v33.mjs`
- `kbx-template-state-matrix.contract.spec.ts`
- `kbx-navigation-hardening.contract.spec.ts`
