# KBX v28 Template & Home Navigation Hardening

## 1. 목적

v28의 목적은 화면 수를 늘리는 것이 아니라 **Screen Type을 선택한 시점에 기본 업무 UX가 충분히 결정되는 상태**를 만드는 것이다.

기존 문제는 다음과 같았다.

- T01~T09 이름은 존재하지만 필수 Surface가 코드 계약으로 고정되지 않았다.
- T07/T08/T09 일부 Template은 실제 Reference Screen에서 요구하는 해결·결과·현장 Context Surface가 약했다.
- Home은 즐겨찾기/최근메뉴 중심으로는 동작하지만 열린 업무를 재개하는 역할이 약했다.
- Side Navigation은 모든 모듈을 연속 나열해 업무 규모가 커질수록 탐색 밀도가 나빠질 수 있었다.
- Workspace Tab 닫기 UI에 nested interactive 구조가 있었다.
- Navigation Preference가 공용 localStorage key를 사용해 사용자/테넌트 Context 분리가 불충분했다.

## 2. T01~T09 Template Manifest

`packages/kbx-ui/src/registry/templateManifest.ts`가 다음을 canonical contract로 가진다.

```text
T01 Search/List
T02 Master CRUD
T03 Header + Detail Transaction
T04 Fast Grid Entry
T05 Master / Detail Explorer
T06 Work Queue
T07 Reconcile / Verification
T08 Excel Import
T09 WMS Mobile Operation
```

각 항목은 다음을 정의한다.

```text
Screen Type
Template Component
Purpose
Required Surfaces
Optional Surfaces
Keyboard
Reference Screens
```

AI Coding Agent와 신규 화면 Scaffolder는 이 Manifest를 Grounding 자료로 사용해야 한다.

## 3. 공통 Template Context

`KbxTemplateContextBar`는 T01~T08에서 다음 정보를 동일한 위치와 표현으로 제공한다.

- 현재 적용된 업무 Context
- 조회/입력 건수
- 선택 건수
- 오류/불일치 건수
- 중요 합계
- 기준/갱신 시각
- 짧은 다음 행동 안내

업무 화면이 임의로 KPI Card를 만들거나 Summary를 중복해서 만들지 않도록 한다.

## 4. Template별 보강

### T01

```text
Page Header
Command Bar
Search
Quick Filter
Context
Bulk/Contextual Action
Grid
Summary
Detail Drawer
```

### T02

```text
Page Header
Command Bar
Validation
Record Lifecycle
Context
Master List
Detail Form
Tabs
Footer
Drawer
```

### T03

```text
Page Header
Command Bar
Validation
Record Lifecycle
Context
Header Form
Detail Grid
Workflow
Sticky Summary
Audit
Drawer
```

### T04

```text
Page Header
Command Bar
Keyboard Guide
Context
Contextual Action
Editable Grid
Validation
Summary
```

### T05

```text
Page Header
Search
Context
Master
Detail
Bottom/History
Summary
Drawer
```

### T06

```text
Page Header
Command Bar
Search
Work Summary
Exception Summary
Context
Quick/Bulk Action
Queue
Detail
Footer
```

### T07

```text
Page Header
Criteria
Summary
Mismatch Filter
Context
Resolution Action
Comparison Grid
Audit
Detail
Footer
```

### T08

```text
Page Header
Progress Steps
Context
Import Content
Result
Job Progress
Footer
```

### T09

```text
Mobile Header
Network State
Task Context
Notice
Current Instruction
Scanner/Content
Sticky Actions
```

## 5. Home Information Architecture

Home은 Dashboard가 아니라 Application Navigation Hub다.

우선순위:

```text
메뉴·화면 검색
↓
확인 필요
↓
이어서 작업
↓
즐겨찾기 / 최근 업무
↓
모듈별 업무
```

차트 중심 Home은 만들지 않는다.

## 6. Side Navigation

기존 모든 모듈 연속 노출을 다음과 같이 정리한다.

```text
Home
Menu Search
OMS | ERP | WMS | 공통
Favorites
Recent
Selected Module
  └ Section
      └ Screen
```

메뉴 깊이는 여전히 2단계를 넘기지 않는다.

## 7. Workspace

Home에서 열린 Tab을 `이어서 작업`으로 다시 진입할 수 있다.

Workspace Tabs:

- ArrowLeft / ArrowRight
- Home / End
- Delete = 닫기 요청
- Dirty Indicator
- Overflow
- Unsaved Changes 보호

Close Action은 Tab Button 내부의 가짜 `role=button`이 아니라 별도 Button으로 분리한다.

## 8. Preference Security

Navigation Preference의 보안 기본값을 변경했다.

```text
preferenceScope 없음
→ session only
→ localStorage 미사용

preferenceScope 있음
→ kbx.navigation.preference.v2:{opaque-scope}
```

`preferenceScope`는 이메일/전화번호 같은 개인정보를 사용하지 않고 Tenant/User를 식별하는 비민감 opaque key를 사용한다.

최근업무는 기본 `recentPolicy='screen'`이다.

```text
현재 route.fullPath
/orders/123/edit
```

같은 동적 Context를 그대로 영구 저장하지 않고:

```text
catalog path
/oms/orders/new
```

같은 안전한 Navigation Path를 저장한다.

정말 동적 Route 재개가 필요하고 민감하지 않은 경우에만 `recentPolicy='route'`를 명시적으로 선택한다.

## 9. Security Boundary

다음 네 영역은 동일 권한 필터를 사용한다.

```text
Home
Side Navigation
Menu Search
Favorites / Recent
```

Direct URL은 Screen Permission을 별도로 다시 검사한다.

Workspace Tab도 권한이 사라지면 Shell과 Home에서 노출하지 않는다.

Frontend 권한은 UX boundary이며 최종 보안 Enforcement는 Backend가 책임진다.
