# V3 메타 컴포넌트 → V2 변환 파이프라인 구현 계획

> 핵심 원칙: V3 메타 컴포넌트는 "설정 추상화 레이어"이다.  
> 실제 렌더링은 기존 V2 DynamicComponentRenderer에 100% 위임한다.  
> V3 변환 후에도 기존과 동일하게 데이터 로딩/저장/삭제가 동작해야 한다.

---

## 현재 상태 (PM이 이미 수정한 부분)

### 1. 신규 생성 파일
- `frontend/lib/meta-components/transform/metaToV2.ts` - V3→V2 핵심 변환기 (생성 완료)

### 2. 수정된 파일
- `frontend/lib/meta-components/index.ts` - metaToV2 관련 export 추가됨
- `frontend/lib/meta-components/migration/migrateTo3_0.ts` - `_originalConfig`, `_originalType` 보존 로직 추가됨
- `frontend/components/screen/RealtimePreviewDynamic.tsx` - MetaComponentRenderer 대신 metaToV2 + DynamicComponentRenderer 사용하도록 변경됨

---

## 에이전트가 해야 할 작업

### Task 1: metaToV2.ts 변환기 완성도 검증 및 보강 (frontend)

**파일**: `frontend/lib/meta-components/transform/metaToV2.ts`

1. `transformDisplay` 함수에 `_originalConfig`/`_originalType` 패턴 적용 (다른 transform 함수들처럼)
2. `transformSearch`, `transformModal` 함수에도 동일 패턴 적용
3. 모든 transform 함수에서 `_originalConfig`가 있을 때 원본 componentType을 우선 사용하는지 확인
4. TypeScript 타입 에러 없는지 확인

### Task 2: RealtimePreviewDynamic.tsx 변경 검증 (frontend)

**파일**: `frontend/components/screen/RealtimePreviewDynamic.tsx`

1. `MetaComponentRenderer` import가 제거되고 `metaToV2`, `isMetaComponent` import로 교체되었는지 확인
2. 메타 컴포넌트 분기 처리가 삭제되고, 단일 `DynamicComponentRenderer`로 통합되었는지 확인
3. `metaToV2` 변환 시 position이 올바르게 전달되는지 확인
4. 사용하지 않는 import가 없는지 정리

### Task 3: ScreenDesigner.tsx의 handleMigrateToV3 검증 (frontend)

**파일**: `frontend/components/screen/ScreenDesigner.tsx`

1. `handleMigrateToV3` 함수가 변환 후 `componentType`을 `mc.type` (예: "meta-field")으로 설정하는지 확인
2. 원본 V2 컴포넌트의 속성들이 `...originalV2`로 보존되는지 확인  
3. 변환된 컴포넌트가 저장될 때 `componentConfig`에 `_originalConfig`가 포함되는지 확인

### Task 4: TypeScript 빌드 검증 (frontend)

```bash
cd frontend && npx tsc --noEmit 2>&1 | head -50
```

- 빌드 에러가 있으면 수정
- 특히 metaToV2.ts의 타입 정의와 import 관계 확인
- `MetaComponentRenderer`가 아직 다른 곳에서 참조되고 있으면 정리

### Task 5: 브라우저 테스트 (browser-use)

**테스트 시나리오**:

1. http://localhost:9771 접속 후 로그인 (ID: admin, PW: 1234)
2. 좌측 메뉴에서 "관리자" > "화면관리" 이동
3. 아무 화면 하나 선택하여 편집
4. 상단 툴바에서 "V3 변환" 버튼 클릭
5. 변환 후 화면이 정상적으로 표시되는지 확인:
   - 입력 필드가 실제 입력 가능한 형태로 보이는지 (빈 박스/UUID가 아닌)
   - 테이블이 데이터를 표시하는지
   - 버튼이 클릭 가능한 형태로 보이는지
6. 변환하지 않은 원래 상태로 돌아와도 정상 작동하는지 확인 (Ctrl+Z 또는 새로고침)

### Task 6: 에러 발생 시 수정 및 재테스트

- Task 4 또는 Task 5에서 에러가 발생하면 원인을 분석하고 수정
- 수정 후 다시 빌드 및 브라우저 테스트 반복
- 모든 테스트가 통과할 때까지 반복

---

## 변환 아키텍처 요약

```
[V2 컴포넌트] → migrateTo3_0() → [V3 메타 컴포넌트] (저장)
                                         ↓
                                  metaToV2() (렌더링 시)
                                         ↓
                                  [V2 ComponentData]
                                         ↓
                                  DynamicComponentRenderer (기존 V2 파이프라인)
                                         ↓
                                  실제 동작하는 화면 (데이터 CRUD 포함)
```

## 핵심 파일 목록

| 파일 | 역할 |
|------|------|
| `frontend/lib/meta-components/transform/metaToV2.ts` | V3→V2 변환기 (핵심) |
| `frontend/lib/meta-components/migration/migrateTo3_0.ts` | V2→V3 변환 (마이그레이션) |
| `frontend/lib/meta-components/index.ts` | 모듈 export |
| `frontend/components/screen/RealtimePreviewDynamic.tsx` | 캔버스 렌더링 |
| `frontend/components/screen/ScreenDesigner.tsx` | V3 변환 버튼 핸들러 |
| `frontend/lib/registry/DynamicComponentRenderer.tsx` | V2 렌더링 엔진 (수정 불필요) |

## 성공 기준

1. `npx tsc --noEmit` 에러 0개
2. V3 변환 후 기존 V2와 동일하게 컴포넌트가 렌더링됨
3. 입력 필드에 실제 데이터 입력 가능
4. 테이블에 데이터 로딩됨
5. 버튼 클릭 시 액션 동작함