# KBX FE Presentation Workbench Hardening v51

## 1. 판단

v50까지의 가장 큰 리스크는 기능 부족이 아니라 **완성도 불균형**이었다.

- Screen Contract, Domain 경계, 오류/권한/복구/운영 검증은 매우 강하다.
- 반면 실제 사용자가 매일 보는 `Application Shell / Home / T01~T08`의 시각적 계층과 업무면 구분은 상대적으로 얇았다.
- 표준 Template SFC가 존재한다는 사실만으로는 표준 화면이 현장에서 같은 품질로 보인다는 것을 보장하지 않는다.
- 검증 스크립트가 PASS여도 사용자가 느끼는 탐색 비용, 현재 모듈 인지, 화면 유형 인지, 작업 시작 속도까지 자동으로 좋아지는 것은 아니다.

따라서 v51은 Backend 기능 추가보다 **실제 Vue/CSS/JavaScript 렌더링 계층**을 우선 보강한다.

## 2. 유지한 KBX 원칙

- 한국형 업무 문법과 Predictable Layout을 유지한다.
- Card Dashboard를 추가하지 않는다.
- 모듈 색은 `상태(success/warning/danger)`와 혼합하지 않는다.
- Primary Action 수, Command 위치, Grid/Excel/Keyboard 계약을 바꾸지 않는다.
- PrimeVue/AG Grid API를 Vertical Slice에 다시 노출하지 않는다.
- 모든 화면을 Runtime JSON UI로 바꾸지 않는다.
- UI Disabled/Hidden을 보안 경계로 간주하지 않는다. 기존 Backend Permission/Domain Validation 계약을 유지한다.

## 3. v51 변경

### 3.1 Module Identity Theme

OMS / ERP / WMS / COMMON에 별도의 Module Identity token을 추가했다.

용도:

- Side Navigation 활성 표시
- Workspace Tab 활성 표시
- Page Header 모듈 식별
- Home 모듈 섹션 식별
- Standard Template의 얇은 accent

금지:

- 오류/성공/경고 의미 대체
- 행 전체 색칠
- 사용자가 임의 CSS/색상 문자열을 주입하는 Runtime Theme

Light/Dark와 Windows forced-colors까지 token generator가 동일 Source of Truth에서 생성한다.

### 3.2 Home = 업무 시작 Workbench

Home 상단에 대형 KPI Card가 아닌 compact operational pulse를 추가했다.

- 사용 가능 화면
- 미저장 업무
- 진행 작업
- 새 알림

각 항목은 단순 숫자가 아니라 기존 메뉴검색 / dirty resume / job center / notification center로 이어지는 작업 진입점이다.

모듈별 업무 목록은 OMS/ERP/WMS/COMMON identity를 명확히 하되 메뉴 깊이를 늘리지 않는다.

### 3.3 T01~T08 Presentation Grammar

표준 Template이 동일한 빈 컨테이너처럼 보이지 않도록 업무 목적에 맞는 surface hierarchy를 부여했다.

| Type | v51 시각/조작 강조 |
|---|---|
| T01 Search/List | Search 시작점 + Grid 작업면 + sticky summary |
| T02 Master CRUD | Master list / Detail의 명확한 분리와 Detail identity |
| T03 Header+Detail | Header form / Detail grid / Workflow의 단계 분리 |
| T04 Fast Entry | Keyboard guide와 입력면을 최우선 |
| T05 Master/Detail | Master context와 Detail 근거의 pane hierarchy |
| T06 Queue | 일반 작업과 Exception 우선순위를 시각적으로 분리 |
| T07 Reconcile | 비교/불일치 Summary를 Grid보다 먼저 인지 |
| T08 Import | Step/Content/Result의 처리 단계 명확화 |

T09 WMS Mobile의 독립 Touch/Scanner 문법은 기존 계약을 유지한다.

### 3.4 Static HTML/JavaScript Reference parity

`apps/web/fe-reference`도 Vue와 별개의 장식 Demo가 되지 않도록 같은 문법을 반영했다.

- Home operational pulse
- Module identity
- T01~T08 template presentation differentiation
- 기존 실제 검색/선택/오류/복구/Import/WMS 동작 보존

이 Reference는 Framework 계약을 증명하는 문서가 아니라 실제 Browser DOM/CSS/JS UX를 빠르게 확인하는 독립 FE 기준면으로 유지한다.

## 4. Token / 기술부채 처리

처음 스타일 강화 과정에서 4개의 hard-coded px literal이 Design Debt Gate에 걸렸다.

기준선을 올리지 않고 다음처럼 제거했다.

- Home max width는 token source로 이동
- tab active indicator는 border-width token 계산 사용
- sticky summary shadow는 border-width token 계산 사용

결과:

- Design debt baseline: 131
- v51 measured: 116
- Ratchet PASS

즉, 화면 완성도 강화 때문에 토큰 규율을 희생하지 않았다.

## 5. Security / Stability

v51은 presentation hardening이므로 Domain/Permission 계약을 약화하지 않는다.

- `data-kbx-module` 값은 Screen Definition의 고정 module vocabulary를 사용한다.
- Runtime arbitrary CSS theme injection을 도입하지 않았다.
- Status semantic과 module identity를 분리해 업무상 상태 오판 가능성을 줄였다.
- forced-colors fallback을 generator에 포함해 접근성 모드에서 정보가 색상에 종속되지 않는다.
- 기존 fail-closed write permission, action allow-list, server validation, concurrency/error contracts는 회귀 검증을 그대로 통과한다.

## 6. 검증 결과

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

핵심 결과:

- TypeScript/Vue script syntax: 308 units PASS
- Screen governance: 20 screens PASS
- Design system: 161 tokens / 85 components PASS
- T01~T09 template completeness PASS
- FE v41~v50 regression PASS
- 신규 `validate-fe-presentation-v51.mjs` PASS
- Design debt ratchet: `116 <= 131` PASS
- Design-code parity PASS
- Release governance PASS

## 7. 아직 남은 냉정한 과제

v51로 “보이는 껍데기” 문제는 한 단계 개선됐지만 다음은 아직 완료가 아니다.

1. **실제 Vite Build/Playwright Visual Evidence**  
   현재 작업 환경에 pnpm/node_modules가 없어 실제 Vue bundle build와 Playwright browser E2E는 실행하지 못했다. Dependency-free syntax/governance 검증과 static FE 검증은 통과했다.

2. **Golden Screen의 픽셀보다 Task Metric 검증**  
   OMS-ORD-001/002, WMS-PICK-001에서 Clicks/Task, Keyboard strokes, Exception resolution time을 실측해야 한다.

3. **Component State Catalog의 시각 깊이**  
   Default만 보는 Catalog가 아니라 Readonly/Disabled/Error/Changed/AI Suggested/Dark/Forced-colors까지 독립 재현성을 더 강화해야 한다.

4. **FE Density 실제 사용자 검증**  
   1440×900 Compact 기준으로 “한 화면에 정보가 많다”가 아니라 “필요한 정보가 빨리 보인다”는 것을 현업 시나리오로 검증해야 한다.

## 8. 다음 우선순위

다음 버전은 새 프레임워크를 만들지 말고 아래 순서가 적절하다.

1. OMS-ORD-001 Golden Screen의 실제 DOM/keyboard/bulk/detail drawer polish
2. OMS-ORD-002 Header+Detail fast-entry polish
3. ERP-MST-ITEM-001 Master CRUD field density/lookup/audit polish
4. T04 Fast Entry의 paste/error navigation 현장성 강화
5. Browser 실행 가능한 Playwright Visual + keyboard regression을 CI evidence로 고정

핵심은 더 많은 추상화가 아니라 **이미 있는 KBX 계약을 실제 화면에서 더 잘 느끼게 만드는 것**이다.
