# KBX FE QA Hardening v40

## 1. 결론

v39는 Dirty Navigation, F2 Lookup, Utility Drawer, T08 Background Job, WMS Scanner/Network Guard를 실제 FE 상호작용으로 올렸다. 그러나 30년 현장 QA 관점에서 다시 보면 **"화면에 기능이 있다"와 "업무 완료 루프가 닫힌다"는 여전히 다른 문제**였다.

v39의 잔여 결함은 다음과 같았다.

1. T01 검색조건이 일부 Quick Filter 중심이라 실제 검색 입력과 결과의 결합이 부족했다.
2. T02 Master CRUD가 선택/조회 위주이고 신규·복사·검증·저장·Dirty 전환의 실체가 약했다.
3. T03 Transaction이 입력 화면처럼 보이지만 Header/Detail 계산·검증·저장·확정의 실제 상태 전이가 충분하지 않았다.
4. T06 Work Queue와 T07 Reconcile의 주요 업무 Action이 결과 데이터를 바꾸지 않는 데모 성격이 남아 있었다.
5. 전역 F8이 화면별 저장/검증 Handler를 우회해 Dirty만 해제할 수 있는 경로가 있었다. 이는 **거짓 저장 성공 인식**을 만들 수 있는 P0 결함이다.
6. SPA 내부 Dirty Guard는 강화됐지만 browser back/refresh/close까지 동일한 데이터 유실 방어가 필요했다.

v40은 새 Framework나 BE 결합을 늘리지 않고 위 결함을 **실제 HTML/CSS/JavaScript 상태 전이**로 닫는다.

---

## 2. v40 완료 기준

Template별 최소 업무 완료 루프를 다음처럼 강제한다.

- T01 Search/List: `조건 → 조회 → 결과 → 선택 → 처리`
- T02 Master CRUD: `목록선택/신규 → 편집 → 검증 → 저장 → 다른 Master 전환`
- T03 Header+Detail: `Header/Line 입력 → 계산 → 검증 → 저장 → 상태전이`
- T04 Fast Entry: `입력/Paste → Validation → 오류해결 → 저장`
- T05 Master/Detail: `Master 선택 → Detail Context 갱신 → 근거 Drill-down`
- T06 Work Queue: `Queue 필터 → 대상선택 → 업무 Action → 결과`
- T07 Reconcile: `불일치 필터 → 대상선택 → Resolution → 재계산 결과`
- T08 Import: `파일 → 매핑 → 검증 → 미리보기 → Job 반영 → 결과`
- T09 WMS Mobile: `Scan → Validation → Feedback → 수량/예외 → 다음 업무`

버튼이 존재하는 것만으로는 완료로 보지 않는다. **업무 상태가 실제로 바뀌고 실패 시 복구 가능해야 한다.**

---

## 3. P0/P1 개선

### P0 — F8 Validation Bypass 제거

기존 위험:

- Global F8
- 화면별 Validation/Save Handler 우회
- Dirty 상태만 해제 가능
- 사용자는 저장되었다고 오인

v40:

- T02 F8 → `#masterSave` 실제 저장 루프
- T03 F8 → `#saveTransaction` 실제 저장 루프
- T04 F8 → `#fastSave` 실제 Validation Gate
- `저장 후 이동/닫기`도 동일 `trySaveDirtyScreen()`을 사용

즉 Keyboard Shortcut은 편의 기능일 뿐 **업무 검증을 우회하는 별도 저장 경로가 아니다.**

### P0 — Browser-level Dirty Guard

SPA Navigation Guard에 더해:

- hash route 변경
- browser back/forward 계열 route change
- refresh
- tab/window close

에서도 Dirty state를 보호한다.

Preference나 URL 상태보다 사용자의 미저장 업무가 우선한다.

### P1 — T01 실제 검색 결합

검색 Panel의 다음 값이 실제 결과 필터에 연결된다.

- 판매채널
- 상태
- 통합검색
- 상세조건의 예외유형
- 기존 Quick Filter

Loading 후 재렌더링되어도 입력값이 유지된다. Reset은 UI 값과 상태 모델을 함께 초기화한다.

### P1 — T02 Master CRUD Completion Loop

추가된 실제 상태:

- `masterDraft`
- `new / edit` mode
- Master 목록 검색
- 필수값 검증
- 신규 ItemCode 중복 검증
- F2 Warehouse Lookup 반영
- 신규 저장
- 기존 수정 저장
- 복사 시 Identity/Barcode 제외
- 사용중지/사용재개 상태 변경
- Dirty 상태에서 다른 Master 선택 시 3-way Guard

Master Detail 화면은 이제 단순 "목록 옆 Form"이 아니라 편집 업무 루프를 검증할 수 있다.

### P1 — T03 Transaction Completion Loop

Header와 Line을 실제 state로 관리한다.

- 주문일
- 거래처 Lookup
- 출고창고 Lookup
- 수취인/연락처/주소
- 품목코드
- 수량
- 단가
- 비고
- 수량×단가 계산
- 총수량/총금액 Summary

Validation 실패 시 저장하지 않고 Summary에서 문제 위치로 Focus할 수 있다. 저장 후에만 Dirty가 해제된다. `확정`은 Dirty/Validation 상태를 통과해야 하고 `작성 → 확정` 상태전이를 실제 표시한다.

### P1 — T06 Queue Action 실체화

- 행 Selection state
- 현재 결과 Select All
- Selection 기반 Command enable/disable
- 작업자 배정 → 선택 Row의 작업자 실제 변경
- Wave 생성 → 대상 Row의 Wave 실제 변경
- 결과 Feedback + Close

Queue는 Dashboard 숫자가 아니라 **지금 처리할 작업을 선택하고 결과를 확인하는 화면**이어야 한다.

### P1 — T07 Reconcile Resolution 실체화

- mismatch-only 실제 필터
- 행 Selection
- Selection 기반 재처리
- 재처리 시 `Actual = Expected`
- `Difference = 0`
- 원인/상태를 `재처리 완료 / 해결`로 갱신
- 처리 후 mismatch-only 목록에서 해결 Row 제거

비교값만 보여주고 사용자가 다른 화면에서 해결하게 만들지 않는다.

---

## 4. 보안/안정성 판단

### FE는 보안 경계가 아니다

v40 Reference Lab의 disabled/validation/guard는 오조작을 줄이는 UX다. 다음은 여전히 Server 최종 책임이다.

- Permission Enforcement
- 업무 상태 전이 검증
- 재고 정합성
- Optimistic Concurrency
- Idempotency
- Audit
- DB Constraint
- Outbox/Inbox

FE가 상태를 바꿨다고 실제 Domain Transaction이 승인됐다고 간주하지 않는다.

### Reference Lab이 의도적으로 하지 않는 것

- 실제 DB Commit
- 실제 Hangfire 실행
- 실제 Permission API
- 실제 Audit Write
- 실제 외부 API 연계

Reference Lab의 목적은 **FE 사용 계약, 상태 표현, 실패 복구, 키보드/Focus, Navigation 품질을 BE 없이 재현**하는 것이다.

---

## 5. 브라우저 QA 증적

`apps/web/fe-reference/previews/browser-interaction-v40.json`

**49 / 49 PASS**, runtime console/page error 0.

주요 검증:

- Home actionable attention
- Ctrl+K 메뉴 검색 / Enter 화면 이동
- Side Nav collapse
- Compact/Comfortable density
- Utility Drawer inert / Focus Trap / Esc Restore
- T01 판매채널 + keyword 실제 결과 필터
- T01 Loading 재렌더 후 검색값 보존
- T01 Selection 기반 출고지시 enable
- T01 Reset 실제 조건 초기화
- T02 blank 신규 상태에서 F8 Validation 발생
- T02 F2 Lookup → Enter → 다음 Control Focus
- T02 신규 저장 후 Master 목록 반영
- T02 Dirty Master 전환 Guard
- T03 invalid quantity 저장 차단
- T03 수정 후 F8 저장
- T03 저장 후 확정 상태전이
- T04 오류 Cell 존재 시 저장 차단 / 해결 후 저장
- T05 Master 선택 시 Detail Context 변경
- T06 Selection → 작업자 배정 → Row 상태 변경
- T07 Selection → 재처리 → mismatch 2 → 1
- Dirty 상태에서 hash route 변경 차단 및 discard 후 이동
- T08 Job 진행 중 화면 이탈/복귀 및 완료
- T09 동일 Barcode 중복 입력 미반영
- T09 잘못된 Barcode actionable error
- T09 390px viewport Full View
- 1280×720 document horizontal overflow = 0

### 실행환경 제한

현재 실행환경은 Chromium의 `file://` 및 localhost 직접 navigation이 관리 정책으로 차단된다. 따라서 Browser QA는 **운영과 동일한 DOM/CSS/JavaScript를 사용하고 CSS/JS asset만 inline한 Playwright harness**에서 수행했다.

- 상호작용 코드: 동일
- DOM: 동일
- CSS: 동일
- production CSP meta: harness에서는 navigation 제약 때문에 제거
- CSP/외부 script/object/base/frame 정책: `validate:fe-reference` 정적 Gate로 별도 검증

이 제한을 browser-native CSP E2E를 통과한 것으로 과장하지 않는다.

---

## 6. 30년 현장 QA 관점의 냉정한 판단

### 1. "컴포넌트 존재"를 완료율로 계산하면 안 된다

실무에서 사고를 만드는 것은 빠진 버튼보다 **동작하는 것처럼 보이는 버튼**이다. T06/T07처럼 Action이 Toast만 띄우면 사용자는 처리됐다고 오인할 수 있다.

완료 기준은 `clickable`이 아니라 `state transition + feedback + recovery`다.

### 2. Keyboard Shortcut은 가장 위험한 우회 경로가 될 수 있다

마우스 Save는 Validation을 거치는데 F8은 Dirty만 해제한다면, 숙련 사용자가 오히려 더 위험하다. ERP에서 Keyboard 생산성과 데이터 정합성은 함께 설계해야 한다.

### 3. Home은 숫자판이 아니라 업무 Context Router여야 한다

홈에서 예외 숫자를 보고 다시 메뉴를 열고 필터를 선택하게 만들면 홈은 업무를 줄이지 못한다. 홈 클릭 한 번으로 **대상 화면 + 대상 Context**까지 전달되어야 한다.

### 4. Template 완성도는 Happy Path보다 Recovery에서 갈린다

운영 화면은 다음 질문으로 봐야 한다.

- 잘못 입력하면 어디에서 고칠 수 있는가?
- 저장 실패해도 입력이 남아 있는가?
- 다른 화면으로 이동하다 데이터가 사라지지 않는가?
- 처리 결과가 실제 Row 상태와 일치하는가?
- 화면을 다시 열어도 사용자가 무엇을 했는지 이해할 수 있는가?

### 5. 지금 새 Meta Framework를 만드는 것은 기술부채다

현재 가장 중요한 미완성은 새로운 Template 종류가 아니다. **Reference FE와 실제 Vue/PrimeVue/AG Grid Golden Screen의 동작 일치**다.

이 단계에서 Runtime JSON UI Engine, Low-code Builder, 자체 Grid Engine을 추가하면 다시 BE/Framework 완성도만 올라가고 실제 FE 품질은 뒤처질 가능성이 높다.

---

## 7. 다음 Gate

v41 우선순위는 다음으로 제한한다.

1. 실제 Vue `OMS-ORD-001`과 FE Reference T01의 Interaction parity
2. 실제 Vue `OMS-ORD-002`의 Form + F2 + Enter + F8 E2E
3. 실제 AG Grid `KbxDataGrid` multi-cell paste / validation navigation / selection contract
4. actual Vue Loading/Empty/Error/Conflict/Permission 상태 Browser E2E
5. 200% browser zoom + keyboard-only + label/focus accessibility gate
6. WMS `offline/unstable → online` pending command recovery
7. T08 Refresh 이후 Job 복구 — 이 시점부터 실제 Read API와 결합

그 전에는 Template/Component 종류를 더 늘리지 않는다.
