# 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)

```text
┌──────────────────────────────────────────────────────────┐
│ 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계층 검증)

1. 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