# KBX FE Reference Lab v50

Backend/API 없이 브라우저에서 즉시 실행하는 KBX 업무 UI 원형이다. 목적은 별도 Demo UI를 만드는 것이 아니라 **T01~T09의 실제 HTML/CSS/JavaScript 상호작용, Theme State, Keyboard, Recovery, WMS Mobile**을 빠르게 재현하는 것이다.

## 실행

```bash
cd apps/web/fe-reference
python3 -m http.server 4173
```

운영 Domain을 흉내 내는 제품이 아니다. Permission, Domain Validation, DB Commit, Audit, Concurrency, Idempotency는 Server 최종 책임이다.

## v50 Operational Truth / Home Overflow QA

- Home Attention 기본 8개, 최대 priority surface 24개
- 총 건수 >24이면 `전체 보기`라고 과장하지 않고 `우선 24개 보기`
- 남은 항목은 `작업 센터 전체 / 알림 센터 전체`로 이동
- Work Center open → Esc close → Home trigger Focus restore
- KBX Business Light/Dark에서 동일한 Label/Action/Focus 유지
- 실제 Template 코드의 non-retryable error는 `[다시 시도]`를 숨기는 공통 계약을 사용
- 증적: `docs/evidence/v50-browser-operational-truth.json` (16/16)
- Preview: `previews/v50-home-overflow-dark-1440x900.png`


## v46 검증 범위

- KBX Business Light / Dark + Forced Colors 의미 체계 유지
- clean Workspace 위치만 `sessionStorage`에 복원
- Query/Hash/Dirty Form·Grid 값은 session snapshot에서 제외
- 복원 tab `↺` + Home `복원` 표시, 실제 진입 시 resumed marker 제거
- Home/no-active-tab 상태에서도 첫 Workspace Tab keyboard entry 보장
- Storage API 차단 시 Preference/Resume 없이 fail-soft 기동
- T09 WMS common state boundary의 Error → `[작업 다시 불러오기]` recovery loop
- Browser Reference QA 20/20: clean resume, dirty exclusion, Dark Theme, 1280px overflow, runtime error 0

## v44 검증 범위

- KBX Business Light / Dark semantic theme
- Windows Forced Colors system-color fallback
- Home: 확인 필요 → 바로 시작 → 모듈별 업무
- Header: 작업/알림 **비모달 System Panel**, Esc, Focus Restore
- Help/AI/Suggestion/Detail: Drawer contract 유지
- T01: 검색 → Loading/Empty/Error/Ready → 선택/Bulk/Drawer → Empty 복구
- T02: Master CRUD + Dirty Guard + Lookup
- T03: Header/Detail + Validation-safe F8
- T04: Fast Entry/Paste/Fill Down
- T05: Master→Location→재고이력
- T06: Actionable Queue
- T07: Reconcile/Resolution
- T08: Excel Import + Background Job
- T09: 390×844 WMS Mobile + Scanner/Network/Duplicate Guard

## Theme 원칙

Light/Dark는 표현 모드이며 업무 상태나 Permission의 Source of Truth가 아니다. Forced Colors가 활성화되면 OS `Canvas`, `CanvasText`, `Highlight`, `LinkText`를 우선한다. Theme 변경으로 Layout/Density/Keyboard 문법을 변경하지 않는다.

## QA 증적

- `previews/v44-home-light-1440x900.png`
- `previews/v44-home-dark-1440x900.png`
- `previews/v44-runtime-panel-dark-1440x900.png`
- `previews/v44-t01-dark-1440x900.png`
- `previews/v44-t01-forced-colors-1440x900.png`
- `previews/v44-t09-dark-390x844.png`
- `docs/evidence/v44-theme-state-browser.json` — 14/14
- `docs/evidence/v44-browser-matrix.json` — 28/28

실행환경의 localhost/file navigation 제약 때문에 Browser QA는 동일 HTML/CSS/JS asset을 Playwright inline harness로 실행했다. 실제 Vue/Vite/PrimeVue/AG Grid runtime E2E와 혼동하지 않는다.

## 검증

```bash
node scripts/validate-fe-reference.mjs
node scripts/validate-fe-state-navigation-v44.mjs
node scripts/validate-kbx.mjs
```


## v45 Safe Preference QA

- T01 `기본조건 저장`, `마지막 조회조건 기억` 실제 JavaScript 동작
- 판매채널/상태/오류유형만 저장하고 자유검색어는 저장하지 않음
- 저장값 allow-list 복원, 잘못된 값은 기본값으로 복구
- Light/Dark Theme와 개인화 UI 동시 검증
- 증적: `docs/evidence/v45-browser-preference-theme.json` (14/14)

## v46 Safe Workspace Resume QA

- clean Workspace tab만 `sessionStorage` 복원
- Query/Hash, Dirty Form/Grid 값은 복원 snapshot에서 제외
- Home `바로 시작`에 `복원` 상태 표시
- active tab이 없는 Home에서도 첫 Workspace tab `tabindex=0`
- Storage API 차단 시 Home/Shell fail-soft
- KBX Business Light/Dark와 resume marker semantic parity
- 증적: `docs/evidence/v46-browser-resume-theme.json` (20/20)
- Preview: `previews/v46-home-resume-dark-1440x900.png`


## v47 Actionable Problem

T01에서 예외 주문을 선택해 출고지시하면 업무규칙 Problem을 인라인으로 표시하고 `문제 N건만 선택`으로 복구한다. 단순 성공 Toast로 거짓 완료시키지 않는다. Light/Dark는 동일 semantic state를 사용한다.

## v48 Template Completion QA

- T05 재고현황: 실제 창고/품목 검색, Loading, Empty, 조건 초기화, Master→Location→History
- T06 작업 Queue: 실제 작업자/통합검색/빠른필터, Selection, Empty Recovery
- T07 Reconcile: 실제 검색/불일치 필터, Selection, Reference 재처리 상태변경
- T08 Excel Import: 실제 Browser File input/Drop, `.xlsx/.xls`/20MB guard, 6-step visual flow
- Search Panel의 조회 버튼은 Enter/F3뿐 아니라 Mouse click도 동일 실행 경로를 사용한다.
- KBX Business Light/Dark semantic theme는 동일 업무 상태와 조작 계약을 유지한다.
- Browser 증적: `docs/evidence/v48-browser-template-completion.json` (30/30)
- Preview: `previews/v48-t05-inventory-dark-1440x900.png`, `previews/v48-t08-file-dark-1440x900.png`