KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/screen-recipe-secure-home-navigation-v35.md

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

신규 계약:

contracts/screens/kbx.screen-recipes.json

생성 결과:

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

각 Recipe는 다음을 가진다.

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

기존:

type: 'transaction'

v35:

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를 생성하려면 반드시:

--write-permission

을 명시해야 한다.

대상:

T02 Master
T03 Transaction
T04 Fast Entry

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

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

6. Scaffolder의 실제 Component Composition

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

예: T01

KbxListPage
 ├─ KbxSearchPanel
 ├─ KbxDataGrid
 └─ KbxSummaryBar

T03:

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

T08:

KbxImportPage
 ├─ KbxProgressSteps
 └─ KbxExcelImport

T09:

KbxWmsMobilePage
 ├─ KbxBarcodeCapture
 └─ KbxWmsActionButton

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

7. Home Attention Queue

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

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

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

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

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는 신뢰하지 않는다.

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 이후 신규 화면 생성 흐름은 다음과 같다.

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

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