# KBX FE Recovery Workbench Hardening v55

## 1. 목적

v55의 목표는 공통 컴포넌트나 Backend 계약을 더 많이 만드는 것이 아니다.

이번 iteration은 실제 사용자가 브라우저에서 실패·예외·대사 불일치·대량 Import·WMS Scan을 처리할 때 다음 질문에 즉시 답할 수 있게 만드는 데 집중한다.

- 지금 어느 단계인가?
- 무엇이 서버에서 확인된 사실인가?
- 무엇이 아직 반영되지 않았는가?
- 오류는 어디에 있는가?
- 다음 행동은 무엇인가?
- 실패해도 어떤 Context가 유지되는가?

KBX Business UX/AX Standard의 `Familiar First`, `Exception Driven`, `Predictable Layout`, `Explicit State`, `Audit by Default`를 실제 Vue/HTML/JavaScript 작업면에 내리는 것이 목적이다.

---

## 2. 냉정한 비판

### 2.1 T08 Vue가 표준보다 뒤처져 있었다

표준은 Import를 다음 6단계로 정의한다.

`파일 → 매핑 → 검증 → Preview → 반영 → 결과`

그러나 v54 `KbxExcelImport` Vue 구현은 사실상 4단계였다.

`파일 → 매핑 → 검증 → 반영`

정적 FE Reference는 이미 6단계였기 때문에, 오히려 실제 Vue 제품 계층이 Reference보다 얇았다. 이 상태에서는 사용자가 검증 성공과 실제 Domain 반영 사이의 경계를 충분히 인식하기 어렵다.

### 2.2 T06 공통 계약이 실제 Wrapper에서 유실됐다

`KbxQueuePage`에는 Queue 제목·설명·건수·Action 위치가 있지만 `KbxWorkQueuePage`가 이를 전달하지 않았다.

즉 공통 Template 계약은 존재하지만 실제 예외센터에서 일부 정보가 사라지는 전형적인 **Wrapper contract erosion**이었다.

### 2.3 T07은 비교는 되지만 근거 검토 흐름이 약했다

Reconcile의 목적은 숫자를 나열하는 것이 아니라:

`Expected → Actual → Difference → Reason → Resolution`

이다.

v54는 Grid에서 비교 후 선택건을 예외로 등록할 수 있었지만, 행 하나의 근거를 Context 유지 상태에서 집중 검토하는 표준 Detail이 부족했다.

### 2.4 T09는 네트워크 Truth는 좋아졌지만 Scan Truth가 한 단계 부족했다

WMS에서는 사용자가 방금 Scan한 값과 서버가 실제로 받아 Domain 검증까지 끝낸 값이 다를 수 있다.

네트워크 timeout에서는 요청이 Commit됐지만 응답만 유실됐을 수도 있다. 따라서 단순한 `최근 Scan` 표시는 오히려 중복 작업을 유도할 수 있다.

필요한 것은 **최근 서버 확인 Scan**이다.

---

## 3. v55 실제 FE 변경

### 3.1 T08 — 6단계 Import Workbench

`KbxExcelImport 1.2.0`

실제 Vue 단계:

1. 파일
2. 매핑
3. 검증
4. 미리보기
5. 반영
6. 결과

Server status와 화면 단계는 명시적으로 연결한다.

- `uploaded / mapping-required` → 매핑
- `validating` → 검증
- `validated` → 미리보기
- `committing` → 반영
- `completed / partially-completed / failed / cancelled` → 결과

주요 개선:

- 현재 파일명·전체 건수·정상/오류 Context 유지
- Preview 전에 Domain DB 반영 없음 명시
- 정상/오류/경고 집계 표시
- 서버가 신규/수정 Projection을 제공할 때만 예상 신규/수정 표시
- 서버 근거가 없으면 신규/수정 숫자를 추정하지 않음
- 첫 오류 / 다음 오류 Focus 이동
- 오류파일 다운로드
- Commit 중 중복 파일 재제출 경고
- 부분 성공과 전체 실패를 다른 결과 UX로 구분
- Forced Colors Focus/Border 보강

### 3.2 T06 — Exception Queue Operational Pressure

`KbxWorkQueuePage 1.7.0`

Wrapper가 다음을 `KbxQueuePage`로 완전히 전달한다.

- queueTitle
- queueDescription
- queueCount
- queueCountUnit
- queue-heading
- queue-actions

실제 `COMMON-OPS-001`에서는:

- 전체 대상 건수: Server `totalCount`
- 표시 긴급: 현재 조회 결과 내 Critical
- 표시 미지정: 현재 조회 결과 내 담당 미지정
- 표시 60분+: 현재 조회 결과 내 장기 경과
- 선택 건수

를 분리했다.

중요한 점은 현재 Page의 200건을 전체 Queue 통계처럼 가장하지 않는 것이다. Page-local 수치는 명시적으로 `표시`라고 표현한다.

Quick action:

- `내 업무`
- `다음 긴급건`

`다음 긴급건`은 Grid를 다시 훑지 않고 기존 Exception Detail Drawer를 연다.

### 3.3 T07 — Evidence-preserving Reconcile

`COMMON-REC-001`에 다음을 추가했다.

Quick Result Filter:

- 전체
- 불일치
- 확인중
- 해결

Double click:

`Reconcile Grid → 대사 근거 Drawer`

Drawer는 다음을 한 번에 보여준다.

- Reference No
- Expected
- Actual
- Difference
- Reason
- Checked Time
- Resolution Status

핵심 정책은 명시적으로 표시한다.

> 원천값을 화면에서 직접 덮어쓰지 않는다.

불일치/확인중 건은 `이 건 예외 등록`으로 Exception Workflow에 진입한다.

Frontend는 `common.operations.create` 권한을 확인해 Action을 비활성화하지만, 실제 Enforcement는 Server가 계속 책임진다.

### 3.4 T09 — Authoritative Scan Truth

`useWmsPicking`에 `lastConfirmedScan`을 추가했다.

이 값은 다음 경우에만 갱신한다.

- Scan API 성공 응답
- 동일 Idempotency Key Retry가 서버에서 성공 확인됨

다음 경우에는 갱신하지 않는다.

- 로컬 Scan 입력만 발생
- 4xx Domain 거부
- Network timeout 후 Retry Queue 대기

실제 WMS Picking 화면에:

- 스캔 가능
- 입력 차단
- 재전송 확인 중
- 서버 확인 중 · 중복 스캔 금지
- 최근 서버 확인 Barcode / 시각

을 분리해 표시한다.

또한 수량 직접 입력은 다음 상태에서 fail-closed 처리한다.

- Offline
- Pending Retry 존재
- Scan API 확인 중

`작업 시작`과 `예외 등록` Mutation도 실패 시 Error feedback + authoritative task refetch를 수행한다.

---

## 4. Theme 적용 원칙

v55는 새로운 장식 테마를 만들지 않았다.

기존 Business Theme를 그대로 사용한다.

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

Module Theme는 Navigation/Context 식별에 사용하고 업무 상태의 의미색과 분리한다.

- success
- warning
- danger
- info
- focus

새 Preview/Error/Scan Truth surface는 전부 Semantic Token을 사용한다.

Dark / Light / Forced Colors에서 동일 업무 의미가 유지되도록 한다.

---

## 5. 보안·정합성 판단

### 유지한 원칙

- UI 숨김을 보안 Enforcement로 간주하지 않음
- Reconcile에서 Client-side 원천값 수정 금지
- Import Preview는 Commit 이전 단계로 명시
- WMS Server 응답 전 성공 Truth 생성 금지
- Idempotency Key 재사용 Retry 유지
- CSP same-origin / no-frame / no-worker / no-object 유지
- Import AI Mapping은 추천 근거일 뿐 확정값 아님

### 추가로 막은 오해

- 현재 Page의 긴급 건수를 전체 Queue 건수처럼 표시하지 않음
- Server Preview가 신규/수정 Count를 제공하지 않으면 FE에서 추정하지 않음
- 로컬 Barcode 입력을 서버 확인 Scan으로 표시하지 않음

---

## 6. QA 결과

`node scripts/validate-kbx.mjs`

전체 PASS.

최종 확인 기준:

- Design Tokens: 161
- Screen Definitions: 20
- Component Definitions: 86
- Core APIs: 34
- TS/Vue syntax units: 309
- T01~T09 Recipe Verification: 9/9
- Design Debt: 116 <= 131
- Design-Code Parity: PASS
- Release Governance: major PASS
- v41~v54 기존 FE regression: PASS
- v55 Recovery Workbench Gate: PASS

신규 Validator:

`scripts/validate-fe-recovery-workbench-v55.mjs`

---

## 7. Runtime 검증 한계

현재 Container에는:

- Node.js 존재
- Chromium 존재
- root pnpm 없음
- root/app node_modules 없음

따라서 다음을 성공했다고 주장하지 않는다.

- Vite production build
- Vitest runtime suite
- Vue/PrimeVue/AG Grid browser Playwright E2E

Static Chromium screenshot을 다시 시도했으나 DBus/zygote 환경 문제로 20초 timeout이 발생했다. Screenshot 생성 여부를 Release 증거로 사용하지 않았다.

정적/계약/Syntax PASS와 실제 Browser Runtime PASS는 분리한다.

---

## 8. 다음 우선순위

### P0 — T08 실제 Browser Workflow

실제 Browser에서 다음을 검증해야 한다.

`파일선택 → Mapping Keyboard → Validation Job → 오류 Focus → Preview → Commit Confirm → Background Job → Partial Result → 오류파일 재처리`

### P0 — T06/T07 Exception Resolution E2E

- Queue Filter 유지
- Detail Drawer Focus Restore
- Claim/Resolve 실패 시 Context 보존
- Reconcile Quick Filter
- Row Detail
- Permission
- 예외 등록 후 원래 대사 Context 복원

### P0 — WMS 390×844 Runtime

- Scanner keyboard wedge
- duplicate debounce
- network timeout
- same Idempotency Key retry
- last confirmed scan
- quantity sheet
- exception sheet
- offline blocking

### P1 — T01/T02/T03와 T06~T09의 Visual QA Matrix 통합

1440×900 / 1280×720 / Dark / Forced Colors / 200% Zoom / 390×844를 Release Evidence로 자동 수집해야 한다.

---

## 9. 최종 판단

v55의 의미는 Component를 더 만든 것이 아니다.

다음 경계를 실제 화면에 더 분명히 만든 것이다.

`입력한 것 ≠ 서버가 확인한 것`

`검증 완료 ≠ Domain 반영 완료`

`현재 Page 통계 ≠ 전체 업무 통계`

`대사 불일치 확인 ≠ 원천값 직접 수정`

이 경계를 사용자 눈앞에서 설명할 수 있어야 OMS/WMS/ERP FE가 운영 제품 수준에 가까워진다.
