# KBX FE QA Hardening v49

## 1. 판단

v48에서 T04~T08의 실제 FE 완료 루프와 Reference 검색/File 상호작용을 보강했지만, Home과 WMS를 다시 현장 관점으로 비교하면 **화면이 완성돼 보이는 것과 업무 사실을 정확히 표현하는 것 사이에 아직 차이**가 있었다.

- Home `확인 필요`는 상위 8개까지만 보여주고 전체 건수를 알려줬지만 숨은 우선업무를 Home 안에서 확인할 방법이 없었다.
- `WMS-WORK-001`의 실제 Vue API adapter는 항상 `[]`를 반환해 화면은 완성돼 보여도 일반 실행에서 항상 Empty였다.
- Receiving/Putaway/Counting은 로컬 `ref()` 상태만으로 Scan→완료를 만들 수 있어 Server validation/idempotency/audit 이전에 성공처럼 보일 수 있었다.
- T06 Queue의 Empty/Error 문구와 Recovery가 업무별로 명시적으로 전달되지 않아 공통 기본문구 의존도가 높았다.

v49는 새 Dashboard, 새 Theme Engine, 새 Metadata Framework를 만들지 않고 **Home Workbench의 숨은 업무 제거와 WMS의 truth boundary**를 FE 계약으로 고정한다.

## 2. AX/UX 비판 기준

Home의 목적은 더 많은 Card를 보여주는 것이 아니라 사용자가 **지금 판단해야 할 업무를 빠짐없이 보고 바로 시작하게 하는 것**이다.

```text
나쁜 흐름
확인 필요 12건
→ 상위 8건만 보임
→ 나머지 4건은 다른 화면을 찾아야 함

v49
확인 필요 12건
→ 상위 8건 우선
→ [전체 12개 보기]
→ 같은 Context에서 나머지 확인
```

또 WMS에서는 `0건`과 `API 미연결`이 같은 뜻일 수 없다. `완료`와 `Client Demo state`도 같은 뜻일 수 없다. 운영 현장에서는 이 구분이 데이터 정합성 문제로 직결된다.

## 3. Home Workbench

`KbxHomePage 1.9.0`은 Attention을 기본 8건만 노출해 시각 과밀을 막되, 전체 건수가 더 많으면 접근성 Disclosure로 최대 24건까지 펼칠 수 있다.

- `aria-controls="kbx-home-attention-list"`
- `aria-expanded`
- `전체 N개 보기 / 상위 8개만 보기`
- 미저장/실패/중요 알림/진행/알림 source summary

source summary는 경영 KPI가 아니다. 사용자가 왜 Attention이 늘었는지 판단하는 최소 업무 분류다. 원형차트나 장식형 Dashboard는 추가하지 않았다.

Reference HTML/JavaScript도 동일하게 10개의 Attention fixture 중 기본 8개를 보여주고 전체 보기/접기를 실제 상태로 처리한다.

## 4. T06 WMS Work Queue

`KbxQueuePage 1.8.0`에 업무별 Query Recovery copy를 명시적으로 전달할 수 있는 계약을 추가했다.

- `emptyTitle`
- `emptyDetail`
- `emptyActionLabel`
- `errorTitle`
- `errorDetail`
- `retryLabel`
- `emptyAction`

`WMS-WORK-001 1.1.0`은 Demo Mode에서는 실제 fixture Projection을 taskType/status/owner/keyword로 필터링한다.

일반 Runtime에서는 더 이상 `[]`를 반환하지 않는다. WMS Work Query API가 연결되지 않았으면 `WMS_WORK_QUERY_NOT_CONNECTED` Integration Problem으로 명시적으로 실패한다.

```text
API 미연결
≠
조회결과 0건
```

이 차이를 숨기지 않는 것이 QA/AX 관점에서 중요하다.

## 5. T09 WMS Truth Boundary

Receiving, Putaway, Counting은 FE scanner flow를 검증할 가치가 있지만, client-only state machine을 Production 업무 완료로 표현하면 안 된다.

v49에서는 세 화면을 다음처럼 분리했다.

```text
Demo Mode
→ scanner / error / quantity / completion FE 상태기계 검증

Normal Runtime
→ Integration Problem
→ 입력/완료 Action 차단
→ Server API 연결 전 성공표시 금지
```

공통 `wmsFrontendCapability.ts`는 `WMS_EXECUTION_API_NOT_CONNECTED` Problem을 생성한다. 문제 상세는 실제 WMS 완료가 Server validation, idempotency, audit 이후에만 확정돼야 함을 명시한다.

`KbxWmsMobilePage 1.7.0`의 `actionsVisible` 계약은 실행이 차단된 Production 화면에서 빈 sticky footer가 남지 않게 한다.

Receiving/Putaway/Counting은 hardcoded `online=true`를 제거하고 `useKbxNetworkState()`를 사용한다.

이 Demo-only guard는 첨부 표준에 동일한 구현 형태로 직접 규정된 것은 아니다. **Server 응답 전 성공 Feedback 금지, Client+Server idempotency, UI가 Domain truth를 대신하지 않는다는 지침을 실제 미연결 화면에 보수적으로 적용한 구현 판단**이다.

## 6. Theme

KBX Business Light/Dark semantic theme은 그대로 유지한다. v49에서는 새 palette를 만들지 않았다.

- Home Attention severity는 text/icon/border 의미를 유지한다.
- WMS Integration Problem은 Dark에서도 `integration` 의미와 다음 행동을 텍스트로 표현한다.
- Theme는 Permission, API 연결여부, WMS 성공상태를 결정하지 않는다.

Theme의 역할은 가독성과 의미 일관성이지 Business Truth가 아니다.

## 7. Browser Reference QA

Chromium Reference asset QA: **10/10 PASS**

- Home title
- Attention collapsed 8건
- Disclosure 존재 및 `aria-expanded=false`
- Mouse click으로 10건 전체 펼치기
- `aria-expanded=true`
- Keyboard Enter로 다시 8건 접기
- Dark theme root 적용
- 1280×720 document horizontal overflow 0
- runtime/page error 0

증적: `docs/evidence/v49-browser-workbench-theme.json`

Preview: `apps/web/fe-reference/previews/v49-home-attention-dark-1440x900.png`

Reference QA는 동일 HTML/CSS/JavaScript asset을 Chromium에 주입한 증적이다. 현재 환경의 package registry 제약 때문에 actual Vite/Vue/PrimeVue/AG Grid live runtime E2E라고 주장하지 않는다.

## 8. 다음 우선순위

1. network-enabled actual Vue install/typecheck/build
2. WMS-WORK-001 Demo/Production boundary actual runtime E2E
3. Receiving/Putaway/Counting 실제 Server Command + Idempotency + Audit 연결
4. WMS rejected scan / retry / network delay / duplicate scanner actual E2E
5. Home Attention 8→전체 disclosure actual Vue keyboard/forced-colors visual regression
6. T08 XLSX/Staging/Hangfire completion

새 T10/T11, 새 Dashboard framework, Runtime JSON UI는 이 항목보다 우선하지 않는다.
