# WACE ERP 화면 구성 시스템 전체 분석

> **최종 업데이트**: 2026-03-13
> **용도**: LLM 챗봇 / AI 에이전트가 화면 개발 요청을 받았을 때 참조하는 시스템 구조 레퍼런스
> **핵심 규칙**: 사용자 업무 화면은 React 코드(.tsx)로 직접 만들지 않는다. DB 등록(screen_definitions + screen_layouts_v2 + menu_info)으로 구현한다.

---

## 1. 시스템 아키텍처 요약

### 1.1 화면 렌더링 파이프라인

```
[DB] screen_definitions (화면 정의)
  + screen_layouts_v2 (레이아웃 JSON)
  + menu_info (메뉴 등록)
       │
       ▼
[Backend API] GET /api/screens/:screenId
       │
       ▼
[Frontend] /screens/[screenId]/page.tsx
       │
       ▼
[Converter] layoutV2Converter.ts → V2 JSON을 Legacy 포맷으로 변환
       │
       ▼
[Renderer] ResponsiveGridRenderer → RealtimePreview → DynamicComponentRenderer
       │
       ▼
[Registry] ComponentRegistry.getComponent(componentType) → 실제 React 컴포넌트 렌더링
```

### 1.2 화면 유형 분류

| 구분 | 구현 방식 | 코드 위치 | 예시 |
|------|----------|----------|------|
| **사용자 업무 화면** | DB 등록 (SQL INSERT) | screen_definitions + screen_layouts_v2 | 수주관리, 품목정보, BOM관리 |
| **관리자 메뉴** | React 코드 직접 작성 | frontend/app/(main)/admin/*/page.tsx | 사용자관리, 권한관리, 시스템설정 |

**절대 규칙**: 사용자 업무 화면(생산, 영업, 구매, 물류, 품질 등)은 React 하드코딩 금지. 반드시 DB 등록 방식으로 구현.

---

## 2. V2 컴포넌트 전체 목록 (32개)

> 모든 컴포넌트는 `v2-` 접두사를 사용한다. 접두사 없는 컴포넌트는 레거시이므로 사용 금지.

### 2.1 입력 컴포넌트 (9개)

| ID | 용도 | 핵심 설정 |
|----|------|----------|
| `v2-input` | 텍스트, 숫자, 비밀번호, textarea, 슬라이더, 컬러, 버튼 | inputType, format(email/tel/url/currency/biz_no), required, readonly, maxLength |
| `v2-select` | 드롭다운, 콤보박스, 라디오, 체크박스, 태그, 토글, 스왑 | mode, source(static/code/db/api/entity/category/distinct/select), searchable, multiple, cascading |
| `v2-date` | 날짜, 시간, 날짜시간, 날짜범위, 월, 연도 | dateType(date/time/datetime), format, range, minDate, maxDate |
| `v2-file-upload` | 파일/이미지 업로드, 다중 업로드 | accept, maxSize, multiple |
| `v2-media` | 이미지, 비디오, 오디오 표시 | mediaType |
| `v2-location-swap-selector` | 출발지/도착지 선택 및 교환 | - |
| `v2-rack-structure` | 창고 랙 위치 일괄 생성 | columns, rows |
| `v2-process-work-standard` | 품목별 공정 작업기준 관리 (Pre/In/Post-Work) | - |
| `v2-item-routing` | 품목별 라우팅 버전 및 공정 순서 관리 (3단계 계층) | - |

### 2.2 표시/데이터 컴포넌트 (10개)

| ID | 용도 | 핵심 설정 |
|----|------|----------|
| `v2-table-list` | 데이터 테이블 (조회/편집, 페이지네이션, 정렬, 필터) | selectedTable, columns, pagination, displayMode(table/card), checkbox, linkedFilters |
| `v2-table-grouped` | 그룹화 테이블 (접기/펼치기, 그룹별 집계) | groupConfig(groupByColumn, summary), v2-table-list 기반 확장 |
| `v2-table-search-widget` | 테이블 검색/필터/그룹 바 | autoSelectFirstTable, showTableSelector |
| `v2-pivot-grid` | 다차원 피벗 분석 (행/열/데이터/필터 영역) | fields(area, summaryType, groupInterval), dataSource |
| `v2-text-display` | 라벨, 제목, 설명 텍스트 표시 | fontSize, fontWeight, color, textAlign |
| `v2-card-display` | 테이블 데이터를 카드 형태로 표시 | cardsPerRow, columnMapping(title/subtitle/image/status), cardStyle |
| `v2-aggregation-widget` | 합계, 평균, 개수, 최대, 최소 집계 카드 | items, filters, layout |
| `v2-status-count` | 상태별 건수 카드 표시 | statusField, countField |
| `v2-numbering-rule` | 자동 코드/번호 채번 (접두사+날짜+순번) | rule, prefix, format |
| `v2-category-manager` | 트리 기반 카테고리 관리 (3단계 계층) | - |

### 2.3 레이아웃 컴포넌트 (8개)

| ID | 용도 | 핵심 설정 |
|----|------|----------|
| `v2-split-panel-layout` | 마스터-디테일 좌우 분할 | splitRatio, leftPanel(displayMode/tableName), rightPanel(relation/foreignKey), additionalTabs |
| `v2-tabs-widget` | 탭 전환, 탭 내 컴포넌트 배치 | tabs(id/label/components), defaultTab, orientation |
| `v2-section-card` | 제목+테두리가 있는 그룹화 컨테이너 | title, collapsible |
| `v2-section-paper` | 배경색 기반 미니멀 그룹화 컨테이너 | backgroundColor, padding |
| `v2-divider-line` | 영역 구분선 | orientation, thickness |
| `v2-split-line` | 캔버스 좌우 분할용 드래그 가능 세로선 | - |
| `v2-repeat-container` | 데이터 수만큼 내부 컴포넌트 반복 렌더링 | dataSourceType, layout, gridColumns |
| `v2-repeater` | 인라인/모달/버튼 모드 반복 데이터 관리 | mode(inline/modal/button) |

### 2.4 특수/비즈니스 컴포넌트 (5개)

| ID | 용도 | 핵심 설정 |
|----|------|----------|
| `v2-button-primary` | 저장/삭제/조회 등 액션 버튼 | text, actionType, variant, webTypeConfig.dataflowConfig |
| `v2-timeline-scheduler` | 간트차트형 일정/계획 시각화 (드래그/리사이즈) | selectedTable, resourceTable, fieldMapping, zoomLevel, editable |
| `v2-approval-step` | 결재 단계 스테퍼 시각화 | - |
| `v2-bom-tree` | BOM 계층 트리 표시 (정전개/역전개) | - |
| `v2-bom-item-editor` | BOM 하위품목 트리 편집 | - |

---

## 3. 화면 UI 패턴 분류 (7가지)

> AI가 화면 개발 요청을 받았을 때, 아래 패턴 중 해당하는 것을 선택하여 구현한다.

### 패턴 A: 기본 마스터 (검색 + 테이블)

**적용 비율**: 약 50% (가장 흔함)
**적용 화면**: 코드관리, 부서정보, 창고정보, 검사기준, 불량관리, 공급업체관리 등

```
┌─────────────────────────────────────────────────┐
│ v2-table-search-widget                          │
│ [검색필드1] [검색필드2] [조회] [엑셀]            │
├─────────────────────────────────────────────────┤
│ v2-table-list                                   │
│ 제목        [신규] [삭제]                        │
│ ─────────────────────────────────────────────── │
│ □ | 코드 | 이름 | 상태 | 등록일                 │
└─────────────────────────────────────────────────┘
```

**필수 컴포넌트**: `v2-table-search-widget` (1개) + `v2-table-list` (1개)

### 패턴 B: 마스터-디테일 (좌우 분할)

**적용 비율**: 약 25%
**적용 화면**: 공정관리, 수주관리, 견적관리, 품목라우팅 등

```
┌──────────────────┬──────────────────────────────┐
│ 마스터 테이블     │ 디테일 테이블/폼              │
│ (좌측 패널)      │ (우측 패널)                   │
│ □ A001 항목1     │ [상세 정보 테이블]             │
│ □ A002 항목2 ←   │                              │
└──────────────────┴──────────────────────────────┘
           v2-split-panel-layout
```

**필수 컴포넌트**: `v2-split-panel-layout` (1개)

### 패턴 C: 마스터-디테일 + 탭

**적용 비율**: 약 10%
**적용 화면**: 거래처관리, 설비정보, 품목정보 등

```
┌──────────────────┬──────────────────────────────┐
│ 마스터 테이블     │ [기본] [이력] [첨부]          │
│                  │ ┌────────────────────────┐   │
│ □ A001 거래처1   │ │ 탭별 컨텐츠            │   │
│ □ A002 거래처2 ← │ └────────────────────────┘   │
└──────────────────┴──────────────────────────────┘
```

**필수 컴포넌트**: `v2-split-panel-layout` (1개, rightPanel에 additionalTabs 설정)

### 패턴 D: 카드 뷰

**적용 비율**: 약 5%
**적용 화면**: 설비정보, 대시보드, 상품 카탈로그 등

```
┌─────────────────────────────────────────────────┐
│ v2-table-search-widget                          │
├─────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│ │ [이미지]│ │ [이미지]│ │ [이미지]│           │
│ │ 제목    │ │ 제목    │ │ 제목    │           │
│ │ 설명    │ │ 설명    │ │ 설명    │           │
│ └─────────┘ └─────────┘ └─────────┘           │
│              v2-card-display                    │
└─────────────────────────────────────────────────┘
```

**필수 컴포넌트**: `v2-card-display` (1개) + `v2-table-search-widget` (선택)

### 패턴 E: 피벗 분석

**적용 비율**: 약 3%
**적용 화면**: 매출분석, 재고현황, 생산실적 분석 등

**필수 컴포넌트**: `v2-pivot-grid` (1개)

### 패턴 F: 그룹화 테이블

**적용 비율**: 약 5%
**적용 화면**: 품목정보(카테고리별), 입출고관리(구분별), 작업지시(공정별) 등

```
┌─────────────────────────────────────────────────┐
│ [전체 펼치기] [전체 접기]                         │
├─────────────────────────────────────────────────┤
│ ▼ □ 그룹A                    수량: 150  3건     │
│   ├─ □ 항목1  50개                              │
│   ├─ □ 항목2  50개                              │
│   └─ □ 항목3  50개                              │
│ ► □ 그룹B                    수량: 200  2건     │
└─────────────────────────────────────────────────┘
```

**필수 컴포넌트**: `v2-table-grouped` (1개)

### 패턴 G: 타임라인/간트차트

**적용 비율**: 약 2%
**적용 화면**: 생산계획관리, 설비가동현황 등

```
┌────────────┬─────────────────────────────────────┐
│            │ 15(수) │ 16(목) │ 17(금) │ 18(토)   │
├────────────┼─────────────────────────────────────┤
│ 설비A      │ ████████████████                    │
│ 설비B      │        █████████████████████        │
│ 설비C      │                    ████████████████ │
└────────────┴─────────────────────────────────────┘
```

**필수 컴포넌트**: `v2-timeline-scheduler` (1개)

---

## 4. 패턴 판단 의사결정 트리

> AI가 화면 요청을 받았을 때 이 트리를 따라 패턴을 결정한다.

```
Q1. 시간축 기반 일정/간트차트가 필요한가?
├─ YES → 패턴 G (타임라인)
└─ NO ↓

Q2. 다차원 집계/피벗 분석이 필요한가?
├─ YES → 패턴 E (피벗)
└─ NO ↓

Q3. 데이터를 그룹별로 묶어서 접기/펼치기가 필요한가?
├─ YES → 패턴 F (그룹화 테이블)
└─ NO ↓

Q4. 이미지+정보를 카드 형태로 표시하는가?
├─ YES → 패턴 D (카드 뷰)
└─ NO ↓

Q5. 마스터 테이블 선택 시 연관 디테일이 필요한가?
├─ YES → Q5-1. 디테일에 탭이 필요한가?
│        ├─ YES → 패턴 C (마스터-디테일+탭)
│        └─ NO  → 패턴 B (마스터-디테일)
└─ NO → 패턴 A (기본 마스터)
```

---

## 5. 화면 구현 불가능/제한 사항

### 5.1 현재 불가능 (별도 React 개발 필요)

| 기능 | 상태 | 대안 |
|------|------|------|
| 칸반 보드 (드래그앤드롭) | 미지원 | 별도 React 컴포넌트 |
| 모바일 네이티브 앱 스타일 | 미지원 | 별도 개발 |
| 복잡한 차트 (line, bar, pie) | 미지원 | 외부 라이브러리 연동 |

### 5.2 이전에 불가능했으나 현재 지원되는 기능

| 기능 | 지원 컴포넌트 | 추가 시점 |
|------|-------------|----------|
| 그룹화 테이블 | `v2-table-grouped` | 2026-01 |
| 타임라인/간트차트 | `v2-timeline-scheduler` | 2026-01 |
| BOM 트리 (정전개/역전개) | `v2-bom-tree` | 2026-02 |
| BOM 하위품목 편집 | `v2-bom-item-editor` | 2026-02 |
| 결재 스테퍼 | `v2-approval-step` | 2026-02 |

### 5.3 권장하지 않는 조합

| 조합 | 이유 |
|------|------|
| 3단계 이상 중첩 분할 | 화면 복잡도 증가, 성능 저하 |
| 탭 안에 탭 | 사용성 저하 |
| 한 화면에 3개 이상 테이블 | 데이터 로딩 성능 |
| 피벗 + 상세 테이블 동시 | 데이터 과부하 |

---

## 6. 화면별 구현 현황 (메뉴 분류)

### 6.1 기준정보

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 회사정보 | A | 완전 지원 | |
| 부서정보 | A | 완전 지원 | |
| 품목정보 | F 또는 A | 완전 지원 | 카테고리별 그룹화 시 F |
| BOM관리 | B + v2-bom-tree | 완전 지원 | v2-bom-tree로 트리 구현 |
| 공정정보관리 | B | 완전 지원 | |
| 공정작업기준 | A | 완전 지원 | v2-process-work-standard 활용 가능 |
| 품목라우팅 | B | 완전 지원 | v2-item-routing 활용 가능 |

### 6.2 영업관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 수주관리 | B | 완전 지원 | |
| 견적관리 | B | 완전 지원 | |
| 거래처관리 | C | 완전 지원 | 탭(기본/이력/첨부) |
| 판매품목정보 | A | 완전 지원 | |
| 출하계획관리 | A | 완전 지원 | |

### 6.3 생산관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 생산계획관리 | G | 완전 지원 | v2-timeline-scheduler |
| 생산관리 | A | 완전 지원 | |
| 생산실적관리 | A | 완전 지원 | |
| 작업지시 | F | 완전 지원 | 공정별 그룹화 |
| 공정관리 | B | 완전 지원 | |

### 6.4 구매관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 발주관리 | A | 완전 지원 | |
| 공급업체관리 | A | 완전 지원 | |
| 구매입고 | A | 완전 지원 | |

### 6.5 설비관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 설비정보 | C 또는 D | 완전 지원 | 카드뷰 또는 탭 |

### 6.6 물류관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 창고정보관리 | A | 완전 지원 | |
| 입출고관리 | F | 완전 지원 | 구분별 그룹화 |
| 재고현황 | A 또는 E | 완전 지원 | 피벗 분석도 가능 |

### 6.7 품질관리

| 화면명 | 패턴 | 구현 가능 | 비고 |
|--------|------|----------|------|
| 검사기준 | A | 완전 지원 | |
| 검사정보관리 | C | 완전 지원 | 탭(수입검사/공정검사/출하검사) |
| 검사장비관리 | A | 완전 지원 | |
| 불량관리 | A | 완전 지원 | |
| 클레임관리 | A | 완전 지원 | |

---

## 7. 컴포넌트 커버리지 요약

| 항목 | 수치 |
|------|------|
| 전체 분석 대상 화면 | 26개 |
| V2 컴포넌트로 구현 가능 | **26개 (100%)** |
| 등록된 V2 컴포넌트 수 | 32개 |
| 화면 UI 패턴 수 | 7가지 (A~G) |

**이전 대비 변경 사항**:
- BOM 트리 지원 추가 (v2-bom-tree) → BOM관리 완전 지원
- 그룹화 테이블 지원 추가 (v2-table-grouped) → 품목정보, 입출고 등 완전 지원
- 타임라인 지원 추가 (v2-timeline-scheduler) → 생산계획관리 완전 지원
- 결재 스테퍼 추가 (v2-approval-step) → 결재 프로세스 시각화 가능
- 전체 커버리지: 65% → **100%** 달성

---

## 8. UI vs 비즈니스 로직 분리 구조

```
┌───────────────────────────────┬───────────────────────────────────┐
│        UI 레이아웃             │         제어관리 (비즈니스 로직)    │
│   screen_layouts_v2 (JSON)    │   dataflow_diagrams (JSONB)       │
├───────────────────────────────┼───────────────────────────────────┤
│ - 컴포넌트 배치/크기/위치      │ - 버튼 클릭 시 액션 (INSERT 등)    │
│ - 검색 필드 구성               │ - 조건부 실행                     │
│ - 테이블 컬럼 표시/숨김        │ - 다중 행 일괄 처리               │
│ - 카드/탭/분할 레이아웃        │ - 테이블 간 데이터 이동            │
│ - 페이지네이션/정렬 설정       │ - 외부 시스템 호출                │
└───────────────────────────────┴───────────────────────────────────┘
```

**핵심**: V2 컴포넌트는 UI만 담당한다. 버튼 클릭 시 INSERT/UPDATE/DELETE 같은 비즈니스 로직은 `dataflow_diagrams` 테이블에서 별도 설정한다.

### 비즈니스 로직 실행 흐름

```
v2-button-primary 클릭
  → webTypeConfig.dataflowConfig 확인
  → ImprovedButtonActionExecutor 실행
    1. Before 제어 실행 (조건 체크)
    2. Main 액션 실행 (save/delete/update)
    3. After 제어 실행 (후처리)
```

---

## 9. 화면 개발 순서 (AI 에이전트용)

```
Step 1: DB 테이블 생성
  └─ 모든 컬럼 VARCHAR(500), 기본 5개 컬럼 필수 (id, created_date, updated_date, writer, company_code)
  └─ table_labels, table_type_columns, column_labels 메타데이터 등록

Step 2: screen_definitions INSERT
  └─ screen_code = '{company_code}_{순번}'
  └─ table_name = 메인 테이블명

Step 3: screen_layouts_v2 INSERT
  └─ layout_data = V2 레이아웃 JSON (version: "2.0", components 배열)
  └─ 패턴(A~G)에 맞는 컴포넌트 배치

Step 4: dataflow_diagrams INSERT (비즈니스 로직이 필요한 경우)
  └─ 버튼별 액션 정의 (INSERT/UPDATE/DELETE)
  └─ 조건, 필드 매핑 설정

Step 5: menu_info INSERT
  └─ menu_url = '/screen/{screen_code}'
  └─ 적절한 parent_id로 메뉴 트리에 배치
```

---

## 10. DB 테이블 구조 레퍼런스

### screen_definitions

| 컬럼 | 타입 | 설명 |
|------|------|------|
| screen_id | integer PK (시퀀스) | 화면 고유 ID |
| screen_name | varchar(100) | 화면명 |
| screen_code | varchar(50) UNIQUE | 화면 코드 (`{company_code}_{순번}`) |
| table_name | varchar(100) | 기본 테이블명 |
| company_code | varchar(50) | 회사 코드 |
| description | text | 설명 |
| is_active | char(1) | Y/N/D |

### screen_layouts_v2

| 컬럼 | 타입 | 설명 |
|------|------|------|
| layout_id | integer PK | 레이아웃 ID |
| screen_id | integer FK | 화면 ID |
| company_code | varchar(20) | 회사 코드 |
| layer_id | integer | 레이어 ID (1=기본) |
| layout_data | jsonb | 전체 레이아웃 JSON |

### layout_data JSON 구조

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/v2-table-list",
      "position": { "x": 0, "y": 150, "z": 1 },
      "size": { "width": 1920, "height": 600 },
      "displayOrder": 0,
      "overrides": {
        "label": "품목 목록",
        "tableName": "item_info",
        "columns": [
          { "columnName": "item_code", "displayName": "품목코드", "visible": true }
        ],
        "pagination": { "enabled": true, "pageSize": 20 }
      }
    }
  ],
  "gridSettings": { "columns": 12, "gap": 16, "padding": 16 },
  "screenResolution": { "width": 1920, "height": 1080 }
}
```

### menu_info (주요 컬럼)

| 컬럼 | 설명 |
|------|------|
| objid / menu_id | 메뉴 PK |
| screen_id | 연결된 화면 ID |
| menu_url | 메뉴 URL (`/screen/{screen_code}`) |
| company_code | 회사 코드 |