kjh2064
284cac18f3
11 KiB
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계층 아키텍처)
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가 아니며 정규화, 검증, 권한, 출처, 이력을 보장하는 표준 계약의 핵심이다.
53. 엔터프라이즈 20대 표준 기술 스택 명세 (Standard Technology Stack)
- .NET 10 / ASP.NET Core 10: 백엔드 표준 런타임 및 닷넷 최신 프레임워크
- Modular Monolith: 순수 도메인과 모듈 경계가 분리된 모듈러 모놀리스 아키텍처
- Vertical Slice: 기능 단위 Vertical Slice 수직 분해 및 격리
- FastEndpoints: REPR (Request-Endpoint-Response) 단일 책임 API 패턴
- PostgreSQL / Npgsql / Dapper: 관계형 데이터베이스, Npgsql 드라이버 및 Dapper 마이크로 ORM
- DbUp: SQL 마이그레이션 스크립트 이력 자동화
- Hangfire: 백그라운드 반복/비동기 작업 스케줄링 엔지
- SignalR: 웹소켓 실시간 이벤트 및 텔레메트리 스트림
- Outbox + Inbox Pattern: 트랜잭션 메시징 정합성 보장 패턴
- Vue 3 / Vite 8 / pnpm: 프론트엔드 최신 반응형 컴포저블 및 초고속 Vite 빌드, pnpm 패키지 매니저
- TanStack Query (Vue Query) / Pinia: 서버 상태 캐싱/인증 페칭 및 전역 리액티브 스토어
- vee-validate / Zod: 클라이언트 1차 및 스키마 2차 런타임 유효성 검증
- PrimeVue / AG Grid: 엔터프라이즈 UI 컴포넌트 라이브러리 및 고성능 데이터 그리드 엔진
- xUnit / Vitest / Playwright: 백엔드 xUnit, 프론트엔드 Vitest 단위 테스트, Playwright E2E 자동화
- Gitea Actions: CI 8단계 품질 게이트 자동화 파이프라인
- Serilog / OpenTelemetry / Telegram: 구조화 로깅, 분산 트레이싱 및 텔레그램 실시간 인시던트 알림
- axios: HTTP 통신 클라이언트 및 CSRF 토큰 인터셉터
- vue-router: SPA 싱글 페이지 라우팅 시스템 및 RouteMeta
- BCrypt.Net-Next: 비밀번호 단방향 암호화 해시 알고리즘
- Polly & Swashbuckle.AspNetCore: 복구력 정책(Retry/CircuitBreaker) 및 OpenAPI Swagger 문서화 Engine