kjh2064
70d9029184
Validators (Pushes and Pull Requests) / Notify PR Results (push) Has been cancelled
Validators (Pushes and Pull Requests) / Security & Secrets (push) Has been cancelled
Validators (Pushes and Pull Requests) / WBS & Audit Validations (push) Has been cancelled
Validators (Pushes and Pull Requests) / .NET Contracts (push) Has been cancelled
Validators (Pushes and Pull Requests) / Core Validators & Database Setup (push) Has been cancelled
Validators (Pushes and Pull Requests) / Calibration & Performance (push) Has been cancelled
Validators (Pushes and Pull Requests) / Operational Report & Decision Packet (push) Has been cancelled
Validators (Pushes and Pull Requests) / CI Workflow Lint (push) Has been cancelled
Validators (Pushes and Pull Requests) / UI & Storage Validation (push) Failing after 10s
Validators (Pushes and Pull Requests) / Database & Schema Validation (push) Successful in 10s
295 lines
9.2 KiB
Markdown
295 lines
9.2 KiB
Markdown
# OMS·WMS·ERP 입력 컴포넌트 및 CRUD 상세 명세
|
|
|
|
## 0. 템플릿 체계 (TPL-LIST-01 ~ TPL-HISTORY-01)
|
|
|
|
| 템플릿 ID | 화면 유형 | 대표 업무 |
|
|
| :--- | :--- | :--- |
|
|
| `TPL-LIST-01` | 목록·검색 | 주문 목록, 재고 현황, 전표 목록 |
|
|
| `TPL-CREATE-01` | 단일 등록 | 거래처, 품목, 단순 주문 |
|
|
| `TPL-CREATE-02` | 헤더·라인 등록 | 주문, 발주, 입고 예정, 전표 |
|
|
| `TPL-CREATE-03` | 단계형 등록 | 복합 주문, 반품, 계약 |
|
|
| `TPL-DETAIL-01` | 상세 조회 | 주문 상세, 입고 상세, 전표 상세 |
|
|
| `TPL-EDIT-01` | 일반 수정 | 마스터, 주문 임시 상태 수정 |
|
|
| `TPL-BULK-01` | 일괄 수정 | 담당자, 예정일, 상태 일괄 변경 |
|
|
| `TPL-DELETE-01` | 삭제 | 미사용 임시 데이터 삭제 |
|
|
| `TPL-CANCEL-01` | 취소·역처리 | 주문 취소, 출고 취소, 전표 역분개 |
|
|
| `TPL-APPROVAL-01` | 승인·반려 | 발주 승인, 전표 승인 |
|
|
| `TPL-HISTORY-01` | 변경 이력 | 값 변경, 상태 전이, 시스템 처리 이력 |
|
|
|
|
---
|
|
|
|
## 1. 목적과 적용 범위
|
|
본 명세의 목적은 OMS·WMS·ERP에서 사용하는 모든 입력 컴포넌트를 표준화하는 것이다.
|
|
* 사용자가 잘못 입력하기 어렵게 한다.
|
|
* 잘못 입력해도 쉽게 발견하고 복구할 수 있게 한다.
|
|
* 화면과 서버의 데이터 해석이 달라지지 않게 한다.
|
|
* 사용자 입력, 시스템 계산, 외부 연동, AI 추천값을 구분한다.
|
|
* 적용 범위: OMS(주문/반품/배송/결제), WMS(입고/피킹/출고/재고), ERP(발주/전표/비용), 마스터(조직/사용자/코드/창고/단위).
|
|
|
|
---
|
|
|
|
## 2. 입력 컴포넌트 계층 (4계층 아키텍처)
|
|
```text
|
|
Primitive (`components/primitives/`)
|
|
↓
|
|
Typed Field (`components/fields/`)
|
|
↓
|
|
Domain Field (`components/domain-fields/`)
|
|
↓
|
|
Business Composite (`components/business-composites/`)
|
|
```
|
|
* **2.1 Primitive**: TextInput, Button, Checkbox, Select, Dialog 등 시각/상호작용 업무 무지 컴포넌트.
|
|
* **2.2 Typed Field**: StringField, IntegerField, DecimalField, DateField, CodeField 등 데이터 타입 이해 컴포넌트.
|
|
* **2.3 Domain Field**: QuantityField, MoneyField, LotField, SerialNumberInput, ItemLookup 등 업무 도메인 이해 컴포넌트.
|
|
* **2.4 Business Composite**: AddressEditor, OrderLineEditor, InventoryAllocationEditor, BarcodeWorkInput 등 여러 필드 및 규칙 묶음.
|
|
|
|
---
|
|
|
|
## 3. 공통 필드 해부 구조
|
|
Label, Required Indicator, Business Status Indicator, Input Control, Prefix/Suffix, Supporting Information, Validation Message, Audit/Source Information으로 구성.
|
|
|
|
---
|
|
|
|
## 4. 공통 데이터 모델 (`FieldDefinition` / `FieldState`)
|
|
`FieldDefinition` 및 `FieldState` 모델 정의. `FieldMessage` 오류 코드로 통제.
|
|
|
|
---
|
|
|
|
## 5. 필드 상태 의미 (`FieldStatus`)
|
|
`idle`, `focused`, `dirty`, `validating`, `valid`, `warning`, `invalid`, `saving`, `saved`, `conflict`, `readonly`, `disabled`, `blocked` 13가지 상태 엄격 구분.
|
|
|
|
---
|
|
|
|
## 6. 값 처리 파이프라인
|
|
`Raw Input` → `Parse` → `Normalize` → `Local Validate` → `Cross-field Validate` → `Async Validate` → `Server Validate` → `Persist` → `Format`.
|
|
|
|
---
|
|
|
|
## 7. 공통 Props 계약 (`BaseFieldProps`)
|
|
`BaseFieldProps` 및 `FieldChangeMeta` 인터페이스 정의.
|
|
|
|
---
|
|
|
|
## 8. 텍스트 입력 `TextField`
|
|
IME 조합 중 강제 변환 금지, 글자 수 제한 잘라내기 금지, 정규화 지원.
|
|
|
|
---
|
|
|
|
## 9. 코드 입력 `CodeField`
|
|
대문자 자동 정규화, 중복 확인 비동기 요청 Debounce 및 요청 취소.
|
|
|
|
---
|
|
|
|
## 10. 숫자 입력 `NumberField`
|
|
정수/소수 구분, Decimal 문자열 사용, 불완전 입력 중 `0` 강제 치환 금지.
|
|
|
|
---
|
|
|
|
## 11. 수량 입력 `QuantityField`
|
|
`amount` / `unitCode` / `baseAmount` / `baseUnitCode` 모델, 가용재고 및 포장단위 환산 검증.
|
|
|
|
---
|
|
|
|
## 12. 금액 입력 `MoneyField`
|
|
`amount` / `currencyCode` 모델, 부동소수점 금지, 통화별 소수 자릿수, 조정 사유 필수.
|
|
|
|
---
|
|
|
|
## 13. 비율 입력 `PercentageField`
|
|
0~100 제한, 할인 적용 순서 및 반올림 시점 명시.
|
|
|
|
---
|
|
|
|
## 14. 날짜 입력 `DateField`
|
|
`LocalDateString` (`YYYY-MM-DD`), 영업일/마감일/회계기간 검증.
|
|
|
|
---
|
|
|
|
## 15. 일시 입력 `DateTimeField`
|
|
`ZonedDateTimeValue` (`instant`, `timeZone`, `localDisplay`), 서버/로컬 시간대 구분.
|
|
|
|
---
|
|
|
|
## 16. 단일 선택 `SelectField`
|
|
소수 항목(2~20개) 대상, 키보드 방향키 및 Enter/Escape 단축키 패턴.
|
|
|
|
---
|
|
|
|
## 17. 참조 검색 `ReferenceLookup`
|
|
품목/거래처/창고/계정 대용량 참조, 초성/코드 동시 검색, Debounce 및 오래된 응답 취소.
|
|
|
|
---
|
|
|
|
## 18. 자동완성 `AutocompleteField`
|
|
`AutocompleteValue` (`selected` vs `free-text`) 구분.
|
|
|
|
---
|
|
|
|
## 19. Checkbox·Switch
|
|
독립 복수 선택 Checkbox, 즉시 반영 Switch, 삼상태 Checkbox(`변경하지 않음` 구분).
|
|
|
|
---
|
|
|
|
## 20. Radio Group
|
|
상호 배타적 소수 선택지 비교.
|
|
|
|
---
|
|
|
|
## 21. 주소 입력 `AddressEditor`
|
|
`AddressValue` 모델, 우편번호 검색, 도서산간 배송비 검증, 개인정보 마스킹.
|
|
|
|
---
|
|
|
|
## 22. 전화번호·사업자번호 입력
|
|
원문 저장과 표시 하이픈 분리, 사업자번호 체크섬 및 중복 검증.
|
|
|
|
---
|
|
|
|
## 23. 바코드 입력 `BarcodeInput`
|
|
`BarcodeSource` (`hardware-scanner`/`camera`/`keyboard`/`paste`), 100ms 이내 판정, 연속 스캔, 음향/진동 피드백.
|
|
|
|
---
|
|
|
|
## 24. 로트 입력 `LotField`
|
|
`LotValue` 모델, FEFO/FIFO 정책 추천, 제조일/유효기간/격리 상태 검증.
|
|
|
|
---
|
|
|
|
## 25. 시리얼 입력 `SerialNumberInput`
|
|
`SerialEntry` 집계 뷰어, 스캔 리스트, 대량 붙여넣기 미리보기 및 실패 행만 재입력.
|
|
|
|
---
|
|
|
|
## 26. 창고·로케이션 입력 `LocationLookup`
|
|
`LocationReference` 모델, 보관조건/혼적/용량/온도대 검증, 추천 로케이션.
|
|
|
|
---
|
|
|
|
## 27. 파일 업로드 `FileUpload`
|
|
`UploadedFile` 모델, MIME 검증, 진행률, 악성코드 검사, 보안 상태 구분.
|
|
|
|
---
|
|
|
|
## 28. Grid Cell Editor
|
|
`GridChangeSet` 모델, 셀 편집 키보드 이동, 붙여넣기 미리보기, 가상화.
|
|
|
|
---
|
|
|
|
## 29. 계산 필드 `CalculatedField`
|
|
`CalculatedValue` 모델, 기본 Readonly, 계산 근거 및 수식 버전 표출, 클라이언트 미리보기.
|
|
|
|
---
|
|
|
|
## 30. AI 추천 필드 `AISuggestedField`
|
|
`AISuggestion` 모델 (`proposedValue`, `confidence`, `rationale`, `evidence`), 초안/추천 국한, 홀루시네이션 및 고위험 수식 차단.
|
|
|
|
---
|
|
|
|
## 31. 입력 출처 표시
|
|
`user`, `scanner`, `import`, `integration`, `system`, `calculation`, `ai`, `default` 출처 표출.
|
|
|
|
---
|
|
|
|
## 32. 기본값 정책
|
|
안전한 기본값만 적용, 이전 거래처/창고 자동 적용 위험 차단.
|
|
|
|
---
|
|
|
|
## 33. 조건부 필드
|
|
Visible/Required/Editable When 조건 제어, 숨겨진 값 유지/초기화 정책 명시.
|
|
|
|
---
|
|
|
|
## 34. 교차 필드 검증
|
|
`CrossFieldRule` 인터페이스 기반 수량/일자/금액 간 종속 관계 검증.
|
|
|
|
---
|
|
|
|
## 35. 비동기 검증
|
|
Debounce, 요청 취소, 최신 요청만 반영, 저장 시 서버 재검증.
|
|
|
|
---
|
|
|
|
## 36. 오류 표시 표준
|
|
필드 하단, Section 요약, 화면 전체 요약 3단계 위치 제공 및 포커스 이동.
|
|
|
|
---
|
|
|
|
## 37. 접근성 요구사항 (WCAG 2.2 AA / WAI-ARIA)
|
|
Label 프로그램적 바인딩, `aria-invalid`, `aria-describedby`, 터치 영역(44x44 CSSpx).
|
|
|
|
---
|
|
|
|
## 38. 키보드 표준
|
|
Tab/Shift+Tab, Enter, Escape, Arrow, Space, Ctrl+S, F2 셀 편집 단축키 패턴.
|
|
|
|
---
|
|
|
|
## 39. 모바일·산업용 단말 정책
|
|
사무용(고밀도 키보드) vs 현장용(스캔/큰 버튼/오프라인/자동 포커스) UX 단순화.
|
|
|
|
---
|
|
|
|
## 40. 오프라인 입력 정책
|
|
`OfflineCommand` 모델, 로컬 큐 적재, 자동 재연결 동기화, Idempotency Key.
|
|
|
|
---
|
|
|
|
## 41. 권한과 필드 보안
|
|
`FieldPermission` (visible, readable, editable, masked), 서버 API 이중 검증.
|
|
|
|
---
|
|
|
|
## 42. 민감정보 컴포넌트
|
|
기본 마스킹, 보기 시 추가 인증, AI 프롬프트 전송 전 비식별화.
|
|
|
|
---
|
|
|
|
## 43. 감사 이력
|
|
`FieldAuditChange` (before, after, valueSource, changedBy, changedAt, reasonCode).
|
|
|
|
---
|
|
|
|
## 44. 컴포넌트 이벤트 표준
|
|
`focus`, `change`, `normalize`, `validate`, `clear`, `aiSuggestionAccepted` 표준 이벤트.
|
|
|
|
---
|
|
|
|
## 45. 디자인 토큰
|
|
Compact(ERP), Standard(OMS), Touch(WMS) 밀도 모드 토큰 분리.
|
|
|
|
---
|
|
|
|
## 46. 컴포넌트 API 설계 원칙
|
|
Boolean Props 남용 금지, 업무 Composite 컴포넌트 분리.
|
|
|
|
---
|
|
|
|
## 47. 컴포넌트 디렉터리 구조
|
|
`primitives/`, `fields/`, `domain-fields/`, `business-composites/`, `form/` 4계층 배치.
|
|
|
|
---
|
|
|
|
## 48. 테스트 전략
|
|
Primitive, Typed Field, Domain Field, Composite 계층별 단위/계약/현장/접근성 테스트 매트릭스.
|
|
|
|
---
|
|
|
|
## 49. Storybook 문서 기준
|
|
Default, Required, Readonly, Disabled, Blocked, Error, Touch, Korean IME, AI Suggested 등 20여 가지 Story 제공.
|
|
|
|
---
|
|
|
|
## 50. Definition of Done (DoD)
|
|
기능/데이터/UX/접근성/품질 5대 영역 DoD 통과.
|
|
|
|
---
|
|
|
|
## 51. 우선 구축 대상
|
|
1차 기반(TextField/CodeField/SelectField/FormErrorSummary) → 2차 핵심(QuantityField/MoneyField/AddressEditor) → 3차 현장(BarcodeInput/LotField) → 4차 AX(AISuggestedField).
|
|
|
|
---
|
|
|
|
## 52. 핵심 설계 결론
|
|
입력 컴포넌트는 단순 UI가 아니며 정규화, 검증, 권한, 출처, 이력을 보장하는 표준 계약의 핵심이다.
|