# 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 우선순위는 다음과 같다.

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

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에 남긴다.
