# 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 존재 - 사용자 제안 진입점 존재 이 조건을 만족하지 않으면 화면이 예쁘더라도 완료된 것이 아니다.