feat: 화면 그룹 및 서브 테이블 관련 로직 개선

- 화면 그룹 조회 시 삭제된 화면(is_active = 'D')을 제외하도록 쿼리를 수정하였습니다. - 화면 서브 테이블 API에서 전역 메인 테이블 목록을 수집하여, 메인 테이블과 서브 테이블의 우선순위를 적용하였습니다. - 화면 삭제 시 연결된 화면 그룹의 관계를 해제하는 로직을 추가하였습니다. - 화면 관계 흐름에서 연결된 화면들을 추가하는 로직을 개선하여, 그룹 모드와 개별 화면 모드에서의 동작을 명확히 하였습니다. - 관련 문서 및 주석을 업데이트하여 새로운 기능에 대한 이해를 돕도록 하였습니다.
2026-02-03 15:50:23 +09:00
parent dd1ddd6418
commit ef9f1b94ff
8 changed files with 510 additions and 64 deletions
--- a/docs/DDD1542/RESPONSIVE_GRID_SYSTEM_ARCHITECTURE.md
+++ b/docs/DDD1542/RESPONSIVE_GRID_SYSTEM_ARCHITECTURE.md
@@ -103,6 +103,162 @@
 - 분할 패널 반응형 처리
 ```

+### 2.5 레이아웃 시스템 구조
+
+현재 시스템에는 두 가지 레벨의 레이아웃이 존재합니다:
+
+#### 2.5.1 화면 레이아웃 (screen_layouts_v2)
+
+화면 전체의 컴포넌트 배치를 담당합니다.
+
+```json
+// DB 구조
+{
+  "version": "2.0",
+  "components": [
+    { "id": "comp_1", "position": { "x": 100, "y": 50 }, ... },
+    { "id": "comp_2", "position": { "x": 500, "y": 50 }, ... },
+    { "id": "GridLayout_1", "position": { "x": 100, "y": 200 }, ... }
+  ]
+}
+```
+
+**현재**: absolute 포지션으로 컴포넌트 배치 → **반응형 불가**
+
+#### 2.5.2 컴포넌트 레이아웃 (GridLayout, FlexboxLayout 등)
+
+개별 레이아웃 컴포넌트 내부의 zone 배치를 담당합니다.
+
+| 컴포넌트 | 위치 | 내부 구조 | CSS Grid 사용 |
+|----------|------|-----------|---------------|
+| `GridLayout` | `layouts/grid/` | zones 배열 | ✅ 이미 사용 |
+| `FlexboxLayout` | `layouts/flexbox/` | zones 배열 | ❌ absolute |
+| `SplitLayout` | `layouts/split/` | left/right | ❌ flex |
+| `TabsLayout` | `layouts/` | tabs 배열 | ❌ 탭 구조 |
+| `CardLayout` | `layouts/card-layout/` | zones 배열 | ❌ flex |
+| `AccordionLayout` | `layouts/accordion/` | items 배열 | ❌ 아코디언 |
+
+#### 2.5.3 구조 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  screen_layouts_v2 (화면 전체)                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  현재: absolute 포지션 → 반응형 불가                       │   │
+│  │  변경: ResponsiveGridLayout (CSS Grid) → 반응형 가능       │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌─────────────────────────────┐   │
+│  │ v2-button │  │ v2-input │  │ GridLayout (컴포넌트)        │   │
+│  │ (shadcn)  │  │ (shadcn) │  │ ┌─────────┬─────────────┐   │   │
+│  └──────────┘  └──────────┘  │ │ zone1   │ zone2       │   │   │
+│                              │ │ (이미   │ (이미       │   │   │
+│                              │ │ CSS Grid│ CSS Grid)   │   │   │
+│                              │ └─────────┴─────────────┘   │   │
+│                              └─────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.6 기존 레이아웃 컴포넌트 호환성
+
+#### 2.6.1 GridLayout (기존 커스텀 그리드)
+
+```tsx
+// frontend/lib/registry/layouts/grid/GridLayout.tsx
+// 이미 CSS Grid를 사용하고 있음!
+
+const gridStyle: React.CSSProperties = {
+  display: "grid",
+  gridTemplateRows: `repeat(${gridConfig.rows}, 1fr)`,
+  gridTemplateColumns: `repeat(${gridConfig.columns}, 1fr)`,
+  gap: `${gridConfig.gap || 16}px`,
+};
+```
+
+**호환성**: ✅ **완전 호환**
+- GridLayout은 화면 내 하나의 컴포넌트로 취급됨
+- ResponsiveGridLayout이 GridLayout의 **위치만** 관리
+- GridLayout 내부는 기존 방식 그대로 동작
+
+#### 2.6.2 FlexboxLayout
+
+```tsx
+// frontend/lib/registry/layouts/flexbox/FlexboxLayout.tsx
+// zone 내부에서 컴포넌트를 absolute로 배치
+
+{zoneChildren.map((child) => (
+  <div style={{
+    position: "absolute",
+    left: child.position?.x || 0,
+    top: child.position?.y || 0,
+  }}>
+    {renderer.renderChild(child)}
+  </div>
+))}
+```
+
+**호환성**: ✅ **호환** (내부는 기존 방식 유지)
+- FlexboxLayout 컴포넌트 자체의 위치는 ResponsiveGridLayout이 관리
+- 내부 zone의 컴포넌트 배치는 기존 absolute 방식 유지
+
+#### 2.6.3 SplitPanelLayout (분할 패널)
+
+**호환성**: ⚠️ **별도 수정 필요**
+- 외부 위치: ResponsiveGridLayout이 관리 ✅
+- 내부 반응형: 별도 수정 필요 (모바일에서 상하 분할)
+
+#### 2.6.4 호환성 요약
+
+| 컴포넌트 | 외부 배치 | 내부 동작 | 추가 수정 |
+|----------|----------|----------|-----------|
+| **v2-button, v2-input 등** | ✅ 반응형 | ✅ shadcn 그대로 | ❌ 불필요 |
+| **GridLayout** | ✅ 반응형 | ✅ CSS Grid 그대로 | ❌ 불필요 |
+| **FlexboxLayout** | ✅ 반응형 | ⚠️ absolute 유지 | ❌ 불필요 |
+| **SplitPanelLayout** | ✅ 반응형 | ❌ 좌우 고정 | ⚠️ 내부 반응형 추가 |
+| **TabsLayout** | ✅ 반응형 | ✅ 탭 그대로 | ❌ 불필요 |
+
+### 2.7 동작 방식 비교
+
+#### 변경 전
+
+```
+화면 로드
+  ↓
+screen_layouts_v2에서 components 조회
+  ↓
+각 컴포넌트를 position.x, position.y로 absolute 배치
+  ↓
+GridLayout 컴포넌트도 absolute로 배치됨
+  ↓
+GridLayout 내부는 CSS Grid로 zone 배치
+  ↓
+결과: 화면 크기 변해도 모든 컴포넌트 위치 고정
+```
+
+#### 변경 후
+
+```
+화면 로드
+  ↓
+screen_layouts_v2에서 components 조회
+  ↓
+layoutMode === "grid" 확인
+  ↓
+ResponsiveGridLayout으로 렌더링 (CSS Grid)
+  ↓
+각 컴포넌트를 grid.col, grid.colSpan으로 배치
+  ↓
+화면 크기 감지 (ResizeObserver)
+  ↓
+breakpoint에 따라 responsive.sm/md/lg 적용
+  ↓
+GridLayout 컴포넌트도 반응형으로 배치됨
+  ↓
+GridLayout 내부는 기존 CSS Grid로 zone 배치 (변경 없음)
+  ↓
+결과: 화면 크기에 따라 컴포넌트 재배치
+```
+
 ---

 ## 3. 기술 결정
@@ -649,6 +805,10 @@ ALTER TABLE screen_layouts_v2_backup_20260130 RENAME TO screen_layouts_v2;
 - [ ] 태블릿 (768px, 1024px) 테스트
 - [ ] 모바일 (375px, 414px) 테스트
 - [ ] 분할 패널 화면 테스트
+- [ ] GridLayout 컴포넌트 포함 화면 테스트
+- [ ] FlexboxLayout 컴포넌트 포함 화면 테스트
+- [ ] TabsLayout 컴포넌트 포함 화면 테스트
+- [ ] 중첩 레이아웃 (GridLayout 안에 컴포넌트) 테스트

 ---

@@ -659,6 +819,8 @@ ALTER TABLE screen_layouts_v2_backup_20260130 RENAME TO screen_layouts_v2;
 | 마이그레이션 실패 | 높음 | 백업 테이블에서 즉시 롤백 |
 | 기존 화면 깨짐 | 중간 | `layoutMode` 없으면 기존 방식 사용 (폴백) |
 | 디자인 모드 혼란 | 낮음 | position/size 필드 유지 |
+| GridLayout 내부 깨짐 | 낮음 | 내부는 기존 방식 유지, 외부 배치만 변경 |
+| 중첩 레이아웃 문제 | 낮음 | 각 레이아웃 컴포넌트는 독립적으로 동작 |

 ---

--- a/docs/DDD1542/화면관계_시각화_개선_보고서.md
+++ b/docs/DDD1542/화면관계_시각화_개선_보고서.md
@@ -23,7 +23,8 @@
 | 테이블명 | 용도 | 주요 컬럼 |
 |----------|------|----------|
 | `screen_definitions` | 화면 정의 정보 | `screen_id`, `screen_name`, `table_name`, `company_code` |
-| `screen_layouts` | 화면 레이아웃/컴포넌트 정보 | `screen_id`, `properties` (JSONB - componentConfig 포함) |
+| `screen_layouts` | 화면 레이아웃/컴포넌트 정보 (Legacy) | `screen_id`, `properties` (JSONB - componentConfig 포함) |
+| `screen_layouts_v2` | 화면 레이아웃/컴포넌트 정보 (V2) | `screen_id`, `layout_data` (JSONB - components 배열) |
 | `screen_groups` | 화면 그룹 정보 | `group_id`, `group_code`, `group_name`, `parent_group_id` |
 | `screen_group_mappings` | 화면-그룹 매핑 | `group_id`, `screen_id`, `display_order` |

@@ -86,9 +87,17 @@ screen_groups (그룹)
    │           │
    │           └─── screen_definitions (화면)
    │                       │
-    │                       └─── screen_layouts (레이아웃/컴포넌트)
+    │                       ├─── screen_layouts (Legacy)
+    │                       │           │
+    │                       │           └─── properties.componentConfig
+    │                       │                   ├── fieldMappings
+    │                       │                   ├── parentDataMapping
+    │                       │                   ├── columns.mapping
+    │                       │                   └── rightPanel.relation
+    │                       │
+    │                       └─── screen_layouts_v2 (V2) ← 현재 표준
    │                                   │
-    │                                   └─── properties.componentConfig
+    │                                   └─── layout_data.components[].overrides
    │                                           ├── fieldMappings
    │                                           ├── parentDataMapping
    │                                           ├── columns.mapping
@@ -1120,9 +1129,12 @@ screenSubTables[screenId].subTables.push({
 21. [x] 필터 연결선 포커싱 제어 (해당 화면 포커싱 시에만 표시)
 22. [x] 저장 테이블 제외 조건 추가 (table-list + 체크박스 + openModalWithData)
 23. [x] 첫 진입 시 포커싱 없이 시작 (트리에서 화면 클릭 시 그룹만 진입)
-24. [ ] **선 교차점 이질감 해결** (계획 중)
-22. [ ] 범례 UI 추가 (선택사항)
-23. [ ] 엣지 라벨에 관계 유형 표시 (선택사항)
+24. [x] **screen_layouts_v2 지원 추가** (rightPanel.relation V2 UNION 쿼리) ✅ 2026-01-30
+25. [x] **테이블 분류 우선순위 시스템** (메인 > 서브 우선순위 적용) ✅ 2026-01-30
+26. [x] **globalMainTables API 추가** (WHERE 조건 대상 테이블 목록 반환) ✅ 2026-01-30
+27. [ ] **선 교차점 이질감 해결** (계획 중)
+28. [ ] 범례 UI 추가 (선택사항)
+29. [ ] 엣지 라벨에 관계 유형 표시 (선택사항)

 ---

@@ -1682,6 +1694,149 @@ frontend/

 ---

+## 테이블 분류 우선순위 시스템 (2026-01-30)
+
+### 배경
+
+마스터-디테일 관계의 디테일 테이블(예: `user_dept`)이 다른 곳에서 autocomplete 참조로도 사용되는 경우, 
+서브 테이블 영역에 잘못 배치되는 문제가 발생했습니다.
+
+### 문제 상황
+
+```
+[user_info] - 화면 139의 디테일 → 메인 테이블 영역 (O)
+[user_dept] - 화면 162의 디테일이지만 autocomplete 참조도 있음 → 서브 테이블 영역 (X)
+```
+
+**원인**: 테이블 분류 시 우선순위가 없어서 먼저 발견된 관계 타입으로 분류됨
+
+### 해결책: 우선순위 기반 테이블 분류
+
+#### 분류 규칙
+
+| 우선순위 | 분류 | 조건 | 비고 |
+|----------|------|------|------|
+| **1순위** | 메인 테이블 | `screen_definitions.table_name` | 컴포넌트 직접 연결 |
+| **1순위** | 메인 테이블 | `v2-split-panel-layout.rightPanel.tableName` | WHERE 조건 대상 |
+| **2순위** | 서브 테이블 | 조인으로만 연결된 테이블 | autocomplete 등 참조 |
+
+#### 핵심 규칙
+
+> **메인 조건에 해당하면, 서브 조건이 있어도 무조건 메인으로 분류**
+
+### 백엔드 변경 (`screenGroupController.ts`)
+
+#### 1. screen_layouts_v2 지원 추가
+
+`rightPanelQuery`에 V2 테이블 UNION 추가:
+
+```sql
+-- V1: screen_layouts에서 조회
+SELECT ...
+FROM screen_definitions sd
+JOIN screen_layouts sl ON sd.screen_id = sl.screen_id
+WHERE sl.properties->'componentConfig'->'rightPanel'->'relation' IS NOT NULL
+
+UNION ALL
+
+-- V2: screen_layouts_v2에서 조회 (v2-split-panel-layout 컴포넌트)
+SELECT 
+  sd.screen_id,
+  comp->'overrides'->>'type' as component_type,
+  comp->'overrides'->'rightPanel'->'relation' as right_panel_relation,
+  comp->'overrides'->'rightPanel'->>'tableName' as right_panel_table,
+  ...
+FROM screen_definitions sd
+JOIN screen_layouts_v2 slv2 ON sd.screen_id = slv2.screen_id,
+jsonb_array_elements(slv2.layout_data->'components') as comp
+WHERE comp->'overrides'->'rightPanel'->'relation' IS NOT NULL
+```
+
+#### 2. globalMainTables API 추가
+
+`getScreenSubTables` 응답에 전역 메인 테이블 목록 추가:
+
+```sql
+-- 모든 화면의 메인 테이블 수집
+SELECT DISTINCT table_name as main_table FROM screen_definitions WHERE screen_id = ANY($1)
+UNION
+SELECT DISTINCT comp->'overrides'->'rightPanel'->>'tableName' as main_table
+FROM screen_layouts_v2 ...
+```
+
+**응답 구조:**
+```typescript
+res.json({
+  success: true,
+  data: screenSubTables,
+  globalMainTables: globalMainTables,  // 메인 테이블 목록 추가
+});
+```
+
+### 프론트엔드 변경 (`ScreenRelationFlow.tsx`)
+
+#### 1. globalMainTables 상태 추가
+
+```typescript
+const [globalMainTables, setGlobalMainTables] = useState<Set<string>>(new Set());
+```
+
+#### 2. 우선순위 기반 테이블 분류
+
+```typescript
+// 1. globalMainTables를 mainTableSet에 먼저 추가 (우선순위 적용)
+globalMainTables.forEach((tableName) => {
+  if (!mainTableSet.has(tableName)) {
+    mainTableSet.add(tableName);
+    filterTableSet.add(tableName);  // 보라색 테두리
+  }
+});
+
+// 2. 서브 테이블 수집 (mainTableSet에 없는 것만)
+screenSubData.subTables.forEach((subTable) => {
+  if (mainTableSet.has(subTable.tableName)) {
+    return;  // 메인 테이블은 서브에서 제외
+  }
+  subTableSet.add(subTable.tableName);
+});
+```
+
+### 시각적 결과
+
+#### 변경 전
+
+```
+[화면 노드들]
+     │
+     ▼
+[메인 테이블: dept_info, user_info]  ← user_dept 없음
+     │
+     ▼
+[서브 테이블: user_dept, customer_mng]  ← user_dept가 잘못 배치됨
+```
+
+#### 변경 후
+
+```
+[화면 노드들]
+     │
+     ▼
+[메인 테이블: dept_info, user_info, user_dept]  ← user_dept 보라색 테두리
+     │
+     ▼
+[서브 테이블: customer_mng]  ← 조인 참조용 테이블만
+```
+
+### 관련 파일
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `backend-node/src/controllers/screenGroupController.ts` | screen_layouts_v2 UNION 추가, globalMainTables 반환 |
+| `frontend/components/screen/ScreenRelationFlow.tsx` | globalMainTables 상태, 우선순위 분류 로직 |
+| `frontend/components/screen/ScreenNode.tsx` | isFilterTable prop 및 보라색 테두리 스타일 |
+
+---
+
 ## 화면 설정 모달 개선 (2026-01-12)

 ### 개요
@@ -1742,4 +1897,6 @@ npm install react-zoom-pan-pinch
 - [멀티테넌시 구현 가이드](.cursor/rules/multi-tenancy-guide.mdc)
 - [API 클라이언트 사용 규칙](.cursor/rules/api-client-usage.mdc)
 - [관리자 페이지 스타일 가이드](.cursor/rules/admin-page-style-guide.mdc)
+- [화면 복제 V2 마이그레이션 계획서](../SCREEN_COPY_V2_MIGRATION_PLAN.md) - screen_layouts_v2 복제 로직
+- [V2 컴포넌트 마이그레이션 분석](../V2_COMPONENT_MIGRATION_ANALYSIS.md) - V2 아키텍처