Merge branch 'feature/v2-renewal' of http://39.117.244.52:3000/kjs/ERP-node into feature/v2-unified-renewal
This commit is contained in:
kjs
670
docs/DDD1542/RESPONSIVE_GRID_SYSTEM_ARCHITECTURE.md
Normal file
670
docs/DDD1542/RESPONSIVE_GRID_SYSTEM_ARCHITECTURE.md
Normal file
@@ -0,0 +1,670 @@
|
||||
# 반응형 그리드 시스템 아키텍처
|
||||
|
||||
> 최종 업데이트: 2026-01-30
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요
|
||||
|
||||
### 1.1 현재 문제
|
||||
|
||||
**컴포넌트 위치/크기가 픽셀 단위로 고정되어 반응형 미지원**
|
||||
|
||||
```json
|
||||
// 현재 DB 저장 방식 (screen_layouts_v2.layout_data)
|
||||
{
|
||||
"position": { "x": 1753, "y": 88 },
|
||||
"size": { "width": 158, "height": 40 }
|
||||
}
|
||||
```
|
||||
|
||||
| 화면 크기 | 결과 |
|
||||
|-----------|------|
|
||||
| 1920px (디자인 기준) | 정상 |
|
||||
| 1280px (노트북) | 오른쪽 버튼 잘림 |
|
||||
| 768px (태블릿) | 레이아웃 완전히 깨짐 |
|
||||
| 375px (모바일) | 사용 불가 |
|
||||
|
||||
### 1.2 목표
|
||||
|
||||
| 목표 | 설명 |
|
||||
|------|------|
|
||||
| PC 대응 | 1280px ~ 1920px |
|
||||
| 태블릿 대응 | 768px ~ 1024px |
|
||||
| 모바일 대응 | 320px ~ 767px |
|
||||
|
||||
### 1.3 해결 방향
|
||||
|
||||
```
|
||||
현재: 픽셀 좌표 → position: absolute → 고정 레이아웃
|
||||
변경: 그리드 셀 번호 → CSS Grid + ResizeObserver → 반응형 레이아웃
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 현재 시스템 분석
|
||||
|
||||
### 2.1 데이터 현황
|
||||
|
||||
```
|
||||
총 레이아웃: 1,250개
|
||||
총 컴포넌트: 5,236개
|
||||
회사 수: 14개
|
||||
테이블 크기: 약 3MB
|
||||
```
|
||||
|
||||
### 2.2 컴포넌트 타입별 분포
|
||||
|
||||
| 컴포넌트 | 수량 | shadcn 사용 |
|
||||
|----------|------|-------------|
|
||||
| v2-input | 1,914 | ✅ `@/components/ui/input` |
|
||||
| v2-button-primary | 1,549 | ✅ `@/components/ui/button` |
|
||||
| v2-table-search-widget | 355 | ✅ shadcn 기반 |
|
||||
| v2-select | 327 | ✅ `@/components/ui/select` |
|
||||
| v2-table-list | 285 | ✅ `@/components/ui/table` |
|
||||
| v2-media | 181 | ✅ shadcn 기반 |
|
||||
| v2-date | 132 | ✅ `@/components/ui/calendar` |
|
||||
| **v2-split-panel-layout** | **131** | ✅ shadcn 기반 (**반응형 필요**) |
|
||||
| v2-tabs-widget | 75 | ✅ shadcn 기반 |
|
||||
| 기타 | 287 | ✅ shadcn 기반 |
|
||||
| **합계** | **5,236** | **전부 shadcn** |
|
||||
|
||||
### 2.3 현재 렌더링 방식
|
||||
|
||||
```tsx
|
||||
// frontend/lib/registry/layouts/flexbox/FlexboxLayout.tsx (라인 234-248)
|
||||
{components.map((child) => (
|
||||
<div
|
||||
style={{
|
||||
position: "absolute", // 절대 위치
|
||||
left: child.position.x, // 픽셀 고정
|
||||
top: child.position.y, // 픽셀 고정
|
||||
width: child.size.width, // 픽셀 고정
|
||||
height: child.size.height, // 픽셀 고정
|
||||
}}
|
||||
>
|
||||
{renderer.renderChild(child)}
|
||||
</div>
|
||||
))}
|
||||
```
|
||||
|
||||
### 2.4 핵심 발견
|
||||
|
||||
```
|
||||
✅ 이미 있는 것:
|
||||
- 12컬럼 그리드 설정 (gridSettings.columns: 12)
|
||||
- 그리드 스냅 기능 (snapToGrid: true)
|
||||
- shadcn/ui 기반 컴포넌트 (전체)
|
||||
|
||||
❌ 없는 것:
|
||||
- 그리드 셀 번호 저장 (현재 픽셀 저장)
|
||||
- 반응형 브레이크포인트 설정
|
||||
- CSS Grid 기반 렌더링
|
||||
- 분할 패널 반응형 처리
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 기술 결정
|
||||
|
||||
### 3.1 왜 Tailwind 동적 클래스가 아닌 CSS Grid + Inline Style인가?
|
||||
|
||||
**Tailwind 동적 클래스의 한계**:
|
||||
```tsx
|
||||
// ❌ 이건 안 됨 - Tailwind가 빌드 타임에 인식 못함
|
||||
className={`col-start-${col} md:col-start-${mdCol}`}
|
||||
|
||||
// ✅ 이것만 됨 - 정적 클래스
|
||||
className="col-start-1 md:col-start-3"
|
||||
```
|
||||
|
||||
Tailwind는 **빌드 타임**에 클래스를 스캔하므로, 런타임에 동적으로 생성되는 클래스는 인식하지 못합니다.
|
||||
|
||||
**해결책: CSS Grid + Inline Style + ResizeObserver**:
|
||||
```tsx
|
||||
// ✅ 올바른 방법
|
||||
<div style={{
|
||||
display: 'grid',
|
||||
gridTemplateColumns: 'repeat(12, 1fr)',
|
||||
}}>
|
||||
<div style={{
|
||||
gridColumn: `${col} / span ${colSpan}`, // 동적 값 가능
|
||||
}}>
|
||||
{component}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 3.2 역할 분담
|
||||
|
||||
| 영역 | 기술 | 설명 |
|
||||
|------|------|------|
|
||||
| **UI 컴포넌트** | shadcn/ui | 버튼, 인풋, 테이블 등 (이미 적용됨) |
|
||||
| **레이아웃 배치** | CSS Grid + Inline Style | 컴포넌트 위치, 크기, 반응형 |
|
||||
| **반응형 감지** | ResizeObserver | 화면 크기 감지 및 브레이크포인트 변경 |
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ ResponsiveGridLayout (CSS Grid) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ shadcn │ │ shadcn │ │ shadcn │ │
|
||||
│ │ Button │ │ Input │ │ Select │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ ┌─────────────────────────────────────────────┐ │
|
||||
│ │ shadcn Table │ │
|
||||
│ └─────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 데이터 구조 변경
|
||||
|
||||
### 4.1 현재 구조 (V2)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.0",
|
||||
"components": [{
|
||||
"id": "comp_xxx",
|
||||
"url": "@/lib/registry/components/v2-button-primary",
|
||||
"position": { "x": 1753, "y": 88, "z": 1 },
|
||||
"size": { "width": 158, "height": 40 },
|
||||
"overrides": { ... }
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 변경 후 구조 (V2 + 그리드)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.0",
|
||||
"layoutMode": "grid",
|
||||
"components": [{
|
||||
"id": "comp_xxx",
|
||||
"url": "@/lib/registry/components/v2-button-primary",
|
||||
"position": { "x": 1753, "y": 88, "z": 1 },
|
||||
"size": { "width": 158, "height": 40 },
|
||||
"grid": {
|
||||
"col": 11,
|
||||
"row": 2,
|
||||
"colSpan": 1,
|
||||
"rowSpan": 1
|
||||
},
|
||||
"responsive": {
|
||||
"sm": { "col": 1, "colSpan": 12 },
|
||||
"md": { "col": 7, "colSpan": 6 },
|
||||
"lg": { "col": 11, "colSpan": 1 }
|
||||
},
|
||||
"overrides": { ... }
|
||||
}],
|
||||
"gridSettings": {
|
||||
"columns": 12,
|
||||
"rowHeight": 80,
|
||||
"gap": 16
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 필드 설명
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
|------|------|------|
|
||||
| `layoutMode` | string | "grid" (반응형 그리드 사용) |
|
||||
| `grid.col` | number | 시작 컬럼 (1-12) |
|
||||
| `grid.row` | number | 시작 행 (1부터) |
|
||||
| `grid.colSpan` | number | 차지하는 컬럼 수 |
|
||||
| `grid.rowSpan` | number | 차지하는 행 수 |
|
||||
| `responsive.sm` | object | 모바일 (< 768px) 설정 |
|
||||
| `responsive.md` | object | 태블릿 (768px ~ 1024px) 설정 |
|
||||
| `responsive.lg` | object | 데스크톱 (> 1024px) 설정 |
|
||||
|
||||
### 4.4 호환성
|
||||
|
||||
- `position`, `size` 필드는 유지 (디자인 모드 + 폴백용)
|
||||
- `layoutMode`가 없으면 기존 방식(absolute) 사용
|
||||
- 마이그레이션 후에도 기존 화면 정상 동작
|
||||
|
||||
---
|
||||
|
||||
## 5. 구현 상세
|
||||
|
||||
### 5.1 그리드 변환 유틸리티
|
||||
|
||||
```typescript
|
||||
// frontend/lib/utils/gridConverter.ts
|
||||
|
||||
const DESIGN_WIDTH = 1920;
|
||||
const COLUMNS = 12;
|
||||
const COLUMN_WIDTH = DESIGN_WIDTH / COLUMNS; // 160px
|
||||
const ROW_HEIGHT = 80;
|
||||
|
||||
/**
|
||||
* 픽셀 좌표를 그리드 셀 번호로 변환
|
||||
*/
|
||||
export function pixelToGrid(
|
||||
position: { x: number; y: number },
|
||||
size: { width: number; height: number }
|
||||
): GridPosition {
|
||||
return {
|
||||
col: Math.max(1, Math.min(12, Math.round(position.x / COLUMN_WIDTH) + 1)),
|
||||
row: Math.max(1, Math.round(position.y / ROW_HEIGHT) + 1),
|
||||
colSpan: Math.max(1, Math.round(size.width / COLUMN_WIDTH)),
|
||||
rowSpan: Math.max(1, Math.round(size.height / ROW_HEIGHT)),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 기본 반응형 설정 생성
|
||||
*/
|
||||
export function getDefaultResponsive(grid: GridPosition): ResponsiveConfig {
|
||||
return {
|
||||
sm: { col: 1, colSpan: 12 }, // 모바일: 전체 너비
|
||||
md: {
|
||||
col: Math.max(1, Math.round(grid.col / 2)),
|
||||
colSpan: Math.min(grid.colSpan * 2, 12)
|
||||
}, // 태블릿: 2배 확장
|
||||
lg: { col: grid.col, colSpan: grid.colSpan }, // 데스크톱: 원본
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 반응형 그리드 레이아웃 컴포넌트
|
||||
|
||||
```tsx
|
||||
// frontend/lib/registry/layouts/responsive-grid/ResponsiveGridLayout.tsx
|
||||
|
||||
import React, { useRef, useState, useEffect } from "react";
|
||||
|
||||
type Breakpoint = "sm" | "md" | "lg";
|
||||
|
||||
interface ResponsiveGridLayoutProps {
|
||||
layout: LayoutData;
|
||||
isDesignMode: boolean;
|
||||
renderer: ComponentRenderer;
|
||||
}
|
||||
|
||||
export function ResponsiveGridLayout({
|
||||
layout,
|
||||
isDesignMode,
|
||||
renderer,
|
||||
}: ResponsiveGridLayoutProps) {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
const [breakpoint, setBreakpoint] = useState<Breakpoint>("lg");
|
||||
|
||||
// 화면 크기 감지
|
||||
useEffect(() => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const observer = new ResizeObserver((entries) => {
|
||||
const width = entries[0].contentRect.width;
|
||||
if (width < 768) setBreakpoint("sm");
|
||||
else if (width < 1024) setBreakpoint("md");
|
||||
else setBreakpoint("lg");
|
||||
});
|
||||
|
||||
observer.observe(containerRef.current);
|
||||
return () => observer.disconnect();
|
||||
}, []);
|
||||
|
||||
const gridSettings = layout.gridSettings || { columns: 12, rowHeight: 80, gap: 16 };
|
||||
|
||||
return (
|
||||
<div
|
||||
ref={containerRef}
|
||||
style={{
|
||||
display: "grid",
|
||||
gridTemplateColumns: `repeat(${gridSettings.columns}, 1fr)`,
|
||||
gridAutoRows: `${gridSettings.rowHeight}px`,
|
||||
gap: `${gridSettings.gap}px`,
|
||||
minHeight: isDesignMode ? "600px" : "auto",
|
||||
}}
|
||||
>
|
||||
{layout.components
|
||||
.sort((a, b) => (a.grid?.row || 0) - (b.grid?.row || 0))
|
||||
.map((component) => {
|
||||
// 반응형 설정 가져오기
|
||||
const gridConfig = component.responsive?.[breakpoint] || component.grid;
|
||||
const { col, colSpan } = gridConfig;
|
||||
const rowSpan = component.grid?.rowSpan || 1;
|
||||
|
||||
return (
|
||||
<div
|
||||
key={component.id}
|
||||
style={{
|
||||
gridColumn: `${col} / span ${colSpan}`,
|
||||
gridRow: `span ${rowSpan}`,
|
||||
}}
|
||||
>
|
||||
{renderer.renderChild(component)}
|
||||
</div>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 브레이크포인트 훅
|
||||
|
||||
```typescript
|
||||
// frontend/lib/registry/layouts/responsive-grid/useBreakpoint.ts
|
||||
|
||||
import { useState, useEffect, RefObject } from "react";
|
||||
|
||||
type Breakpoint = "sm" | "md" | "lg";
|
||||
|
||||
export function useBreakpoint(containerRef: RefObject<HTMLElement>): Breakpoint {
|
||||
const [breakpoint, setBreakpoint] = useState<Breakpoint>("lg");
|
||||
|
||||
useEffect(() => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const observer = new ResizeObserver((entries) => {
|
||||
const width = entries[0].contentRect.width;
|
||||
if (width < 768) setBreakpoint("sm");
|
||||
else if (width < 1024) setBreakpoint("md");
|
||||
else setBreakpoint("lg");
|
||||
});
|
||||
|
||||
observer.observe(containerRef.current);
|
||||
return () => observer.disconnect();
|
||||
}, [containerRef]);
|
||||
|
||||
return breakpoint;
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 분할 패널 반응형 수정
|
||||
|
||||
```tsx
|
||||
// frontend/lib/registry/components/v2-split-panel-layout/SplitPanelLayoutComponent.tsx
|
||||
|
||||
// 추가할 코드
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
const [isMobile, setIsMobile] = useState(false);
|
||||
|
||||
useEffect(() => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const observer = new ResizeObserver((entries) => {
|
||||
const width = entries[0].contentRect.width;
|
||||
setIsMobile(width < 768);
|
||||
});
|
||||
|
||||
observer.observe(containerRef.current);
|
||||
return () => observer.disconnect();
|
||||
}, []);
|
||||
|
||||
// 렌더링 부분 수정
|
||||
return (
|
||||
<div
|
||||
ref={containerRef}
|
||||
className={cn(
|
||||
"flex h-full",
|
||||
isMobile ? "flex-col" : "flex-row" // 모바일: 상하, 데스크톱: 좌우
|
||||
)}
|
||||
>
|
||||
<div style={{
|
||||
width: isMobile ? "100%" : `${leftWidth}%`,
|
||||
minHeight: isMobile ? "300px" : "auto"
|
||||
}}>
|
||||
{/* 좌측/상단 패널 */}
|
||||
</div>
|
||||
<div style={{
|
||||
width: isMobile ? "100%" : `${100 - leftWidth}%`,
|
||||
minHeight: isMobile ? "300px" : "auto"
|
||||
}}>
|
||||
{/* 우측/하단 패널 */}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 렌더링 분기 처리
|
||||
|
||||
```typescript
|
||||
// frontend/lib/registry/DynamicComponentRenderer.tsx
|
||||
|
||||
function renderLayout(layout: LayoutData) {
|
||||
// layoutMode에 따라 분기
|
||||
if (layout.layoutMode === "grid") {
|
||||
return <ResponsiveGridLayout layout={layout} renderer={this} />;
|
||||
}
|
||||
|
||||
// 기존 방식 (폴백)
|
||||
return <FlexboxLayout layout={layout} renderer={this} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 마이그레이션
|
||||
|
||||
### 7.1 백업
|
||||
|
||||
```sql
|
||||
-- 마이그레이션 전 백업
|
||||
CREATE TABLE screen_layouts_v2_backup_20260130 AS
|
||||
SELECT * FROM screen_layouts_v2;
|
||||
```
|
||||
|
||||
### 7.2 마이그레이션 스크립트
|
||||
|
||||
```sql
|
||||
-- grid, responsive 필드 추가
|
||||
UPDATE screen_layouts_v2
|
||||
SET layout_data = (
|
||||
SELECT jsonb_set(
|
||||
jsonb_set(
|
||||
layout_data,
|
||||
'{layoutMode}',
|
||||
'"grid"'
|
||||
),
|
||||
'{components}',
|
||||
(
|
||||
SELECT jsonb_agg(
|
||||
comp || jsonb_build_object(
|
||||
'grid', jsonb_build_object(
|
||||
'col', GREATEST(1, LEAST(12, ROUND((comp->'position'->>'x')::NUMERIC / 160) + 1)),
|
||||
'row', GREATEST(1, ROUND((comp->'position'->>'y')::NUMERIC / 80) + 1),
|
||||
'colSpan', GREATEST(1, ROUND((comp->'size'->>'width')::NUMERIC / 160)),
|
||||
'rowSpan', GREATEST(1, ROUND((comp->'size'->>'height')::NUMERIC / 80))
|
||||
),
|
||||
'responsive', jsonb_build_object(
|
||||
'sm', jsonb_build_object('col', 1, 'colSpan', 12),
|
||||
'md', jsonb_build_object(
|
||||
'col', GREATEST(1, ROUND((ROUND((comp->'position'->>'x')::NUMERIC / 160) + 1) / 2.0)),
|
||||
'colSpan', LEAST(ROUND((comp->'size'->>'width')::NUMERIC / 160) * 2, 12)
|
||||
),
|
||||
'lg', jsonb_build_object(
|
||||
'col', GREATEST(1, LEAST(12, ROUND((comp->'position'->>'x')::NUMERIC / 160) + 1)),
|
||||
'colSpan', GREATEST(1, ROUND((comp->'size'->>'width')::NUMERIC / 160))
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
FROM jsonb_array_elements(layout_data->'components') as comp
|
||||
)
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
### 7.3 롤백
|
||||
|
||||
```sql
|
||||
-- 문제 발생 시 롤백
|
||||
DROP TABLE screen_layouts_v2;
|
||||
ALTER TABLE screen_layouts_v2_backup_20260130 RENAME TO screen_layouts_v2;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 동작 흐름
|
||||
|
||||
### 8.1 데스크톱 (> 1024px)
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ 1 2 3 4 5 6 7 8 9 10 │ 11 12 │ │
|
||||
│ │ [버튼] │ │
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 테이블 (12컬럼) │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 8.2 태블릿 (768px ~ 1024px)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 1 2 3 4 5 6 │ 7 8 9 10 11 12 │
|
||||
│ │ [버튼] │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ 테이블 (12컬럼) │
|
||||
│ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 8.3 모바일 (< 768px)
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ [버튼] │ ← 12컬럼 (전체 너비)
|
||||
├──────────────────┤
|
||||
│ │
|
||||
│ 테이블 (스크롤) │ ← 12컬럼 (전체 너비)
|
||||
│ │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### 8.4 분할 패널 (반응형)
|
||||
|
||||
**데스크톱**:
|
||||
```
|
||||
┌─────────────────────────┬─────────────────────────┐
|
||||
│ 좌측 패널 (60%) │ 우측 패널 (40%) │
|
||||
└─────────────────────────┴─────────────────────────┘
|
||||
```
|
||||
|
||||
**모바일**:
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ 상단 패널 (이전 좌측) │
|
||||
├─────────────────────────┤
|
||||
│ 하단 패널 (이전 우측) │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 수정 파일 목록
|
||||
|
||||
### 9.1 새로 생성
|
||||
|
||||
| 파일 | 설명 |
|
||||
|------|------|
|
||||
| `lib/utils/gridConverter.ts` | 픽셀 → 그리드 변환 유틸리티 |
|
||||
| `lib/registry/layouts/responsive-grid/ResponsiveGridLayout.tsx` | CSS Grid 레이아웃 |
|
||||
| `lib/registry/layouts/responsive-grid/useBreakpoint.ts` | ResizeObserver 훅 |
|
||||
| `lib/registry/layouts/responsive-grid/index.ts` | 모듈 export |
|
||||
|
||||
### 9.2 수정
|
||||
|
||||
| 파일 | 수정 내용 |
|
||||
|------|-----------|
|
||||
| `lib/registry/DynamicComponentRenderer.tsx` | layoutMode 분기 추가 |
|
||||
| `components/screen/ScreenDesigner.tsx` | 저장 시 grid/responsive 생성 |
|
||||
| `v2-split-panel-layout/SplitPanelLayoutComponent.tsx` | 반응형 처리 추가 |
|
||||
|
||||
### 9.3 수정 없음
|
||||
|
||||
| 파일 | 이유 |
|
||||
|------|------|
|
||||
| `v2-input/*` | 레이아웃과 무관 (shadcn 그대로) |
|
||||
| `v2-button-primary/*` | 레이아웃과 무관 (shadcn 그대로) |
|
||||
| `v2-table-list/*` | 레이아웃과 무관 (shadcn 그대로) |
|
||||
| `v2-select/*` | 레이아웃과 무관 (shadcn 그대로) |
|
||||
| **...모든 v2 컴포넌트** | **수정 불필요** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 작업 일정
|
||||
|
||||
| Phase | 작업 | 파일 | 시간 |
|
||||
|-------|------|------|------|
|
||||
| **1** | 그리드 변환 유틸리티 | `gridConverter.ts` | 2시간 |
|
||||
| **1** | 브레이크포인트 훅 | `useBreakpoint.ts` | 1시간 |
|
||||
| **2** | ResponsiveGridLayout | `ResponsiveGridLayout.tsx` | 4시간 |
|
||||
| **2** | 렌더링 분기 처리 | `DynamicComponentRenderer.tsx` | 1시간 |
|
||||
| **3** | 저장 로직 수정 | `ScreenDesigner.tsx` | 2시간 |
|
||||
| **3** | 분할 패널 반응형 | `SplitPanelLayoutComponent.tsx` | 3시간 |
|
||||
| **4** | 마이그레이션 스크립트 | SQL | 2시간 |
|
||||
| **4** | 마이그레이션 실행 | - | 1시간 |
|
||||
| **5** | 테스트 및 버그 수정 | - | 4시간 |
|
||||
| | **합계** | | **약 2.5일** |
|
||||
|
||||
---
|
||||
|
||||
## 11. 체크리스트
|
||||
|
||||
### 개발 전
|
||||
|
||||
- [ ] screen_layouts_v2 백업 완료
|
||||
- [ ] 개발 환경에서 테스트 데이터 준비
|
||||
|
||||
### Phase 1: 유틸리티
|
||||
|
||||
- [ ] `gridConverter.ts` 생성
|
||||
- [ ] `useBreakpoint.ts` 생성
|
||||
- [ ] 단위 테스트 작성
|
||||
|
||||
### Phase 2: 레이아웃
|
||||
|
||||
- [ ] `ResponsiveGridLayout.tsx` 생성
|
||||
- [ ] `DynamicComponentRenderer.tsx` 분기 추가
|
||||
- [ ] 기존 화면 정상 동작 확인
|
||||
|
||||
### Phase 3: 저장/수정
|
||||
|
||||
- [ ] `ScreenDesigner.tsx` 저장 로직 수정
|
||||
- [ ] `SplitPanelLayoutComponent.tsx` 반응형 추가
|
||||
- [ ] 디자인 모드 테스트
|
||||
|
||||
### Phase 4: 마이그레이션
|
||||
|
||||
- [ ] 마이그레이션 스크립트 테스트 (개발 DB)
|
||||
- [ ] 운영 DB 백업
|
||||
- [ ] 마이그레이션 실행
|
||||
- [ ] 검증
|
||||
|
||||
### Phase 5: 테스트
|
||||
|
||||
- [ ] PC (1920px, 1280px) 테스트
|
||||
- [ ] 태블릿 (768px, 1024px) 테스트
|
||||
- [ ] 모바일 (375px, 414px) 테스트
|
||||
- [ ] 분할 패널 화면 테스트
|
||||
|
||||
---
|
||||
|
||||
## 12. 리스크 및 대응
|
||||
|
||||
| 리스크 | 영향 | 대응 |
|
||||
|--------|------|------|
|
||||
| 마이그레이션 실패 | 높음 | 백업 테이블에서 즉시 롤백 |
|
||||
| 기존 화면 깨짐 | 중간 | `layoutMode` 없으면 기존 방식 사용 (폴백) |
|
||||
| 디자인 모드 혼란 | 낮음 | position/size 필드 유지 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 참고
|
||||
|
||||
- [COMPONENT_LAYOUT_V2_ARCHITECTURE.md](./COMPONENT_LAYOUT_V2_ARCHITECTURE.md) - V2 아키텍처
|
||||
- [CSS Grid Layout - MDN](https://developer.mozilla.org/ko/docs/Web/CSS/CSS_Grid_Layout)
|
||||
- [ResizeObserver - MDN](https://developer.mozilla.org/ko/docs/Web/API/ResizeObserver)
|
||||
- [shadcn/ui](https://ui.shadcn.com/) - 컴포넌트 라이브러리
|
||||
524
docs/SCREEN_COPY_V2_MIGRATION_PLAN.md
Normal file
524
docs/SCREEN_COPY_V2_MIGRATION_PLAN.md
Normal file
@@ -0,0 +1,524 @@
|
||||
# 화면 복제 로직 V2 마이그레이션 계획서
|
||||
|
||||
> 작성일: 2026-01-28
|
||||
|
||||
## 1. 현황 분석
|
||||
|
||||
### 1.1 현재 복제 방식 (Legacy)
|
||||
|
||||
```
|
||||
테이블: screen_layouts (다중 레코드)
|
||||
방식: 화면당 N개 레코드 (컴포넌트 수만큼)
|
||||
저장: properties에 전체 설정 "박제"
|
||||
```
|
||||
|
||||
**데이터 구조:**
|
||||
```sql
|
||||
-- 화면당 여러 레코드
|
||||
SELECT * FROM screen_layouts WHERE screen_id = 123;
|
||||
-- layout_id | screen_id | component_type | component_id | properties (전체 설정)
|
||||
-- 1 | 123 | table-list | comp_001 | {"tableName": "user", "columns": [...], ...}
|
||||
-- 2 | 123 | button | comp_002 | {"label": "저장", "variant": "default", ...}
|
||||
```
|
||||
|
||||
### 1.2 V2 방식
|
||||
|
||||
```
|
||||
테이블: screen_layouts_v2 (1개 레코드)
|
||||
방식: 화면당 1개 레코드 (JSONB)
|
||||
저장: url + overrides (차이값만)
|
||||
```
|
||||
|
||||
**데이터 구조:**
|
||||
```sql
|
||||
-- 화면당 1개 레코드
|
||||
SELECT layout_data FROM screen_layouts_v2 WHERE screen_id = 123;
|
||||
-- {
|
||||
-- "version": "2.0",
|
||||
-- "components": [
|
||||
-- { "id": "comp_001", "url": "@/lib/registry/components/table-list", "overrides": {...} },
|
||||
-- { "id": "comp_002", "url": "@/lib/registry/components/button-primary", "overrides": {...} }
|
||||
-- ]
|
||||
-- }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 현재 복제 로직 분석
|
||||
|
||||
### 2.1 복제 진입점 (2곳)
|
||||
|
||||
| 경로 | 파일 | 함수 | 용도 |
|
||||
|-----|------|------|-----|
|
||||
| 단일 화면 복제 | `screenManagementService.ts` | `copyScreen()` | 화면 관리에서 개별 화면 복제 |
|
||||
| 메뉴 일괄 복제 | `menuCopyService.ts` | `copyScreens()` | 메뉴 복제 시 연결된 화면들 복제 |
|
||||
|
||||
### 2.2 screenManagementService.copyScreen() 흐름
|
||||
|
||||
```
|
||||
1. screen_definitions 조회 (원본)
|
||||
2. screen_definitions INSERT (대상)
|
||||
3. screen_layouts 조회 (원본) ← Legacy
|
||||
4. flowId 수집 및 복제 (회사 간 복제 시)
|
||||
5. numberingRuleId 수집 및 복제 (회사 간 복제 시)
|
||||
6. componentId 재생성 (idMapping)
|
||||
7. properties 내 참조 업데이트 (flowId, ruleId)
|
||||
8. screen_layouts INSERT (대상) ← Legacy
|
||||
```
|
||||
|
||||
**V2 처리: ❌ 없음**
|
||||
|
||||
### 2.3 menuCopyService.copyScreens() 흐름
|
||||
|
||||
```
|
||||
1단계: screen_definitions 처리
|
||||
- 기존 복사본 존재 시: 업데이트
|
||||
- 없으면: 신규 생성
|
||||
- screenIdMap 생성
|
||||
|
||||
2단계: screen_layouts 처리
|
||||
- 원본 조회
|
||||
- componentIdMap 생성
|
||||
- properties 내 참조 업데이트 (screenId, flowId, ruleId, menuId)
|
||||
- 배치 INSERT
|
||||
```
|
||||
|
||||
**V2 처리: ❌ 없음**
|
||||
|
||||
### 2.4 복제 시 처리되는 참조 ID들
|
||||
|
||||
| 참조 ID | 설명 | 매핑 방식 |
|
||||
|--------|-----|----------|
|
||||
| `componentId` | 컴포넌트 고유 ID | 새로 생성 (`comp_xxx`) |
|
||||
| `parentId` | 부모 컴포넌트 ID | componentIdMap으로 매핑 |
|
||||
| `flowId` | 노드 플로우 ID | flowIdMap으로 매핑 (회사 간 복제 시) |
|
||||
| `numberingRuleId` | 채번 규칙 ID | ruleIdMap으로 매핑 (회사 간 복제 시) |
|
||||
| `screenId` (탭) | 탭에서 참조하는 화면 ID | screenIdMap으로 매핑 |
|
||||
| `menuObjid` | 메뉴 ID | menuIdMap으로 매핑 |
|
||||
|
||||
---
|
||||
|
||||
## 3. V2 마이그레이션 시 변경 필요 사항
|
||||
|
||||
### 3.1 핵심 변경점
|
||||
|
||||
| 항목 | Legacy | V2 |
|
||||
|-----|--------|-----|
|
||||
| 읽기 테이블 | `screen_layouts` | `screen_layouts_v2` |
|
||||
| 쓰기 테이블 | `screen_layouts` | `screen_layouts_v2` |
|
||||
| 데이터 형태 | N개 레코드 | 1개 JSONB |
|
||||
| ID 매핑 위치 | 각 레코드의 컬럼 | JSONB 내부 순회 |
|
||||
| 참조 업데이트 | `properties` JSON | `overrides` JSON |
|
||||
|
||||
### 3.2 수정해야 할 함수들
|
||||
|
||||
#### screenManagementService.ts
|
||||
|
||||
| 함수 | 변경 내용 |
|
||||
|-----|----------|
|
||||
| `copyScreen()` | screen_layouts_v2 복제 로직 추가 |
|
||||
| `collectFlowIdsFromLayouts()` | V2 JSONB 구조에서 flowId 수집 |
|
||||
| `collectNumberingRuleIdsFromLayouts()` | V2 JSONB 구조에서 ruleId 수집 |
|
||||
| `updateFlowIdsInProperties()` | V2 overrides 내 flowId 업데이트 |
|
||||
| `updateNumberingRuleIdsInProperties()` | V2 overrides 내 ruleId 업데이트 |
|
||||
|
||||
#### menuCopyService.ts
|
||||
|
||||
| 함수 | 변경 내용 |
|
||||
|-----|----------|
|
||||
| `copyScreens()` | screen_layouts_v2 복제 로직 추가 |
|
||||
| `hasLayoutChanges()` | V2 JSONB 비교 로직 |
|
||||
| `updateReferencesInProperties()` | V2 overrides 내 참조 업데이트 |
|
||||
|
||||
### 3.3 새로 추가할 함수들
|
||||
|
||||
```typescript
|
||||
// V2 레이아웃 복제 (공통)
|
||||
async copyLayoutV2(
|
||||
sourceScreenId: number,
|
||||
targetScreenId: number,
|
||||
targetCompanyCode: string,
|
||||
mappings: {
|
||||
componentIdMap: Map<string, string>;
|
||||
flowIdMap: Map<number, number>;
|
||||
ruleIdMap: Map<string, string>;
|
||||
screenIdMap: Map<number, number>;
|
||||
menuIdMap?: Map<number, number>;
|
||||
},
|
||||
client: PoolClient
|
||||
): Promise<void>
|
||||
|
||||
// V2 JSONB에서 참조 ID 수집
|
||||
collectReferencesFromLayoutV2(layoutData: any): {
|
||||
flowIds: Set<number>;
|
||||
ruleIds: Set<string>;
|
||||
screenIds: Set<number>;
|
||||
}
|
||||
|
||||
// V2 JSONB 내 참조 업데이트
|
||||
updateReferencesInLayoutV2(
|
||||
layoutData: any,
|
||||
mappings: { ... }
|
||||
): any
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 마이그레이션 전략
|
||||
|
||||
### 4.1 전략: V2 완전 전환
|
||||
|
||||
```
|
||||
결정: V2만 복제 (Legacy 복제 제거)
|
||||
이유: 깔끔한 코드, 유지보수 용이, V2 아키텍처 일관성
|
||||
전제: 기존 화면들은 이미 screen_layouts_v2로 마이그레이션 완료 (1,347개 100%)
|
||||
```
|
||||
|
||||
### 4.2 단계별 계획
|
||||
|
||||
#### Phase 1: V2 복제 로직 구현 및 전환
|
||||
|
||||
```
|
||||
목표: Legacy 복제를 V2 복제로 완전 교체
|
||||
영향: 복제 시 screen_layouts_v2 테이블만 사용
|
||||
|
||||
작업:
|
||||
1. copyLayoutV2() 공통 함수 구현
|
||||
2. screenManagementService.copyScreen() - Legacy → V2 교체
|
||||
3. menuCopyService.copyScreens() - Legacy → V2 교체
|
||||
4. 테스트 및 검증
|
||||
```
|
||||
|
||||
#### Phase 2: Legacy 코드 정리
|
||||
|
||||
```
|
||||
목표: 불필요한 Legacy 복제 코드 제거
|
||||
영향: 코드 간소화
|
||||
|
||||
작업:
|
||||
1. screen_layouts 관련 복제 코드 제거
|
||||
2. 관련 헬퍼 함수 정리 (collectFlowIdsFromLayouts 등)
|
||||
3. 코드 리뷰 및 정리
|
||||
```
|
||||
|
||||
#### Phase 3: Legacy 테이블 정리 (선택, 추후)
|
||||
|
||||
```
|
||||
목표: 불필요한 테이블 제거
|
||||
영향: 데이터 정리
|
||||
|
||||
작업:
|
||||
1. screen_layouts 테이블 데이터 백업
|
||||
2. screen_layouts 테이블 삭제 (또는 보관)
|
||||
3. 관련 코드 정리
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 상세 구현 계획
|
||||
|
||||
### 5.1 Phase 1 작업 목록
|
||||
|
||||
| # | 작업 | 파일 | 예상 공수 |
|
||||
|---|-----|------|---------|
|
||||
| 1 | `copyLayoutV2()` 공통 함수 구현 | screenManagementService.ts | 2시간 |
|
||||
| 2 | `collectReferencesFromLayoutV2()` 구현 | screenManagementService.ts | 1시간 |
|
||||
| 3 | `updateReferencesInLayoutV2()` 구현 | screenManagementService.ts | 2시간 |
|
||||
| 4 | `copyScreen()` - Legacy 제거, V2로 교체 | screenManagementService.ts | 2시간 |
|
||||
| 5 | `copyScreens()` - Legacy 제거, V2로 교체 | menuCopyService.ts | 3시간 |
|
||||
| 6 | 단위 테스트 | - | 2시간 |
|
||||
| 7 | 통합 테스트 | - | 2시간 |
|
||||
|
||||
**총 예상 공수: 14시간 (약 2일)**
|
||||
|
||||
### 5.2 주요 변경 포인트
|
||||
|
||||
#### copyScreen() 변경 전후
|
||||
|
||||
**Before (Legacy):**
|
||||
```typescript
|
||||
// 4. 원본 화면의 레이아웃 정보 조회
|
||||
const sourceLayoutsResult = await client.query<any>(
|
||||
`SELECT * FROM screen_layouts WHERE screen_id = $1`,
|
||||
[sourceScreenId]
|
||||
);
|
||||
// ... N개 레코드 순회하며 INSERT
|
||||
```
|
||||
|
||||
**After (V2):**
|
||||
```typescript
|
||||
// 4. 원본 V2 레이아웃 조회
|
||||
const sourceLayoutV2 = await client.query(
|
||||
`SELECT layout_data FROM screen_layouts_v2
|
||||
WHERE screen_id = $1 AND company_code = $2`,
|
||||
[sourceScreenId, sourceCompanyCode]
|
||||
);
|
||||
// ... JSONB 변환 후 1개 레코드 INSERT
|
||||
```
|
||||
|
||||
#### copyScreens() 변경 전후
|
||||
|
||||
**Before (Legacy):**
|
||||
```typescript
|
||||
// 레이아웃 배치 INSERT
|
||||
await client.query(
|
||||
`INSERT INTO screen_layouts (...) VALUES ${layoutValues.join(", ")}`,
|
||||
layoutParams
|
||||
);
|
||||
```
|
||||
|
||||
**After (V2):**
|
||||
```typescript
|
||||
// V2 레이아웃 UPSERT
|
||||
await this.copyLayoutV2(
|
||||
originalScreenId, targetScreenId, sourceCompanyCode, targetCompanyCode,
|
||||
{ componentIdMap, flowIdMap, ruleIdMap, screenIdMap, menuIdMap },
|
||||
client
|
||||
);
|
||||
```
|
||||
|
||||
### 5.2 copyLayoutV2() 구현 방안
|
||||
|
||||
```typescript
|
||||
private async copyLayoutV2(
|
||||
sourceScreenId: number,
|
||||
targetScreenId: number,
|
||||
sourceCompanyCode: string,
|
||||
targetCompanyCode: string,
|
||||
mappings: {
|
||||
componentIdMap: Map<string, string>;
|
||||
flowIdMap?: Map<number, number>;
|
||||
ruleIdMap?: Map<string, string>;
|
||||
screenIdMap?: Map<number, number>;
|
||||
menuIdMap?: Map<number, number>;
|
||||
},
|
||||
client: PoolClient
|
||||
): Promise<void> {
|
||||
// 1. 원본 V2 레이아웃 조회
|
||||
const sourceResult = await client.query(
|
||||
`SELECT layout_data FROM screen_layouts_v2
|
||||
WHERE screen_id = $1 AND company_code = $2`,
|
||||
[sourceScreenId, sourceCompanyCode]
|
||||
);
|
||||
|
||||
if (sourceResult.rows.length === 0) {
|
||||
// V2 레이아웃 없으면 스킵 (Legacy만 있는 경우)
|
||||
return;
|
||||
}
|
||||
|
||||
const layoutData = sourceResult.rows[0].layout_data;
|
||||
|
||||
// 2. components 배열 순회하며 ID 매핑
|
||||
const updatedComponents = layoutData.components.map((comp: any) => {
|
||||
const newId = mappings.componentIdMap.get(comp.id) || comp.id;
|
||||
|
||||
// overrides 내 참조 업데이트
|
||||
let updatedOverrides = { ...comp.overrides };
|
||||
|
||||
// flowId 매핑
|
||||
if (mappings.flowIdMap && updatedOverrides.flowId) {
|
||||
const newFlowId = mappings.flowIdMap.get(updatedOverrides.flowId);
|
||||
if (newFlowId) updatedOverrides.flowId = newFlowId;
|
||||
}
|
||||
|
||||
// numberingRuleId 매핑
|
||||
if (mappings.ruleIdMap && updatedOverrides.numberingRuleId) {
|
||||
const newRuleId = mappings.ruleIdMap.get(updatedOverrides.numberingRuleId);
|
||||
if (newRuleId) updatedOverrides.numberingRuleId = newRuleId;
|
||||
}
|
||||
|
||||
// screenId 매핑 (탭 컴포넌트 등)
|
||||
if (mappings.screenIdMap && updatedOverrides.screenId) {
|
||||
const newScreenId = mappings.screenIdMap.get(updatedOverrides.screenId);
|
||||
if (newScreenId) updatedOverrides.screenId = newScreenId;
|
||||
}
|
||||
|
||||
// tabs 배열 내 screenId 매핑
|
||||
if (mappings.screenIdMap && Array.isArray(updatedOverrides.tabs)) {
|
||||
updatedOverrides.tabs = updatedOverrides.tabs.map((tab: any) => ({
|
||||
...tab,
|
||||
screenId: mappings.screenIdMap.get(tab.screenId) || tab.screenId
|
||||
}));
|
||||
}
|
||||
|
||||
return {
|
||||
...comp,
|
||||
id: newId,
|
||||
overrides: updatedOverrides
|
||||
};
|
||||
});
|
||||
|
||||
const newLayoutData = {
|
||||
...layoutData,
|
||||
components: updatedComponents,
|
||||
updatedAt: new Date().toISOString()
|
||||
};
|
||||
|
||||
// 3. 대상 V2 레이아웃 저장 (UPSERT)
|
||||
await client.query(
|
||||
`INSERT INTO screen_layouts_v2 (screen_id, company_code, layout_data, created_at, updated_at)
|
||||
VALUES ($1, $2, $3, NOW(), NOW())
|
||||
ON CONFLICT (screen_id, company_code)
|
||||
DO UPDATE SET layout_data = $3, updated_at = NOW()`,
|
||||
[targetScreenId, targetCompanyCode, JSON.stringify(newLayoutData)]
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 테스트 계획
|
||||
|
||||
### 6.1 단위 테스트
|
||||
|
||||
| 테스트 케이스 | 설명 |
|
||||
|-------------|------|
|
||||
| V2 레이아웃 복제 - 기본 | 단순 컴포넌트 복제 |
|
||||
| V2 레이아웃 복제 - flowId 매핑 | 회사 간 복제 시 flowId 변경 확인 |
|
||||
| V2 레이아웃 복제 - ruleId 매핑 | 회사 간 복제 시 ruleId 변경 확인 |
|
||||
| V2 레이아웃 복제 - 탭 screenId 매핑 | 탭 컴포넌트의 screenId 변경 확인 |
|
||||
| V2 레이아웃 없는 경우 | Legacy만 있는 화면 복제 시 스킵 확인 |
|
||||
|
||||
### 6.2 통합 테스트
|
||||
|
||||
| 테스트 케이스 | 설명 |
|
||||
|-------------|------|
|
||||
| 단일 화면 복제 (같은 회사) | copyScreen() - 동일 회사 내 복제 |
|
||||
| 단일 화면 복제 (다른 회사) | copyScreen() - 회사 간 복제 |
|
||||
| 메뉴 일괄 복제 | copyScreens() - 여러 화면 동시 복제 |
|
||||
| 모달 포함 복제 | copyScreenWithModals() - 메인 + 모달 복제 |
|
||||
|
||||
### 6.3 검증 항목
|
||||
|
||||
```
|
||||
복제 후 확인:
|
||||
- [ ] screen_layouts_v2에 레코드 생성됨
|
||||
- [ ] componentId가 새로 생성됨
|
||||
- [ ] flowId가 정확히 매핑됨
|
||||
- [ ] numberingRuleId가 정확히 매핑됨
|
||||
- [ ] 탭 컴포넌트의 screenId가 정확히 매핑됨
|
||||
- [ ] screen_layouts(Legacy)는 복제되지 않음
|
||||
- [ ] 복제된 화면이 프론트엔드에서 정상 로드됨
|
||||
- [ ] 복제된 화면 편집/저장 정상 동작
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 영향 분석
|
||||
|
||||
### 7.1 영향 받는 기능
|
||||
|
||||
| 기능 | 영향 | 비고 |
|
||||
|-----|-----|-----|
|
||||
| 화면 관리 - 화면 복제 | 직접 영향 | copyScreen() |
|
||||
| 화면 관리 - 그룹 복제 | 직접 영향 | copyScreenWithModals() |
|
||||
| 메뉴 복제 | 직접 영향 | menuCopyService.copyScreens() |
|
||||
| 화면 디자이너 | 간접 영향 | 복제된 화면 로드 시 V2 사용 |
|
||||
|
||||
### 7.2 롤백 계획
|
||||
|
||||
```
|
||||
V2 전환 롤백 (필요시):
|
||||
1. Git에서 이전 버전 복원 (copyScreen, copyScreens)
|
||||
2. Legacy 복제 코드 복원
|
||||
3. 테스트 후 배포
|
||||
|
||||
주의사항:
|
||||
- V2로 복제된 화면들은 screen_layouts_v2에만 데이터 존재
|
||||
- 롤백 시 해당 화면들은 screen_layouts에 데이터 없음
|
||||
- 필요시 V2 → Legacy 역변환 스크립트 실행
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 관련 파일
|
||||
|
||||
### 8.1 수정 대상
|
||||
|
||||
| 파일 | 변경 내용 |
|
||||
|-----|----------|
|
||||
| `backend-node/src/services/screenManagementService.ts` | copyLayoutV2(), copyScreen() 수정 |
|
||||
| `backend-node/src/services/menuCopyService.ts` | copyScreens() 수정 |
|
||||
|
||||
### 8.2 참고 파일
|
||||
|
||||
| 파일 | 설명 |
|
||||
|-----|-----|
|
||||
| `docs/COMPONENT_LAYOUT_V2_ARCHITECTURE.md` | V2 아키텍처 문서 |
|
||||
| `frontend/lib/api/screen.ts` | getLayoutV2, saveLayoutV2 |
|
||||
| `frontend/lib/utils/layoutV2Converter.ts` | V2 변환 유틸리티 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 체크리스트
|
||||
|
||||
### 9.1 개발 전
|
||||
|
||||
- [ ] V2 아키텍처 문서 숙지
|
||||
- [ ] 현재 복제 로직 코드 리뷰
|
||||
- [ ] 테스트 데이터 준비 (V2 레이아웃이 있는 화면)
|
||||
|
||||
### 9.2 Phase 1 완료 조건
|
||||
|
||||
- [x] copyLayoutV2() 함수 구현 ✅ 2026-01-28
|
||||
- [x] collectReferencesFromLayoutV2() 함수 구현 ✅ 2026-01-28
|
||||
- [x] updateReferencesInLayoutV2() 함수 구현 ✅ 2026-01-28
|
||||
- [x] copyScreen() - Legacy 제거, V2로 교체 ✅ 2026-01-28
|
||||
- [x] copyScreens() - Legacy 제거, V2로 교체 ✅ 2026-01-28
|
||||
- [x] hasLayoutChangesV2() 함수 추가 ✅ 2026-01-28
|
||||
- [x] updateTabScreenReferences() V2 지원 추가 ✅ 2026-01-28
|
||||
- [ ] 단위 테스트 통과
|
||||
- [ ] 통합 테스트 통과
|
||||
- [ ] V2 전용 복제 동작 확인
|
||||
|
||||
### 9.3 Phase 2 완료 조건
|
||||
|
||||
- [ ] Legacy 관련 헬퍼 함수 정리
|
||||
- [ ] 불필요한 코드 제거
|
||||
- [ ] 코드 리뷰 완료
|
||||
- [ ] 회귀 테스트 통과
|
||||
|
||||
---
|
||||
|
||||
## 10. 시뮬레이션 검증 결과
|
||||
|
||||
### 10.1 검증된 시나리오
|
||||
|
||||
| 시나리오 | 결과 | 비고 |
|
||||
|---------|------|------|
|
||||
| 같은 회사 내 복제 | ✅ 정상 | componentId만 새로 생성 |
|
||||
| 회사 간 복제 (flowId 매핑) | ✅ 정상 | flowIdMap 적용됨 |
|
||||
| 회사 간 복제 (ruleId 매핑) | ✅ 정상 | ruleIdMap 적용됨 |
|
||||
| 탭 컴포넌트 screenId 매핑 | ✅ 정상 | updateTabScreenReferences V2 지원 추가 |
|
||||
| V2 레이아웃 없는 화면 | ✅ 정상 | 스킵 처리 |
|
||||
|
||||
### 10.2 발견 및 수정된 문제
|
||||
|
||||
| 문제 | 해결 |
|
||||
|-----|------|
|
||||
| updateTabScreenReferences가 V2 미지원 | V2 처리 로직 추가 완료 |
|
||||
|
||||
### 10.3 Zod 활용 가능성
|
||||
|
||||
프론트엔드에 이미 훌륭한 Zod 유틸리티 존재:
|
||||
- `deepMerge()` - 깊은 병합
|
||||
- `extractCustomConfig()` - 차이값 추출
|
||||
- `loadComponentV2()` / `saveComponentV2()` - V2 로드/저장
|
||||
|
||||
향후 백엔드에도 Zod 추가 시:
|
||||
- 타입 안전성 향상
|
||||
- 프론트/백엔드 스키마 공유 가능
|
||||
- 범용 참조 탐색 로직으로 하드코딩 제거 가능
|
||||
|
||||
---
|
||||
|
||||
## 11. 변경 이력
|
||||
|
||||
| 날짜 | 변경 내용 | 작성자 |
|
||||
|-----|----------|-------|
|
||||
| 2026-01-28 | 초안 작성 | Claude |
|
||||
| 2026-01-28 | V2 완전 전환 전략으로 변경 (병행 운영 → V2 전용) | Claude |
|
||||
| 2026-01-28 | Phase 1 구현 완료 - V2 복제 함수들 구현 및 Legacy 교체 | Claude |
|
||||
| 2026-01-28 | 시뮬레이션 검증 - updateTabScreenReferences V2 지원 추가 | Claude |
|
||||
| 2026-01-28 | V2 경로 지원 추가 - action/sections 직접 경로 (componentConfig 없이) | Claude |
|
||||
| 2026-01-30 | **실제 코드 구현 완료** - copyScreen(), copyScreens() V2 전환 | Claude |
|
||||
356
docs/V2_COMPONENT_MIGRATION_ANALYSIS.md
Normal file
356
docs/V2_COMPONENT_MIGRATION_ANALYSIS.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# V2 컴포넌트 마이그레이션 분석 보고서
|
||||
|
||||
> 작성일: 2026-01-27
|
||||
> 목적: 미구현 V1 컴포넌트들의 V2 마이그레이션 가능성 분석
|
||||
|
||||
---
|
||||
|
||||
## 1. 현황 요약
|
||||
|
||||
| 구분 | 개수 | 비율 |
|
||||
|------|------|------|
|
||||
| V1 총 컴포넌트 | 7,170개 | 100% |
|
||||
| V2 마이그레이션 완료 | 5,212개 | 72.7% |
|
||||
| **미구현 (분석 대상)** | **~520개** | **7.3%** |
|
||||
|
||||
---
|
||||
|
||||
## 2. 미구현 컴포넌트 상세 분석
|
||||
|
||||
### 2.1 ✅ 통합 가능 (기존 V2 컴포넌트로 대체)
|
||||
|
||||
#### 2.1.1 `unified-list` (97개) → `v2-table-list`
|
||||
|
||||
**분석 결과**: ✅ **통합 가능**
|
||||
|
||||
| 항목 | unified-list | v2-table-list |
|
||||
|------|-------------|---------------|
|
||||
| 테이블 뷰 | ✅ | ✅ |
|
||||
| 카드 뷰 | ✅ | ❌ (추가 필요) |
|
||||
| 검색 | ✅ | ✅ |
|
||||
| 페이지네이션 | ✅ | ✅ |
|
||||
| 편집 가능 | ✅ | ✅ |
|
||||
|
||||
**결론**: `v2-table-list`에 `cardView` 모드만 추가하면 통합 가능. 또는 DB 마이그레이션으로 `v2-table-list`로 변환.
|
||||
|
||||
**작업량**: 중간 (v2-table-list 확장 또는 DB 마이그레이션)
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.2 `autocomplete-search-input` (50개) → `v2-select`
|
||||
|
||||
**분석 결과**: ✅ **통합 가능**
|
||||
|
||||
| 항목 | autocomplete-search-input | v2-select |
|
||||
|------|--------------------------|-----------|
|
||||
| 자동완성 드롭다운 | ✅ | ✅ (mode: autocomplete) |
|
||||
| 테이블 데이터 검색 | ✅ | ✅ (dataSource 설정) |
|
||||
| 표시/값 필드 분리 | ✅ | ✅ |
|
||||
|
||||
**결론**: `v2-select`의 `mode: "autocomplete"` 또는 `mode: "combobox"`로 대체 가능.
|
||||
|
||||
**작업량**: 낮음 (DB 마이그레이션만)
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.3 `repeater-field-group` (24개) → `v2-repeater`
|
||||
|
||||
**분석 결과**: ✅ **통합 가능**
|
||||
|
||||
`v2-repeater`가 이미 다음을 지원:
|
||||
- 인라인 테이블 모드
|
||||
- 모달 선택 모드
|
||||
- 버튼 모드
|
||||
|
||||
**결론**: `v2-repeater`의 `renderMode: "inline"`으로 대체.
|
||||
|
||||
**작업량**: 낮음 (DB 마이그레이션만)
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.4 `simple-repeater-table` (1개) → `v2-repeater`
|
||||
|
||||
**분석 결과**: ✅ **통합 가능**
|
||||
|
||||
**결론**: `v2-repeater`로 대체.
|
||||
|
||||
**작업량**: 매우 낮음
|
||||
|
||||
---
|
||||
|
||||
### 2.2 ⚠️ Renderer 추가만 필요 (코드 구조 있음)
|
||||
|
||||
#### 2.2.1 `split-panel-layout2` (8개)
|
||||
|
||||
**분석 결과**: ⚠️ **Renderer 추가 필요**
|
||||
|
||||
- V1 Renderer: `SplitPanelLayout2Renderer.tsx` ✅ 존재
|
||||
- V2 Renderer: ❌ 없음
|
||||
- Component: `SplitPanelLayout2Component.tsx` ✅ 존재
|
||||
|
||||
**결론**: V2 형식으로 DB 마이그레이션만 하면 됨 (기존 Renderer가 `split-panel-layout2` ID로 등록됨).
|
||||
|
||||
**작업량**: 매우 낮음 (DB 마이그레이션만)
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.2 `repeat-screen-modal` (7개)
|
||||
|
||||
**분석 결과**: ⚠️ **Renderer 추가 필요**
|
||||
|
||||
- V1 Renderer: `RepeatScreenModalRenderer.tsx` ✅ 존재
|
||||
- 정의: `hidden: true` (v2-repeat-screen-modal 사용으로 패널에서 숨김)
|
||||
|
||||
**결론**: 기존 Renderer 사용 가능, DB 마이그레이션만.
|
||||
|
||||
**작업량**: 매우 낮음
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.3 `related-data-buttons` (5개)
|
||||
|
||||
**분석 결과**: ⚠️ **Renderer 추가 필요**
|
||||
|
||||
- V1 Renderer: `RelatedDataButtonsRenderer.tsx` ✅ 존재
|
||||
- Component: `RelatedDataButtonsComponent.tsx` ✅ 존재
|
||||
|
||||
**결론**: 기존 Renderer 사용 가능, DB 마이그레이션만.
|
||||
|
||||
**작업량**: 매우 낮음
|
||||
|
||||
---
|
||||
|
||||
### 2.3 ❌ 별도 V2 개발 필요 (복잡한 구조)
|
||||
|
||||
#### 2.3.1 `entity-search-input` (99개)
|
||||
|
||||
**분석 결과**: ❌ **별도 개발 필요**
|
||||
|
||||
**특징**:
|
||||
```typescript
|
||||
// 모달 기반 엔티티 검색
|
||||
- 테이블 선택 (tableName)
|
||||
- 검색 필드 설정 (searchFields)
|
||||
- 모달 팝업 (modalTitle, modalColumns)
|
||||
- 값/표시 필드 분리 (valueField, displayField)
|
||||
- 추가 정보 표시 (additionalFields)
|
||||
```
|
||||
|
||||
**복잡도 요인**:
|
||||
1. 모달 검색 UI가 필요
|
||||
2. 다양한 테이블 연동
|
||||
3. 추가 필드 연계 로직
|
||||
|
||||
**권장 방안**:
|
||||
- `v2-entity-search` 새로 개발
|
||||
- 또는 `v2-select`에 `mode: "entity"` 추가
|
||||
|
||||
**작업량**: 높음 (1-2일)
|
||||
|
||||
---
|
||||
|
||||
#### 2.3.2 `modal-repeater-table` (68개)
|
||||
|
||||
**분석 결과**: ❌ **별도 개발 필요**
|
||||
|
||||
**특징**:
|
||||
```typescript
|
||||
// 모달에서 항목 검색 + 동적 테이블
|
||||
- 소스 테이블 (sourceTable, sourceColumns)
|
||||
- 모달 검색 (modalTitle, modalButtonText, multiSelect)
|
||||
- 동적 컬럼 추가 (columns)
|
||||
- 계산 규칙 (calculationRules)
|
||||
- 고유 필드 (uniqueField)
|
||||
```
|
||||
|
||||
**복잡도 요인**:
|
||||
1. 모달 검색 + 선택
|
||||
2. 동적 테이블 행 추가/삭제
|
||||
3. 계산 규칙 (단가 × 수량 = 금액)
|
||||
4. 중복 방지 로직
|
||||
|
||||
**권장 방안**:
|
||||
- `v2-repeater`의 `modal` 모드 확장
|
||||
- `ItemSelectionModal` + `RepeaterTable` 재사용
|
||||
|
||||
**작업량**: 중간 (v2-repeater가 이미 기반 제공)
|
||||
|
||||
---
|
||||
|
||||
#### 2.3.3 `selected-items-detail-input` (83개)
|
||||
|
||||
**분석 결과**: ❌ **별도 개발 필요**
|
||||
|
||||
**특징**:
|
||||
```typescript
|
||||
// 선택된 항목들의 상세 입력
|
||||
- 데이터 소스 (dataSourceId)
|
||||
- 표시 컬럼 (displayColumns)
|
||||
- 추가 입력 필드 (additionalFields)
|
||||
- 타겟 테이블 (targetTable)
|
||||
- 레이아웃 (grid/table)
|
||||
```
|
||||
|
||||
**복잡도 요인**:
|
||||
1. 부모 컴포넌트에서 데이터 수신
|
||||
2. 동적 필드 생성
|
||||
3. 다중 테이블 저장
|
||||
|
||||
**권장 방안**:
|
||||
- `v2-selected-items-detail` 새로 개발
|
||||
- 또는 `v2-repeater`에 `mode: "detail-input"` 추가
|
||||
|
||||
**작업량**: 중간~높음
|
||||
|
||||
---
|
||||
|
||||
#### 2.3.4 `conditional-container` (53개)
|
||||
|
||||
**분석 결과**: ❌ **별도 개발 필요**
|
||||
|
||||
**특징**:
|
||||
```typescript
|
||||
// 조건부 UI 분기
|
||||
- 제어 필드 (controlField, controlLabel)
|
||||
- 조건별 섹션 (sections: [{condition, label, screenId}])
|
||||
- 기본값 (defaultValue)
|
||||
```
|
||||
|
||||
**복잡도 요인**:
|
||||
1. 셀렉트박스 값에 따른 동적 UI 변경
|
||||
2. 화면 임베딩 (screenId)
|
||||
3. 상태 관리 복잡
|
||||
|
||||
**권장 방안**:
|
||||
- `v2-conditional-container` 새로 개발
|
||||
- 조건부 렌더링 + 화면 임베딩 로직
|
||||
|
||||
**작업량**: 높음
|
||||
|
||||
---
|
||||
|
||||
#### 2.3.5 `universal-form-modal` (26개)
|
||||
|
||||
**분석 결과**: ❌ **별도 개발 필요**
|
||||
|
||||
**특징**:
|
||||
```typescript
|
||||
// 범용 폼 모달
|
||||
- 섹션 기반 레이아웃
|
||||
- 반복 섹션
|
||||
- 채번규칙 연동
|
||||
- 다중 테이블 저장
|
||||
```
|
||||
|
||||
**복잡도 요인**:
|
||||
1. 동적 섹션 구성
|
||||
2. 채번규칙 연동
|
||||
3. 다중 테이블 저장
|
||||
4. 반복 필드 그룹
|
||||
|
||||
**권장 방안**:
|
||||
- `v2-universal-form` 새로 개발
|
||||
- 또는 기존 컴포넌트 유지 (특수 목적)
|
||||
|
||||
**작업량**: 매우 높음 (3일 이상)
|
||||
|
||||
---
|
||||
|
||||
### 2.4 🟢 V1 유지 권장 (특수 목적)
|
||||
|
||||
| 컴포넌트 | 개수 | 이유 |
|
||||
|----------|------|------|
|
||||
| `tax-invoice-list` | 1 | 세금계산서 전용, 재사용 낮음 |
|
||||
| `mail-recipient-selector` | 1 | 메일 전용, 재사용 낮음 |
|
||||
| `unified-select` | 5 | → v2-select로 이미 마이그레이션 |
|
||||
| `unified-date` | 2 | → v2-date로 이미 마이그레이션 |
|
||||
| `unified-repeater` | 2 | → v2-repeater로 이미 마이그레이션 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 마이그레이션 우선순위 권장
|
||||
|
||||
### 3.1 즉시 처리 (1일 이내)
|
||||
|
||||
| 순위 | 컴포넌트 | 개수 | 작업 |
|
||||
|------|----------|------|------|
|
||||
| 1 | `split-panel-layout2` | 8 | DB 마이그레이션만 |
|
||||
| 2 | `repeat-screen-modal` | 7 | DB 마이그레이션만 |
|
||||
| 3 | `related-data-buttons` | 5 | DB 마이그레이션만 |
|
||||
| 4 | `autocomplete-search-input` | 50 | → v2-select 변환 |
|
||||
| 5 | `repeater-field-group` | 24 | → v2-repeater 변환 |
|
||||
|
||||
**총: 94개 컴포넌트**
|
||||
|
||||
---
|
||||
|
||||
### 3.2 단기 처리 (1주 이내)
|
||||
|
||||
| 순위 | 컴포넌트 | 개수 | 작업 |
|
||||
|------|----------|------|------|
|
||||
| 1 | `unified-list` | 97 | → v2-table-list 확장 또는 변환 |
|
||||
| 2 | `modal-repeater-table` | 68 | v2-repeater modal 모드 확장 |
|
||||
|
||||
**총: 165개 컴포넌트**
|
||||
|
||||
---
|
||||
|
||||
### 3.3 중기 처리 (2주 이상)
|
||||
|
||||
| 순위 | 컴포넌트 | 개수 | 작업 |
|
||||
|------|----------|------|------|
|
||||
| 1 | `entity-search-input` | 99 | v2-entity-search 신규 개발 |
|
||||
| 2 | `selected-items-detail-input` | 83 | v2-selected-items-detail 개발 |
|
||||
| 3 | `conditional-container` | 53 | v2-conditional-container 개발 |
|
||||
| 4 | `universal-form-modal` | 26 | v2-universal-form 개발 |
|
||||
|
||||
**총: 261개 컴포넌트**
|
||||
|
||||
---
|
||||
|
||||
## 4. 권장 아키텍처
|
||||
|
||||
### 4.1 V2 컴포넌트 통합 계획
|
||||
|
||||
```
|
||||
v2-input ← text-input, number-input, textarea, unified-input ✅ 완료
|
||||
v2-select ← select-basic, checkbox, radio, autocomplete ⚠️ 진행중
|
||||
v2-date ← date-input, unified-date ✅ 완료
|
||||
v2-media ← file-upload, image-widget ✅ 완료
|
||||
v2-table-list ← table-list, unified-list ⚠️ 확장 필요
|
||||
v2-repeater ← repeater-field-group, modal-repeater-table,
|
||||
simple-repeater-table, related-data-buttons ⚠️ 진행중
|
||||
v2-entity-search ← entity-search-input (신규 개발 필요)
|
||||
v2-conditional ← conditional-container (신규 개발 필요)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 결론
|
||||
|
||||
### 즉시 처리 가능 (Renderer/DB만)
|
||||
- `split-panel-layout2`, `repeat-screen-modal`, `related-data-buttons`: **20개**
|
||||
- `autocomplete-search-input` → `v2-select`: **50개**
|
||||
- `repeater-field-group` → `v2-repeater`: **24개**
|
||||
|
||||
### 통합 검토 필요
|
||||
- `unified-list` → `v2-table-list` 확장: **97개**
|
||||
- `modal-repeater-table` → `v2-repeater` 확장: **68개**
|
||||
|
||||
### 신규 개발 필요
|
||||
- `entity-search-input`: **99개** (복잡도 높음)
|
||||
- `selected-items-detail-input`: **83개**
|
||||
- `conditional-container`: **53개**
|
||||
- `universal-form-modal`: **26개**
|
||||
|
||||
### 유지
|
||||
- 특수 목적 컴포넌트: **3개** (tax-invoice-list, mail-recipient-selector)
|
||||
|
||||
---
|
||||
|
||||
## 6. 다음 단계
|
||||
|
||||
1. **즉시**: `split-panel-layout2`, `repeat-screen-modal`, `related-data-buttons` DB 마이그레이션
|
||||
2. **이번 주**: `autocomplete-search-input` → `v2-select`, `repeater-field-group` → `v2-repeater` 변환
|
||||
3. **다음 주**: `unified-list`, `modal-repeater-table` 통합 설계
|
||||
4. **이후**: `entity-search-input`, `conditional-container` 신규 개발 계획 수립
|
||||
Reference in New Issue
Block a user