1789 lines
53 KiB
Plaintext
1789 lines
53 KiB
Plaintext
---
|
|
description: 화면 컴포넌트 개발 시 필수 가이드 - V2 컴포넌트, 엔티티 조인, 폼 데이터, 다국어 지원
|
|
alwaysApply: false
|
|
---
|
|
|
|
# 화면 컴포넌트 개발 가이드
|
|
|
|
새로운 화면 컴포넌트를 개발할 때 반드시 따라야 하는 핵심 원칙과 패턴입니다.
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [V2 컴포넌트 규칙 (최우선)](#1-v2-컴포넌트-규칙-최우선)
|
|
2. [V2 + Zod 레이아웃 저장/로드 시스템 (핵심)](#2-v2--zod-레이아웃-저장로드-시스템-핵심)
|
|
3. [표준 Props 인터페이스](#3-표준-props-인터페이스)
|
|
4. [멀티테넌시 (company_code)](#4-멀티테넌시-company_code)
|
|
5. [디자인 모드 vs 인터랙티브 모드](#5-디자인-모드-vs-인터랙티브-모드)
|
|
6. [로딩 및 에러 처리](#6-로딩-및-에러-처리)
|
|
7. [테이블 컬럼 기반 입력 위젯](#7-테이블-컬럼-기반-입력-위젯)
|
|
8. [컴포넌트별 테이블 설정](#8-컴포넌트별-테이블-설정)
|
|
9. [엔티티 조인 컬럼 활용](#9-엔티티-조인-컬럼-활용)
|
|
10. [폼 데이터 관리](#10-폼-데이터-관리)
|
|
11. [다국어 지원](#11-다국어-지원)
|
|
12. [저장 버튼 및 플로우 연동](#12-저장-버튼-및-플로우-연동)
|
|
13. [표준 코드 스타일 가이드](#13-표준-코드-스타일-가이드)
|
|
14. [성능 최적화](#14-성능-최적화)
|
|
15. [체크리스트](#15-체크리스트)
|
|
|
|
---
|
|
|
|
## 1. V2 컴포넌트 규칙 (최우선)
|
|
|
|
### 핵심 원칙
|
|
|
|
**화면관리 시스템에서는 반드시 V2 컴포넌트만 사용하고 수정합니다.**
|
|
|
|
- 원본 컴포넌트(v2 접두사 없는 것)는 더 이상 사용하지 않음
|
|
- 모든 수정/개발은 V2 폴더에서 진행
|
|
|
|
### V2 컴포넌트 목록 (18개)
|
|
|
|
| 컴포넌트 ID | 이름 | 용도 |
|
|
|-------------|------|------|
|
|
| `v2-button-primary` | 기본 버튼 | 저장, 삭제, 조회 등 액션 |
|
|
| `v2-text-display` | 텍스트 표시 | 읽기 전용 텍스트 |
|
|
| `v2-divider-line` | 구분선 | 섹션 구분 |
|
|
| `v2-table-list` | 테이블 리스트 | 데이터 목록 조회 |
|
|
| `v2-table-search-widget` | 검색 필터 | 테이블 검색 조건 |
|
|
| `v2-card-display` | 카드 디스플레이 | 카드 형태 표시 |
|
|
| `v2-split-panel-layout` | 분할 패널 | 좌우/상하 분할 |
|
|
| `v2-numbering-rule` | 채번 규칙 | 자동 채번 생성 |
|
|
| `v2-tabs-widget` | 탭 위젯 | 탭 레이아웃 |
|
|
| `v2-repeater` | 통합 리피터 | 행 단위 입력/저장 |
|
|
| `v2-rack-structure` | 렉 구조 | 창고 렉 위치 생성 |
|
|
| `v2-section-paper` | 섹션 페이퍼 | 섹션 컨테이너 |
|
|
| `v2-section-card` | 섹션 카드 | 카드 컨테이너 |
|
|
| `v2-repeat-screen-modal` | 반복 화면 모달 | 반복 팝업 |
|
|
| `v2-location-swap-selector` | 위치 선택 | 출발지/도착지 |
|
|
| `v2-pivot-grid` | 피벗 그리드 | 피벗 테이블 |
|
|
| `v2-aggregation-widget` | 집계 위젯 | 데이터 집계 |
|
|
| `v2-repeat-container` | 리피터 컨테이너 | 반복 컨테이너 |
|
|
|
|
### 파일 경로
|
|
|
|
```
|
|
frontend/lib/registry/components/
|
|
├── v2-button-primary/ ← V2 컴포넌트 (수정 대상)
|
|
├── v2-table-list/ ← V2 컴포넌트 (수정 대상)
|
|
├── button-primary/ ← 원본 (수정 금지)
|
|
├── table-list/ ← 원본 (수정 금지)
|
|
└── ...
|
|
```
|
|
|
|
### 수정/개발 시 규칙
|
|
|
|
1. **버그 수정/기능 추가**: V2 폴더의 파일만 수정
|
|
2. **새 컴포넌트 생성**: `v2-` 접두사로 폴더 및 ID 생성
|
|
3. **원본 폴더는 절대 수정하지 않음**
|
|
|
|
### Definition 네이밍 규칙
|
|
|
|
```typescript
|
|
// V2 접두사 사용
|
|
export const V2TableListDefinition = createComponentDefinition({
|
|
id: "v2-table-list",
|
|
name: "테이블 리스트",
|
|
// ...
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 2. V2 + Zod 레이아웃 저장/로드 시스템 (핵심)
|
|
|
|
### 핵심 원칙
|
|
|
|
**컴포넌트 코드 수정 시 모든 화면에 자동 반영되도록 V2 + Zod 기반 저장/로드 방식을 사용합니다.**
|
|
|
|
```
|
|
저장: component_url + overrides (차이값만)
|
|
로드: Zod 기본값 + overrides 병합
|
|
```
|
|
|
|
### 기존 방식 vs V2 방식
|
|
|
|
| 항목 | 기존 (문제점) | V2 (해결) |
|
|
|-----|-------------|----------|
|
|
| 저장 | 전체 설정 "박제" | url + overrides (차이값만) |
|
|
| 코드 수정 반영 | 안 됨 | 자동 반영 |
|
|
| 테이블 | `screen_layouts` (다중 레코드) | `screen_layouts_v2` (1 레코드) |
|
|
|
|
### 저장 구조 (screen_layouts_v2)
|
|
|
|
```json
|
|
{
|
|
"version": "2.0",
|
|
"components": [
|
|
{
|
|
"id": "comp_xxx",
|
|
"url": "@/lib/registry/components/v2-select",
|
|
"position": { "x": 100, "y": 50 },
|
|
"size": { "width": 180, "height": 30 },
|
|
"displayOrder": 0,
|
|
"overrides": {
|
|
"tableName": "warehouse_info",
|
|
"columnName": "warehouse_code",
|
|
"label": "창고코드",
|
|
"webType": "select"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 핵심 필드: overrides에 반드시 포함되어야 하는 속성
|
|
|
|
컴포넌트가 테이블 컬럼에서 드래그되어 생성된 경우, 다음 속성들이 `overrides`에 저장됩니다:
|
|
|
|
| 속성 | 설명 | 예시 |
|
|
|-----|------|-----|
|
|
| `tableName` | 연결된 테이블명 | `"warehouse_info"` |
|
|
| `columnName` | 연결된 컬럼명 | `"warehouse_code"` |
|
|
| `label` | 표시 라벨 | `"창고코드"` |
|
|
| `required` | 필수 입력 여부 | `true` / `false` |
|
|
| `readonly` | 읽기 전용 여부 | `true` / `false` |
|
|
| `inputType` | 입력 타입 | `"text"`, `"select"`, `"date"` 등 |
|
|
| `webType` | 웹 타입 | `"text"`, `"select"`, `"date"` 등 |
|
|
| `codeCategory` | 코드 카테고리 (코드 타입인 경우) | `"WAREHOUSE_TYPE"` |
|
|
|
|
### 저장 로직 (convertLegacyToV2)
|
|
|
|
```typescript
|
|
// frontend/lib/utils/layoutV2Converter.ts
|
|
|
|
export function convertLegacyToV2(legacyLayout: LegacyLayoutData): LayoutV2 {
|
|
const components = legacyLayout.components.map((comp, index) => {
|
|
const componentType = comp.componentType || comp.widgetType || comp.type;
|
|
const url = getComponentUrl(componentType);
|
|
const defaults = getDefaultsByUrl(url);
|
|
|
|
// 상위 레벨 속성들도 overrides에 포함 (중요!)
|
|
const topLevelProps: Record<string, any> = {};
|
|
if (comp.tableName) topLevelProps.tableName = comp.tableName;
|
|
if (comp.columnName) topLevelProps.columnName = comp.columnName;
|
|
if (comp.label) topLevelProps.label = comp.label;
|
|
if (comp.required !== undefined) topLevelProps.required = comp.required;
|
|
if (comp.readonly !== undefined) topLevelProps.readonly = comp.readonly;
|
|
|
|
// componentConfig에서 차이값만 추출
|
|
const configOverrides = extractCustomConfig(comp.componentConfig || {}, defaults);
|
|
|
|
// 병합
|
|
const overrides = { ...topLevelProps, ...configOverrides };
|
|
|
|
return {
|
|
id: comp.id,
|
|
url: url,
|
|
position: comp.position,
|
|
size: comp.size,
|
|
displayOrder: index,
|
|
overrides: overrides,
|
|
};
|
|
});
|
|
|
|
return { version: "2.0", components };
|
|
}
|
|
```
|
|
|
|
### 로드 로직 (convertV2ToLegacy)
|
|
|
|
```typescript
|
|
// frontend/lib/utils/layoutV2Converter.ts
|
|
|
|
export function convertV2ToLegacy(v2Layout: LayoutV2): LegacyLayoutData {
|
|
const components = v2Layout.components.map((comp) => {
|
|
const componentType = getComponentTypeFromUrl(comp.url);
|
|
const defaults = getDefaultsByUrl(comp.url);
|
|
const mergedConfig = mergeComponentConfig(defaults, comp.overrides);
|
|
|
|
// overrides에서 상위 레벨 속성들 복원
|
|
const overrides = comp.overrides || {};
|
|
|
|
return {
|
|
id: comp.id,
|
|
componentType: componentType,
|
|
position: comp.position,
|
|
size: comp.size,
|
|
componentConfig: mergedConfig,
|
|
// 상위 레벨 속성 복원 (중요!)
|
|
tableName: overrides.tableName,
|
|
columnName: overrides.columnName,
|
|
label: overrides.label || "",
|
|
required: overrides.required,
|
|
readonly: overrides.readonly,
|
|
};
|
|
});
|
|
|
|
return { components };
|
|
}
|
|
```
|
|
|
|
### Zod 스키마 구조
|
|
|
|
```typescript
|
|
// frontend/lib/schemas/componentConfig.ts
|
|
|
|
// 컴포넌트별 overrides 스키마
|
|
export const v2SelectOverridesSchema = z.object({
|
|
mode: z.enum(["dropdown", "combobox", "radio", "checkbox"]).default("dropdown"),
|
|
source: z.enum(["static", "code", "entity", "db", "distinct"]).default("distinct"),
|
|
multiple: z.boolean().default(false),
|
|
searchable: z.boolean().default(true),
|
|
placeholder: z.string().default("선택하세요"),
|
|
}).passthrough(); // 정의되지 않은 필드도 통과 (tableName, columnName 등)
|
|
|
|
// 스키마 레지스트리
|
|
export const componentOverridesSchemaRegistry: Record<string, z.ZodType<any>> = {
|
|
"v2-select": v2SelectOverridesSchema,
|
|
"v2-input": v2InputOverridesSchema,
|
|
"v2-table-list": v2TableListOverridesSchema,
|
|
// ...
|
|
};
|
|
|
|
// 기본값 레지스트리
|
|
export const componentDefaultsRegistry: Record<string, any> = {
|
|
"v2-select": {
|
|
mode: "dropdown",
|
|
source: "distinct", // 기본: 테이블 컬럼에서 자동 로드
|
|
multiple: false,
|
|
searchable: true,
|
|
},
|
|
// ...
|
|
};
|
|
```
|
|
|
|
### v2-select 자동 옵션 로드
|
|
|
|
`webType`이 `"select"`인 컬럼을 드래그하면:
|
|
|
|
1. **저장 시**: `tableName`, `columnName`이 `overrides`에 저장됨
|
|
2. **로드 시**: `source`가 `"distinct"`이면 자동으로 `/entity/{tableName}/distinct/{columnName}` API 호출
|
|
3. **결과**: 해당 컬럼의 고유 값들이 옵션으로 표시됨
|
|
|
|
```typescript
|
|
// DynamicComponentRenderer.tsx
|
|
|
|
case "v2-select":
|
|
return (
|
|
<V2Select
|
|
{...commonProps}
|
|
config={{
|
|
mode: config.mode || "dropdown",
|
|
source: config.source || "distinct", // 기본: 테이블에서 자동 로드
|
|
// ...
|
|
}}
|
|
/>
|
|
);
|
|
```
|
|
|
|
### 관련 파일
|
|
|
|
| 파일 | 역할 |
|
|
|------|------|
|
|
| `frontend/lib/schemas/componentConfig.ts` | Zod 스키마 및 기본값 레지스트리 |
|
|
| `frontend/lib/utils/layoutV2Converter.ts` | V2 ↔ Legacy 변환 유틸리티 |
|
|
| `frontend/lib/api/screen.ts` | `getLayoutV2`, `saveLayoutV2` API |
|
|
| `backend-node/src/services/screenManagementService.ts` | 백엔드 저장/로드 로직 |
|
|
|
|
### 새 컴포넌트 추가 시 체크리스트
|
|
|
|
1. [ ] `componentConfig.ts`에 Zod 스키마 추가 (`.passthrough()` 필수)
|
|
2. [ ] `componentOverridesSchemaRegistry`에 등록
|
|
3. [ ] `componentDefaultsRegistry`에 기본값 등록
|
|
4. [ ] 테이블 컬럼 드래그 시 `tableName`, `columnName` 저장 확인
|
|
|
|
---
|
|
|
|
## 3. 표준 Props 인터페이스
|
|
|
|
### 컴포넌트가 받아야 하는 표준 Props
|
|
|
|
모든 화면 컴포넌트는 다음 Props를 지원해야 합니다:
|
|
|
|
```typescript
|
|
interface StandardComponentProps {
|
|
// 필수
|
|
component: ComponentData; // 컴포넌트 설정 데이터
|
|
isDesignMode?: boolean; // 디자인 모드 여부 (기본: false)
|
|
isSelected?: boolean; // 선택 상태 (디자인 모드용)
|
|
isPreview?: boolean; // 미리보기 모드
|
|
|
|
// 폼 데이터 관련
|
|
formData?: Record<string, any>; // 현재 폼 데이터
|
|
onFormDataChange?: (fieldName: string, value: any) => void;
|
|
|
|
// 선택 관련 (테이블/리스트 컴포넌트)
|
|
selectedRows?: any[]; // 선택된 행 ID 목록
|
|
selectedRowsData?: any[]; // 선택된 행 전체 데이터
|
|
onSelectedRowsChange?: (rows: any[], data: any[]) => void;
|
|
|
|
// 사용자 정보 (멀티테넌시용)
|
|
userId?: string;
|
|
userName?: string;
|
|
companyCode?: string; // 회사 코드 (멀티테넌시 필수)
|
|
|
|
// 화면 정보
|
|
screenId?: number;
|
|
tableName?: string; // 화면 메인 테이블
|
|
menuObjid?: number;
|
|
|
|
// 새로고침 제어
|
|
refreshKey?: number; // 변경 시 데이터 새로고침
|
|
onRefresh?: () => void;
|
|
|
|
// 기타
|
|
className?: string;
|
|
style?: React.CSSProperties;
|
|
}
|
|
```
|
|
|
|
### Props 사용 예시
|
|
|
|
```typescript
|
|
export const MyComponent: React.FC<StandardComponentProps> = ({
|
|
component,
|
|
isDesignMode = false,
|
|
formData = {},
|
|
onFormDataChange,
|
|
companyCode,
|
|
refreshKey,
|
|
}) => {
|
|
// 컴포넌트 구현
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 멀티테넌시 (company_code)
|
|
|
|
### 핵심 원칙
|
|
|
|
**모든 데이터 조회/저장 API 호출 시 `autoFilter`를 사용하여 회사별 데이터 격리를 적용합니다.**
|
|
|
|
### API 호출 시 autoFilter 패턴 (필수)
|
|
|
|
```typescript
|
|
// 데이터 조회 시
|
|
const response = await apiClient.post(`/table-management/tables/${tableName}/data`, {
|
|
page: 1,
|
|
size: 100,
|
|
// 멀티테넌시: company_code 자동 필터링
|
|
autoFilter: {
|
|
enabled: true,
|
|
filterColumn: "company_code",
|
|
userField: "companyCode",
|
|
},
|
|
});
|
|
|
|
// entityJoinApi 사용 시
|
|
const response = await entityJoinApi.getTableDataWithJoins(tableName, {
|
|
page: 1,
|
|
size: 100,
|
|
enableEntityJoin: true,
|
|
companyCodeOverride: companyCode, // 프리뷰용 회사 코드 오버라이드
|
|
});
|
|
```
|
|
|
|
### 데이터 저장 시
|
|
|
|
```typescript
|
|
// 저장 시에는 백엔드에서 자동으로 company_code 추가
|
|
// 프론트엔드에서 명시적으로 company_code를 전달할 필요 없음
|
|
const response = await apiClient.post(`/table-management/tables/${tableName}/add`, {
|
|
...formData,
|
|
// company_code는 백엔드에서 세션 정보로 자동 추가
|
|
});
|
|
```
|
|
|
|
### 주의사항
|
|
|
|
1. **모든 테이블 조회에 autoFilter 적용** (예외: 시스템 설정 테이블)
|
|
2. **company_code = "*"는 최고 관리자 전용** (일반 사용자에게 노출 금지)
|
|
3. **JOIN 시에도 company_code 조건 확인** (entityJoinApi가 자동 처리)
|
|
|
|
---
|
|
|
|
## 5. 디자인 모드 vs 인터랙티브 모드
|
|
|
|
### 모드 구분
|
|
|
|
| 모드 | 설명 | API 호출 | 이벤트 처리 |
|
|
|------|------|---------|------------|
|
|
| 디자인 모드 (`isDesignMode=true`) | 화면 편집기에서 레이아웃 설계 시 | 스킵 | 비활성화 |
|
|
| 인터랙티브 모드 (`isDesignMode=false`) | 실제 화면 실행 시 | 정상 실행 | 활성화 |
|
|
| 미리보기 모드 (`isPreview=true`) | 편집기 내 미리보기 | 제한적 실행 | 활성화 |
|
|
|
|
### 디자인 모드 처리 패턴
|
|
|
|
```typescript
|
|
export const MyComponent: React.FC<Props> = ({ isDesignMode = false }) => {
|
|
const [data, setData] = useState<any[]>([]);
|
|
const [loading, setLoading] = useState(false);
|
|
|
|
// 1. 디자인 모드에서 API 호출 스킵
|
|
useEffect(() => {
|
|
if (isDesignMode) return;
|
|
fetchData();
|
|
}, [isDesignMode]);
|
|
|
|
// 2. 디자인 모드에서 더미 데이터 표시
|
|
if (isDesignMode) {
|
|
return (
|
|
<div className="border-2 border-dashed border-muted p-4">
|
|
<p className="text-sm text-muted-foreground">
|
|
테이블 리스트 (3개 컬럼)
|
|
</p>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
// 3. 인터랙티브 모드에서 실제 데이터 표시
|
|
return (
|
|
<Table>
|
|
{data.map((row) => (
|
|
<TableRow key={row.id}>...</TableRow>
|
|
))}
|
|
</Table>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 이벤트 핸들러 비활성화
|
|
|
|
```typescript
|
|
const handleClick = useCallback(() => {
|
|
if (isDesignMode) return; // 디자인 모드에서 클릭 무시
|
|
|
|
// 실제 액션 수행
|
|
executeAction();
|
|
}, [isDesignMode]);
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 로딩 및 에러 처리
|
|
|
|
### 로딩 상태 관리
|
|
|
|
```typescript
|
|
const [loading, setLoading] = useState(false);
|
|
const [error, setError] = useState<string | null>(null);
|
|
|
|
const fetchData = useCallback(async () => {
|
|
if (isDesignMode) return;
|
|
|
|
setLoading(true);
|
|
setError(null);
|
|
|
|
try {
|
|
const response = await apiClient.get(`/api/data`);
|
|
if (response.data.success) {
|
|
setData(response.data.data);
|
|
}
|
|
} catch (err: any) {
|
|
setError(err.message || "데이터 조회 실패");
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
}, [isDesignMode]);
|
|
```
|
|
|
|
### 로딩 UI 표시
|
|
|
|
```tsx
|
|
if (loading) {
|
|
return (
|
|
<div className="flex items-center justify-center p-4">
|
|
<Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
|
|
<span className="ml-2 text-sm text-muted-foreground">로딩 중...</span>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
if (error) {
|
|
return (
|
|
<div className="p-4 text-sm text-destructive">
|
|
{error}
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
### 토스트 알림 패턴
|
|
|
|
```typescript
|
|
import { toast } from "sonner";
|
|
|
|
// 성공
|
|
toast.success("저장되었습니다.");
|
|
|
|
// 에러
|
|
toast.error("저장 중 오류가 발생했습니다.");
|
|
|
|
// 로딩 (장시간 작업)
|
|
const toastId = toast.loading("저장 중...");
|
|
// 완료 후
|
|
toast.dismiss(toastId);
|
|
toast.success("저장 완료");
|
|
```
|
|
|
|
### DB 에러 유형별 처리
|
|
|
|
```typescript
|
|
const handleApiError = (error: any): string => {
|
|
const responseData = error?.response?.data;
|
|
|
|
if (!responseData?.error) {
|
|
return error.message || "오류가 발생했습니다.";
|
|
}
|
|
|
|
const errorMsg = responseData.error;
|
|
|
|
// 중복 키 에러
|
|
if (errorMsg.includes("duplicate key")) {
|
|
return "이미 존재하는 값입니다. 다른 값을 입력해주세요.";
|
|
}
|
|
|
|
// NOT NULL 제약조건 에러
|
|
if (errorMsg.includes("null value")) {
|
|
const match = errorMsg.match(/column "(\w+)"/);
|
|
const columnName = match ? match[1] : "필수";
|
|
return `${columnName} 필드는 필수 입력 항목입니다.`;
|
|
}
|
|
|
|
// 외래키 제약조건 에러
|
|
if (errorMsg.includes("foreign key")) {
|
|
return "참조하는 데이터가 존재하지 않습니다.";
|
|
}
|
|
|
|
return responseData.message || errorMsg;
|
|
};
|
|
|
|
// 사용
|
|
try {
|
|
await apiClient.post("/api/save", data);
|
|
toast.success("저장되었습니다.");
|
|
} catch (error) {
|
|
toast.error(handleApiError(error));
|
|
}
|
|
```
|
|
|
|
### 조용히 처리해야 하는 액션
|
|
|
|
다음 액션은 성공/실패 토스트를 표시하지 않습니다:
|
|
|
|
```typescript
|
|
const silentActions = ["edit", "modal", "navigate", "excel_upload", "barcode_scan"];
|
|
|
|
if (!silentActions.includes(actionType)) {
|
|
toast.success("처리 완료");
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 테이블 컬럼 기반 입력 위젯
|
|
|
|
### 드래그 방식으로 입력 폼 생성
|
|
|
|
좌측 패널에서 테이블 컬럼을 드래그하면 **테이블 타입관리에서 설정된 `inputType`**에 따라 자동으로 적절한 입력 위젯이 생성됩니다.
|
|
|
|
```
|
|
┌─────────────────────┐ ┌─────────────────────┐
|
|
│ 좌측 테이블 패널 │ 드래그 │ 캔버스 │
|
|
├─────────────────────┤ ───▶ ├─────────────────────┤
|
|
│ 창고코드 (text) │ │ [창고코드] [____] │
|
|
│ 층 (category) │ │ [층] [▼] │
|
|
│ 열 (number) │ │ [열] [____] │
|
|
└─────────────────────┘ └─────────────────────┘
|
|
```
|
|
|
|
### inputType → 위젯 타입 매핑
|
|
|
|
| inputType | 생성 위젯 | 설명 |
|
|
|-----------|----------|------|
|
|
| `text`, `textarea` | V2Input | 텍스트 입력 |
|
|
| `number` | V2Input | 숫자 입력 |
|
|
| `date`, `datetime` | V2Date | 날짜/시간 선택 |
|
|
| `code`, `category`, `entity` | V2Select | 선택박스 |
|
|
| `checkbox`, `radio` | 체크박스/라디오 | 선택 |
|
|
| `image`, `file` | V2Media | 파일 업로드 |
|
|
|
|
### 핵심 V2 컴포넌트 (3개)
|
|
|
|
| 컴포넌트 | 담당 inputType | 파일 경로 |
|
|
|----------|---------------|-----------|
|
|
| `V2Input` | text, textarea, number, password | `components/v2/V2Input.tsx` |
|
|
| `V2Select` | code, category, entity, select | `components/v2/V2Select.tsx` |
|
|
| `V2Date` | date, datetime, time, daterange | `components/v2/V2Date.tsx` |
|
|
|
|
### 컴포넌트 패널에서 직접 드래그 가능한 컴포넌트
|
|
|
|
| 컴포넌트 ID | 이름 | 설명 |
|
|
|-------------|------|------|
|
|
| `v2-repeater` | 리피터 그리드 | 행 단위 데이터 추가/수정/삭제 |
|
|
| `v2-table-list` | 테이블 리스트 | 데이터 목록 조회/필터/정렬 |
|
|
| `v2-table-search-widget` | 검색 필터 | 테이블 검색 조건 입력 |
|
|
| `v2-button-primary` | 버튼 | 저장, 삭제, 조회 등 액션 |
|
|
| `v2-split-panel-layout` | 분할 패널 | 좌우/상하 분할 레이아웃 |
|
|
| `v2-tabs-widget` | 탭 위젯 | 탭으로 화면 분리 |
|
|
|
|
### 입력 폼 필수 설정 (중요)
|
|
|
|
입력 폼 컴포넌트 개발 시 **반드시** 다음 설정을 지원해야 합니다:
|
|
|
|
#### 필수 항목 설정 (`required`)
|
|
|
|
```typescript
|
|
interface InputWidgetConfig {
|
|
required?: boolean; // 필수 입력 여부
|
|
requiredMessage?: string; // 에러 메시지 (기본: "필수 입력 항목입니다")
|
|
}
|
|
```
|
|
|
|
- 우측 속성 패널에서 **"필수 입력"** 체크박스 제공
|
|
- 필수 필드는 라벨 옆에 **빨간색 `*`** 표시
|
|
- 테이블 타입관리의 `isNullable = 'NO'`인 경우 기본값 `required: true`
|
|
|
|
#### 숨김 설정 (`hidden`)
|
|
|
|
```typescript
|
|
interface InputWidgetConfig {
|
|
hidden?: boolean; // 화면에서 숨김 여부
|
|
hiddenOnNew?: boolean; // 신규 모드에서만 숨김
|
|
hiddenOnEdit?: boolean; // 수정 모드에서만 숨김
|
|
}
|
|
```
|
|
|
|
#### 저장 시 필수 항목 검증 (필수 구현)
|
|
|
|
```typescript
|
|
// buttonActions.ts - 저장 액션
|
|
const validateRequiredFields = (
|
|
formData: Record<string, any>,
|
|
allComponents: ComponentData[],
|
|
): { isValid: boolean; errors: string[] } => {
|
|
const errors: string[] = [];
|
|
|
|
allComponents.forEach((comp) => {
|
|
if (comp.type === "widget" && comp.required) {
|
|
const value = formData[comp.columnName];
|
|
const isEmpty = value === null || value === undefined || value === "" ||
|
|
(Array.isArray(value) && value.length === 0);
|
|
|
|
if (isEmpty) {
|
|
const label = comp.label || comp.columnName;
|
|
errors.push(`${label}은(는) 필수 입력 항목입니다.`);
|
|
}
|
|
}
|
|
});
|
|
|
|
return { isValid: errors.length === 0, errors };
|
|
};
|
|
|
|
// 저장 전 검증
|
|
const handleSave = async (context: ButtonActionContext) => {
|
|
const validation = validateRequiredFields(context.formData, context.allComponents);
|
|
|
|
if (!validation.isValid) {
|
|
toast.error(validation.errors.join("\n"));
|
|
return { success: false, errors: validation.errors };
|
|
}
|
|
|
|
return await saveFormData(context.formData);
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 컴포넌트별 테이블 설정
|
|
|
|
### 핵심 원칙
|
|
|
|
**하나의 화면에서 여러 테이블을 다룰 수 있습니다.**
|
|
|
|
| 예시: 입고 화면 | 테이블 | 용도 |
|
|
|----------------|--------|------|
|
|
| 메인 폼 | `receiving_mng` | 입고 마스터 정보 |
|
|
| 조회 리스트 | `purchase_order_detail` | 발주 상세 조회 (읽기 전용) |
|
|
| 입력 리피터 | `receiving_detail` | 입고 상세 입력/저장 |
|
|
|
|
### 컴포넌트 설정 패턴
|
|
|
|
#### 조회용 (테이블 리스트)
|
|
|
|
```typescript
|
|
interface TableListConfig {
|
|
customTableName?: string; // 사용할 테이블명
|
|
useCustomTable?: boolean; // true: customTableName 사용
|
|
isReadOnly?: boolean; // true: 조회만
|
|
}
|
|
```
|
|
|
|
#### 저장용 (리피터)
|
|
|
|
```typescript
|
|
interface V2RepeaterConfig {
|
|
mainTableName?: string; // 저장할 테이블명
|
|
useCustomTable?: boolean; // true: mainTableName 사용
|
|
foreignKeyColumn?: string; // FK 컬럼 (예: receiving_id)
|
|
foreignKeySourceColumn?: string; // PK 컬럼 (예: id)
|
|
}
|
|
```
|
|
|
|
### 테이블 선택 UI 표준 (Combobox 그룹별)
|
|
|
|
```tsx
|
|
<Command>
|
|
<CommandInput placeholder="테이블 검색..." />
|
|
<CommandList>
|
|
{/* 그룹 1: 기본 (화면 테이블) */}
|
|
<CommandGroup heading="기본">
|
|
<CommandItem value={screenTableName}>
|
|
<Database className="mr-2 h-3 w-3 text-blue-500" />
|
|
{screenTableName}
|
|
</CommandItem>
|
|
</CommandGroup>
|
|
|
|
{/* 그룹 2: 연관 테이블 (FK 자동 설정) */}
|
|
<CommandGroup heading="연관 테이블 (FK 자동 설정)">
|
|
{relatedTables.map((table) => (
|
|
<CommandItem key={table.tableName} value={table.tableName}>
|
|
<Link2 className="mr-2 h-3 w-3 text-green-500" />
|
|
{table.tableName}
|
|
<span className="ml-auto text-xs text-muted-foreground">
|
|
FK: {table.foreignKeyColumn}
|
|
</span>
|
|
</CommandItem>
|
|
))}
|
|
</CommandGroup>
|
|
|
|
{/* 그룹 3: 전체 테이블 */}
|
|
<CommandGroup heading="전체 테이블">
|
|
{allTables.map((table) => (
|
|
<CommandItem key={table.tableName} value={table.tableName}>
|
|
{table.displayName || table.tableName}
|
|
</CommandItem>
|
|
))}
|
|
</CommandGroup>
|
|
</CommandList>
|
|
</Command>
|
|
```
|
|
|
|
### 연관 테이블 선택 시 FK 자동 설정
|
|
|
|
```typescript
|
|
const handleTableSelect = (tableName: string) => {
|
|
const relation = relatedTables.find(r => r.tableName === tableName);
|
|
|
|
if (relation) {
|
|
// 연관 테이블: FK/PK 자동 설정
|
|
updateConfig({
|
|
useCustomTable: true,
|
|
mainTableName: tableName,
|
|
foreignKeyColumn: relation.foreignKeyColumn,
|
|
foreignKeySourceColumn: relation.referenceColumn,
|
|
});
|
|
}
|
|
};
|
|
```
|
|
|
|
### 연관 테이블 조회 API
|
|
|
|
```typescript
|
|
const response = await apiClient.get(
|
|
`/api/table-management/columns/${currentTableName}/referenced-by`
|
|
);
|
|
|
|
// 응답
|
|
{
|
|
success: true,
|
|
data: [
|
|
{
|
|
tableName: "receiving_detail",
|
|
columnName: "receiving_id",
|
|
referenceColumn: "id",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 엔티티 조인 컬럼 활용
|
|
|
|
### 핵심 원칙
|
|
|
|
**테이블 타입관리의 엔티티 관계를 불러와서 조인된 컬럼들을 모두 사용 가능하게 합니다.**
|
|
|
|
### API 사용법
|
|
|
|
```typescript
|
|
import { entityJoinApi } from "@/lib/api/entityJoin";
|
|
|
|
const result = await entityJoinApi.getEntityJoinColumns(tableName);
|
|
|
|
// 응답 구조
|
|
{
|
|
tableName: string;
|
|
joinTables: Array<{
|
|
tableName: string;
|
|
currentDisplayColumn: string;
|
|
availableColumns: Array<{
|
|
columnName: string;
|
|
columnLabel: string;
|
|
dataType: string;
|
|
}>;
|
|
}>;
|
|
availableColumns: Array<{
|
|
tableName: string;
|
|
columnName: string;
|
|
columnLabel: string;
|
|
joinAlias: string; // 예: item_code_item_name
|
|
suggestedLabel: string; // 예: 품목명
|
|
}>;
|
|
}
|
|
```
|
|
|
|
### 설정 패널에 엔티티 조인 컬럼 섹션 추가 (필수)
|
|
|
|
```typescript
|
|
// 상태 정의
|
|
const [entityJoinColumns, setEntityJoinColumns] = useState<{
|
|
availableColumns: any[];
|
|
joinTables: any[];
|
|
}>({ availableColumns: [], joinTables: [] });
|
|
|
|
// 엔티티 조인 컬럼 로드
|
|
useEffect(() => {
|
|
const fetchEntityJoinColumns = async () => {
|
|
const tableName = config.selectedTable || screenTableName;
|
|
if (!tableName) return;
|
|
|
|
const result = await entityJoinApi.getEntityJoinColumns(tableName);
|
|
setEntityJoinColumns({
|
|
availableColumns: result.availableColumns || [],
|
|
joinTables: result.joinTables || [],
|
|
});
|
|
};
|
|
|
|
fetchEntityJoinColumns();
|
|
}, [config.selectedTable, screenTableName]);
|
|
```
|
|
|
|
### 엔티티 조인 컬럼 추가 함수
|
|
|
|
```typescript
|
|
const addEntityJoinColumn = (tableName: string, column: any) => {
|
|
// "테이블명.컬럼명" 형식으로 저장
|
|
const fullColumnName = `${tableName}.${column.columnName}`;
|
|
|
|
const newColumn = {
|
|
columnName: fullColumnName,
|
|
displayName: column.columnLabel,
|
|
isEntityJoin: true,
|
|
entityJoinTable: tableName,
|
|
entityJoinColumn: column.columnName,
|
|
};
|
|
|
|
onChange({
|
|
...config,
|
|
columns: [...(config.columns || []), newColumn],
|
|
});
|
|
};
|
|
```
|
|
|
|
### 셀 값 추출 헬퍼
|
|
|
|
```typescript
|
|
const getEntityJoinValue = (item: any, columnName: string): any => {
|
|
// 직접 매칭
|
|
if (item[columnName] !== undefined) return item[columnName];
|
|
|
|
// "테이블명.컬럼명" 형식
|
|
if (columnName.includes(".")) {
|
|
const [tableName, fieldName] = columnName.split(".");
|
|
const inferredSourceColumn = tableName.replace("_info", "_code");
|
|
const exactKey = `${inferredSourceColumn}_${fieldName}`;
|
|
|
|
if (item[exactKey] !== undefined) return item[exactKey];
|
|
if (item[fieldName] !== undefined) return item[fieldName];
|
|
}
|
|
|
|
return undefined;
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 폼 데이터 관리
|
|
|
|
### 통합 폼 시스템 (V2FormContext)
|
|
|
|
```typescript
|
|
import { useFormCompatibility } from "@/hooks/useFormCompatibility";
|
|
|
|
const MyComponent = ({ onFormDataChange, formData }) => {
|
|
const { getValue, setValue, submit } = useFormCompatibility({
|
|
legacyOnFormDataChange: onFormDataChange,
|
|
});
|
|
|
|
// 값 읽기
|
|
const currentValue = getValue("fieldName");
|
|
|
|
// 값 설정
|
|
const handleChange = (value: any) => {
|
|
setValue("fieldName", value);
|
|
};
|
|
|
|
// 저장
|
|
const handleSave = async () => {
|
|
const result = await submit({ tableName: "my_table", mode: "insert" });
|
|
};
|
|
};
|
|
```
|
|
|
|
### onChange 핸들러 패턴
|
|
|
|
```typescript
|
|
const handleChange = useCallback((value: any) => {
|
|
// 1. V2FormContext
|
|
v2Context?.setValue(fieldName, value);
|
|
|
|
// 2. ScreenContext
|
|
screenContext?.updateFormData?.(fieldName, value);
|
|
|
|
// 3. 레거시 콜백
|
|
onFormDataChange?.(fieldName, value);
|
|
}, [fieldName, v2Context, screenContext, onFormDataChange]);
|
|
```
|
|
|
|
---
|
|
|
|
## 11. 다국어 지원
|
|
|
|
### 타입 정의 시 다국어 필드 추가
|
|
|
|
```typescript
|
|
interface MyComponentConfig {
|
|
title?: string;
|
|
titleLangKeyId?: number;
|
|
titleLangKey?: string;
|
|
|
|
columns?: Array<{
|
|
name: string;
|
|
label: string;
|
|
langKeyId?: number;
|
|
langKey?: string;
|
|
}>;
|
|
}
|
|
```
|
|
|
|
### 라벨 추출 로직 등록
|
|
|
|
파일: `frontend/lib/utils/multilangLabelExtractor.ts`
|
|
|
|
```typescript
|
|
// extractMultilangLabels 함수에 추가
|
|
if (comp.componentType === "my-new-component") {
|
|
const config = comp.componentConfig;
|
|
|
|
if (config?.title) {
|
|
addLabel({
|
|
id: `${comp.id}_title`,
|
|
label: config.title,
|
|
langKeyId: config.titleLangKeyId,
|
|
langKey: config.titleLangKey,
|
|
});
|
|
}
|
|
|
|
config?.columns?.forEach((col, index) => {
|
|
addLabel({
|
|
id: `${comp.id}_col_${index}`,
|
|
label: col.label,
|
|
langKeyId: col.langKeyId,
|
|
langKey: col.langKey,
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
### 번역 표시 로직
|
|
|
|
```typescript
|
|
import { useScreenMultiLang } from "@/contexts/ScreenMultiLangContext";
|
|
|
|
const MyComponent = ({ component }) => {
|
|
const { getTranslatedText } = useScreenMultiLang();
|
|
const config = component.componentConfig;
|
|
|
|
const displayTitle = config?.titleLangKey
|
|
? getTranslatedText(config.titleLangKey, config.title || "")
|
|
: config?.title || "";
|
|
|
|
return <h2>{displayTitle}</h2>;
|
|
};
|
|
```
|
|
|
|
|
|
---
|
|
|
|
## 12. 저장 버튼 및 플로우 연동
|
|
|
|
### beforeFormSave 이벤트 처리 (필수)
|
|
|
|
저장 버튼 클릭 시 `beforeFormSave` 이벤트가 발생하며, 각 컴포넌트는 자신의 데이터를 제공해야 합니다:
|
|
|
|
```typescript
|
|
useEffect(() => {
|
|
const handleSaveRequest = (event: CustomEvent) => {
|
|
const componentKey = columnName || component?.id;
|
|
if (event.detail && componentKey) {
|
|
event.detail.formData[componentKey] = currentValue;
|
|
}
|
|
};
|
|
|
|
window.addEventListener("beforeFormSave", handleSaveRequest as EventListener);
|
|
return () => window.removeEventListener("beforeFormSave", handleSaveRequest as EventListener);
|
|
}, [currentValue, columnName, component?.id]);
|
|
```
|
|
|
|
### 배열 데이터 처리 (리피터, 테이블)
|
|
|
|
```typescript
|
|
useEffect(() => {
|
|
const handleSaveRequest = (event: CustomEvent) => {
|
|
const componentKey = columnName || component?.id || "repeater_data";
|
|
|
|
// 메타데이터 필드(_로 시작) 제외
|
|
const filteredData = localValue.map((item: any) => {
|
|
const filtered: Record<string, any> = {};
|
|
Object.keys(item).forEach((key) => {
|
|
if (!key.startsWith("_")) {
|
|
filtered[key] = item[key];
|
|
}
|
|
});
|
|
return filtered;
|
|
});
|
|
|
|
if (event.detail) {
|
|
event.detail.formData[componentKey] = filteredData;
|
|
}
|
|
};
|
|
|
|
window.addEventListener("beforeFormSave", handleSaveRequest as EventListener);
|
|
return () => window.removeEventListener("beforeFormSave", handleSaveRequest as EventListener);
|
|
}, [localValue, columnName, component?.id]);
|
|
```
|
|
|
|
### 플로우(제어관리)와의 연동
|
|
|
|
```typescript
|
|
import { useFlowContext } from "@/contexts/FlowContext";
|
|
|
|
const MyFormComponent = ({ formData, onFormDataChange }) => {
|
|
const flowContext = useFlowContext();
|
|
|
|
// 스텝에서 선택된 데이터로 폼 초기화
|
|
useEffect(() => {
|
|
if (flowContext?.selectedData?.length > 0) {
|
|
const firstItem = flowContext.selectedData[0];
|
|
Object.keys(firstItem).forEach((key) => {
|
|
onFormDataChange?.(key, firstItem[key]);
|
|
});
|
|
}
|
|
}, [flowContext?.selectedData]);
|
|
};
|
|
```
|
|
|
|
### 저장 버튼 액션 타입
|
|
|
|
| 액션 타입 | 설명 | 플로우 연동 |
|
|
|----------|------|------------|
|
|
| `save` | 단순 저장 | X |
|
|
| `saveAndClose` | 저장 후 모달/화면 닫기 | X |
|
|
| `saveAndMove` | 저장 후 다음 스텝으로 이동 | O |
|
|
| `saveAndRefresh` | 저장 후 화면 새로고침 | X |
|
|
|
|
### 주의사항
|
|
|
|
1. **컴포넌트 독립성**: 플로우 없이도 단독으로 작동해야 함
|
|
2. **옵셔널 처리**: `flowContext`가 없을 수 있으므로 항상 옵셔널 체이닝 사용
|
|
3. **데이터 키 일관성**: `columnName`이 있으면 우선 사용, 없으면 `component.id` 사용
|
|
4. **메타데이터 제외**: 저장 시 `_`로 시작하는 메타데이터 필드는 제외
|
|
|
|
|
|
|
|
---
|
|
|
|
## 13. 표준 코드 스타일 가이드
|
|
|
|
**`v2-repeater`** 컴포넌트를 표준으로 삼아 동일한 구조로 작성합니다.
|
|
|
|
### 핵심 원칙: 느슨한 결합도 (Loose Coupling)
|
|
|
|
**컴포넌트 간 직접 참조를 피하고, 이벤트 기반 통신을 사용합니다.**
|
|
|
|
```
|
|
┌─────────────┐ 이벤트 ┌─────────────┐ 이벤트 ┌─────────────┐
|
|
│ 저장 버튼 │ ──────────▶ │ 리피터 │ ◀────────── │ 플로우 │
|
|
│ │ beforeFormSave │ │ flowStepChange │ │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────┐
|
|
│ Window Event Bus │
|
|
│ beforeFormSave, repeaterSave, flowStepChange │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 파일 구조 표준
|
|
|
|
```
|
|
frontend/lib/registry/components/v2-[component-name]/
|
|
├── index.ts # V2ComponentDefinition (V2 접두사)
|
|
├── [Name]Renderer.tsx # 렌더러 (자동 등록)
|
|
├── [Name]Component.tsx # 메인 컴포넌트
|
|
├── [Name]ConfigPanel.tsx # 설정 패널
|
|
└── types.ts # 타입 정의 (선택적)
|
|
```
|
|
|
|
### index.ts 표준 구조
|
|
|
|
```typescript
|
|
import { ComponentCategory } from "@/types/component";
|
|
import { createComponentDefinition } from "../../utils/createComponentDefinition";
|
|
import { MyComponentConfigPanel } from "./MyComponentConfigPanel";
|
|
import { MyComponent } from "./MyComponent";
|
|
|
|
export const V2MyComponentDefinition = createComponentDefinition({
|
|
id: "v2-my-component", // 반드시 v2- 접두사
|
|
name: "마이 컴포넌트",
|
|
category: ComponentCategory.INPUT,
|
|
component: MyComponent,
|
|
configPanel: MyComponentConfigPanel,
|
|
defaultProps: { config: {} },
|
|
events: ["onDataChange", "onRowClick"],
|
|
});
|
|
|
|
export default V2MyComponentDefinition;
|
|
```
|
|
|
|
### 메인 컴포넌트 표준 구조
|
|
|
|
```typescript
|
|
"use client";
|
|
|
|
import React, { useState, useEffect, useCallback, useMemo, useRef } from "react";
|
|
import { cn } from "@/lib/utils";
|
|
import { v2EventBus, V2_EVENTS, V2ErrorBoundary } from "@/lib/v2-core";
|
|
|
|
interface MyComponentProps {
|
|
config: MyComponentConfig;
|
|
parentId?: string | number;
|
|
onDataChange?: (data: any[]) => void;
|
|
}
|
|
|
|
export const MyComponent: React.FC<MyComponentProps> = ({
|
|
config: propConfig,
|
|
parentId,
|
|
onDataChange,
|
|
}) => {
|
|
// 1. 설정 병합 (useMemo)
|
|
const config = useMemo(() => ({
|
|
...DEFAULT_CONFIG,
|
|
...propConfig,
|
|
}), [propConfig]);
|
|
|
|
// 2. 상태 정의
|
|
const [data, setData] = useState<any[]>([]);
|
|
const dataRef = useRef(data);
|
|
dataRef.current = data;
|
|
|
|
// 3. 이벤트 리스너 등록 (느슨한 결합)
|
|
useEffect(() => {
|
|
const handleSaveEvent = async (event: CustomEvent) => {
|
|
const { masterRecordId } = event.detail || {};
|
|
await saveData(dataRef.current, masterRecordId);
|
|
};
|
|
|
|
// V2 이벤트 버스 구독
|
|
const unsubscribe = v2EventBus.subscribe(
|
|
V2_EVENTS.FORM.REPEATER_SAVE,
|
|
handleSaveEvent
|
|
);
|
|
|
|
// 레거시 이벤트 지원
|
|
window.addEventListener("repeaterSave", handleSaveEvent as any);
|
|
|
|
return () => {
|
|
unsubscribe();
|
|
window.removeEventListener("repeaterSave", handleSaveEvent as any);
|
|
};
|
|
}, [config]);
|
|
|
|
// 4. beforeFormSave 이벤트 리스너
|
|
useEffect(() => {
|
|
const handleBeforeFormSave = (event: CustomEvent) => {
|
|
const fieldName = config.fieldName || config.columnName;
|
|
if (event.detail && fieldName) {
|
|
// 메타데이터 제외 후 데이터 제공
|
|
const cleanData = dataRef.current.map(item => {
|
|
const clean: Record<string, any> = {};
|
|
Object.keys(item).forEach(key => {
|
|
if (!key.startsWith("_")) clean[key] = item[key];
|
|
});
|
|
return clean;
|
|
});
|
|
event.detail.formData[fieldName] = cleanData;
|
|
}
|
|
};
|
|
|
|
const unsubscribe = v2EventBus.subscribe(
|
|
V2_EVENTS.FORM.BEFORE_SAVE,
|
|
handleBeforeFormSave
|
|
);
|
|
window.addEventListener("beforeFormSave", handleBeforeFormSave as any);
|
|
|
|
return () => {
|
|
unsubscribe();
|
|
window.removeEventListener("beforeFormSave", handleBeforeFormSave as any);
|
|
};
|
|
}, [config.fieldName, config.columnName]);
|
|
|
|
// 5. 렌더링
|
|
return (
|
|
<V2ErrorBoundary componentName="MyComponent">
|
|
<div className={cn("my-component")}>
|
|
{/* 컴포넌트 내용 */}
|
|
</div>
|
|
</V2ErrorBoundary>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 설정 패널 표준 구조
|
|
|
|
```typescript
|
|
"use client";
|
|
|
|
import React, { useState, useEffect, useMemo, useCallback } from "react";
|
|
import { Label } from "@/components/ui/label";
|
|
import { Checkbox } from "@/components/ui/checkbox";
|
|
import { Button } from "@/components/ui/button";
|
|
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
|
|
import { Command, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command";
|
|
import { Database, Link2, ChevronsUpDown, Check } from "lucide-react";
|
|
import { tableManagementApi } from "@/lib/api/tableManagement";
|
|
import { cn } from "@/lib/utils";
|
|
|
|
interface MyComponentConfigPanelProps {
|
|
config: MyComponentConfig;
|
|
onChange: (config: MyComponentConfig) => void;
|
|
screenTableName?: string;
|
|
}
|
|
|
|
export const MyComponentConfigPanel: React.FC<MyComponentConfigPanelProps> = ({
|
|
config: propConfig,
|
|
onChange,
|
|
screenTableName,
|
|
}) => {
|
|
// 1. config 안전하게 초기화 (useMemo)
|
|
const config = useMemo(() => ({
|
|
...DEFAULT_CONFIG,
|
|
...propConfig,
|
|
}), [propConfig]);
|
|
|
|
// 2. 상태 정의
|
|
const [allTables, setAllTables] = useState<any[]>([]);
|
|
const [relatedTables, setRelatedTables] = useState<any[]>([]);
|
|
const [tableComboboxOpen, setTableComboboxOpen] = useState(false);
|
|
|
|
// 3. 데이터 로딩
|
|
useEffect(() => {
|
|
const loadTables = async () => {
|
|
const response = await tableManagementApi.getTableList();
|
|
if (response.success) setAllTables(response.data);
|
|
};
|
|
loadTables();
|
|
}, []);
|
|
|
|
useEffect(() => {
|
|
if (!screenTableName) return;
|
|
const loadRelatedTables = async () => {
|
|
const response = await tableManagementApi.getReferencedByTables(screenTableName);
|
|
if (response.success) setRelatedTables(response.data);
|
|
};
|
|
loadRelatedTables();
|
|
}, [screenTableName]);
|
|
|
|
// 4. 핸들러
|
|
const handleChange = useCallback(<K extends keyof MyComponentConfig>(
|
|
key: K, value: MyComponentConfig[K]
|
|
) => {
|
|
onChange({ ...config, [key]: value });
|
|
}, [config, onChange]);
|
|
|
|
const handleTableSelect = useCallback((tableName: string) => {
|
|
const relation = relatedTables.find(r => r.tableName === tableName);
|
|
|
|
if (relation) {
|
|
onChange({
|
|
...config,
|
|
useCustomTable: true,
|
|
mainTableName: tableName,
|
|
foreignKeyColumn: relation.foreignKeyColumn,
|
|
foreignKeySourceColumn: relation.referenceColumn,
|
|
});
|
|
} else {
|
|
onChange({
|
|
...config,
|
|
useCustomTable: tableName !== screenTableName,
|
|
mainTableName: tableName !== screenTableName ? tableName : undefined,
|
|
});
|
|
}
|
|
setTableComboboxOpen(false);
|
|
}, [config, onChange, screenTableName, relatedTables]);
|
|
|
|
// 5. 렌더링
|
|
return (
|
|
<div className="space-y-4 p-4">
|
|
{/* 테이블 선택 (그룹별 Combobox) */}
|
|
<div className="space-y-2">
|
|
<Label className="text-xs font-medium">저장 테이블</Label>
|
|
<Popover open={tableComboboxOpen} onOpenChange={setTableComboboxOpen}>
|
|
<PopoverTrigger asChild>
|
|
<Button variant="outline" className="w-full justify-between">
|
|
{config.mainTableName || screenTableName || "테이블 선택..."}
|
|
<ChevronsUpDown className="ml-2 h-4 w-4 opacity-50" />
|
|
</Button>
|
|
</PopoverTrigger>
|
|
<PopoverContent className="w-full p-0">
|
|
<Command>
|
|
<CommandInput placeholder="테이블 검색..." />
|
|
<CommandList>
|
|
{/* 기본 */}
|
|
{screenTableName && (
|
|
<CommandGroup heading="기본">
|
|
<CommandItem onSelect={() => handleTableSelect(screenTableName)}>
|
|
<Database className="mr-2 h-3 w-3 text-blue-500" />
|
|
{screenTableName}
|
|
</CommandItem>
|
|
</CommandGroup>
|
|
)}
|
|
|
|
{/* 연관 테이블 */}
|
|
{relatedTables.length > 0 && (
|
|
<CommandGroup heading="연관 테이블 (FK 자동 설정)">
|
|
{relatedTables.map((table) => (
|
|
<CommandItem key={table.tableName} onSelect={() => handleTableSelect(table.tableName)}>
|
|
<Link2 className="mr-2 h-3 w-3 text-green-500" />
|
|
{table.tableName}
|
|
<span className="ml-auto text-xs text-muted-foreground">
|
|
FK: {table.foreignKeyColumn}
|
|
</span>
|
|
</CommandItem>
|
|
))}
|
|
</CommandGroup>
|
|
)}
|
|
|
|
{/* 전체 */}
|
|
<CommandGroup heading="전체 테이블">
|
|
{allTables.filter(t =>
|
|
t.tableName !== screenTableName &&
|
|
!relatedTables.some(r => r.tableName === t.tableName)
|
|
).map((table) => (
|
|
<CommandItem key={table.tableName} onSelect={() => handleTableSelect(table.tableName)}>
|
|
{table.displayName || table.tableName}
|
|
</CommandItem>
|
|
))}
|
|
</CommandGroup>
|
|
</CommandList>
|
|
</Command>
|
|
</PopoverContent>
|
|
</Popover>
|
|
</div>
|
|
|
|
{/* 필수/숨김 설정 */}
|
|
<div className="space-y-2">
|
|
<Label className="text-xs font-medium">필드 옵션</Label>
|
|
<div className="flex items-center space-x-2">
|
|
<Checkbox
|
|
checked={config.required || false}
|
|
onCheckedChange={(checked) => handleChange("required", checked as boolean)}
|
|
/>
|
|
<Label className="text-xs">필수 입력</Label>
|
|
</div>
|
|
<div className="flex items-center space-x-2">
|
|
<Checkbox
|
|
checked={config.hidden || false}
|
|
onCheckedChange={(checked) => handleChange("hidden", checked as boolean)}
|
|
/>
|
|
<Label className="text-xs">숨김</Label>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 이벤트 패턴
|
|
|
|
#### 이벤트 구독 (소비자)
|
|
|
|
```typescript
|
|
useEffect(() => {
|
|
const handleEvent = (event: CustomEvent) => { /* 처리 */ };
|
|
|
|
// V2 이벤트 버스 (권장)
|
|
const unsubscribe = v2EventBus.subscribe(V2_EVENTS.FORM.BEFORE_SAVE, handleEvent);
|
|
|
|
// 레거시 지원
|
|
window.addEventListener("beforeFormSave", handleEvent as any);
|
|
|
|
// Cleanup 필수!
|
|
return () => {
|
|
unsubscribe();
|
|
window.removeEventListener("beforeFormSave", handleEvent as any);
|
|
};
|
|
}, [dependencies]);
|
|
```
|
|
|
|
#### 이벤트 발행 (생산자)
|
|
|
|
```typescript
|
|
// V2 이벤트 버스
|
|
v2EventBus.emit(V2_EVENTS.FORM.REPEATER_SAVE, {
|
|
tableName: "my_table",
|
|
masterRecordId: savedId,
|
|
});
|
|
|
|
// 레거시 이벤트
|
|
window.dispatchEvent(new CustomEvent("repeaterSave", {
|
|
detail: { tableName: "my_table", masterRecordId: savedId }
|
|
}));
|
|
```
|
|
|
|
### 옵셔널 체이닝 필수 사용
|
|
|
|
```typescript
|
|
// 컨텍스트가 없을 수 있음
|
|
const flowContext = useFlowContext?.();
|
|
const currentStepId = flowContext?.currentStepId;
|
|
|
|
// 콜백이 없을 수 있음
|
|
onDataChange?.(newData);
|
|
|
|
// 중첩 속성 접근
|
|
const tableName = config?.dataSource?.tableName;
|
|
```
|
|
|
|
---
|
|
|
|
## 14. 성능 최적화
|
|
|
|
### useMemo로 계산 비용 줄이기
|
|
|
|
```typescript
|
|
// 설정 병합 (매 렌더링마다 새 객체 생성 방지)
|
|
const config = useMemo(() => ({
|
|
...DEFAULT_CONFIG,
|
|
...propConfig,
|
|
}), [propConfig]);
|
|
|
|
// 필터링된 데이터 (데이터나 필터가 변경될 때만 재계산)
|
|
const filteredData = useMemo(() => {
|
|
return data.filter(item => item.status === selectedStatus);
|
|
}, [data, selectedStatus]);
|
|
|
|
// 컬럼 정의 (설정이 변경될 때만 재생성)
|
|
const columns = useMemo(() => {
|
|
return config.columns?.map(col => ({
|
|
...col,
|
|
render: (value: any) => formatValue(value, col.type),
|
|
}));
|
|
}, [config.columns]);
|
|
```
|
|
|
|
### useCallback으로 핸들러 안정화
|
|
|
|
```typescript
|
|
// 자식 컴포넌트에 전달되는 콜백 안정화
|
|
const handleRowClick = useCallback((row: any) => {
|
|
setSelectedRow(row);
|
|
onRowClick?.(row);
|
|
}, [onRowClick]);
|
|
|
|
const handleChange = useCallback((value: any) => {
|
|
onFormDataChange?.(fieldName, value);
|
|
}, [fieldName, onFormDataChange]);
|
|
|
|
// 의존성이 많은 핸들러는 useRef 활용
|
|
const dataRef = useRef(data);
|
|
dataRef.current = data;
|
|
|
|
const handleSave = useCallback(async () => {
|
|
// dataRef.current로 최신 값 참조 (의존성 배열에 data 불필요)
|
|
await saveData(dataRef.current);
|
|
}, []);
|
|
```
|
|
|
|
### useRef로 이벤트 핸들러 최적화
|
|
|
|
```typescript
|
|
// 이벤트 핸들러에서 최신 상태 참조
|
|
const [data, setData] = useState<any[]>([]);
|
|
const dataRef = useRef(data);
|
|
|
|
// 상태 변경 시 ref도 업데이트
|
|
useEffect(() => {
|
|
dataRef.current = data;
|
|
}, [data]);
|
|
|
|
// 이벤트 핸들러에서 ref 사용 (의존성 배열 최소화)
|
|
useEffect(() => {
|
|
const handleSaveEvent = (event: CustomEvent) => {
|
|
// data 대신 dataRef.current 사용
|
|
event.detail.formData[fieldName] = dataRef.current;
|
|
};
|
|
|
|
window.addEventListener("beforeFormSave", handleSaveEvent as any);
|
|
return () => window.removeEventListener("beforeFormSave", handleSaveEvent as any);
|
|
}, [fieldName]); // data 의존성 제거 → 리스너 재등록 방지
|
|
```
|
|
|
|
### React.memo로 불필요한 리렌더링 방지
|
|
|
|
```typescript
|
|
// 자주 리렌더링되는 자식 컴포넌트
|
|
const TableRow = React.memo(({ row, onClick }: TableRowProps) => {
|
|
return (
|
|
<tr onClick={() => onClick(row)}>
|
|
{/* 셀 렌더링 */}
|
|
</tr>
|
|
);
|
|
});
|
|
|
|
// 커스텀 비교 함수 (필요 시)
|
|
const TableRow = React.memo(
|
|
({ row, onClick }: TableRowProps) => { /* ... */ },
|
|
(prevProps, nextProps) => prevProps.row.id === nextProps.row.id
|
|
);
|
|
```
|
|
|
|
### 대량 데이터 처리 패턴
|
|
|
|
```typescript
|
|
// 1. 페이지네이션 필수 (전체 데이터 로드 금지)
|
|
const fetchData = async (page: number, size: number) => {
|
|
const response = await apiClient.post(`/table-management/tables/${tableName}/data`, {
|
|
page,
|
|
size, // 기본값 50~100
|
|
});
|
|
};
|
|
|
|
// 2. 가상화 (1000개 이상 행 표시 시)
|
|
import { useVirtualizer } from "@tanstack/react-virtual";
|
|
|
|
const rowVirtualizer = useVirtualizer({
|
|
count: data.length,
|
|
getScrollElement: () => containerRef.current,
|
|
estimateSize: () => 40, // 행 높이
|
|
});
|
|
|
|
// 3. 디바운싱 (검색/필터 입력)
|
|
import { useDebouncedCallback } from "use-debounce";
|
|
|
|
const debouncedSearch = useDebouncedCallback((value: string) => {
|
|
setSearchTerm(value);
|
|
fetchData(1, pageSize);
|
|
}, 300);
|
|
```
|
|
|
|
### 렌더링 최적화 패턴
|
|
|
|
```typescript
|
|
// 조건부 렌더링 최적화
|
|
const MyComponent = ({ isVisible, data }) => {
|
|
// 숨겨진 컴포넌트는 early return
|
|
if (!isVisible) return null;
|
|
|
|
// 데이터 없으면 빈 상태만 표시
|
|
if (!data?.length) {
|
|
return <EmptyState />;
|
|
}
|
|
|
|
return <DataTable data={data} />;
|
|
};
|
|
|
|
// 무거운 컴포넌트 지연 로드
|
|
const HeavyChart = React.lazy(() => import("./HeavyChart"));
|
|
|
|
const Dashboard = () => (
|
|
<Suspense fallback={<Skeleton />}>
|
|
<HeavyChart />
|
|
</Suspense>
|
|
);
|
|
```
|
|
|
|
### 피해야 할 패턴
|
|
|
|
```typescript
|
|
// ❌ 렌더링마다 새 객체/배열 생성
|
|
<ChildComponent style={{ color: "red" }} />
|
|
<ChildComponent options={[1, 2, 3]} />
|
|
|
|
// ✅ useMemo 또는 상수로 분리
|
|
const style = useMemo(() => ({ color: "red" }), []);
|
|
const options = useMemo(() => [1, 2, 3], []);
|
|
<ChildComponent style={style} options={options} />
|
|
|
|
// ❌ 인라인 함수로 핸들러 전달
|
|
<ChildComponent onClick={() => handleClick(id)} />
|
|
|
|
// ✅ useCallback으로 안정화
|
|
const handleItemClick = useCallback(() => handleClick(id), [id]);
|
|
<ChildComponent onClick={handleItemClick} />
|
|
|
|
// ❌ 불필요한 상태 업데이트
|
|
useEffect(() => {
|
|
setDerivedValue(data.map(x => x.value)); // 매번 새 배열 생성
|
|
}, [data]);
|
|
|
|
// ✅ useMemo로 파생 값 계산
|
|
const derivedValue = useMemo(() => data.map(x => x.value), [data]);
|
|
```
|
|
|
|
---
|
|
|
|
## 15. 체크리스트
|
|
|
|
### V2 컴포넌트 규칙
|
|
|
|
- [ ] V2 폴더(`v2-*/`)에서 작업
|
|
- [ ] 컴포넌트 ID에 `v2-` 접두사 사용
|
|
- [ ] Definition 이름에 `V2` 접두사 사용
|
|
- [ ] 원본 폴더 수정하지 않음
|
|
|
|
### V2 + Zod 레이아웃 시스템
|
|
|
|
- [ ] `componentConfig.ts`에 Zod 스키마 추가 (`.passthrough()` 필수)
|
|
- [ ] `componentOverridesSchemaRegistry`에 컴포넌트 등록
|
|
- [ ] `componentDefaultsRegistry`에 기본값 등록
|
|
- [ ] 테이블 컬럼 드래그 시 `tableName`, `columnName` 저장 확인
|
|
- [ ] `convertLegacyToV2`에서 상위 레벨 속성 포함 확인
|
|
- [ ] `convertV2ToLegacy`에서 상위 레벨 속성 복원 확인
|
|
- [ ] v2-select는 `source: "distinct"` 기본값 확인
|
|
|
|
### 표준 Props
|
|
|
|
- [ ] `component`, `isDesignMode` props 지원
|
|
- [ ] `formData`, `onFormDataChange` props 지원
|
|
- [ ] `companyCode` props 지원 (멀티테넌시)
|
|
- [ ] `refreshKey`, `onRefresh` props 지원
|
|
|
|
### 멀티테넌시
|
|
|
|
- [ ] 모든 데이터 조회 API에 `autoFilter` 적용
|
|
- [ ] `company_code` 필터링 확인
|
|
- [ ] 최고 관리자(`*`) 데이터 일반 사용자에게 노출 안함
|
|
|
|
### 디자인/인터랙티브 모드
|
|
|
|
- [ ] `isDesignMode` 체크하여 API 호출 스킵
|
|
- [ ] 디자인 모드에서 더미 UI 표시
|
|
- [ ] 디자인 모드에서 이벤트 핸들러 비활성화
|
|
|
|
### 로딩 및 에러 처리
|
|
|
|
- [ ] `loading` 상태 관리
|
|
- [ ] `error` 상태 관리
|
|
- [ ] 로딩 중 UI 표시 (Spinner/Skeleton)
|
|
- [ ] 에러 메시지 토스트 표시
|
|
- [ ] DB 에러 유형별 메시지 처리
|
|
|
|
### 입력 폼 필수 설정
|
|
|
|
- [ ] `required` 속성 지원
|
|
- [ ] `hidden` 속성 지원
|
|
- [ ] 필수 필드에 빨간색 `*` 표시
|
|
- [ ] 속성 패널에 "필수 입력", "숨김" 체크박스 제공
|
|
- [ ] 저장 시 필수 항목 검증 로직 구현
|
|
|
|
### 테이블 설정
|
|
|
|
- [ ] `useCustomTable`, `mainTableName` 설정 지원
|
|
- [ ] 연관 테이블 선택 시 FK/PK 자동 설정
|
|
- [ ] 테이블 선택 UI는 Combobox 그룹별 표시
|
|
|
|
### 엔티티 조인
|
|
|
|
- [ ] `entityJoinApi.getEntityJoinColumns()` 호출
|
|
- [ ] 설정 패널에 "엔티티 조인 컬럼" 섹션 추가
|
|
- [ ] 컬럼명 `tableName.columnName` 형식으로 저장
|
|
|
|
### 폼 데이터
|
|
|
|
- [ ] `useFormCompatibility` 훅 사용
|
|
- [ ] 리피터 컴포넌트는 `beforeFormSave` 이벤트 처리
|
|
|
|
### 다국어 지원
|
|
|
|
- [ ] 타입에 `langKeyId`, `langKey` 필드 추가
|
|
- [ ] `extractMultilangLabels` 함수에 추출 로직 추가
|
|
- [ ] `applyMultilangMappings` 함수에 매핑 로직 추가
|
|
- [ ] `collectLangKeys` 함수에 수집 로직 추가
|
|
|
|
### 저장 버튼 연동
|
|
|
|
- [ ] `beforeFormSave` 이벤트에서 데이터 제공
|
|
- [ ] 배열 데이터는 메타데이터(`_` 접두사) 제외
|
|
- [ ] 이벤트 리스너 cleanup 처리
|
|
|
|
### 플로우 연동
|
|
|
|
- [ ] `FlowContext` 있을 때 `selectedData`로 초기화
|
|
- [ ] 플로우 없이도 단독 작동 가능 (옵셔널 체이닝)
|
|
|
|
### 코드 스타일
|
|
|
|
- [ ] `v2-repeater` 구조 참고
|
|
- [ ] 느슨한 결합도 유지 (이벤트 기반 통신)
|
|
|
|
### 성능 최적화
|
|
|
|
- [ ] `useMemo`로 설정/데이터 병합
|
|
- [ ] `useCallback`으로 핸들러 안정화
|
|
- [ ] `useRef`로 이벤트 핸들러에서 최신 값 참조
|
|
- [ ] 렌더링마다 새 객체/배열 생성 방지
|
|
- [ ] 인라인 함수 콜백 방지 (자식 컴포넌트 리렌더링 유발)
|
|
- [ ] 대량 데이터는 페이지네이션 필수
|
|
|
|
---
|
|
|
|
## 관련 파일 목록
|
|
|
|
### 핵심 파일
|
|
|
|
| 파일 | 역할 |
|
|
|------|------|
|
|
| `components/v2/V2Input.tsx` | text, number 입력 |
|
|
| `components/v2/V2Select.tsx` | code, entity 선택 |
|
|
| `components/v2/V2Date.tsx` | date, datetime 선택 |
|
|
| `lib/registry/components/v2-*/` | V2 컴포넌트 폴더 |
|
|
| `lib/api/entityJoin.ts` | 엔티티 조인 API |
|
|
| `hooks/useFormCompatibility.ts` | 폼 호환성 브릿지 |
|
|
| `lib/utils/multilangLabelExtractor.ts` | 다국어 라벨 추출/매핑 |
|
|
| `lib/utils/buttonActions.ts` | 저장 버튼 액션 처리 |
|
|
| `contexts/FlowContext.tsx` | 플로우 컨텍스트 |
|
|
|
|
### 참고 컴포넌트
|
|
|
|
| 컴포넌트 | 경로 | 참고 사항 |
|
|
|----------|------|-----------|
|
|
| `v2-repeater` | `lib/registry/components/v2-repeater/` | **표준 참조 컴포넌트** |
|
|
| `v2-table-list` | `lib/registry/components/v2-table-list/` | 조회 컴포넌트 참조 |
|
|
| `v2-table-search-widget` | `lib/registry/components/v2-table-search-widget/` | 검색 필터 참조 |
|