# KBX Foundation v35
## Screen Recipe · Secure Scaffolder · Actionable Home Navigation

## 1. 목적

v34까지 T01~T09 Template, 핵심 Business Component, 상태/권한/복구 계약은 상당 부분 정리되었다. 그러나 신규 화면 생성 시 개발자가 다시 다음을 판단해야 하는 여지가 남아 있었다.

- 어떤 Command를 기본으로 두는가
- 어떤 데이터/프로세스 정책을 반드시 지키는가
- 오류 후 어떤 복구 동작을 제공하는가
- 어떤 보안/권한 경계를 확인해야 하는가
- 어떤 Canonical E2E Scenario를 재사용해야 하는가
- Scaffolder가 생성한 저장 Command에 어떤 권한을 붙여야 하는가

v35는 이 빈틈을 `Screen Recipe` 계약으로 닫는다.

## 2. Source of Truth

신규 계약:

```text
contracts/screens/kbx.screen-recipes.json
```

생성 결과:

```text
generated/screen-recipe-manifest.json
packages/kbx-contracts/src/generated/screenRecipeCatalog.ts
```

각 Recipe는 다음을 가진다.

```text
code
screen type
template component
default commands
required data/process policies
recovery policies
security policies
canonical test scenarios
scaffold surfaces
```

Template Manifest가 "어떤 UX 골격인가"를 정의한다면 Screen Recipe는 "이 화면 유형을 운영 수준으로 완성하려면 무엇이 함께 존재해야 하는가"를 정의한다.

## 3. T01~T09 Recipe 요약

| Code | Type | 핵심 정책 | 대표 Canonical Scenario |
|---|---|---|---|
| T01 | list | Server Read Model, TanStack Query, Server Bulk Selection | OMS 주문 Bulk Ship |
| T02 | master | Normalized Write, Lookup, Concurrency, Audit | ERP 품목 Lifecycle |
| T03 | transaction | Header/Detail, Server Validation, Outbox, Conflict | OMS 주문등록 Keyboard/Conflict |
| T04 | fast-entry | Typed Paste, Stable Row Key, Idempotent Bulk Save | ERP 품목단가 Fast Entry |
| T05 | master-detail | Context Retention, Detail Projection, N+1 금지 | ERP 재고 Master/Detail |
| T06 | queue | Exception First, SLA, Partial Result, Audit | Operations Stale Event/Retry |
| T07 | reconcile | Expected/Actual/Difference, Resolution State | Reconcile Grace Period |
| T08 | import | Staging, Mapping Trace, Job, Idempotent Commit | OMS 주문 Import Partial |
| T09 | wms-mobile | Barcode, Server Success, Idempotency, Offline Policy | WMS Picking Replay/Wrong Item |

## 4. ScreenDefinition의 명시적 Template Identity

기존:

```ts
type: 'transaction'
```

v35:

```ts
type: 'transaction',
templateCode: 'T03'
```

두 값은 반드시 일치해야 한다.

검증 위치:

1. Screen Governance
2. Generated Screen Manifest
3. `KbxScreenFrame` Runtime Guard
4. `KbxWmsMobilePage` T09 Guard
5. v35 dedicated Gate

잘못된 조합을 UI가 임의로 렌더링하지 않는다.

## 5. Secure Scaffolder

기존 Scaffolder는 Master/Transaction/Fast Entry에서 저장 명령을 만들 수 있었지만 별도 쓰기 권한을 필수로 요구하지 않았다.

v35에서는 다음 화면 유형이 변경 Command를 생성하려면 반드시:

```text
--write-permission
```

을 명시해야 한다.

대상:

```text
T02 Master
T03 Transaction
T04 Fast Entry
```

권한이 없으면 Scaffolder 자체가 실패한다.

이는 존재하지 않는 권한을 AI/Generator가 임의 추론하는 것보다 안전하다.

## 6. Scaffolder의 실제 Component Composition

v35는 TODO `<div>` 위주의 얇은 골격에서 벗어나 다음 공통 컴포넌트를 직접 조합한다.

예: T01

```text
KbxListPage
 ├─ KbxSearchPanel
 ├─ KbxDataGrid
 └─ KbxSummaryBar
```

T03:

```text
KbxTransactionPage
 ├─ KbxFormSection
 ├─ KbxFormGrid
 ├─ KbxDataGrid
 └─ KbxSummaryBar
```

T08:

```text
KbxImportPage
 ├─ KbxProgressSteps
 └─ KbxExcelImport
```

T09:

```text
KbxWmsMobilePage
 ├─ KbxBarcodeCapture
 └─ KbxWmsActionButton
```

Scaffolder의 README에는 해당 Recipe의 Data/Recovery/Security Policy와 Canonical Scenario가 자동 포함된다.

## 7. Home Attention Queue

기존 Home은 확인 필요 항목을 주로 숫자로 표시했다.

```text
실패 작업 2
중요 알림 3
진행 작업 1
```

사용자는 다시 작업센터/알림센터를 열어 실제 대상을 찾아야 했다.

v35는 `buildKbxHomeAttention()`을 추가해 다음 우선순위로 실제 항목을 조합한다.

```text
1. Dirty Workspace
2. Failed / Partially-completed Operation
3. Warning / Error Notification
4. Running / Queued Operation
5. Other Unread Notification
```

각 항목은 제목, 간단한 이유, 다음 Action을 가진다.

## 8. Home Navigation 보안

Runtime API에서 전달되는 operation/notification을 Navigation Truth로 사용하지 않는다.

### Operation / Notification visibility

`sourceScreenId` 또는 `screenId`가 있으면 현재 사용자의 허용 Screen 집합에 다시 포함되는지 확인한다.

권한 없는 Screen의 Runtime 항목은 Home에서 노출하지 않는다.

### Notification route

알림의 `action.route`는 신뢰하지 않는다.

```text
notification action route
  ↓
현재 사용자에게 허용된 Screen 확인
  ↓
screenRoutePatterns allowlist
  ↓
resolveKbxSafeWorkspacePath
  ↓
일치 시 이동
```

불일치하면 경로를 차단하고 알림센터를 연다.

## 9. Release Governance

Release Impact Analyzer도 v35에서 다음을 추적한다.

- Screen `type`
- Screen `templateCode`
- Screen Recipe 추가/삭제
- Recipe `type/templateComponent`
- Security Policy 제거
- Recipe Command/Data/Recovery/Test 계약 변경

Template/Recipe의 변화가 릴리스 영향 분석에서 빠지지 않는다.

## 10. 과유불급 방지

v35는 다음을 만들지 않았다.

- Runtime JSON UI Builder
- 자체 Grid Engine
- 업무 Rule Metadata DSL
- AI 기반 자동 Permission 추론
- Screen Recipe를 Domain Rule 저장소로 사용하는 구조

Recipe는 화면 구현의 체크리스트/조립 계약이지 Domain Model의 대체물이 아니다.

## 11. 결과

v35 이후 신규 화면 생성 흐름은 다음과 같다.

```text
업무 요구사항
  ↓
T01~T09 선택
  ↓
Screen Recipe 자동 선택
  ↓
명시적 Screen/Write Permission
  ↓
KBX Component 조합 생성
  ↓
Vertical Slice 데이터/Command 연결
  ↓
Canonical Scenario + 화면별 Scenario
  ↓
Governance Gate
```

이 구조의 목적은 화면 생성 속도 자체보다 "새 화면이 시작부터 표준을 어기기 어렵게" 만드는 것이다.
