# KBX Foundation v52 — FE Operational Navigation & Screen Anatomy Hardening

## 1. 작업 목적

v52의 목표는 새로운 UI Framework를 만드는 것이 아니다. v51까지 축적된 계약·거버넌스·토큰·보안 경계를 유지하면서, 실제 사용자가 보는 Vue/HTML/JavaScript 계층의 업무 완성도를 높이는 것이다.

판단 기준은 다음 세 문장으로 고정한다.

1. 사용자는 화면 진입 후 3초 안에 현재 상태, 주요 행동, 다음 이동을 판단할 수 있어야 한다.
2. T01~T09는 이름만 다른 Wrapper가 아니라 업무 유형에 맞는 정보 계층을 가져야 한다.
3. 홈은 카드 Dashboard가 아니라 업무 런처, 이어하기, 예외 진입, 전체 업무 탐색기여야 한다.

근거 문서: `KBX Business UX-AX Standard v1.0`, `KBX Design System v1.0`, `KBX Reference Screens v1.0`, `KBX Implementation Contract v1.0`.

## 2. 냉정한 진단

### 2.1 강한 부분

- Screen Definition, Permission, Problem Contract, Concurrency, Audit, Outbox/Job 경계가 이미 강하다.
- `@kbx/ui`가 PrimeVue/AG Grid를 감싸는 방향이 일관되어 있다.
- T01~T09 Recipe/Manifest/Validation이 자동 검증된다.
- 순수 `fe-reference`는 Lookup, Keyboard, Dirty, Import, WMS Scan 등 상당히 많은 실제 FE 동작을 이미 재현한다.

### 2.2 약한 부분

#### A. 계약 완성도가 사용자 화면 완성도로 착각될 위험

공통 Template에 slot과 props가 존재하는 것과 사용자가 화면을 즉시 이해하는 것은 다르다. v51의 일부 T02/T03/T06/T07은 구조는 맞았으나 `목록/상세`, `Header/Detail`, `Queue`, `Comparison`의 시각적 시작점과 건수·설명이 충분히 표준화되지 않았다.

#### B. Home은 기능은 많지만 탐색 결정이 한 단계 더 필요했다

기존 Home에는 검색, pulse, 예외, 바로 시작, 업무 목록이 존재했지만 사용자가 OMS/ERP/WMS 중 어디로 들어갈지 빠르게 좁히는 compact module launcher가 없었다. Side Navigation의 module switcher와 Home의 work explorer가 하나의 탐색 문법으로 연결되어야 했다.

#### C. 일부 Vertical Slice Page는 여전히 너무 얇다

현재 파일 크기만 보더라도 다음 화면은 Template 조립은 되어 있으나 실제 업무 FE orchestration의 깊이는 부족하다.

- `PurchasePage.vue`: 19 lines
- `InventoryMovePage.vue`: 9 lines
- `WmsWorkPage.vue`: 22 lines

파일 길이가 품질의 척도는 아니지만, 현 시점에서는 이 얇음이 “표준 컴포넌트 재사용”보다 “업무 상호작용 미구현”에 가까운 구간도 있다. 다음 단계에서는 BE 계약을 추가하기보다 실제 입력, Lookup, 상태 전이, 오류 회복, Grid Editing, Keyboard Flow를 먼저 채워야 한다.

#### D. 자동 검증은 강하지만 실제 Browser Visual Gate는 별도 보강이 필요

v52 정적/계약 검증은 모두 통과했으나 현재 작업 환경에 `pnpm`과 `node_modules`가 없어 Vite bundle/Playwright를 실행하지 않았다. Chromium direct screenshot도 container DBus/headless 제약으로 완료되지 않았다. 따라서 v52는 “코드/계약 회귀 PASS”이지 “실 브라우저 E2E 전체 PASS”라고 과장하지 않는다.

## 3. v52 적용 내용

### 3.1 Home — Operational Module Rail

`KbxHomePage.vue`에 모듈별 업무 런처를 추가했다.

표시 정보:

- 전체 화면 수
- OMS / ERP / WMS / COMMON
- 모듈별 화면 수
- 즐겨찾기 수
- 현재 열린 Workspace Tab 수

모듈 선택 시 동일 페이지의 `kbx-home-explorer`로 이동한다. 단순 CSS Filter가 아니라 “탐색 행동 → 업무 목록” 흐름으로 연결한다.

Home의 최종 정보 순서:

```text
업무검색
→ Operational Pulse
→ Module Rail
→ 확인 필요
→ 바로 시작
→ 모듈별 업무 탐색기
```

카드형 KPI Dashboard는 추가하지 않았다.

### 3.2 T02 Master CRUD Anatomy

`KbxMasterPage`에 다음 표준 계약을 추가했다.

- `listTitle`
- `listCount`
- `detailTitle`
- `detailDescription`
- `list-header` / `detail-header` extension slot
- list/detail body 분리

`KbxSectionHeader`를 공통 사용한다.

ERP 품목관리에는 다음을 적용했다.

```text
품목 목록 · N건
품목 상세 · ABC001 · 품목명
기본정보 · 설명
물류정보 · 설명
```

즉, 단순 2-pane이 아니라 “어느 pane이 무엇이며 현재 무엇을 보고 있는가”가 명확해졌다.

### 3.3 T03 Header + Detail Transaction Anatomy

`KbxTransactionPage`에 다음을 추가했다.

- `headerTitle`
- `headerDescription`
- `detailTitle`
- `detailDescription`
- `detailCount`
- Header/Detail body 분리

OMS 주문등록에는:

```text
주문 정보
  주문 조건과 배송 기준 확인

주문 상품 · N건
  Enter 연속입력 / F2 Lookup / Excel 붙여넣기 문법
```

을 적용했다.

ERP 구매등록과 재고이동에도 동일 계약을 적용했다. 거래 화면마다 임의의 섹션 문법을 만들지 않는다.

### 3.4 T06 Queue Anatomy

`KbxQueuePage`에:

- `queueTitle`
- `queueDescription`
- `queueCount`

를 추가했다.

WMS Work 화면은 “현재 작업 Queue”라는 업무 목적과 표시 건수를 명시한다. Queue는 그래프가 아니라 지금 처리할 업무를 보여준다는 기존 KBX 원칙을 강화한다.

### 3.5 T07 Reconcile Anatomy

`KbxReconcilePage`에:

- `comparisonTitle`
- `comparisonDescription`
- `comparisonCount`

를 추가했다.

COMMON Reconcile에는 “OMS ↔ WMS 대사”와 Expected / Actual / Difference / Reason / Resolution 순서를 명시했다. 대사 화면의 목적을 일반 Grid와 구별한다.

### 3.6 순수 HTML/JavaScript Reference parity

`apps/web/fe-reference`에도 동일 Home module rail을 구현했다.

- `data-home-module="ALL|OMS|ERP|WMS|COMMON"`
- `aria-pressed`
- 모듈별 screen/favorite/open count
- 선택 후 work explorer scroll
- 전체 업무 복귀
- forced-colors active cue

Vue Shell만 개선하고 실제 정적 HTML/JS Reference가 뒤처지는 이중화를 피했다.

## 4. Theme 적용 원칙

v51에서 도입한 Module Identity Theme을 유지한다.

- OMS: Blue
- ERP: Violet
- WMS: Teal
- COMMON: Neutral

중요 규칙:

- Module color는 navigation/chrome/context identification에만 사용한다.
- 성공/경고/오류/취소 등 Business State color를 대체하지 않는다.
- Dark와 forced-colors에서도 active cue를 유지한다.
- 화면별 임의 RGB보다 token source를 우선한다.

## 5. FE 보안 보강

정적 Reference CSP를 다음처럼 더 좁혔다.

- `connect-src 'self'`
- `font-src 'self'`
- `frame-src 'none'`
- `worker-src 'none'`
- 기존 `object-src 'none'`, `base-uri 'none'`, `frame-ancestors 'none'`, `form-action 'self'` 유지

이 변경의 목적은 FE가 권한의 Source of Truth가 되는 것이 아니다. 브라우저 공격면은 브라우저 정책으로 줄이고, Permission/Business Rule/Concurrency/Entity Resolve는 Backend/Domain이 계속 최종 책임진다.

## 6. 검증 결과

`node scripts/validate-kbx.mjs` 전체 PASS.

주요 결과:

- Design tokens: 161
- Screen definitions: 20
- Component definitions: 85
- Core component APIs: 34
- Navigation entries: 16
- T01~T09 Recipe verification: 9/9
- TypeScript/Vue script syntax: 308 units PASS
- FE v41~v51 regression: PASS
- 신규 `validate-fe-anatomy-v52.mjs`: PASS
- Design Debt Ratchet: `116 <= 131` PASS
- Design-Code Parity: PASS
- Release Governance: major PASS

전체 로그: `docs/evidence/v52-validate-kbx-full.log`

## 7. 브라우저 검증 제한

현재 environment:

- `node`: 사용 가능
- `pnpm`: 없음
- root `node_modules`: 없음

따라서 Vite build, Vitest, Playwright browser suite는 이번 실행에서 수행하지 않았다.

정적 HTML Reference를 Chromium CLI로 screenshot하려 했으나 container의 DBus/headless process가 timeout되어 시각 증거로 채택하지 않았다. 코드 검증 결과와 browser E2E 결과를 혼동하지 않는다.

## 8. 다음 우선순위

다음 단계에서 새 Framework나 Metadata Engine을 추가하면 안 된다. 우선순위는 다음과 같다.

### P0 — 실제 Golden Screen FE 완성

1. `OMS-ORD-001` 주문관리
   - Grid row/detail context
   - quick filter / bulk result
   - drawer/action continuity
   - loading/empty/error/refetch 시각 검증

2. `OMS-ORD-002` 주문등록
   - Header → Detail Keyboard path
   - KbxLookup 실제 focus continuation
   - Detail Grid Enter/Tab/Paste
   - validation first/next error
   - 저장/확정/동시성 UX

3. `WMS-PICK-001`
   - Scanner state
   - network delay/offline
   - duplicate scan
   - success/error sound/vibration abstraction
   - one-hand operation visual QA

### P1 — 얇은 Vertical Slice Page 보강

- Purchase
- Inventory Move
- WMS Work Queue

이들은 Backend 타입을 더 만드는 것보다 사용자 입력·상태·예외·복구 동작을 실제 Vue 코드에서 완성해야 한다.

### P1 — Visual QA Gate

CI/개발환경에 pnpm dependency를 복원한 뒤 1440×900 / 1280×720 / Dark / forced-colors / WMS 390×844 기준의 Playwright screenshot + interaction regression을 main gate에 넣는다.

## 9. 최종 판단

v52는 “컴포넌트 수 증가”가 아니라 **기존 컴포넌트와 Template이 실제 업무 화면에서 더 명확한 의미를 가지도록 만드는 작업**이다.

향후에도 다음 질문으로 리뷰한다.

> 사용자가 화면을 처음 보고 현재 상태, 처리할 대상, 주요 Action, 다음 이동을 설명 없이 판단할 수 있는가?

아니라면 Contract가 아무리 완벽해도 FE는 미완성이다.
