# V2 컴포넌트 가이드

> 작성일: 2026-01-26
> 목적: V2 컴포넌트 전반적인 아키텍처, 설계 원칙, 사용법 정리

---

## 1. V2 컴포넌트 개요

### 1.1 V2란?

V2(Version 2) 컴포넌트는 기존 레거시 컴포넌트의 문제점을 해결하고 다음 목표를 달성하기 위해 재설계된 컴포넌트입니다:

- **느슨한 결합 (Loose Coupling)**: 컴포넌트 간 직접 의존성 제거
- **장애 격리 (Fault Isolation)**: 한 컴포넌트 오류가 다른 컴포넌트에 영향 없음
- **화면 복제 용이성**: 메뉴/회사 종속적인 설정 제거
- **점진적 마이그레이션**: 레거시 컴포넌트와 공존 가능

### 1.2 V2 vs 레거시 비교

| 항목 | 레거시 | V2 |
|------|--------|-----|
| 이벤트 통신 | `window.dispatchEvent` | V2 EventBus |
| 에러 처리 | 전역 오류 → 전체 중단 | ErrorBoundary → 해당만 실패 |
| 전역 상태 | `window.__xxx` | Context/Store |
| 채번/카테고리 | 메뉴에 종속 | 테이블 컬럼에 종속 |
| 설정 저장 | componentConfig에 ID 저장 | 표시 옵션만 저장 |

---

## 2. V2 컴포넌트 목록 (19개)

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

| 컴포넌트 ID | 이름 | 설명 |
|------------|------|------|
| `v2-split-panel-layout` | 분할 패널 레이아웃 | 좌우/상하 분할 레이아웃 |
| `v2-section-card` | 섹션 카드 | 카드 형태 컨테이너 |
| `v2-section-paper` | 섹션 페이퍼 | 페이퍼 형태 컨테이너 |
| `v2-tabs-widget` | 탭 위젯 | 탭 기반 컨테이너 |
| `v2-repeat-container` | 리피터 컨테이너 | 반복 섹션 컨테이너 |
| `v2-divider-line` | 구분선 | 시각적 구분선 |

### 2.2 데이터 표시 컴포넌트

| 컴포넌트 ID | 이름 | 설명 |
|------------|------|------|
| `v2-table-list` | 테이블 리스트 | 데이터 그리드/테이블 |
| `v2-card-display` | 카드 디스플레이 | 카드 형태 데이터 표시 |
| `v2-text-display` | 텍스트 디스플레이 | 텍스트 표시 |
| `v2-pivot-grid` | 피벗 그리드 | 피벗 테이블 |
| `v2-aggregation-widget` | 집계 위젯 | 데이터 집계 표시 |

### 2.3 입력/관리 컴포넌트

| 컴포넌트 ID | 이름 | 설명 |
|------------|------|------|
| `v2-button-primary` | 기본 버튼 | 저장/삭제/모달 등 액션 버튼 |
| `v2-numbering-rule` | 채번 규칙 | 채번 규칙 설정 컴포넌트 |
| `v2-category-manager` | 카테고리 관리 | 트리 기반 카테고리 관리 |
| `v2-table-search-widget` | 테이블 검색 위젯 | 테이블 검색 UI |
| `v2-location-swap-selector` | 위치 교환 선택기 | 출발지/도착지 선택 |

### 2.4 특수 컴포넌트

| 컴포넌트 ID | 이름 | 설명 |
|------------|------|------|
| `v2-rack-structure` | 렉 구조 | 창고 렉 구조 표시 |
| `v2-repeat-screen-modal` | 반복 화면 모달 | 반복 가능한 화면 모달 |
| `v2-repeater` | 통합 리피터 | 통합 리피터 테이블 |

---

## 3. V2 Core 인프라

### 3.1 파일 구조

```
frontend/lib/v2-core/
├── index.ts                    # 메인 내보내기
├── init.ts                     # 앱 초기화
├── events/
│   ├── index.ts
│   ├── types.ts               # 이벤트 타입 정의 (30+)
│   └── EventBus.ts            # 타입 안전한 이벤트 버스
├── components/
│   ├── index.ts
│   └── V2ErrorBoundary.tsx    # 에러 바운더리
└── adapters/
    ├── index.ts
    └── LegacyEventAdapter.ts  # 레거시 브릿지
```

### 3.2 V2 EventBus

타입 안전한 Pub/Sub 이벤트 시스템입니다.

**특징:**
- 타입 안전한 이벤트 발행/구독
- 에러 격리 (Promise.allSettled)
- 타임아웃 및 재시도 지원
- 디버그 모드 지원

**사용법:**

```typescript
import { v2EventBus, V2_EVENTS } from "@/lib/v2-core";

// 이벤트 발행
v2EventBus.emit(V2_EVENTS.TABLE_REFRESH, {
  tableName: "item_info",
  target: "single",
});

// 이벤트 구독
const unsubscribe = v2EventBus.subscribe(
  V2_EVENTS.TABLE_REFRESH,
  (payload) => {
    console.log("테이블 새로고침:", payload.tableName);
  },
  { componentId: "my-component" }
);

// 정리 (useEffect cleanup에서)
useEffect(() => {
  return () => unsubscribe();
}, []);
```

### 3.3 V2 ErrorBoundary

컴포넌트별 에러 격리를 제공합니다.

**특징:**
- 에러 발생 시 해당 컴포넌트만 폴백 UI 표시
- 3가지 폴백 스타일 (minimal, compact, full)
- 재시도 기능
- 에러 이벤트 자동 발행

**사용법:**

```tsx
import { V2ErrorBoundary } from "@/lib/v2-core";

// 컴포넌트 래핑
<V2ErrorBoundary
  componentId="my-component-id"
  componentType="MyComponent"
  fallbackStyle="compact"
>
  <MyComponent {...props} />
</V2ErrorBoundary>
```

### 3.4 Legacy Event Adapter

기존 CustomEvent와 V2 EventBus 간 양방향 브릿지입니다.

**특징:**
- 레거시 `window.dispatchEvent` → V2 EventBus 자동 변환
- V2 EventBus → 레거시 CustomEvent 자동 변환
- 무한 루프 방지
- 점진적 마이그레이션 지원

---

## 4. 이벤트 시스템

### 4.1 주요 이벤트 목록

| 이벤트 | 설명 | 발행자 | 구독자 |
|--------|------|--------|--------|
| `v2:table:refresh` | 테이블 새로고침 | v2-button-primary | v2-table-list |
| `v2:table:data:change` | 테이블 데이터 변경 | v2-table-list | v2-aggregation-widget |
| `v2:form:save:collect` | 폼 저장 전 데이터 수집 | buttonActions | v2-repeat-container, V2Repeater |
| `v2:modal:close` | 모달 닫기 | v2-button-primary | EditModal |
| `v2:modal:save:success` | 모달 저장 성공 | v2-button-primary | EditModal |
| `v2:repeater:save` | 리피터 저장 | buttonActions | V2Repeater |
| `v2:component:error` | 컴포넌트 에러 | V2ErrorBoundary | 로깅/모니터링 |

### 4.2 이벤트 흐름 다이어그램

```
┌─────────────────────────────────────────────────────────────────┐
│                     V2 EventBus (중앙)                          │
│                                                                 │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
│   │TABLE_REFRESH│    │TABLE_DATA   │    │FORM_SAVE    │        │
│   │             │    │   _CHANGE   │    │  _COLLECT   │        │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘        │
└──────────│──────────────────│──────────────────│────────────────┘
           │                  │                  │
           ▼                  ▼                  ▼
   ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
   │ v2-table-list │  │v2-aggregation │  │v2-repeat      │
   │               │  │    -widget    │  │  -container   │
   └───────────────┘  └───────────────┘  └───────────────┘
```

---

## 5. 채번/카테고리 시스템

### 5.1 설계 원칙

**핵심: 메뉴 종속성 제거**

- ❌ 이전: 채번/카테고리 설정이 화면 레이아웃(componentConfig)에 저장
- ✅ 현재: 채번/카테고리 설정이 테이블 컬럼 정의에 저장

### 5.2 채번 규칙 동작 방식

```
1. 테이블 타입 관리에서 컬럼에 input_type='numbering' 설정
2. 해당 컬럼에 numbering_rule_id 연결 (테이블 정의에 저장)
3. 화면에서 해당 컬럼 사용 시 자동으로 채번 규칙 적용
4. 화면 복제해도 테이블 정의는 그대로 → 채번 규칙 유지
```

**관련 테이블:**
- `numbering_rules_test`: 채번 규칙 마스터
- `numbering_rule_parts_test`: 채번 규칙 파트
- `column_labels`: 컬럼별 input_type 및 설정 저장

### 5.3 카테고리 동작 방식

```
1. 테이블 타입 관리에서 컬럼에 input_type='category' 설정
2. category_values_test 테이블에 카테고리 값 저장 (트리 구조)
3. 화면에서 해당 컬럼 사용 시 자동으로 카테고리 드롭다운 표시
4. 화면 복제해도 테이블 정의는 그대로 → 카테고리 유지
```

**관련 테이블:**
- `category_values_test`: 카테고리 값 (트리 구조, 3단계 지원)
  - `parent_id`: 부모 노드 ID
  - `level`: 깊이 (1=대분류, 2=중분류, 3=소분류)
  - `path`: 경로 (예: "1.2.3")

### 5.4 화면 복제 시 이점

```
이전 (메뉴 종속):
화면 복제 → 채번/카테고리 ID도 복제 → 잘못된 참조 → 수동 수정 필요

현재 (테이블 종속):
화면 복제 → 테이블 컬럼 정의 참조 → 자동으로 올바른 채번/카테고리 적용
```

---

## 6. 설정 패널 (ConfigPanel) 가이드

### 6.1 설계 원칙

V2 컴포넌트의 ConfigPanel은 **표시/동작 옵션만** 저장합니다.

**저장해야 하는 것:**
- 뷰 모드 (tree/list/card 등)
- 레이아웃 설정 (너비, 높이, 패딩)
- 표시 옵션 (readonly, showPreview 등)
- 스타일 설정 (색상, 폰트 등)

**저장하면 안 되는 것:**
- ❌ 특정 채번 규칙 ID (numberingRuleId)
- ❌ 특정 카테고리 ID (categoryId)
- ❌ 메뉴 ID (menuObjid, menu_id)
- ❌ 회사 코드 (companyCode) - 런타임에 결정

### 6.2 ConfigPanel 예시

```tsx
// ✅ 올바른 ConfigPanel
export const MyComponentConfigPanel: React.FC<Props> = ({ config, onChange }) => {
  return (
    <div className="space-y-4">
      {/* 표시 옵션만 설정 */}
      <div>
        <Label>뷰 모드</Label>
        <Select 
          value={config.viewMode} 
          onValueChange={(v) => onChange({ ...config, viewMode: v })}
        >
          <SelectItem value="list">리스트</SelectItem>
          <SelectItem value="card">카드</SelectItem>
        </Select>
      </div>
      
      <div>
        <Label>읽기 전용</Label>
        <Switch
          checked={config.readonly}
          onCheckedChange={(v) => onChange({ ...config, readonly: v })}
        />
      </div>
    </div>
  );
};

// ❌ 잘못된 ConfigPanel
export const BadConfigPanel: React.FC<Props> = ({ config, onChange }) => {
  return (
    <div>
      {/* 채번 규칙 ID를 저장하면 안 됨! */}
      <Select 
        value={config.numberingRuleId}  // ❌
        onValueChange={(v) => onChange({ ...config, numberingRuleId: v })}
      >
        {numberingRules.map(rule => (
          <SelectItem value={rule.id}>{rule.name}</SelectItem>
        ))}
      </Select>
    </div>
  );
};
```

---

## 7. 결합도 현황

### 7.1 V2 컴포넌트 결합도 점수

| 결합도 수준 | 개수 | 컴포넌트 |
|------------|------|---------|
| 🔴 높음 (7-10점) | 0개 | - (마이그레이션 완료) |
| 🟠 중간 (4-6점) | 4개 | v2-repeat-container, v2-split-panel-layout, v2-aggregation-widget, v2-tabs-widget |
| 🟢 낮음 (1-3점) | 15개 | 나머지 모든 V2 컴포넌트 |

### 7.2 마이그레이션 완료 컴포넌트

| 컴포넌트 | V2 EventBus | ErrorBoundary | 레거시 호환 |
|---------|-------------|---------------|-------------|
| v2-button-primary | ✅ | ✅ | ✅ |
| v2-table-list | ✅ | ✅ | ✅ |
| V2Repeater | ✅ | ✅ | ✅ |

### 7.3 장애 격리 검증

```
v2-button-primary 에러 발생 시:
├── V2ErrorBoundary 캐치 → 버튼만 에러 UI 표시
├── v2-table-list: 정상 동작 ✅
└── V2Repeater: 정상 동작 ✅

v2-table-list 에러 발생 시:
├── V2ErrorBoundary 캐치 → 테이블만 에러 UI 표시
├── v2-button-primary: 정상 동작 ✅
└── v2-aggregation-widget: 데이터 없음 상태 ✅
```

---

## 8. V2 폼 컴포넌트

### 8.1 목록 (11개)

| 컴포넌트 | 파일 | 용도 |
|---------|------|------|
| V2Input | V2Input.tsx | 텍스트/숫자/이메일/채번 입력 |
| V2Select | V2Select.tsx | 선택박스/라디오/체크박스/카테고리 |
| V2Date | V2Date.tsx | 날짜/시간 입력 |
| V2Repeater | V2Repeater.tsx | 리피터 테이블 |
| V2Layout | V2Layout.tsx | 레이아웃 컨테이너 |
| V2Group | V2Group.tsx | 그룹 컨테이너 |
| V2Hierarchy | V2Hierarchy.tsx | 계층 구조 표시 |
| V2List | V2List.tsx | 리스트 표시 |
| V2Media | V2Media.tsx | 파일/이미지/비디오 |
| V2Biz | V2Biz.tsx | 비즈니스 컴포넌트 |
| V2FormContext | V2FormContext.tsx | 폼 상태 관리 |

### 8.2 inputType 자동 처리

V2 컴포넌트는 `inputType`에 따라 자동으로 적절한 UI를 렌더링합니다:

```typescript
// V2Input.tsx
switch (inputType) {
  case "numbering":
    // 채번 규칙 자동 조회 및 코드 생성
    break;
  case "text":
  case "email":
  case "phone":
    // 텍스트 입력
    break;
}

// V2Select.tsx
switch (inputType) {
  case "category":
    // 카테고리 값 자동 조회 및 드롭다운 표시
    break;
  case "select":
  case "radio":
    // 일반 선택
    break;
}
```

---

## 9. 개발 가이드

### 9.1 새 V2 컴포넌트 생성

```bash
frontend/lib/registry/components/v2-my-component/
├── index.ts                    # 컴포넌트 정의 (createComponentDefinition)
├── types.ts                    # 타입 정의
├── MyComponent.tsx             # 메인 컴포넌트
├── MyComponentRenderer.tsx     # 렌더러 (선택)
├── MyComponentConfigPanel.tsx  # 설정 패널
└── README.md                   # 문서
```

### 9.2 컴포넌트 정의 템플릿

```typescript
// index.ts
import { createComponentDefinition, ComponentCategory } from "@/types/component";
import { MyComponent } from "./MyComponent";
import { MyComponentConfigPanel } from "./MyComponentConfigPanel";
import { defaultConfig } from "./types";

export const V2MyComponentDefinition = createComponentDefinition({
  id: "v2-my-component",
  name: "내 컴포넌트",
  nameEng: "My Component",
  description: "컴포넌트 설명",
  category: ComponentCategory.DISPLAY,
  component: MyComponent,
  defaultConfig,
  configPanel: MyComponentConfigPanel,
  tags: ["태그1", "태그2"],
});
```

### 9.3 V2 EventBus 사용 체크리스트

- [ ] V2 EventBus import: `import { v2EventBus, V2_EVENTS } from "@/lib/v2-core";`
- [ ] 이벤트 구독 시 `componentId` 설정
- [ ] `useEffect` cleanup에서 `unsubscribe()` 호출
- [ ] 레거시 호환 필요 시 `window.addEventListener`도 유지 (점진적 마이그레이션)

### 9.4 V2 ErrorBoundary 사용 체크리스트

- [ ] 컴포넌트 export에서 ErrorBoundary 래핑
- [ ] `componentId`와 `componentType` 설정
- [ ] 적절한 `fallbackStyle` 선택

---

## 10. 참고 자료

### 10.1 관련 문서

- [V2 컴포넌트 결합도 분석](./V2_COMPONENT_COUPLING_ANALYSIS.md)
- [채번 규칙 가이드](../frontend/lib/registry/components/v2-numbering-rule/README.md)
- [카테고리 트리 구조](../db/migrations/042_create_category_values_test.sql)

### 10.2 관련 파일

```
V2 Core:
- frontend/lib/v2-core/

V2 컴포넌트:
- frontend/lib/registry/components/v2-*/

V2 폼 컴포넌트:
- frontend/components/v2/

채번/카테고리 테스트 테이블:
- db/migrations/040_create_numbering_rules_test.sql
- db/migrations/042_create_category_values_test.sql
```

### 10.3 디버깅

개발 환경에서 다음 전역 객체로 상태 확인 가능:

```javascript
// 브라우저 콘솔에서
window.__v2EventBus.printState()  // EventBus 구독 상태
window.__legacyEventAdapter.getMappings()  // 레거시 이벤트 매핑
```

---

## 11. 향후 계획

### 11.1 단기 (1-2주)

- [ ] 나머지 중간 결합도 컴포넌트 마이그레이션
  - v2-repeat-container
  - v2-split-panel-layout
  - v2-aggregation-widget
  - v2-tabs-widget

### 11.2 중기 (1개월)

- [ ] buttonActions.ts 분할 (7,145줄 → 여러 서비스)
- [ ] 전역 상태 (`window.__`) 제거
- [ ] Zustand/Context로 상태 관리 전환

### 11.3 장기

- [ ] 레거시 컴포넌트 완전 제거
- [ ] CustomEvent 완전 제거
- [ ] V2 전용 모드 도입

---

## 부록: V2 컴포넌트 위치

```
frontend/lib/registry/components/
├── v2-aggregation-widget/
├── v2-button-primary/
├── v2-card-display/
├── v2-category-manager/
├── v2-divider-line/
├── v2-location-swap-selector/
├── v2-numbering-rule/
├── v2-pivot-grid/
├── v2-rack-structure/
├── v2-repeat-container/
├── v2-repeat-screen-modal/
├── v2-section-card/
├── v2-section-paper/
├── v2-split-panel-layout/
├── v2-table-list/
├── v2-table-search-widget/
├── v2-tabs-widget/
├── v2-text-display/
└── v2-repeater/
```

