# KBX Business UX/AX Standard v1.0
### OMS · WMS · ERP 업무형 UX/AX 표준

---

## 1. 표준의 목적

KBX의 목표는 새로운 UX를 발명하는 것이 아니다.

**한국 업무사용자가 더존 Smart A 계열, WEHAGO, 이카운트, 영림원, 사방넷, 이지어드민, 카페24 등의 업무시스템에서 이미 학습한 사용 문법을 정리하고, OMS·WMS·ERP 전체에서 동일하게 재사용하는 것​**을 목표로 한다.

성공 기준은 다음과 같다.

1. 별도 교육 없이 기본적인 조회·등록·수정 업무가 가능하다.
2. 초보자는 마우스로 모든 기능을 사용할 수 있다.
3. 숙련자는 키보드 중심으로 빠르게 업무할 수 있다.
4. Excel 사용자가 Excel을 포기하지 않아도 된다.
5. 반복 클릭과 중복입력을 최소화한다.
6. 정상 데이터는 자동처리하고 예외만 사용자에게 노출한다.
7. AI는 기존 업무 UI를 대체하지 않고 업무 옆에서 보조한다.
8. AI가 잘못 판단하더라도 업무 데이터 정합성을 훼손할 수 없다.
9. 모든 주요 변경은 원인과 결과를 재현할 수 있다.
10. 화면 수가 증가해도 UX가 분화되지 않는다.

---

# 2. KBX의 7대 설계 원칙

## 2.1 Familiar First

기존 한국 ERP 문법을 우선한다.

권장 용어:

- 조회
- 신규
- 저장
- 수정
- 취소
- 삭제
- 복사
- 인쇄
- 엑셀
- 도움말
- 변경이력
- 확정
- 마감
- 일괄처리

불필요하게 다음과 같이 바꾸지 않는다.

- Create
- Submit
- Action
- Manage
- Process
- Execute

업무 사용자가 이미 아는 표현을 다시 학습시키지 않는다.

---

## 2.2 Keyboard Accelerated, Mouse Complete

마우스만으로 모든 업무가 가능해야 한다.

동시에 숙련 사용자는 키보드를 통해 반복 업무를 가속할 수 있어야 한다.

단축키는 필수 학습 기능이 아니라 생산성 증폭 장치다.

---

## 2.3 Grid First

OMS·WMS·ERP에서 Grid는 단순 조회 Table이 아니다.

Grid는 다음 역할을 수행한다.

- 조회
- 선택
- 편집
- 비교
- 대량입력
- 복사
- 붙여넣기
- 일괄처리
- 검증
- 합계
- Drill-down

따라서 `KbxDataGrid`는 전체 제품에서 가장 중요한 공통 컴포넌트로 관리한다.

---

## 2.4 Exception Driven

사용자가 정상 건을 일일이 처리하지 않는다.

예:

전체 주문 8,240건 중

- 재고 부족 7건
- 주소 오류 4건
- SKU Mapping 오류 2건
- 송장 발급 실패 3건

이라면 사용자의 업무 대상은 8,240건이 아니라 **16건**이어야 한다.

---

## 2.5 Predictable Layout

동일한 기능은 모든 화면에서 동일한 위치에 존재한다.

화면마다 버튼 위치가 달라지면 안 된다.

---

## 2.6 Explicit State

현재 상태와 다음 행동을 숨기지 않는다.

예:

`작성 → 확정 → 할당 → 피킹 → 검수 → 출고`

현재:

`피킹 완료`

다음 가능 작업:

`검수 시작`

금지 작업:

`주문 수정`

---

## 2.7 Audit by Default

중요한 변경은 항상 다음을 기록한다.

- 누가
- 언제
- 어디서
- 무엇을
- 변경 전
- 변경 후
- 변경 방법
- 업무 사유

자동화나 AI에 의한 작업도 사용자 작업과 동일하게 추적한다.

---

# 3. Desktop 표준 화면 구조

기준 Viewport:

`1440 × 900`

이보다 커져도 본문이 무작정 확장되지 않도록 구성한다.

기본 화면:

```text
┌──────────────────────────────────────────────────────────────┐
│ Logo │ 모듈 │ 메뉴검색 │ Workspace Tabs            사용자 │
├───────────┬──────────────────────────────────────────────────┤
│           │ Breadcrumb / 화면명               도움말 AI 제안│
│           ├──────────────────────────────────────────────────┤
│ 메뉴      │ Command Bar                                      │
│           │ [조회] [신규] [저장] [일괄처리] [엑셀▼]          │
│ 즐겨찾기  ├──────────────────────────────────────────────────┤
│ 최근메뉴  │ Search Condition                                 │
│           ├──────────────────────────────────────────────────┤
│           │                                                  │
│           │                 Main Workspace                   │
│           │                                                  │
│           ├──────────────────────────────────────────────────┤
│           │ Summary / Total / Selection Status               │
└───────────┴──────────────────────────────────────────────────┘
```

---

# 4. 기본 치수

## Desktop Dense

| 항목 | 기준 |
|---|---:|
| 기본 Font | 14px |
| Grid Font | 13~14px |
| Input Height | 34px |
| Button Height | 34px |
| Grid Row | 34px |
| Grid Header | 36px |
| Page Title | 20px |
| Section Title | 16px |
| Label Width | 88~120px |
| 기본 Input | 180~240px |
| Radius | 4~6px |
| 기본 Gap | 8px |
| Section Gap | 16~24px |

### 원칙

업무시스템에서 8px 단위의 과도하게 큰 여백을 반복 사용하지 않는다.

`예쁜 여백`보다 `정보 접근성`을 우선한다.

---

# 5. Command Bar 표준

버튼 순서는 가능한 한 고정한다.

```text
[조회 F3]
[신규]
[저장 F8]
[삭제/취소]
|
[업무별 주요 Action]
|
[인쇄]
[엑셀 ▼]
[더보기 ⋯]
```

### 규칙

Primary Action은 화면당 최대 1개.

예:

- 저장
- 출고확정
- 입고확정
- 검수완료

나머지는 Secondary 처리한다.

화면마다 여러 개의 파란 Primary 버튼을 사용하지 않는다.

---

# 6. Search Panel 표준

검색 조건은 최대한 한 줄에 구성한다.

```text
기간 [2026-08-01 ~ 2026-08-08]
거래처 [10001 대한상사]
상태 [전체 ▼]
키워드 [                   ]
[조회]
[상세조건]
```

### 규칙

초기 화면:

- 자주 사용하는 조건만 표시
- 4~6개 이내

상세조건:

- Accordion 또는 Drawer
- 최근 조건 유지 가능

사용자별로:

`마지막 조회조건 기억`

옵션 제공 가능.

---

# 7. 표준 Screen Template

전체 제품 화면의 최소 90%를 다음 9개 타입으로 제한한다.

---

## T01 — Search / List

적용:

- 주문조회
- 입고조회
- 출고조회
- 구매조회
- 재고조회
- 작업조회

구조:

```text
Page Header
Command Bar
Search Panel
Data Grid
Summary Bar
```

---

## T02 — Master CRUD

적용:

- 품목
- 거래처
- 창고
- 로케이션
- 배송사
- 단가정책

구조:

```text
Page Header
Command Bar
Basic Information
Additional Information
Optional Tabs
Audit
```

---

## T03 — Header + Detail Transaction

적용:

- 주문등록
- 구매등록
- 입고등록
- 출고등록
- 재고이동

구조:

```text
Header Form
Detail Grid
Summary
Command Bar
```

가장 중요한 Transaction Template이다.

---

## T04 — Fast Grid Entry

다량 행 입력용.

적용:

- 주문 일괄등록
- 재고조정
- 품목 단가
- 입고 예정
- 거래처별 가격

특징:

- Enter 연속입력
- 이전 값 자동복사
- F2 Lookup
- 다중 Cell Paste
- 행 복제
- Fill Down

---

## T05 — Master / Detail Explorer

적용:

```text
거래처 → 주문
품목 → 재고
창고 → 로케이션
주문 → 출고
```

구조:

```text
┌──────────────┬────────────────────────┐
│ Master Grid  │ Detail Grid            │
│              │                        │
│              │                        │
└──────────────┴────────────────────────┘
```

사용자가 상세 화면을 반복적으로 열었다 닫지 않아도 된다.

---

## T06 — Work Queue

사용자가 지금 처리할 업무를 보여준다.

예:

```text
오늘 업무

신규주문             2,138
출고 준비              927
재고부족                 7
주소 확인                 4
송장 실패                 3
반품 검수                12
```

차트 중심 Dashboard와 구분한다.

---

## T07 — Reconcile / Verification

데이터 정합성 비교 화면.

예:

```text
             주문   할당   피킹   검수   출고

ABC-001       10     10     10      9      0
                                  ▲ 불일치
```

또는:

```text
OMS      WMS      Difference

10       9        -1
```

불일치만 필터링할 수 있어야 한다.

---

## T08 — Excel Import

모든 Import는 동일한 UX를 사용한다.

```text
파일 선택
   ↓
필드 매핑
   ↓
검증
   ↓
Preview
   ↓
반영
   ↓
결과
```

---

## T09 — WMS Mobile Operation

Desktop Template과 별도로 관리한다.

적용:

- 입고
- 적치
- 피킹
- 검수
- 패킹
- 재고이동
- 실사

---

# 8. Form 표준

## 8.1 Layout

기본 2-column.

```text
주문일    [2026-08-08]        거래처    [10001][대한상사][F2]

담당자    [홍길동      ]      출고창고   [서울물류센터 ▼]
```

필드 관계가 없는 값을 공간이 남는다는 이유만으로 옆에 배치하지 않는다.

---

## 8.2 Required

```text
거래처 *
[                    ]
```

별표 + validation message를 같이 사용한다.

색상만으로 표현하지 않는다.

---

## 8.3 Validation Timing

검증 단계:

```text
입력 즉시
   ↓
Field Validation
   ↓
화면 저장
   ↓
Business Validation
   ↓
Server Validation
   ↓
Database Constraint
```

Zod는 사용자 편의를 위한 1차 검증이다.

최종 데이터 정합성은 서버가 책임진다.

---

# 9. KbxLookup 표준

ERP 친숙도를 결정하는 핵심 Component.

기본:

```text
거래처
[10001] [대한상사                 ] [검색]
```

지원:

1. 코드 직접입력
2. 이름 직접입력
3. Auto Complete
4. F2 Lookup
5. 검색 버튼
6. 최근 사용
7. 즐겨찾기

### Lookup Popup

```text
거래처 검색

검색어 [대한                ] [조회]

코드       거래처명           사업자번호
10001      대한상사
10002      대한유통
10003      대한물류
```

Enter:

선택

Esc:

닫기

선택 완료:

원래 입력 필드 다음 위치로 Focus 이동

---

# 10. KbxDataGrid 표준

## 필수 기능

- Column Resize
- Column Move
- Pin
- Sort
- Filter
- Multi Select
- Checkbox
- Keyboard Navigation
- Copy
- Paste
- Fill Down
- Row Add
- Row Duplicate
- Group
- Summary
- Export
- Saved Layout
- Personal Layout
- Changed Cell 표시
- Inline Validation
- Context Menu
- Drill Down

---

## Grid 정렬

| 유형 | 정렬 |
|---|---|
| 코드 | Left |
| 이름 | Left |
| 날짜 | Center |
| 상태 | Center |
| Boolean | Center |
| 수량 | Right |
| 금액 | Right |
| 비율 | Right |

---

## 금액

```text
1,250,000
```

소수점이 필요한 경우:

```text
1,250.50
```

표시와 DB Numeric Precision은 별도 관리한다.

---

# 11. Grid Editing

편집 가능한 셀은 화면만 보아도 구분할 수 있어야 한다.

상태:

- Readonly
- Editable
- Changed
- Invalid
- Computed
- AI Suggested

예:

```text
수량
[  10 ]

수량
[  20 ]  변경됨

수량
[  -1 ]  수량은 0보다 커야 합니다.
```

---

# 12. Keyboard Standard

## 공통

| Key | Action |
|---|---|
| Tab | 다음 필드 |
| Shift+Tab | 이전 필드 |
| Enter | 입력 확정 / 다음 |
| Shift+Enter | 이전 |
| Esc | 편집취소 / Popup 닫기 |
| F2 | Lookup |
| F3 | 조회 |
| F8 | 저장 |
| Ctrl+S | 저장 |
| Ctrl+C | Copy |
| Ctrl+V | Paste |
| Ctrl+Z | 편집 Undo 가능 범위 |
| Ctrl+F | 화면/Grid 검색 |

Browser 기본 단축키를 무리하게 override하지 않는다.

---

# 13. Enter Key 정책

ERP 사용성에서 매우 중요하다.

Form:

`Enter = 다음 입력`

Grid:

`Enter = 현재 값 확정 + 다음 행/셀`

Textarea:

`Enter = 줄바꿈`

Popup:

`Enter = 선택`

일관되지 않은 Enter 동작을 허용하지 않는다.

---

# 14. Delete 정책

`Delete` 키로 업무 Record를 삭제하지 않는다.

Delete 키:

`현재 Cell 값 제거`

Record 삭제 또는 업무 취소:

명시적 Action 필요.

```text
[삭제]
```

또는

```text
[주문취소]
```

Transaction은 가능한 한 물리 삭제보다 상태 기반 취소를 사용한다.

---

# 15. Mouse Standard

Single click:

`선택`

Double click:

`상세 열기`

Right click:

`보조 메뉴`

하지만 우클릭에서만 접근 가능한 핵심 기능은 금지한다.

---

# 16. Bulk Action

선택 시 contextual toolbar를 표시한다.

```text
✓ 17건 선택

[출고지시]
[담당자 변경]
[상태 변경]
[엑셀]
```

처리 결과:

```text
17건 처리

성공 15
실패 2

[실패건 보기]
```

전체 실패 때문에 정상 15건을 다시 처리하게 만들지 않는다.

---

# 17. Excel Standard

모든 입력형 업무 화면에는 공통 Excel 기능을 제공한다.

```text
엑셀 ▼

현재 조회결과 다운로드
업로드 양식 다운로드
엑셀 업로드
Excel 붙여넣기
최근 업로드 결과
```

---

# 18. Excel Import Mapping

```text
Excel Column               System Field

상품코드          →       품목코드        ✓
상품명            →       품목명          ✓
수량              →       주문수량        ✓
업체              →       거래처          ?
배송메모          →       배송메모        ✓
```

매핑 판단순서:

1. 정확한 Field Name
2. Alias
3. 사용자 저장 Mapping
4. AI Suggestion
5. 사용자 선택

---

# 19. Field Metadata

화면·API·Excel·AI에서 동일한 Field Definition을 사용한다.

```text
FieldKey
Label
Aliases
DataType
Required
Format
MaxLength
Precision
Scale
LookupSource
EnumValues
DefaultValue
Importable
Exportable
Readonly
ValidationRule
Sensitive
HelpText
```

이 메타데이터는 UI Schema의 Source 역할을 수행한다.

단, Domain Business Rule 전체를 UI Metadata에 넣지는 않는다.

---

# 20. Excel Backend Flow

```text
Upload
  ↓
File Parse
  ↓
Staging
  ↓
Normalization
  ↓
Field Validation
  ↓
Business Validation
  ↓
Preview
  ↓
Commit
  ↓
Audit
```

DB에 즉시 Import하지 않는다.

---

# 21. Excel 오류 UX

```text
전체 18,230건

정상 17,894
오류    336
```

오류:

```text
8행
존재하지 않는 품목코드입니다.

12행
주문수량은 0보다 커야 합니다.

17행
출고완료 주문은 수정할 수 없습니다.
```

사용자는 실패 데이터만 Excel로 다시 내려받을 수 있다.

```text
[오류 336건 다운로드]
```

---

# 22. Excel Mapping 재사용

저장 키:

```text
Tenant
User
Screen
ImportType
SourceTemplate
```

예:

```text
쿠팡 주문양식 → OMS 주문 Import
```

한 번 매핑한 사용자는 이후 자동 적용한다.

---

# 23. OMS 주문관리 표준

```text
주문관리

기간      [오늘 ▼]
판매채널  [전체 ▼]
상태      [전체 ▼]
검색      [                         ]
                               [조회 F3]

전체       신규       출고대기       오류
8,241      2,138        927           16

────────────────────────────────────────────────

□ 주문번호 │ 채널 │ 주문자 │ 상품 │ 수량 │ 재고 │ 상태 │ 송장
```

---

# 24. OMS Exception UX

상단 또는 우측에:

```text
확인 필요

재고부족            7
주소 오류            4
SKU 매칭실패         2
송장실패             3
```

각 숫자는 필터 바로가기 역할을 한다.

---

# 25. OMS 주문 Detail

전체 페이지 전환보다 Drawer 또는 Side Detail을 우선 고려한다.

```text
주문목록                 주문 상세

202608080001             주문자
202608080002             상품
202608080003             배송
                         처리이력
                         CS
```

조회 Context를 유지해야 한다.

복잡한 수정 작업이 필요한 경우만 전체 화면으로 전환한다.

---

# 26. ERP — 회계 제외 Master 화면

예: 품목관리

```text
품목관리

[조회] [신규] [저장] [복사] [엑셀▼]

기본정보
────────────────────────────────

품목코드 *     [ABC-001         ]
품목명 *       [스포츠화        ]
규격           [270 / BLACK     ]
단위           [EA ▼]

물류정보
────────────────────────────────

기본창고       [WH01 서울센터 F2]
바코드         [8801234567890   ]
LOT관리        [✓]
유통기한관리   [ ]

[변경이력]
```

---

# 27. WMS Desktop

관리자는 Desktop으로 다음을 처리한다.

- 입출고 현황
- 재고현황
- 로케이션
- 작업지시
- 작업자 배정
- Wave/Picking
- Inventory Reconcile
- Exception

현장 작업 화면과 분리한다.

---

# 28. WMS Mobile

기준:

- Scanner
- PDA
- Mobile
- 한 손 조작
- 장갑
- 이동중
- 네트워크 지연

Touch Target:

`48px 이상`

주요 CTA:

`52~56px`

---

# 29. Picking 화면

```text
출고 피킹

23 / 138

LOCATION
A-03-02

┌──────────────────────────┐
│      BARCODE SCAN        │
└──────────────────────────┘

ABC 운동화
BLACK / 270

필요       피킹       남음
  6          4          2

[ +1 ]        [수량입력]
```

다음 상품 이동을 위한 별도 확인 버튼을 최소화한다.

정상 Barcode Scan이면 자동 진행한다.

---

# 30. WMS Feedback

성공:

- 시각 Feedback
- 짧은 Success Sound
- Vibration

오류:

- 강한 Error Feedback
- Error Sound
- Vibration
- 수정 방법 표시

금지:

```text
오류가 발생했습니다.
[확인]
```

권장:

```text
잘못된 위치입니다.

현재 스캔
A-03-01

작업 위치
A-03-02

A-03-02로 이동하세요.
```

---

# 31. Offline / Network UX

WMS는 Network 상태를 명확히 표시한다.

```text
온라인
동기화 완료
```

또는

```text
네트워크 불안정

작업 3건 전송 대기
```

네트워크 장애 때문에 사용자가 동일 작업을 반복하지 않게 한다.

Idempotency와 UX가 연결되어야 한다.

---

# 32. Help Standard

우측 Utility Rail:

```text
[도움말]
[AI]
[제안]
```

---

## 도움말

화면 도움말:

```text
출고지시

이 화면에서는 출고대상 주문을
WMS 작업으로 전송합니다.

사용순서

1. 주문 조회
2. 주문 선택
3. 출고지시

단축키

F3 조회
Space 선택
F8 실행

주의

출고완료 주문은 수정할 수 없습니다.
```

별도의 대형 매뉴얼을 먼저 읽게 하지 않는다.

---

# 33. Field Help

짧은 의미:

Tooltip

복잡한 규칙:

Help Panel

예:

`안전재고`

Tooltip:

`출고 가능 수량 계산 시 확보하는 최소 재고`

Help:

구체적인 계산 규칙 및 예제

---

# 34. AI 위치

AI를 업무 메인 화면으로 만들지 않는다.

기본:

```text
┌────────────────────────────┐
│ AI 도우미                  │
├────────────────────────────┤
│ 현재 화면: 주문관리        │
│                            │
│ 확인 필요                  │
│ 재고부족 7건               │
│ 주소오류 4건               │
│                            │
│ 추천                       │
│ 출고 가능 주문 927건       │
│                            │
│ 질문                       │
│ [                        ] │
└────────────────────────────┘
```

---

# 35. AI Capability Level

AI 기능을 4등급으로 구분한다.

## L1 — Explain

읽기만 한다.

예:

`왜 출고가 안 됐어?`

---

## L2 — Suggest

업무값을 추천한다.

예:

`배송사를 롯데택배로 추천합니다.`

---

## L3 — Draft

Command 초안을 생성한다.

예:

`재고조정안 17건 생성`

---

## L4 — Execute

실제 Domain Command 실행.

L4는 제한적으로만 허용한다.

중요 Transaction은 사용자 확인이 필요하다.

---

# 36. AI Proposal Pattern

```text
AI 제안

재고조정 17건

ABC001
10 → 8

ABC002
12 → 11

근거
2026-08-08 실사자료

[취소]
[상세보기]
[17건 반영]
```

버튼을 누르기 전 DB를 변경하지 않는다.

---

# 37. AI Hallucination 방어

AI는 다음을 직접 생성할 수 없다.

- 존재하지 않는 ItemId
- 존재하지 않는 CustomerId
- 존재하지 않는 WarehouseId
- 임의 재고수량
- 임의 주문
- 임의 배송상태

AI Text:

```text
대한상사
```

를 Action으로 사용할 때는 반드시:

```text
CustomerId = 3817
CustomerCode = 10001
```

와 실제 Domain Identity가 Resolver를 통해 확인되어야 한다.

---

# 38. AI의 Grounding 우선순위

```text
Domain DB
↓
Internal API
↓
Business Rule
↓
Audit/Event
↓
Approved Document
↓
LLM Knowledge
```

업무 사실을 LLM 기억에서 가져오지 않는다.

---

# 39. AI 변경 이력

```text
2026-08-08 15:21

AI 추천
택배사 변경

CJ대한통운
→ 롯데택배

사용자 승인
홍길동
```

누가 최종 승인했는지를 반드시 남긴다.

---

# 40. 사용자 제안 UX

우측:

```text
제안
```

클릭:

```text
이 화면에 의견 보내기

○ 불편
○ 오류
○ 개선 제안

내용
[                                  ]

☑ 현재 화면 정보 포함

[보내기]
```

---

# 41. 사용자 제안에 자동 포함되는 정보

- Module
- ScreenId
- Route
- AppVersion
- UserRole
- Browser
- Filter
- GridLayout
- 발생시각

개인정보와 업무 민감데이터는 자동 첨부하지 않는다.

---

# 42. VOC AI 정리

사용자:

```text
주문조회 들어올 때마다
쿠팡 다시 선택하는 게 귀찮습니다.
```

내부:

```text
Category
OMS > 주문조회 > 조회조건

Summary
최근 판매채널 조건 유지 요청

Similar Suggestions
18건

Possible Improvement
사용자별 마지막 검색조건 저장
```

사용자에게 복잡한 분류 입력을 요구하지 않는다.

---

# 43. Audit Component

중요 화면에는 공통:

```text
[변경이력]
```

Panel:

```text
15:32 홍길동
출고수량
10 → 8

15:18 시스템
배송사
CJ → 롯데

사유
배송정책 자동 적용
```

---

# 44. 상태 변경과 수정 분리

Transaction 상태가 진행되면 수정 권한도 변해야 한다.

예:

```text
작성
→ 모든 필드 수정 가능

확정
→ 일부 필드 수정 제한

피킹
→ 주문수량 수정 불가

출고완료
→ 업무 취소 프로세스 필요
```

UI Disabled만 믿지 않는다.

Server에서 동일 Rule을 검증한다.

---

# 45. Frontend Component Architecture

```text
PrimeVue
AG Grid
       ↓
KBX Primitive
       ↓
KBX Business Component
       ↓
KBX Screen Template
       ↓
Vertical Slice Page
```

---

# 46. Primitive

예:

```text
KbxButton
KbxInput
KbxNumber
KbxDate
KbxSelect
KbxCheckbox
KbxDialog
KbxDrawer
```

PrimeVue를 직접 노출하지 않는다.

---

# 47. Business Component

```text
KbxLookup
KbxMoneyField
KbxQuantityField
KbxBarcodeField
KbxStatus
KbxDataGrid
KbxSearchPanel
KbxCommandBar
KbxAuditTrail
KbxExcelImport
KbxHelpPanel
KbxAiPanel
```

---

# 48. Template Component

```text
KbxListPage
KbxMasterPage
KbxTransactionPage
KbxFastEntryPage
KbxMasterDetailPage
KbxQueuePage
KbxReconcilePage
KbxImportPage
KbxWmsMobilePage
```

Vertical Slice는 임의의 Layout을 만드는 것이 아니라 Template을 선택해야 한다.

---

# 49. Vertical Slice 예

```text
Orders/
 ├─ Search/
 │   ├─ SearchOrderEndpoint.cs
 │   ├─ SearchOrderQuery.cs
 │   └─ OrderListPage.vue
 │
 ├─ Register/
 ├─ Cancel/
 ├─ Allocate/
 └─ Ship/
```

`OrderListPage.vue`

는:

```text
KbxListPage
 + OrderSearchSchema
 + OrderGridSchema
 + OrderCommands
```

조합으로 만든다.

---

# 50. 과도한 Metadata-driven UI 금지

Metadata 기반이라고 모든 화면을 JSON으로 정의하지 않는다.

단순 화면:

Schema 중심 가능

복잡 화면:

명시적인 Vue Component 사용

권장:

```text
70% 표준 Template
20% Template Extension
10% Custom
```

100% Dynamic Form Framework를 만들려고 하지 않는다.

그 자체가 기술부채가 된다.

---

# 51. Read Model 원칙

업무 Grid에 필요한 데이터는 Backend에서 한 번에 제공한다.

금지:

```text
Order API
Customer API
Item API
Warehouse API
Shipment API
```

를 Frontend가 호출하고 Join.

권장:

```text
OrderSearchReadModel
```

예:

```text
OrderNo
OrderDate
ChannelName
CustomerName
ItemSummary
TotalQty
AllocationStatus
ShipmentStatus
ExceptionCode
```

Dapper Read Model이 적합하다.

---

# 52. Normalization / Denormalization

Write:

정규화.

Read:

업무 UX에 맞는 Projection.

즉:

```text
Normalized Transaction
       ↓
Projection
       ↓
Grid optimized Read Model
```

UX 때문에 Write DB를 무조건 역정규화하지 않는다.

---

# 53. Outbox UX

예:

주문 확정 성공.

하지만 WMS 이벤트 전달 대기.

사용자에게:

```text
주문 확정 완료

WMS 출고지시
전송 대기
```

로 표시한다.

단순:

`성공`

만 표시하지 않는다.

---

# 54. Integration Failure UX

```text
주문 저장 완료

WMS 연계가 지연되고 있습니다.

시스템이 자동 재처리합니다.

[상세보기]
```

사용자가 중복으로 저장하지 않게 한다.

Inbox/Idempotency와 UX가 같이 설계되어야 한다.

---

# 55. Hangfire Job UX

대용량 Excel:

```text
18,230건 처리 중

████████████░░░░ 74%

정상 13,429
오류    217
```

다른 화면으로 이동해도 계속 처리한다.

완료:

Notification + 작업이력.

---

# 56. Notification 표준

정보:

Toast

업무 실패:

Inline Alert / Notification Center

긴 Batch:

Job Notification

위험한 의사결정:

Confirm Dialog

모든 성공 작업을 Modal로 보여주지 않는다.

---

# 57. Modal 금지 원칙

Modal을 남발하지 않는다.

Modal 적합:

- 위험한 확정
- 짧은 Lookup
- 취소사유
- 중요한 확인

Modal 부적합:

- 주문 상세
- 장시간 편집
- 복잡한 조회
- 여러 단계 업무

이런 경우 Drawer 또는 Page를 사용한다.

---

# 58. Workspace Tabs

ERP 사용자는 여러 업무를 동시에 확인한다.

따라서:

```text
주문조회 ×
출고지시 ×
재고현황 ×
품목조회 ×
```

Workspace Tab을 제공한다.

단:

무제한 Tab은 금지.

권장 최대:

`8~12`

---

# 59. Unsaved Changes

Tab 변경이나 화면 이탈 시:

수정 없음:

바로 이동

수정 존재:

```text
저장하지 않은 변경사항이 있습니다.

[계속 편집]
[변경 버리기]
[저장 후 이동]
```

---

# 60. 개인화 허용 범위

허용:

- Grid Column
- Column Width
- Sort
- Favorite
- 최근 메뉴
- 기본 Filter
- Page Size
- Density

금지:

- Form 전체 재배치
- 임의 Workflow
- 업무 필수 필드 제거
- 업무 상태 변경

지원 가능성과 재현성을 유지해야 한다.

---

# 61. Density

사용자 설정:

```text
● Compact
○ Comfortable
```

Desktop 업무는 기본 Compact.

WMS Mobile은 별도 Density.

---

# 62. Accessibility

업무시스템이라고 접근성을 포기하지 않는다.

필수:

- Keyboard Focus
- Label 연결
- 색상 이외의 상태표시
- Focus Indicator
- 충분한 Contrast
- Screen Reader 기본 지원
- Tab Order

업무 효율성과 접근성은 충돌하는 개념이 아니다.

---

# 63. UX Quality Gate

새 화면은 개발 완료 전에 다음을 통과해야 한다.

## Familiarity

- 기존 표준 Template인가?
- 조회/저장 위치가 기존과 같은가?

## Keyboard

- Tab 순서가 정상인가?
- F2 Lookup이 동작하는가?
- Enter 입력이 자연스러운가?

## Grid

- Copy/Paste 가능한가?
- Column 설정 가능한가?
- 대량 선택 가능한가?

## Excel

- Download 가능한가?
- 입력 화면이면 Import 가능한가?
- 오류행 재처리가 가능한가?

## Validation

- 오류 위치가 명확한가?
- 입력 단계에서 가능한 오류를 먼저 차단하는가?

## Audit

- 중요한 변경을 추적할 수 있는가?

## Automation

- 사람이 불필요하게 반복하는 작업이 남아 있지 않은가?

## AI

- AI가 없어도 업무를 할 수 있는가?
- AI가 잘못 추천해도 데이터가 안전한가?

---

# 64. 금지 패턴

다음 UX는 기본적으로 금지한다.

### UX

- Card Dashboard 남발
- 핵심 기능을 Icon-only 처리
- Hidden Action
- Hover-only Action
- Drag & Drop 필수
- 대형 Modal 편집
- Wizard 남용
- 화면별 제각각 Button 위치

### Data

- Client-side business truth
- AI 결과 직접 DB Update
- Excel 직접 DB Insert
- Transaction 물리삭제 남용

### Architecture

- Vertical Slice에서 PrimeVue 직접 남발
- 화면별 AG Grid 설정 복사
- 화면마다 Excel Parser 개발
- SharedKernel에 업무규칙 집중

---

# 65. 신규 화면 생성 규칙

화면을 만들 때 다음 순서로 결정한다.

```text
1. Screen Type 선택
      ↓
2. KBX Template 선택
      ↓
3. Business Component 배치
      ↓
4. Domain-specific Data 연결
      ↓
5. Exception 정의
      ↓
6. Excel 정의
      ↓
7. Keyboard 검증
      ↓
8. Audit 정의
      ↓
9. AI 보조가 필요한지 판단
```

디자이너가 빈 Canvas에서 시작하지 않는다.

---

# 66. 화면 요구사항 Definition

모든 화면 요구사항에 다음 항목을 포함한다.

```text
ScreenId
ScreenName
Module
TemplateType
Purpose
PrimaryUser
PrimaryAction
SearchFields
FormFields
GridColumns
Lookup
BulkActions
Keyboard
Excel
Validation
States
Exceptions
Audit
Help
AI
Permissions
```

이 정의는 디자인, 개발, 테스트, AI Code Generation의 공통 계약으로 사용한다.

---

# 67. Playwright UX Regression

단순 화면 Screenshot Test만 하지 않는다.

업무 동작을 검증한다.

예:

```text
주문등록

거래처 입력
→ F2
→ 검색
→ Enter
→ 품목 입력
→ 수량
→ F8
→ 저장
```

이를 Playwright 표준 Scenario로 유지한다.

---

# 68. Vitest Component Contract

공통 컴포넌트는 기능계약을 테스트한다.

예:

`KbxLookup`

- F2 open
- Esc close
- Enter select
- Focus restore
- invalid code
- disabled
- readonly

---

# 69. UX 변경의 재현성

Production에서 사용자가 문제를 제보할 때:

```text
ScreenId
ScreenVersion
ComponentVersion
GridLayout
UserPreferenceVersion
```

를 알 수 있어야 한다.

그래야:

`내 PC에서는 됩니다.`

문제를 줄일 수 있다.

---

# 70. Design System Versioning

KBX 자체도 Version을 관리한다.

```text
KBX 1.0
KBX 1.1
KBX 1.2
```

Breaking UX 변경:

Major

Component 기능 추가:

Minor

Bug fix:

Patch

화면별 임의 변경보다 공통 Component 개선을 우선한다.

---

# 71. 최종 제품 철학

KBX에서 화면 혁신은 시각적 실험을 의미하지 않는다.

다음과 같은 변화가 진짜 혁신이다.

```text
5번 입력
→ 1번 입력

10번 클릭
→ 2번 클릭

1,000건 확인
→ 예외 7건 확인

Excel 수작업
→ Mapping 저장

문제 발생
→ 원인 추적 가능

업무 질문
→ AI가 현재 Context에서 설명

사용자 제안
→ 화면에서 즉시 제출

반복 업무
→ 자동화
```

---

# 72. 최종 판단 기준

새 기능이나 디자인을 검토할 때 다음 질문 하나를 먼저 한다.

> 기존 한국 업무사용자가 설명 없이 사용할 수 있으면서 기존 방식보다 입력·클릭·판단이 줄어드는가?

YES라면 개선 가능성이 높다.

NO라면 혁신적으로 보이더라도 채택하지 않는다.

---

# 73. KBX Definition of Done

하나의 업무 화면은 다음 조건을 만족해야 완료된 것으로 본다.

- 표준 Screen Type 사용
- 공통 Command 위치 준수
- Keyboard 완전 지원
- Mouse 완전 지원
- Excel 정책 정의
- Lookup 표준 준수
- Grid 표준 준수
- Validation Server 재검증
- 변경이력 정의
- 상태 변화 정의
- Bulk 처리 결과 정의
- Error Recovery 가능
- Loading/Empty/Error 상태 존재
- Permission 처리
- AI 비의존 업무 가능
- 현장 사용 Scenario 검증
- Playwright 핵심 업무 Scenario 존재
- 사용자 제안 진입점 존재

이 조건을 만족하지 않으면 화면이 예쁘더라도 완료된 것이 아니다.