kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81ff8da086bc2ff310f506a8f8823d013a8f1aee
KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/core-component-recovery-home-navigation-v34.md
T
kjh2064 3f293d8aa8
deploy / deploy (push) Successful in 1m52s
Details
deploy / notify (push) Successful in 1s
Details
V13-FE-006: consolidate approved UI and contract hardening
2026-08-13 02:41:00 +09:00

9.7 KiB
Raw Blame History

KBX Foundation v34

Core Component Recovery · Permission · Home Navigation Hardening

1. 목적

v34는 T01~T09 Screen Template 자체의 상태 계약을 확장한 v33 다음 단계다. 목표는 Template Manifest에 선언된 핵심 Business Component가 실제 운영 수준의 오류·복구·권한·접근성 계약을 갖도록 하고, Home Workbench의 탐색 상태가 권한/카탈로그 변경에도 일관되도록 만드는 것이다.

핵심 원칙은 다음과 같다.

  • Template은 Core Component 이름만 나열하지 않고 실제 Manifest와 독립 Catalog Scenario까지 폐쇄적으로 연결한다.
  • Component 내부 비동기/오류 상태를 화면 Slice가 매번 재구현하지 않는다.
  • Frontend Permission은 UX 표현과 defense-in-depth를 담당하고 Backend Permission/Domain Validation을 대체하지 않는다.
  • Import/AI/WMS 입력은 Client 편의 검증 뒤에도 Server validation, idempotency, staging, domain rule을 최종 기준으로 둔다.
  • Home은 열린 업무/고정 업무를 중복 집계하지 않고, Permission이나 Catalog 변경으로 사라진 Module filter를 안전하게 복구한다.

2. T01~T09 Core Component Closure

kbxTemplateManifest.coreComponents에 포함되는 모든 Component는 다음 세 조건을 만족해야 한다.

Template Manifest
      ↓
Component Manifest
      ↓
Component Catalog Scenario

v34 Governance Gate는 세 계층 중 하나라도 누락되면 실패한다.

v33 기준으로 독립 Catalog Scenario가 없던 다음 Core Component를 추가했다.

  • KbxLookupDialog
  • KbxValidationSummary
  • KbxExceptionSummary
  • KbxExceptionDetailDrawer
  • KbxRecordLifecycle
  • KbxBarcodeCapture
  • KbxNetworkIndicator
  • KbxWmsActionButton

AI/Utility의 운영 상태 재현성을 위해 다음 Scenario도 보강했다.

  • KbxAiAssistant
  • KbxUtilityRail

이로써 "Template 계약에는 존재하지만 독립 상태를 재현할 수 없는 Component"를 허용하지 않는다.

3. Lookup 고도화

3.1 비동기 응답 역전 방지

Lookup 입력은 사용자가 빠르게 값을 바꾸는 경우 먼저 보낸 요청이 나중에 도착할 수 있다. v34는 request sequence를 사용하여 오래된 응답이 최신 입력을 덮어쓰지 못하게 한다.

A 검색 요청
B 검색 요청
B 응답 반영
A 응답 도착 → 폐기

3.2 상태 표준화

Lookup Dialog가 다음 상태를 직접 책임진다.

  • Provider unavailable
  • Loading
  • Error
  • Empty
  • Ready
  • Paging
  • Selected row

오류 후 다시 조회가 가능하며, 결과가 없을 때 빈 Grid처럼 보이지 않고 명시적인 Empty 상태를 제공한다.

3.3 Keyboard / Accessibility

  • Arrow Up/Down: 결과 이동
  • Enter: 선택
  • Esc: 닫기
  • 선택 후 원래 Input으로 Focus restore
  • aria-selected
  • 선택 Row 자동 Scroll

3.4 Provider Metadata Column

Lookup별 결과 컬럼을 페이지가 직접 Table로 만들지 않도록 KbxLookupColumnDefinition을 추가했다.

지원 source:

  • code
  • displayName
  • secondaryText
  • status
  • metadata.*

3.5 Primitive 경계

KbxLookupDialog는 PrimeVue Dialog/Button을 직접 import하지 않고 KbxDialog, KbxButton을 조합한다. Vertical Slice뿐 아니라 Business Component 내부에서도 가능한 한 KBX Primitive 계층을 유지한다.

4. Excel Import 고도화

4.1 Session Isolation

Import Session이 변경되면 이전 Session의 local mapping을 초기화한다. 서로 다른 파일/업무의 Mapping이 조용히 섞이는 것을 차단한다.

4.2 Client Preflight

서버 검증 이전에 사용자 피드백을 빠르게 제공하기 위해 다음을 확인한다.

  • .xlsx 확장자
  • maxFileSize
  • Required field mapping 누락
  • 동일 Target field 중복 Mapping

Client preflight는 편의 검증이며 Server staging/business validation을 대체하지 않는다.

4.3 Mapping 1:1 계약

동일 System Field에 여러 Excel Column이 연결된 경우 Commit 전에 오류로 표시한다. Required import field가 연결되지 않은 경우도 Commit을 차단한다.

4.4 Commit 확인

대량 반영은 KbxConfirm high-risk confirmation을 거친다. 반영 전 신규/수정/정상/오류 범위를 사용자가 확인할 수 있는 기존 Import 정책을 유지한다.

4.5 Terminal Result

다음을 구분한다.

  • Completed
  • PartiallyCompleted
  • Failed
  • Cancelled

부분 완료는 성공 건과 제외된 오류 건을 분리해서 설명하고 오류 데이터 재처리 경로를 제공한다. 실패 시 KbxImportFailure의 code/title/detail을 표현할 수 있다.

5. Exception Action Permission

KbxExceptionDetailDrawer를 KbxDrawer + KbxButton 조합으로 정리하고 Permission Host를 자동 소비한다.

Action은 다음 정책을 지원한다.

permissionMode = hide
permissionMode = disable

Permission Host가 없는데 permission이 명시된 Action은 안전한 방향으로 실행을 허용하지 않는다.

화면 Shell의 접근권한과 Exception Drawer 내부 Action 권한이 분리되어 누락되는 문제를 줄인다.

6. AI Guard 고도화

6.1 Proposal Permission

KbxProposalPanel은 proposal의 requiredPermission을 Permission Host로 확인한다.

6.2 Proposal Validation State

AI Proposal은 다음 상태를 가질 수 있다.

pending
validated
invalid
stale

validation 정보가 존재하는 Proposal은 validated 상태에서만 Apply가 가능하다. AI confidence를 실행 권한이나 Domain validation의 대체값으로 사용하지 않는다.

6.3 Answer Action Capability / Permission

AI 답변에 포함된 Action은 각각:

  • requiredCapability
  • requiredPermission

을 확인한다.

AI가 설명할 수 있다는 이유로 사용자가 실행할 수 없는 Action을 노출/실행하지 않는다.

6.4 User-facing Context 최소화

AI Panel은 내부 screenId를 기본 사용자 문구로 직접 노출하지 않고 currentScreenLabel을 사용한다. ScreenId는 Grounding/Telemetry용 내부 식별자로 유지한다.

6.5 Error Recovery

AI 질문 실패 시 일반 오류 상태를 표시하고 마지막 질문을 다시 시도할 수 있다. 네트워크 오류를 Answer처럼 취급하지 않는다.

7. WMS Barcode Capture 고도화

7.1 Bounded Buffer

Scanner keyboard wedge가 비정상적으로 긴 데이터를 보내더라도 buffer를 무제한 확장하지 않는다.

기본 maxLength:

256

7.2 Duplicate Debounce

동일 Scanner가 극히 짧은 간격으로 같은 Barcode를 중복 전송하는 장비 bounce를 Client에서 억제한다.

기본 debounce:

180ms

하지만 일정 시간이 지난 동일 Barcode는 정상 재스캔이므로 허용한다.

이 처리는 UX 보조이며 Server Idempotency가 최종 중복 방어선이다.

7.3 입력 Source

  • keyboard-wedge
  • manual
  • camera (submitCamera entry)

를 동일 Barcode Event 계약으로 연결한다.

7.4 Context Reset

  • Esc: 현재 buffer 초기화
  • visibility change: 숨겨진 화면의 미완성 scanner buffer 제거
  • exposed reset()

백그라운드/화면전환 후 오래된 Scanner 조각이 다음 Barcode와 합쳐지는 위험을 낮춘다.

8. Home Workbench / Navigation

8.1 Open / Pinned 중복 제거

Home Source Summary에서 open은 !pinned Workspace만 집계한다.

Pinned 3
Open 5

가 실제로 서로 다른 집합이 되며, 고정 탭을 열린 업무에도 다시 집계하지 않는다.

8.2 Permission / Catalog Change Recovery

현재 선택된 Module이 권한 변경이나 화면 Catalog 변경으로 더 이상 존재하지 않으면 Module filter를 자동으로 ALL로 복구한다.

숨겨진 Module filter 때문에 Home이 빈 화면처럼 남는 상태를 방지한다.

8.3 검색 결과 접근성

현재 Module 조건에서 접근 가능한 화면 수를 aria-live로 제공한다.

Home은 기존 v31~v33의 다음 Navigation hardening을 유지한다.

  • multi-instance workspace key
  • pinned tab capacity protection
  • tab roving focus
  • Ctrl+K menu search
  • focus restore
  • skip-to-content
  • recent route sanitization
  • encoded traversal/backslash/control rejection
  • query/hash 제거 후 recent persistence
  • preference size/field limit

9. Design Debt

v33 baseline:

268

v34 구현 후:

131

Lookup/Import/AI/WMS Component의 hard-coded spacing/width를 semantic/component token으로 이동한 결과다.

v34 release에서는 131을 새 ratchet baseline으로 설정하여 이후 132 이상으로 다시 증가하면 Governance Gate가 실패하도록 한다.

10. 변경하지 않은 경계

v34는 다음을 UI Framework 내부로 끌어오지 않는다.

  • Domain business rule
  • Backend permission enforcement
  • Import staging/business validation
  • AI entity/domain validation
  • WMS server idempotency
  • Transaction concurrency source of truth

즉 KBX는 사용방법과 오류복구 UX를 표준화하고 Domain/Backend가 가능한 업무와 최종 정합성을 결정한다.

11. 다음 검증 단계

Repository Governance Gate와 별도로 실환경에서 다음을 수행해야 한다.

  1. Vitest Component Contract

    • Lookup race/error/paging/focus restore
    • Import mapping guard/session reset/partial result
    • Proposal permission/validation
    • Barcode duplicate/buffer/camera

  2. Playwright

    • T01 lookup/search/error recovery
    • T03 transaction dirty/conflict/save
    • T08 import mapping → validation → commit → partial result
    • T09 scan duplicate/network recovery
    • Home permission change/module filter recovery

  3. .NET/PostgreSQL Integration

    • Permission enforcement
    • Import staging
    • Idempotency
    • Outbox/Audit
    • AI Proposal domain revalidation
Reference in New Issue View Git Blame Copy Permalink