# 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 (자동 데이터 채움)
탑씰 회사정보 화면에서 가장 많이 쓰이는 패턴:
```json
{
  "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개