KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/frontend/KBX-FE-Work-Surface-Triage-Hardening-v54.md

KBX FE Work Surface Triage & Wayfinding Hardening v54

1. 판단

v53까지 KBX는 Home module rail, 표준 Section Header, Golden Screen interaction, fail-closed workflow를 상당히 확보했다. 그러나 실제 업무 FE 관점에서는 여전히 세 가지 간극이 남았다.

첫째, Home의 확인 필요가 시간순 flat queue 성격을 유지하면 실패·미저장·장시간 Job·일반 알림이 같은 시각 우선순위로 경쟁한다. 사용자는 “무엇부터 처리해야 하는가”를 다시 판단해야 한다.

둘째, T02 목록-상세는 목록과 Form을 동시에 보여주지만 현재 레코드가 조회 결과의 몇 번째인지, 이전/다음으로 연속 검토할 수 있는지가 표준 계약이 아니었다. 마우스로 목록을 다시 찾는 왕복은 Master CRUD 현장에서 매우 자주 발생하는 낭비다.

셋째, T04/T05는 Template 골격은 있었으나 이 Grid가 무엇을 입력하는가, 현재 몇 건인가, 이 Pane이 어떤 Context인가, Pane-level Action은 어디에 있는가가 화면별 구현에 의존했다. Template이 배치만 표준화하고 work surface 자체를 충분히 설명하지 못한 상태였다.

따라서 v54는 새 Metadata Engine이나 BE 추상화를 추가하지 않고 Home triage, record wayfinding, workflow next-action, T04/T05 work-surface anatomy를 실제 Vue/HTML/JavaScript에 보강한다.

2. Home — flat attention queue를 operational triage로 변경

Home의 Attention truth는 기존 allAttentionQueue를 그대로 source of truth로 사용한다. 새로운 별도 집계 저장소를 만들지 않는다.

표현만 다음 네 lane으로 분류한다.

• 긴급·예외: 실패 작업 + 긴급 알림
• 미저장: 중단한 편집
• 진행 작업: Batch/Integration 작업
• 알림: 일반 Notification

Collapsed 상태에서는 lane당 상위 2건, expanded 상태에서는 lane당 상위 6건을 보여준다. 이렇게 하면 한 종류의 알림이 많아도 다른 종류의 중요한 업무가 첫 화면에서 밀려나지 않는다.

중요한 routing 보정도 했다. 긴급·예외는 실패 작업과 긴급 알림이 혼합될 수 있으므로 overflow를 알림센터로 단정하지 않는다. 먼저 lane을 확장해 원래 source와 intent를 유지한다. 진행 작업은 작업센터, 알림은 알림센터로 연결한다.

Card dashboard, 차트, KPI 장식을 늘리지 않았다. Home은 업무 시작점이며 목적은 판단량을 줄이는 것이다.

3. T02 — KbxRecordNavigator

KbxRecordNavigator를 신규 Business Component로 추가했다.

표준 기능:

• 현재 레코드 위치 current / total
• 이전 / 다음
• 첫/마지막 경계 disabled
• dirty 상태에서 이동 disabled
• focus-visible
• forced-colors
• 모바일 폭에서는 button text를 줄이고 기능은 유지

실제 ERP-MST-ITEM-001에 적용했다. 핵심은 Navigator가 직접 selection state를 바꾸지 않는 것이다. 기존 requestChoose() 경로를 재사용하므로 미저장 변경 확인/보호 로직을 우회하지 않는다.

이 구조는 UX Component가 Domain/dirty safety를 침범하지 않으면서 반복 탐색 조작을 줄인다.

4. Workflow — 현재 상태만이 아니라 다음 작업까지 명시

KbxWorkflowBar 1.2.0은 다음을 동시에 보여준다.

• 현재 상태
• 상태 흐름
• 현재 위치 n / total
• 다음 가능한 Action label
• 실제 실행 Action

가능한 Action이 없을 때 빈 공간을 보여주지 않고 현재 상태에서 실행 가능한 다음 작업이 없습니다.를 표시한다.

상태 흐름의 현재 항목에는 aria-current="step"을 적용했다. Theme accent는 현재 단계 식별용이며 success/warning/error semantic color를 대체하지 않는다.

5. T04 — Fast Entry를 “Grid 슬롯”이 아니라 작업면으로 승격

KbxFastEntryPage 1.10.0에 다음 계약을 추가했다.

• gridTitle
• gridDescription
• rowCount
• rowCountUnit
• grid-heading
• grid-actions

화면 구조는 Keyboard Guide → Context → Bulk/Contextual → Named Fast Entry Surface → Validation → Sticky Summary로 고정한다.

실제 품목단가 화면은 품목 단가 입력, 입력 건수, 오류 건수를 Grid 상단에서 즉시 확인할 수 있다. 오류 수는 별도 dashboard card가 아니라 작업 Grid 바로 옆에 둔다.

6. T05 — Master / Detail / History의 목적과 규모를 표시

KbxMasterDetailPage 1.9.0에 Master/Detail/Bottom 각각의 title/description/count/countUnit과 action slot을 추가했다.

• master-actions
• detail-actions
• bottom-actions

실제 ERP 재고현황은 다음처럼 읽힌다.

• Master: 품목 — 조회된 품목 수
• Detail: 창고/로케이션 — 선택 품목의 위치 수
• Bottom: 재고이력 — 선택 품목의 이력 수

기존 Grid를 바꾸지 않고 Context 이해를 높였다. 데이터는 기존 Query projection을 그대로 사용하므로 별도 client-side truth를 만들지 않는다.

7. Static HTML / JavaScript parity

apps/web/fe-reference도 v54로 함께 변경했다.

• Home 4-lane triage
• lane overflow routing
• T02 record navigator
• dirty 상태의 이전/다음 차단
• T04 named fast-entry surface
• keyboard module rail 유지
• focus/high-contrast cue

Vue에만 좋아진 UX를 넣고 Reference HTML/JavaScript가 낡는 구조를 허용하지 않았다.

정적 Reference CSP는 기존 보안 경계를 유지한다.

• connect-src 'self'
• object-src 'none'
• frame-src 'none'
• worker-src 'none'
• frame-ancestors 'none'
• base-uri 'none'

새 Home/Navigation 기능을 위해 외부 script, inline script, 임의 network origin을 열지 않았다.

8. 회귀에서 발견하고 바로잡은 문제

8.1 긴급 overflow 오라우팅

초기 구현에서는 긴급·예외의 나머지 항목을 알림센터로 보냈다. 그러나 lane에는 operation failure도 들어갈 수 있으므로 잘못된 라우팅이었다. v54에서는 긴급 lane을 먼저 확장하도록 수정했다.

8.2 Theme v43 gate 회귀

신규 triage가 border-top과 background로 구분되면서 과거 v43 gate의 색 이외의 priority cue 계약을 만족하지 못했다. 기준을 완화하지 않고 각 triage item에 accent left border를 복원했고, critical item은 danger border로 식별하도록 수정했다.

8.3 정적 theme 변수

신규 Reference CSS가 기존 forced-colors 구간에서만 존재하는 --surface-hover와 정의되지 않은 --focus에 의존할 수 있는 문제를 제거했다. 실제 기본 theme에 존재하는 --muted, --primary를 사용한다.

9. 검증 결과

최종 node scripts/validate-kbx.mjs 결과:

• Design tokens: 161
• Screens: 20
• Components: 86
• Core APIs: 34
• Navigation entries: 16
• T01~T09 recipe verification: 9/9
• TypeScript/Vue syntax units: 309
• Design Debt: 116 <= 131
• Design-Code Parity: PASS
• Release Governance: major PASS
• v41~v54 FE regression: PASS

v54 전용 gate는 Home triage, T02 record navigation, Workflow next action, T04/T05 work-surface anatomy, static FE parity, CSP/high-contrast를 검사한다.

10. 아직 완료라고 부르면 안 되는 부분

현재 root에는 pnpm과 node_modules가 없다. 따라서 Vite production build, Vitest, Playwright browser E2E까지 PASS했다고 주장하지 않는다.

Chromium 자체는 설치돼 있어 static reference screenshot을 시도했지만 container DBus/zygote 환경에서 headless process가 종료되지 않아 timeout되었다. 이 결과는 시각 QA 증거로 채택하지 않았다.

즉 현재 증거는 source contract / JavaScript syntax / TypeScript·Vue transpile / KBX governance regression 수준이다. 실제 browser runtime 검증은 별도로 필요하다.

11. 다음 우선순위

다음 FE 단계는 Framework 증설보다 다음 순서가 맞다.

1. T08 Excel Import의 실제 6단계 입력·매핑·검증·Preview·Job 결과 work-surface 밀도 고도화
2. T06 Queue와 T07 Reconcile의 row-level recovery/action pattern을 실제 Golden interaction으로 승격
3. T09 WMS Picking의 390×844 runtime visual/keyboard-wedge/network state 검증
4. 의존성이 준비된 환경에서 1440×900 / 1280×720 / Dark / forced-colors / 390×844 Playwright 시각·조작 회귀 실행

중요한 원칙은 그대로다. FE 완성도는 컴포넌트 수가 아니라 사용자가 현재 상태 → 다음 행동 → 오류 복구를 빠르게 판단하고 실제 업무를 끝낼 수 있는지로 판단해야 한다.