# 컴포넌트 레이아웃 V2 아키텍처

> 최종 업데이트: 2026-01-27

## 1. 개요

### 1.1 목표
- **핵심 목표**: 컴포넌트 코드 수정 시 모든 화면에 자동 반영
- **문제 해결**: 기존 JSON "박제" 방식으로 인한 코드 수정 미반영 문제
- **방식**: 1 레코드 방식 (화면당 1개 레코드, JSON에 모든 컴포넌트 포함)

### 1.2 핵심 원칙
```
저장: component_url + overrides (차이값만)
로드: 코드 기본값 + overrides 병합 (Zod)
```

**이전 방식 (문제점)**:
```json
// 전체 설정 박제 → 코드 수정해도 반영 안 됨
{
  "componentType": "table-list",
  "componentConfig": {
    "columns": [...],
    "pagination": true,
    "pageSize": 20,
    // ... 수백 줄의 설정
  }
}
```

**V2 방식 (해결)**:
```json
// url로 코드 참조 + 차이값만 저장
{
  "url": "@/lib/registry/components/table-list",
  "overrides": {
    "tableName": "user_info",
    "columns": ["id", "name"]
  }
}
```

---

## 2. 데이터베이스 구조

### 2.1 테이블 정의

```sql
CREATE TABLE screen_layouts_v2 (
  layout_id      SERIAL PRIMARY KEY,
  screen_id      INTEGER NOT NULL,
  company_code   VARCHAR(20) NOT NULL,
  layout_data    JSONB NOT NULL DEFAULT '{}'::jsonb,
  created_at     TIMESTAMPTZ DEFAULT NOW(),
  updated_at     TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(screen_id, company_code)
);

-- 인덱스
CREATE INDEX idx_v2_screen_id ON screen_layouts_v2(screen_id);
CREATE INDEX idx_v2_company_code ON screen_layouts_v2(company_code);
CREATE INDEX idx_v2_screen_company ON screen_layouts_v2(screen_id, company_code);
```

### 2.2 layout_data 구조

```json
{
  "version": "2.0",
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/table-list",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 100, "height": 50 },
      "displayOrder": 0,
      "overrides": {
        "tableName": "user_info",
        "columns": ["id", "name", "email"]
      }
    },
    {
      "id": "comp_yyy",
      "url": "@/lib/registry/components/button-primary",
      "position": { "x": 0, "y": 60 },
      "size": { "width": 20, "height": 5 },
      "displayOrder": 1,
      "overrides": {
        "label": "저장",
        "variant": "default"
      }
    }
  ],
  "updatedAt": "2026-01-27T12:00:00Z"
}
```

### 2.3 필드 설명

| 필드 | 타입 | 설명 |
|-----|-----|-----|
| `id` | string | 컴포넌트 고유 ID |
| `url` | string | 컴포넌트 코드 경로 (필수) |
| `position` | object | 캔버스 내 위치 {x, y} |
| `size` | object | 크기 {width, height} |
| `displayOrder` | number | 렌더링 순서 |
| `overrides` | object | 기본값과 다른 설정만 (차이값) |

---

## 3. API 정의

### 3.1 레이아웃 조회

```
GET /api/screen-management/screens/:screenId/layout-v2
```

**응답**:
```json
{
  "success": true,
  "data": {
    "version": "2.0",
    "components": [...]
  }
}
```

**로직**:
1. 회사별 레이아웃 먼저 조회
2. 없으면 공통(*) 레이아웃 조회
3. 없으면 null 반환

### 3.2 레이아웃 저장

```
POST /api/screen-management/screens/:screenId/layout-v2
```

**요청**:
```json
{
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/table-list",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 100, "height": 50 },
      "overrides": { ... }
    }
  ]
}
```

**로직**:
1. 권한 확인
2. 버전 정보 추가
3. UPSERT (있으면 업데이트, 없으면 삽입)

---

## 4. 컴포넌트 URL 규칙

### 4.1 URL 형식

```
@/lib/registry/components/{component-name}
```

### 4.2 현재 등록된 컴포넌트

| URL | 설명 |
|-----|-----|
| `@/lib/registry/components/table-list` | 테이블 리스트 |
| `@/lib/registry/components/button-primary` | 기본 버튼 |
| `@/lib/registry/components/text-input` | 텍스트 입력 |
| `@/lib/registry/components/select-basic` | 기본 셀렉트 |
| `@/lib/registry/components/date-input` | 날짜 입력 |
| `@/lib/registry/components/split-panel-layout` | 분할 패널 |
| `@/lib/registry/components/tabs-widget` | 탭 위젯 |
| `@/lib/registry/components/card-display` | 카드 디스플레이 |
| `@/lib/registry/components/flow-widget` | 플로우 위젯 |
| `@/lib/registry/components/category-management` | 카테고리 관리 |
| `@/lib/registry/components/pivot-table` | 피벗 테이블 |
| `@/lib/registry/components/unified-grid` | 통합 그리드 |

---

## 5. Zod 스키마 관리

### 5.1 목적
- 런타임 타입 검증
- 기본값 자동 적용
- overrides 유효성 검사

### 5.2 구조

```typescript
// frontend/lib/schemas/componentConfig.ts

import { z } from "zod";

// 공통 스키마
export const baseComponentSchema = z.object({
  id: z.string(),
  url: z.string(),
  position: z.object({
    x: z.number().default(0),
    y: z.number().default(0),
  }),
  size: z.object({
    width: z.number().default(100),
    height: z.number().default(100),
  }),
  displayOrder: z.number().default(0),
  overrides: z.record(z.any()).default({}),
});

// 컴포넌트별 overrides 스키마
export const tableListOverridesSchema = z.object({
  tableName: z.string().optional(),
  columns: z.array(z.string()).optional(),
  pagination: z.boolean().default(true),
  pageSize: z.number().default(20),
});

export const buttonOverridesSchema = z.object({
  label: z.string().default("버튼"),
  variant: z.enum(["default", "destructive", "outline", "ghost"]).default("default"),
  icon: z.string().optional(),
});
```

### 5.3 사용 방법

```typescript
// 로드 시: 코드 기본값 + overrides 병합
function loadComponent(component: any) {
  const schema = getSchemaByUrl(component.url);
  const defaults = schema.parse({});
  const merged = deepMerge(defaults, component.overrides);
  return merged;
}

// 저장 시: 기본값과 다른 부분만 추출
function saveComponent(component: any, config: any) {
  const schema = getSchemaByUrl(component.url);
  const defaults = schema.parse({});
  const overrides = extractDiff(defaults, config);
  return { ...component, overrides };
}
```

---

## 6. 마이그레이션 현황

### 6.1 완료된 작업

| 작업 | 상태 | 날짜 |
|-----|-----|-----|
| screen_layouts_v2 테이블 생성 | ✅ 완료 | 2026-01-27 |
| 기존 데이터 마이그레이션 | ✅ 완료 | 2026-01-27 |
| 백엔드 API 추가 (getLayoutV2, saveLayoutV2) | ✅ 완료 | 2026-01-27 |
| 프론트엔드 API 클라이언트 추가 | ✅ 완료 | 2026-01-27 |
| Zod 스키마 V2 확장 | ✅ 완료 | 2026-01-27 |
| V2 변환 유틸리티 (layoutV2Converter.ts) | ✅ 완료 | 2026-01-27 |
| ScreenDesigner V2 API 연동 | ✅ 완료 | 2026-01-27 |

### 6.2 마이그레이션 통계

```
마이그레이션 대상 화면: 1,347개
성공: 1,347개 (100%)
실패: 0개

컴포넌트 많은 화면 TOP 5:
- screen 74: 25개 컴포넌트
- screen 1204: 18개 컴포넌트
- screen 1242: 18개 컴포넌트
- screen 119: 18개 컴포넌트
- screen 1255: 18개 컴포넌트
```

---

## 7. 남은 작업

### 7.1 필수 작업

| 작업 | 우선순위 | 예상 공수 | 상태 |
|-----|---------|---------|------|
| 프론트엔드 디자이너 V2 API 연동 | 높음 | 3일 | ✅ 완료 |
| Zod 스키마 컴포넌트별 정의 | 높음 | 2일 | ✅ 완료 |
| V2 변환 유틸리티 | 높음 | 1일 | ✅ 완료 |
| 테스트 및 검증 | 중간 | 2일 | 🔄 진행 필요 |

### 7.2 선택 작업

| 작업 | 우선순위 | 예상 공수 |
|-----|---------|---------|
| 기존 API (layout, layout-v1) 제거 | 낮음 | 1일 |
| 기존 테이블 (screen_layouts, screen_layouts_v1) 정리 | 낮음 | 1일 |
| 마이그레이션 검증 도구 | 낮음 | 1일 |
| 컴포넌트별 기본값 레지스트리 확장 | 낮음 | 2일 |

---

## 8. 개발 가이드

### 8.1 새 컴포넌트 추가 시

1. **컴포넌트 코드 생성**
   ```
   frontend/lib/registry/components/{component-name}/
   ├── index.ts
   ├── {ComponentName}Renderer.tsx
   └── types.ts
   ```

2. **Zod 스키마 정의**
   ```typescript
   // frontend/lib/schemas/components/{component-name}.ts
   export const {componentName}OverridesSchema = z.object({
     // 컴포넌트 고유 설정
   });
   ```

3. **레지스트리 등록**
   ```typescript
   // frontend/lib/registry/components/index.ts
   export { default as {ComponentName} } from "./{component-name}";
   ```

### 8.2 화면 저장 시

```typescript
// 디자이너에서 저장 시
async function handleSave() {
  const layoutData = {
    components: components.map(comp => ({
      id: comp.id,
      url: comp.url,
      position: comp.position,
      size: comp.size,
      displayOrder: comp.displayOrder,
      overrides: extractOverrides(comp.url, comp.config)  // 차이값만 추출
    }))
  };
  
  await screenApi.saveLayoutV2(screenId, layoutData);
}
```

### 8.3 화면 로드 시

```typescript
// 화면 렌더러에서 로드 시
async function loadScreen(screenId: number) {
  const layoutData = await screenApi.getLayoutV2(screenId);
  
  const components = layoutData.components.map(comp => {
    const defaults = getDefaultsByUrl(comp.url);  // Zod 기본값
    const mergedConfig = deepMerge(defaults, comp.overrides);
    
    return {
      ...comp,
      config: mergedConfig
    };
  });
  
  return components;
}
```

---

## 9. 비교: 기존 vs V2

| 항목 | 기존 (다중 레코드) | V2 (1 레코드) |
|-----|------------------|--------------|
| 레코드 수 | 화면당 N개 (컴포넌트 수) | 화면당 1개 |
| 저장 방식 | 전체 설정 박제 | url + overrides |
| 코드 수정 반영 | ❌ 안 됨 | ✅ 자동 반영 |
| 중복 데이터 | 있음 (DB 컬럼 + JSON) | 없음 |
| 공사량 | - | 테이블 변경 필요 |

---

## 10. 관련 파일

### 10.1 백엔드
- `backend-node/src/services/screenManagementService.ts` - getLayoutV2, saveLayoutV2
- `backend-node/src/controllers/screenManagementController.ts` - API 엔드포인트
- `backend-node/src/routes/screenManagementRoutes.ts` - 라우트 정의

### 10.2 프론트엔드
- `frontend/lib/api/screen.ts` - getLayoutV2, saveLayoutV2 클라이언트
- `frontend/lib/schemas/componentConfig.ts` - Zod 스키마 및 V2 유틸리티
- `frontend/lib/utils/layoutV2Converter.ts` - V2 ↔ Legacy 변환 유틸리티
- `frontend/components/screen/ScreenDesigner.tsx` - V2 API 연동 (USE_V2_API 플래그)
- `frontend/lib/registry/components/` - 컴포넌트 레지스트리

### 10.3 데이터베이스
- `screen_layouts_v2` - V2 레이아웃 테이블

---

## 11. FAQ

### Q1: 기존 화면은 어떻게 되나요?
기존 화면은 마이그레이션되어 `screen_layouts_v2`에 저장됩니다. 디자이너가 V2 API를 사용하도록 수정되면 자동으로 새 구조를 사용합니다.

### Q2: 컴포넌트 코드를 수정하면 정말 전체 반영되나요?
네. `overrides`에는 차이값만 저장되고, 로드 시 코드의 기본값과 병합됩니다. 기본값을 수정하면 모든 화면에 반영됩니다.

### Q3: 회사별 설정은 어떻게 관리하나요?
`company_code` 컬럼으로 회사별 레이아웃을 분리합니다. 회사별 레이아웃이 없으면 공통(*) 레이아웃을 사용합니다.

### Q4: 기존 테이블(screen_layouts)은 언제 삭제하나요?
V2가 안정화되고 모든 기능이 정상 동작하는지 확인된 후에 삭제합니다. 최소 1개월 이상 병행 운영 권장.

---

## 12. 변경 이력

| 날짜 | 변경 내용 | 작성자 |
|-----|----------|-------|
| 2026-01-27 | 초안 작성, 테이블 생성, 마이그레이션, API 추가 | Claude |
| 2026-01-27 | Zod 스키마 V2 확장, 변환 유틸리티, ScreenDesigner 연동 | Claude |