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

# V2 컴포넌트 사용 가이드 (LLM/챗봇용)

> **최종 업데이트**: 2026-03-13
> **용도**: LLM 챗봇이 화면 개발 요청을 받았을 때, 어떤 컴포넌트를 어떤 설정으로 사용해야 하는지 판단하는 레퍼런스
> **버전**: 2.0.0
> **대상**: AI 에이전트, 챗봇, 화면 설계자

---

## 0. 핵심 규칙 (반드시 준수)

1. **사용자 업무 화면은 React 코드로 직접 만들지 않는다** → DB에 `screen_definitions` + `screen_layouts_v2` + `menu_info` INSERT로 구현
2. **모든 컴포넌트는 `v2-` 접두사** → `v2-` 없는 레거시 컴포넌트 사용 금지
3. **UI와 로직 분리** → UI는 `screen_layouts_v2`, 비즈니스 로직은 `dataflow_diagrams`
4. **멀티테넌시 필수** → 모든 테이블에 `company_code` 컬럼, 모든 쿼리에 `company_code` 필터링

---

## 1. 컴포넌트 전체 카탈로그 (32개)

### 1.1 입력 컴포넌트

#### v2-input

텍스트, 숫자, 비밀번호, textarea 등 모든 단일 값 입력을 처리하는 통합 입력 컴포넌트.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| inputType | string | 입력 유형 | `text`, `number`, `password`, `slider`, `color`, `button`, `textarea` |
| format | string | 포맷 검증 | `email`, `tel`, `url`, `currency`, `biz_no` |
| required | boolean | 필수 여부 | true/false |
| readonly | boolean | 읽기 전용 | true/false |
| maxLength | number | 최대 길이 | 숫자 |
| min / max | number | 숫자 범위 | 숫자 (inputType=number일 때) |
| step | number | 증감 단위 | 숫자 (inputType=number/slider일 때) |
| tableName | string | 바인딩 테이블 | DB 테이블명 |
| columnName | string | 바인딩 컬럼 | DB 컬럼명 |

#### v2-select

드롭다운, 콤보박스, 라디오, 체크박스, 태그 등 선택형 입력 통합 컴포넌트.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| mode | string | 선택 모드 | `dropdown`, `combobox`, `radio`, `check`, `tag`, `tagbox`, `toggle`, `swap` |
| source | string | 데이터 소스 | `static`, `code`, `db`, `api`, `entity`, `category`, `distinct`, `select` |
| searchable | boolean | 검색 가능 | true/false (mode=combobox일 때 기본 true) |
| multiple | boolean | 다중 선택 | true/false |
| cascading | object | 연쇄 선택 | 상위 select 값에 따라 하위 옵션 변경 |

**source 설명**:
- `static`: 고정 옵션 목록 (options 배열 직접 지정)
- `code`: code_info 테이블의 공통 코드
- `db`: 특정 테이블의 컬럼 값
- `entity`: 엔티티 조인 (다른 테이블 참조)
- `category`: v2-category-manager의 카테고리
- `distinct`: 테이블 컬럼의 DISTINCT 값

#### v2-date

날짜, 시간, 날짜시간, 날짜범위, 월, 연도 입력.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| dateType | string | 날짜 유형 | `date`, `time`, `datetime`, `month`, `year` |
| format | string | 표시 형식 | `YYYY-MM-DD`, `HH:mm`, `YYYY-MM-DD HH:mm` 등 |
| range | boolean | 범위 선택 | true/false (시작~종료 날짜) |
| minDate / maxDate | string | 선택 가능 범위 | ISO 8601 날짜 |
| showToday | boolean | 오늘 버튼 | true/false |

#### v2-file-upload

파일/이미지 업로드. 다중 업로드, 미리보기 지원.

#### v2-media

이미지, 비디오, 오디오 등 미디어 표시/재생.

#### v2-location-swap-selector

출발지/도착지 선택 및 교환 (물류 화면용).

#### v2-rack-structure

창고 랙 위치 일괄 생성 (열 범위, 단 수 설정).

#### v2-process-work-standard

품목별 공정 작업기준(Pre-Work/In-Work/Post-Work) 관리. 라우팅과 연동.

#### v2-item-routing

품목별 라우팅 버전 및 공정 순서 관리 (3단계 계층: 품목 → 라우팅 버전 → 공정).

---

### 1.2 표시/데이터 컴포넌트

#### v2-table-list

가장 핵심 컴포넌트. DB 테이블 데이터를 조회/편집하는 테이블.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| selectedTable | string | **필수**. DB 테이블명 | 예: `"item_info"` |
| columns | array | 표시할 컬럼 설정 | `[{ columnName, displayName, visible, sortable, width, editable }]` |
| pagination | object | 페이지네이션 | `{ enabled: true, pageSize: 20, showSizeSelector: true }` |
| displayMode | string | 표시 모드 | `"table"` (기본) 또는 `"card"` |
| checkbox | object | 체크박스 | `{ enabled: true, multiple: true, position: "left", selectAll: true }` |
| horizontalScroll | object | 가로 스크롤 | `{ enabled: true, maxVisibleColumns: 8 }` |
| linkedFilters | array | 다른 컴포넌트와 연동 필터 | - |
| excludeFilter | object | 제외 필터 | - |
| autoLoad | boolean | 자동 데이터 로드 | true/false |
| stickyHeader | boolean | 헤더 고정 | true/false |
| toolbar | object | 툴바 (신규/삭제/엑셀 등) | - |
| tableStyle | object | 테이블 스타일 | `{ compact: true, striped: true }` |

**columns 배열 항목**:

```json
{
  "columnName": "item_code",
  "displayName": "품목코드",
  "visible": true,
  "sortable": true,
  "width": 120,
  "editable": false,
  "inputType": "text",
  "format": null,
  "align": "left"
}
```

#### v2-table-grouped

v2-table-list 기반 확장. 특정 컬럼 기준으로 데이터를 그룹화하여 접기/펼치기 기능 제공.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| selectedTable | string | **필수**. DB 테이블명 | - |
| groupConfig | object | **필수**. 그룹화 설정 | 아래 참조 |
| columns | array | 컬럼 설정 (v2-table-list와 동일) | - |
| showCheckbox | boolean | 체크박스 표시 | true/false |

**groupConfig 구조**:

```json
{
  "groupByColumn": "category",
  "groupLabelFormat": "{category_name} ({category_code})",
  "summary": {
    "sumColumns": ["quantity", "amount"],
    "showCount": true
  },
  "defaultExpanded": true,
  "nestedGroup": null
}
```

#### v2-table-search-widget

테이블 상단에 배치하는 검색/필터 바. 대상 테이블의 컬럼을 자동 감지하여 검색 필드 생성.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| autoSelectFirstTable | boolean | 첫 번째 테이블 자동 선택 | true/false |
| showTableSelector | boolean | 테이블 선택기 표시 | true/false |
| title | string | 검색 바 제목 | - |

#### v2-pivot-grid

다차원 피벗 테이블. 행/열/데이터/필터 영역으로 데이터 분석.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| fields | array | **필수**. 필드 정의 | 아래 참조 |
| dataSource | object | 데이터 소스 | `{ type: "table"/"api"/"static", joinConfigs, filterConditions }` |

**fields 배열 항목**:

```json
{
  "dataField": "region",
  "area": "row",
  "caption": "지역"
}
```

area 값: `"row"`, `"column"`, `"data"`, `"filter"`
summaryType (area=data일 때): `"sum"`, `"avg"`, `"count"`, `"min"`, `"max"`, `"countDistinct"`
groupInterval (날짜 필드): `"year"`, `"quarter"`, `"month"`, `"week"`, `"day"`

#### v2-text-display

라벨, 제목, 설명 텍스트 표시.

| 설정 | 타입 | 설명 |
|------|------|------|
| fontSize | string | 폰트 크기 |
| fontWeight | string | 폰트 두께 |
| color | string | 텍스트 색상 |
| textAlign | string | 정렬 |

#### v2-card-display

테이블 데이터를 카드 형태로 표시.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| dataSource | string | 데이터 소스 | `"table"`, `"static"`, `"api"` |
| cardsPerRow | number | 행당 카드 수 | 1~6 |
| columnMapping | object | 필드 매핑 | `{ title, subtitle, description, image, status }` |
| cardStyle | object | 카드 스타일 | `{ imagePosition, imageSize }` |

#### v2-aggregation-widget

합계, 평균, 개수, 최대, 최소 등 집계 카드 표시.

| 설정 | 타입 | 설명 |
|------|------|------|
| items | array | 집계 항목 배열 (테이블, 컬럼, 집계함수) |
| filters | array | 필터 조건 |
| layout | string | 레이아웃 (horizontal/vertical) |

#### v2-status-count

상태별 건수를 카드 형태로 표시. 대시보드/현황 화면에 적합.

#### v2-numbering-rule

자동 코드/번호 채번. 접두사 + 날짜 + 순번 조합.

| 설정 | 타입 | 설명 |
|------|------|------|
| rule | string | 채번 규칙 |
| prefix | string | 접두사 |
| format | string | 포맷 |

#### v2-category-manager

트리 기반 카테고리 관리 (3단계 계층). 카테고리 생성/수정/삭제/이동.

---

### 1.3 레이아웃 컴포넌트

#### v2-split-panel-layout

**가장 복잡하고 중요한 컴포넌트**. 마스터-디테일 좌우 분할 레이아웃.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| splitRatio | number | 좌측 비율 (0-100) | 기본 30 |
| resizable | boolean | 리사이즈 가능 | true/false |
| minLeftWidth | number | 좌측 최소 너비 | 기본 200 |
| minRightWidth | number | 우측 최소 너비 | 기본 300 |
| syncSelection | boolean | 선택 동기화 | true/false |
| autoLoad | boolean | 자동 로드 | true/false |

**leftPanel / rightPanel 구조**:

```json
{
  "leftPanel": {
    "displayMode": "table",
    "tableName": "master_table",
    "columns": [],
    "showSearch": true,
    "showAdd": true,
    "showEdit": true,
    "showDelete": true,
    "addButton": {
      "enabled": true,
      "mode": "auto",
      "modalScreenId": ""
    },
    "editButton": {
      "enabled": true,
      "mode": "auto",
      "modalScreenId": ""
    },
    "deleteButton": {
      "enabled": true,
      "buttonLabel": "삭제",
      "confirmMessage": "삭제하시겠습니까?"
    },
    "addModalColumns": [],
    "additionalTabs": [],
    "dataFilter": {}
  },
  "rightPanel": {
    "displayMode": "table",
    "tableName": "detail_table",
    "relation": {
      "type": "detail",
      "foreignKey": "master_id",
      "leftColumn": "id",
      "rightColumn": "master_id",
      "keys": []
    },
    "addButton": { "enabled": true },
    "editButton": { "enabled": true },
    "deleteButton": { "enabled": true },
    "additionalTabs": []
  }
}
```

**displayMode 종류**:
- `"list"`: 리스트 형태 (제목, 부제목)
- `"table"`: 테이블 형태 (컬럼, 행)
- `"custom"`: 자유 배치 (components 배열로 내부 컴포넌트 배치)

**relation.type 종류**:
- `"join"`: 두 테이블 JOIN
- `"detail"`: 마스터 PK → 디테일 FK 관계
- `"custom"`: 커스텀 관계 (leftColumn, rightColumn 직접 지정)

**additionalTabs** (우측 패널에 멀티 탭 배치):

```json
{
  "additionalTabs": [
    {
      "id": "tab1",
      "label": "기본정보",
      "tableName": "detail_basic",
      "relation": { "type": "detail", "foreignKey": "master_id" }
    },
    {
      "id": "tab2",
      "label": "이력",
      "tableName": "detail_history",
      "relation": { "type": "detail", "foreignKey": "master_id" }
    }
  ]
}
```

#### v2-tabs-widget

탭 전환 레이아웃. 탭 내부에 컴포넌트를 배치할 수 있음.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| tabs | array | **필수**. 탭 배열 | `[{ id, label, order, disabled, components }]` |
| defaultTab | string | 기본 활성 탭 ID | - |
| orientation | string | 탭 방향 | `"horizontal"`, `"vertical"` |
| persistSelection | boolean | 선택 유지 | true/false |

**tabs 항목 구조**:

```json
{
  "id": "tab-basic",
  "label": "기본정보",
  "order": 0,
  "disabled": false,
  "components": [
    {
      "id": "tbl-basic",
      "componentType": "v2-table-list",
      "label": "기본정보",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 800, "height": 400 },
      "componentConfig": { "selectedTable": "basic_info" }
    }
  ]
}
```

#### v2-section-card

제목+테두리가 있는 그룹화 컨테이너. 폼 필드를 묶을 때 사용.

| 설정 | 타입 | 설명 |
|------|------|------|
| title | string | 섹션 제목 |
| collapsible | boolean | 접기/펼치기 가능 |
| padding | string | 내부 여백 |

#### v2-section-paper

배경색 기반 미니멀 그룹화 컨테이너.

#### v2-divider-line

영역 구분선 (가로/세로).

#### v2-split-line

캔버스 화면에서 좌우 영역을 분할하는 드래그 가능한 세로선. 디자이너 모드에서 사용.

#### v2-repeat-container

데이터 수만큼 내부 컴포넌트를 반복 렌더링.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| dataSourceType | string | 데이터 소스 | `"table"`, `"api"`, `"static"` |
| layout | string | 레이아웃 | `"vertical"`, `"horizontal"`, `"grid"` |
| gridColumns | number | 그리드 열 수 | 1~12 |

#### v2-repeater

인라인/모달/버튼 모드로 반복 데이터를 관리하는 컴포넌트. 주문 상세, 항목 리스트 등.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| mode | string | 동작 모드 | `"inline"` (인라인 편집), `"modal"` (모달 팝업), `"button"` (버튼 트리거) |

---

### 1.4 특수/비즈니스 컴포넌트

#### v2-button-primary

저장, 삭제, 조회 등 액션 버튼. 제어관리(dataflow)와 연결 가능.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| text | string | 버튼 텍스트 | 예: `"저장"`, `"삭제"` |
| actionType | string | 액션 유형 | `"save"`, `"delete"`, `"search"`, `"custom"` |
| variant | string | 스타일 | `"default"`, `"outline"`, `"destructive"`, `"ghost"` |

**제어관리 연결** (webTypeConfig.dataflowConfig):

```json
{
  "webTypeConfig": {
    "enableDataflowControl": true,
    "dataflowConfig": {
      "controlMode": "relationship",
      "relationshipConfig": {
        "relationshipId": "rel_001",
        "relationshipName": "수주확정",
        "executionTiming": "after"
      }
    }
  }
}
```

executionTiming 값:
- `"before"`: 메인 액션 전에 제어 실행 (조건 체크용)
- `"after"`: 메인 액션 후에 제어 실행 (후처리용)
- `"replace"`: 메인 액션 대신 제어만 실행

#### v2-timeline-scheduler

간트차트형 일정/계획 시각화. 드래그/리사이즈로 일정 변경 가능.

| 설정 | 타입 | 설명 | 값 |
|------|------|------|----|
| selectedTable | string | 스케줄 테이블명 | - |
| resourceTable | string | 리소스 테이블명 (설비/작업자) | - |
| fieldMapping | object | 필드 매핑 | `{ id, resourceId, title, startDate, endDate, status, progress }` |
| resourceFieldMapping | object | 리소스 필드 매핑 | `{ id, name, group }` |
| defaultZoomLevel | string | 초기 줌 | `"day"`, `"week"`, `"month"` |
| editable | boolean | 편집 가능 | true/false |
| allowDrag | boolean | 드래그 이동 허용 | true/false |
| allowResize | boolean | 리사이즈 허용 | true/false |

#### v2-approval-step

결재 단계 스테퍼 시각화. 결재 프로세스의 진행 상태를 단계별로 표시.

#### v2-bom-tree

BOM(Bill of Materials) 계층 트리 표시. 정전개(상위→하위)/역전개(하위→상위) 전환 가능.

#### v2-bom-item-editor

BOM 하위품목 트리 편집. 하위 부품 추가/수정/삭제/수량 변경 등.

---

## 2. 화면 패턴별 상세 구현 가이드

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

**적용 조건**: 단일 테이블 CRUD. 마스터-디테일 관계 없음.

**layout_data 예시**:

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "search_widget",
      "url": "@/lib/registry/components/v2-table-search-widget",
      "position": { "x": 0, "y": 0, "z": 1 },
      "size": { "width": 1920, "height": 100 },
      "displayOrder": 0,
      "overrides": {
        "label": "검색",
        "autoSelectFirstTable": true
      }
    },
    {
      "id": "table_list",
      "url": "@/lib/registry/components/v2-table-list",
      "position": { "x": 0, "y": 120, "z": 1 },
      "size": { "width": 1920, "height": 700 },
      "displayOrder": 1,
      "overrides": {
        "label": "품목 목록",
        "tableName": "item_info",
        "columns": [
          { "columnName": "item_code", "displayName": "품목코드", "visible": true, "sortable": true, "width": 120 },
          { "columnName": "item_name", "displayName": "품목명", "visible": true, "sortable": true, "width": 200 },
          { "columnName": "item_type", "displayName": "품목유형", "visible": true, "width": 100 },
          { "columnName": "unit", "displayName": "단위", "visible": true, "width": 80 }
        ],
        "pagination": { "enabled": true, "pageSize": 20 },
        "checkbox": { "enabled": true, "multiple": true }
      }
    }
  ],
  "gridSettings": { "columns": 12, "gap": 16, "padding": 16 },
  "screenResolution": { "width": 1920, "height": 1080 }
}
```

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

**적용 조건**: 마스터 테이블 선택 시 연관 디테일 테이블 표시. 두 테이블 간 FK 관계 존재.

**layout_data 예시**:

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "split_panel",
      "url": "@/lib/registry/components/v2-split-panel-layout",
      "position": { "x": 0, "y": 0, "z": 1 },
      "size": { "width": 1920, "height": 800 },
      "displayOrder": 0,
      "overrides": {
        "label": "수주관리",
        "splitRatio": 35,
        "resizable": true,
        "leftPanel": {
          "displayMode": "table",
          "tableName": "order_master",
          "columns": [
            { "columnName": "order_no", "displayName": "수주번호", "visible": true, "width": 120 },
            { "columnName": "customer_name", "displayName": "거래처", "visible": true, "width": 150 },
            { "columnName": "order_date", "displayName": "수주일자", "visible": true, "width": 100 },
            { "columnName": "status", "displayName": "상태", "visible": true, "width": 80 }
          ],
          "showSearch": true,
          "showAdd": true,
          "showDelete": true,
          "addButton": { "enabled": true, "mode": "auto" },
          "deleteButton": { "enabled": true, "confirmMessage": "삭제하시겠습니까?" }
        },
        "rightPanel": {
          "displayMode": "table",
          "tableName": "order_detail",
          "relation": {
            "type": "detail",
            "foreignKey": "order_master_id",
            "leftColumn": "id",
            "rightColumn": "order_master_id"
          },
          "columns": [
            { "columnName": "item_code", "displayName": "품목코드", "visible": true, "width": 120 },
            { "columnName": "item_name", "displayName": "품목명", "visible": true, "width": 150 },
            { "columnName": "quantity", "displayName": "수량", "visible": true, "width": 80, "editable": true },
            { "columnName": "unit_price", "displayName": "단가", "visible": true, "width": 100, "editable": true }
          ],
          "addButton": { "enabled": true },
          "deleteButton": { "enabled": true }
        }
      }
    }
  ],
  "gridSettings": { "columns": 12, "gap": 16, "padding": 16 },
  "screenResolution": { "width": 1920, "height": 1080 }
}
```

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

**적용 조건**: 마스터-디테일에서 우측에 여러 종류의 상세 정보를 탭으로 분리.

**차이점**: rightPanel에 `additionalTabs` 배열 추가.

```json
{
  "rightPanel": {
    "displayMode": "table",
    "tableName": "customer_basic",
    "relation": {
      "type": "detail",
      "foreignKey": "customer_id"
    },
    "additionalTabs": [
      {
        "id": "tab-basic",
        "label": "기본정보",
        "tableName": "customer_basic",
        "relation": { "type": "detail", "foreignKey": "customer_id" }
      },
      {
        "id": "tab-history",
        "label": "거래이력",
        "tableName": "customer_history",
        "relation": { "type": "detail", "foreignKey": "customer_id" }
      },
      {
        "id": "tab-files",
        "label": "첨부파일",
        "tableName": "customer_files",
        "relation": { "type": "detail", "foreignKey": "customer_id" }
      }
    ]
  }
}
```

---

## 3. 제어관리 (비즈니스 로직) 설정

### 3.1 개요

V2 컴포넌트는 **UI만 담당**한다. 버튼 클릭 시 실행되는 비즈니스 로직(INSERT/UPDATE/DELETE, 조건 체크, 외부 호출 등)은 `dataflow_diagrams` 테이블에서 별도 설정한다.

### 3.2 설정 위치

| 구분 | 저장 위치 | 용도 |
|------|----------|------|
| 버튼-제어 연결 | `screen_layouts_v2` → 컴포넌트 `webTypeConfig.dataflowConfig` | 어떤 버튼이 어떤 제어를 실행하는지 |
| 제어 정의 | `dataflow_diagrams` → `control`, `plan` JSONB | 조건, 액션, 필드 매핑 |
| 노드 플로우 | `node_flows` → `flow_data` JSONB | 복잡한 다단계 플로우 |

### 3.3 실행 흐름

```
[버튼 클릭] v2-button-primary
      │
      ▼
[설정 확인] webTypeConfig.dataflowConfig
      │
      ├─ controlMode: "relationship" → dataflow_diagrams 실행
      ├─ controlMode: "flow" → node_flows 실행
      └─ controlMode: "none" → 기본 액션만 실행
      │
      ▼
[실행기] ImprovedButtonActionExecutor
      │
      ├─ 1. Before 제어 (executionTiming = "before")
      │     └─ 조건 체크 → 실패 시 중단
      │
      ├─ 2. Main 액션 (executionTiming ≠ "replace"일 때)
      │     └─ save / delete / update 실행
      │
      └─ 3. After 제어 (executionTiming = "after")
            └─ 후처리 (이력 저장, 상태 변경, 외부 호출 등)
```

### 3.4 dataflow_diagrams 설정 예시

**시나리오**: 수주 목록에서 [확정] 버튼 클릭 → 상태를 '확정'으로 변경 + 이력 테이블에 기록

```json
{
  "control": [
    {
      "conditions": [
        { "field": "status", "operator": "=", "value": "대기", "dataType": "string" }
      ],
      "triggerType": "update"
    }
  ],
  "plan": [
    {
      "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" },
            { "targetField": "action", "defaultValue": "확정" }
          ]
        }
      ]
    }
  ]
}
```

---

## 4. 화면 개발 체크리스트 (AI 에이전트용)

화면 개발 요청을 받았을 때 이 순서대로 확인한다.

### Step 1: 요구사항 분석

```
□ 어떤 테이블을 사용하는가? (메인 테이블, 디테일 테이블)
□ 테이블 간 관계는? (FK, 1:N, M:N)
□ 어떤 패턴인가? (A~G 중 선택, 의사결정 트리 참조)
□ 어떤 버튼이 필요한가? (저장, 삭제, 확정 등)
□ 비즈니스 로직이 있는가? (상태 변경, 이력 기록, 외부 호출 등)
```

### Step 2: DB 테이블 생성

```
□ 모든 컬럼 VARCHAR(500)
□ 기본 5개 컬럼 포함 (id, created_date, updated_date, writer, company_code)
□ table_labels, table_type_columns, column_labels 메타데이터 등록
□ company_code 인덱스 생성
```

### Step 3: screen_definitions INSERT

```sql
INSERT INTO screen_definitions (screen_name, screen_code, table_name, company_code, is_active)
VALUES ('화면명', '{company_code}_순번', '메인_테이블', '{company_code}', 'Y');
```

### Step 4: screen_layouts_v2 INSERT

```sql
INSERT INTO screen_layouts_v2 (screen_id, company_code, layer_id, layout_data)
VALUES ({screen_id}, '{company_code}', 1, '{패턴별 JSON}');
```

### Step 5: dataflow_diagrams INSERT (비즈니스 로직 필요 시)

```
□ 버튼별 액션 정의
□ 조건 설정 (어떤 상태일 때만 실행)
□ 필드 매핑 (소스→타겟)
□ 실행 타이밍 (before/after/replace)
```

### Step 6: menu_info INSERT

```sql
INSERT INTO menu_info (screen_id, menu_url, company_code, ...)
VALUES ({screen_id}, '/screen/{screen_code}', '{company_code}', ...);
```

### Step 7: 멀티테넌시 검증

```
□ 테이블에 company_code 컬럼 존재
□ 모든 SELECT에 company_code 필터링
□ INSERT에 company_code 포함
□ UPDATE/DELETE WHERE절에 company_code 포함
□ JOIN에 company_code 매칭
```

---

## 5. 자주 묻는 질문 (FAQ)

### Q: v2-table-list와 v2-table-grouped 중 어떤 걸 써야 하나?

**A**: 데이터를 특정 컬럼 기준으로 묶어서 접기/펼치기가 필요하면 `v2-table-grouped`, 아니면 `v2-table-list`. 예를 들어 "카테고리별 품목 목록"은 `v2-table-grouped`, "품목 전체 목록"은 `v2-table-list`.

### Q: 마스터-디테일에서 탭을 사용하고 싶은데?

**A**: `v2-split-panel-layout`의 rightPanel에 `additionalTabs` 배열을 설정한다. 별도의 `v2-tabs-widget`을 배치할 필요 없다.

### Q: BOM 화면은 어떻게 만드나?

**A**: `v2-split-panel-layout`의 좌측에 `v2-bom-tree` (또는 `v2-table-list`), 우측에 `v2-bom-item-editor`를 배치한다. 트리 컴포넌트가 자체적으로 정전개/역전개를 지원한다.

### Q: 버튼 클릭 시 특정 로직을 실행하고 싶은데?

**A**: `v2-button-primary`의 `webTypeConfig.dataflowConfig`에 제어관리를 연결한다. `dataflow_diagrams` 테이블에 실행할 액션(INSERT/UPDATE/DELETE)과 조건을 정의한다.

### Q: 검색 기능은 어떻게 추가하나?

**A**: `v2-table-search-widget`을 `v2-table-list` 위에 배치한다. `autoSelectFirstTable: true`로 설정하면 자동으로 화면의 첫 번째 테이블과 연동된다.

### Q: 파일 업로드는?

**A**: `v2-file-upload` 컴포넌트를 사용한다. 폼 내 배치하여 파일/이미지 업로드를 처리한다.

### Q: 결재 프로세스를 표시하고 싶은데?

**A**: `v2-approval-step` 컴포넌트를 사용한다. 결재 단계를 스테퍼 형태로 시각화한다.

### Q: 인라인 편집이 가능한가?

**A**: `v2-table-list`의 columns에서 `editable: true`로 설정하면 해당 컬럼의 셀을 직접 편집할 수 있다. 단, 복잡한 편집은 모달 편집(`v2-split-panel-layout`의 editButton.mode = "modal")을 권장한다.

### Q: 화면에 집계(합계, 평균 등)를 표시하고 싶은데?

**A**: `v2-aggregation-widget`을 사용하여 테이블 데이터의 합계, 평균, 개수 등을 카드 형태로 표시한다. 또는 `v2-status-count`로 상태별 건수를 표시한다.

---

## 6. 컴포넌트 선택 빠른 참조표

| 요구사항 | 컴포넌트 |
|----------|----------|
| 데이터 목록 보기 | `v2-table-list` |
| 데이터 검색/필터 | `v2-table-search-widget` |
| 좌우 분할 (마스터-디테일) | `v2-split-panel-layout` |
| 그룹별 묶기 (접기/펼치기) | `v2-table-grouped` |
| 탭 전환 | `v2-tabs-widget` 또는 `v2-split-panel-layout`의 additionalTabs |
| 카드 형태 보기 | `v2-card-display` |
| 피벗/집계 분석 | `v2-pivot-grid` |
| 간트차트/일정 | `v2-timeline-scheduler` |
| BOM 트리 | `v2-bom-tree` + `v2-bom-item-editor` |
| 텍스트 입력 | `v2-input` |
| 선택 (드롭다운 등) | `v2-select` |
| 날짜 입력 | `v2-date` |
| 파일 업로드 | `v2-file-upload` |
| 액션 버튼 | `v2-button-primary` |
| 자동 채번 | `v2-numbering-rule` |
| 카테고리 관리 | `v2-category-manager` |
| 결재 단계 표시 | `v2-approval-step` |
| 상태별 건수 | `v2-status-count` |
| 합계/평균 카드 | `v2-aggregation-widget` |
| 구분선 | `v2-divider-line` |
| 그룹 컨테이너 | `v2-section-card` 또는 `v2-section-paper` |
| 데이터 반복 | `v2-repeat-container` 또는 `v2-repeater` |
| 공정 작업기준 | `v2-process-work-standard` |
| 품목 라우팅 | `v2-item-routing` |
| 미디어 표시 | `v2-media` |
| 랙 구조 | `v2-rack-structure` |
| 위치 교환 | `v2-location-swap-selector` |