# KBX FE Work Surface Triage & Wayfinding Hardening v54

## 1. 판단

v53까지 KBX는 Home module rail, 표준 Section Header, Golden Screen interaction, fail-closed workflow를 상당히 확보했다. 그러나 실제 업무 FE 관점에서는 여전히 세 가지 간극이 남았다.

첫째, Home의 `확인 필요`가 시간순 flat queue 성격을 유지하면 실패·미저장·장시간 Job·일반 알림이 같은 시각 우선순위로 경쟁한다. 사용자는 “무엇부터 처리해야 하는가”를 다시 판단해야 한다.

둘째, T02 목록-상세는 목록과 Form을 동시에 보여주지만 현재 레코드가 조회 결과의 몇 번째인지, 이전/다음으로 연속 검토할 수 있는지가 표준 계약이 아니었다. 마우스로 목록을 다시 찾는 왕복은 Master CRUD 현장에서 매우 자주 발생하는 낭비다.

셋째, T04/T05는 Template 골격은 있었으나 `이 Grid가 무엇을 입력하는가`, `현재 몇 건인가`, `이 Pane이 어떤 Context인가`, `Pane-level Action은 어디에 있는가`가 화면별 구현에 의존했다. Template이 배치만 표준화하고 work surface 자체를 충분히 설명하지 못한 상태였다.

따라서 v54는 새 Metadata Engine이나 BE 추상화를 추가하지 않고 Home triage, record wayfinding, workflow next-action, T04/T05 work-surface anatomy를 실제 Vue/HTML/JavaScript에 보강한다.

## 2. Home — flat attention queue를 operational triage로 변경

Home의 Attention truth는 기존 `allAttentionQueue`를 그대로 source of truth로 사용한다. 새로운 별도 집계 저장소를 만들지 않는다.

표현만 다음 네 lane으로 분류한다.

- `긴급·예외`: 실패 작업 + 긴급 알림
- `미저장`: 중단한 편집
- `진행 작업`: Batch/Integration 작업
- `알림`: 일반 Notification

Collapsed 상태에서는 lane당 상위 2건, expanded 상태에서는 lane당 상위 6건을 보여준다. 이렇게 하면 한 종류의 알림이 많아도 다른 종류의 중요한 업무가 첫 화면에서 밀려나지 않는다.

중요한 routing 보정도 했다. `긴급·예외`는 실패 작업과 긴급 알림이 혼합될 수 있으므로 overflow를 알림센터로 단정하지 않는다. 먼저 lane을 확장해 원래 source와 intent를 유지한다. `진행 작업`은 작업센터, `알림`은 알림센터로 연결한다.

Card dashboard, 차트, KPI 장식을 늘리지 않았다. Home은 업무 시작점이며 목적은 판단량을 줄이는 것이다.

## 3. T02 — KbxRecordNavigator

`KbxRecordNavigator`를 신규 Business Component로 추가했다.

표준 기능:

- 현재 레코드 위치 `current / total`
- 이전 / 다음
- 첫/마지막 경계 disabled
- dirty 상태에서 이동 disabled
- focus-visible
- forced-colors
- 모바일 폭에서는 button text를 줄이고 기능은 유지

실제 `ERP-MST-ITEM-001`에 적용했다. 핵심은 Navigator가 직접 selection state를 바꾸지 않는 것이다. 기존 `requestChoose()` 경로를 재사용하므로 미저장 변경 확인/보호 로직을 우회하지 않는다.

이 구조는 UX Component가 Domain/dirty safety를 침범하지 않으면서 반복 탐색 조작을 줄인다.

## 4. Workflow — 현재 상태만이 아니라 다음 작업까지 명시

`KbxWorkflowBar 1.2.0`은 다음을 동시에 보여준다.

- 현재 상태
- 상태 흐름
- 현재 위치 `n / total`
- 다음 가능한 Action label
- 실제 실행 Action

가능한 Action이 없을 때 빈 공간을 보여주지 않고 `현재 상태에서 실행 가능한 다음 작업이 없습니다.`를 표시한다.

상태 흐름의 현재 항목에는 `aria-current="step"`을 적용했다. Theme accent는 현재 단계 식별용이며 success/warning/error semantic color를 대체하지 않는다.

## 5. T04 — Fast Entry를 “Grid 슬롯”이 아니라 작업면으로 승격

`KbxFastEntryPage 1.10.0`에 다음 계약을 추가했다.

- `gridTitle`
- `gridDescription`
- `rowCount`
- `rowCountUnit`
- `grid-heading`
- `grid-actions`

화면 구조는 Keyboard Guide → Context → Bulk/Contextual → Named Fast Entry Surface → Validation → Sticky Summary로 고정한다.

실제 품목단가 화면은 `품목 단가 입력`, 입력 건수, 오류 건수를 Grid 상단에서 즉시 확인할 수 있다. 오류 수는 별도 dashboard card가 아니라 작업 Grid 바로 옆에 둔다.

## 6. T05 — Master / Detail / History의 목적과 규모를 표시

`KbxMasterDetailPage 1.9.0`에 Master/Detail/Bottom 각각의 title/description/count/countUnit과 action slot을 추가했다.

- `master-actions`
- `detail-actions`
- `bottom-actions`

실제 ERP 재고현황은 다음처럼 읽힌다.

- Master: 품목 — 조회된 품목 수
- Detail: 창고/로케이션 — 선택 품목의 위치 수
- Bottom: 재고이력 — 선택 품목의 이력 수

기존 Grid를 바꾸지 않고 Context 이해를 높였다. 데이터는 기존 Query projection을 그대로 사용하므로 별도 client-side truth를 만들지 않는다.

## 7. Static HTML / JavaScript parity

`apps/web/fe-reference`도 v54로 함께 변경했다.

- Home 4-lane triage
- lane overflow routing
- T02 record navigator
- dirty 상태의 이전/다음 차단
- T04 named fast-entry surface
- keyboard module rail 유지
- focus/high-contrast cue

Vue에만 좋아진 UX를 넣고 Reference HTML/JavaScript가 낡는 구조를 허용하지 않았다.

정적 Reference CSP는 기존 보안 경계를 유지한다.

- `connect-src 'self'`
- `object-src 'none'`
- `frame-src 'none'`
- `worker-src 'none'`
- `frame-ancestors 'none'`
- `base-uri 'none'`

새 Home/Navigation 기능을 위해 외부 script, inline script, 임의 network origin을 열지 않았다.

## 8. 회귀에서 발견하고 바로잡은 문제

### 8.1 긴급 overflow 오라우팅

초기 구현에서는 `긴급·예외`의 나머지 항목을 알림센터로 보냈다. 그러나 lane에는 operation failure도 들어갈 수 있으므로 잘못된 라우팅이었다. v54에서는 긴급 lane을 먼저 확장하도록 수정했다.

### 8.2 Theme v43 gate 회귀

신규 triage가 border-top과 background로 구분되면서 과거 v43 gate의 `색 이외의 priority cue` 계약을 만족하지 못했다. 기준을 완화하지 않고 각 triage item에 accent left border를 복원했고, critical item은 danger border로 식별하도록 수정했다.

### 8.3 정적 theme 변수

신규 Reference CSS가 기존 forced-colors 구간에서만 존재하는 `--surface-hover`와 정의되지 않은 `--focus`에 의존할 수 있는 문제를 제거했다. 실제 기본 theme에 존재하는 `--muted`, `--primary`를 사용한다.

## 9. 검증 결과

최종 `node scripts/validate-kbx.mjs` 결과:

- Design tokens: 161
- Screens: 20
- Components: 86
- Core APIs: 34
- Navigation entries: 16
- T01~T09 recipe verification: 9/9
- TypeScript/Vue syntax units: 309
- Design Debt: 116 <= 131
- Design-Code Parity: PASS
- Release Governance: major PASS
- v41~v54 FE regression: PASS

v54 전용 gate는 Home triage, T02 record navigation, Workflow next action, T04/T05 work-surface anatomy, static FE parity, CSP/high-contrast를 검사한다.

## 10. 아직 완료라고 부르면 안 되는 부분

현재 root에는 `pnpm`과 `node_modules`가 없다. 따라서 Vite production build, Vitest, Playwright browser E2E까지 PASS했다고 주장하지 않는다.

Chromium 자체는 설치돼 있어 static reference screenshot을 시도했지만 container DBus/zygote 환경에서 headless process가 종료되지 않아 timeout되었다. 이 결과는 시각 QA 증거로 채택하지 않았다.

즉 현재 증거는 source contract / JavaScript syntax / TypeScript·Vue transpile / KBX governance regression 수준이다. 실제 browser runtime 검증은 별도로 필요하다.

## 11. 다음 우선순위

다음 FE 단계는 Framework 증설보다 다음 순서가 맞다.

1. T08 Excel Import의 실제 6단계 입력·매핑·검증·Preview·Job 결과 work-surface 밀도 고도화
2. T06 Queue와 T07 Reconcile의 row-level recovery/action pattern을 실제 Golden interaction으로 승격
3. T09 WMS Picking의 390×844 runtime visual/keyboard-wedge/network state 검증
4. 의존성이 준비된 환경에서 1440×900 / 1280×720 / Dark / forced-colors / 390×844 Playwright 시각·조작 회귀 실행

중요한 원칙은 그대로다. FE 완성도는 컴포넌트 수가 아니라 사용자가 `현재 상태 → 다음 행동 → 오류 복구`를 빠르게 판단하고 실제 업무를 끝낼 수 있는지로 판단해야 한다.
