ERP-node/docs/screen-implementation-guide/00_analysis/v2-component-usage-guide.md

# V2 공통 컴포넌트 사용 가이드

> **목적**: 다양한 회사에서 V2 컴포넌트를 활용하여 화면을 개발할 때 참고하는 범용 가이드
> **대상**: 화면 설계자, 개발자
> **버전**: 1.0.0
> **작성일**: 2026-01-30

---

## 1. V2 컴포넌트로 가능한 것 / 불가능한 것

### 1.1 가능한 화면 유형

| 화면 유형 | 설명 | 대표 예시 |
|-----------|------|----------|
| 마스터 관리 | 단일 테이블 CRUD | 회사정보, 부서정보, 코드관리 |
| 마스터-디테일 | 좌측 선택 → 우측 상세 | 공정관리, 품목라우팅, 견적관리 |
| 탭 기반 화면 | 탭별 다른 테이블/뷰 | 검사정보관리, 거래처관리 |
| 카드 뷰 | 이미지+정보 카드 형태 | 설비정보, 대시보드 |
| 피벗 분석 | 다차원 집계 | 매출분석, 재고현황 |
| 반복 컨테이너 | 데이터 수만큼 UI 반복 | 주문 상세, 항목 리스트 |

### 1.2 불가능한 화면 유형 (별도 개발 필요)

| 화면 유형 | 이유 | 해결 방안 |
|-----------|------|----------|
| 간트 차트 / 타임라인 | 시간축 기반 UI 없음 | 별도 컴포넌트 개발 or 외부 라이브러리 |
| 트리 뷰 (계층 구조) | 트리 컴포넌트 미존재 | `v2-tree-view` 개발 필요 |
| 그룹화 테이블 | 그룹핑 기능 미지원 | `v2-grouped-table` 개발 필요 |
| 드래그앤드롭 보드 | 칸반 스타일 UI 없음 | 별도 개발 |
| 모바일 앱 스타일 | 네이티브 앱 UI | 별도 개발 |
| 복잡한 차트 | 기본 집계 외 시각화 | 차트 라이브러리 연동 |

---

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

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

| ID | 이름 | 용도 | 주요 옵션 |
|----|------|------|----------|
| `v2-input` | 입력 | 텍스트, 숫자, 비밀번호, 이메일, 전화번호, URL, 여러 줄 | inputType, required, readonly, maxLength |
| `v2-select` | 선택 | 드롭다운, 콤보박스, 라디오, 체크박스 | mode, source(distinct/static/code/entity), multiple |
| `v2-date` | 날짜 | 날짜, 시간, 날짜시간, 날짜범위, 월, 연도 | dateType, format, showTime |

### 2.2 표시 컴포넌트 (3개)

| ID | 이름 | 용도 | 주요 옵션 |
|----|------|------|----------|
| `v2-text-display` | 텍스트 표시 | 라벨, 제목, 설명 텍스트 | fontSize, fontWeight, color, textAlign |
| `v2-card-display` | 카드 디스플레이 | 테이블 데이터를 카드 형태로 표시 | cardsPerRow, showImage, columnMapping |
| `v2-aggregation-widget` | 집계 위젯 | 합계, 평균, 개수, 최대, 최소 | items, filters, layout |

### 2.3 테이블/데이터 컴포넌트 (3개)

| ID | 이름 | 용도 | 주요 옵션 |
|----|------|------|----------|
| `v2-table-list` | 테이블 리스트 | 데이터 조회/편집 테이블 | selectedTable, columns, pagination, filter |
| `v2-table-search-widget` | 검색 필터 | 테이블 검색/필터/그룹 | autoSelectFirstTable, showTableSelector |
| `v2-pivot-grid` | 피벗 그리드 | 다차원 분석 (행/열/데이터 영역) | fields, totals, aggregation |

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

| ID | 이름 | 용도 | 주요 옵션 |
|----|------|------|----------|
| `v2-split-panel-layout` | 분할 패널 | 마스터-디테일 좌우 분할 | splitRatio, resizable, relation |
| `v2-tabs-widget` | 탭 위젯 | 탭 전환, 탭 내 컴포넌트 | tabs, activeTabId |
| `v2-section-card` | 섹션 카드 | 제목+테두리 그룹화 | title, collapsible, padding |
| `v2-section-paper` | 섹션 페이퍼 | 배경색 그룹화 | backgroundColor, padding, shadow |
| `v2-divider-line` | 구분선 | 영역 구분 | orientation, thickness |
| `v2-repeat-container` | 리피터 컨테이너 | 데이터 수만큼 반복 렌더링 | dataSourceType, layout, gridColumns |
| `v2-repeater` | 리피터 | 반복 컨트롤 | - |
| `v2-repeat-screen-modal` | 반복 화면 모달 | 모달 반복 | - |

### 2.5 액션/특수 컴포넌트 (6개)

| ID | 이름 | 용도 | 주요 옵션 |
|----|------|------|----------|
| `v2-button-primary` | 기본 버튼 | 저장, 삭제 등 액션 | text, actionType, variant |
| `v2-numbering-rule` | 채번규칙 | 자동 코드/번호 생성 | rule, prefix, format |
| `v2-category-manager` | 카테고리 관리자 | 카테고리 관리 UI | - |
| `v2-location-swap-selector` | 위치 교환 | 위치 선택/교환 | - |
| `v2-rack-structure` | 랙 구조 | 창고 랙 시각화 | - |
| `v2-media` | 미디어 | 이미지/동영상 표시 | - |

---

## 3. 화면 패턴별 컴포넌트 조합

### 3.1 패턴 A: 기본 마스터 화면 (가장 흔함)

**적용 화면**: 코드관리, 사용자관리, 부서정보, 창고정보 등

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

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

**설정 포인트**:
- 테이블명 지정
- 검색 대상 컬럼 설정
- 컬럼 표시/숨김 설정

---

### 3.2 패턴 B: 마스터-디테일 화면

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

```
┌──────────────────┬──────────────────────────────┐
│ v2-table-list    │ v2-table-list 또는 폼        │
│ (마스터)         │ (디테일)                     │
│ ───────────────  │                              │
│ □ A001 항목1     │ [상세 정보]                  │
│ □ A002 항목2 ←   │                              │
│ □ A003 항목3     │                              │
└──────────────────┴──────────────────────────────┘
        v2-split-panel-layout
```

**필수 컴포넌트**:
- `v2-split-panel-layout` (1개)
- `v2-table-list` (2개: 마스터, 디테일)

**설정 포인트**:
- `splitRatio`: 좌우 비율 (기본 30:70)
- `relation.type`: join / detail / custom
- `relation.foreignKey`: 연결 키 컬럼

---

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

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

```
┌──────────────────┬──────────────────────────────┐
│ v2-table-list    │ v2-tabs-widget               │
│ (마스터)         │ ┌────┬────┬────┐            │
│                  │ │기본│이력│첨부│            │
│ □ A001 거래처1   │ └────┴────┴────┘            │
│ □ A002 거래처2 ← │ [탭별 컨텐츠]               │
└──────────────────┴──────────────────────────────┘
```

**필수 컴포넌트**:
- `v2-split-panel-layout` (1개)
- `v2-table-list` (1개: 마스터)
- `v2-tabs-widget` (1개)

**설정 포인트**:
- 탭별 표시할 테이블/폼 설정
- 마스터 선택 시 탭 컨텐츠 연동

---

### 3.4 패턴 D: 카드 뷰

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

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

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

**설정 포인트**:
- `cardsPerRow`: 한 행당 카드 수
- `columnMapping`: 제목, 부제목, 이미지, 상태 필드 매핑
- `cardStyle`: 이미지 위치, 크기

---

### 3.5 패턴 E: 피벗 분석

**적용 화면**: 매출분석, 재고현황, 생산실적 분석 등

```
┌─────────────────────────────────────────────────┐
│ v2-pivot-grid                                   │
│         │ 2024년 │ 2025년 │ 2026년 │ 합계     │
│ ─────────────────────────────────────────────── │
│ 지역A   │ 1,000  │ 1,200  │ 1,500  │ 3,700   │
│ 지역B   │ 2,000  │ 2,500  │ 3,000  │ 7,500   │
│ 합계    │ 3,000  │ 3,700  │ 4,500  │ 11,200  │
└─────────────────────────────────────────────────┘
```

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

**설정 포인트**:
- `fields[].area`: row / column / data / filter
- `fields[].summaryType`: sum / avg / count / min / max
- `fields[].groupInterval`: 날짜 그룹화 (year/quarter/month)

---

## 4. 회사별 개발 시 핵심 체크포인트

### 4.1 테이블 설계 확인

**가장 먼저 확인**:
1. 회사에서 사용할 테이블 목록
2. 테이블 간 관계 (FK)
3. 조회 조건으로 쓸 컬럼

```
✅ 체크리스트:
□ 테이블명이 DB에 존재하는가?
□ company_code 컬럼이 있는가? (멀티테넌시)
□ 마스터-디테일 관계의 FK가 정의되어 있는가?
□ 검색 대상 컬럼에 인덱스가 있는가?
```

### 4.2 화면 패턴 판단

**질문을 통한 판단**:

| 질문 | 예 → 패턴 |
|------|----------|
| 단일 테이블만 조회/편집? | 패턴 A (기본 마스터) |
| 마스터 선택 시 디테일 표시? | 패턴 B (마스터-디테일) |
| 상세에 탭이 필요? | 패턴 C (마스터-디테일+탭) |
| 이미지+정보 카드 형태? | 패턴 D (카드 뷰) |
| 다차원 집계/분석? | 패턴 E (피벗) |

### 4.3 컴포넌트 설정 필수 항목

#### v2-table-list 필수 설정

```typescript
{
  selectedTable: "테이블명",  // 필수
  columns: [                  // 표시할 컬럼
    { columnName: "id", displayName: "ID", visible: true, sortable: true },
    // ...
  ],
  pagination: {
    enabled: true,
    pageSize: 20
  }
}
```

#### v2-split-panel-layout 필수 설정

```typescript
{
  leftPanel: {
    tableName: "마스터_테이블명"
  },
  rightPanel: {
    tableName: "디테일_테이블명",
    relation: {
      type: "detail",          // join | detail | custom
      foreignKey: "master_id"  // 연결 키
    }
  },
  splitRatio: 30  // 좌측 비율
}
```

#### v2-card-display 필수 설정

```typescript
{
  dataSource: "table",
  columnMapping: {
    title: "name",       // 제목 필드
    subtitle: "code",    // 부제목 필드
    image: "image_url",  // 이미지 필드 (선택)
    status: "status"     // 상태 필드 (선택)
  },
  cardsPerRow: 3
}
```

---

## 5. 공통 컴포넌트 한계점

### 5.1 현재 불가능한 기능

| 기능 | 상태 | 대안 |
|------|------|------|
| 트리 뷰 (BOM, 조직도) | ❌ 미지원 | 테이블로 대체 or 별도 개발 |
| 그룹화 테이블 | ❌ 미지원 | 일반 테이블로 대체 or 별도 개발 |
| 간트 차트 | ❌ 미지원 | 별도 개발 필요 |
| 드래그앤드롭 정렬 | ❌ 미지원 | 순서 컬럼으로 대체 |
| 인라인 편집 | ⚠️ 제한적 | 모달 편집으로 대체 |
| 복잡한 차트 | ❌ 미지원 | 외부 라이브러리 연동 |

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

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

---

## 6. 제어관리 (비즈니스 로직) - 별도 설정 필수

> **핵심**: V2 컴포넌트는 **UI만 담당**합니다. 비즈니스 로직은 **제어관리**에서 별도 설정해야 합니다.

### 6.1 UI vs 제어 분리 구조

```
┌─────────────────────────────────────────────────────────────────┐
│                         화면 구성                               │
├─────────────────────────────┬───────────────────────────────────┤
│        UI 레이아웃           │         제어관리                  │
│   (screen_layouts_v2)       │   (dataflow_diagrams)             │
├─────────────────────────────┼───────────────────────────────────┤
│ • 컴포넌트 배치              │ • 버튼 클릭 시 액션               │
│ • 검색 필드 구성             │ • INSERT/UPDATE/DELETE 설정      │
│ • 테이블 컬럼 표시           │ • 조건부 실행                     │
│ • 카드/탭 레이아웃           │ • 다중 행 처리                    │
│                             │ • 테이블 간 데이터 이동            │
└─────────────────────────────┴───────────────────────────────────┘
```

### 6.2 HTML에서 파악 가능/불가능

| 구분 | HTML에서 파악 | 이유 |
|------|--------------|------|
| 컴포넌트 배치 | ✅ 가능 | HTML 구조에서 보임 |
| 검색 필드 | ✅ 가능 | input 태그로 확인 |
| 테이블 컬럼 | ✅ 가능 | thead에서 확인 |
| **저장 테이블** | ❌ 불가능 | JS/백엔드에서 처리 |
| **버튼 액션** | ❌ 불가능 | 제어관리에서 설정 |
| **전/후 처리** | ❌ 불가능 | 제어관리에서 설정 |
| **다중 행 처리** | ❌ 불가능 | 제어관리에서 설정 |
| **테이블 간 관계** | ❌ 불가능 | DB/제어관리에서 설정 |

### 6.3 제어관리 설정 항목

#### 트리거 타입
- **버튼 클릭 전 (before)**: 클릭 직전 실행
- **버튼 클릭 후 (after)**: 클릭 완료 후 실행

#### 액션 타입
- **INSERT**: 새로운 데이터 삽입
- **UPDATE**: 기존 데이터 수정
- **DELETE**: 데이터 삭제

#### 조건 설정
```typescript
// 예: 선택된 행의 상태가 '대기'인 경우에만 실행
{
  field: "status",
  operator: "=",
  value: "대기",
  dataType: "string"
}
```

#### 필드 매핑
```typescript
// 예: 소스 테이블의 값을 타겟 테이블로 이동
{
  sourceTable: "order_master",
  sourceField: "order_no",
  targetTable: "order_history",
  targetField: "order_no"
}
```

### 6.4 제어관리 예시: 수주 확정 버튼

**시나리오**: 수주 목록에서 3건 선택 후 [확정] 버튼 클릭

```
┌─────────────────────────────────────────────────────────────────┐
│ [확정] 버튼 클릭                                                 │
├─────────────────────────────────────────────────────────────────┤
│ 1. 조건 체크: status = '대기' 인 행만                            │
│ 2. UPDATE order_master SET status = '확정' WHERE id IN (선택)   │
│ 3. INSERT order_history (수주이력 테이블에 기록)                 │
│ 4. 외부 시스템 호출 (ERP 연동)                                   │
└─────────────────────────────────────────────────────────────────┘
```

**제어관리 설정**:
```json
{
  "triggerType": "after",
  "actions": [
    {
      "actionType": "update",
      "targetTable": "order_master",
      "conditions": [{ "field": "status", "operator": "=", "value": "대기" }],
      "fieldMappings": [{ "targetField": "status", "defaultValue": "확정" }]
    },
    {
      "actionType": "insert",
      "targetTable": "order_history",
      "fieldMappings": [
        { "sourceField": "order_no", "targetField": "order_no" },
        { "sourceField": "customer_name", "targetField": "customer_name" }
      ]
    }
  ]
}
```

### 6.5 회사별 개발 시 제어관리 체크리스트

```
□ 버튼별 액션 정의
  - 어떤 버튼이 있는가?
  - 각 버튼 클릭 시 무슨 동작?

□ 저장/수정/삭제 대상 테이블
  - 메인 테이블은?
  - 이력 테이블은?
  - 연관 테이블은?

□ 조건부 실행
  - 특정 상태일 때만 실행?
  - 특정 값 체크 필요?

□ 다중 행 처리
  - 여러 행 선택 후 일괄 처리?
  - 각 행별 개별 처리?

□ 외부 연동
  - ERP/MES 등 외부 시스템 호출?
  - API 연동 필요?
```

---

## 7. 회사별 커스터마이징 영역

### 7.1 컴포넌트로 처리되는 영역 (표준화)

| 영역 | 설명 |
|------|------|
| UI 레이아웃 | 컴포넌트 배치, 크기, 위치 |
| 검색 조건 | 화면 디자이너에서 설정 |
| 테이블 컬럼 | 표시/숨김, 순서, 너비 |
| 기본 CRUD | 조회, 저장, 삭제 자동 처리 |
| 페이지네이션 | 자동 처리 |
| 정렬/필터 | 자동 처리 |

### 7.2 회사별 개발 필요 영역

| 영역 | 설명 | 개발 방법 |
|------|------|----------|
| 비즈니스 로직 | 저장 전/후 검증, 계산 | 데이터플로우 또는 백엔드 API |
| 특수 UI | 간트, 트리, 차트 등 | 별도 컴포넌트 개발 |
| 외부 연동 | ERP, MES 등 연계 | 외부 호출 설정 |
| 리포트/인쇄 | 전표, 라벨 출력 | 리포트 컴포넌트 |
| 결재 프로세스 | 승인/반려 흐름 | 워크플로우 설정 |

---

## 8. 빠른 개발 가이드

### Step 1: 화면 분석
1. 어떤 테이블을 사용하는가?
2. 테이블 간 관계는?
3. 어떤 패턴인가? (A/B/C/D/E)

### Step 2: 컴포넌트 배치
1. 화면 디자이너에서 패턴에 맞는 컴포넌트 배치
2. 각 컴포넌트에 테이블/컬럼 설정

### Step 3: 연동 설정
1. 마스터-디테일 관계 설정 (FK)
2. 검색 조건 설정
3. 버튼 액션 설정

### Step 4: 테스트
1. 데이터 조회 확인
2. 마스터 선택 시 디테일 연동 확인
3. 저장/삭제 동작 확인

---

## 9. 요약

### V2 컴포넌트 커버리지

| 화면 유형 | 지원 여부 | 주요 컴포넌트 |
|-----------|----------|--------------|
| 기본 CRUD | ✅ 완전 | v2-table-list, v2-table-search-widget |
| 마스터-디테일 | ✅ 완전 | v2-split-panel-layout |
| 탭 화면 | ✅ 완전 | v2-tabs-widget |
| 카드 뷰 | ✅ 완전 | v2-card-display |
| 피벗 분석 | ✅ 완전 | v2-pivot-grid |
| 그룹화 테이블 | ❌ 미지원 | 개발 필요 |
| 트리 뷰 | ❌ 미지원 | 개발 필요 |
| 간트 차트 | ❌ 미지원 | 개발 필요 |

### 개발 시 핵심 원칙

1. **테이블 먼저**: DB 테이블 구조 확인이 최우선
2. **패턴 판단**: 5가지 패턴 중 어디에 해당하는지 판단
3. **표준 조합**: 검증된 컴포넌트 조합 사용
4. **한계 인식**: 불가능한 UI는 조기에 식별하여 별도 개발 계획
5. **멀티테넌시**: 모든 테이블에 company_code 필터링 필수
6. **제어관리 필수**: UI 완성 후 버튼별 비즈니스 로직 설정 필수

### UI vs 제어 구분

| 영역 | 담당 | 설정 위치 |
|------|------|----------|
| 화면 레이아웃 | V2 컴포넌트 | 화면 디자이너 |
| 비즈니스 로직 | 제어관리 | dataflow_diagrams |
| 외부 연동 | 외부호출 설정 | external_call_configs |

**HTML에서 배낄 수 있는 것**: UI 구조만
**별도 설정 필요한 것**: 저장 테이블, 버튼 액션, 조건 처리, 다중 행 처리