# KBX Foundation v34
## Core Component Recovery · Permission · Home Navigation Hardening

## 1. 목적

v34는 T01~T09 Screen Template 자체의 상태 계약을 확장한 v33 다음 단계다. 목표는 Template Manifest에 선언된 핵심 Business Component가 실제 운영 수준의 오류·복구·권한·접근성 계약을 갖도록 하고, Home Workbench의 탐색 상태가 권한/카탈로그 변경에도 일관되도록 만드는 것이다.

핵심 원칙은 다음과 같다.

- Template은 Core Component 이름만 나열하지 않고 실제 Manifest와 독립 Catalog Scenario까지 폐쇄적으로 연결한다.
- Component 내부 비동기/오류 상태를 화면 Slice가 매번 재구현하지 않는다.
- Frontend Permission은 UX 표현과 defense-in-depth를 담당하고 Backend Permission/Domain Validation을 대체하지 않는다.
- Import/AI/WMS 입력은 Client 편의 검증 뒤에도 Server validation, idempotency, staging, domain rule을 최종 기준으로 둔다.
- Home은 열린 업무/고정 업무를 중복 집계하지 않고, Permission이나 Catalog 변경으로 사라진 Module filter를 안전하게 복구한다.

---

## 2. T01~T09 Core Component Closure

`kbxTemplateManifest.coreComponents`에 포함되는 모든 Component는 다음 세 조건을 만족해야 한다.

```text
Template Manifest
      ↓
Component Manifest
      ↓
Component Catalog Scenario
```

v34 Governance Gate는 세 계층 중 하나라도 누락되면 실패한다.

v33 기준으로 독립 Catalog Scenario가 없던 다음 Core Component를 추가했다.

- KbxLookupDialog
- KbxValidationSummary
- KbxExceptionSummary
- KbxExceptionDetailDrawer
- KbxRecordLifecycle
- KbxBarcodeCapture
- KbxNetworkIndicator
- KbxWmsActionButton

AI/Utility의 운영 상태 재현성을 위해 다음 Scenario도 보강했다.

- KbxAiAssistant
- KbxUtilityRail

이로써 "Template 계약에는 존재하지만 독립 상태를 재현할 수 없는 Component"를 허용하지 않는다.

---

## 3. Lookup 고도화

### 3.1 비동기 응답 역전 방지

Lookup 입력은 사용자가 빠르게 값을 바꾸는 경우 먼저 보낸 요청이 나중에 도착할 수 있다. v34는 request sequence를 사용하여 오래된 응답이 최신 입력을 덮어쓰지 못하게 한다.

```text
A 검색 요청
B 검색 요청
B 응답 반영
A 응답 도착 → 폐기
```

### 3.2 상태 표준화

Lookup Dialog가 다음 상태를 직접 책임진다.

- Provider unavailable
- Loading
- Error
- Empty
- Ready
- Paging
- Selected row

오류 후 `다시 조회`가 가능하며, 결과가 없을 때 빈 Grid처럼 보이지 않고 명시적인 Empty 상태를 제공한다.

### 3.3 Keyboard / Accessibility

- Arrow Up/Down: 결과 이동
- Enter: 선택
- Esc: 닫기
- 선택 후 원래 Input으로 Focus restore
- `aria-selected`
- 선택 Row 자동 Scroll

### 3.4 Provider Metadata Column

Lookup별 결과 컬럼을 페이지가 직접 Table로 만들지 않도록 `KbxLookupColumnDefinition`을 추가했다.

지원 source:

- code
- displayName
- secondaryText
- status
- metadata.*

### 3.5 Primitive 경계

`KbxLookupDialog`는 PrimeVue Dialog/Button을 직접 import하지 않고 `KbxDialog`, `KbxButton`을 조합한다. Vertical Slice뿐 아니라 Business Component 내부에서도 가능한 한 KBX Primitive 계층을 유지한다.

---

## 4. Excel Import 고도화

### 4.1 Session Isolation

Import Session이 변경되면 이전 Session의 local mapping을 초기화한다. 서로 다른 파일/업무의 Mapping이 조용히 섞이는 것을 차단한다.

### 4.2 Client Preflight

서버 검증 이전에 사용자 피드백을 빠르게 제공하기 위해 다음을 확인한다.

- `.xlsx` 확장자
- maxFileSize
- Required field mapping 누락
- 동일 Target field 중복 Mapping

Client preflight는 편의 검증이며 Server staging/business validation을 대체하지 않는다.

### 4.3 Mapping 1:1 계약

동일 System Field에 여러 Excel Column이 연결된 경우 Commit 전에 오류로 표시한다. Required import field가 연결되지 않은 경우도 Commit을 차단한다.

### 4.4 Commit 확인

대량 반영은 `KbxConfirm` high-risk confirmation을 거친다. 반영 전 신규/수정/정상/오류 범위를 사용자가 확인할 수 있는 기존 Import 정책을 유지한다.

### 4.5 Terminal Result

다음을 구분한다.

- Completed
- PartiallyCompleted
- Failed
- Cancelled

부분 완료는 성공 건과 제외된 오류 건을 분리해서 설명하고 오류 데이터 재처리 경로를 제공한다. 실패 시 `KbxImportFailure`의 code/title/detail을 표현할 수 있다.

---

## 5. Exception Action Permission

`KbxExceptionDetailDrawer`를 `KbxDrawer + KbxButton` 조합으로 정리하고 Permission Host를 자동 소비한다.

Action은 다음 정책을 지원한다.

```text
permissionMode = hide
permissionMode = disable
```

Permission Host가 없는데 permission이 명시된 Action은 안전한 방향으로 실행을 허용하지 않는다.

화면 Shell의 접근권한과 Exception Drawer 내부 Action 권한이 분리되어 누락되는 문제를 줄인다.

---

## 6. AI Guard 고도화

### 6.1 Proposal Permission

`KbxProposalPanel`은 proposal의 `requiredPermission`을 Permission Host로 확인한다.

### 6.2 Proposal Validation State

AI Proposal은 다음 상태를 가질 수 있다.

```text
pending
validated
invalid
stale
```

validation 정보가 존재하는 Proposal은 `validated` 상태에서만 Apply가 가능하다. AI confidence를 실행 권한이나 Domain validation의 대체값으로 사용하지 않는다.

### 6.3 Answer Action Capability / Permission

AI 답변에 포함된 Action은 각각:

- requiredCapability
- requiredPermission

을 확인한다.

AI가 설명할 수 있다는 이유로 사용자가 실행할 수 없는 Action을 노출/실행하지 않는다.

### 6.4 User-facing Context 최소화

AI Panel은 내부 `screenId`를 기본 사용자 문구로 직접 노출하지 않고 `currentScreenLabel`을 사용한다. ScreenId는 Grounding/Telemetry용 내부 식별자로 유지한다.

### 6.5 Error Recovery

AI 질문 실패 시 일반 오류 상태를 표시하고 마지막 질문을 다시 시도할 수 있다. 네트워크 오류를 Answer처럼 취급하지 않는다.

---

## 7. WMS Barcode Capture 고도화

### 7.1 Bounded Buffer

Scanner keyboard wedge가 비정상적으로 긴 데이터를 보내더라도 buffer를 무제한 확장하지 않는다.

기본 maxLength:

```text
256
```

### 7.2 Duplicate Debounce

동일 Scanner가 극히 짧은 간격으로 같은 Barcode를 중복 전송하는 장비 bounce를 Client에서 억제한다.

기본 debounce:

```text
180ms
```

하지만 일정 시간이 지난 동일 Barcode는 정상 재스캔이므로 허용한다.

이 처리는 UX 보조이며 Server Idempotency가 최종 중복 방어선이다.

### 7.3 입력 Source

- keyboard-wedge
- manual
- camera (`submitCamera` entry)

를 동일 Barcode Event 계약으로 연결한다.

### 7.4 Context Reset

- Esc: 현재 buffer 초기화
- visibility change: 숨겨진 화면의 미완성 scanner buffer 제거
- exposed `reset()`

백그라운드/화면전환 후 오래된 Scanner 조각이 다음 Barcode와 합쳐지는 위험을 낮춘다.

---

## 8. Home Workbench / Navigation

### 8.1 Open / Pinned 중복 제거

Home Source Summary에서 `open`은 `!pinned` Workspace만 집계한다.

```text
Pinned 3
Open 5
```

가 실제로 서로 다른 집합이 되며, 고정 탭을 열린 업무에도 다시 집계하지 않는다.

### 8.2 Permission / Catalog Change Recovery

현재 선택된 Module이 권한 변경이나 화면 Catalog 변경으로 더 이상 존재하지 않으면 Module filter를 자동으로 `ALL`로 복구한다.

숨겨진 Module filter 때문에 Home이 빈 화면처럼 남는 상태를 방지한다.

### 8.3 검색 결과 접근성

현재 Module 조건에서 접근 가능한 화면 수를 `aria-live`로 제공한다.

Home은 기존 v31~v33의 다음 Navigation hardening을 유지한다.

- multi-instance workspace key
- pinned tab capacity protection
- tab roving focus
- Ctrl+K menu search
- focus restore
- skip-to-content
- recent route sanitization
- encoded traversal/backslash/control rejection
- query/hash 제거 후 recent persistence
- preference size/field limit

---

## 9. Design Debt

v33 baseline:

```text
268
```

v34 구현 후:

```text
131
```

Lookup/Import/AI/WMS Component의 hard-coded spacing/width를 semantic/component token으로 이동한 결과다.

v34 release에서는 131을 새 ratchet baseline으로 설정하여 이후 132 이상으로 다시 증가하면 Governance Gate가 실패하도록 한다.

---

## 10. 변경하지 않은 경계

v34는 다음을 UI Framework 내부로 끌어오지 않는다.

- Domain business rule
- Backend permission enforcement
- Import staging/business validation
- AI entity/domain validation
- WMS server idempotency
- Transaction concurrency source of truth

즉 KBX는 사용방법과 오류복구 UX를 표준화하고 Domain/Backend가 가능한 업무와 최종 정합성을 결정한다.

---

## 11. 다음 검증 단계

Repository Governance Gate와 별도로 실환경에서 다음을 수행해야 한다.

1. Vitest Component Contract
   - Lookup race/error/paging/focus restore
   - Import mapping guard/session reset/partial result
   - Proposal permission/validation
   - Barcode duplicate/buffer/camera

2. Playwright
   - T01 lookup/search/error recovery
   - T03 transaction dirty/conflict/save
   - T08 import mapping → validation → commit → partial result
   - T09 scan duplicate/network recovery
   - Home permission change/module filter recovery

3. .NET/PostgreSQL Integration
   - Permission enforcement
   - Import staging
   - Idempotency
   - Outbox/Audit
   - AI Proposal domain revalidation
