ERP-node/docs/v3-meta-to-v2-transform-plan.md

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)

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. 버튼 클릭 시 액션 동작함