ERP-node/docs/v3-topseal-ready-plan.md

V3 메타 컴포넌트 - 탑씰 실전 구현 레벨 달성 계획

목표: 심플 + 모든 것 컨트롤 + 설정 쉬움 + 현재 탑씰 구현 가능

---

현재 상태

V3 렌더러 7개 (Field, DataView, Action, Search, Layout, Display, Modal)가 자체 데이터 파이프라인으로 동작 확인됨.

부족한 부분 (탑씰 기준)

1. FieldRenderer 확장 (가장 큰 갭)

탑씰에서 가장 많이 쓰는 컴포넌트가 Field인데, 현재 FieldRenderer가 지원 못하는 타입:

widgetType	V2 componentType	탑씰 사용량	현재 V3 지원
text/email/tel/url	text-input	191	O
select (options)	select-basic	40	O
date	date-input	15	O
number	number-input	8	O
entity (엔티티 검색)	entity-search-input	11	텍스트만 (검색 X)
category (카테고리)	category-manager	10	X
file/image	file-upload, image-widget	14	file input만
numbering (자동채번)	numbering-rule	8	읽기전용만
autocomplete	autocomplete-search-input	7	X

필요한 작업:

1-1. Entity Search (엔티티 검색 입력)

• Popover + Command (shadcn combobox 패턴) 사용
• config.join.sourceTable에서 데이터 검색
• entityJoinApi 활용
• 검색어 입력 시 debounce로 API 호출
• 선택 시 formData에 값 반영 + join.valueColumn 값 저장

1-2. Category Select (카테고리 드롭다운)

• 기존 카테고리 API (/api/admin/categories/tree) 활용
• config.categoryGroupCode로 카테고리 그룹 지정
• Select 컴포넌트에 카테고리 옵션 자동 로딩

1-3. AutoFill (자동 데이터 채움)

탑씰 회사정보 화면에서 가장 많이 쓰이는 패턴:

{
  "autoFill": {
    "enabled": true,
    "userField": "companyCode",
    "sourceTable": "company_mng",
    "filterColumn": "company_code",
    "displayColumn": "company_name"
  }
}

• 컴포넌트 마운트 시 autoFill 설정이 있으면 자동으로 API 호출
• 현재 사용자의 companyCode로 sourceTable에서 displayColumn 값 조회
• formData에 자동 설정

1-4. File Upload (파일 업로드)

• 기존 file API (/api/files/upload) 활용
• 드래그 앤 드롭 + 클릭 업로드
• 이미지 미리보기 지원
• config.fileConfig에서 accept, maxSize, multiple 등 설정

---

2. SearchRenderer → DataView 연동

현재 SearchRenderer는 v2EventBus로 이벤트만 발행하는데, DataViewRenderer가 이 이벤트에서 필터 조건을 받아서 데이터를 다시 로드해야 함.

필요한 작업:

• DataViewRenderer의 TABLE_REFRESH 이벤트 핸들러에서 payload.filters를 받아 쿼리에 반영
• SearchRenderer에서 필터 구조를 DataView가 이해할 수 있는 형태로 전달
• 필터 구조: { columnName: string, operator: string, value: any }[]

---

3. Smart Config Panel (설정 쉬움의 핵심)

현재 UnifiedConfigPanel이 존재하지만, V3 렌더러와의 연동이 약함.

필요한 작업:

3-1. 테이블 선택 → 컬럼 자동 로드

• 테이블 드롭다운에서 테이블 선택
• API로 해당 테이블의 컬럼 목록 자동 조회
• 컬럼 선택하면 webType 자동 감지 (DB 컬럼 타입 기반)
  • varchar → text
  • integer/numeric → number
  • date/timestamp → date
  • boolean → checkbox

3-2. 심플 모드 Config

각 메타 컴포넌트별 최소 설정:

Field: 테이블 → 컬럼 → 라벨 (3개만 설정하면 동작) DataView: 테이블 → 표시할 컬럼 (2개만 설정하면 동작) Action: 액션 유형 → 대상 테이블 (2개만 설정하면 동작) Search: 연결할 DataView → 검색 필드 (2개만 설정하면 동작)

3-3. 고급 모드 Config

심플 모드에서 토글하면:

• Field: validation, placeholder, autoFill, join 등
• DataView: 페이징, 정렬, 컬럼 숨기기, 행 선택 모드 등
• Action: steps 배열, confirmDialog, enableCondition 등

---

4. V2 → V3 Migration 개선

현재 migrateTo3_0.ts가 있지만, V2의 풍부한 속성을 V3 config에 더 정확히 매핑해야 함.

필요한 매핑 강화:

• autoFill 설정 보존
• fileConfig 보존
• category widgetType 인식
• entity 검색 join 설정 보존
• split-panel → Layout 변환
• tabs-widget → Layout(tabs) 변환
• table-search-widget → Search 변환

---

실행 순서

Phase A: FieldRenderer 확장 (가장 임팩트 큼)

1. entity search (combobox) 추가
2. category select 추가
3. autoFill 로직 추가
4. file upload 개선
5. tsc 빌드 확인

Phase B: DataView + Search 연동

1. DataViewRenderer에 필터 수신 로직 추가
2. SearchRenderer 필터 포맷 통일
3. 연동 테스트

Phase C: Config Panel 스마트화

1. 테이블 → 컬럼 자동 로드
2. webType 자동 감지
3. 심플/고급 모드 토글
4. 각 메타 컴포넌트별 최소 설정 UI

Phase D: Migration 정확도 향상

1. autoFill, fileConfig, category 매핑
2. split-panel, tabs, table-search 변환
3. 통합 테스트

Phase E: 브라우저 통합 테스트

1. 탑씰 실제 화면 패턴으로 V3 화면 구성 테스트
2. 데이터 입력 → 저장 → 조회 전체 플로우
3. 검색 → 테이블 필터링 동작

---

성공 기준

• FieldRenderer에서 entity/category/autoFill/file 동작
• Search → DataView 필터 연동 동작
• 메타 컴포넌트 드롭 → 테이블 선택 → 컬럼 선택 → 동작하는 컴포넌트 완성 (3단계)
• 탑씰 회사정보 화면 수준의 폼 구성 가능
• 탑씰 설비등록 화면 수준의 리스트+폼 구성 가능
• TypeScript 빌드 에러 0개