# V2 마이그레이션 학습노트 (DDD1542 전용)

> **목적**: 마이그레이션 작업 전 완벽한 이해를 위한 개인 학습노트
> **작성일**: 2026-02-03
> **절대 규칙**: 모르면 물어보기, 추측 금지

---

## 1. 가장 중요한 핵심 (이전 신하가 실패한 이유)

### 1.1 "component" vs "v2-input" 차이

```
[잘못된 상태]              [올바른 상태]
┌──────────────────┐      ┌──────────────────┐
│ component        │      │ v2-input         │
│ 업체코드         │      │ 업체코드         │
│ "자동 생성됩니다" │      │ "자동 생성됩니다" │
└──────────────────┘      └──────────────────┘
    ↑                         ↑
    테이블-컬럼 연결 없음        table_name + column_name 연결됨
```

**핵심**: 컬럼을 왼쪽 패널에서 **드래그**해야 올바른 연결이 생성됨

### 1.2 올바른 컴포넌트 생성 방법

```
[왼쪽 패널: 테이블 컬럼 목록]
운송업체 (8개)
├── 업체코드 [numbering]  ─드래그→  화면 캔버스  →  v2-numbering-rule (또는 v2-input)
├── 업체명 [text]         ─드래그→  화면 캔버스  →  v2-input
├── 유형 [category]       ─드래그→  화면 캔버스  →  v2-select
├── 연락처 [text]         ─드래그→  화면 캔버스  →  v2-input
└── ...
```

### 1.3 input_type → V2 컴포넌트 매핑

| table_type_columns.input_type | V2 컴포넌트 | 연동 테이블 |
|-------------------------------|-------------|-------------|
| text | v2-input | - |
| number | v2-input (type=number) | - |
| date | v2-date | - |
| category | v2-select | category_values |
| numbering | v2-numbering-rule 또는 v2-input | numbering_rules |
| entity | v2-entity-search | 엔티티 조인 |

---

## 2. V1 vs V2 구조 차이

### 2.1 테이블 구조

```
V1 (본서버: screen_layouts)          V2 (개발서버: screen_layouts_v2)
──────────────────────────────────────────────────────────────────
- 컴포넌트별 1개 레코드              - 화면당 1개 레코드
- properties JSONB                   - layout_data JSONB
- component_type VARCHAR             - url (컴포넌트 경로)
- menu_objid 기반 채번/카테고리      - table_name + column_name 기반
```

### 2.2 V2 layout_data 구조

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/v2-table-list",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 100, "height": 50 },
      "displayOrder": 0,
      "overrides": {
        "tableName": "inspection_standard",
        "columns": ["id", "name", "status"]
      }
    }
  ],
  "updatedAt": "2026-02-03T12:00:00Z"
}
```

### 2.3 컴포넌트 URL 매핑

```typescript
const V1_TO_V2_URL_MAPPING = {
  'table-list':          '@/lib/registry/components/v2-table-list',
  'button-primary':      '@/lib/registry/components/v2-button-primary',
  'text-input':          '@/lib/registry/components/v2-input',
  'select-basic':        '@/lib/registry/components/v2-select',
  'date-input':          '@/lib/registry/components/v2-date',
  'entity-search-input': '@/lib/registry/components/v2-entity-search',
  'category-manager':    '@/lib/registry/components/v2-category-manager',
  'numbering-rule':      '@/lib/registry/components/v2-numbering-rule',
  'tabs-widget':         '@/lib/registry/components/v2-tabs-widget',
  'split-panel-layout':  '@/lib/registry/components/v2-split-panel-layout',
};
```

---

## 3. 데이터 타입 관리 (V2)

### 3.1 핵심 테이블 관계

```
table_type_columns (컬럼 타입 정의)
├── input_type = 'category'  → category_values (table_name + column_name)
├── input_type = 'numbering' → numbering_rules (detail_settings.numberingRuleId)
├── input_type = 'entity'    → 엔티티 조인
└── input_type = 'text', 'number', 'date', etc.
```

### 3.2 category_values 조회 쿼리

```sql
-- 특정 테이블.컬럼의 카테고리 값 조회
SELECT value_id, value_code, value_label, parent_value_id, depth
FROM category_values
WHERE table_name = '테이블명'
  AND column_name = '컬럼명'
  AND company_code = 'COMPANY_7'
ORDER BY value_order;
```

### 3.3 numbering_rules 연결 방식

```json
// table_type_columns.detail_settings
{
  "numberingRuleId": "rule-xxx"
}

// numbering_rules에서 해당 rule 조회
SELECT * FROM numbering_rules WHERE rule_id = 'rule-xxx';
```

---

## 4. V2 컴포넌트 목록 (23개)

### 4.1 입력 컴포넌트

| ID | 이름 | 용도 |
|----|------|------|
| v2-input | 입력 | 텍스트, 숫자, 비밀번호, 이메일 |
| v2-select | 선택 | 드롭다운, 라디오, 체크박스 |
| v2-date | 날짜 | 날짜, 시간, 날짜범위 |

### 4.2 표시 컴포넌트

| ID | 이름 | 용도 |
|----|------|------|
| v2-text-display | 텍스트 표시 | 라벨, 제목 |
| v2-card-display | 카드 디스플레이 | 카드 형태 데이터 |
| v2-aggregation-widget | 집계 위젯 | 합계, 평균, 개수 |

### 4.3 테이블/데이터 컴포넌트

| ID | 이름 | 용도 |
|----|------|------|
| v2-table-list | 테이블 리스트 | 데이터 그리드 |
| v2-table-search-widget | 검색 필터 | 테이블 검색 |
| v2-pivot-grid | 피벗 그리드 | 다차원 분석 |
| v2-table-grouped | 그룹화 테이블 | 그룹별 접기/펼치기 |

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

| ID | 이름 | 용도 |
|----|------|------|
| v2-split-panel-layout | 분할 패널 | 마스터-디테일 |
| v2-tabs-widget | 탭 위젯 | 탭 전환 |
| v2-section-card | 섹션 카드 | 제목+테두리 그룹 |
| v2-section-paper | 섹션 페이퍼 | 배경색 그룹 |
| v2-divider-line | 구분선 | 영역 구분 |
| v2-repeat-container | 리피터 컨테이너 | 데이터 반복 |
| v2-unified-repeater | 통합 리피터 | 인라인/모달/버튼 |

### 4.5 액션/특수 컴포넌트

| ID | 이름 | 용도 |
|----|------|------|
| v2-button-primary | 기본 버튼 | 저장, 삭제 등 |
| v2-numbering-rule | 채번 규칙 | 자동 코드 생성 |
| v2-category-manager | 카테고리 관리자 | 카테고리 관리 |
| v2-location-swap-selector | 위치 교환 | 위치 선택 |
| v2-rack-structure | 랙 구조 | 창고 랙 시각화 |

---

## 5. 화면 패턴 (5가지)

### 5.1 패턴 A: 기본 마스터 화면

```
사용 조건: 단일 테이블 CRUD

┌─────────────────────────────────────────────────┐
│ v2-table-search-widget                          │
├─────────────────────────────────────────────────┤
│ v2-table-list                                   │
│ [신규] [삭제] v2-button-primary                 │
└─────────────────────────────────────────────────┘
```

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

```
사용 조건: 마스터 선택 → 디테일 표시

┌──────────────────┬──────────────────────────────┐
│ 마스터 리스트    │ 디테일 리스트                │
│ v2-table-list    │ v2-table-list                │
│                  │ (relation: foreignKey)       │
└──────────────────┴──────────────────────────────┘
          v2-split-panel-layout
```

**필수 설정:**
```json
{
  "leftPanel": { "tableName": "master_table" },
  "rightPanel": {
    "tableName": "detail_table",
    "relation": { "type": "detail", "foreignKey": "master_id" }
  },
  "splitRatio": 30
}
```

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

```
┌──────────────────┬──────────────────────────────┐
│ 마스터 리스트    │ v2-tabs-widget               │
│ v2-table-list    │ ├─ 탭1: v2-table-list        │
│                  │ ├─ 탭2: v2-table-list        │
│                  │ └─ 탭3: 폼 컴포넌트들        │
└──────────────────┴──────────────────────────────┘
          v2-split-panel-layout
```

---

## 6. 모달 처리 방식 변경

### 6.1 V1 (본서버)

```
화면 A (screen_id: 142) - 검사장비관리
    └── 버튼 클릭 → 화면 B (screen_id: 143) - 검사장비 등록모달 (별도 screen_id)
```

### 6.2 V2 (개발서버)

```
화면 A (screen_id: 142) - 검사장비관리
    └── layout_data.components[] 내에 v2-dialog-form 또는 overlay 포함
```

**핵심**: V2에서는 모달을 별도 화면이 아닌, 부모 화면의 컴포넌트로 통합

---

## 7. 마이그레이션 절차 (Step by Step)

### Step 1: 사전 분석

```sql
-- 본서버 화면 목록 확인
SELECT sd.screen_id, sd.screen_code, sd.screen_name, sd.table_name,
       COUNT(sl.layout_id) as component_count
FROM screen_definitions sd
LEFT JOIN screen_layouts sl ON sd.screen_id = sl.screen_id
WHERE sd.screen_code LIKE 'COMPANY_7_%'
GROUP BY sd.screen_id, sd.screen_code, sd.screen_name, sd.table_name;

-- 개발서버 V2 현황 확인
SELECT sd.screen_id, sd.screen_code, sd.screen_name,
       sv2.layout_data IS NOT NULL as has_v2_layout
FROM screen_definitions sd
LEFT JOIN screen_layouts_v2 sv2 ON sd.screen_id = sv2.screen_id
WHERE sd.company_code = 'COMPANY_7';
```

### Step 2: table_type_columns 확인

```sql
-- 해당 테이블의 컬럼 타입 확인
SELECT column_name, column_label, input_type, detail_settings
FROM table_type_columns
WHERE table_name = '대상테이블명'
  AND company_code = 'COMPANY_7';
```

### Step 3: V2 layout_data 생성

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "생성된ID",
      "url": "@/lib/registry/components/v2-컴포넌트타입",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 100, "height": 50 },
      "displayOrder": 0,
      "overrides": {
        "tableName": "테이블명",
        "fieldName": "컬럼명"
      }
    }
  ],
  "migratedFrom": "V1",
  "migratedAt": "2026-02-03T00:00:00Z"
}
```

### Step 4: screen_layouts_v2 INSERT

```sql
INSERT INTO screen_layouts_v2 (screen_id, company_code, layout_data)
VALUES ($1, $2, $3::jsonb)
ON CONFLICT (screen_id, company_code) 
DO UPDATE SET layout_data = $3::jsonb, updated_at = NOW();
```

### Step 5: 검증

- [ ] 화면 렌더링 확인 (component가 아닌 v2-xxx로 표시되는지)
- [ ] 컴포넌트별 테이블-컬럼 연결 확인
- [ ] 카테고리 드롭다운 동작 확인
- [ ] 채번 규칙 동작 확인
- [ ] 저장/수정/삭제 테스트

---

## 8. 품질관리 메뉴 마이그레이션 현황

| 본서버 코드 | 화면명 | 테이블 | 상태 | 비고 |
|-------------|--------|--------|------|------|
| COMPANY_7_126 | 검사정보 관리 | inspection_standard | ✅ V2 존재 | 컴포넌트 검증 필요 |
| COMPANY_7_127 | 품목옵션 설정 | - | ✅ V2 존재 | v2-category-manager |
| COMPANY_7_138 | 카테고리 설정 | inspection_standard | ❌ 누락 | table_name 기반 |
| COMPANY_7_139 | 코드 설정 | inspection_standard | ❌ 누락 | table_name 기반 |
| COMPANY_7_142 | 검사장비 관리 | inspection_equipment_mng | ❌ 누락 | 모달 통합 |
| COMPANY_7_143 | 검사장비 등록모달 | inspection_equipment_mng | ❌ 누락 | → 142 통합 |
| COMPANY_7_144 | 불량기준 정보 | defect_standard_mng | ❌ 누락 | 모달 통합 |
| COMPANY_7_145 | 불량기준 등록모달 | defect_standard_mng | ❌ 누락 | → 144 통합 |

---

## 9. 관련 코드 파일 경로

| 항목 | 경로 |
|------|------|
| V2 컴포넌트 폴더 | `frontend/lib/registry/components/v2-xxx/` |
| 컴포넌트 등록 | `frontend/lib/registry/components/index.ts` |
| 카테고리 서비스 | `backend-node/src/services/categoryTreeService.ts` |
| 채번 서비스 | `backend-node/src/services/numberingRuleService.ts` |
| 엔티티 조인 API | `frontend/lib/api/entityJoin.ts` |
| 폼 호환성 훅 | `frontend/hooks/useFormCompatibility.ts` |

---

## 10. 절대 하지 말 것

1. ❌ **테이블-컬럼 연결 없이 컴포넌트 배치** → "component"로 표시됨
2. ❌ **menu_objid 기반 카테고리/채번 사용** → V2는 table_name + column_name 기반
3. ❌ **모달을 별도 screen_id로 생성** → V2는 부모 화면에 통합
4. ❌ **V1 컴포넌트 타입 사용** → 반드시 v2- 접두사 컴포넌트 사용
5. ❌ **company_code 필터링 누락** → 멀티테넌시 필수

---

## 11. 모르면 확인할 곳

1. **컴포넌트 구조**: `docs/V2_컴포넌트_분석_가이드.md`
2. **화면 개발 표준**: `docs/screen-implementation-guide/화면개발_표준_가이드.md`
3. **마이그레이션 절차**: `docs/DDD1542/본서버_개발서버_마이그레이션_상세가이드.md`
4. **탑실 디자인 명세**: `/Users/gbpark/Downloads/화면개발 8/`
5. **실제 코드**: 위 경로의 소스 파일들

---

## 12. 왕의 훈계

> **"항상 애매한 거는 md파일 보거나 물어볼 것. 코드에는 전부 정답이 있음. 만약 모른다면 너 잘못. 실수해도 너 잘못."**

---

## 변경 이력

| 날짜 | 작성자 | 내용 |
|------|--------|------|
| 2026-02-03 | DDD1542 | 초안 작성 (문서 4개 정독 후) |