KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/frontend/KBX-FE-QA-Hardening-v40.md

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 종류를 더 늘리지 않는다.