KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/kbx-v33-standard-traceability.md

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