# KBX FE QA Hardening v48

## 1. 판단

v47에서 T01/T02/T03의 `business-rule / permission / not-found / integration / system` Command Problem을 현재 업무 Context 안에서 복구할 수 있게 했지만, 실제 FE 전체를 다시 비교하면 **템플릿 유형별 실패 UX와 Reference 동작 수준이 달랐다.**

- T04/T06/T07/T08 actual Vue는 Mutation/Import 실패 시 일부 경로가 공통 Actionable Problem Surface까지 연결되지 않았다.
- Reference T05/T06/T07의 검색조건은 화면에 존재해도 조회 Action 일부가 Toast 또는 키보드 경로에 의존했다.
- Search Panel 내부 `[조회]`가 `type="button"`인데 click binding이 없는 경로가 있어 Mouse Complete를 위반했다.
- T08은 샘플 파일명을 상태에 넣는 방식이라 실제 Browser File 선택/Drop의 최소 계약을 재현하지 못했다.
- T08 데이터 흐름은 6단계인데 `.import-steps` 기본 CSS는 5열이었다.

v48은 새 Template이나 Metadata Engine을 추가하지 않고 이 **FE completion gap**만 닫는다.

## 2. 완료 루프 기준

```text
T04 Fast Entry
입력/붙여넣기 → 검증 → 저장 → 실패 원인/재시도

T05 Master-Detail
검색조건 → Loading → 결과/Empty → Master 선택 → Detail/History

T06 Work Queue
검색/빠른필터 → 대상 선택 → 배정/Wave → 실패/결과

T07 Reconcile
조건/불일치 → 대상 선택 → 재처리 → 결과/복구

T08 Import
실제 File → Mapping → Validation → Preview → Commit/Job → Result
```

버튼이 존재하거나 Toast가 발생하는 것만으로 완료하지 않는다.

## 3. Actual Vue 보강

### T04 `ERP-PRICE-001`

`useItemPriceFastEntry`에 `KbxProblem` 상태, 실패 작업, retry/dismiss를 연결했다. Local/Grid validation은 기존 Cell/Validation Summary를 유지하고, Server에서 인식 가능한 비-validation Problem만 Template Actionable Surface로 보낸다.

### T06 `COMMON Operations Queue`

claim/resolve/retry 등 Mutation 실패를 `KbxWorkQueuePage`의 Problem Surface로 연결한다. 실패 시 Queue Context를 지우지 않고, 성공했을 때만 Selection/Detail 상태를 정리한다.

### T07 `COMMON Reconcile`

예외 생성/재처리 계열 실패도 현재 조회조건과 Selection을 유지한다. Retry는 마지막 실패 작업의 안전한 Closure만 재실행한다.

### T08 `OMS-ORD-003`

Upload, Mapping 저장, 검증, Commit, Template/Error download를 동일 Problem boundary로 연결했다. Import의 Server Staging/Domain Validation 책임은 변경하지 않는다.

## 4. Template 계약 통일

다음 Template이 `problem / problemActionAllowlist / retryProblem / dismissProblem`을 공통 지원한다.

- KbxFastEntryPage
- KbxMasterDetailPage
- KbxQueuePage
- KbxWorkQueuePage
- KbxReconcilePage
- KbxImportPage

`KbxProblemFeedback 1.1.0`은 Validation Problem이 상위로 올라오는 경우 첫 3개 메시지와 잔여 건수를 제한적으로 요약한다. 이것은 Field/Cell validation을 대체하지 않는다.

## 5. Reference HTML/JavaScript 고도화

### T05

창고/품목 입력값을 실제 fixture Projection에 적용한다. 조회 시 Loading, 결과, Empty, 조건 초기화를 실제 상태 전이로 재현한다.

### T06

작업자/통합검색과 빠른필터를 실제 Queue rows에 함께 적용한다. 0건이면 Empty Recovery가 제공되고, Selection은 현재 visible rows 기준이다.

### T07

기준일/통합검색/불일치 조건을 실제 reconcile rows에 적용하고 재처리는 `Actual=Expected`, `Difference=0`, `상태=해결`로 Reference state를 변경한다.

### T08

샘플 파일명 주입을 제거했다. 실제 `<input type="file">`과 Drop Event의 `File`을 사용하며 `.xlsx/.xls`, 20MB presentation guard를 적용한다. 6단계 흐름에 맞춰 visual grid도 6열로 정합화했다.

File 확장자/크기 확인은 FE 편의 검증일 뿐, 실제 Import의 File parsing/Staging/Normalization/Business Validation/Commit은 Server 계약이다.

## 6. Chromium QA에서 추가 발견한 결함

초기 v48 QA에서 T05/T06/T07의 Search Panel `[조회]`가 `type="button"`인데 click handler가 없어 **Enter/F3은 되지만 마우스 조회는 안 되는 결함**을 발견했다.

이를 각각 `inventorySearchInline`, `queueSearchInline`, `reconcileSearchInline`로 명시적으로 bind하고 v48 Gate에 회귀 조건을 추가했다.

이 결함은 Screenshot이나 정적 구조 검사만으로 발견하기 어렵다. `Keyboard Accelerated`와 `Mouse Complete`를 별개의 QA 축으로 검증해야 하는 이유다.

## 7. Theme

KBX Business Light/Dark의 semantic token 계약은 유지한다. 이번 변경은 Theme palette를 확장하지 않고 검색/Empty/Problem/File state가 Dark에서도 동일한 정보 위계와 Focus를 갖게 한다.

Theme는 Permission이나 Domain rule에 관여하지 않는다.

## 8. Browser QA

Reference Chromium inline-asset harness: **30/30 PASS**

- Home boot + Dark Theme
- T05 실제 검색 → Loading → 결과 축소 → Empty → Reset
- T06 작업자 검색 → Loading → 결과 축소 → Empty → Reset
- T07 원인 검색 → Loading → mismatch selection → Resolution state mutation
- T08 실제 File input, File name 반영, 잘못된 extension 거부, 6-step, Mapping/Validation/Preview/Commit 이동
- 1280×720 document horizontal overflow 0
- runtime/page/console error 0

증적: `docs/evidence/v48-browser-template-completion.json`

Preview:

- `apps/web/fe-reference/previews/v48-t05-inventory-dark-1440x900.png`
- `apps/web/fe-reference/previews/v48-t08-file-dark-1440x900.png`

CSP meta는 inline harness에서만 제거했으며 Production CSP는 기존 정적 Governance Gate로 검증한다. 이 증적을 actual Vite/Vue/PrimeVue/AG Grid runtime E2E라고 주장하지 않는다.

## 9. 남은 우선순위

1. network-enabled 환경 actual Vue install/typecheck/build
2. T04/T06/T07/T08 actual runtime Problem Playwright
3. T08 실제 XLSX Template/Upload/Staging/Job/Result E2E
4. T05/T06/T07 API Loading/Empty/Error/Permission/Integration failure E2E
5. 1440×900 / 1280×720 / 200% Zoom × Light/Dark/Forced Colors visual regression

새 T10/T11, Runtime JSON UI, 자체 Grid/Theme Engine은 이 항목보다 우선하지 않는다.
