KArtSell.Aegis/docs/Design/kbx-foundation-v36/docs/template-component-home-navigation-actionability-v32.md

KBX v32 Template · Component · Home Navigation Actionability

1. 목적

v31까지는 Template Type 불일치, 중복 Search 렌더링, Workspace 다중업무 손실, Navigation 저장값 신뢰 문제를 줄였다. v32는 그 다음 단계로, 문서에 정의된 T01~T09가 실제 화면 개발에서 다시 조립되지 않도록 반복 Surface를 Template 계약으로 흡수한다.

핵심 경계는 유지한다.

• KBX: 화면 사용방법, 위치, 상태표현, Keyboard, Summary, Exception UX
• Domain/Vertical Slice: 업무 가능 여부, 상태전이, 검증, 권한, 데이터 Truth

2. T01~T09 Surface 관측성

각 Template의 주요 영역에 data-kbx-surface를 부여했다. 목적은 Runtime JSON UI를 만들기 위함이 아니라 다음을 안정화하기 위함이다.

• Playwright가 화면 구조를 의미 기반으로 찾음
• Screenshot/운영 재현 시 DOM class 변경에 덜 결합
• Template별 필수 영역 누락을 자동 검증하기 쉬움
• AI Coding Agent가 임의 Layout 대신 공개 Surface를 사용

공통 Surface는 page-header, command-bar이며, 각 유형별로 search, header-form, detail-grid, editable-grid, work-summary, exception-summary, comparison-grid, progress-steps, network-state, sticky-actions 등을 사용한다.

3. First-class Composition Contract

T01 Search/List

KbxListPage가 quickFilters, summaryItems를 직접 받을 수 있다. 업무 화면은 필요하면 Slot으로 완전히 대체할 수 있다.

T03 Transaction

summaryItems를 받아 KbxSummaryBar를 기본 렌더링한다. 주문등록·구매등록·재고이동처럼 동일한 합계 영역을 각 화면에서 다시 작성하지 않는다.

T04 Fast Entry

errors, summaryItems를 받아 KbxValidationSummary, KbxSummaryBar를 기본 조합한다. Grid 편집 로직과 Validation 데이터는 Vertical Slice에 남긴다.

T05 Master/Detail

summaryItems를 표준 하단 Summary로 직접 제공한다. Master 선택 Context와 Detail/History 구조는 그대로 유지한다.

T06 Work Queue

summaryItems, exceptionCounters, activeExceptionKey를 제공한다. exceptionFilter Event만 Vertical Slice가 받아 실제 조회조건을 변경한다. 정상 데이터보다 사용자가 판단해야 할 예외를 먼저 노출한다는 KBX Exception Driven 원칙을 Template 수준으로 끌어올렸다.

4. Home 업무 재개 우선순위

Home Workbench 우선순위는 다음과 같다.

미저장
→ 고정
→ 열림
→ 즐겨찾기
→ 최근
→ 권장

Dirty는 데이터 유실 위험 때문에 최우선이다. Pinned는 사용자가 명시적으로 유지한 업무이므로 일반 Open보다 먼저 노출한다. 같은 Screen의 서로 다른 record route는 tab.key 단위로 계속 보존한다.

5. Home 즐겨찾기와 열린 업무 표시

모듈별 업무 목록에서 별도 Side Navigation으로 이동하지 않고도 즐겨찾기를 추가/해제할 수 있다. 화면별 열린 Workspace 수를 같이 표시하여 “이 화면을 이미 열어두었는가”를 빠르게 판단할 수 있다.

즐겨찾기는 Screen 단위이며 열린 Workspace는 Route Instance 단위라는 기존 구분은 유지한다.

6. Keyboard / Accessibility

Home, Global Header, Side Navigation의 Menu Search Trigger에 aria-keyshortcuts="Control+K"를 추가했다. Side Navigation과 Home의 Favorite Toggle은 aria-pressed로 현재 상태를 명시한다.

v31의 Menu Search Focus Restore, Workspace roving focus, Skip Link 정책은 그대로 유지한다.

7. Token normalization

KbxValidationSummary, KbxExceptionSummary의 직접 색상/spacing 값을 Design Token으로 변경했다. 업무 의미는 Semantic Token을 통해 표현하고 개별 Component에서 RGB나 독립 숫자를 확산시키지 않는다.

8. 실제 적용 화면

• OMS-ORD-002: T03 Summary Contract
• ERP-PUR-001: T03 Summary Contract
• ERP-INV-MOVE-001: T03 Summary Contract
• ERP-PRICE-001: T04 Validation/Summary Contract
• ERP-INV-001: T05 Summary Contract
• WMS-WORK-001: T06 Work Summary/Exception Contract

Reference Screen을 실제 소비 화면에 적용해 Template API가 문서상 계약으로만 남지 않도록 했다.

9. 과유불급 방지

v32에서도 다음은 만들지 않았다.

• Runtime JSON UI Builder
• 자체 Grid/DatePicker 엔진
• Domain Rule을 Template Metadata로 이동
• Home을 차트 Dashboard로 변경
• AI가 화면 Layout을 임의 생성하는 체계

Template은 반복 UX를 흡수하되 업무 의미와 상태 전이는 Vertical Slice에 남긴다.