308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
|
# V3 메타 컴포넌트 - 자체 데이터 파이프라인 구축 계획
|
||
|
|
|
||
|
|
> **핵심 원칙**: V3 메타 컴포넌트는 V2를 래핑하지 않는다.
|
||
|
|
> 자체적으로 완전히 동작하는 렌더링 + 데이터 파이프라인을 가진다.
|
||
|
|
> V2의 좋은 부분(API, EventBus, formData 패턴)은 재사용하되, 렌더러는 새로 만든다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 아키텍처
|
||
|
|
|
||
|
|
```
|
||
|
|
[V3 메타 컴포넌트]
|
||
|
|
│
|
||
|
|
├─ FieldRenderer ─── formData/onFormDataChange + entityJoinApi + validation
|
||
|
|
├─ DataViewRenderer ─── entityJoinApi.getTableDataWithJoins + 페이징/정렬/필터
|
||
|
|
├─ ActionRenderer ─── ButtonActionExecutor + v2EventBus
|
||
|
|
├─ SearchRenderer ─── v2EventBus로 DataView 필터링
|
||
|
|
├─ LayoutRenderer ─── children 관리 (순수 컨테이너)
|
||
|
|
├─ DisplayRenderer ─── formData 바인딩 + 포맷팅
|
||
|
|
└─ ModalRenderer ─── 모달 상태 + 내부 폼
|
||
|
|
```
|
||
|
|
|
||
|
|
## 재사용하는 V2 인프라 (수정 없이 그대로 사용)
|
||
|
|
|
||
|
|
| 모듈 | 파일 | 용도 |
|
||
|
|
|------|------|------|
|
||
|
|
| entityJoinApi | `frontend/lib/api/entityJoin.ts` | 테이블 데이터 조회 (조인 포함) |
|
||
|
|
| DynamicFormApi | `frontend/lib/api/dynamicForm.ts` | 폼 저장/검증 |
|
||
|
|
| screenApi | `frontend/lib/api/screen.ts` | CRUD API (add/edit/delete) |
|
||
|
|
| v2EventBus | `frontend/lib/v2-core/events/EventBus.ts` | 컴포넌트 간 이벤트 통신 |
|
||
|
|
| V2_EVENTS | `frontend/lib/v2-core/events/types.ts` | 이벤트 타입 상수 |
|
||
|
|
| ButtonActionExecutor | `frontend/lib/utils/buttonActions.ts` | 버튼 액션 실행 |
|
||
|
|
| apiClient | `frontend/lib/api/client.ts` | HTTP 클라이언트 |
|
||
|
|
| formData 패턴 | props 전달 | `formData`, `onFormDataChange(fieldName, value)` |
|
||
|
|
|
||
|
|
## 새로 만드는 V3 전용 모듈
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Phase 1: FieldRenderer (자체 데이터 바인딩)
|
||
|
|
|
||
|
|
**목표**: 하나의 FieldRenderer가 webType에 따라 모든 입력 필드를 렌더링
|
||
|
|
|
||
|
|
**파일**: `frontend/lib/meta-components/Field/FieldRenderer.tsx`
|
||
|
|
|
||
|
|
**기능 요구사항**:
|
||
|
|
1. `formData[columnName]`에서 현재 값 읽기
|
||
|
|
2. `onFormDataChange(columnName, newValue)` 호출로 값 변경
|
||
|
|
3. webType별 렌더링:
|
||
|
|
- `text`, `number`, `email`, `tel`, `url`, `password`: shadcn `<Input>` 사용
|
||
|
|
- `textarea`: shadcn `<Textarea>` 사용
|
||
|
|
- `date`, `datetime`: shadcn date picker 또는 기존 `<input type="date">` 사용
|
||
|
|
- `select`: shadcn `<Select>` 사용, options는 config.options에서 가져오거나 API 호출
|
||
|
|
- `checkbox`, `radio`, `toggle`: shadcn `<Checkbox>`, `<RadioGroup>`, `<Switch>`
|
||
|
|
- `entity`: 엔티티 검색 입력 (autocomplete) - `entityJoinApi` 활용
|
||
|
|
- `file`: 파일 업로드 - 기존 file API 활용
|
||
|
|
- `numbering`: 읽기 전용 채번 필드
|
||
|
|
4. 라벨 표시 (config.label, labelPosition)
|
||
|
|
5. 필수/읽기전용/비활성 상태 처리
|
||
|
|
6. 검증 규칙 적용 (config.validation)
|
||
|
|
|
||
|
|
**Props 인터페이스**:
|
||
|
|
```typescript
|
||
|
|
interface FieldRendererProps {
|
||
|
|
id: string;
|
||
|
|
config: FieldComponentConfig;
|
||
|
|
// 데이터 바인딩 (상위에서 전달)
|
||
|
|
formData?: Record<string, any>;
|
||
|
|
onFormDataChange?: (fieldName: string, value: any) => void;
|
||
|
|
// 컨텍스트
|
||
|
|
tableName?: string;
|
||
|
|
companyCode?: string;
|
||
|
|
screenId?: number;
|
||
|
|
// UI 모드
|
||
|
|
isDesignMode?: boolean;
|
||
|
|
disabled?: boolean;
|
||
|
|
className?: string;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**shadcn 컴포넌트 사용**:
|
||
|
|
- Input, Textarea, Select, Checkbox, RadioGroup, Switch, Label, DatePicker
|
||
|
|
- 모두 기존 설치된 shadcn/ui 활용
|
||
|
|
|
||
|
|
**엔티티 검색 구현**:
|
||
|
|
- config.join이 있으면 엔티티 검색 모드
|
||
|
|
- entityJoinApi를 사용하여 검색 대상 테이블 조회
|
||
|
|
- Popover + Command (shadcn combobox 패턴) 사용
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Phase 2: DataViewRenderer (자체 데이터 Fetching)
|
||
|
|
|
||
|
|
**목표**: 하나의 DataViewRenderer가 테이블/카드/트리 뷰를 모두 처리
|
||
|
|
|
||
|
|
**파일**: `frontend/lib/meta-components/DataView/DataViewRenderer.tsx`
|
||
|
|
|
||
|
|
**기능 요구사항**:
|
||
|
|
1. 컴포넌트 마운트 시 `entityJoinApi.getTableDataWithJoins(config.tableName, ...)` 호출
|
||
|
|
2. 페이징 처리 (config.pageSize, 현재 페이지 상태 관리)
|
||
|
|
3. 정렬 (컬럼 헤더 클릭)
|
||
|
|
4. 행 선택 (단일/다중)
|
||
|
|
5. 행 클릭 시 formData에 선택된 행 데이터 반영
|
||
|
|
6. v2EventBus.subscribe(TABLE_REFRESH) 구독 → 데이터 재로드
|
||
|
|
7. v2EventBus.emitSync(TABLE_DATA_CHANGE) 발행 → 선택 변경 시
|
||
|
|
8. viewMode에 따라 테이블/카드 전환
|
||
|
|
|
||
|
|
**Props 인터페이스**:
|
||
|
|
```typescript
|
||
|
|
interface DataViewRendererProps {
|
||
|
|
id: string;
|
||
|
|
config: DataViewComponentConfig;
|
||
|
|
// 선택된 행
|
||
|
|
selectedRowsData?: any[];
|
||
|
|
onSelectedRowsChange?: (rows: any[], data: any[]) => void;
|
||
|
|
// 컨텍스트
|
||
|
|
tableName?: string;
|
||
|
|
companyCode?: string;
|
||
|
|
screenId?: number;
|
||
|
|
// formData (마스터-디테일 연동용)
|
||
|
|
formData?: Record<string, any>;
|
||
|
|
onFormDataChange?: (fieldName: string, value: any) => void;
|
||
|
|
// UI
|
||
|
|
isDesignMode?: boolean;
|
||
|
|
className?: string;
|
||
|
|
onRefresh?: () => void;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**테이블 렌더링**:
|
||
|
|
- shadcn `<Table>` 기반
|
||
|
|
- 컬럼은 config.columns 또는 API에서 컬럼 메타데이터 자동 조회
|
||
|
|
- 페이징: 하단에 페이지네이션 컴포넌트
|
||
|
|
- 정렬: 컬럼 헤더 클릭으로 ASC/DESC 전환
|
||
|
|
|
||
|
|
**디자인 모드**:
|
||
|
|
- 데이터 로드 안 함
|
||
|
|
- 컬럼 헤더만 표시 + 샘플 빈 행 표시
|
||
|
|
- "DataView: {tableName}" 배지 표시
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Phase 3: ActionRenderer (자체 CRUD 실행)
|
||
|
|
|
||
|
|
**목표**: 버튼 클릭 시 config.steps에 정의된 액션을 순차 실행
|
||
|
|
|
||
|
|
**파일**: `frontend/lib/meta-components/Action/ActionRenderer.tsx`
|
||
|
|
|
||
|
|
**기능 요구사항**:
|
||
|
|
1. shadcn `<Button>` 렌더링 (variant, icon, label)
|
||
|
|
2. 클릭 시 config.steps를 순차 실행:
|
||
|
|
- `save`: `screenApi.addTableData()` 또는 `screenApi.editTableData()` 호출
|
||
|
|
- `delete`: `screenApi.deleteTableData()` 호출
|
||
|
|
- `refresh`: `v2EventBus.emitSync(TABLE_REFRESH)` 발행
|
||
|
|
- `navigate`: router.push로 화면 이동
|
||
|
|
- `openModal`: 모달 열기 이벤트
|
||
|
|
- `api`: 커스텀 API 호출
|
||
|
|
- `toast`: 토스트 메시지 표시
|
||
|
|
- `validate`: 폼 검증
|
||
|
|
3. config.confirmDialog가 있으면 실행 전 확인 대화상자
|
||
|
|
4. config.enableCondition에 따라 버튼 활성/비활성
|
||
|
|
|
||
|
|
**Props 인터페이스**:
|
||
|
|
```typescript
|
||
|
|
interface ActionRendererProps {
|
||
|
|
id: string;
|
||
|
|
config: ActionComponentConfig;
|
||
|
|
// 데이터
|
||
|
|
formData?: Record<string, any>;
|
||
|
|
selectedRowsData?: any[];
|
||
|
|
// 컨텍스트
|
||
|
|
tableName?: string;
|
||
|
|
companyCode?: string;
|
||
|
|
screenId?: number;
|
||
|
|
userId?: string;
|
||
|
|
// 콜백
|
||
|
|
onRefresh?: () => void;
|
||
|
|
// UI
|
||
|
|
isDesignMode?: boolean;
|
||
|
|
disabled?: boolean;
|
||
|
|
className?: string;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Phase 4: SearchRenderer, LayoutRenderer, DisplayRenderer, ModalRenderer
|
||
|
|
|
||
|
|
#### SearchRenderer
|
||
|
|
- 검색 필드들 렌더링 (config.fields 기반)
|
||
|
|
- "검색" 버튼 클릭 시 필터 조건 구성
|
||
|
|
- v2EventBus로 연결된 DataView에 필터 전달
|
||
|
|
- 또는 onSearch 콜백으로 필터 전달
|
||
|
|
|
||
|
|
#### LayoutRenderer
|
||
|
|
- config.mode에 따라 레이아웃 구성:
|
||
|
|
- `columns`: CSS Grid 기반 수평 분할
|
||
|
|
- `rows`: Flex 기반 수직 분할
|
||
|
|
- `tabs`: shadcn `<Tabs>` 사용
|
||
|
|
- `card`: shadcn `<Card>` 사용
|
||
|
|
- `accordion`: shadcn `<Accordion>` 사용
|
||
|
|
- children을 각 영역에 배치
|
||
|
|
|
||
|
|
#### DisplayRenderer
|
||
|
|
- config.displayType에 따라 표시:
|
||
|
|
- `text`/`heading`: 텍스트/제목 표시
|
||
|
|
- `divider`: 구분선
|
||
|
|
- `badge`: 뱃지
|
||
|
|
- `alert`: 알림
|
||
|
|
- `stat`: 통계 카드
|
||
|
|
- config.dataBinding이 있으면 formData에서 값 바인딩
|
||
|
|
|
||
|
|
#### ModalRenderer
|
||
|
|
- 트리거 버튼 렌더링
|
||
|
|
- 클릭 시 shadcn `<Dialog>` 열기
|
||
|
|
- 모달 내부에 폼 필드 자동 구성 (config.content.formConfig 기반)
|
||
|
|
- 저장/취소 버튼
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## RealtimePreviewDynamic.tsx 수정
|
||
|
|
|
||
|
|
메타 컴포넌트 렌더링 시 `metaToV2` 변환 없이 직접 V3 렌더러를 호출하도록 수정:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// 메타 컴포넌트는 자체 렌더러로 직접 렌더링
|
||
|
|
if (isMetaComponent(component)) {
|
||
|
|
return (
|
||
|
|
<MetaComponentRenderer
|
||
|
|
component={{ id, type: componentType, config: componentConfig }}
|
||
|
|
formData={formData}
|
||
|
|
onFormDataChange={onFormDataChange}
|
||
|
|
selectedRowsData={selectedRowsData}
|
||
|
|
onSelectedRowsChange={onSelectedRowsChange}
|
||
|
|
tableName={tableName}
|
||
|
|
companyCode={companyCode}
|
||
|
|
screenId={screenId}
|
||
|
|
userId={userId}
|
||
|
|
onRefresh={onRefresh}
|
||
|
|
isDesignMode={isDesignMode}
|
||
|
|
/>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
// V2 컴포넌트는 기존 DynamicComponentRenderer로
|
||
|
|
return <DynamicComponentRenderer ... />;
|
||
|
|
```
|
||
|
|
|
||
|
|
## MetaComponentRenderer.tsx 수정
|
||
|
|
|
||
|
|
각 개별 렌더러에 모든 필요한 props를 전달하는 진정한 디스패처로 수정:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
export function MetaComponentRenderer({ component, ...runtimeProps }) {
|
||
|
|
const { type, config } = component;
|
||
|
|
|
||
|
|
switch (type) {
|
||
|
|
case "meta-field":
|
||
|
|
return <FieldRenderer id={component.id} config={config} {...runtimeProps} />;
|
||
|
|
case "meta-dataview":
|
||
|
|
return <DataViewRenderer id={component.id} config={config} {...runtimeProps} />;
|
||
|
|
case "meta-action":
|
||
|
|
return <ActionRenderer id={component.id} config={config} {...runtimeProps} />;
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 테스트 기준
|
||
|
|
|
||
|
|
### Phase 1 (FieldRenderer) 완료 조건:
|
||
|
|
- [ ] text/number/email 입력 → formData에 값 반영
|
||
|
|
- [ ] select → 옵션 목록 표시, 선택 시 formData 반영
|
||
|
|
- [ ] date → 날짜 선택 가능
|
||
|
|
- [ ] 라벨, 필수 표시, 읽기전용 동작
|
||
|
|
- [ ] 디자인 모드에서 비활성 상태로 표시
|
||
|
|
|
||
|
|
### Phase 2 (DataViewRenderer) 완료 조건:
|
||
|
|
- [ ] 테이블명으로 데이터 자동 로드
|
||
|
|
- [ ] 테이블 형태로 데이터 표시
|
||
|
|
- [ ] 페이징 동작
|
||
|
|
- [ ] 행 클릭 시 선택
|
||
|
|
- [ ] TABLE_REFRESH 이벤트에 반응
|
||
|
|
|
||
|
|
### Phase 3 (ActionRenderer) 완료 조건:
|
||
|
|
- [ ] 버튼 렌더링 (variant, icon)
|
||
|
|
- [ ] 클릭 시 save → API 호출 → 토스트
|
||
|
|
- [ ] 클릭 시 delete → 확인 → API 호출
|
||
|
|
- [ ] 클릭 시 refresh → 테이블 새로고침
|
||
|
|
|
||
|
|
### 전체 통합 테스트:
|
||
|
|
- [ ] V3 변환 후 입력 필드에 데이터 입력 가능
|
||
|
|
- [ ] V3 변환 후 테이블에 데이터 로드됨
|
||
|
|
- [ ] V3 변환 후 버튼 클릭 시 저장/삭제 동작
|
||
|
|
- [ ] TypeScript 빌드 에러 0개
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 실행 순서
|
||
|
|
|
||
|
|
1. **frontend 에이전트**: Phase 1 (FieldRenderer) 구현 + 빌드 테스트
|
||
|
|
2. **frontend 에이전트**: Phase 2 (DataViewRenderer) 구현 + 빌드 테스트
|
||
|
|
3. **frontend 에이전트**: Phase 3 (ActionRenderer) 구현 + 빌드 테스트
|
||
|
|
4. **frontend 에이전트**: Phase 4 (나머지) 구현 + 빌드 테스트
|
||
|
|
5. **frontend 에이전트**: RealtimePreviewDynamic + MetaComponentRenderer 수정
|
||
|
|
6. **browser-use**: 전체 통합 브라우저 테스트
|