kjh2064
1e37e715e9
8.7 KiB
OMS·WMS·ERP 공통 CRUD 화면 및 입력 컴포넌트 상용화 지침 명세
0. 템플릿 체계
0.1 표준 템플릿 ID
| 템플릿 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 |
변경 이력 | 값 변경, 상태 전이, 시스템 처리 이력 |
CRUD 화면을 단순히 URL 네 개로 구현하지 않고, 업무 위험도와 데이터 생명주기에 따라 템플릿을 분리한다.
1. 최상위 설계 원칙 & 전체 화면 공통 골격
1.1 CRUD가 아니라 업무 트랜잭션으로 정의한다
주문 조회 → 재고 할당 → 피킹 지시 → 피킹 확정 → 패킹 → 출고 확정 → 운송장 반영 → 취소 또는 역처리
완료된 거래 데이터를 삭제하거나 직접 덮어쓰는 방식보다 취소·반제·역처리 트랜잭션을 생성하는 방식이 이력성과 재현성 측면에서 안전하다.
1.2 기본 레이아웃 (Global Header / Page Header / Sticky Action Bar)
┌──────────────────────────────────────────────────────────┐
│ Global Header │
├──────────────────────────────────────────────────────────┤
│ Breadcrumb │
├──────────────────────────────────────────────────────────┤
│ Page Header │
│ [화면명] [상태] [식별번호] [주요 작업 버튼] │
├──────────────────────────────────────────────────────────┤
│ Context Bar │
│ 사업장 / 창고 / 기준일 / 데이터 최신시각 / 잠금 상태 │
├──────────────────────────────────────────────────────────┤
│ Main Content │
├──────────────────────────────────────────────────────────┤
│ Sticky Action Bar │
│ [취소] [임시저장] [저장] [확정] │
└──────────────────────────────────────────────────────────┘
2. 전체 아키텍처 방향 및 공통 화면 상태
입력 화면은 다음 5개 계층(UI Primitive → 도메인 필드 → 업무 패턴 → 화면 템플릿 → 프로세스)으로 분리하며, Initial Loading, Record Locked, Version Conflict, Offline 등 16가지 화면 상태를 공통 제공해야 한다.
3. 권한 모델
화면 권한은 최소 네 계층(화면 접근 → 작업 → 필드 → 데이터 범위)으로 나눈다.
4. TPL-LIST-01 목록·검색 템플릿
필수 요구사항:
- 저장된 검색조건과 개인별 기본 필터
- 컬럼 표시·숨김·순서·폭 저장 (
sizeColumnsToFit) - 다중 조건 필터 및 조건 그룹
- 서버 기반 정렬·필터·페이지 처리
- 선택 행 유지 및 엑셀 다운로드
5. TPL-CREATE-01 단일 등록 템플릿
적용 대상: 거래처, 품목 분류, 창고 존, 코드 마스터. 저장 순서: 포커스 확정 → 값 정규화 → 클라이언트 검증 → Idempotency Key 생성 → 서버 저장 요청.
6. TPL-CREATE-02 헤더·라인 등록 템플릿
OMS·WMS·ERP에서 가장 중요한 등록 템플릿이다 (주문/발주/입고예정/전표 등록). 헤더 변경 시 라인 재계산 토스트 및 확인창 제공, 저장과 확정 분리.
7. TPL-DETAIL-01 상세 조회 템플릿
주요 요소: Status Timeline, 요약 KPI 카드, 탭 레이아웃, 관련 문서 Tree 내비게이션, 작업 버튼 정책.
8. TPL-EDIT-01 수정 템플릿 및 충돌 해결
수정 진입 조건 검증, ChangeSet 기반 변경 추적, 409 Conflict 발생 시 서버 최신값 vs 내 변경값 3-Way 비교 UI 표출.
9. TPL-DELETE-01 삭제 템플릿
물리적 삭제는 미사용 임시 데이터/Draft에 국한하며, 참조 데이터 존재 시 비활성화 및 사유/연결문서 표출.
10. TPL-CANCEL-01 취소·역처리 템플릿
Cancellation Preview와 Execute 2단계 API 분리 및 역트랜잭션 생성을 통한 안전한 역처리.
11. TPL-BULK-01 일괄 수정 템플릿
대상/영향도 예상 표시, 100건 초과 시 비동기 Job ID 변환.
12. TPL-APPROVAL-01 승인·반려 템플릿
직무분리(SoD: 작성자와 승인자 분리) 및 승인 한도/예산 잔액 위험 뱃지 표출.
13. 입력 컴포넌트 공통 계약 (FieldStatus / FieldState)
readonly와 disabled, blocked 상태를 구별하는 표준 TypeScript FieldState 계약 적용.
14. 입력 컴포넌트별 상용 요구조건 (수량/금액/바코드/로트/Grid)
- 수량 입력: 단위/가용수량/환산단위 분리.
- 금액 입력: 부동소수점 금지, Decimal 적용.
- 스캐너 입력: 100ms 이내 로컬 판정, 음향/진동 피드백.
- 라인 Grid: 가상화, 엑셀 범위 붙여넣기.
15. 검증과 데이터 정합성 (4계층 검증)
- UI 형식 검증 → 2. 스키마 검증 → 3. 서버 업무 규칙 검증 → 4. DB 무결성/낙관적 락 검증.
16. 정규화와 역정규화 기준 & 스냅샷
마스터는 정규화, Read Model은 역정규화, 거래 당시 스냅샷(품목명, 판매가, 세율 등) 필수 보존.
17. UX와 접근성 요구조건 (WCAG 2.2 AA / WAI-ARIA)
키보드 전용 조작, 명확한 포커스 표시, 스크린리더 aria-invalid 및 aria-describedby 바인딩.
18. 역할별 UX 전략 (사무 / 현장 / 승인자 / 외부)
사무(고밀도), 창고현장(스캔 우선/큰 버튼/오프라인), 승인자(예외 중심), 외부(안내 중심).
19. AX: AI·Agent Experience 설계 & R0~R4 위험 등급
- 적용 원칙: 세금/금액/재고 차감 등 결정론적 수식은 AI 금지.
- 위험 등급: R0(조회/요약) ~ R4(회계확정/대량삭제 - AI 실행 금지).
20. SOLID와 컴포넌트 구조
SRP(단일책임), OCP(FieldAdapter 레지스트리), LSP(교체가능성), ISP(인터페이스 분리), DIP(Form Port 의존성 역전).
21. 바이브코딩과 기술부채 통제
프로토타입/테스트에 한해 허용하며, 상용 코드 반영 시 타입검사, 정적분석, E2E 검증 게이트 100% 통과 의무화.
22. 성능과 안정성 목표
일반 입력 반응 < 100ms, 바코드 판정 < 100ms, P95 검색 < 1s, P95 저장 < 2s.
23. 보안 요구조건 & 이력성/감사로그
화면/API 이중 검증, RBAC+ABAC, AuditEvent 감사로그(누가, 언제, 무엇을, 왜) 100% 보존.
24. 단계별 추진 전략 및 QA 인수 기준
1단계 현행 진단 → 2단계 표준 계약 → 3단계 기반 컴포넌트 → 4단계 파일럿(OMS/WMS/ERP) → 5단계 점진적 전환.
25. 상용화 Definition of Done (DoD)
- 디자인 시스템 규격 충족
- TypeScript Strict Null Check 타입 안정성
- 정상·오류·읽기전용·권한없음 4대 상태 제공
- 키보드 조작 및 접근성(WCAG 2.2 AA)
- 한국어 IME 및 산업용 스캐너 반응성
- 서버 검증 및 동시성 낙관적 락 충돌 처리
- 하네스 CLI(
validate_enterprise_crud_specification_v1.py) 100% PASS