# KBX Foundation v53 — FE Golden Screen Interaction Hardening

## 1. 작업 목적

v53의 목표는 v52에서 정리한 화면 Anatomy를 **실제 사용자가 조작하는 Vue/HTML/JavaScript 업무 흐름**으로 한 단계 더 내리는 것이다.

새 Backend 추상화나 Runtime UI Engine을 늘리지 않는다. 기존 KBX 계약을 유지한 채 다음 네 가지를 우선한다.

1. Home이 모듈 선택 이후 실제 업무 탐색과 예외 압력까지 연결되어야 한다.
2. T02/T03/T06/T07의 Section 안에서 사용자가 할 수 있는 Action이 예측 가능한 위치에 있어야 한다.
3. 얇은 Vertical Slice는 Lookup, Grid Editing, Dirty, Validation, Keyboard를 실제 FE 코드로 구현하되 Server Command가 없는 상태를 성공으로 가장하지 않는다.
4. WMS T09는 작업자가 다음 Scan/대기/복구 행동을 즉시 판단할 수 있어야 한다.

근거 문서: `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 컴포넌트 수는 이미 충분하다

현재 문제는 `KbxButton`, `KbxLookup`, `KbxDataGrid`, Template의 개수가 부족한 것이 아니다. 공통 계약과 Manifest는 강하다. 문제는 **화면에서 계약을 얼마나 실제 업무행동으로 연결했는가**다.

계약만 강하고 조작이 비어 있으면 다음 문제가 생긴다.

- 버튼은 보이지만 실제 Command가 없다.
- 상태가 바뀌는 것처럼 보이지만 Server Domain truth가 아니다.
- Grid는 보이지만 행 추가/Lookup/오류 이동이 끊긴다.
- Home에 정보가 많아도 키보드로 업무영역을 빠르게 좁히기 어렵다.
- WMS가 메시지는 보여도 작업자가 다음 행동을 즉시 알기 어렵다.

### 2.2 가장 위험한 결함은 “가짜 성공”이다

Purchase / Inventory Move 같은 얇은 화면에서 Server Command 연결 없이 Client가 workflow status를 바꾸는 방식은 시연 화면에서는 그럴듯하지만 업무시스템에서는 위험하다.

```text
사용자가 확정 클릭
→ Client status = Confirmed
→ 실제 DB/Domain은 미변경
```

이것은 단순 미완성보다 나쁘다. 화면이 잘못된 업무 사실을 전달하기 때문이다.

v53에서는 로컬 입력, Lookup, Grid 편집, Validation, Dirty, Keyboard는 실제로 동작시키되 Server Command가 없는 저장/확정/출고/입고는 **fail-closed**로 처리한다. UI는 “상태를 변경하지 않았습니다”라고 명시한다.

### 2.3 Home은 “메뉴 수”보다 “업무 압력”을 보여줘야 한다

v52 Home Module Rail은 screen/favorite/open count를 제공했다. 하지만 실무에서 사용자는 화면 개수보다 **지금 확인할 일이 어디에 몰렸는가**를 먼저 봐야 한다.

따라서 v53은 동일 Attention source에서 모듈별 확인 필요 건수를 계산한다. 별도 집계 truth를 만들지 않는다.

### 2.4 Section Action은 페이지마다 흩어지면 안 된다

Master/Transaction/Queue/Reconcile에서 해당 작업면의 행 추가, 오류 이동, 선택 작업 같은 Action이 임의 위치에 생기면 Predictable Layout이 무너진다.

따라서 Section Header가 count/unit뿐 아니라 표준 action slot을 소유하게 했다.

---

## 3. v53 적용 내용

## 3.1 Home — Attention-aware Module Rail + Keyboard

`KbxHomePage.vue`의 module rail을 다음처럼 강화했다.

- `전체 / OMS / ERP / WMS / 공통`
- 화면 수
- `확인 필요` 건수
- 즐겨찾기 수
- 열린 Workspace 수
- ArrowLeft / ArrowRight
- Home / End
- 선택 후 `kbx-home-explorer` scroll + focus
- stable `data-home-module`
- forced-colors에서 active/focus cue 유지

중요한 점은 module attention을 별도 하드코딩하지 않고 Home Attention Queue와 **동일 truth**에서 파생한다는 것이다.

Home의 판단 흐름은 다음으로 정리된다.

```text
검색
→ 운영상태
→ 업무영역 + 확인 필요 압력
→ 확인 필요
→ 바로 시작
→ 전체 업무 Explorer
```

---

## 3.2 Standard Section Header — Count Unit + Action Surface

`KbxSectionHeader`에 `countUnit`을 추가했다.

예:

```text
주문 상품 · 3종
품목 목록 · 218개
현재 작업 Queue · 42건
```

화면이 매번 `건/개/종` markup을 직접 만들지 않는다.

다음 Template에는 표준 Section Action slot을 추가했다.

- `KbxMasterPage`: `list-actions`, `detail-actions`
- `KbxTransactionPage`: `header-actions`, `detail-actions`
- `KbxQueuePage`: `queue-actions`
- `KbxReconcilePage`: `comparison-actions`

목적은 Slot 자유도를 늘리는 것이 아니라 **업무면 안의 Action 위치를 고정**하는 것이다.

---

## 3.3 Golden Screen — OMS 주문등록

`OMS-ORD-002`에 다음을 보강했다.

### 현재 Context

화면 상단 Context에 다음 정보를 명시한다.

- 현재 주문 / 신규
- 현재 상태
- Dirty 여부
- 주문 상품 수
- 현재 Validation 오류 수

### Detail Work Surface

`주문 상품` Section Header에:

- `행 추가`
- `첫/다음 오류`

Action을 배치했다.

`행 추가` 후 품목코드 셀로 Focus가 이동한다.

`오류 이동`은 Grid의 `focusError()` 계약을 사용한다.

상세 건수는 일반 `건`이 아니라 업무 의미에 맞는 `종`을 사용한다.

---

## 3.4 ERP 구매등록 — 얇은 Wrapper에서 실제 FE Draft로

기존의 매우 얇은 조립 화면을 실제 입력 가능한 Draft FE로 보강했다.

구현 범위:

- `KbxTransactionPage`
- `KbxFormSection / KbxFormGrid`
- 거래처 Lookup
- 창고 Lookup
- Item F2 Lookup
- Item code 직접 입력 + `resolveByCode`
- 행 추가 / 행 복제
- 수량 / 단가 편집
- 금액 즉시 재계산
- `KbxValidationError`
- Header/Row validation
- Dirty state
- Workspace navigation guard
- F8 save intent
- 오류 Focus

Validation 예:

```text
거래처 필수
입고창고 필수
최소 1개 품목
품목 필수
수량 > 0
단가 >= 0
```

### 중요한 보안/정합성 경계

Server Save/Confirm Command가 Foundation에 연결되지 않은 상태에서 다음을 하지 않는다.

```text
status.value = CONFIRMED
저장 성공 Toast
가짜 Audit
가짜 Domain commit
```

대신 사용자가 저장/확정을 시도하면 서버 Command가 연결되지 않았으며 **업무 상태를 변경하지 않았음**을 명시한다.

즉, v53의 Purchase는 “실제 FE Draft interaction”까지 완성했지만 “End-to-End 업무 완료”라고 주장하지 않는다.

---

## 3.5 ERP 재고이동 — 실제 입력과 즉시 UX 검증

Inventory Move도 동일 원칙으로 보강했다.

구현:

- 출발창고 / 도착창고 Lookup
- 품목 F2 Lookup / code resolve
- Item metadata의 available quantity 반영
- 행 추가 / 복제 / Focus
- 이동수량 편집
- Dirty / F8 / Workspace guard
- Validation summary / cell focus

즉시 UX validation:

```text
출발창고 필수
도착창고 필수
출발창고 != 도착창고
품목 필수
이동수량 > 0
이동수량 <= 가용재고
```

하지만 최종 재고 정합성은 Client 값으로 확정하지 않는다. Server Domain validation 이전에 `확정/출고/입고완료` state를 Client에서 만들지 않는다.

---

## 3.6 WMS Picking — 다음 행동 중심 T09

WMS Picking의 가장 중요한 UX는 “예쁜 Mobile 화면”이 아니라 **작업자가 지금 무엇을 해야 하는가**다.

v53은 `KbxWmsMobilePage`의 `taskContext`와 `instruction`을 실제 화면에 연결했다.

별도 `notice` surface에서 다음을 구분한다.

- 온라인 처리 메시지
- 오프라인
- 전송 대기 Command
- 동기화 중
- Server 확인 대기

작업 본문에는 `다음 행동`을 명시한다.

예:

```text
위치 스캔
상품 스캔
서버 확인 중
피킹 완료
스캔 대기
```

Server 응답 대기 중에는 중복 Scan을 하지 말라는 행동 지침을 표시한다.

Offline + pending command 상태에서는 동일 Command Key를 이용한 안전한 replay 원칙을 설명하고, Server validation이 필요한 Scan을 성공으로 가장하지 않는다.

---

## 3.7 Queue / Reconcile 실사용 Action 위치

`WMS-WORK-001`:

- Queue Section Header에 `선택 작업 시작`
- 선택 0건이면 disabled

`COMMON-RECON-001`:

- Comparison Section Header에 `선택건 예외 등록`
- 선택 0건이면 disabled

화면의 Command Bar를 무작정 늘리는 대신 해당 work surface의 contextual action으로 배치했다.

---

## 3.8 순수 HTML / JavaScript Reference parity

`apps/web/fe-reference`에도 v53 Home interaction을 반영했다.

- module별 attention count
- ArrowLeft / ArrowRight / Home / End
- 선택 후 explorer scroll/focus
- focus-visible
- v53 build label

Vue만 계약을 갖고 순수 FE Reference가 낡는 이중화를 방지한다.

---

## 4. Theme 적용 원칙

v51~v52의 Module Identity Theme을 그대로 유지한다.

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

이 색은 **Navigation / Chrome / Module Context identification** 용도다.

다음 의미색과 분리한다.

- success
- warning
- danger
- info
- disabled

즉, WMS가 Teal이라고 “성공”이 Teal인 것은 아니다. Domain state와 module identity를 같은 색 체계로 합치지 않는다.

Dark / forced-colors에서도 동일한 업무 의미와 Keyboard contract를 유지한다.

---

## 5. 보안·업무 Truth 원칙

v53에서 가장 중요한 보강은 보이는 보안보다 **truthful UI**다.

### Frontend가 할 수 있는 것

- Required/format/cross-field 1차 UX validation
- Lookup resolve
- Grid editing
- Dirty state
- 작업 전 Command intent
- 오류 위치 이동
- Permission 기반 표시

### Frontend가 최종 결정하면 안 되는 것

- 재고 확정
- 구매 확정
- 재고이동 workflow transition
- 출고/입고 성공
- 권한 최종 승인
- Concurrency 승패
- Audit truth

최종 truth는 Server/Domain/DB constraint가 책임진다.

Server Command가 없을 때 Client state machine으로 성공을 흉내 내지 않는 것이 v53의 명시적 정책이다.

---

## 6. 검증 결과

실행:

```bash
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**
- v41~v52 FE regression: **PASS**
- 신규 `validate-fe-golden-interaction-v53.mjs`: **PASS**
- Component catalog: **34 core APIs / 70 entries**
- Design Debt Ratchet: **116 <= 131 PASS**
- Design-Code Parity: **161 tokens / 34 core / 85 total PASS**
- Release Governance: **major PASS**

전체 로그:

`docs/evidence/v53-validate-kbx-full.log`

---

## 7. Runtime 검증 제한

현재 작업 환경에서:

- `node`: 사용 가능
- `npm`: 사용 가능
- `pnpm`: 없음
- root `node_modules`: 없음
- `apps/web/node_modules`: 없음

따라서 이번 실행에서 다음을 수행했다고 주장하지 않는다.

- Vite production build
- Vitest browser/component runtime
- Playwright 실제 Vue runtime E2E

정적 generator/contract/syntax/regression gate와 실제 browser runtime 검증은 별개의 증거다.

---

## 8. 다음 우선순위

### P0 — Dependency 복원 후 Golden Screen Browser QA

화면:

1. `OMS-ORD-001`
2. `OMS-ORD-002`
3. `WMS-PICK-001`

Viewport/환경:

- 1440×900
- 1280×720
- Light
- Dark
- forced-colors
- WMS 390×844

검증:

- Mouse
- Keyboard only
- Focus order
- Drawer restore
- Grid selection/edit
- Lookup F2/Enter/Esc
- Bulk result
- Validation recovery
- WMS duplicate/network/retry

### P0 — Purchase / Inventory Move 실제 Server Command 연결

현재 FE Draft contract는 유지한다.

연결할 것은:

```text
Save / Confirm / Move Confirm / Ship / Receive
↓
FastEndpoint
↓
Application Command
↓
Domain validation
↓
PostgreSQL transaction
↓
Audit + Outbox
```

연결 이후에도 Client가 authoritative state를 먼저 바꾸면 안 된다.

### P1 — OMS-ORD-001 실전 밀도 고도화

다음 단계는 새 컴포넌트 추가보다:

- all-filtered selection
- Bulk partial failure recovery
- Drawer context continuity
- saved layout
- Excel export/import continuity
- quick filter exception pressure

을 실제 Browser 시나리오로 검증하는 것이다.

---

## 9. 최종 판단

v53에서 중요한 변화는 코드량 증가가 아니다.

```text
Template이 있다
→ Template 안에서 행동 위치가 예측 가능하다

Button이 있다
→ 실제 FE interaction이 있다

Workflow가 보인다
→ Server가 없으면 성공을 가장하지 않는다

Home에 메뉴가 있다
→ 지금 확인할 업무 압력까지 보인다

WMS에 메시지가 있다
→ 작업자가 다음 행동을 즉시 안다
```

이 방향이 유지되어야 KBX가 “BE 계약이 강한 UI Framework”를 넘어 **실제 현장 사용자가 빠르고 안전하게 쓰는 업무 Frontend**가 된다.
