# KBX FE QA Hardening v50

## 1. 30년 현장 QA/AX/UX 판단

v49는 `API 미연결 ≠ 0건`, `Client Demo 완료 ≠ WMS 업무 완료`를 명확하게 만들었다. 그러나 다시 실제 조작 관점에서 보면 두 종류의 **사실성 결함**이 남아 있었다.

1. 영구적인 API 미연결 오류가 `retryable:true`로 표시되어 사용자가 의미 없는 `[다시 조회]`를 반복할 수 있었다.
2. Home Attention이 최대 24건까지만 펼치면서 총 건수가 24건보다 큰 경우에도 `[전체 N개 보기]`라고 표현할 수 있었다. 화면이 실제로 보여주는 범위와 Label이 다르면 Home은 업무 판단의 Source가 될 수 없다.

v50은 새 Template, Dashboard, Theme Engine, Metadata Framework를 만들지 않고 **실제 FE가 보여주는 Action과 업무 사실을 일치시키는 것**에 집중한다.

## 2. Retry는 오류 장식이 아니라 복구 가능성 계약

`KbxTemplateStateBoundary 1.3.0`에 `errorRetryable` 계약을 추가했다.

```text
transient network error
→ errorRetryable = true
→ [다시 조회]

permission / configuration / API not connected
→ errorRetryable = false
→ 원인만 정확히 표시
→ 무의미한 Retry 없음
```

이 계약을 T01~T08 주요 Desktop Template과 T09 WMS Mobile Shell까지 전달한다.

- `KbxListPage 1.9.0`
- `KbxMasterPage 1.8.0`
- `KbxTransactionPage 1.8.0`
- `KbxFastEntryPage 1.9.0`
- `KbxMasterDetailPage 1.8.0`
- `KbxQueuePage 1.9.0`
- `KbxWorkQueuePage 1.6.0`
- `KbxReconcilePage 1.7.0`
- `KbxImportPage 1.6.0`
- `KbxWmsMobilePage 1.8.0`

Default는 기존 호환성을 위해 retryable이다. 업무 Slice가 표준 Problem의 `retryable:false`를 알고 있으면 Template에 전달해 Retry를 제거한다.

## 3. WMS-WORK-001: 무한 Retry 착시 제거

`WMS_WORK_QUERY_NOT_CONNECTED`는 네트워크 순간 장애가 아니다. 운영 API가 아직 연결되지 않은 구성 상태이므로 v49의 `retryable:true`는 잘못된 표현이었다.

v50:

```text
Production WMS Work API 미연결
→ integration problem
→ retryable:false
→ 빈 Queue로 가장하지 않음
→ 의미 없는 다시 조회도 표시하지 않음
```

`WMS-WORK-001` ScreenVersion은 `1.2.0`으로 올렸다.

실제 Server API가 연결된 이후에는 Network timeout/503처럼 복구 가능한 오류만 retryable로 분류하는 것이 맞다.

## 4. Home Attention: "전체"라는 단어도 업무 계약이다

Home은 기본 8개를 유지한다. 업무시스템 Home에 예외 수십 건을 한꺼번에 펼치면 정보 접근성이 오히려 떨어진다.

하지만 총 Attention이 24건보다 클 때:

```text
나쁜 표현
전체 38개 보기
→ 실제로 24개만 표시

v50
우선 24개 보기
→ 24개 표시
→ 남은 항목 존재 사실 유지
→ [작업 센터 전체] [알림 센터 전체]
```

즉 Home은 **우선순위 Workbench**이고 Runtime Center는 **전체 작업/알림 조회 Surface**라는 역할을 분리한다.

`KbxHomePage 1.10.0`은 다음을 지원한다.

- 기본 8개
- 총 건수 ≤ 24: `전체 N개 보기`
- 총 건수 > 24: `우선 24개 보기`
- 펼친 뒤에도 overflow가 있으면 `작업 센터 전체 / 알림 센터 전체`
- `aria-expanded / aria-controls`
- Center Panel Esc 종료 및 Focus Restore는 기존 Shell 계약 유지

## 5. Theme 적용

새 Palette는 추가하지 않았다. 기존 **KBX Business Light / Dark + Forced Colors** semantic theme를 그대로 사용한다.

v50에서 Theme가 지켜야 하는 것은 다음이다.

- Retry가 사라졌다고 Error가 사라진 것처럼 보이면 안 된다.
- `API 미연결`, `권한 없음`, `일시적 네트워크 오류`를 색 하나로만 구별하지 않는다.
- Home Attention overflow navigation은 Light/Dark에서 동일한 Label/Focus/Action을 가진다.
- Theme는 Permission, retryability, Domain state의 Source of Truth가 아니다.

## 6. Reference HTML/JavaScript

Reference Home도 실제 Vue 계약과 동일한 bounded disclosure를 사용한다.

QA를 위해 28개의 Attention fixture를 구성했다.

```text
초기
전체 28 / 8 표시
[우선 24개 보기]

확장
전체 28 / 24 표시
[상위 8개만 보기]
[작업 센터 전체]
[알림 센터 전체]
```

Reference의 추가 fixture는 Home overflow UX를 재현하기 위한 Browser fixture이며 Production 업무 데이터가 아니다.

## 7. Browser Reference QA

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

- Home boot
- 전체 28건 / 기본 8건
- truthful `우선 24개 보기`
- collapsed `aria-expanded=false`
- KBX Business Dark 전환
- 확장 24건
- expanded `aria-expanded=true`
- Work/Notification Center 전체 진입점 존재
- `전체 28개 · 24개 표시`
- Work Center open
- Header `aria-expanded=true`
- Esc close
- Focus 원래 Home button 복귀
- 1280×720 document horizontal overflow 0
- runtime/page error 0

증적: `docs/evidence/v50-browser-operational-truth.json`

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

## 8. QA 자동화 기술부채

v49 Validator가 `KbxHomePage 1.9.0`, `KbxQueuePage 1.8.0`, `KbxWmsMobilePage 1.7.0`을 정확한 문자열로 요구하고 있었다. 공통 컴포넌트를 정상 Minor Upgrade하면 과거 Gate가 실패하는 구조다.

v50에서는 v49가 보장하려던 의미를 보존하면서 **최소 SemVer 이상**을 검사하도록 변경했다. WMS ScreenVersion도 동일하게 `>= 1.1.0` 계약으로 변경했다.

과거 UI 구현을 고정하는 테스트가 아니라 최소 품질 계약을 고정하는 테스트가 되어야 한다.

## 9. 다음 우선순위

1. network-enabled actual Vue install/typecheck/build
2. actual Vue T06 `retryable:false` visual/keyboard E2E
3. Permission / not-connected / transient network problem matrix를 T01~T09 실제 API에 연결
4. Home overflow 실제 Vue Light/Dark/Forced Colors/200% Zoom regression
5. WMS Receiving/Putaway/Counting Server Command + Idempotency + Audit
6. T08 full-query XLSX / Staging / Hangfire

새 T10/T11이나 새 Theme Engine은 위 항목보다 우선하지 않는다.
