KArtSell.Aegis/docs/Design/kbx-foundation-v52-fe-operational-navigation-screen-anatomy/README.md

KBX Foundation v50 — FE Operational Truth · Retryability · Home Overflow · Theme Hardening

v50 핵심

• T01~T09 주요 Template에 errorRetryable 계약을 전파해 영구 오류에서 무의미한 [다시 조회] 제거
• KbxTemplateStateBoundary 1.3.0: transient error와 non-retryable error를 UI 계약으로 분리
• WMS-WORK-001 1.2.0: WMS_WORK_QUERY_NOT_CONNECTED를 retryable:false로 수정, API 미연결에 무한 Retry 착시 제거
• Home Attention: 기본 8개 유지, 총 건수 >24이면 전체가 아니라 우선 24개 보기로 정확히 표현
• 24개 이후 남은 Attention은 작업 센터 전체 / 알림 센터 전체로 직접 연결
• KbxHomePage 1.10.0, KbxQueuePage 1.9.0, 기타 T01~T09 Template 공개 Retry 계약 Minor Upgrade
• Reference HTML/JavaScript도 28개 fixture로 8→24 bounded disclosure와 Center navigation 재현
• KBX Business Light/Dark + Forced Colors semantic theme 유지, Theme는 Retry/Permission/Domain truth를 결정하지 않음
• Browser Reference QA 16/16 PASS, 전체 validate:kbx PASS, Design Debt 116 <= 131

상세: docs/frontend/KBX-FE-QA-Hardening-v50.md
검증: docs/validation-report-v50.md

---

KBX Foundation v49 — FE Workbench · WMS Truthful Boundary · Theme Hardening

v49 핵심

• Home 확인 필요가 상위 8개만 숨긴 채 끝나지 않도록 8개 ↔ 전체(최대 24개) 접근성 Disclosure 추가
• Home 우선업무 출처를 미저장/실패/중요알림/진행/알림으로 요약해 AX 판단량 감소
• KbxQueuePage 1.8.0: T06 Empty/Error/Retry copy와 Empty recovery Action 계약 추가
• WMS-WORK-001 1.1.0: Demo에서는 실제 필터 가능한 Queue, 일반 Runtime에서는 미연결 API를 0건으로 가장하지 않고 Integration Problem으로 fail-explicit
• Receiving/Putaway/Counting 1.1.0: client-only 성공 상태를 Production에서 차단하고 Demo Mode에서만 FE scanner state machine 검증
• KbxWmsMobilePage 1.7.0: Production execution 차단 시 빈 sticky action footer를 숨기는 actionsVisible 계약
• WMS 네트워크 표시를 useKbxNetworkState()로 통일하고 hardcoded online 제거
• Reference Home도 동일한 8→전체 Priority disclosure와 KBX Business Light/Dark semantic theme 적용
• Browser Reference QA 10/10 PASS: Attention disclosure, keyboard collapse, Dark theme, 1280×720 overflow 0, runtime error 0
• WMS에서 Server validation / Idempotency / Audit 이전의 성공표시는 금지한다는 경계를 FE Gate로 고정

상세: docs/frontend/KBX-FE-QA-Hardening-v49.md
검증: docs/validation-report-v49.md

---

KBX Foundation v48 — FE Template Completion · Real Search/File · Theme-safe Recovery Hardening

v48 핵심

• 실제 Vue T04/T06/T07/T08에 KbxProblemFeedback 기반 Actionable Problem Recovery 확장
• T04~T08 Template 계층의 problem / retry / dismiss 계약 통일
• KbxProblemFeedback 1.1.0: 상위 Validation Problem의 bounded summary 추가, Field/Cell Validation 역할은 유지
• Reference T05/T06/T07: Toast/표시 위주의 조회를 실제 검색 → Loading → 결과/Empty → 복구 상태 전이로 교체
• Chromium QA에서 발견한 Search Panel Mouse no-op 결함 수정: T05/T06/T07 [조회] click과 Enter/F3 동일 실행
• Reference T08: 샘플 파일명 주입 제거, 실제 Browser File input/Drop + .xlsx/.xls + 20MB guard
• T08 6단계(파일→매핑→검증→미리보기→반영→결과)와 CSS 6-column 정합화
• KBX Business Light/Dark semantic theme, Home/Workspace, Permission/Domain server-authority 경계 유지
• Browser Reference QA 30/30 PASS: T05~T08 completion loops, Dark theme, 1280px overflow 0, runtime error 0

상세: docs/frontend/KBX-FE-QA-Hardening-v48.md
검증: docs/validation-report-v48.md

---

KBX Foundation v47 — Actionable Problem Recovery · Theme-safe FE Hardening

v47 핵심

• 실제 T01/T02/T03에서 Command 실패를 조회 Error와 분리: business-rule / permission / not-found / integration / system 인라인 Problem Surface
• KbxProblemFeedback 1.0.0: 문제 유형 텍스트, 원인, 참조번호, retryable 재시도, 닫기
• Server problem.actions는 기본 미노출 + 명시적 allow-list만 렌더링하여 임의 Action ID → FE Command 실행 차단
• OMS-ORD-001 Bulk 출고, OMS-ORD-002 저장/확정, ERP-MST-ITEM-001 목록 로드/저장/사용중지 실패 시 현재 화면·선택·입력 Context 유지
• KbxListPage 1.8.0, KbxMasterPage 1.7.0, KbxTransactionPage 1.7.0
• Reference HTML/JavaScript: 예외 주문 출고지시 → 업무 규칙 인라인 오류 → 문제 주문만 선택 복구
• Browser Reference QA 12/12 PASS: Dark Theme, 문제표시/복구/닫기, 1280px overflow 0, runtime error 0
• 전체 Problem 계약에서도 Validation은 Field/Cell, Conflict는 최신값 비교, Command Problem은 인라인 복구로 역할 분리

상세: docs/frontend/KBX-FE-QA-Hardening-v47.md
검증: docs/validation-report-v47.md

---

KBX Foundation v46 — Safe Workspace Resume · T09 Recovery · Theme-preserving FE Hardening

v46 핵심

• 열린 Workspace의 clean 업무 위치만 sessionStorage에 복원, Query/Hash/Dirty Form·Grid 값은 저장 금지
• 복원 전 Permission + Screen Registry + Safe Route 재검증, resumed 상태는 실제 업무 진입 시 제거
• Home 바로 시작에서 복원 업무를 구분하고 미저장 편집은 안전상 복원 제외 사실만 표시
• Home에서 active tab이 없어도 첫 Workspace Tab을 keyboard roving entry로 제공
• Navigation Preference의 최초 localStorage read까지 fail-soft로 통일
• KbxWorkspaceTabs 1.3.0, KbxHomePage 1.8.0, KbxWmsMobilePage 1.6.0
• T09 WMS Picking: TanStack Query Loading/Error/Ready → 공통 Mobile State Boundary, 오류 [작업 다시 불러오기] 실제 refetch 연결
• Reference HTML/CSS/JavaScript Browser QA 20/20 PASS: clean resume, dirty exclusion, storage-blocked Shell, Dark Theme, 1280px overflow
• Theme/Permission/Domain 경계는 유지: Theme/Resume는 FE 표현·생산성 상태이며 업무 truth가 아님
• 전체 validate:kbx PASS: 153 tokens / 20 screens / 84 components / 69 catalog entries / 306 TS·Vue units / Design Debt 116 <= 131

상세: docs/frontend/KBX-FE-QA-Hardening-v46.md
검증: docs/validation-report-v46.md

---

KBX Foundation v45 — Safe Preference · Home Context · Theme Hardening

v45 핵심

• 실제 Vue OMS-ORD-001에 기본조건 저장 / 마지막 조회조건 기억을 연결하되 자유검색어는 localStorage 저장에서 제외
• Screen Preference key를 Tenant/User scope + ScreenId + ScreenVersion으로 격리하고 size/type 검증 + fail-soft 적용
• Home의 실패/진행 작업 클릭 시 Runtime Center 전체가 아니라 해당 Operation/Notification으로 Focus
• KbxSearchPanel 1.4.0, KbxOperationCenter 1.1.0, KbxNotificationCenter 1.1.0
• HTML/JavaScript Reference Lab에도 동일한 안전한 조회조건 기억과 Light/Dark Theme parity 적용
• Browser QA 14/14: 저장/복원, 자유검색어 비저장, Dark Theme, 1280 Home overflow, runtime error 0
• Domain Rule·Permission·Concurrency·Audit은 여전히 Server authority이며 Preference는 표현/생산성 상태에 한정

상세: docs/frontend/KBX-FE-QA-Hardening-v45.md
검증: docs/validation-report-v45.md

v44 핵심

• 실제 App artifact version v44-fe-theme-state로 정합화
• Header 작업/알림 trigger ↔ runtime panel aria-expanded/aria-controls 연결
• runtime panel: 명시 제목/닫기, Esc 닫기, open 시 panel focus, close 시 trigger focus restore
• route 전환/메뉴검색/Utility Rail 진입 시 non-modal runtime panel을 정리해 surface stacking 방지
• Windows Forced Colors에서 Light/Dark palette 대신 OS system color로 fail-safe
• Forced Colors에서도 현재 화면/선택/Focus를 색상 하나가 아니라 outline/텍스트 상태로 유지
• T01 Empty → [조회조건 초기화] → 즉시 재조회 공통 Recovery contract
• FE Reference Lab 작업/알림을 실제 Vue와 동일한 non-modal System Panel로 정렬
• FE Reference Lab에도 동일 high-contrast bridge 적용
• Browser matrix 28/28 PASS: T01~T09 Light/Dark, T01 Empty recovery, 1280px, Forced Colors, runtime error 0
• v44 전용 static QA gate를 전체 validate:kbx에 편입

상세: docs/frontend/KBX-FE-QA-Hardening-v44.md
검증: docs/validation-report-v44.md

---

KBX Foundation v43 — Semantic Theme · Home Navigation Hierarchy · Light/Dark FE Hardening

이번 iteration은 v42의 first-class Vue runtime 위에 KBX Business Light / Dark를 실제 업무 Semantic Theme으로 통합한다. Theme를 장식용 팔레트로 만들지 않고 surface / text / border / primary / success / warning / danger / focus / AI 의미 계약을 Application Shell, Home, PrimeVue, AG Grid, 공통 Component, FE Reference Lab까지 공유한다.

v43 핵심

• Design Token source 1.9.0: KBX Business Light / Dark semantic override 계약
• Theme runtime API + light|dark allow-list/fail-safe preference persistence
• Global Header에 명시적 Light/Dark 전환 + 접근성 label + narrow-header reflow
• PrimeVue dark selector와 KBX theme root 연결
• AG Grid Quartz foreground/background/accent/border/header/hover/selection을 KBX semantic token으로 연결
• Home: 확인 필요 → 바로 시작 → 모듈 업무의 시각 우선순위를 warning/danger/info semantic으로 강화하되 Dashboard card 증식 금지
• Side Navigation 현재 화면 primary inset marker
• Network/Dialog/Toast/Reference surface 하드코딩 감소
• FE Reference Lab Light/Dark parity + 실제 Dark inheritance 결함 발견/수정
• Theme Browser QA 16/16 PASS: T01~T09 Dark render, T09 WMS mobile mode, 1280px overflow 0, runtime error 0
• 전체 validate:kbx PASS / 305 TS·Vue script units / Design Debt 116 (ratchet 131 대비 감소)

v43에서 완료로 계산하지 않는 항목

첨부 표준은 Semantic Color/Density/Accessibility를 요구하지만 Light/Dark 자체를 명시적으로 강제하지 않는다. Dark는 사용자 요청에 따른 구현 확장이다. 또한 현재 실행환경은 package registry 접근이 차단되어 실제 Vite + PrimeVue + AG Grid live-runtime Theme E2E를 통과했다고 주장하지 않는다. Browser 증적은 실제 FE Reference HTML/CSS/JS asset 기준이며 production CSP는 별도 정적 Gate로 검증한다. Server-side full-query XLSX 역시 기존 잔여 P1이다.

상세: docs/frontend/KBX-FE-QA-Hardening-v43.md
검증: docs/validation-report-v43.md

---

KBX Foundation v42 — First-class Vue Runtime · Secure Demo Transport · Home Context · Excel Menu · Zoom Hardening

이번 iteration은 v41의 Golden Screen parity를 넘어 실제 FE 제품을 독립적으로 기동·빌드·검증할 수 있는 Runtime 경계를 우선 완성한다. BE 결합을 더 늘리지 않고 apps/web을 Vite 8 application으로 명시하고, Demo Mode도 별도 Mock UI가 아니라 실제 Axios/kbxApi 경계의 transport adapter로 구성했다.

v42 핵심

• apps/web first-class Vite 8 package / index.html / main.ts / App.vue / typecheck-build scripts
• Vue + Pinia + Router + TanStack Query + PrimeVue + installKbx() 실제 application bootstrap
• --mode demo에서만 fixture HTTP adapter 사용, 일반 runtime은 real transport + permission fail-closed
• Demo unknown operation은 성공 위장이 아니라 DEMO_OPERATION_UNSUPPORTED 명시 실패
• Home/Notification의 OMS 예외 Context를 useOrderSearch()가 allow-list로 hydrate하고 자동 조회
• KbxCommandBar ↔ KbxExcelMenu 실제 통합, Excel 5개 표준 진입점 + keyboard/focus contract
• 일부 row만 로드된 경우 local CSV를 전체 Export로 오인하지 않도록 다운로드 차단
• 56rem/40rem Shell pressure hardening: 200% Zoom에서 Workspace 우선 보존
• v42 runtime-readiness Gate를 전체 validate:kbx에 편입
• 304 TS/Vue syntax + 전체 Governance PASS / Design Debt 122 (ratchet 131 대비 감소)

v42에서 완료로 계산하지 않는 항목

현재 실행환경은 npm registry 접근이 차단되어 pnpm 의존성 설치가 불가능하다. 따라서 실제 Vite build/server와 Vue/PrimeVue/AG Grid Playwright를 통과했다고 주장하지 않는다. 또한 T01의 전체 검색조건 XLSX/Background Export API는 아직 미연결이며, 부분 row CSV는 전체 Export로 오인될 수 있어 의도적으로 차단한다.

상세: docs/frontend/KBX-FE-QA-Hardening-v42.md
검증: docs/validation-report-v42.md

---

KBX Foundation v41 — Actual Vue Golden Screen Parity · Controlled Grid Selection · Drawer/Dirty/Focus Hardening

이번 iteration은 v40의 FE Reference Lab을 더 확장하지 않고, 실제 Vue/PrimeVue/AG Grid Golden Screen이 동일한 업무 UX 계약을 지키는지를 우선 검수한다. 대상은 OMS-ORD-001, OMS-ORD-002, ERP-MST-ITEM-001, KbxDataGrid, KbxLookup, KbxUnsavedChangesDialog, Application Shell navigation이다.

v41 핵심

• OMS-ORD-001 주문번호 Link의 no-op 제거: 실제 Order Detail Drawer 연결
• 행 Double Click도 Drawer 우선으로 통일하여 List 조회 Context 보존
• Drawer async request sequence guard로 늦게 도착한 응답의 stale overwrite 방지
• KbxDataGrid: AG Grid 33+ multiRow selection contract, checkbox/header checkbox, 외부 Selection State ↔ 내부 Grid selection 동기화
• Grid error navigation이 Header/Form 오류를 Cell 오류로 잘못 세지 않도록 grid-scoped error 분리
• KbxDataGrid에 focusCell, focusNextEditableCell, selectRowByKey, clearSelection 제어 API 추가
• KbxLookup: 직접 코드 Enter 성공도 다음 Control로 Focus 이동, 선택/취소 Focus 정책 분리, 접근성 label 고유화
• ERP-MST-ITEM-001: Dirty 상태에서 다른 Master 선택/New 전환 시 3-way Guard로 편집값 덮어쓰기 방지
• OMS-ORD-002: F2 품목 선택 후 다음 Editable Cell Focus, New/Copy 내부 전환에도 Dirty Guard 적용
• KbxUnsavedChangesDialog: Esc/Tab/Shift+Tab Focus Trap + 닫힌 후 Focus Restore
• OMS 주문관리의 구현되지 않은 보류 no-op Command 제거
• Side Navigation 즐겨찾기 접근성 이름과 현재 화면 상태 보강
• Component version: KbxDataGrid 1.5.0 / KbxLookup 1.4.0 / UnsavedChangesDialog 1.1.0 / SideNavigation 1.3.1
• 전체 validate:kbx PASS / Design Debt 131 유지

v41에서 완료로 계산하지 않는 항목

현재 OMS 주문조회 엑셀 동작은 AG Grid CSV export 수준이다. KBX 표준의 Excel 메뉴 전체 계약(현재 조회결과 Excel, 양식, 업로드, 붙여넣기, 최근 업로드)은 아직 완료가 아니므로 잔여 P1로 유지한다. 또한 이 산출물에는 node_modules가 없어 실제 Vue runtime E2E/visual regression을 실행하지 못했다. 이번 v41 증적은 TypeScript/Vue syntax transpile + 전체 Foundation governance/static parity gate이며, 실제 앱 런타임 E2E는 다음 Gate다.

상세: docs/frontend/KBX-FE-QA-Hardening-v41.md
검증: docs/validation-report-v41.md

---

KBX Foundation v40 — FE Completion Loop · Validation-safe Shortcut · Master/Transaction/Queue/Reconcile Hardening

이번 iteration은 BE 구조나 새 Metadata Framework를 늘리지 않고, 실제 HTML/CSS/JavaScript FE에서 T01~T09의 최소 업무 완료 루프가 닫히는지를 기준으로 고도화한다. v39의 Navigation/Lookup/Drawer/Job/WMS 기반 위에서 T01 실제 검색, T02 Master CRUD, T03 Header+Detail 저장/확정, T06 Queue Action, T07 Reconcile Resolution을 실제 상태 전이로 연결했다.

v40 핵심

• T01 검색조건(판매채널/상태/키워드/예외) ↔ 실제 Grid 결과 결합
• T02 Master 신규/수정/복사/검증/F2 Lookup/저장/상태/Dirty 전환
• T03 Header+Detail 입력/계산/Validation/F8 저장/작성→확정
• T06 선택 기반 작업자 배정/Wave 생성 실제 Row 갱신
• T07 선택 기반 재처리 후 Expected/Actual/Difference 및 mismatch 목록 갱신
• Global F8이 실제 화면 Save Handler를 호출하도록 수정 — Validation 우회 제거
• Hash/Refresh/Close까지 Dirty 보호 확대
• Browser QA 49/49 PASS, Runtime Error 0
• 1280×720 document overflow 0, WMS 390×844 Full View
• Design Debt ratchet 131 유지

상세: docs/frontend/KBX-FE-QA-Hardening-v40.md
검증: docs/validation-report-v40.md

---

KBX Foundation v39 — FE Product Parity · Lookup · Dirty Navigation · Job/WMS Hardening

이번 iteration은 BE 구조를 늘리지 않고 실제 HTML/CSS/JavaScript와 핵심 Vue Component의 사용성을 고도화한다. v38의 상태전이 기반 위에 Context-aware Home, 화면 이동 Dirty Guard, 실제 F2 Lookup, Utility Drawer, T08 Background Job UX, T09 Mobile Full View/중복 Scan Guard를 추가했다.

v39 핵심

• Home 예외 → 실제 대상 필터/Context 적용 후 이동
• Dirty 상태에서 Tab Close뿐 아니라 Side Nav/Home/다른 Tab 이동도 3-way Guard
• T02/T03 F2 Lookup: Search/Arrow/Enter/Esc/Focus Next
• 실제 KbxLookup.vue: 선택 후 다음 Control, 취소 시 Trigger Focus 복원
• Help/AI/Suggestion/Job/Notification 실제 Drawer + inert/Focus Trap
• T08 6단계 + Background Progress + 화면 이탈/복귀
• T09 중복 Barcode Guard + Network Failure No-Commit UX
• 767px 이하 WMS Mobile Full View
• 1280×720 및 720px zoom-pressure document overflow 없음
• Browser QA 31/31 PASS · Runtime Error 0
• Design Debt ratchet 131 유지

상세: docs/frontend/KBX-FE-QA-Hardening-v39.md

---

KBX Foundation v38 — FE QA Hardening · Interaction-complete Reference Lab

이 패키지는 기존 v36 Foundation 거버넌스를 유지하면서 v37 FE Reference Lab을 실제 상태 전이·복구·키보드·보안 실패 격리 기준으로 고도화한 v38 작업본이다. 이번 iteration은 BE 구조를 확장하지 않고 실제 HTML/CSS/JavaScript FE 완성도에 집중한다.

v38 핵심

• Home: 예외 우선 → 이어서 처리 → 모듈별 업무 → Ctrl+K 검색
• T01: Quick Filter/전체선택/Bulk/Drawer/Data State/선택 기반 Command disable
• T02: Master→Detail 실제 전환 + Dirty 보호
• T03: Header/Detail edit + Enter 흐름 + Dirty/Save
• T04: Fast Entry input + TSV paste + Add/Duplicate/Fill Down + error gate
• T05: 품목→Location→재고이력 동시 문맥 갱신
• T06/T07: Queue/불일치 필터 실제 적용
• T08: 파일 gate + 이전/다음 + Mapping/Validation/Commit/Result
• T09: keyboard-wedge Scan + wrong barcode recovery + quantity/exception dialog
• CSP + dynamic HTML escape + localStorage fail-soft + prompt/eval/document.write 금지
• Headless Chromium interaction evidence 및 1440×900/390px 화면 증적
• Design Debt ratchet 131 유지

v38 검증

node scripts/validate-fe-reference.mjs
node scripts/validate-kbx.mjs

상세: docs/frontend/KBX-FE-QA-Hardening-v38.md

---

KBX Foundation v36 — Recipe Verification · Generated Test Plan · Deterministic Home Workbench

KBX v36는 v35의 Screen Recipe / Secure Scaffolder 기반을 실제 검증계약까지 닫는 Foundation iteration이다. 목표는 화면·컴포넌트 수를 더 늘리는 것이 아니라, T01~T09를 선택한 순간부터 표준 UX, 보안, 복구, 테스트 증적이 함께 따라오도록 만드는 것이다.

v36 핵심

• T01~T09 testProfile 추가
  • 필수 Scenario Kind
  • 필수 Behavioral Tag
  • 필수 Evidence
  • 필수 Recovery/Interaction Check
• generated/screen-recipe-verification-manifest.json 추가
• T01~T09 Recipe Verification 9/9 자동 폐쇄성
• 각 Recipe는 실제 해당 Template을 사용하는 Screen의 Canonical E2E Scenario를 최소 1개 요구
• T02 Master / T06 Queue / T07 Reconcile Canonical E2E Recovery Scenario 추가
• Scaffolder가 신규 Vertical Slice에 *.test-plan.ts 자동 생성
• 생성 Test Plan은 Canonical Scenario / Required Check / Required Evidence를 타입 계약으로 보존
• 기존 Master / Transaction / Fast Entry의 명시적 --write-permission fail-closed 정책 유지
• Home Attention Queue를 동일 우선순위 내 최신 발생 순으로 정렬
• Home은 표시 상한과 별개로 권한 필터 후 실제 전체 건수 및 overflow를 정확히 표시
• buildKbxHomeAttentionQueue() public API 추가, 기존 buildKbxHomeAttention() 호환 유지
• Screen Recipe testProfile / canonicalScenarioIds 변경을 Release Impact에서 추적
• Design Debt ratchet 131 유지

검증

node scripts/validate-kbx.mjs

최종 검증 기준:

• 299 TS/Vue script units
• 20 Screen Definitions
• 84 Component Definitions
• 66 Component Catalog entries
• 153 Design Tokens
• 9 Screen Recipes
• 30 Canonical Test Scenarios
• Recipe Verification 9/9
• 16 Navigation Entries
• Design Debt 131 <= 131
• Release Impact major / major

문서

• docs/screen-recipe-verification-home-attention-v36.md
• docs/kbx-v36-standard-traceability.md
• docs/validation-report-v36.md
• docs/release/migration-guide.md

FE Reference Lab (v37)

Backend 없이 실제 브라우저에서 Application Shell, 홈 네비게이션과 T01~T09를 검증하려면 apps/web/fe-reference/를 사용한다.

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

FE 정적 계약 검증:

pnpm validate:fe-reference

상세 설계 기록: docs/frontend/KBX-FE-Completion-v37.md