Merge branch 'feature/v2-renewal' of http://39.117.244.52:3000/kjs/ERP-node into feat/multilang

backend-node/package-lock.json

@@ -1044,6 +1044,7 @@
       "integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.3",
@@ -2371,6 +2372,7 @@
       "resolved": "https://registry.npmjs.org/@redis/client/-/client-1.6.1.tgz",
       "integrity": "sha512-/KCsg3xSlR+nCK8/8ZYSknYxvXHwubJrU82F3Lm1Fp6789VQ0/3RJKfsmRXjqfaTA++23CvC3hqmqe/2GEt6Kw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "cluster-key-slot": "1.1.2",
         "generic-pool": "3.9.0",
@@ -3474,6 +3476,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.17.tgz",
       "integrity": "sha512-gfehUI8N1z92kygssiuWvLiwcbOB3IRktR6hTDgJlXMYh5OvkPSRmgfoBUmfZt+vhwJtX7v1Yw4KvvAf7c5QKQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -3710,6 +3713,7 @@
       "integrity": "sha512-tbsV1jPne5CkFQCgPBcDOt30ItF7aJoZL997JSF7MhGQqOeT3svWRYxiqlfA5RUdlHN6Fi+EI9bxqbdyAUZjYQ==",
       "dev": true,
       "license": "BSD-2-Clause",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "6.21.0",
         "@typescript-eslint/types": "6.21.0",
@@ -3927,6 +3931,7 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -4453,6 +4458,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.8.3",
         "caniuse-lite": "^1.0.30001741",
@@ -5663,6 +5669,7 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -7425,6 +7432,7 @@
       "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@jest/core": "^29.7.0",
         "@jest/types": "^29.6.3",
@@ -8394,7 +8402,6 @@
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
       "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "js-tokens": "^3.0.0 || ^4.0.0"
       },
@@ -9283,6 +9290,7 @@
       "resolved": "https://registry.npmjs.org/pg/-/pg-8.16.3.tgz",
       "integrity": "sha512-enxc1h0jA/aq5oSDMvqyW3q89ra6XIIDZgCX9vkMrnz5DFTw/Ny3Li2lFQ+pt3L6MCgm/5o2o8HW9hiJji+xvw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "pg-connection-string": "^2.9.1",
         "pg-pool": "^3.10.1",
@@ -10133,7 +10141,6 @@
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
       "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       }
@@ -10942,6 +10949,7 @@
       "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@cspotcode/source-map-support": "^0.8.0",
         "@tsconfig/node10": "^1.0.7",
@@ -11047,6 +11055,7 @@
       "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"

backend-node/src/app.ts

@@ -73,6 +73,7 @@ import codeMergeRoutes from "./routes/codeMergeRoutes"; // 코드 병합
 import numberingRuleRoutes from "./routes/numberingRuleRoutes"; // 채번 규칙 관리
 import entitySearchRoutes from "./routes/entitySearchRoutes"; // 엔티티 검색
 import screenEmbeddingRoutes from "./routes/screenEmbeddingRoutes"; // 화면 임베딩 및 데이터 전달
+import screenGroupRoutes from "./routes/screenGroupRoutes"; // 화면 그룹 관리
 import vehicleTripRoutes from "./routes/vehicleTripRoutes"; // 차량 운행 이력 관리
 import driverRoutes from "./routes/driverRoutes"; // 공차중계 운전자 관리
 import taxInvoiceRoutes from "./routes/taxInvoiceRoutes"; // 세금계산서 관리
@@ -197,6 +198,7 @@ app.use("/api/multilang", multilangRoutes);
 app.use("/api/table-management", tableManagementRoutes);
 app.use("/api/table-management", entityJoinRoutes); // 🎯 Entity 조인 기능
 app.use("/api/screen-management", screenManagementRoutes);
+app.use("/api/screen-groups", screenGroupRoutes); // 화면 그룹 관리
 app.use("/api/common-codes", commonCodeRoutes);
 app.use("/api/dynamic-form", dynamicFormRoutes);
 app.use("/api/files", fileRoutes);

backend-node/src/controllers/entityJoinController.ts

@@ -70,11 +70,23 @@ export class EntityJoinController {
             const userField = parsedAutoFilter.userField || "companyCode";
             const userValue = ((req as any).user as any)[userField];
 
-            if (userValue) {
+            // 🆕 프리뷰용 회사 코드 오버라이드 (최고 관리자만 허용)
-              searchConditions[filterColumn] = userValue;
+            let finalCompanyCode = userValue;
+            if (parsedAutoFilter.companyCodeOverride && userValue === "*") {
+              // 최고 관리자만 다른 회사 코드로 오버라이드 가능
+              finalCompanyCode = parsedAutoFilter.companyCodeOverride;
+              logger.info("🔓 최고 관리자 회사 코드 오버라이드:", {
+                originalCompanyCode: userValue,
+                overrideCompanyCode: parsedAutoFilter.companyCodeOverride,
+                tableName,
+              });
+            }
+
+            if (finalCompanyCode) {
+              searchConditions[filterColumn] = finalCompanyCode;
               logger.info("🔒 Entity 조인에 멀티테넌시 필터 적용:", {
                 filterColumn,
-                userValue,
+                finalCompanyCode,
                 tableName,
               });
             }

backend-node/src/controllers/tableManagementController.ts

@@ -775,18 +775,25 @@ export async function getTableData(
       const userField = autoFilter?.userField || "companyCode";
       const userValue = (req.user as any)[userField];
 
-      // 🆕 최고 관리자(company_code = '*')는 모든 회사 데이터 조회 가능
+      // 🆕 프리뷰용 회사 코드 오버라이드 (최고 관리자만 허용)
-      if (userValue && userValue !== "*") {
+      let finalCompanyCode = userValue;
-        enhancedSearch[filterColumn] = userValue;
+      if (autoFilter?.companyCodeOverride && userValue === "*") {
+        // 최고 관리자만 다른 회사 코드로 오버라이드 가능
+        finalCompanyCode = autoFilter.companyCodeOverride;
+        logger.info("🔓 최고 관리자 회사 코드 오버라이드:", {
+          originalCompanyCode: userValue,
+          overrideCompanyCode: autoFilter.companyCodeOverride,
+          tableName,
+        });
+      }
+
+      if (finalCompanyCode) {
+        enhancedSearch[filterColumn] = finalCompanyCode;
 
         logger.info("🔍 현재 사용자 필터 적용:", {
           filterColumn,
           userField,
-          userValue,
+          userValue: finalCompanyCode,
-          tableName,
-        });
-      } else if (userValue === "*") {
-        logger.info("🔓 최고 관리자 - 회사 필터 미적용 (모든 회사 데이터 조회)", {
           tableName,
         });
       } else {
@@ -798,7 +805,10 @@ export async function getTableData(
     }
 
     // 🆕 최종 검색 조건 로그
-    logger.info(`🔍 최종 검색 조건 (enhancedSearch):`, JSON.stringify(enhancedSearch));
+    logger.info(
+      `🔍 최종 검색 조건 (enhancedSearch):`,
+      JSON.stringify(enhancedSearch)
+    );
 
     // 데이터 조회
     const result = await tableManagementService.getTableData(tableName, {
@@ -883,7 +893,10 @@ export async function addTableData(
     const companyCode = req.user?.companyCode;
     if (companyCode && !data.company_code) {
       // 테이블에 company_code 컬럼이 있는지 확인
-      const hasCompanyCodeColumn = await tableManagementService.hasColumn(tableName, "company_code");
+      const hasCompanyCodeColumn = await tableManagementService.hasColumn(
+        tableName,
+        "company_code"
+      );
       if (hasCompanyCodeColumn) {
         data.company_code = companyCode;
         logger.info(`멀티테넌시: company_code 자동 추가 - ${companyCode}`);
@@ -893,7 +906,10 @@ export async function addTableData(
     // 🆕 writer 컬럼 자동 추가 (테이블에 writer 컬럼이 있고 값이 없는 경우)
     const userId = req.user?.userId;
     if (userId && !data.writer) {
-      const hasWriterColumn = await tableManagementService.hasColumn(tableName, "writer");
+      const hasWriterColumn = await tableManagementService.hasColumn(
+        tableName,
+        "writer"
+      );
       if (hasWriterColumn) {
         data.writer = userId;
         logger.info(`writer 자동 추가 - ${userId}`);
@@ -911,11 +927,13 @@ export async function addTableData(
       savedColumns?: string[];
     }> = {
       success: true,
-      message: result.skippedColumns.length > 0
+      message:
-        ? `테이블 데이터를 추가했습니다. (무시된 컬럼 ${result.skippedColumns.length}개: ${result.skippedColumns.join(", ")})`
+        result.skippedColumns.length > 0
-        : "테이블 데이터를 성공적으로 추가했습니다.",
+          ? `테이블 데이터를 추가했습니다. (무시된 컬럼 ${result.skippedColumns.length}개: ${result.skippedColumns.join(", ")})`
+          : "테이블 데이터를 성공적으로 추가했습니다.",
       data: {
-        skippedColumns: result.skippedColumns.length > 0 ? result.skippedColumns : undefined,
+        skippedColumns:
+          result.skippedColumns.length > 0 ? result.skippedColumns : undefined,
         savedColumns: result.savedColumns,
       },
     };
@@ -1645,10 +1663,10 @@ export async function toggleLogTable(
 
 /**
  * 메뉴의 상위 메뉴들이 설정한 모든 카테고리 타입 컬럼 조회 (계층 구조 상속)
- * 
+ *
  * @route GET /api/table-management/menu/:menuObjid/category-columns
  * @description 현재 메뉴와 상위 메뉴들에서 설정한 category_column_mapping의 모든 카테고리 컬럼 조회
- * 
+ *
  * 예시:
  * - 2레벨 메뉴 "고객사관리"에서 discount_type, rounding_type 설정
  * - 3레벨 메뉴 "고객등록", "고객조회" 등에서도 동일하게 보임 (상속)
@@ -1661,7 +1679,10 @@ export async function getCategoryColumnsByMenu(
     const { menuObjid } = req.params;
     const companyCode = req.user?.companyCode;
 
-    logger.info("📥 메뉴별 카테고리 컬럼 조회 요청", { menuObjid, companyCode });
+    logger.info("📥 메뉴별 카테고리 컬럼 조회 요청", {
+      menuObjid,
+      companyCode,
+    });
 
     if (!menuObjid) {
       res.status(400).json({
@@ -1687,8 +1708,11 @@ export async function getCategoryColumnsByMenu(
 
     if (mappingTableExists) {
       // 🆕 category_column_mapping을 사용한 계층 구조 기반 조회
-      logger.info("🔍 category_column_mapping 기반 카테고리 컬럼 조회 (계층 구조 상속)", { menuObjid, companyCode });
+      logger.info(
-      
+        "🔍 category_column_mapping 기반 카테고리 컬럼 조회 (계층 구조 상속)",
+        { menuObjid, companyCode }
+      );
+
       // 현재 메뉴와 모든 상위 메뉴의 objid 조회 (재귀)
       const ancestorMenuQuery = `
         WITH RECURSIVE menu_hierarchy AS (
@@ -1710,17 +1734,21 @@ export async function getCategoryColumnsByMenu(
           ARRAY_AGG(menu_name_kor) as menu_names
         FROM menu_hierarchy
       `;
-      
+
-      const ancestorMenuResult = await pool.query(ancestorMenuQuery, [parseInt(menuObjid)]);
+      const ancestorMenuResult = await pool.query(ancestorMenuQuery, [
-      const ancestorMenuObjids = ancestorMenuResult.rows[0]?.menu_objids || [parseInt(menuObjid)];
+        parseInt(menuObjid),
+      ]);
+      const ancestorMenuObjids = ancestorMenuResult.rows[0]?.menu_objids || [
+        parseInt(menuObjid),
+      ];
       const ancestorMenuNames = ancestorMenuResult.rows[0]?.menu_names || [];
-      
+
-      logger.info("✅ 상위 메뉴 계층 조회 완료", { 
+      logger.info("✅ 상위 메뉴 계층 조회 완료", {
-        ancestorMenuObjids, 
+        ancestorMenuObjids,
         ancestorMenuNames,
-        hierarchyDepth: ancestorMenuObjids.length 
+        hierarchyDepth: ancestorMenuObjids.length,
       });
-      
+
       // 상위 메뉴들에 설정된 모든 카테고리 컬럼 조회 (테이블 필터링 제거)
       const columnsQuery = `
         SELECT DISTINCT
@@ -1750,20 +1778,31 @@ export async function getCategoryColumnsByMenu(
           AND ttc.input_type = 'category'
         ORDER BY ttc.table_name, ccm.logical_column_name
       `;
-      
+
-      columnsResult = await pool.query(columnsQuery, [companyCode, ancestorMenuObjids]);
+      columnsResult = await pool.query(columnsQuery, [
-      logger.info("✅ category_column_mapping 기반 조회 완료 (계층 구조 상속)", { 
+        companyCode,
-        rowCount: columnsResult.rows.length,
+        ancestorMenuObjids,
-        columns: columnsResult.rows.map((r: any) => `${r.tableName}.${r.columnName}`)
+      ]);
-      });
+      logger.info(
+        "✅ category_column_mapping 기반 조회 완료 (계층 구조 상속)",
+        {
+          rowCount: columnsResult.rows.length,
+          columns: columnsResult.rows.map(
+            (r: any) => `${r.tableName}.${r.columnName}`
+          ),
+        }
+      );
     } else {
       // 🔄 레거시 방식: 형제 메뉴들의 테이블에서 모든 카테고리 컬럼 조회
-      logger.info("🔍 레거시 방식: 형제 메뉴 테이블 기반 카테고리 컬럼 조회", { menuObjid, companyCode });
+      logger.info("🔍 레거시 방식: 형제 메뉴 테이블 기반 카테고리 컬럼 조회", {
-      
+        menuObjid,
+        companyCode,
+      });
+
       // 형제 메뉴 조회
       const { getSiblingMenuObjids } = await import("../services/menuService");
       const siblingObjids = await getSiblingMenuObjids(parseInt(menuObjid));
-      
+
       // 형제 메뉴들이 사용하는 테이블 조회
       const tablesQuery = `
         SELECT DISTINCT sd.table_name
@@ -1773,11 +1812,17 @@ export async function getCategoryColumnsByMenu(
           AND sma.company_code = $2
           AND sd.table_name IS NOT NULL
       `;
-      
+
-      const tablesResult = await pool.query(tablesQuery, [siblingObjids, companyCode]);
+      const tablesResult = await pool.query(tablesQuery, [
+        siblingObjids,
+        companyCode,
+      ]);
       const tableNames = tablesResult.rows.map((row: any) => row.table_name);
-      
+
-      logger.info("✅ 형제 메뉴 테이블 조회 완료", { tableNames, count: tableNames.length });
+      logger.info("✅ 형제 메뉴 테이블 조회 완료", {
+        tableNames,
+        count: tableNames.length,
+      });
 
       if (tableNames.length === 0) {
         res.json({
@@ -1787,7 +1832,7 @@ export async function getCategoryColumnsByMenu(
         });
         return;
       }
-      
+
       const columnsQuery = `
         SELECT 
           ttc.table_name AS "tableName",
@@ -1812,13 +1857,15 @@ export async function getCategoryColumnsByMenu(
           AND ttc.input_type = 'category'
         ORDER BY ttc.table_name, ttc.column_name
       `;
-      
+
       columnsResult = await pool.query(columnsQuery, [tableNames, companyCode]);
-      logger.info("✅ 레거시 방식 조회 완료", { rowCount: columnsResult.rows.length });
+      logger.info("✅ 레거시 방식 조회 완료", {
+        rowCount: columnsResult.rows.length,
+      });
     }
-    
+
-    logger.info("✅ 카테고리 컬럼 조회 완료", { 
+    logger.info("✅ 카테고리 컬럼 조회 완료", {
-      columnCount: columnsResult.rows.length 
+      columnCount: columnsResult.rows.length,
     });
 
     res.json({
@@ -1843,9 +1890,9 @@ export async function getCategoryColumnsByMenu(
 
 /**
  * 범용 다중 테이블 저장 API
- * 
+ *
  * 메인 테이블과 서브 테이블(들)에 트랜잭션으로 데이터를 저장합니다.
- * 
+ *
  * 요청 본문:
  * {
  *   mainTable: { tableName: string, primaryKeyColumn: string },
@@ -1915,23 +1962,29 @@ export async function multiTableSave(
     }
 
     let mainResult: any;
-    
+
     if (isUpdate && pkValue) {
       // UPDATE
       const updateColumns = Object.keys(mainData)
-        .filter(col => col !== pkColumn)
+        .filter((col) => col !== pkColumn)
         .map((col, idx) => `"${col}" = $${idx + 1}`)
         .join(", ");
       const updateValues = Object.keys(mainData)
-        .filter(col => col !== pkColumn)
+        .filter((col) => col !== pkColumn)
-        .map(col => mainData[col]);
+        .map((col) => mainData[col]);
-      
+
       // updated_at 컬럼 존재 여부 확인
-      const hasUpdatedAt = await client.query(`
+      const hasUpdatedAt = await client.query(
+        `
         SELECT 1 FROM information_schema.columns 
         WHERE table_name = $1 AND column_name = 'updated_at'
-      `, [mainTableName]);
+      `,
-      const updatedAtClause = hasUpdatedAt.rowCount && hasUpdatedAt.rowCount > 0 ? ", updated_at = NOW()" : "";
+        [mainTableName]
+      );
+      const updatedAtClause =
+        hasUpdatedAt.rowCount && hasUpdatedAt.rowCount > 0
+          ? ", updated_at = NOW()"
+          : "";
 
       const updateQuery = `
         UPDATE "${mainTableName}"
@@ -1940,29 +1993,43 @@ export async function multiTableSave(
         ${companyCode !== "*" ? `AND company_code = $${updateValues.length + 2}` : ""}
         RETURNING *
       `;
-      
+
-      const updateParams = companyCode !== "*" 
+      const updateParams =
-        ? [...updateValues, pkValue, companyCode]
+        companyCode !== "*"
-        : [...updateValues, pkValue];
+          ? [...updateValues, pkValue, companyCode]
-      
+          : [...updateValues, pkValue];
-      logger.info("메인 테이블 UPDATE:", { query: updateQuery, paramsCount: updateParams.length });
+
+      logger.info("메인 테이블 UPDATE:", {
+        query: updateQuery,
+        paramsCount: updateParams.length,
+      });
       mainResult = await client.query(updateQuery, updateParams);
     } else {
       // INSERT
-      const columns = Object.keys(mainData).map(col => `"${col}"`).join(", ");
+      const columns = Object.keys(mainData)
-      const placeholders = Object.keys(mainData).map((_, idx) => `$${idx + 1}`).join(", ");
+        .map((col) => `"${col}"`)
+        .join(", ");
+      const placeholders = Object.keys(mainData)
+        .map((_, idx) => `$${idx + 1}`)
+        .join(", ");
       const values = Object.values(mainData);
 
       // updated_at 컬럼 존재 여부 확인
-      const hasUpdatedAt = await client.query(`
+      const hasUpdatedAt = await client.query(
+        `
         SELECT 1 FROM information_schema.columns 
         WHERE table_name = $1 AND column_name = 'updated_at'
-      `, [mainTableName]);
+      `,
-      const updatedAtClause = hasUpdatedAt.rowCount && hasUpdatedAt.rowCount > 0 ? ", updated_at = NOW()" : "";
+        [mainTableName]
+      );
+      const updatedAtClause =
+        hasUpdatedAt.rowCount && hasUpdatedAt.rowCount > 0
+          ? ", updated_at = NOW()"
+          : "";
 
       const updateSetClause = Object.keys(mainData)
-        .filter(col => col !== pkColumn)
+        .filter((col) => col !== pkColumn)
-        .map(col => `"${col}" = EXCLUDED."${col}"`)
+        .map((col) => `"${col}" = EXCLUDED."${col}"`)
         .join(", ");
 
       const insertQuery = `
@@ -1973,7 +2040,10 @@ export async function multiTableSave(
         RETURNING *
       `;
 
-      logger.info("메인 테이블 INSERT/UPSERT:", { query: insertQuery, paramsCount: values.length });
+      logger.info("메인 테이블 INSERT/UPSERT:", {
+        query: insertQuery,
+        paramsCount: values.length,
+      });
       mainResult = await client.query(insertQuery, values);
     }
 
@@ -1992,12 +2062,15 @@ export async function multiTableSave(
       const { tableName, linkColumn, items, options } = subTableConfig;
 
       // saveMainAsFirst가 활성화된 경우, items가 비어있어도 메인 데이터를 서브 테이블에 저장해야 함
-      const hasSaveMainAsFirst = options?.saveMainAsFirst && 
+      const hasSaveMainAsFirst =
-                                  options?.mainFieldMappings && 
+        options?.saveMainAsFirst &&
-                                  options.mainFieldMappings.length > 0;
+        options?.mainFieldMappings &&
-      
+        options.mainFieldMappings.length > 0;
+
       if (!tableName || (!items?.length && !hasSaveMainAsFirst)) {
-        logger.info(`서브 테이블 ${tableName} 스킵: 데이터 없음 (saveMainAsFirst: ${hasSaveMainAsFirst})`);
+        logger.info(
+          `서브 테이블 ${tableName} 스킵: 데이터 없음 (saveMainAsFirst: ${hasSaveMainAsFirst})`
+        );
         continue;
       }
 
@@ -2010,15 +2083,20 @@ export async function multiTableSave(
 
       // 기존 데이터 삭제 옵션
       if (options?.deleteExistingBefore && linkColumn?.subColumn) {
-        const deleteQuery = options?.deleteOnlySubItems && options?.mainMarkerColumn
+        const deleteQuery =
-          ? `DELETE FROM "${tableName}" WHERE "${linkColumn.subColumn}" = $1 AND "${options.mainMarkerColumn}" = $2`
+          options?.deleteOnlySubItems && options?.mainMarkerColumn
-          : `DELETE FROM "${tableName}" WHERE "${linkColumn.subColumn}" = $1`;
+            ? `DELETE FROM "${tableName}" WHERE "${linkColumn.subColumn}" = $1 AND "${options.mainMarkerColumn}" = $2`
-        
+            : `DELETE FROM "${tableName}" WHERE "${linkColumn.subColumn}" = $1`;
-        const deleteParams = options?.deleteOnlySubItems && options?.mainMarkerColumn
-          ? [savedPkValue, options.subMarkerValue ?? false]
-          : [savedPkValue];
 
-        logger.info(`서브 테이블 ${tableName} 기존 데이터 삭제:`, { deleteQuery, deleteParams });
+        const deleteParams =
+          options?.deleteOnlySubItems && options?.mainMarkerColumn
+            ? [savedPkValue, options.subMarkerValue ?? false]
+            : [savedPkValue];
+
+        logger.info(`서브 테이블 ${tableName} 기존 데이터 삭제:`, {
+          deleteQuery,
+          deleteParams,
+        });
         await client.query(deleteQuery, deleteParams);
       }
 
@@ -2031,7 +2109,12 @@ export async function multiTableSave(
         linkColumn,
         mainDataKeys: Object.keys(mainData),
       });
-      if (options?.saveMainAsFirst && options?.mainFieldMappings && options.mainFieldMappings.length > 0 && linkColumn?.subColumn) {
+      if (
+        options?.saveMainAsFirst &&
+        options?.mainFieldMappings &&
+        options.mainFieldMappings.length > 0 &&
+        linkColumn?.subColumn
+      ) {
         const mainSubItem: Record<string, any> = {
           [linkColumn.subColumn]: savedPkValue,
         };
@@ -2045,7 +2128,8 @@ export async function multiTableSave(
 
         // 메인 마커 설정
         if (options.mainMarkerColumn) {
-          mainSubItem[options.mainMarkerColumn] = options.mainMarkerValue ?? true;
+          mainSubItem[options.mainMarkerColumn] =
+            options.mainMarkerValue ?? true;
         }
 
         // company_code 추가
@@ -2068,20 +2152,30 @@ export async function multiTableSave(
         if (companyCode !== "*") {
           checkParams.push(companyCode);
         }
-        
+
         const existingResult = await client.query(checkQuery, checkParams);
-        
+
         if (existingResult.rows.length > 0) {
           // UPDATE
           const updateColumns = Object.keys(mainSubItem)
-            .filter(col => col !== linkColumn.subColumn && col !== options.mainMarkerColumn && col !== "company_code")
+            .filter(
+              (col) =>
+                col !== linkColumn.subColumn &&
+                col !== options.mainMarkerColumn &&
+                col !== "company_code"
+            )
             .map((col, idx) => `"${col}" = $${idx + 1}`)
             .join(", ");
-          
+
           const updateValues = Object.keys(mainSubItem)
-            .filter(col => col !== linkColumn.subColumn && col !== options.mainMarkerColumn && col !== "company_code")
+            .filter(
-            .map(col => mainSubItem[col]);
+              (col) =>
-          
+                col !== linkColumn.subColumn &&
+                col !== options.mainMarkerColumn &&
+                col !== "company_code"
+            )
+            .map((col) => mainSubItem[col]);
+
           if (updateColumns) {
             const updateQuery = `
               UPDATE "${tableName}"
@@ -2100,14 +2194,26 @@ export async function multiTableSave(
             }
 
             const updateResult = await client.query(updateQuery, updateParams);
-            subTableResults.push({ tableName, type: "main", data: updateResult.rows[0] });
+            subTableResults.push({
+              tableName,
+              type: "main",
+              data: updateResult.rows[0],
+            });
           } else {
-            subTableResults.push({ tableName, type: "main", data: existingResult.rows[0] });
+            subTableResults.push({
+              tableName,
+              type: "main",
+              data: existingResult.rows[0],
+            });
           }
         } else {
           // INSERT
-          const mainSubColumns = Object.keys(mainSubItem).map(col => `"${col}"`).join(", ");
+          const mainSubColumns = Object.keys(mainSubItem)
-          const mainSubPlaceholders = Object.keys(mainSubItem).map((_, idx) => `$${idx + 1}`).join(", ");
+            .map((col) => `"${col}"`)
+            .join(", ");
+          const mainSubPlaceholders = Object.keys(mainSubItem)
+            .map((_, idx) => `$${idx + 1}`)
+            .join(", ");
           const mainSubValues = Object.values(mainSubItem);
 
           const insertQuery = `
@@ -2117,7 +2223,11 @@ export async function multiTableSave(
           `;
 
           const insertResult = await client.query(insertQuery, mainSubValues);
-          subTableResults.push({ tableName, type: "main", data: insertResult.rows[0] });
+          subTableResults.push({
+            tableName,
+            type: "main",
+            data: insertResult.rows[0],
+          });
         }
       }
 
@@ -2133,8 +2243,12 @@ export async function multiTableSave(
           item.company_code = companyCode;
         }
 
-        const subColumns = Object.keys(item).map(col => `"${col}"`).join(", ");
+        const subColumns = Object.keys(item)
-        const subPlaceholders = Object.keys(item).map((_, idx) => `$${idx + 1}`).join(", ");
+          .map((col) => `"${col}"`)
+          .join(", ");
+        const subPlaceholders = Object.keys(item)
+          .map((_, idx) => `$${idx + 1}`)
+          .join(", ");
         const subValues = Object.values(item);
 
         const subInsertQuery = `
@@ -2143,9 +2257,16 @@ export async function multiTableSave(
           RETURNING *
         `;
 
-        logger.info(`서브 테이블 ${tableName} 아이템 저장:`, { subInsertQuery, subValuesCount: subValues.length });
+        logger.info(`서브 테이블 ${tableName} 아이템 저장:`, {
+          subInsertQuery,
+          subValuesCount: subValues.length,
+        });
         const subResult = await client.query(subInsertQuery, subValues);
-        subTableResults.push({ tableName, type: "sub", data: subResult.rows[0] });
+        subTableResults.push({
+          tableName,
+          type: "sub",
+          data: subResult.rows[0],
+        });
       }
 
       logger.info(`서브 테이블 ${tableName} 저장 완료`);
@@ -2188,7 +2309,7 @@ export async function multiTableSave(
 /**
  * 두 테이블 간의 엔티티 관계 자동 감지
  * GET /api/table-management/tables/entity-relations?leftTable=xxx&rightTable=yyy
- * 
+ *
  * column_labels에서 정의된 엔티티/카테고리 타입 설정을 기반으로
  * 두 테이블 간의 외래키 관계를 자동으로 감지합니다.
  */
@@ -2199,7 +2320,9 @@ export async function getTableEntityRelations(
   try {
     const { leftTable, rightTable } = req.query;
 
-    logger.info(`=== 테이블 엔티티 관계 조회 시작: ${leftTable} <-> ${rightTable} ===`);
+    logger.info(
+      `=== 테이블 엔티티 관계 조회 시작: ${leftTable} <-> ${rightTable} ===`
+    );
 
     if (!leftTable || !rightTable) {
       const response: ApiResponse<null> = {
@@ -2248,4 +2371,3 @@ export async function getTableEntityRelations(
     res.status(500).json(response);
   }
 }
-

backend-node/src/routes/screenGroupRoutes.ts

@@ -0,0 +1,94 @@
+import { Router } from "express";
+import { authenticateToken } from "../middleware/authMiddleware";
+import {
+  // 화면 그룹
+  getScreenGroups,
+  getScreenGroup,
+  createScreenGroup,
+  updateScreenGroup,
+  deleteScreenGroup,
+  // 화면-그룹 연결
+  addScreenToGroup,
+  removeScreenFromGroup,
+  updateScreenInGroup,
+  // 필드 조인
+  getFieldJoins,
+  createFieldJoin,
+  updateFieldJoin,
+  deleteFieldJoin,
+  // 데이터 흐름
+  getDataFlows,
+  createDataFlow,
+  updateDataFlow,
+  deleteDataFlow,
+  // 화면-테이블 관계
+  getTableRelations,
+  createTableRelation,
+  updateTableRelation,
+  deleteTableRelation,
+  // 화면 레이아웃 요약
+  getScreenLayoutSummary,
+  getMultipleScreenLayoutSummary,
+  // 화면 서브 테이블 관계
+  getScreenSubTables,
+} from "../controllers/screenGroupController";
+
+const router = Router();
+
+// 모든 라우트에 인증 미들웨어 적용
+router.use(authenticateToken);
+
+// ============================================================
+// 화면 그룹 (screen_groups)
+// ============================================================
+router.get("/groups", getScreenGroups);
+router.get("/groups/:id", getScreenGroup);
+router.post("/groups", createScreenGroup);
+router.put("/groups/:id", updateScreenGroup);
+router.delete("/groups/:id", deleteScreenGroup);
+
+// ============================================================
+// 화면-그룹 연결 (screen_group_screens)
+// ============================================================
+router.post("/group-screens", addScreenToGroup);
+router.put("/group-screens/:id", updateScreenInGroup);
+router.delete("/group-screens/:id", removeScreenFromGroup);
+
+// ============================================================
+// 필드 조인 설정 (screen_field_joins)
+// ============================================================
+router.get("/field-joins", getFieldJoins);
+router.post("/field-joins", createFieldJoin);
+router.put("/field-joins/:id", updateFieldJoin);
+router.delete("/field-joins/:id", deleteFieldJoin);
+
+// ============================================================
+// 데이터 흐름 (screen_data_flows)
+// ============================================================
+router.get("/data-flows", getDataFlows);
+router.post("/data-flows", createDataFlow);
+router.put("/data-flows/:id", updateDataFlow);
+router.delete("/data-flows/:id", deleteDataFlow);
+
+// ============================================================
+// 화면-테이블 관계 (screen_table_relations)
+// ============================================================
+router.get("/table-relations", getTableRelations);
+router.post("/table-relations", createTableRelation);
+router.put("/table-relations/:id", updateTableRelation);
+router.delete("/table-relations/:id", deleteTableRelation);
+
+// ============================================================
+// 화면 레이아웃 요약 (미리보기용)
+// ============================================================
+router.get("/layout-summary/:screenId", getScreenLayoutSummary);
+router.post("/layout-summary/batch", getMultipleScreenLayoutSummary);
+
+// ============================================================
+// 화면 서브 테이블 관계 (조인/참조 테이블)
+// ============================================================
+router.post("/sub-tables/batch", getScreenSubTables);
+
+export default router;
+
+

docs/화면설정모달_개선_완료_보고서.md

@@ -0,0 +1,535 @@
+# 화면 설정 모달 개선 완료 보고서
+
+## 개요
+화면 관리에서 화면 노드 우클릭 시 열리는 설정 모달을 대폭 개선하여, 테이블 정보 시각화, 필드 매핑 확인, 컬럼 변경/추가/제거 기능, 조인 설정 기능, 실시간 프리뷰 기능을 강화했습니다.
+
+## 주요 개선 사항
+
+### 1. 화면 개요 탭 통합 개선
+
+#### 1.1 필드 매핑 탭 → 개요 탭 통합
+- 기존 "필드 매핑" 탭 제거
+- 필드 매핑 정보를 개요 탭의 메인/필터 테이블 아코디언에 통합 표시
+- 더 직관적이고 간결한 UI 제공
+
+#### 1.2 메인 테이블 아코디언
+- 메인 테이블(예: `customer_mng`)을 아코디언 형식으로 표시
+- 클릭 시 테이블의 모든 컬럼 정보 표시
+- **1열 레이아웃**: 컬럼 정보를 세로로 배치
+- 화면에서 사용 중인 컬럼은 **파란색 배경 + "필드" 배지**로 강조
+- **컬럼 정렬**: 
+  - 사용중인 필드가 상단에 표시
+  - 화면에 표시되는 순서대로 정렬 (y좌표 기준)
+  - 미사용 컬럼은 하단에 표시
+
+#### 1.3 필터 테이블 아코디언
+- 필터 테이블(예: `customer_item_mapping`)을 아코디언 형식으로 표시
+- 클릭 시 테이블의 모든 컬럼 정보 표시
+- 컬럼별 색상 구분:
+  - **파란색**: 화면에서 사용 중인 컬럼 (필드)
+  - **보라색**: 필터 키 컬럼 (WHERE 절에 사용)
+  - **주황색**: 조인 키 컬럼 (JOIN 조건에 사용)
+- **다중 배지 표시**: 컬럼이 필드이면서 조인/필터 키인 경우 배지 동시 표시
+- 필터 연결 정보 표시 (예: `→ customer_mng`)
+
+#### 1.4 컬럼 레이아웃 순서
+- **순서**: `컬럼명 | 배지 | 데이터타입`
+- 예: `거래처 코드` `[필드]` `character varying`
+- 데이터타입은 오른쪽 정렬
+
+#### 1.5 클릭 스타일 개선
+- **테두리 제거**: ring-2, ring-offset 등 제거
+- **강조 색상 연하게**: 
+  - 선택됨: `bg-blue-100 border-blue-300`
+  - 미선택: `bg-blue-50 border-blue-200`
+- 더 부드러운 시각적 피드백
+
+#### 1.6 패널 높이 동기화
+- 왼쪽(컬럼 목록)과 오른쪽(설정 패널) 동일한 `max-h-[350px]` 적용
+- `overflow-y-auto`로 스크롤 처리
+- `items-stretch`로 양쪽 패널 높이 동기화
+
+### 2. 컬럼 변경 기능
+
+#### 2.1 인라인 컬럼 편집
+- 사용중인 필드(파란색 배경)를 클릭하면 우측에 "컬럼 설정" 패널 표시
+- 패널 정보:
+  - **화면 필드**: 컬럼 한글명 표시 (예: "거래처 코드")
+  - **현재 컬럼**: 영문 컬럼명 표시 (예: `customer_code`)
+  - **컬럼 변경**: 드롭다운으로 다른 컬럼 선택
+- 검색 기능으로 컬럼 빠르게 찾기
+
+#### 2.2 실시간 반영
+- 컬럼 변경 후 **페이지 새로고침 없이** 실시간 반영
+- `onRefresh` 콜백으로 데이터 리로드 + iframe 새로고침
+- 더 빠른 사용자 경험
+
+#### 2.3 변경사항 저장
+- `screenApi.saveLayout()` 사용하여 **화면 디자이너와 동일한 테이블에 저장**
+- 저장 위치:
+  - `componentConfig.leftPanel.columns` (분할 패널)
+  - `componentConfig.rightPanel.columns` (분할 패널)
+  - `usedColumns` 배열
+  - `bindField` 필드
+  - `fieldMapping` 배열
+
+### 3. 필드 추가/제거 기능 (신규)
+
+#### 3.1 필드 추가
+- 비필드 컬럼(회색/흰색 배경) 클릭
+- "컬럼 설정" 패널에 컬럼 정보 표시
+- **"필드로 추가"** 버튼 클릭 → 해당 컬럼이 화면 필드로 추가됨
+- 버튼 스타일: `text-blue-600 border-blue-300 hover:bg-blue-50` (파란색 테두리)
+
+#### 3.2 필드 제거
+- 기존 필드(파란색 배경) 클릭
+- "컬럼 설정" 패널에 필드 정보 표시
+- **"필드에서 제거"** 버튼 클릭 → 해당 필드가 화면에서 제거됨
+- 버튼 스타일: `text-red-600 border-red-300 hover:bg-red-50` (빨간색 테두리)
+
+#### 3.3 저장 로직
+```typescript
+// 필드 추가: 배열에 새 컬럼 추가
+if (isAddingField) {
+  return {
+    ...comp,
+    componentConfig: {
+      ...comp.componentConfig,
+      leftPanel: {
+        ...comp.componentConfig.leftPanel,
+        columns: [...leftColumns, { name: newColumn, columnName: newColumn }],
+      },
+    },
+  };
+}
+
+// 필드 제거: 배열에서 해당 컬럼 제거
+if (isRemovingField) {
+  const filteredColumns = leftColumns.filter((_, i) => i !== columnIdx);
+  return {
+    ...comp,
+    componentConfig: {
+      ...comp.componentConfig,
+      leftPanel: {
+        ...comp.componentConfig.leftPanel,
+        columns: filteredColumns,
+      },
+    },
+  };
+}
+```
+
+#### 3.4 적용 범위
+- 메인 테이블 아코디언: 필드 추가/제거 가능
+- 필터 테이블 아코디언: 필드 추가/제거 가능
+- `usedColumns`, `componentConfig.usedColumns`, `componentConfig.columns`, `leftPanel.columns`, `rightPanel.columns` 모두 지원
+
+### 4. 화면 프리뷰 상시 표시
+
+#### 4.1 레이아웃 변경
+- 기존: 탭으로 프리뷰 전환
+- 개선: **모달 우측에 프리뷰 상시 표시**
+- 모달 크기 확대 (1600px 최대 너비)
+- 좌측 40% (탭 콘텐츠) / 우측 60% (프리뷰)
+
+#### 4.2 줌/드래그/클릭 기능 (react-zoom-pan-pinch 라이브러리)
+- **휠 스크롤**: 마우스 포인터 위치 기준 확대/축소 (20% ~ 300%)
+- **드래그**: 마우스 왼쪽 버튼으로 화면 이동 (5px 이상 이동 시)
+- **클릭**: iframe 내부 요소 정상 클릭 가능
+  - 버튼, 셀렉트박스, 체크박스, 테이블 행 클릭
+  - 인풋박스/텍스트박스 포커스 및 입력
+  - X버튼(닫기) 등 SVG 아이콘 버튼 클릭
+
+#### 4.3 클릭 좌표 보정 시스템
+- 줌 상태에서도 정확한 클릭 위치 계산
+- `designWidth / rect.width` 비율로 좌표 변환
+- 오버레이 방식으로 드래그와 클릭 분리 처리
+
+### 5. 필드+조인 컬럼 스타일 개선
+
+#### 5.1 다중 역할 컬럼 표시
+- 컬럼이 **필드이면서 조인 키**인 경우:
+  - **파란색 배경** (필드 기준)
+  - **왼쪽에 주황색 세로 선** (`border-l-4 border-l-orange-500`)
+  - 배지: `조인` `필드` 동시 표시
+- 컬럼이 **필드이면서 필터 키**인 경우:
+  - **파란색 배경** (필드 기준)
+  - **왼쪽에 보라색 세로 선** (`border-l-4 border-l-purple-400`)
+  - 배지: `필터` `필드` 동시 표시
+
+#### 5.2 조인 컬럼도 필드로 인식
+- `filterTableColumnMappings` 생성 시 조인 컬럼(`ft.joinColumnRefs`)도 포함
+- 조인 테이블 데이터를 화면에서 보여주므로 필드로 간주
+
+#### 5.3 컬럼 설정 패널 - 조인 정보 표시
+- 조인 키 클릭 시 패널에 조인 정보 표시:
+  - **대상 테이블**: item_info (실제 참조 테이블)
+  - **연결 컬럼**: item_number (참조 컬럼)
+
+### 6. 조인 관계 설정/수정 기능
+
+#### 6.1 기능 설명
+- 컬럼 설정 패널에서 **조인 관계 직접 수정** 가능
+- **모든 컬럼에서 조인 설정 가능** (기존 조인 키가 아닌 컬럼도 포함)
+- 테이블 타입 관리(`column_labels` 테이블)와 동일한 저장 위치 사용
+
+#### 6.2 저장 테이블
+```
+column_labels 테이블:
+├── reference_table   (참조 테이블명)
+├── reference_column  (참조 컬럼 - 보통 PK)
+└── display_column    (화면에 표시할 컬럼)
+```
+
+#### 6.3 구현된 UI
+1. **컬럼 클릭** → 컬럼 설정 패널 표시
+2. **"조인" 섹션 확인**:
+   - 조인 설정 있음: "편집" 버튼
+   - 조인 설정 없음: "추가" 버튼
+3. **드롭다운으로 설정** (모두 검색 가능):
+   - 대상 테이블: 전체 테이블 목록에서 검색/선택
+   - 연결 컬럼 (PK): 선택한 테이블의 컬럼 중 검색/선택
+   - 표시 컬럼: 화면에 표시할 컬럼 검색/선택
+4. **저장 버튼** → `column_labels` 테이블에 저장
+5. **취소 버튼** → 편집 취소
+
+#### 6.4 검색 가능한 드롭다운
+- Popover + Command 컴포넌트 사용
+- 실시간 텍스트 검색 지원
+- 대상 테이블, 연결 컬럼, 표시 컬럼 모두 검색 가능
+
+#### 6.5 API 연동
+- **테이블 목록 조회**: `tableManagementApi.getTableList()`
+- **컬럼 목록 조회**: `tableManagementApi.getColumnList(tableName)`
+- **저장**: `tableManagementApi.updateColumnSettings(tableName, columnName, settings)`
+
+#### 6.6 메인 테이블에도 조인 설정 적용
+- 메인 테이블 아코디언에서도 조인 설정 가능
+- 필터 테이블과 동일한 UI/기능 제공
+
+#### 6.7 조인 데이터 소스 수정
+- 기존 조인 키 클릭 시 `joinRef.refTable` 값을 사용
+- 예: `품목 ID` → `item_info` (실제 참조 테이블)
+- `mainTable` 대신 `joinRef.refTable` 사용으로 정확한 테이블 표시
+
+### 7. 배지 순서 및 스타일
+- **배지 순서**: `필터` → `조인` → `필드` (필드가 맨 뒤)
+- **조인 배지**: 주황색 배경 (`bg-orange-200 text-orange-700`)
+- **필터 배지**: 보라색 배경 (`bg-purple-200 text-purple-700`)
+- **필드 배지**: 파란색 배경 (`bg-blue-500 text-white`)
+
+### 8. 컴포넌트 통합 리팩토링
+
+#### 8.1 `TableColumnAccordion` 통합 컴포넌트
+- 기존 `MainTableAccordion`과 `FilterTableAccordion`을 하나의 컴포넌트로 통합
+- `tableType` prop으로 "main" 또는 "filter" 구분
+- 코드 중복 제거 및 유지보수성 향상
+
+#### 8.2 Props 구조
+```typescript
+interface TableColumnAccordionProps {
+  tableName: string;
+  tableLabel?: string;
+  tableType: "main" | "filter";
+  columnMappings?: ColumnMapping[];
+  onColumnChange?: (fieldLabel: string, oldColumn: string, newColumn: string) => void;
+  onColumnReorder?: (newOrder: string[]) => void;
+  onJoinSettingSaved?: () => void;
+  // 필터 테이블 전용 props
+  mainTable?: string;
+  filterKeyMapping?: FilterKeyMapping;
+  joinColumnRefs?: JoinColumnRef[];
+}
+```
+
+#### 8.3 동적 테마 적용
+- 메인 테이블: 파란색 테마 (`blue`)
+- 필터 테이블: 보라색 테마 (`purple`)
+- `themeColor`, `themeIcon`, `themeBadge` 변수로 동적 스타일 적용
+
+### 9. 드래그 앤 드롭 컬럼 순서 변경
+
+#### 9.1 기능 설명
+- 사용 중인 컬럼(필드)을 드래그하여 순서 변경 가능
+- 드래그 중에는 시각적으로만 순서 변경, **드롭 시에만 저장**
+- 드래그 취소(영역 밖으로 나간 경우) 시 원래 순서로 복원
+
+#### 9.2 드래그 상태 관리
+```typescript
+// 드래그 상태
+const [draggedIndex, setDraggedIndex] = useState<number | null>(null);
+const [localColumnOrder, setLocalColumnOrder] = useState<string[] | null>(null);
+```
+
+#### 9.3 드래그 핸들러
+```typescript
+// 드래그 시작: 현재 순서를 로컬 상태로 저장
+const handleDragStart = (e: React.DragEvent, index: number) => {
+  setDraggedIndex(index);
+  const usedColumns = sortedColumns.filter(col => columnMappingMap.has(col.columnName.toLowerCase()));
+  setLocalColumnOrder(usedColumns.map(col => col.columnName));
+};
+
+// 드래그 중: 로컬 순서만 변경 (저장하지 않음)
+const handleDragOver = (e: React.DragEvent, hoverIndex: number) => {
+  if (draggedIndex === null || draggedIndex === hoverIndex || !localColumnOrder) return;
+  const newOrder = [...localColumnOrder];
+  const draggedItem = newOrder[draggedIndex];
+  newOrder.splice(draggedIndex, 1);
+  newOrder.splice(hoverIndex, 0, draggedItem);
+  setDraggedIndex(hoverIndex);
+  setLocalColumnOrder(newOrder);
+};
+
+// 드롭: 최종 순서로 저장
+const handleDrop = (e: React.DragEvent) => {
+  if (localColumnOrder && onColumnReorder) {
+    onColumnReorder(localColumnOrder);
+  }
+  setDraggedIndex(null);
+  setLocalColumnOrder(null);
+};
+
+// 드래그 취소
+const handleDragEnd = () => {
+  setDraggedIndex(null);
+  setLocalColumnOrder(null);
+};
+```
+
+#### 9.4 시각적 피드백
+- 드래그 가능한 컬럼: `cursor-grab active:cursor-grabbing`
+- 드래그 중인 컬럼: `opacity-50 scale-95`
+- 드래그 중 실시간 순서 변경 표시
+
+#### 9.5 저장 로직 (`handleColumnReorder`)
+```typescript
+const handleColumnReorder = async (tableType: "main" | "filter", newOrder: string[]) => {
+  const currentLayout = await screenApi.getLayout(screenId);
+  
+  const updatedComponents = currentLayout.components.map((comp: any) => {
+    // leftPanel.columns 순서 변경
+    if (comp.componentConfig?.leftPanel?.columns) {
+      const leftColumns = comp.componentConfig.leftPanel.columns;
+      const reorderedColumns = newOrder.map(colName => 
+        leftColumns.find((col: any) => col.name?.toLowerCase() === colName.toLowerCase())
+      ).filter(Boolean);
+      const remainingColumns = leftColumns.filter((col: any) => 
+        !newOrder.some(n => n.toLowerCase() === col.name?.toLowerCase())
+      );
+      
+      return {
+        ...comp,
+        componentConfig: {
+          ...comp.componentConfig,
+          leftPanel: {
+            ...comp.componentConfig.leftPanel,
+            columns: [...reorderedColumns, ...remainingColumns],
+          },
+        },
+      };
+    }
+    return comp;
+  });
+
+  await screenApi.saveLayout(screenId, { ...currentLayout, components: updatedComponents });
+  onRefresh?.();
+};
+```
+
+#### 9.6 지원 범위
+- 메인 테이블: `onColumnReorder={(newOrder) => handleColumnReorder("main", newOrder)}`
+- 필터 테이블: `onColumnReorder={(newOrder) => handleColumnReorder("filter", newOrder)}`
+- 지원 배열:
+  - `componentConfig.leftPanel.columns`
+  - `componentConfig.rightPanel.columns`
+  - `componentConfig.usedColumns`
+  - `componentConfig.columns`
+
+## 기술 스택
+
+### 신규 의존성
+```bash
+npm install react-zoom-pan-pinch
+```
+
+### 사용된 컴포넌트
+- `TransformWrapper`, `TransformComponent` - 줌/드래그 기능
+- `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger` - 아코디언 UI
+- `Popover`, `PopoverTrigger`, `PopoverContent` - 드롭다운 컨테이너
+- `Command`, `CommandInput`, `CommandList`, `CommandItem`, `CommandEmpty` - 검색 가능한 선택 UI
+- `tableManagementApi.getColumnList()` - 테이블 컬럼 정보 조회
+- `tableManagementApi.getTableList()` - 테이블 목록 조회
+- `tableManagementApi.updateColumnSettings()` - 조인 설정 저장
+- `screenApi.saveLayout()` - 레이아웃 저장
+- `screenApi.getLayout()` - 레이아웃 조회
+
+### 핵심 로직
+
+#### 컬럼 변경/추가/제거
+```typescript
+const handleColumnChange = async (fieldLabel: string, oldColumn: string, newColumn: string) => {
+  const isAddingField = fieldLabel === "__NEW_FIELD__";
+  const isRemovingField = newColumn === "__REMOVE_FIELD__";
+  
+  const currentLayout = await screenApi.getLayout(screenId);
+  
+  const updatedComponents = currentLayout.components.map((comp: any) => {
+    if (comp.componentConfig?.leftPanel?.columns) {
+      const leftColumns = comp.componentConfig.leftPanel.columns;
+      
+      // 필드 추가
+      if (isAddingField) {
+        return {
+          ...comp,
+          componentConfig: {
+            ...comp.componentConfig,
+            leftPanel: {
+              ...comp.componentConfig.leftPanel,
+              columns: [...leftColumns, { name: newColumn, columnName: newColumn }],
+            },
+          },
+        };
+      }
+      
+      // 필드 제거
+      const columnIdx = leftColumns.findIndex((col: any) => ...);
+      if (columnIdx !== -1 && isRemovingField) {
+        return {
+          ...comp,
+          componentConfig: {
+            ...comp.componentConfig,
+            leftPanel: {
+              ...comp.componentConfig.leftPanel,
+              columns: leftColumns.filter((_, i) => i !== columnIdx),
+            },
+          },
+        };
+      }
+      
+      // 컬럼 변경
+      if (columnIdx !== -1) {
+        return {
+          ...comp,
+          componentConfig: {
+            ...comp.componentConfig,
+            leftPanel: {
+              ...comp.componentConfig.leftPanel,
+              columns: leftColumns.map((col, i) => 
+                i === columnIdx ? { ...col, name: newColumn } : col
+              ),
+            },
+          },
+        };
+      }
+    }
+    return comp;
+  });
+
+  await screenApi.saveLayout(screenId, { ...currentLayout, components: updatedComponents });
+  onRefresh?.();
+};
+```
+
+#### 조인 설정 편집기 (JoinSettingEditor)
+```tsx
+<JoinSettingEditor
+  editingJoin={editingJoin}
+  setEditingJoin={setEditingJoin}
+  allTables={allTables}
+  refTableColumns={refTableColumns}
+  loadingRefColumns={loadingRefColumns}
+  savingJoinSetting={savingJoinSetting}
+  loadRefTableColumns={loadRefTableColumns}
+  handleSaveJoinSetting={handleSaveJoinSetting}
+/>
+```
+
+## 파일 변경 목록
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `frontend/components/screen/ScreenSettingModal.tsx` | 전체 UI 개선, 줌/드래그 기능, 컬럼 변경/추가/제거 기능, 조인 설정 기능, 필드 매핑 통합, 실시간 반영 |
+| `frontend/components/screen/ScreenRelationFlow.tsx` | `filterKeyMapping`, `joinColumnRefs` 데이터 전달 |
+| `frontend/lib/api/entityJoin.ts` | `companyCodeOverride` 파라미터 추가 |
+| `frontend/lib/api/screen.ts` | `saveLayout`, `getLayout` API 사용 |
+| `frontend/lib/api/tableManagement.ts` | `getTableList`, `getColumnList`, `updateColumnSettings` API |
+| `frontend/lib/registry/components/split-panel-layout/SplitPanelLayoutComponent.tsx` | `companyCode` prop 추가 |
+| `backend-node/src/controllers/entityJoinController.ts` | `companyCodeOverride` 처리 로직 추가 |
+
+## 사용 방법
+
+### 화면 설정 모달 열기
+1. 화면 관리 페이지에서 화면 그룹 선택
+2. 화면 노드 우클릭 → 컨텍스트 메뉴 표시
+3. "화면 설정" 선택 → 모달 열림
+4. 좌측 탭에서 정보 확인/수정, 우측에서 실시간 프리뷰
+
+### 프리뷰 영역 조작
+- **휠 스크롤**: 확대/축소 (5% 단위)
+- **마우스 드래그**: 화면 이동 (5px 이상 움직여야 드래그로 인식)
+- **짧은 클릭**: iframe 내부 요소 클릭
+
+### 컬럼 변경
+1. 메인/필터 테이블 아코디언 펼치기
+2. 파란색 배경의 "필드" 컬럼 클릭
+3. 우측 "컬럼 설정" 패널 확인
+4. "컬럼 변경" 드롭다운에서 새 컬럼 선택
+5. **실시간 반영** (페이지 새로고침 없음)
+
+### 필드 추가
+1. 메인/필터 테이블 아코디언 펼치기
+2. 회색/흰색 배경의 비필드 컬럼 클릭
+3. 우측 패널에서 **"필드로 추가"** 버튼 클릭
+4. 해당 컬럼이 화면 필드로 추가됨
+
+### 필드 제거
+1. 메인/필터 테이블 아코디언 펼치기
+2. 파란색 배경의 필드 컬럼 클릭
+3. 우측 패널에서 **"필드에서 제거"** 버튼 클릭
+4. 해당 필드가 화면에서 제거됨
+
+### 조인 설정 추가/편집
+1. 메인/필터 테이블 아코디언 펼치기
+2. 아무 컬럼 클릭 (조인 키가 아니어도 됨)
+3. 우측 패널의 "조인" 섹션에서:
+   - 조인 없음: **"추가"** 버튼 클릭
+   - 조인 있음: **"편집"** 버튼 클릭
+4. 대상 테이블 선택 (검색 가능)
+5. 연결 컬럼 (PK) 선택 (검색 가능)
+6. 표시 컬럼 선택 (검색 가능)
+7. **"저장"** 버튼 클릭
+
+### 컬럼 순서 변경 (드래그 앤 드롭)
+1. 메인/필터 테이블 아코디언 펼치기
+2. 파란색 배경의 "필드" 컬럼을 드래그 시작
+3. 원하는 위치로 드래그하여 이동 (실시간으로 순서 변경 표시)
+4. 마우스를 놓으면 (드롭) 순서가 저장됨
+5. 드래그 취소하려면 컬럼 영역 밖으로 드래그
+
+**참고:**
+- 사용 중인 필드만 드래그 가능 (파란색 배경)
+- 미사용 컬럼은 드래그 불가
+- 드래그 중에는 저장되지 않고, 드롭 시에만 저장됨
+
+---
+
+## 완료일
+2026-01-13
+
+## 변경 이력
+- 2026-01-12: 최초 작성 (줌/드래그/클릭, company_code 전달)
+- 2026-01-12: 컬럼 변경 기능 추가, 필드 매핑 통합, UI 개선 (1열 레이아웃, 배지 변경)
+- 2026-01-12: 실시간 반영 구현 (reload 제거), 레이아웃 순서 변경, 스타일 개선
+- 2026-01-12: 필드+조인 컬럼 스타일 개선 (파란배경 + 왼쪽 주황선), 조인 정보 패널 표시
+- 2026-01-12: 조인 관계 설정/수정 기능 구현 완료 (column_labels 테이블 저장)
+- 2026-01-13: 필드 추가/제거 기능 구현
+- 2026-01-13: 검색 가능한 조인 설정 드롭다운 (Command 컴포넌트)
+- 2026-01-13: 모든 컬럼에서 조인 설정 가능 (범용성 패치)
+- 2026-01-13: 메인 테이블에도 조인 설정 기능 추가
+- 2026-01-13: 조인 라인 색상 주황색으로 변경 (`border-l-orange-500`)
+- 2026-01-13: 조인 데이터 소스 수정 (`joinRef.refTable` 사용)
+- 2026-01-13: 패널 높이 동기화 (`max-h-[350px]`, `items-stretch`)
+- 2026-01-13: `MainTableAccordion`과 `FilterTableAccordion`을 `TableColumnAccordion`으로 통합
+- 2026-01-13: 드래그 앤 드롭 컬럼 순서 변경 기능 구현
+- 2026-01-13: 드래그 중에는 로컬 상태만 변경, 드롭 시에만 저장하도록 최적화

frontend/app/(main)/admin/screenMng/screenMngList/page.tsx

@@ -1,68 +1,93 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useEffect, useCallback } from "react";
 import { Button } from "@/components/ui/button";
-import { ArrowLeft } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { ArrowLeft, Plus, RefreshCw, Search, LayoutGrid, LayoutList } from "lucide-react";
 import ScreenList from "@/components/screen/ScreenList";
 import ScreenDesigner from "@/components/screen/ScreenDesigner";
 import TemplateManager from "@/components/screen/TemplateManager";
+import { ScreenGroupTreeView } from "@/components/screen/ScreenGroupTreeView";
+import { ScreenRelationFlow } from "@/components/screen/ScreenRelationFlow";
 import { ScrollToTop } from "@/components/common/ScrollToTop";
 import { ScreenDefinition } from "@/types/screen";
+import { screenApi } from "@/lib/api/screen";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import CreateScreenModal from "@/components/screen/CreateScreenModal";
 
 // 단계별 진행을 위한 타입 정의
 type Step = "list" | "design" | "template";
+type ViewMode = "tree" | "table";
 
 export default function ScreenManagementPage() {
   const [currentStep, setCurrentStep] = useState<Step>("list");
   const [selectedScreen, setSelectedScreen] = useState<ScreenDefinition | null>(null);
+  const [selectedGroup, setSelectedGroup] = useState<{ id: number; name: string; company_code?: string } | null>(null);
+  const [focusedScreenIdInGroup, setFocusedScreenIdInGroup] = useState<number | null>(null);
   const [stepHistory, setStepHistory] = useState<Step[]>(["list"]);
+  const [viewMode, setViewMode] = useState<ViewMode>("tree");
+  const [screens, setScreens] = useState<ScreenDefinition[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [searchTerm, setSearchTerm] = useState("");
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+
+  // 화면 목록 로드
+  const loadScreens = useCallback(async () => {
+    try {
+      setLoading(true);
+      const result = await screenApi.getScreens({ page: 1, size: 1000, searchTerm: "" });
+      // screenApi.getScreens는 { data: ScreenDefinition[], total, page, size, totalPages } 형태 반환
+      if (result.data && result.data.length > 0) {
+        setScreens(result.data);
+      }
+    } catch (error) {
+      console.error("화면 목록 로드 실패:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    loadScreens();
+  }, [loadScreens]);
 
   // 화면 설계 모드일 때는 전체 화면 사용
   const isDesignMode = currentStep === "design";
 
-  // 단계별 제목과 설명
-  const stepConfig = {
-    list: {
-      title: "화면 목록 관리",
-      description: "생성된 화면들을 확인하고 관리하세요",
-    },
-    design: {
-      title: "화면 설계",
-      description: "드래그앤드롭으로 화면을 설계하세요",
-    },
-    template: {
-      title: "템플릿 관리",
-      description: "화면 템플릿을 관리하고 재사용하세요",
-    },
-  };
-
   // 다음 단계로 이동
   const goToNextStep = (nextStep: Step) => {
     setStepHistory((prev) => [...prev, nextStep]);
     setCurrentStep(nextStep);
   };
 
-  // 이전 단계로 이동
-  const goToPreviousStep = () => {
-    if (stepHistory.length > 1) {
-      const newHistory = stepHistory.slice(0, -1);
-      const previousStep = newHistory[newHistory.length - 1];
-      setStepHistory(newHistory);
-      setCurrentStep(previousStep);
-    }
-  };
-
   // 특정 단계로 이동
   const goToStep = (step: Step) => {
     setCurrentStep(step);
-    // 해당 단계까지의 히스토리만 유지
     const stepIndex = stepHistory.findIndex((s) => s === step);
     if (stepIndex !== -1) {
       setStepHistory(stepHistory.slice(0, stepIndex + 1));
     }
   };
 
-  // 화면 설계 모드일 때는 레이아웃 없이 전체 화면 사용 (고정 높이)
+  // 화면 선택 핸들러 (개별 화면 선택 시 그룹 선택 해제)
+  const handleScreenSelect = (screen: ScreenDefinition) => {
+    setSelectedScreen(screen);
+    setSelectedGroup(null); // 그룹 선택 해제
+  };
+
+  // 화면 디자인 핸들러
+  const handleDesignScreen = (screen: ScreenDefinition) => {
+    setSelectedScreen(screen);
+    goToNextStep("design");
+  };
+
+  // 검색어로 필터링된 화면
+  const filteredScreens = screens.filter((screen) =>
+    screen.screenName.toLowerCase().includes(searchTerm.toLowerCase()) ||
+    screen.screenCode.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  // 화면 설계 모드일 때는 레이아웃 없이 전체 화면 사용
   if (isDesignMode) {
     return (
       <div className="fixed inset-0 z-50 bg-background">
@@ -72,56 +97,116 @@ export default function ScreenManagementPage() {
   }
 
   return (
-    <div className="flex min-h-screen flex-col bg-background">
+    <div className="flex h-screen flex-col bg-background overflow-hidden">
-      <div className="space-y-6 p-6">
+      {/* 페이지 헤더 */}
-        {/* 페이지 헤더 */}
+      <div className="flex-shrink-0 border-b bg-background px-6 py-4">
-        <div className="space-y-2 border-b pb-4">
+        <div className="flex items-center justify-between">
-          <h1 className="text-3xl font-bold tracking-tight">화면 관리</h1>
+          <div>
-          <p className="text-sm text-muted-foreground">화면을 설계하고 템플릿을 관리합니다</p>
+            <h1 className="text-2xl font-bold tracking-tight">화면 관리</h1>
-        </div>
+            <p className="text-sm text-muted-foreground">화면을 그룹별로 관리하고 데이터 관계를 확인합니다</p>
-
+          </div>
-        {/* 단계별 내용 */}
+          <div className="flex items-center gap-2">
-        <div className="flex-1">
+            {/* 뷰 모드 전환 */}
-          {/* 화면 목록 단계 */}
+            <Tabs value={viewMode} onValueChange={(v) => setViewMode(v as ViewMode)}>
-          {currentStep === "list" && (
+              <TabsList className="h-9">
-            <ScreenList
+                <TabsTrigger value="tree" className="gap-1.5 px-3">
-              onScreenSelect={setSelectedScreen}
+                  <LayoutGrid className="h-4 w-4" />
-              selectedScreen={selectedScreen}
+                  트리
-              onDesignScreen={(screen) => {
+                </TabsTrigger>
-                setSelectedScreen(screen);
+                <TabsTrigger value="table" className="gap-1.5 px-3">
-                goToNextStep("design");
+                  <LayoutList className="h-4 w-4" />
-              }}
+                  테이블
-            />
+                </TabsTrigger>
-          )}
+              </TabsList>
-
+            </Tabs>
-          {/* 템플릿 관리 단계 */}
+            <Button variant="outline" size="icon" onClick={loadScreens}>
-          {currentStep === "template" && (
+              <RefreshCw className="h-4 w-4" />
-            <div className="space-y-6">
+            </Button>
-              <div className="flex items-center justify-between rounded-lg border bg-card p-4 shadow-sm">
+            <Button onClick={() => setIsCreateOpen(true)} className="gap-2">
-                <h2 className="text-xl font-semibold">{stepConfig.template.title}</h2>
+              <Plus className="h-4 w-4" />
-                <div className="flex gap-2">
+              새 화면
-                  <Button 
+            </Button>
-                    variant="outline" 
+          </div>
-                    onClick={goToPreviousStep}
-                    className="h-10 gap-2 text-sm font-medium"
-                  >
-                    <ArrowLeft className="h-4 w-4" />
-                    이전 단계
-                  </Button>
-                  <Button 
-                    onClick={() => goToStep("list")}
-                    className="h-10 gap-2 text-sm font-medium"
-                  >
-                    목록으로 돌아가기
-                  </Button>
-                </div>
-              </div>
-              <TemplateManager selectedScreen={selectedScreen} onBackToList={() => goToStep("list")} />
-            </div>
-          )}
         </div>
       </div>
 
+      {/* 메인 콘텐츠 */}
+      {viewMode === "tree" ? (
+        <div className="flex-1 overflow-hidden flex">
+          {/* 왼쪽: 트리 구조 */}
+          <div className="w-[350px] min-w-[280px] max-w-[450px] flex flex-col border-r bg-background">
+            {/* 검색 */}
+            <div className="flex-shrink-0 p-3 border-b">
+              <div className="relative">
+                <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+                <Input
+                  placeholder="화면 검색..."
+                  value={searchTerm}
+                  onChange={(e) => setSearchTerm(e.target.value)}
+                  className="pl-9 h-9"
+                />
+              </div>
+            </div>
+            {/* 트리 뷰 */}
+            <div className="flex-1 overflow-hidden">
+              <ScreenGroupTreeView
+                screens={filteredScreens}
+                selectedScreen={selectedScreen}
+                onScreenSelect={handleScreenSelect}
+                onScreenDesign={handleDesignScreen}
+                onGroupSelect={(group) => {
+                  setSelectedGroup(group);
+                  setSelectedScreen(null); // 화면 선택 해제
+                  setFocusedScreenIdInGroup(null); // 포커스 초기화
+                }}
+                onScreenSelectInGroup={(group, screenId) => {
+                  // 그룹 내 화면 클릭 시
+                  const isNewGroup = selectedGroup?.id !== group.id;
+                  
+                  if (isNewGroup) {
+                    // 새 그룹 진입: 포커싱 없이 시작 (첫 진입 시 망가지는 문제 방지)
+                    setSelectedGroup(group);
+                    setFocusedScreenIdInGroup(null);
+                  } else {
+                    // 같은 그룹 내에서 다른 화면 클릭: 포커싱 유지
+                    setFocusedScreenIdInGroup(screenId);
+                  }
+                  setSelectedScreen(null);
+                }}
+              />
+            </div>
+          </div>
+
+          {/* 오른쪽: 관계 시각화 (React Flow) */}
+          <div className="flex-1 overflow-hidden">
+            <ScreenRelationFlow 
+              screen={selectedScreen} 
+              selectedGroup={selectedGroup}
+              initialFocusedScreenId={focusedScreenIdInGroup}
+            />
+          </div>
+        </div>
+      ) : (
+        // 테이블 뷰 (기존 ScreenList 사용)
+        <div className="flex-1 overflow-auto p-6">
+          <ScreenList
+            onScreenSelect={handleScreenSelect}
+            selectedScreen={selectedScreen}
+            onDesignScreen={handleDesignScreen}
+          />
+        </div>
+      )}
+
+      {/* 화면 생성 모달 */}
+      <CreateScreenModal
+        isOpen={isCreateOpen}
+        onClose={() => setIsCreateOpen(false)}
+        onSuccess={() => {
+          setIsCreateOpen(false);
+          loadScreens();
+        }}
+      />
+
       {/* Scroll to Top 버튼 */}
       <ScrollToTop />
     </div>

frontend/app/(main)/screens/[screenId]/page.tsx

@@ -32,9 +32,18 @@ function ScreenViewPage() {
 
   // URL 쿼리에서 menuObjid 가져오기 (메뉴 스코프)
   const menuObjid = searchParams.get("menuObjid") ? parseInt(searchParams.get("menuObjid")!) : undefined;
+  
+  // URL 쿼리에서 프리뷰용 company_code 가져오기
+  const previewCompanyCode = searchParams.get("company_code");
+  
+  // 프리뷰 모드 감지 (iframe에서 로드될 때)
+  const isPreviewMode = searchParams.get("preview") === "true";
 
   // 🆕 현재 로그인한 사용자 정보
-  const { user, userName, companyCode } = useAuth();
+  const { user, userName, companyCode: authCompanyCode } = useAuth();
+  
+  // 프리뷰 모드에서는 URL 파라미터의 company_code 우선 사용
+  const companyCode = previewCompanyCode || authCompanyCode;
 
   // 🆕 모바일 환경 감지
   const { isMobile } = useResponsive();
@@ -233,27 +242,40 @@ function ScreenViewPage() {
         const designWidth = layout?.screenResolution?.width || 1200;
         const designHeight = layout?.screenResolution?.height || 800;
 
-        // 컨테이너의 실제 크기
+        // 컨테이너의 실제 크기 (프리뷰 모드에서는 window 크기 사용)
-        const containerWidth = containerRef.current.offsetWidth;
+        let containerWidth: number;
-        const containerHeight = containerRef.current.offsetHeight;
+        let containerHeight: number;
+        
+        if (isPreviewMode) {
+          // iframe에서는 window 크기를 직접 사용
+          containerWidth = window.innerWidth;
+          containerHeight = window.innerHeight;
+        } else {
+          containerWidth = containerRef.current.offsetWidth;
+          containerHeight = containerRef.current.offsetHeight;
+        }
 
-        // 여백 설정: 좌우 16px씩 (총 32px), 상단 패딩 32px (pt-8)
+        let newScale: number;
-        const MARGIN_X = 32;
+        
-        const availableWidth = containerWidth - MARGIN_X;
+        if (isPreviewMode) {
-
+          // 프리뷰 모드: 가로/세로 모두 fit하도록 (여백 없이)
-        // 가로 기준 스케일 계산 (좌우 여백 16px씩 고정)
+          const scaleX = containerWidth / designWidth;
-        const newScale = availableWidth / designWidth;
+          const scaleY = containerHeight / designHeight;
+          newScale = Math.min(scaleX, scaleY, 1); // 최대 1배율
+        } else {
+          // 일반 모드: 가로 기준 스케일 (좌우 여백 16px씩 고정)
+          const MARGIN_X = 32;
+          const availableWidth = containerWidth - MARGIN_X;
+          newScale = availableWidth / designWidth;
+        }
 
         // console.log("📐 스케일 계산:", {
         //   containerWidth,
         //   containerHeight,
-        //   MARGIN_X,
-        //   availableWidth,
         //   designWidth,
         //   designHeight,
         //   finalScale: newScale,
-        //   "스케일된 화면 크기": `${designWidth * newScale}px × ${designHeight * newScale}px`,
+        //   isPreviewMode,
-        //   "실제 좌우 여백": `${(containerWidth - designWidth * newScale) / 2}px씩`,
         // });
 
         setScale(newScale);
@@ -272,7 +294,7 @@ function ScreenViewPage() {
     return () => {
       clearTimeout(timer);
     };
-  }, [layout, isMobile]);
+  }, [layout, isMobile, isPreviewMode]);
 
   if (loading) {
     return (
@@ -310,7 +332,7 @@ function ScreenViewPage() {
     <ScreenPreviewProvider isPreviewMode={false}>
       <ActiveTabProvider>
         <TableOptionsProvider>
-        <div ref={containerRef} className="bg-background h-full w-full overflow-auto p-3">
+        <div ref={containerRef} className={`bg-background h-full w-full ${isPreviewMode ? "overflow-hidden p-0" : "overflow-auto p-3"}`}>
           {/* 레이아웃 준비 중 로딩 표시 */}
           {!layoutReady && (
             <div className="from-muted to-muted/50 flex h-full w-full items-center justify-center bg-gradient-to-br">

frontend/app/globals.css

@@ -463,7 +463,8 @@ select {
   left: 0;
   right: 0;
   bottom: 0;
-  background: repeating-linear-gradient(90deg, rgba(0, 212, 255, 0.03) 0px, transparent 1px, transparent 60px),
+  background:
+    repeating-linear-gradient(90deg, rgba(0, 212, 255, 0.03) 0px, transparent 1px, transparent 60px),
     repeating-linear-gradient(0deg, rgba(0, 212, 255, 0.03) 0px, transparent 1px, transparent 60px),
     radial-gradient(ellipse 80% 50% at 50% 0%, rgba(0, 212, 255, 0.08) 0%, transparent 60%);
   pointer-events: none;
@@ -471,18 +472,24 @@ select {
 }
 
 .pop-light .pop-bg-pattern::before {
-  background: repeating-linear-gradient(90deg, rgba(0, 122, 204, 0.02) 0px, transparent 1px, transparent 60px),
+  background:
+    repeating-linear-gradient(90deg, rgba(0, 122, 204, 0.02) 0px, transparent 1px, transparent 60px),
     repeating-linear-gradient(0deg, rgba(0, 122, 204, 0.02) 0px, transparent 1px, transparent 60px),
     radial-gradient(ellipse 80% 50% at 50% 0%, rgba(0, 122, 204, 0.05) 0%, transparent 60%);
 }
 
 /* POP 글로우 효과 */
 .pop-glow-cyan {
-  box-shadow: 0 0 20px rgba(0, 212, 255, 0.5), 0 0 40px rgba(0, 212, 255, 0.3);
+  box-shadow:
+    0 0 20px rgba(0, 212, 255, 0.5),
+    0 0 40px rgba(0, 212, 255, 0.3);
 }
 
 .pop-glow-cyan-strong {
-  box-shadow: 0 0 10px rgba(0, 212, 255, 0.8), 0 0 30px rgba(0, 212, 255, 0.5), 0 0 50px rgba(0, 212, 255, 0.3);
+  box-shadow:
+    0 0 10px rgba(0, 212, 255, 0.8),
+    0 0 30px rgba(0, 212, 255, 0.5),
+    0 0 50px rgba(0, 212, 255, 0.3);
 }
 
 .pop-glow-success {
@@ -504,7 +511,9 @@ select {
     box-shadow: 0 0 5px rgba(0, 212, 255, 0.5);
   }
   50% {
-    box-shadow: 0 0 20px rgba(0, 212, 255, 0.8), 0 0 30px rgba(0, 212, 255, 0.4);
+    box-shadow:
+      0 0 20px rgba(0, 212, 255, 0.8),
+      0 0 30px rgba(0, 212, 255, 0.4);
   }
 }
 
@@ -610,4 +619,18 @@ select {
   animation: marching-ants-v 0.4s linear infinite;
 }
 
+/* ===== 저장 테이블 막대기 애니메이션 ===== */
+@keyframes saveBarDrop {
+  0% {
+    transform: scaleY(0);
+    transform-origin: top;
+    opacity: 0;
+  }
+  100% {
+    transform: scaleY(1);
+    transform-origin: top;
+    opacity: 1;
+  }
+}
+
 /* ===== End of Global Styles ===== */

frontend/components/layout/AppLayout.tsx

@@ -302,6 +302,9 @@ function AppLayoutInner({ children }: AppLayoutProps) {
   // 현재 경로에 따라 어드민 모드인지 판단 (쿼리 파라미터도 고려)
   const isAdminMode = pathname.startsWith("/admin") || searchParams.get("mode") === "admin";
 
+  // 프리뷰 모드: 사이드바/헤더 없이 화면만 표시 (iframe 임베드용)
+  const isPreviewMode = searchParams.get("preview") === "true";
+
   // 현재 모드에 따라 표시할 메뉴 결정
   // 관리자 모드에서는 관리자 메뉴만, 사용자 모드에서는 사용자 메뉴만 표시
   const currentMenus = isAdminMode ? adminMenus : userMenus;
@@ -458,6 +461,15 @@ function AppLayoutInner({ children }: AppLayoutProps) {
     );
   }
 
+  // 프리뷰 모드: 사이드바/헤더 없이 화면만 표시
+  if (isPreviewMode) {
+    return (
+      <div className="h-screen w-full overflow-auto bg-white p-4">
+        {children}
+      </div>
+    );
+  }
+
   // UI 변환된 메뉴 데이터
   const uiMenus = convertMenuToUI(currentMenus, user as ExtendedUserInfo);
 

frontend/components/screen/ScreenGroupModal.tsx

@@ -0,0 +1,467 @@
+"use client";
+
+import React, { useState, useEffect } from "react";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { ScreenGroup, createScreenGroup, updateScreenGroup } from "@/lib/api/screenGroup";
+import { toast } from "sonner";
+import { apiClient } from "@/lib/api/client";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Check, ChevronsUpDown, Folder } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface ScreenGroupModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onSuccess: () => void;
+  group?: ScreenGroup | null; // 수정 모드일 때 기존 그룹 데이터
+}
+
+export function ScreenGroupModal({
+  isOpen,
+  onClose,
+  onSuccess,
+  group,
+}: ScreenGroupModalProps) {
+  const [currentCompanyCode, setCurrentCompanyCode] = useState<string>("");
+  const [isSuperAdmin, setIsSuperAdmin] = useState(false);
+  
+  const [formData, setFormData] = useState({
+    group_name: "",
+    group_code: "",
+    description: "",
+    display_order: 0,
+    target_company_code: "",
+    parent_group_id: null as number | null,
+  });
+  const [loading, setLoading] = useState(false);
+  const [companies, setCompanies] = useState<{ code: string; name: string }[]>([]);
+  const [availableParentGroups, setAvailableParentGroups] = useState<ScreenGroup[]>([]);
+  const [isParentGroupSelectOpen, setIsParentGroupSelectOpen] = useState(false);
+
+  // 그룹 경로 가져오기 (계층 구조 표시용)
+  const getGroupPath = (groupId: number): string => {
+    const grp = availableParentGroups.find((g) => g.id === groupId);
+    if (!grp) return "";
+    
+    const path: string[] = [grp.group_name];
+    let currentGroup = grp;
+    
+    while ((currentGroup as any).parent_group_id) {
+      const parent = availableParentGroups.find((g) => g.id === (currentGroup as any).parent_group_id);
+      if (parent) {
+        path.unshift(parent.group_name);
+        currentGroup = parent;
+      } else {
+        break;
+      }
+    }
+    
+    return path.join(" > ");
+  };
+
+  // 그룹을 계층 구조로 정렬
+  const getSortedGroups = (): typeof availableParentGroups => {
+    const result: typeof availableParentGroups = [];
+    
+    const addChildren = (parentId: number | null, level: number) => {
+      const children = availableParentGroups
+        .filter((g) => (g as any).parent_group_id === parentId)
+        .sort((a, b) => (a.display_order || 0) - (b.display_order || 0));
+      
+      for (const child of children) {
+        result.push({ ...child, group_level: level } as any);
+        addChildren(child.id, level + 1);
+      }
+    };
+    
+    addChildren(null, 1);
+    return result;
+  };
+
+  // 현재 사용자 정보 로드
+  useEffect(() => {
+    const loadUserInfo = async () => {
+      try {
+        const response = await apiClient.get("/auth/me");
+        const result = response.data;
+        if (result.success && result.data) {
+          const companyCode = result.data.companyCode || result.data.company_code || "";
+          setCurrentCompanyCode(companyCode);
+          setIsSuperAdmin(companyCode === "*");
+        }
+      } catch (error) {
+        console.error("사용자 정보 로드 실패:", error);
+      }
+    };
+    
+    if (isOpen) {
+      loadUserInfo();
+    }
+  }, [isOpen]);
+
+  // 회사 목록 로드 (최고 관리자만)
+  useEffect(() => {
+    if (isSuperAdmin && isOpen) {
+      const loadCompanies = async () => {
+        try {
+          const response = await apiClient.get("/admin/companies");
+          const result = response.data;
+          if (result.success && result.data) {
+            const companyList = result.data.map((c: any) => ({
+              code: c.company_code,
+              name: c.company_name,
+            }));
+            setCompanies(companyList);
+          }
+        } catch (error) {
+          console.error("회사 목록 로드 실패:", error);
+        }
+      };
+      loadCompanies();
+    }
+  }, [isSuperAdmin, isOpen]);
+
+  // 부모 그룹 목록 로드 (현재 회사의 대분류/중분류 그룹만)
+  useEffect(() => {
+    if (isOpen && currentCompanyCode) {
+      const loadParentGroups = async () => {
+        try {
+          const response = await apiClient.get(`/screen-groups/groups?size=1000`);
+          const result = response.data;
+          if (result.success && result.data) {
+            // 모든 그룹을 상위 그룹으로 선택 가능 (무한 중첩 지원)
+            setAvailableParentGroups(result.data);
+          }
+        } catch (error) {
+          console.error("부모 그룹 목록 로드 실패:", error);
+        }
+      };
+      loadParentGroups();
+    }
+  }, [isOpen, currentCompanyCode]);
+
+  // 그룹 데이터가 변경되면 폼 초기화
+  useEffect(() => {
+    if (currentCompanyCode) {
+      if (group) {
+        setFormData({
+          group_name: group.group_name || "",
+          group_code: group.group_code || "",
+          description: group.description || "",
+          display_order: group.display_order || 0,
+          target_company_code: group.company_code || currentCompanyCode,
+          parent_group_id: (group as any).parent_group_id || null,
+        });
+      } else {
+        setFormData({
+          group_name: "",
+          group_code: "",
+          description: "",
+          display_order: 0,
+          target_company_code: currentCompanyCode,
+          parent_group_id: null,
+        });
+      }
+    }
+  }, [group, isOpen, currentCompanyCode]);
+
+  const handleSubmit = async () => {
+    // 필수 필드 검증
+    if (!formData.group_name.trim()) {
+      toast.error("그룹명을 입력하세요");
+      return;
+    }
+    if (!formData.group_code.trim()) {
+      toast.error("그룹 코드를 입력하세요");
+      return;
+    }
+
+    setLoading(true);
+    try {
+      let response;
+      if (group) {
+        // 수정 모드
+        response = await updateScreenGroup(group.id, formData);
+      } else {
+        // 추가 모드
+        response = await createScreenGroup({
+          ...formData,
+          is_active: "Y",
+        });
+      }
+
+      if (response.success) {
+        toast.success(group ? "그룹이 수정되었습니다" : "그룹이 추가되었습니다");
+        onSuccess();
+        onClose();
+      } else {
+        toast.error(response.message || "작업에 실패했습니다");
+      }
+    } catch (error: any) {
+      console.error("그룹 저장 실패:", error);
+      toast.error("그룹 저장에 실패했습니다");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent className="max-w-[95vw] sm:max-w-[500px]">
+        <DialogHeader>
+          <DialogTitle className="text-base sm:text-lg">
+            {group ? "그룹 수정" : "그룹 추가"}
+          </DialogTitle>
+          <DialogDescription className="text-xs sm:text-sm">
+            화면 그룹 정보를 입력하세요
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 sm:space-y-4">
+          {/* 회사 선택 (최고 관리자만) */}
+          {isSuperAdmin && (
+            <div>
+              <Label htmlFor="target_company_code" className="text-xs sm:text-sm">
+                회사 선택 *
+              </Label>
+              <Select
+                value={formData.target_company_code}
+                onValueChange={(value) =>
+                  setFormData({ ...formData, target_company_code: value })
+                }
+              >
+                <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                  <SelectValue placeholder="회사를 선택하세요" />
+                </SelectTrigger>
+                <SelectContent>
+                  {companies.map((company) => (
+                    <SelectItem key={company.code} value={company.code}>
+                      {company.name} ({company.code})
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+              <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+                선택한 회사에 그룹이 생성됩니다
+              </p>
+            </div>
+          )}
+
+          {/* 부모 그룹 선택 (하위 그룹 만들기) - 트리 구조 + 검색 */}
+          <div>
+            <Label htmlFor="parent_group_id" className="text-xs sm:text-sm">
+              상위 그룹 (선택사항)
+            </Label>
+            <Popover open={isParentGroupSelectOpen} onOpenChange={setIsParentGroupSelectOpen}>
+              <PopoverTrigger asChild>
+                <Button
+                  variant="outline"
+                  role="combobox"
+                  aria-expanded={isParentGroupSelectOpen}
+                  className="h-8 w-full justify-between text-xs sm:h-10 sm:text-sm"
+                >
+                  {formData.parent_group_id === null
+                    ? "대분류로 생성"
+                    : getGroupPath(formData.parent_group_id) || "그룹 선택"}
+                  <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+                </Button>
+              </PopoverTrigger>
+              <PopoverContent
+                className="p-0"
+                style={{ width: "var(--radix-popover-trigger-width)" }}
+                align="start"
+              >
+                <Command>
+                  <CommandInput
+                    placeholder="그룹 검색..."
+                    className="text-xs sm:text-sm"
+                  />
+                  <CommandList>
+                    <CommandEmpty className="text-xs sm:text-sm py-2 text-center">
+                      그룹을 찾을 수 없습니다
+                    </CommandEmpty>
+                    <CommandGroup>
+                      {/* 대분류로 생성 옵션 */}
+                      <CommandItem
+                        value="none"
+                        onSelect={() => {
+                          setFormData({ ...formData, parent_group_id: null });
+                          setIsParentGroupSelectOpen(false);
+                        }}
+                        className="text-xs sm:text-sm"
+                      >
+                        <Check
+                          className={cn(
+                            "mr-2 h-4 w-4",
+                            formData.parent_group_id === null ? "opacity-100" : "opacity-0"
+                          )}
+                        />
+                        <Folder className="mr-2 h-4 w-4 text-muted-foreground" />
+                        대분류로 생성
+                      </CommandItem>
+                      {/* 계층 구조로 그룹 표시 */}
+                      {getSortedGroups().map((parentGroup) => (
+                        <CommandItem
+                          key={parentGroup.id}
+                          value={`${parentGroup.group_name} ${getGroupPath(parentGroup.id)}`}
+                          onSelect={() => {
+                            setFormData({ ...formData, parent_group_id: parentGroup.id });
+                            setIsParentGroupSelectOpen(false);
+                          }}
+                          className="text-xs sm:text-sm"
+                        >
+                          <Check
+                            className={cn(
+                              "mr-2 h-4 w-4",
+                              formData.parent_group_id === parentGroup.id ? "opacity-100" : "opacity-0"
+                            )}
+                          />
+                          {/* 들여쓰기로 계층 표시 */}
+                          <span
+                            style={{ marginLeft: `${(((parentGroup as any).group_level || 1) - 1) * 16}px` }}
+                            className="flex items-center"
+                          >
+                            <Folder className="mr-2 h-4 w-4 text-muted-foreground" />
+                            {parentGroup.group_name}
+                          </span>
+                        </CommandItem>
+                      ))}
+                    </CommandGroup>
+                  </CommandList>
+                </Command>
+              </PopoverContent>
+            </Popover>
+            <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+              부모 그룹을 선택하면 하위 그룹으로 생성됩니다
+            </p>
+          </div>
+
+          {/* 그룹명 */}
+          <div>
+            <Label htmlFor="group_name" className="text-xs sm:text-sm">
+              그룹명 *
+            </Label>
+            <Input
+              id="group_name"
+              value={formData.group_name}
+              onChange={(e) =>
+                setFormData({ ...formData, group_name: e.target.value })
+              }
+              placeholder="그룹명을 입력하세요"
+              className="h-8 text-xs sm:h-10 sm:text-sm"
+            />
+          </div>
+
+          {/* 그룹 코드 */}
+          <div>
+            <Label htmlFor="group_code" className="text-xs sm:text-sm">
+              그룹 코드 *
+            </Label>
+            <Input
+              id="group_code"
+              value={formData.group_code}
+              onChange={(e) =>
+                setFormData({ ...formData, group_code: e.target.value })
+              }
+              placeholder="영문 대문자와 언더스코어로 입력"
+              className="h-8 text-xs sm:h-10 sm:text-sm"
+              disabled={!!group} // 수정 모드일 때는 코드 변경 불가
+            />
+            {group && (
+              <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+                그룹 코드는 수정할 수 없습니다
+              </p>
+            )}
+          </div>
+
+          {/* 설명 */}
+          <div>
+            <Label htmlFor="description" className="text-xs sm:text-sm">
+              설명
+            </Label>
+            <Textarea
+              id="description"
+              value={formData.description}
+              onChange={(e) =>
+                setFormData({ ...formData, description: e.target.value })
+              }
+              placeholder="그룹에 대한 설명을 입력하세요"
+              className="min-h-[60px] text-xs sm:min-h-[80px] sm:text-sm"
+            />
+          </div>
+
+          {/* 정렬 순서 */}
+          <div>
+            <Label htmlFor="display_order" className="text-xs sm:text-sm">
+              정렬 순서
+            </Label>
+            <Input
+              id="display_order"
+              type="number"
+              value={formData.display_order}
+              onChange={(e) =>
+                setFormData({
+                  ...formData,
+                  display_order: parseInt(e.target.value) || 0,
+                })
+              }
+              className="h-8 text-xs sm:h-10 sm:text-sm"
+            />
+            <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+              숫자가 작을수록 상단에 표시됩니다
+            </p>
+          </div>
+        </div>
+
+        <DialogFooter className="gap-2 sm:gap-0">
+          <Button
+            variant="outline"
+            onClick={onClose}
+            disabled={loading}
+            className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+          >
+            취소
+          </Button>
+          <Button
+            onClick={handleSubmit}
+            disabled={loading}
+            className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+          >
+            {loading ? "저장 중..." : "저장"}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+

frontend/components/screen/ScreenGroupTreeView.tsx

@@ -0,0 +1,973 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { cn } from "@/lib/utils";
+import {
+  ChevronRight,
+  ChevronDown,
+  Monitor,
+  FolderOpen,
+  Folder,
+  Plus,
+  MoreVertical,
+  Edit,
+  Trash2,
+  FolderInput,
+} from "lucide-react";
+import { ScreenDefinition } from "@/types/screen";
+import {
+  ScreenGroup,
+  getScreenGroups,
+  deleteScreenGroup,
+  addScreenToGroup,
+  removeScreenFromGroup,
+} from "@/lib/api/screenGroup";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  DropdownMenuSeparator,
+} from "@/components/ui/dropdown-menu";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Input } from "@/components/ui/input";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Check, ChevronsUpDown } from "lucide-react";
+import { ScreenGroupModal } from "./ScreenGroupModal";
+import { toast } from "sonner";
+
+interface ScreenGroupTreeViewProps {
+  screens: ScreenDefinition[];
+  selectedScreen: ScreenDefinition | null;
+  onScreenSelect: (screen: ScreenDefinition) => void;
+  onScreenDesign: (screen: ScreenDefinition) => void;
+  onGroupSelect?: (group: { id: number; name: string; company_code?: string } | null) => void;
+  onScreenSelectInGroup?: (group: { id: number; name: string; company_code?: string }, screenId: number) => void;
+  companyCode?: string;
+}
+
+interface TreeNode {
+  type: "group" | "screen";
+  id: string;
+  name: string;
+  data?: ScreenDefinition | ScreenGroup;
+  children?: TreeNode[];
+  expanded?: boolean;
+}
+
+export function ScreenGroupTreeView({
+  screens,
+  selectedScreen,
+  onScreenSelect,
+  onScreenDesign,
+  onGroupSelect,
+  onScreenSelectInGroup,
+  companyCode,
+}: ScreenGroupTreeViewProps) {
+  const [groups, setGroups] = useState<ScreenGroup[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [expandedGroups, setExpandedGroups] = useState<Set<string>>(new Set());
+  const [groupScreensMap, setGroupScreensMap] = useState<Map<number, number[]>>(new Map());
+
+  // 그룹 모달 상태
+  const [isGroupModalOpen, setIsGroupModalOpen] = useState(false);
+  const [editingGroup, setEditingGroup] = useState<ScreenGroup | null>(null);
+
+  // 삭제 확인 다이얼로그 상태
+  const [isDeleteDialogOpen, setIsDeleteDialogOpen] = useState(false);
+  const [deletingGroup, setDeletingGroup] = useState<ScreenGroup | null>(null);
+
+  // 화면 이동 메뉴 상태
+  const [movingScreen, setMovingScreen] = useState<ScreenDefinition | null>(null);
+  const [isMoveMenuOpen, setIsMoveMenuOpen] = useState(false);
+  const [selectedGroupForMove, setSelectedGroupForMove] = useState<number | null>(null);
+  const [screenRole, setScreenRole] = useState<string>("");
+  const [isGroupSelectOpen, setIsGroupSelectOpen] = useState(false);
+  const [displayOrder, setDisplayOrder] = useState<number>(1);
+
+  // 그룹 목록 및 그룹별 화면 로드
+  useEffect(() => {
+    loadGroupsData();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [companyCode]);
+
+  // 그룹에 속한 화면 ID들을 가져오기
+  const getGroupedScreenIds = (): Set<number> => {
+    const ids = new Set<number>();
+    groupScreensMap.forEach((screenIds) => {
+      screenIds.forEach((id) => ids.add(id));
+    });
+    return ids;
+  };
+
+  // 미분류 화면들 (어떤 그룹에도 속하지 않은 화면)
+  const getUngroupedScreens = (): ScreenDefinition[] => {
+    const groupedIds = getGroupedScreenIds();
+    return screens.filter((screen) => !groupedIds.has(screen.screenId));
+  };
+
+  // 그룹에 속한 화면들 (display_order 오름차순 정렬)
+  const getScreensInGroup = (groupId: number): ScreenDefinition[] => {
+    const group = groups.find((g) => g.id === groupId);
+    if (!group?.screens) {
+    const screenIds = groupScreensMap.get(groupId) || [];
+    return screens.filter((screen) => screenIds.includes(screen.screenId));
+    }
+    
+    // 그룹의 screens 배열에서 display_order 정보를 가져와서 정렬
+    const sortedScreenIds = [...group.screens]
+      .sort((a, b) => (a.display_order || 999) - (b.display_order || 999))
+      .map((s) => s.screen_id);
+    
+    return sortedScreenIds
+      .map((id) => screens.find((screen) => screen.screenId === id))
+      .filter((screen): screen is ScreenDefinition => screen !== undefined);
+  };
+
+  const toggleGroup = (groupId: string) => {
+    const newExpanded = new Set(expandedGroups);
+    if (newExpanded.has(groupId)) {
+      newExpanded.delete(groupId);
+      // 그룹 접으면 선택 해제
+      if (onGroupSelect) {
+        onGroupSelect(null);
+      }
+    } else {
+      newExpanded.add(groupId);
+      // 그룹 펼치면 해당 그룹 선택
+      if (onGroupSelect && groupId !== "ungrouped") {
+        const group = groups.find((g) => String(g.id) === groupId);
+        if (group) {
+          onGroupSelect({ id: group.id, name: group.group_name, company_code: group.company_code });
+        }
+      }
+    }
+    setExpandedGroups(newExpanded);
+  };
+
+  const handleScreenClick = (screen: ScreenDefinition) => {
+    onScreenSelect(screen);
+  };
+
+  // 그룹 내 화면 클릭 핸들러 (그룹 전체 표시 + 해당 화면 포커스)
+  const handleScreenClickInGroup = (screen: ScreenDefinition, group: ScreenGroup) => {
+    if (onScreenSelectInGroup) {
+      onScreenSelectInGroup(
+        { id: group.id, name: group.group_name, company_code: group.company_code },
+        screen.screenId
+      );
+    } else {
+      // fallback: 기존 동작
+      onScreenSelect(screen);
+    }
+  };
+
+  const handleScreenDoubleClick = (screen: ScreenDefinition) => {
+    onScreenDesign(screen);
+  };
+
+  // 그룹 추가 버튼 클릭
+  const handleAddGroup = () => {
+    setEditingGroup(null);
+    setIsGroupModalOpen(true);
+  };
+
+  // 그룹 수정 버튼 클릭
+  const handleEditGroup = (group: ScreenGroup, e: React.MouseEvent) => {
+    e.stopPropagation();
+    setEditingGroup(group);
+    setIsGroupModalOpen(true);
+  };
+
+  // 그룹 삭제 버튼 클릭
+  const handleDeleteGroup = (group: ScreenGroup, e: React.MouseEvent) => {
+    e.stopPropagation();
+    setDeletingGroup(group);
+    setIsDeleteDialogOpen(true);
+  };
+
+  // 그룹 삭제 확인
+  const confirmDeleteGroup = async () => {
+    if (!deletingGroup) return;
+
+    try {
+      const response = await deleteScreenGroup(deletingGroup.id);
+      if (response.success) {
+        toast.success("그룹이 삭제되었습니다");
+        loadGroupsData();
+      } else {
+        toast.error(response.message || "그룹 삭제에 실패했습니다");
+      }
+    } catch (error) {
+      console.error("그룹 삭제 실패:", error);
+      toast.error("그룹 삭제에 실패했습니다");
+    } finally {
+      setIsDeleteDialogOpen(false);
+      setDeletingGroup(null);
+    }
+  };
+
+  // 화면 이동 메뉴 열기
+  const handleMoveScreen = (screen: ScreenDefinition, e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setMovingScreen(screen);
+    
+    // 현재 화면이 속한 그룹 정보 찾기
+    let currentGroupId: number | null = null;
+    let currentScreenRole: string = "";
+    let currentDisplayOrder: number = 1;
+    
+    // 현재 화면이 속한 그룹 찾기
+    for (const group of groups) {
+      if (group.screens && Array.isArray(group.screens)) {
+        const screenInfo = group.screens.find((s: any) => Number(s.screen_id) === Number(screen.screenId));
+        if (screenInfo) {
+          currentGroupId = group.id;
+          currentScreenRole = screenInfo.screen_role || "";
+          currentDisplayOrder = screenInfo.display_order || 1;
+          break;
+        }
+      }
+    }
+    
+    setSelectedGroupForMove(currentGroupId);
+    setScreenRole(currentScreenRole);
+    setDisplayOrder(currentDisplayOrder);
+    setIsMoveMenuOpen(true);
+  };
+
+  // 화면을 특정 그룹으로 이동
+  const moveScreenToGroup = async (targetGroupId: number | null) => {
+    if (!movingScreen) return;
+
+    try {
+      // 현재 그룹에서 제거
+      const currentGroupId = Array.from(groupScreensMap.entries()).find(([_, screenIds]) =>
+        screenIds.includes(movingScreen.screenId)
+      )?.[0];
+
+      if (currentGroupId) {
+        // screen_group_screens에서 해당 연결 찾아서 삭제
+        const currentGroup = groups.find((g) => g.id === currentGroupId);
+        if (currentGroup && currentGroup.screens) {
+          const screenGroupScreen = currentGroup.screens.find(
+            (s: any) => s.screen_id === movingScreen.screenId
+          );
+          if (screenGroupScreen) {
+            await removeScreenFromGroup(screenGroupScreen.id);
+          }
+        }
+      }
+
+      // 새 그룹에 추가 (미분류가 아닌 경우)
+      if (targetGroupId !== null) {
+        await addScreenToGroup({
+          group_id: targetGroupId,
+          screen_id: movingScreen.screenId,
+          screen_role: screenRole,
+          display_order: displayOrder,
+          is_default: "N",
+        });
+      }
+
+      toast.success("화면이 이동되었습니다");
+      loadGroupsData();
+    } catch (error) {
+      console.error("화면 이동 실패:", error);
+      toast.error("화면 이동에 실패했습니다");
+    } finally {
+      setIsMoveMenuOpen(false);
+      setMovingScreen(null);
+      setSelectedGroupForMove(null);
+      setScreenRole("");
+      setDisplayOrder(1);
+    }
+  };
+
+  // 그룹 경로 가져오기 (계층 구조 표시용)
+  const getGroupPath = (groupId: number): string => {
+    const group = groups.find((g) => g.id === groupId);
+    if (!group) return "";
+    
+    const path: string[] = [group.group_name];
+    let currentGroup = group;
+    
+    while (currentGroup.parent_group_id) {
+      const parent = groups.find((g) => g.id === currentGroup.parent_group_id);
+      if (parent) {
+        path.unshift(parent.group_name);
+        currentGroup = parent;
+      } else {
+        break;
+      }
+    }
+    
+    return path.join(" > ");
+  };
+
+  // 그룹 레벨 가져오기 (들여쓰기용)
+  const getGroupLevel = (groupId: number): number => {
+    const group = groups.find((g) => g.id === groupId);
+    return group?.group_level || 1;
+  };
+
+  // 그룹을 계층 구조로 정렬
+  const getSortedGroups = (): typeof groups => {
+    const result: typeof groups = [];
+    
+    const addChildren = (parentId: number | null, level: number) => {
+      const children = groups
+        .filter((g) => g.parent_group_id === parentId)
+        .sort((a, b) => (a.display_order || 0) - (b.display_order || 0));
+      
+      for (const child of children) {
+        result.push({ ...child, group_level: level });
+        addChildren(child.id, level + 1);
+      }
+    };
+    
+    addChildren(null, 1);
+    return result;
+  };
+
+  // 그룹 데이터 새로고침
+  const loadGroupsData = async () => {
+    try {
+      setLoading(true);
+      const response = await getScreenGroups({ size: 1000 }); // 모든 그룹 가져오기
+      if (response.success && response.data) {
+        setGroups(response.data);
+
+        // 각 그룹별 화면 목록 매핑
+        const screenMap = new Map<number, number[]>();
+        for (const group of response.data) {
+          if (group.screens && Array.isArray(group.screens)) {
+            screenMap.set(
+              group.id,
+              group.screens.map((s: any) => s.screen_id)
+            );
+          }
+        }
+        setGroupScreensMap(screenMap);
+      }
+    } catch (error) {
+      console.error("그룹 목록 로드 실패:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center p-8">
+        <div className="text-sm text-muted-foreground">로딩 중...</div>
+      </div>
+    );
+  }
+
+  const ungroupedScreens = getUngroupedScreens();
+
+  return (
+    <div className="h-full flex flex-col overflow-hidden">
+      {/* 그룹 추가 버튼 */}
+      <div className="flex-shrink-0 border-b p-2">
+        <Button
+          onClick={handleAddGroup}
+          variant="outline"
+          size="sm"
+          className="w-full gap-2"
+        >
+          <Plus className="h-4 w-4" />
+          그룹 추가
+        </Button>
+      </div>
+
+      {/* 트리 목록 */}
+      <div className="flex-1 overflow-auto p-2">
+        {/* 그룹화된 화면들 (대분류만 먼저 렌더링) */}
+        {groups
+          .filter((g) => !(g as any).parent_group_id) // 대분류만 (parent_group_id가 null)
+          .map((group) => {
+          const groupId = String(group.id);
+          const isExpanded = expandedGroups.has(groupId);
+          const groupScreens = getScreensInGroup(group.id);
+            
+            // 하위 그룹들 찾기
+            const childGroups = groups.filter((g) => (g as any).parent_group_id === group.id);
+
+          return (
+            <div key={groupId} className="mb-1">
+              {/* 그룹 헤더 */}
+              <div
+                className={cn(
+                  "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer hover:bg-accent transition-colors",
+                  "text-sm font-medium group/item"
+                )}
+                onClick={() => toggleGroup(groupId)}
+              >
+                {isExpanded ? (
+                  <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground" />
+                ) : (
+                  <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" />
+                )}
+                {isExpanded ? (
+                  <FolderOpen className="h-4 w-4 shrink-0 text-amber-500" />
+                ) : (
+                  <Folder className="h-4 w-4 shrink-0 text-amber-500" />
+                )}
+                <span className="truncate flex-1">{group.group_name}</span>
+                <Badge variant="secondary" className="text-xs">
+                  {groupScreens.length}
+                </Badge>
+                {/* 그룹 메뉴 버튼 */}
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-6 w-6 opacity-0 group-hover/item:opacity-100"
+                    >
+                      <MoreVertical className="h-3 w-3" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end">
+                    <DropdownMenuItem onClick={(e) => handleEditGroup(group, e as any)}>
+                      <Edit className="mr-2 h-4 w-4" />
+                      수정
+                    </DropdownMenuItem>
+                    <DropdownMenuSeparator />
+                    <DropdownMenuItem
+                      onClick={(e) => handleDeleteGroup(group, e as any)}
+                      className="text-destructive"
+                    >
+                      <Trash2 className="mr-2 h-4 w-4" />
+                      삭제
+                    </DropdownMenuItem>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </div>
+
+              {/* 그룹 내 하위 그룹들 */}
+              {isExpanded && childGroups.length > 0 && (
+                <div className="ml-6 mt-1 space-y-0.5">
+                  {childGroups.map((childGroup) => {
+                    const childGroupId = String(childGroup.id);
+                    const isChildExpanded = expandedGroups.has(childGroupId);
+                    const childScreens = getScreensInGroup(childGroup.id);
+                    
+                    // 손자 그룹들 (3단계)
+                    const grandChildGroups = groups.filter((g) => (g as any).parent_group_id === childGroup.id);
+
+                    return (
+                      <div key={childGroupId}>
+                        {/* 중분류 헤더 */}
+                        <div
+                          className={cn(
+                            "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer hover:bg-accent transition-colors",
+                            "text-xs font-medium group/item"
+                          )}
+                          onClick={() => toggleGroup(childGroupId)}
+                        >
+                          {isChildExpanded ? (
+                            <ChevronDown className="h-3 w-3 shrink-0 text-muted-foreground" />
+                          ) : (
+                            <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground" />
+                          )}
+                          {isChildExpanded ? (
+                            <FolderOpen className="h-3 w-3 shrink-0 text-blue-500" />
+                          ) : (
+                            <Folder className="h-3 w-3 shrink-0 text-blue-500" />
+                          )}
+                          <span className="truncate flex-1">{childGroup.group_name}</span>
+                          <Badge variant="secondary" className="text-[10px] h-4">
+                            {childScreens.length}
+                          </Badge>
+                          <DropdownMenu>
+                            <DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+                              <Button
+                                variant="ghost"
+                                size="icon"
+                                className="h-5 w-5 opacity-0 group-hover/item:opacity-100"
+                              >
+                                <MoreVertical className="h-3 w-3" />
+                              </Button>
+                            </DropdownMenuTrigger>
+                            <DropdownMenuContent align="end">
+                              <DropdownMenuItem onClick={(e) => handleEditGroup(childGroup, e as any)}>
+                                <Edit className="mr-2 h-4 w-4" />
+                                수정
+                              </DropdownMenuItem>
+                              <DropdownMenuSeparator />
+                              <DropdownMenuItem
+                                onClick={(e) => handleDeleteGroup(childGroup, e as any)}
+                                className="text-destructive"
+                              >
+                                <Trash2 className="mr-2 h-4 w-4" />
+                                삭제
+                              </DropdownMenuItem>
+                            </DropdownMenuContent>
+                          </DropdownMenu>
+                        </div>
+
+                        {/* 중분류 내 손자 그룹들 (소분류) */}
+                        {isChildExpanded && grandChildGroups.length > 0 && (
+                          <div className="ml-6 mt-1 space-y-0.5">
+                            {grandChildGroups.map((grandChild) => {
+                              const grandChildId = String(grandChild.id);
+                              const isGrandExpanded = expandedGroups.has(grandChildId);
+                              const grandScreens = getScreensInGroup(grandChild.id);
+
+                              return (
+                                <div key={grandChildId}>
+                                  {/* 소분류 헤더 */}
+                                  <div
+                                    className={cn(
+                                      "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer hover:bg-accent transition-colors",
+                                      "text-xs group/item"
+                                    )}
+                                    onClick={() => toggleGroup(grandChildId)}
+                                  >
+                                    {isGrandExpanded ? (
+                                      <ChevronDown className="h-3 w-3 shrink-0 text-muted-foreground" />
+                                    ) : (
+                                      <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground" />
+                                    )}
+                                    {isGrandExpanded ? (
+                                      <FolderOpen className="h-3 w-3 shrink-0 text-green-500" />
+                                    ) : (
+                                      <Folder className="h-3 w-3 shrink-0 text-green-500" />
+                                    )}
+                                    <span className="truncate flex-1">{grandChild.group_name}</span>
+                                    <Badge variant="outline" className="text-[10px] h-4">
+                                      {grandScreens.length}
+                                    </Badge>
+                                    <DropdownMenu>
+                                      <DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+                                        <Button
+                                          variant="ghost"
+                                          size="icon"
+                                          className="h-5 w-5 opacity-0 group-hover/item:opacity-100"
+                                        >
+                                          <MoreVertical className="h-3 w-3" />
+                                        </Button>
+                                      </DropdownMenuTrigger>
+                                      <DropdownMenuContent align="end">
+                                        <DropdownMenuItem onClick={(e) => handleEditGroup(grandChild, e as any)}>
+                                          <Edit className="mr-2 h-4 w-4" />
+                                          수정
+                                        </DropdownMenuItem>
+                                        <DropdownMenuSeparator />
+                                        <DropdownMenuItem
+                                          onClick={(e) => handleDeleteGroup(grandChild, e as any)}
+                                          className="text-destructive"
+                                        >
+                                          <Trash2 className="mr-2 h-4 w-4" />
+                                          삭제
+                                        </DropdownMenuItem>
+                                      </DropdownMenuContent>
+                                    </DropdownMenu>
+                                  </div>
+
+                                  {/* 소분류 내 화면들 */}
+                                  {isGrandExpanded && (
+                                    <div className="ml-6 mt-1 space-y-0.5">
+                                      {grandScreens.length === 0 ? (
+                                        <div className="pl-6 py-2 text-xs text-muted-foreground">
+                                          화면이 없습니다
+                                        </div>
+                                      ) : (
+                                        grandScreens.map((screen) => (
+                                          <div
+                                            key={screen.screenId}
+                                            className={cn(
+                                              "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer transition-colors",
+                                              "text-xs hover:bg-accent",
+                                              selectedScreen?.screenId === screen.screenId && "bg-accent"
+                                            )}
+                                            onClick={() => handleScreenClickInGroup(screen, grandChild)}
+                                            onDoubleClick={() => handleScreenDoubleClick(screen)}
+                                            onContextMenu={(e) => handleMoveScreen(screen, e)}
+                                          >
+                                            <Monitor className="h-3 w-3 shrink-0 text-blue-500" />
+                                            <span className="truncate flex-1">{screen.screenName}</span>
+                                            <span className="text-[10px] text-muted-foreground truncate max-w-[80px]">
+                                              {screen.screenCode}
+                                            </span>
+                                          </div>
+                                        ))
+                                      )}
+                                    </div>
+                                  )}
+                                </div>
+                              );
+                            })}
+                          </div>
+                        )}
+
+                        {/* 중분류 내 화면들 */}
+                        {isChildExpanded && (
+                          <div className="ml-6 mt-1 space-y-0.5">
+                            {childScreens.length === 0 && grandChildGroups.length === 0 ? (
+                              <div className="pl-6 py-2 text-xs text-muted-foreground">
+                                화면이 없습니다
+                              </div>
+                            ) : (
+                              childScreens.map((screen) => (
+                                <div
+                                  key={screen.screenId}
+                                  className={cn(
+                                    "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer transition-colors",
+                                    "text-xs hover:bg-accent",
+                                    selectedScreen?.screenId === screen.screenId && "bg-accent"
+                                  )}
+                                  onClick={() => handleScreenClickInGroup(screen, childGroup)}
+                                  onDoubleClick={() => handleScreenDoubleClick(screen)}
+                                  onContextMenu={(e) => handleMoveScreen(screen, e)}
+                                >
+                                  <Monitor className="h-3 w-3 shrink-0 text-blue-500" />
+                                  <span className="truncate flex-1">{screen.screenName}</span>
+                                  <span className="text-[10px] text-muted-foreground truncate max-w-[80px]">
+                                    {screen.screenCode}
+                                  </span>
+                                </div>
+                              ))
+                            )}
+                          </div>
+                        )}
+                      </div>
+                    );
+                  })}
+                </div>
+              )}
+
+              {/* 그룹 내 화면들 (대분류 직속) */}
+              {isExpanded && (
+                <div className="ml-4 mt-1 space-y-0.5">
+                  {groupScreens.length === 0 && childGroups.length === 0 ? (
+                    <div className="pl-6 py-2 text-xs text-muted-foreground">
+                      화면이 없습니다
+                    </div>
+                  ) : (
+                    groupScreens.map((screen) => (
+                      <div
+                        key={screen.screenId}
+                        className={cn(
+                          "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer transition-colors",
+                          "text-sm hover:bg-accent group/screen",
+                          selectedScreen?.screenId === screen.screenId && "bg-accent"
+                        )}
+                        onClick={() => handleScreenClickInGroup(screen, group)}
+                        onDoubleClick={() => handleScreenDoubleClick(screen)}
+                        onContextMenu={(e) => handleMoveScreen(screen, e)}
+                      >
+                        <Monitor className="h-4 w-4 shrink-0 text-blue-500" />
+                        <span className="truncate flex-1">{screen.screenName}</span>
+                        <span className="text-xs text-muted-foreground truncate max-w-[100px]">
+                          {screen.screenCode}
+                        </span>
+                      </div>
+                    ))
+                  )}
+                </div>
+              )}
+            </div>
+          );
+        })}
+
+        {/* 미분류 화면들 */}
+        {ungroupedScreens.length > 0 && (
+          <div className="mb-1">
+            <div
+              className={cn(
+                "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer hover:bg-accent transition-colors",
+                "text-sm font-medium text-muted-foreground"
+              )}
+              onClick={() => toggleGroup("ungrouped")}
+            >
+              {expandedGroups.has("ungrouped") ? (
+                <ChevronDown className="h-4 w-4 shrink-0" />
+              ) : (
+                <ChevronRight className="h-4 w-4 shrink-0" />
+              )}
+              <Folder className="h-4 w-4 shrink-0" />
+              <span className="truncate flex-1">미분류</span>
+              <Badge variant="outline" className="text-xs">
+                {ungroupedScreens.length}
+              </Badge>
+            </div>
+
+            {expandedGroups.has("ungrouped") && (
+              <div className="ml-4 mt-1 space-y-0.5">
+                {ungroupedScreens.map((screen) => (
+                  <div
+                    key={screen.screenId}
+                    className={cn(
+                      "flex items-center gap-2 rounded-md px-2 py-1.5 cursor-pointer transition-colors",
+                      "text-sm hover:bg-accent",
+                      selectedScreen?.screenId === screen.screenId && "bg-accent"
+                    )}
+                    onClick={() => handleScreenClick(screen)}
+                    onDoubleClick={() => handleScreenDoubleClick(screen)}
+                    onContextMenu={(e) => handleMoveScreen(screen, e)}
+                  >
+                    <Monitor className="h-4 w-4 shrink-0 text-blue-500" />
+                    <span className="truncate flex-1">{screen.screenName}</span>
+                    <span className="text-xs text-muted-foreground truncate max-w-[100px]">
+                      {screen.screenCode}
+                    </span>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+
+        {groups.length === 0 && ungroupedScreens.length === 0 && (
+          <div className="flex flex-col items-center justify-center py-8 text-center">
+            <Monitor className="h-12 w-12 text-muted-foreground/50 mb-2" />
+            <p className="text-sm text-muted-foreground">등록된 화면이 없습니다</p>
+          </div>
+        )}
+      </div>
+
+      {/* 그룹 추가/수정 모달 */}
+      <ScreenGroupModal
+        isOpen={isGroupModalOpen}
+        onClose={() => {
+          setIsGroupModalOpen(false);
+          setEditingGroup(null);
+        }}
+        onSuccess={loadGroupsData}
+        group={editingGroup}
+      />
+
+      {/* 그룹 삭제 확인 다이얼로그 */}
+      <AlertDialog open={isDeleteDialogOpen} onOpenChange={setIsDeleteDialogOpen}>
+        <AlertDialogContent className="max-w-[95vw] sm:max-w-[500px]">
+          <AlertDialogHeader>
+            <AlertDialogTitle className="text-base sm:text-lg">그룹 삭제</AlertDialogTitle>
+            <AlertDialogDescription className="text-xs sm:text-sm">
+              "{deletingGroup?.group_name}" 그룹을 삭제하시겠습니까?
+              <br />
+              그룹에 속한 화면들은 미분류로 이동됩니다.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter className="gap-2 sm:gap-0">
+            <AlertDialogCancel className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm">
+              취소
+            </AlertDialogCancel>
+            <AlertDialogAction
+              onClick={confirmDeleteGroup}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm bg-destructive hover:bg-destructive/90"
+            >
+              삭제
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      {/* 화면 이동 메뉴 (다이얼로그) */}
+      <Dialog open={isMoveMenuOpen} onOpenChange={setIsMoveMenuOpen}>
+        <DialogContent className="max-w-[95vw] sm:max-w-[400px]">
+          <DialogHeader>
+            <DialogTitle className="text-base sm:text-lg">화면 그룹 설정</DialogTitle>
+            <DialogDescription className="text-xs sm:text-sm">
+              "{movingScreen?.screenName}"의 그룹과 역할을 설정하세요
+            </DialogDescription>
+          </DialogHeader>
+          
+          <div className="space-y-3 sm:space-y-4">
+            {/* 그룹 선택 (트리 구조 + 검색) */}
+            <div>
+              <Label htmlFor="target-group" className="text-xs sm:text-sm">
+                그룹 선택 *
+              </Label>
+              <Popover open={isGroupSelectOpen} onOpenChange={setIsGroupSelectOpen}>
+                <PopoverTrigger asChild>
+                  <Button
+                    variant="outline"
+                    role="combobox"
+                    aria-expanded={isGroupSelectOpen}
+                    className="h-8 w-full justify-between text-xs sm:h-10 sm:text-sm"
+                  >
+                    {selectedGroupForMove === null
+                      ? "미분류"
+                      : getGroupPath(selectedGroupForMove) || "그룹 선택"}
+                    <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent
+                  className="p-0"
+                  style={{ width: "var(--radix-popover-trigger-width)" }}
+                  align="start"
+                >
+                  <Command>
+                    <CommandInput
+                      placeholder="그룹 검색..."
+                      className="text-xs sm:text-sm"
+                    />
+                    <CommandList>
+                      <CommandEmpty className="text-xs sm:text-sm py-2 text-center">
+                        그룹을 찾을 수 없습니다
+                      </CommandEmpty>
+                      <CommandGroup>
+                        {/* 미분류 옵션 */}
+                        <CommandItem
+                          value="none"
+                          onSelect={() => {
+                            setSelectedGroupForMove(null);
+                            setIsGroupSelectOpen(false);
+                          }}
+                          className="text-xs sm:text-sm"
+                        >
+                          <Check
+                            className={cn(
+                              "mr-2 h-4 w-4",
+                              selectedGroupForMove === null ? "opacity-100" : "opacity-0"
+                            )}
+                          />
+                          <Folder className="mr-2 h-4 w-4 text-muted-foreground" />
+                          미분류
+                        </CommandItem>
+                        {/* 계층 구조로 그룹 표시 */}
+                        {getSortedGroups().map((group) => (
+                          <CommandItem
+                            key={group.id}
+                            value={`${group.group_name} ${getGroupPath(group.id)}`}
+                            onSelect={() => {
+                              setSelectedGroupForMove(group.id);
+                              setIsGroupSelectOpen(false);
+                            }}
+                            className="text-xs sm:text-sm"
+                          >
+                            <Check
+                              className={cn(
+                                "mr-2 h-4 w-4",
+                                selectedGroupForMove === group.id ? "opacity-100" : "opacity-0"
+                              )}
+                            />
+                            {/* 들여쓰기로 계층 표시 */}
+                            <span
+                              style={{ marginLeft: `${((group.group_level || 1) - 1) * 16}px` }}
+                              className="flex items-center"
+                            >
+                              <Folder className="mr-2 h-4 w-4 text-muted-foreground" />
+                              {group.group_name}
+                            </span>
+                          </CommandItem>
+                        ))}
+                      </CommandGroup>
+                    </CommandList>
+                  </Command>
+                </PopoverContent>
+              </Popover>
+              <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+                계층 구조로 표시됩니다. 검색으로 빠르게 찾을 수 있습니다.
+              </p>
+            </div>
+
+            {/* 화면 역할 입력 (그룹이 선택된 경우만) */}
+            {selectedGroupForMove !== null && (
+              <>
+                <div>
+                  <Label htmlFor="screen-role" className="text-xs sm:text-sm">
+                    화면 역할 (선택사항)
+                  </Label>
+                  <Input
+                    id="screen-role"
+                    value={screenRole}
+                    onChange={(e) => setScreenRole(e.target.value)}
+                    placeholder="예: 목록, 등록, 조회, 팝업..."
+                    className="h-8 text-xs sm:h-10 sm:text-sm"
+                  />
+                  <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+                    화면의 용도를 자유롭게 입력하세요
+                  </p>
+                </div>
+
+                <div>
+                  <Label htmlFor="display-order" className="text-xs sm:text-sm">
+                    표시 순서 *
+                  </Label>
+                  <Input
+                    id="display-order"
+                    type="number"
+                    value={displayOrder}
+                    onChange={(e) => setDisplayOrder(parseInt(e.target.value) || 1)}
+                    min={1}
+                    className="h-8 text-xs sm:h-10 sm:text-sm"
+                  />
+                  <p className="text-muted-foreground mt-1 text-[10px] sm:text-xs">
+                    화면 흐름 순서 (1: 메인 그리드 → 2: 등록 폼 → 3: 팝업)
+                  </p>
+                </div>
+              </>
+            )}
+          </div>
+
+          <DialogFooter className="gap-2 sm:gap-0">
+            <Button
+              variant="outline"
+              onClick={() => {
+                setIsMoveMenuOpen(false);
+                setMovingScreen(null);
+                setSelectedGroupForMove(null);
+                setScreenRole("");
+                setDisplayOrder(1);
+              }}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              취소
+            </Button>
+            <Button
+              onClick={() => moveScreenToGroup(selectedGroupForMove)}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              이동
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}

frontend/components/screen/ScreenList.tsx

@@ -42,6 +42,8 @@ import { MoreHorizontal, Edit, Trash2, Copy, Eye, Plus, Search, Palette, RotateC
 import { ScreenDefinition } from "@/types/screen";
 import { screenApi } from "@/lib/api/screen";
 import { ExternalRestApiConnectionAPI, ExternalRestApiConnection } from "@/lib/api/externalRestApiConnection";
+import { getScreenGroups, ScreenGroup } from "@/lib/api/screenGroup";
+import { Layers } from "lucide-react";
 import CreateScreenModal from "./CreateScreenModal";
 import CopyScreenModal from "./CopyScreenModal";
 import dynamic from "next/dynamic";
@@ -93,6 +95,11 @@ export default function ScreenList({ onScreenSelect, selectedScreen, onDesignScr
   const [isCopyOpen, setIsCopyOpen] = useState(false);
   const [screenToCopy, setScreenToCopy] = useState<ScreenDefinition | null>(null);
 
+  // 그룹 필터 관련 상태
+  const [selectedGroupId, setSelectedGroupId] = useState<string>("all");
+  const [groups, setGroups] = useState<ScreenGroup[]>([]);
+  const [loadingGroups, setLoadingGroups] = useState(false);
+
   // 검색어 디바운스를 위한 타이머 ref
   const debounceTimer = useRef<NodeJS.Timeout | null>(null);
   
@@ -183,6 +190,25 @@ export default function ScreenList({ onScreenSelect, selectedScreen, onDesignScr
     }
   };
 
+  // 화면 그룹 목록 로드
+  useEffect(() => {
+    loadGroups();
+  }, []);
+
+  const loadGroups = async () => {
+    try {
+      setLoadingGroups(true);
+      const response = await getScreenGroups();
+      if (response.success && response.data) {
+        setGroups(response.data);
+      }
+    } catch (error) {
+      console.error("그룹 목록 조회 실패:", error);
+    } finally {
+      setLoadingGroups(false);
+    }
+  };
+
   // 검색어 디바운스 처리 (150ms 지연 - 빠른 응답)
   useEffect(() => {
     // 이전 타이머 취소
@@ -224,6 +250,11 @@ export default function ScreenList({ onScreenSelect, selectedScreen, onDesignScr
             params.companyCode = selectedCompanyCode;
           }
 
+          // 그룹 필터
+          if (selectedGroupId !== "all") {
+            params.groupId = selectedGroupId;
+          }
+
           console.log("🔍 화면 목록 API 호출:", params); // 디버깅용
           const resp = await screenApi.getScreens(params);
           console.log("✅ 화면 목록 응답:", resp); // 디버깅용
@@ -256,7 +287,7 @@ export default function ScreenList({ onScreenSelect, selectedScreen, onDesignScr
     return () => {
       abort = true;
     };
-  }, [currentPage, debouncedSearchTerm, activeTab, selectedCompanyCode, isSuperAdmin]);
+  }, [currentPage, debouncedSearchTerm, activeTab, selectedCompanyCode, selectedGroupId, isSuperAdmin]);
 
   const filteredScreens = screens; // 서버 필터 기준 사용
 
@@ -671,6 +702,25 @@ export default function ScreenList({ onScreenSelect, selectedScreen, onDesignScr
             </div>
           )}
 
+          {/* 그룹 필터 */}
+          <div className="w-full sm:w-[180px]">
+            <Select value={selectedGroupId} onValueChange={setSelectedGroupId} disabled={activeTab === "trash"}>
+              <SelectTrigger className="h-10 text-sm">
+                <Layers className="mr-2 h-4 w-4 text-muted-foreground" />
+                <SelectValue placeholder="전체 그룹" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="all">전체 그룹</SelectItem>
+                <SelectItem value="ungrouped">미분류</SelectItem>
+                {groups.map((group) => (
+                  <SelectItem key={group.id} value={String(group.id)}>
+                    {group.groupName}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
           {/* 검색 입력 */}
           <div className="w-full sm:w-[400px]">
             <div className="relative">

frontend/components/screen/ScreenNode.tsx

@@ -0,0 +1,869 @@
+"use client";
+
+import React, { useMemo, useState, useEffect } from "react";
+import { Handle, Position } from "@xyflow/react";
+import {
+  Monitor,
+  Database,
+  FormInput,
+  Table2,
+  LayoutDashboard,
+  MousePointer2,
+  Key,
+  Link2,
+  Columns3,
+} from "lucide-react";
+import { ScreenLayoutSummary } from "@/lib/api/screenGroup";
+
+// ========== 타입 정의 ==========
+
+// 화면 노드 데이터 인터페이스
+export interface ScreenNodeData {
+  label: string;
+  subLabel?: string;
+  type: "screen" | "table" | "action";
+  tableName?: string;
+  isMain?: boolean;
+  // 레이아웃 요약 정보 (미리보기용)
+  layoutSummary?: ScreenLayoutSummary;
+  // 그룹 내 포커스 관련 속성
+  isInGroup?: boolean;     // 그룹 모드인지
+  isFocused?: boolean;     // 포커스된 화면인지
+  isFaded?: boolean;       // 흑백 처리할지
+  screenRole?: string;     // 화면 역할 (메인그리드, 등록폼 등)
+}
+
+// 필드 매핑 정보 (조인 관계 표시용)
+export interface FieldMappingDisplay {
+  sourceField: string;        // 메인 테이블 컬럼 (예: manager_id)
+  targetField: string;        // 서브 테이블 컬럼 (예: user_id)
+  sourceDisplayName?: string; // 메인 테이블 한글 컬럼명 (예: 담당자)
+  targetDisplayName?: string; // 서브 테이블 한글 컬럼명 (예: 사용자ID)
+  sourceTable?: string;       // 소스 테이블명 (필드 매핑에서 테이블 구분용)
+}
+
+// 참조 관계 정보 (다른 테이블에서 이 테이블을 참조하는 경우)
+export interface ReferenceInfo {
+  fromTable: string;        // 참조하는 테이블명 (영문)
+  fromTableLabel?: string;  // 참조하는 테이블 한글명
+  fromColumn: string;       // 참조하는 컬럼명 (영문)
+  fromColumnLabel?: string; // 참조하는 컬럼 한글명
+  toColumn: string;         // 참조되는 컬럼명 (이 테이블의 컬럼)
+  toColumnLabel?: string;   // 참조되는 컬럼 한글명
+  relationType: 'lookup' | 'join' | 'filter';  // 참조 유형
+}
+
+// 테이블 노드 데이터 인터페이스
+export interface TableNodeData {
+  label: string;
+  subLabel?: string;
+  isMain?: boolean;
+  isFocused?: boolean;     // 포커스된 테이블인지
+  isFaded?: boolean;       // 흑백 처리할지
+  columns?: Array<{
+    name: string;           // 표시용 이름 (한글명)
+    originalName?: string;  // 원본 컬럼명 (영문, 필터링용)
+    type: string;
+    isPrimaryKey?: boolean;
+    isForeignKey?: boolean;
+  }>;
+  // 포커스 시 강조할 컬럼 정보
+  highlightedColumns?: string[];  // 화면에서 사용하는 컬럼 (영문명)
+  joinColumns?: string[];         // 조인에 사용되는 컬럼
+  joinColumnRefs?: Array<{        // 조인 컬럼의 참조 정보
+    column: string;               // FK 컬럼명 (예: 'customer_id')
+    refTable: string;             // 참조 테이블 (예: 'customer_mng')
+    refTableLabel?: string;       // 참조 테이블 한글명 (예: '거래처 관리')
+    refColumn: string;            // 참조 컬럼 (예: 'customer_code')
+  }>;
+  filterColumns?: string[];       // 필터링에 사용되는 FK 컬럼 (마스터-디테일 관계)
+  // 필드 매핑 정보 (조인 관계 표시용)
+  fieldMappings?: FieldMappingDisplay[];  // 서브 테이블일 때 조인 관계 표시
+  // 참조 관계 정보 (다른 테이블에서 이 테이블을 참조하는 경우)
+  referencedBy?: ReferenceInfo[];  // 이 테이블을 참조하는 관계들
+  // 저장 관계 정보
+  saveInfos?: Array<{
+    saveType: string;          // 'save' | 'edit' | 'delete' | 'transferData'
+    componentType: string;     // 버튼 컴포넌트 타입
+    isMainTable: boolean;      // 메인 테이블 저장인지
+    sourceScreenId?: number;   // 어떤 화면에서 저장하는지
+  }>;
+}
+
+// ========== 유틸리티 함수 ==========
+
+// 화면 타입별 아이콘
+const getScreenTypeIcon = (screenType?: string) => {
+  switch (screenType) {
+    case "grid":
+      return <Table2 className="h-4 w-4" />;
+    case "dashboard":
+      return <LayoutDashboard className="h-4 w-4" />;
+    case "action":
+      return <MousePointer2 className="h-4 w-4" />;
+    default:
+      return <FormInput className="h-4 w-4" />;
+  }
+};
+
+// 화면 타입별 색상 (헤더)
+const getScreenTypeColor = (screenType?: string, isMain?: boolean) => {
+  if (!isMain) return "bg-slate-400";
+  switch (screenType) {
+    case "grid":
+      return "bg-violet-500";
+    case "dashboard":
+      return "bg-amber-500";
+    case "action":
+      return "bg-rose-500";
+    default:
+      return "bg-blue-500";
+  }
+};
+
+// 화면 역할(screenRole)에 따른 색상
+const getScreenRoleColor = (screenRole?: string) => {
+  if (!screenRole) return "bg-slate-400";
+  
+  // 역할명에 포함된 키워드로 색상 결정
+  const role = screenRole.toLowerCase();
+  
+  if (role.includes("그리드") || role.includes("grid") || role.includes("메인") || role.includes("main") || role.includes("list")) {
+    return "bg-violet-500"; // 보라색 - 메인 그리드
+  }
+  if (role.includes("등록") || role.includes("폼") || role.includes("form") || role.includes("register") || role.includes("input")) {
+    return "bg-blue-500"; // 파란색 - 등록 폼
+  }
+  if (role.includes("액션") || role.includes("action") || role.includes("이벤트") || role.includes("event") || role.includes("클릭")) {
+    return "bg-rose-500"; // 빨간색 - 액션/이벤트
+  }
+  if (role.includes("상세") || role.includes("detail") || role.includes("popup") || role.includes("팝업")) {
+    return "bg-amber-500"; // 주황색 - 상세/팝업
+  }
+  
+  return "bg-slate-400"; // 기본 회색
+};
+
+// 화면 타입별 라벨
+const getScreenTypeLabel = (screenType?: string) => {
+  switch (screenType) {
+    case "grid":
+      return "그리드";
+    case "dashboard":
+      return "대시보드";
+    case "action":
+      return "액션";
+    default:
+      return "폼";
+  }
+};
+
+// ========== 화면 노드 (상단) - 미리보기 표시 ==========
+export const ScreenNode: React.FC<{ data: ScreenNodeData }> = ({ data }) => {
+  const { label, subLabel, isMain, tableName, layoutSummary, isInGroup, isFocused, isFaded, screenRole } = data;
+  const screenType = layoutSummary?.screenType || "form";
+  
+  // 그룹 모드에서는 screenRole 기반 색상, 그렇지 않으면 screenType 기반 색상
+  // isFocused일 때 색상 활성화, isFaded일 때 회색
+  let headerColor: string;
+  if (isInGroup) {
+    if (isFaded) {
+      headerColor = "bg-gray-300"; // 흑백 처리 - 더 확실한 회색
+    } else {
+      // 포커스되었거나 아직 아무것도 선택 안됐을 때: 역할별 색상
+      headerColor = getScreenRoleColor(screenRole);
+    }
+  } else {
+    headerColor = getScreenTypeColor(screenType, isMain);
+  }
+
+  return (
+    <div 
+      className={`group relative flex h-[320px] w-[260px] flex-col overflow-hidden rounded-lg border bg-card shadow-md transition-all cursor-pointer ${
+        isFocused 
+          ? "border-2 border-primary ring-4 ring-primary/50 shadow-xl scale-105" 
+          : isFaded
+          ? "border-gray-200 opacity-50"
+          : "border-border hover:shadow-lg hover:ring-2 hover:ring-primary/20"
+      }`}
+      style={{
+        filter: isFaded ? "grayscale(100%)" : "none",
+        transition: "all 0.3s ease",
+        transform: isFocused ? "scale(1.02)" : "scale(1)",
+      }}
+    >
+      {/* Handles */}
+      <Handle
+        type="target"
+        position={Position.Left}
+        id="left"
+        className="!h-2 !w-2 !border-2 !border-background !bg-blue-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        id="right"
+        className="!h-2 !w-2 !border-2 !border-background !bg-blue-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="bottom"
+        className="!h-2 !w-2 !border-2 !border-background !bg-blue-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+
+      {/* 헤더 (컬러) */}
+      <div className={`flex items-center gap-2 px-3 py-2 text-white ${headerColor} transition-colors duration-300`}>
+        <Monitor className="h-4 w-4" />
+        <span className="flex-1 truncate text-xs font-semibold">{label}</span>
+        {(isMain || isFocused) && <span className="flex h-2 w-2 rounded-full bg-white/80 animate-pulse" />}
+      </div>
+
+      {/* 화면 미리보기 영역 (컴팩트) */}
+      <div className="h-[140px] overflow-hidden bg-slate-50 p-2">
+        {layoutSummary ? (
+          <ScreenPreview layoutSummary={layoutSummary} screenType={screenType} />
+        ) : (
+          <div className="flex h-full flex-col items-center justify-center text-muted-foreground">
+            {getScreenTypeIcon(screenType)}
+            <span className="mt-1 text-[10px]">화면: {label}</span>
+          </div>
+        )}
+      </div>
+
+      {/* 필드 매핑 영역 */}
+      <div className="flex-1 overflow-hidden border-t border-slate-200 bg-white px-2 py-1.5">
+        <div className="mb-1 flex items-center gap-1 text-[9px] font-medium text-slate-500">
+          <Columns3 className="h-3 w-3" />
+          <span>필드 매핑</span>
+          <span className="ml-auto text-[8px] text-slate-400">
+            {layoutSummary?.layoutItems?.filter(i => i.label && !i.componentKind?.includes('button')).length || 0}개
+          </span>
+        </div>
+        <div className="flex flex-col gap-0.5 overflow-y-auto" style={{ maxHeight: '80px' }}>
+          {layoutSummary?.layoutItems
+            ?.filter(item => item.label && !item.componentKind?.includes('button'))
+            ?.slice(0, 6)
+            ?.map((item, idx) => (
+              <div key={idx} className="flex items-center gap-1 rounded bg-slate-50 px-1.5 py-0.5">
+                <div className={`h-1.5 w-1.5 rounded-full ${
+                  item.componentKind === 'table-list' ? 'bg-violet-400' :
+                  item.componentKind?.includes('select') ? 'bg-amber-400' :
+                  'bg-slate-400'
+                }`} />
+                <span className="flex-1 truncate text-[9px] text-slate-600">{item.label}</span>
+                <span className="text-[8px] text-slate-400">{item.componentKind?.split('-')[0] || 'field'}</span>
+              </div>
+            )) || (
+              <div className="text-center text-[9px] text-slate-400 py-2">필드 정보 없음</div>
+            )}
+        </div>
+          </div>
+
+      {/* 푸터 (테이블 정보) */}
+      <div className="flex items-center justify-between border-t border-border bg-muted/30 px-3 py-1.5">
+        <div className="flex items-center gap-1 text-[10px] text-muted-foreground">
+          <Database className="h-3 w-3" />
+          <span className="max-w-[120px] truncate font-mono">{tableName || "No Table"}</span>
+        </div>
+        <span className="rounded bg-muted px-1.5 py-0.5 text-[9px] font-medium text-muted-foreground">
+          {getScreenTypeLabel(screenType)}
+        </span>
+      </div>
+    </div>
+  );
+};
+
+// ========== 컴포넌트 종류별 미니어처 색상 ==========
+// componentKind는 더 정확한 컴포넌트 타입 (table-list, button-primary 등)
+const getComponentColor = (componentKind: string) => {
+  // 테이블/그리드 관련
+  if (componentKind === "table-list" || componentKind === "data-grid") {
+    return "bg-violet-200 border-violet-400";
+  }
+  // 검색 필터
+  if (componentKind === "table-search-widget" || componentKind === "search-filter") {
+    return "bg-pink-200 border-pink-400";
+  }
+  // 버튼 관련
+  if (componentKind?.includes("button")) {
+    return "bg-blue-300 border-blue-500";
+  }
+  // 입력 필드
+  if (componentKind?.includes("input") || componentKind?.includes("text")) {
+    return "bg-slate-200 border-slate-400";
+  }
+  // 셀렉트/드롭다운
+  if (componentKind?.includes("select") || componentKind?.includes("dropdown")) {
+    return "bg-amber-200 border-amber-400";
+  }
+  // 차트
+  if (componentKind?.includes("chart")) {
+    return "bg-emerald-200 border-emerald-400";
+  }
+  // 커스텀 위젯
+  if (componentKind === "custom") {
+    return "bg-pink-200 border-pink-400";
+  }
+  return "bg-slate-100 border-slate-300";
+};
+
+// ========== 화면 미리보기 컴포넌트 - 화면 타입별 간단한 일러스트 ==========
+const ScreenPreview: React.FC<{ layoutSummary: ScreenLayoutSummary; screenType: string }> = ({
+  layoutSummary,
+  screenType,
+}) => {
+  const { totalComponents, widgetCounts } = layoutSummary;
+
+  // 그리드 화면 일러스트
+  if (screenType === "grid") {
+  return (
+      <div className="flex h-full flex-col gap-2 rounded-lg border border-slate-200 bg-gradient-to-b from-slate-50 to-white p-3">
+        {/* 상단 툴바 */}
+        <div className="flex items-center gap-2">
+          <div className="h-4 w-16 rounded bg-pink-400/80 shadow-sm" />
+          <div className="flex-1" />
+          <div className="h-4 w-8 rounded bg-blue-500 shadow-sm" />
+          <div className="h-4 w-8 rounded bg-blue-500 shadow-sm" />
+          <div className="h-4 w-8 rounded bg-rose-500 shadow-sm" />
+        </div>
+        {/* 테이블 헤더 */}
+        <div className="flex gap-1 rounded-t-md bg-violet-500 px-2 py-2 shadow-sm">
+          {[...Array(5)].map((_, i) => (
+            <div key={i} className="h-2.5 flex-1 rounded bg-white/40" />
+          ))}
+        </div>
+        {/* 테이블 행들 */}
+        <div className="flex flex-1 flex-col gap-1 overflow-hidden">
+          {[...Array(7)].map((_, i) => (
+            <div key={i} className={`flex gap-1 rounded px-2 py-1.5 ${i % 2 === 0 ? "bg-slate-100" : "bg-white"}`}>
+              {[...Array(5)].map((_, j) => (
+                <div key={j} className="h-2 flex-1 rounded bg-slate-300/70" />
+              ))}
+            </div>
+          ))}
+        </div>
+        {/* 페이지네이션 */}
+        <div className="flex items-center justify-center gap-2 pt-1">
+          <div className="h-2.5 w-4 rounded bg-slate-300" />
+          <div className="h-2.5 w-4 rounded bg-blue-500" />
+          <div className="h-2.5 w-4 rounded bg-slate-300" />
+          <div className="h-2.5 w-4 rounded bg-slate-300" />
+        </div>
+        {/* 컴포넌트 수 */}
+        <div className="absolute bottom-2 right-2 rounded-md bg-slate-800/80 px-2 py-1 text-[10px] font-medium text-white shadow-sm">
+          {totalComponents}개
+        </div>
+      </div>
+    );
+  }
+
+  // 폼 화면 일러스트
+  if (screenType === "form") {
+    return (
+      <div className="flex h-full flex-col gap-3 rounded-lg border border-slate-200 bg-gradient-to-b from-slate-50 to-white p-3">
+        {/* 폼 필드들 */}
+        {[...Array(6)].map((_, i) => (
+          <div key={i} className="flex items-center gap-3">
+            <div className="h-2.5 w-14 rounded bg-slate-400" />
+            <div className="h-5 flex-1 rounded-md border border-slate-300 bg-white shadow-sm" />
+          </div>
+        ))}
+        {/* 버튼 영역 */}
+        <div className="mt-auto flex justify-end gap-2 border-t border-slate-100 pt-3">
+          <div className="h-5 w-14 rounded-md bg-slate-300 shadow-sm" />
+          <div className="h-5 w-14 rounded-md bg-blue-500 shadow-sm" />
+        </div>
+        {/* 컴포넌트 수 */}
+        <div className="absolute bottom-2 right-2 rounded-md bg-slate-800/80 px-2 py-1 text-[10px] font-medium text-white shadow-sm">
+          {totalComponents}개
+        </div>
+      </div>
+    );
+  }
+
+  // 대시보드 화면 일러스트
+  if (screenType === "dashboard") {
+    return (
+      <div className="grid h-full grid-cols-2 gap-2 rounded-lg border border-slate-200 bg-gradient-to-b from-slate-50 to-white p-3">
+        {/* 카드/차트들 */}
+        <div className="rounded-lg bg-emerald-100 p-2 shadow-sm">
+          <div className="mb-2 h-2.5 w-10 rounded bg-emerald-400" />
+          <div className="h-10 rounded-md bg-emerald-300/80" />
+        </div>
+        <div className="rounded-lg bg-amber-100 p-2 shadow-sm">
+          <div className="mb-2 h-2.5 w-10 rounded bg-amber-400" />
+          <div className="h-10 rounded-md bg-amber-300/80" />
+                </div>
+        <div className="col-span-2 rounded-lg bg-blue-100 p-2 shadow-sm">
+          <div className="mb-2 h-2.5 w-12 rounded bg-blue-400" />
+          <div className="flex h-14 items-end gap-1">
+            {[...Array(10)].map((_, i) => (
+              <div
+                key={i}
+                className="flex-1 rounded-t bg-blue-400/80"
+                style={{ height: `${25 + Math.random() * 75}%` }}
+              />
+            ))}
+          </div>
+        </div>
+        {/* 컴포넌트 수 */}
+        <div className="absolute bottom-2 right-2 rounded-md bg-slate-800/80 px-2 py-1 text-[10px] font-medium text-white shadow-sm">
+          {totalComponents}개
+        </div>
+                </div>
+    );
+  }
+
+  // 액션 화면 일러스트 (버튼 중심)
+  if (screenType === "action") {
+    return (
+      <div className="flex h-full flex-col items-center justify-center gap-4 rounded-lg border border-slate-200 bg-gradient-to-b from-slate-50 to-white p-3">
+        <div className="rounded-full bg-slate-100 p-4 text-slate-400">
+          <MousePointer2 className="h-10 w-10" />
+            </div>
+        <div className="flex gap-3">
+          <div className="h-7 w-16 rounded-md bg-blue-500 shadow-sm" />
+          <div className="h-7 w-16 rounded-md bg-slate-300 shadow-sm" />
+            </div>
+        <div className="text-xs font-medium text-slate-400">액션 화면</div>
+        {/* 컴포넌트 수 */}
+        <div className="absolute bottom-2 right-2 rounded-md bg-slate-800/80 px-2 py-1 text-[10px] font-medium text-white shadow-sm">
+          {totalComponents}개
+        </div>
+      </div>
+    );
+  }
+
+  // 기본 (알 수 없는 타입)
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-3 rounded-lg border border-slate-200 bg-gradient-to-b from-slate-50 to-white text-slate-400">
+      <div className="rounded-full bg-slate-100 p-4">
+        {getScreenTypeIcon(screenType)}
+      </div>
+      <span className="text-sm font-medium">{totalComponents}개 컴포넌트</span>
+    </div>
+  );
+};
+
+// ========== 테이블 노드 (하단) - 컬럼 목록 표시 (컴팩트) ==========
+export const TableNode: React.FC<{ data: TableNodeData }> = ({ data }) => {
+  const { label, subLabel, isMain, isFocused, isFaded, columns, highlightedColumns, joinColumns, joinColumnRefs, filterColumns, fieldMappings, referencedBy, saveInfos } = data;
+  
+  // 강조할 컬럼 세트 (영문 컬럼명 기준)
+  const highlightSet = new Set(highlightedColumns || []);
+  const filterSet = new Set(filterColumns || []);  // 필터링에 사용되는 FK 컬럼
+  const joinSet = new Set(joinColumns || []);
+  
+  // 조인 컬럼 참조 정보 맵 생성 (column → { refTable, refTableLabel, refColumn })
+  const joinRefMap = new Map<string, { refTable: string; refTableLabel: string; refColumn: string }>();
+  if (joinColumnRefs) {
+    joinColumnRefs.forEach((ref) => {
+      joinRefMap.set(ref.column, { 
+        refTable: ref.refTable, 
+        refTableLabel: ref.refTableLabel || ref.refTable, // 한글명 (없으면 영문명)
+        refColumn: ref.refColumn 
+      });
+    });
+  }
+  
+  // 필드 매핑 맵 생성 (targetField → { sourceField, sourceDisplayName })
+  // 서브 테이블에서 targetField가 어떤 메인 테이블 컬럼(sourceField)과 연결되는지
+  const fieldMappingMap = new Map<string, { sourceField: string; sourceDisplayName: string }>();
+  if (fieldMappings) {
+    fieldMappings.forEach(mapping => {
+      fieldMappingMap.set(mapping.targetField, {
+        sourceField: mapping.sourceField,
+        // 한글명이 있으면 한글명, 없으면 영문명 사용
+        sourceDisplayName: mapping.sourceDisplayName || mapping.sourceField,
+      });
+    });
+  }
+  
+  // 필터 소스 컬럼 세트 (메인 테이블에서 필터에 사용되는 컬럼)
+  const filterSourceSet = new Set(
+    referencedBy?.filter(r => r.relationType === 'filter').map(r => r.fromColumn) || []
+  );
+  
+  // 포커스 모드: 사용 컬럼만 필터링하여 표시
+  // originalName (영문) 또는 name으로 매칭 시도
+  // 필터 컬럼(filterSet) 및 필터 소스 컬럼(filterSourceSet)도 포함하여 보라색으로 표시
+  const potentialFilteredColumns = columns?.filter(col => {
+    const colOriginal = col.originalName || col.name;
+    return highlightSet.has(colOriginal) || joinSet.has(colOriginal) || filterSet.has(colOriginal) || filterSourceSet.has(colOriginal);
+  }) || [];
+  
+  // 정렬: 조인 컬럼 → 필터 컬럼/필터 소스 컬럼 → 사용 컬럼 순서
+  const sortedFilteredColumns = [...potentialFilteredColumns].sort((a, b) => {
+    const aOriginal = a.originalName || a.name;
+    const bOriginal = b.originalName || b.name;
+    
+    const aIsJoin = joinSet.has(aOriginal);
+    const bIsJoin = joinSet.has(bOriginal);
+    const aIsFilter = filterSet.has(aOriginal) || filterSourceSet.has(aOriginal);
+    const bIsFilter = filterSet.has(bOriginal) || filterSourceSet.has(bOriginal);
+    
+    // 조인 컬럼 우선
+    if (aIsJoin && !bIsJoin) return -1;
+    if (!aIsJoin && bIsJoin) return 1;
+    // 필터 컬럼/필터 소스 다음
+    if (aIsFilter && !bIsFilter) return -1;
+    if (!aIsFilter && bIsFilter) return 1;
+    // 나머지는 원래 순서 유지
+    return 0;
+  });
+  
+  const hasActiveColumns = sortedFilteredColumns.length > 0;
+  
+  // 필터 관계가 있는 테이블인지 확인 (마스터-디테일 필터링)
+  // - hasFilterRelation: 디테일 테이블 (WHERE 조건 대상) - filterColumns에 FK 컬럼이 있음
+  // - isFilterSource: 마스터 테이블 (필터 소스, WHERE 조건 제공) - 포커스된 화면의 메인 테이블이고 filterSourceSet에 컬럼이 있음
+  // 디테일 테이블: filterColumns(filterSet)에 FK 컬럼이 있고, 포커스된 화면의 메인이 아님
+  const hasFilterRelation = filterSet.size > 0 && !isFocused;
+  // 마스터 테이블: 포커스된 화면의 메인 테이블(isFocused)이고 filterSourceSet에 컬럼이 있음
+  const isFilterSource = isFocused && filterSourceSet.size > 0;
+  
+  // 표시할 컬럼:
+  // - 포커스 시 (활성 컬럼 있음): 정렬된 컬럼만 표시
+  // - 비포커스 시: 최대 8개만 표시
+  const MAX_DEFAULT_COLUMNS = 8;
+  const allColumns = columns || [];
+  const displayColumns = hasActiveColumns 
+    ? sortedFilteredColumns 
+    : allColumns.slice(0, MAX_DEFAULT_COLUMNS);
+  const remainingCount = hasActiveColumns 
+    ? 0 
+    : Math.max(0, allColumns.length - MAX_DEFAULT_COLUMNS);
+  const totalCount = allColumns.length;
+
+  // 컬럼 수 기반 높이 계산 (DOM 측정 없이)
+  // - 각 컬럼 행 높이: 약 22px (py-0.5 + text + gap-px)
+  // - 컨테이너 패딩: p-1.5 = 12px (상하 합계)
+  // - 뱃지 높이: 약 26px (py-1 + text + gap)
+  const COLUMN_ROW_HEIGHT = 22;
+  const CONTAINER_PADDING = 12;
+  const BADGE_HEIGHT = 26;
+  const MAX_HEIGHT = 200; // 뱃지 포함 가능하도록 증가
+  
+  // 뱃지가 표시될지 미리 계산 (필터/참조만, 저장은 헤더에 표시)
+  const hasFilterOrLookupBadge = referencedBy && referencedBy.some(r => r.relationType === 'filter' || r.relationType === 'lookup');
+  const hasBadge = hasFilterOrLookupBadge;
+  
+  const calculatedHeight = useMemo(() => {
+    const badgeHeight = hasBadge ? BADGE_HEIGHT : 0;
+    const rawHeight = CONTAINER_PADDING + badgeHeight + (displayColumns.length * COLUMN_ROW_HEIGHT);
+    return Math.min(rawHeight, MAX_HEIGHT);
+  }, [displayColumns.length, hasBadge]);
+  
+  // Debounce된 높이: 중간 값(늘어났다가 줄어드는 현상)을 무시하고 최종 값만 사용
+  // 듀얼 그리드에서 filterColumns와 joinColumns가 2단계로 업데이트되는 문제 해결
+  const [debouncedHeight, setDebouncedHeight] = useState(calculatedHeight);
+  
+  useEffect(() => {
+    // 50ms 내에 다시 변경되면 이전 값 무시
+    const timer = setTimeout(() => {
+      setDebouncedHeight(calculatedHeight);
+    }, 50);
+    
+    return () => clearTimeout(timer);
+  }, [calculatedHeight]);
+
+  // 저장 대상 여부
+  const hasSaveTarget = saveInfos && saveInfos.length > 0;
+
+  return (
+    <div 
+      className={`group relative flex w-[260px] flex-col overflow-visible rounded-xl border shadow-md ${
+        // 필터 관련 테이블 (마스터 또는 디테일): 보라색
+        (hasFilterRelation || isFilterSource)
+          ? "border-2 border-violet-500 ring-4 ring-violet-500/30 shadow-xl bg-violet-50"
+          // 순수 포커스 (필터 관계 없음): 초록색
+          : isFocused
+          ? "border-2 border-emerald-500 ring-4 ring-emerald-500/30 shadow-xl bg-card" 
+          // 흐리게 처리
+          : isFaded
+          ? "border-gray-200 opacity-60 bg-card"
+          // 기본
+          : "border-border hover:shadow-lg hover:ring-2 hover:ring-emerald-500/20 bg-card"
+      }`}
+      style={{
+        filter: isFaded ? "grayscale(80%)" : "none",
+        // 색상/테두리/그림자만 transition (높이 제외)
+        transition: "background-color 0.7s ease, border-color 0.7s ease, box-shadow 0.7s ease, filter 0.3s ease, opacity 0.3s ease",
+      }}
+      title={hasSaveTarget ? "저장 대상 테이블" : undefined}
+    >
+      {/* 저장 대상: 테이블 바깥 왼쪽에 띄워진 막대기 (나타나기/사라지기 애니메이션) */}
+      <div 
+        className="absolute -left-1.5 top-1 bottom-1 w-0.5 z-20 rounded-full transition-all duration-500 ease-out"
+        title={hasSaveTarget ? "저장 대상 테이블" : undefined}
+        style={{
+            background: 'linear-gradient(to bottom, transparent 0%, #f472b6 15%, #f472b6 85%, transparent 100%)',
+          opacity: hasSaveTarget ? 1 : 0,
+          transform: hasSaveTarget ? 'scaleY(1)' : 'scaleY(0)',
+          transformOrigin: 'top',
+          pointerEvents: hasSaveTarget ? 'auto' : 'none',
+        }}
+      />
+      
+      {/* Handles */}
+      {/* top target: 화면 → 메인테이블 연결용 */}
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="top"
+        className="!h-2 !w-2 !border-2 !border-background !bg-emerald-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      {/* top source: 메인테이블 → 메인테이블 연결용 (위쪽으로 나가는 선) */}
+      <Handle
+        type="source"
+        position={Position.Top}
+        id="top_source"
+        style={{ top: -4 }}
+        className="!h-2 !w-2 !border-2 !border-background !bg-orange-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      <Handle
+        type="target"
+        position={Position.Left}
+        id="left"
+        className="!h-2 !w-2 !border-2 !border-background !bg-emerald-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        id="right"
+        className="!h-2 !w-2 !border-2 !border-background !bg-emerald-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="bottom"
+        className="!h-2 !w-2 !border-2 !border-background !bg-orange-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+      {/* bottom target: 메인테이블 ← 메인테이블 연결용 (아래에서 들어오는 선) */}
+      <Handle
+        type="target"
+        position={Position.Bottom}
+        id="bottom_target"
+        style={{ bottom: -4 }}
+        className="!h-2 !w-2 !border-2 !border-background !bg-orange-500 opacity-0 transition-opacity group-hover:opacity-100"
+      />
+
+      {/* 헤더 (필터 관계: 보라색, 필터 소스: 보라색, 메인: 초록색, 기본: 슬레이트) */}
+      <div className={`flex items-center gap-2 px-3 py-1.5 text-white rounded-t-xl transition-colors duration-700 ease-in-out ${
+        isFaded ? "bg-gray-400" : (hasFilterRelation || isFilterSource) ? "bg-violet-600" : isMain ? "bg-emerald-600" : "bg-slate-500"
+      }`}>
+        <Database className="h-3.5 w-3.5 shrink-0" />
+        <div className="flex-1 min-w-0">
+          <div className="truncate text-[11px] font-semibold">{label}</div>
+          {/* 필터 관계에 따른 문구 변경 */}
+          <div className="truncate text-[9px] opacity-80">
+            {isFilterSource 
+              ? "마스터 테이블 (필터 소스)" 
+              : hasFilterRelation 
+              ? "디테일 테이블 (WHERE 조건)" 
+              : subLabel}
+          </div>
+        </div>
+        {hasActiveColumns && (
+          <span className="rounded-full bg-white/20 px-1.5 py-0.5 text-[8px] shrink-0">
+            {displayColumns.length}개 활성
+          </span>
+        )}
+      </div>
+
+      {/* 컬럼 목록 - 컴팩트하게 (부드러운 높이 전환 + 스크롤) */}
+      {/* 뱃지도 이 영역 안에 포함되어 높이 계산에 반영됨 */}
+      <div 
+        className="p-1.5 overflow-y-auto scrollbar-thin scrollbar-thumb-gray-300 scrollbar-track-transparent"
+        style={{
+          height: `${debouncedHeight}px`,
+          maxHeight: `${MAX_HEIGHT}px`,
+          // Debounce로 중간 값이 무시되므로 항상 부드러운 transition 적용 가능
+          transition: 'height 0.5s cubic-bezier(0.4, 0, 0.2, 1)',
+        }}
+      >
+        {/* 필터링/참조 관계 뱃지 (컬럼 목록 영역 안에 포함, 저장은 헤더에 표시) */}
+        {hasBadge && (() => {
+          const filterRefs = referencedBy?.filter(r => r.relationType === 'filter') || [];
+          const lookupRefs = referencedBy?.filter(r => r.relationType === 'lookup') || [];
+          
+          if (filterRefs.length === 0 && lookupRefs.length === 0) return null;
+          
+          return (
+            <div className="flex items-center gap-1.5 px-2 py-1 mb-1.5 rounded border border-slate-300 bg-slate-50 text-[9px]">
+              {/* 필터 뱃지 */}
+              {filterRefs.length > 0 && (
+                <span 
+                  className="flex items-center gap-1 rounded-full bg-violet-600 px-2 py-px text-white font-semibold shadow-sm"
+                  title={`마스터-디테일 필터링\n${filterRefs.map(r => `${r.fromTable}.${r.fromColumn || 'id'} → ${r.toColumn}`).join('\n')}`}
+                >
+                  <Link2 className="h-3 w-3" />
+                  <span>필터</span>
+                </span>
+              )}
+              {filterRefs.length > 0 && (
+                <span className="text-violet-700 font-medium truncate">
+                  {filterRefs.map(r => `${r.fromTableLabel || r.fromTable}.${r.fromColumnLabel || r.fromColumn || 'id'}`).join(', ')}
+                </span>
+              )}
+              {/* 참조 뱃지 */}
+              {lookupRefs.length > 0 && (
+                <span 
+                  className="flex items-center gap-1 rounded-full bg-amber-500 px-2 py-px text-white font-semibold shadow-sm"
+                  title={`코드 참조 (lookup)\n${lookupRefs.map(r => `${r.fromTable} → ${r.toColumn}`).join('\n')}`}
+                >
+                  {lookupRefs.length}곳 참조
+                </span>
+              )}
+            </div>
+          );
+        })()}
+        
+        {displayColumns.length > 0 ? (
+          <div className="flex flex-col gap-px transition-all duration-700 ease-in-out">
+            {displayColumns.map((col, idx) => {
+              const colOriginal = col.originalName || col.name;
+              const isJoinColumn = joinSet.has(colOriginal);
+              const isFilterColumn = filterSet.has(colOriginal);  // 서브 테이블의 필터링 FK 컬럼
+              const isHighlighted = highlightSet.has(colOriginal);
+              
+              // 필터링 참조 정보 (어떤 테이블의 어떤 컬럼에서 필터링되는지) - 서브 테이블용
+              const filterRefInfo = referencedBy?.find(
+                r => r.relationType === 'filter' && r.toColumn === colOriginal
+              );
+              
+              // 메인 테이블에서 필터 소스로 사용되는 컬럼인지 (fromColumn과 일치)
+              const isFilterSourceColumn = filterSourceSet.has(colOriginal);
+              
+              return (
+                <div
+                  key={col.name}
+                  className={`flex items-center gap-1 rounded px-1.5 py-0.5 transition-all duration-300 ${
+                    isJoinColumn 
+                      ? "bg-orange-100 border border-orange-300 shadow-sm" 
+                      : isFilterColumn || isFilterSourceColumn
+                      ? "bg-violet-100 border border-violet-300 shadow-sm"  // 필터 컬럼/필터 소스: 보라색
+                      : isHighlighted 
+                      ? "bg-blue-100 border border-blue-300 shadow-sm"
+                      : hasActiveColumns
+                      ? "bg-slate-100"
+                      : "bg-slate-50 hover:bg-slate-100"
+                  }`}
+                  style={{
+                    animation: hasActiveColumns ? `fadeIn 0.5s ease-out ${idx * 80}ms forwards` : undefined,
+                    opacity: hasActiveColumns ? 0 : 1,
+                  }}
+                >
+                  {/* PK/FK/조인/필터 아이콘 */}
+                  {isJoinColumn && <Link2 className="h-2.5 w-2.5 text-orange-500" />}
+                  {(isFilterColumn || isFilterSourceColumn) && !isJoinColumn && <Link2 className="h-2.5 w-2.5 text-violet-500" />}
+                  {!isJoinColumn && !isFilterColumn && !isFilterSourceColumn && col.isPrimaryKey && <Key className="h-2.5 w-2.5 text-amber-500" />}
+                  {!isJoinColumn && !isFilterColumn && !isFilterSourceColumn && col.isForeignKey && !col.isPrimaryKey && <Link2 className="h-2.5 w-2.5 text-blue-500" />}
+                  {!isJoinColumn && !isFilterColumn && !isFilterSourceColumn && !col.isPrimaryKey && !col.isForeignKey && <div className="w-2.5" />}
+
+                  {/* 컬럼명 */}
+                  <span className={`flex-1 truncate font-mono text-[9px] font-medium ${
+                    isJoinColumn ? "text-orange-700" 
+                    : (isFilterColumn || isFilterSourceColumn) ? "text-violet-700"
+                    : isHighlighted ? "text-blue-700" 
+                    : "text-slate-700"
+                  }`}>
+                    {col.name}
+                  </span>
+
+                  {/* 역할 태그 + 참조 관계 표시 */}
+                  {isJoinColumn && (
+                    <>
+                      {/* 조인 참조 테이블 표시 (joinColumnRefs에서) */}
+                      {joinRefMap.has(colOriginal) && (
+                        <span className="rounded bg-orange-100 px-1 text-[7px] text-orange-600">
+                          ← {joinRefMap.get(colOriginal)?.refTableLabel}
+                        </span>
+                      )}
+                      {/* 필드 매핑 참조 표시 (fieldMappingMap에서, joinRefMap에 없는 경우) */}
+                      {!joinRefMap.has(colOriginal) && fieldMappingMap.has(colOriginal) && (
+                        <span className="rounded bg-orange-100 px-1 text-[7px] text-orange-600">
+                          ← {fieldMappingMap.get(colOriginal)?.sourceDisplayName}
+                        </span>
+                      )}
+                      <span className="rounded bg-orange-200 px-1 text-[7px] text-orange-700">조인</span>
+                    </>
+                  )}
+                  {isFilterColumn && !isJoinColumn && (
+                    <span className="rounded bg-violet-200 px-1 text-[7px] text-violet-700">필터</span>
+                  )}
+                  {/* 메인 테이블에서 필터 소스로 사용되는 컬럼: "필터" + "사용" 둘 다 표시 */}
+                  {isFilterSourceColumn && !isJoinColumn && !isFilterColumn && (
+                    <>
+                      <span className="rounded bg-violet-200 px-1 text-[7px] text-violet-700">필터</span>
+                      {isHighlighted && (
+                        <span className="rounded bg-blue-200 px-1 text-[7px] text-blue-700">사용</span>
+                      )}
+                    </>
+                  )}
+                  {isHighlighted && !isJoinColumn && !isFilterColumn && !isFilterSourceColumn && (
+                    <span className="rounded bg-blue-200 px-1 text-[7px] text-blue-700">사용</span>
+                  )}
+
+                  {/* 타입 */}
+                  <span className="text-[8px] text-slate-400">{col.type}</span>
+                </div>
+              );
+            })}
+            {/* 더 많은 컬럼이 있을 경우 표시 */}
+            {remainingCount > 0 && (
+              <div className="text-center text-[8px] text-slate-400 py-0.5">
+                + {remainingCount}개 더
+              </div>
+            )}
+          </div>
+        ) : (
+          <div className="flex flex-col items-center justify-center py-2 text-muted-foreground">
+            <Database className="h-4 w-4 text-slate-300" />
+            <span className="mt-0.5 text-[8px] text-slate-400">컬럼 정보 없음</span>
+          </div>
+        )}
+      </div>
+
+      {/* 푸터 (컴팩트) */}
+      <div className="flex items-center justify-between border-t border-border bg-muted/30 px-2 py-1">
+        <span className="text-[9px] text-muted-foreground">PostgreSQL</span>
+        {columns && (
+          <span className="text-[9px] text-muted-foreground">
+            {hasActiveColumns ? `${displayColumns.length}/${totalCount}` : totalCount}개 컬럼
+          </span>
+        )}
+      </div>
+      
+      {/* CSS 애니메이션 정의 */}
+      <style jsx>{`
+        @keyframes fadeIn {
+          from {
+            opacity: 0;
+            transform: translateY(-5px);
+          }
+          to {
+            opacity: 1;
+            transform: translateY(0);
+          }
+        }
+      `}</style>
+    </div>
+  );
+};
+
+// ========== 기존 호환성 유지용 ==========
+export const LegacyScreenNode = ScreenNode;
+export const AggregateNode: React.FC<{ data: any }> = ({ data }) => {
+  return (
+    <div className="rounded-lg border-2 border-purple-300 bg-white p-3 shadow-lg">
+      <Handle type="target" position={Position.Left} id="left" className="!h-3 !w-3 !bg-purple-500" />
+      <Handle type="source" position={Position.Right} id="right" className="!h-3 !w-3 !bg-purple-500" />
+      <div className="flex items-center gap-2 text-purple-600">
+        <Table2 className="h-4 w-4" />
+        <span className="text-sm font-semibold">{data.label || "Aggregate"}</span>
+      </div>
+    </div>
+  );
+};

frontend/components/screen/ScreenRelationView.tsx

@@ -0,0 +1,296 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { ScreenDefinition } from "@/types/screen";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { Separator } from "@/components/ui/separator";
+import { 
+  Database, 
+  Monitor, 
+  ArrowRight, 
+  Link2, 
+  Table, 
+  Columns,
+  ExternalLink,
+  Layers,
+  GitBranch
+} from "lucide-react";
+import { getFieldJoins, getDataFlows, getTableRelations, FieldJoin, DataFlow, TableRelation } from "@/lib/api/screenGroup";
+import { screenApi } from "@/lib/api/screen";
+
+interface ScreenRelationViewProps {
+  screen: ScreenDefinition | null;
+}
+
+export function ScreenRelationView({ screen }: ScreenRelationViewProps) {
+  const [loading, setLoading] = useState(false);
+  const [fieldJoins, setFieldJoins] = useState<FieldJoin[]>([]);
+  const [dataFlows, setDataFlows] = useState<DataFlow[]>([]);
+  const [tableRelations, setTableRelations] = useState<TableRelation[]>([]);
+  const [layoutInfo, setLayoutInfo] = useState<any>(null);
+
+  useEffect(() => {
+    const loadRelations = async () => {
+      if (!screen) {
+        setFieldJoins([]);
+        setDataFlows([]);
+        setTableRelations([]);
+        setLayoutInfo(null);
+        return;
+      }
+
+      try {
+        setLoading(true);
+
+        // 병렬로 데이터 로드
+        const [joinsRes, flowsRes, relationsRes, layoutRes] = await Promise.all([
+          getFieldJoins(screen.screenId),
+          getDataFlows(screen.screenId),
+          getTableRelations(screen.screenId),
+          screenApi.getLayout(screen.screenId).catch(() => null),
+        ]);
+
+        if (joinsRes.success && joinsRes.data) {
+          setFieldJoins(joinsRes.data);
+        }
+        if (flowsRes.success && flowsRes.data) {
+          setDataFlows(flowsRes.data);
+        }
+        if (relationsRes.success && relationsRes.data) {
+          setTableRelations(relationsRes.data);
+        }
+        if (layoutRes) {
+          setLayoutInfo(layoutRes);
+        }
+      } catch (error) {
+        console.error("관계 정보 로드 실패:", error);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadRelations();
+  }, [screen?.screenId]);
+
+  if (!screen) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full text-center py-12">
+        <Layers className="h-16 w-16 text-muted-foreground/30 mb-4" />
+        <h3 className="text-lg font-medium text-muted-foreground mb-2">화면을 선택하세요</h3>
+        <p className="text-sm text-muted-foreground/70">
+          왼쪽 트리에서 화면을 선택하면 데이터 관계가 표시됩니다
+        </p>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center p-8">
+        <div className="text-sm text-muted-foreground">로딩 중...</div>
+      </div>
+    );
+  }
+
+  // 컴포넌트에서 사용하는 테이블 분석
+  const getUsedTables = () => {
+    const tables = new Set<string>();
+    if (screen.tableName) {
+      tables.add(screen.tableName);
+    }
+    if (layoutInfo?.components) {
+      layoutInfo.components.forEach((comp: any) => {
+        if (comp.properties?.tableName) {
+          tables.add(comp.properties.tableName);
+        }
+        if (comp.properties?.dataSource?.tableName) {
+          tables.add(comp.properties.dataSource.tableName);
+        }
+      });
+    }
+    return Array.from(tables);
+  };
+
+  const usedTables = getUsedTables();
+
+  return (
+    <div className="p-4 space-y-4 overflow-auto h-full">
+      {/* 화면 기본 정보 */}
+      <div className="flex items-start gap-4">
+        <div className="flex items-center justify-center w-12 h-12 rounded-lg bg-blue-500/10">
+          <Monitor className="h-6 w-6 text-blue-500" />
+        </div>
+        <div className="flex-1 min-w-0">
+          <h3 className="font-semibold text-lg truncate">{screen.screenName}</h3>
+          <div className="flex items-center gap-2 mt-1">
+            <Badge variant="outline">{screen.screenCode}</Badge>
+            <Badge variant="secondary">{screen.screenType}</Badge>
+          </div>
+          {screen.description && (
+            <p className="text-sm text-muted-foreground mt-2 line-clamp-2">
+              {screen.description}
+            </p>
+          )}
+        </div>
+      </div>
+
+      <Separator />
+
+      {/* 연결된 테이블 */}
+      <Card>
+        <CardHeader className="py-3 px-4">
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <Database className="h-4 w-4 text-green-500" />
+            연결된 테이블
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="px-4 pb-4 pt-0">
+          {usedTables.length > 0 ? (
+            <div className="space-y-2">
+              {usedTables.map((tableName, index) => (
+                <div
+                  key={index}
+                  className="flex items-center gap-2 p-2 rounded-md bg-muted/50"
+                >
+                  <Table className="h-4 w-4 text-muted-foreground" />
+                  <span className="text-sm font-mono">{tableName}</span>
+                  {tableName === screen.tableName && (
+                    <Badge variant="default" className="text-xs ml-auto">
+                      메인
+                    </Badge>
+                  )}
+                </div>
+              ))}
+            </div>
+          ) : (
+            <p className="text-sm text-muted-foreground">연결된 테이블이 없습니다</p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* 필드 조인 관계 */}
+      <Card>
+        <CardHeader className="py-3 px-4">
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <Link2 className="h-4 w-4 text-purple-500" />
+            필드 조인 관계
+            {fieldJoins.length > 0 && (
+              <Badge variant="secondary" className="ml-auto">{fieldJoins.length}</Badge>
+            )}
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="px-4 pb-4 pt-0">
+          {fieldJoins.length > 0 ? (
+            <div className="space-y-2">
+              {fieldJoins.map((join) => (
+                <div
+                  key={join.id}
+                  className="flex items-center gap-2 p-2 rounded-md bg-muted/50 text-sm"
+                >
+                  <div className="flex items-center gap-1">
+                    <span className="font-mono text-xs">{join.sourceTable}</span>
+                    <span className="text-muted-foreground">.</span>
+                    <span className="font-mono text-xs text-blue-600">{join.sourceColumn}</span>
+                  </div>
+                  <ArrowRight className="h-3 w-3 text-muted-foreground" />
+                  <div className="flex items-center gap-1">
+                    <span className="font-mono text-xs">{join.targetTable}</span>
+                    <span className="text-muted-foreground">.</span>
+                    <span className="font-mono text-xs text-green-600">{join.targetColumn}</span>
+                  </div>
+                  <Badge variant="outline" className="ml-auto text-xs">
+                    {join.joinType}
+                  </Badge>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <p className="text-sm text-muted-foreground">설정된 조인이 없습니다</p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* 데이터 흐름 */}
+      <Card>
+        <CardHeader className="py-3 px-4">
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <GitBranch className="h-4 w-4 text-orange-500" />
+            데이터 흐름
+            {dataFlows.length > 0 && (
+              <Badge variant="secondary" className="ml-auto">{dataFlows.length}</Badge>
+            )}
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="px-4 pb-4 pt-0">
+          {dataFlows.length > 0 ? (
+            <div className="space-y-2">
+              {dataFlows.map((flow) => (
+                <div
+                  key={flow.id}
+                  className="flex items-center gap-2 p-2 rounded-md bg-muted/50 text-sm"
+                >
+                  <Monitor className="h-4 w-4 text-blue-500" />
+                  <span className="truncate">{flow.flowName || "이름 없음"}</span>
+                  <ArrowRight className="h-3 w-3 text-muted-foreground" />
+                  <Monitor className="h-4 w-4 text-green-500" />
+                  <span className="text-muted-foreground truncate">
+                    화면 #{flow.targetScreenId}
+                  </span>
+                  <Badge variant="outline" className="ml-auto text-xs">
+                    {flow.flowType}
+                  </Badge>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <p className="text-sm text-muted-foreground">설정된 데이터 흐름이 없습니다</p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* 테이블 관계 */}
+      <Card>
+        <CardHeader className="py-3 px-4">
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <Columns className="h-4 w-4 text-cyan-500" />
+            테이블 관계
+            {tableRelations.length > 0 && (
+              <Badge variant="secondary" className="ml-auto">{tableRelations.length}</Badge>
+            )}
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="px-4 pb-4 pt-0">
+          {tableRelations.length > 0 ? (
+            <div className="space-y-2">
+              {tableRelations.map((relation) => (
+                <div
+                  key={relation.id}
+                  className="flex items-center gap-2 p-2 rounded-md bg-muted/50 text-sm"
+                >
+                  <Table className="h-4 w-4 text-muted-foreground" />
+                  <span className="font-mono text-xs">{relation.parentTable}</span>
+                  <ArrowRight className="h-3 w-3 text-muted-foreground" />
+                  <span className="font-mono text-xs">{relation.childTable}</span>
+                  <Badge variant="outline" className="ml-auto text-xs">
+                    {relation.relationType}
+                  </Badge>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <p className="text-sm text-muted-foreground">설정된 테이블 관계가 없습니다</p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* 빠른 작업 */}
+      <div className="pt-2 border-t">
+        <p className="text-xs text-muted-foreground mb-2">
+          더블클릭하면 화면 디자이너로 이동합니다
+        </p>
+      </div>
+    </div>
+  );
+}
+

frontend/components/screen/panels/DataFlowPanel.tsx

@@ -0,0 +1,463 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Textarea } from "@/components/ui/textarea";
+import { toast } from "sonner";
+import { Plus, ArrowRight, Trash2, Pencil, GitBranch, RefreshCw } from "lucide-react";
+import {
+  getDataFlows,
+  createDataFlow,
+  updateDataFlow,
+  deleteDataFlow,
+  DataFlow,
+} from "@/lib/api/screenGroup";
+
+interface DataFlowPanelProps {
+  groupId?: number;
+  screenId?: number;
+  screens?: Array<{ screen_id: number; screen_name: string }>;
+}
+
+export default function DataFlowPanel({ groupId, screenId, screens = [] }: DataFlowPanelProps) {
+  // 상태 관리
+  const [dataFlows, setDataFlows] = useState<DataFlow[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [selectedFlow, setSelectedFlow] = useState<DataFlow | null>(null);
+  const [formData, setFormData] = useState({
+    source_screen_id: 0,
+    source_action: "",
+    target_screen_id: 0,
+    target_action: "",
+    data_mapping: "",
+    flow_type: "unidirectional",
+    flow_label: "",
+    condition_expression: "",
+    is_active: "Y",
+  });
+
+  // 데이터 로드
+  const loadDataFlows = useCallback(async () => {
+    setLoading(true);
+    try {
+      const response = await getDataFlows(groupId);
+      if (response.success && response.data) {
+        setDataFlows(response.data);
+      }
+    } catch (error) {
+      console.error("데이터 흐름 로드 실패:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, [groupId]);
+
+  useEffect(() => {
+    loadDataFlows();
+  }, [loadDataFlows]);
+
+  // 모달 열기
+  const openModal = (flow?: DataFlow) => {
+    if (flow) {
+      setSelectedFlow(flow);
+      setFormData({
+        source_screen_id: flow.source_screen_id,
+        source_action: flow.source_action || "",
+        target_screen_id: flow.target_screen_id,
+        target_action: flow.target_action || "",
+        data_mapping: flow.data_mapping ? JSON.stringify(flow.data_mapping, null, 2) : "",
+        flow_type: flow.flow_type,
+        flow_label: flow.flow_label || "",
+        condition_expression: flow.condition_expression || "",
+        is_active: flow.is_active,
+      });
+    } else {
+      setSelectedFlow(null);
+      setFormData({
+        source_screen_id: screenId || 0,
+        source_action: "",
+        target_screen_id: 0,
+        target_action: "",
+        data_mapping: "",
+        flow_type: "unidirectional",
+        flow_label: "",
+        condition_expression: "",
+        is_active: "Y",
+      });
+    }
+    setIsModalOpen(true);
+  };
+
+  // 저장
+  const handleSave = async () => {
+    if (!formData.source_screen_id || !formData.target_screen_id) {
+      toast.error("소스 화면과 타겟 화면을 선택해주세요.");
+      return;
+    }
+
+    try {
+      let dataMappingJson = null;
+      if (formData.data_mapping) {
+        try {
+          dataMappingJson = JSON.parse(formData.data_mapping);
+        } catch {
+          toast.error("데이터 매핑 JSON 형식이 올바르지 않습니다.");
+          return;
+        }
+      }
+
+      const payload = {
+        group_id: groupId,
+        source_screen_id: formData.source_screen_id,
+        source_action: formData.source_action || null,
+        target_screen_id: formData.target_screen_id,
+        target_action: formData.target_action || null,
+        data_mapping: dataMappingJson,
+        flow_type: formData.flow_type,
+        flow_label: formData.flow_label || null,
+        condition_expression: formData.condition_expression || null,
+        is_active: formData.is_active,
+      };
+
+      let response;
+      if (selectedFlow) {
+        response = await updateDataFlow(selectedFlow.id, payload);
+      } else {
+        response = await createDataFlow(payload);
+      }
+
+      if (response.success) {
+        toast.success(selectedFlow ? "데이터 흐름이 수정되었습니다." : "데이터 흐름이 추가되었습니다.");
+        setIsModalOpen(false);
+        loadDataFlows();
+      } else {
+        toast.error(response.message || "저장에 실패했습니다.");
+      }
+    } catch (error) {
+      toast.error("저장 중 오류가 발생했습니다.");
+    }
+  };
+
+  // 삭제
+  const handleDelete = async (id: number) => {
+    if (!confirm("이 데이터 흐름을 삭제하시겠습니까?")) return;
+
+    try {
+      const response = await deleteDataFlow(id);
+      if (response.success) {
+        toast.success("데이터 흐름이 삭제되었습니다.");
+        loadDataFlows();
+      } else {
+        toast.error(response.message || "삭제에 실패했습니다.");
+      }
+    } catch (error) {
+      toast.error("삭제 중 오류가 발생했습니다.");
+    }
+  };
+
+  // 액션 옵션
+  const sourceActions = [
+    { value: "click", label: "클릭" },
+    { value: "submit", label: "제출" },
+    { value: "select", label: "선택" },
+    { value: "change", label: "변경" },
+    { value: "doubleClick", label: "더블클릭" },
+  ];
+
+  const targetActions = [
+    { value: "open", label: "열기" },
+    { value: "load", label: "로드" },
+    { value: "refresh", label: "새로고침" },
+    { value: "save", label: "저장" },
+    { value: "filter", label: "필터" },
+  ];
+
+  return (
+    <div className="space-y-4">
+      {/* 헤더 */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <GitBranch className="h-4 w-4 text-primary" />
+          <h3 className="text-sm font-semibold">데이터 흐름</h3>
+        </div>
+        <div className="flex items-center gap-2">
+          <Button variant="ghost" size="sm" onClick={loadDataFlows} className="h-8 w-8 p-0">
+            <RefreshCw className="h-3 w-3" />
+          </Button>
+          <Button variant="outline" size="sm" onClick={() => openModal()} className="h-8 gap-1 text-xs">
+            <Plus className="h-3 w-3" />
+            추가
+          </Button>
+        </div>
+      </div>
+
+      {/* 설명 */}
+      <p className="text-xs text-muted-foreground">
+        화면 간 데이터 전달 흐름을 정의합니다. (예: 목록 화면에서 행 클릭 시 상세 화면 열기)
+      </p>
+
+      {/* 흐름 목록 */}
+      {loading ? (
+        <div className="flex items-center justify-center py-8">
+          <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+        </div>
+      ) : dataFlows.length === 0 ? (
+        <div className="flex flex-col items-center justify-center rounded-lg border border-dashed py-8">
+          <GitBranch className="h-8 w-8 text-muted-foreground/50" />
+          <p className="mt-2 text-xs text-muted-foreground">정의된 데이터 흐름이 없습니다</p>
+        </div>
+      ) : (
+        <div className="space-y-2">
+          {dataFlows.map((flow) => (
+            <div
+              key={flow.id}
+              className="flex items-center justify-between rounded-lg border bg-card p-3 text-xs"
+            >
+              <div className="flex items-center gap-2 flex-1 min-w-0">
+                {/* 소스 화면 */}
+                <div className="flex flex-col">
+                  <span className="font-medium truncate max-w-[100px]">
+                    {flow.source_screen_name || `화면 ${flow.source_screen_id}`}
+                  </span>
+                  {flow.source_action && (
+                    <span className="text-muted-foreground">{flow.source_action}</span>
+                  )}
+                </div>
+
+                {/* 화살표 */}
+                <div className="flex items-center gap-1 text-primary">
+                  <ArrowRight className="h-4 w-4" />
+                  {flow.flow_type === "bidirectional" && (
+                    <ArrowRight className="h-4 w-4 rotate-180" />
+                  )}
+                </div>
+
+                {/* 타겟 화면 */}
+                <div className="flex flex-col">
+                  <span className="font-medium truncate max-w-[100px]">
+                    {flow.target_screen_name || `화면 ${flow.target_screen_id}`}
+                  </span>
+                  {flow.target_action && (
+                    <span className="text-muted-foreground">{flow.target_action}</span>
+                  )}
+                </div>
+
+                {/* 라벨 */}
+                {flow.flow_label && (
+                  <span className="rounded bg-muted px-2 py-0.5 text-muted-foreground">
+                    {flow.flow_label}
+                  </span>
+                )}
+              </div>
+
+              {/* 액션 버튼 */}
+              <div className="flex items-center gap-1 ml-2">
+                <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => openModal(flow)}>
+                  <Pencil className="h-3 w-3" />
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-6 w-6 text-destructive hover:text-destructive"
+                  onClick={() => handleDelete(flow.id)}
+                >
+                  <Trash2 className="h-3 w-3" />
+                </Button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* 추가/수정 모달 */}
+      <Dialog open={isModalOpen} onOpenChange={setIsModalOpen}>
+        <DialogContent className="max-w-[95vw] sm:max-w-[600px]">
+          <DialogHeader>
+            <DialogTitle className="text-base sm:text-lg">
+              {selectedFlow ? "데이터 흐름 수정" : "데이터 흐름 추가"}
+            </DialogTitle>
+            <DialogDescription className="text-xs sm:text-sm">
+              화면 간 데이터 전달 흐름을 설정합니다
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-4">
+            {/* 소스 화면 */}
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">소스 화면 *</Label>
+                <Select
+                  value={formData.source_screen_id.toString()}
+                  onValueChange={(value) => setFormData({ ...formData, source_screen_id: parseInt(value) })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue placeholder="화면 선택" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {screens.map((screen) => (
+                      <SelectItem key={screen.screen_id} value={screen.screen_id.toString()}>
+                        {screen.screen_name}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">소스 액션</Label>
+                <Select
+                  value={formData.source_action}
+                  onValueChange={(value) => setFormData({ ...formData, source_action: value })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue placeholder="액션 선택" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {sourceActions.map((action) => (
+                      <SelectItem key={action.value} value={action.value}>
+                        {action.label}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+
+            {/* 타겟 화면 */}
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">타겟 화면 *</Label>
+                <Select
+                  value={formData.target_screen_id.toString()}
+                  onValueChange={(value) => setFormData({ ...formData, target_screen_id: parseInt(value) })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue placeholder="화면 선택" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {screens.map((screen) => (
+                      <SelectItem key={screen.screen_id} value={screen.screen_id.toString()}>
+                        {screen.screen_name}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">타겟 액션</Label>
+                <Select
+                  value={formData.target_action}
+                  onValueChange={(value) => setFormData({ ...formData, target_action: value })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue placeholder="액션 선택" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {targetActions.map((action) => (
+                      <SelectItem key={action.value} value={action.value}>
+                        {action.label}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+
+            {/* 흐름 설정 */}
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">흐름 타입</Label>
+                <Select
+                  value={formData.flow_type}
+                  onValueChange={(value) => setFormData({ ...formData, flow_type: value })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="unidirectional">단방향</SelectItem>
+                    <SelectItem value="bidirectional">양방향</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">흐름 라벨</Label>
+                <Input
+                  value={formData.flow_label}
+                  onChange={(e) => setFormData({ ...formData, flow_label: e.target.value })}
+                  placeholder="예: 상세 보기"
+                  className="h-8 text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+            </div>
+
+            {/* 데이터 매핑 */}
+            <div>
+              <Label className="text-xs sm:text-sm">데이터 매핑 (JSON)</Label>
+              <Textarea
+                value={formData.data_mapping}
+                onChange={(e) => setFormData({ ...formData, data_mapping: e.target.value })}
+                placeholder='{"source_field": "target_field"}'
+                className="min-h-[80px] font-mono text-xs sm:text-sm"
+              />
+              <p className="mt-1 text-[10px] text-muted-foreground">
+                소스 화면의 필드를 타겟 화면의 필드로 매핑합니다
+              </p>
+            </div>
+
+            {/* 조건식 */}
+            <div>
+              <Label className="text-xs sm:text-sm">실행 조건 (선택)</Label>
+              <Input
+                value={formData.condition_expression}
+                onChange={(e) => setFormData({ ...formData, condition_expression: e.target.value })}
+                placeholder="예: data.status === 'active'"
+                className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+              />
+            </div>
+          </div>
+
+          <DialogFooter className="gap-2 sm:gap-0">
+            <Button
+              variant="outline"
+              onClick={() => setIsModalOpen(false)}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              취소
+            </Button>
+            <Button
+              onClick={handleSave}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              {selectedFlow ? "수정" : "추가"}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
+
+
+
+
+
+
+
+

frontend/components/screen/panels/FieldJoinPanel.tsx

@@ -0,0 +1,415 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { Textarea } from "@/components/ui/textarea";
+import { toast } from "sonner";
+import { Plus, Pencil, Trash2, Link2, Database } from "lucide-react";
+import {
+  getFieldJoins,
+  createFieldJoin,
+  updateFieldJoin,
+  deleteFieldJoin,
+  FieldJoin,
+} from "@/lib/api/screenGroup";
+
+interface FieldJoinPanelProps {
+  screenId: number;
+  componentId?: string;
+  layoutId?: number;
+}
+
+export default function FieldJoinPanel({ screenId, componentId, layoutId }: FieldJoinPanelProps) {
+  // 상태 관리
+  const [fieldJoins, setFieldJoins] = useState<FieldJoin[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [selectedJoin, setSelectedJoin] = useState<FieldJoin | null>(null);
+  const [formData, setFormData] = useState({
+    field_name: "",
+    save_table: "",
+    save_column: "",
+    join_table: "",
+    join_column: "",
+    display_column: "",
+    join_type: "LEFT",
+    filter_condition: "",
+    sort_column: "",
+    sort_direction: "ASC",
+    is_active: "Y",
+  });
+
+  // 데이터 로드
+  const loadFieldJoins = useCallback(async () => {
+    if (!screenId) return;
+    
+    setLoading(true);
+    try {
+      const response = await getFieldJoins(screenId);
+      if (response.success && response.data) {
+        // 현재 컴포넌트에 해당하는 조인만 필터링
+        const filtered = componentId 
+          ? response.data.filter(join => join.component_id === componentId)
+          : response.data;
+        setFieldJoins(filtered);
+      }
+    } catch (error) {
+      console.error("필드 조인 로드 실패:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, [screenId, componentId]);
+
+  useEffect(() => {
+    loadFieldJoins();
+  }, [loadFieldJoins]);
+
+  // 모달 열기
+  const openModal = (join?: FieldJoin) => {
+    if (join) {
+      setSelectedJoin(join);
+      setFormData({
+        field_name: join.field_name || "",
+        save_table: join.save_table,
+        save_column: join.save_column,
+        join_table: join.join_table,
+        join_column: join.join_column,
+        display_column: join.display_column,
+        join_type: join.join_type,
+        filter_condition: join.filter_condition || "",
+        sort_column: join.sort_column || "",
+        sort_direction: join.sort_direction || "ASC",
+        is_active: join.is_active,
+      });
+    } else {
+      setSelectedJoin(null);
+      setFormData({
+        field_name: "",
+        save_table: "",
+        save_column: "",
+        join_table: "",
+        join_column: "",
+        display_column: "",
+        join_type: "LEFT",
+        filter_condition: "",
+        sort_column: "",
+        sort_direction: "ASC",
+        is_active: "Y",
+      });
+    }
+    setIsModalOpen(true);
+  };
+
+  // 저장
+  const handleSave = async () => {
+    if (!formData.save_table || !formData.save_column || !formData.join_table || !formData.join_column || !formData.display_column) {
+      toast.error("필수 필드를 모두 입력해주세요.");
+      return;
+    }
+
+    try {
+      const payload = {
+        screen_id: screenId,
+        layout_id: layoutId,
+        component_id: componentId,
+        ...formData,
+      };
+
+      let response;
+      if (selectedJoin) {
+        response = await updateFieldJoin(selectedJoin.id, payload);
+      } else {
+        response = await createFieldJoin(payload);
+      }
+
+      if (response.success) {
+        toast.success(selectedJoin ? "조인 설정이 수정되었습니다." : "조인 설정이 추가되었습니다.");
+        setIsModalOpen(false);
+        loadFieldJoins();
+      } else {
+        toast.error(response.message || "저장에 실패했습니다.");
+      }
+    } catch (error) {
+      toast.error("저장 중 오류가 발생했습니다.");
+    }
+  };
+
+  // 삭제
+  const handleDelete = async (id: number) => {
+    if (!confirm("이 조인 설정을 삭제하시겠습니까?")) return;
+
+    try {
+      const response = await deleteFieldJoin(id);
+      if (response.success) {
+        toast.success("조인 설정이 삭제되었습니다.");
+        loadFieldJoins();
+      } else {
+        toast.error(response.message || "삭제에 실패했습니다.");
+      }
+    } catch (error) {
+      toast.error("삭제 중 오류가 발생했습니다.");
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      {/* 헤더 */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Link2 className="h-4 w-4 text-primary" />
+          <h3 className="text-sm font-semibold">필드 조인 설정</h3>
+        </div>
+        <Button variant="outline" size="sm" onClick={() => openModal()} className="h-8 gap-1 text-xs">
+          <Plus className="h-3 w-3" />
+          추가
+        </Button>
+      </div>
+
+      {/* 설명 */}
+      <p className="text-xs text-muted-foreground">
+        이 필드가 다른 테이블의 값을 참조하여 표시할 때 조인 설정을 추가하세요.
+      </p>
+
+      {/* 조인 목록 */}
+      {loading ? (
+        <div className="flex items-center justify-center py-8">
+          <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+        </div>
+      ) : fieldJoins.length === 0 ? (
+        <div className="flex flex-col items-center justify-center rounded-lg border border-dashed py-8">
+          <Database className="h-8 w-8 text-muted-foreground/50" />
+          <p className="mt-2 text-xs text-muted-foreground">설정된 조인이 없습니다</p>
+        </div>
+      ) : (
+        <div className="rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow className="bg-muted/50">
+                <TableHead className="h-8 text-xs">저장 테이블.컬럼</TableHead>
+                <TableHead className="h-8 text-xs">조인 테이블.컬럼</TableHead>
+                <TableHead className="h-8 text-xs">표시 컬럼</TableHead>
+                <TableHead className="h-8 w-[60px] text-xs">관리</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {fieldJoins.map((join) => (
+                <TableRow key={join.id} className="text-xs">
+                  <TableCell className="py-2">
+                    <span className="font-mono">{join.save_table}.{join.save_column}</span>
+                  </TableCell>
+                  <TableCell className="py-2">
+                    <span className="font-mono">{join.join_table}.{join.join_column}</span>
+                  </TableCell>
+                  <TableCell className="py-2">
+                    <span className="font-mono">{join.display_column}</span>
+                  </TableCell>
+                  <TableCell className="py-2">
+                    <div className="flex items-center gap-1">
+                      <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => openModal(join)}>
+                        <Pencil className="h-3 w-3" />
+                      </Button>
+                      <Button 
+                        variant="ghost" 
+                        size="icon" 
+                        className="h-6 w-6 text-destructive hover:text-destructive" 
+                        onClick={() => handleDelete(join.id)}
+                      >
+                        <Trash2 className="h-3 w-3" />
+                      </Button>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+
+      {/* 추가/수정 모달 */}
+      <Dialog open={isModalOpen} onOpenChange={setIsModalOpen}>
+        <DialogContent className="max-w-[95vw] sm:max-w-[600px]">
+          <DialogHeader>
+            <DialogTitle className="text-base sm:text-lg">
+              {selectedJoin ? "조인 설정 수정" : "조인 설정 추가"}
+            </DialogTitle>
+            <DialogDescription className="text-xs sm:text-sm">
+              필드가 참조할 테이블과 컬럼을 설정합니다
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-4">
+            {/* 필드명 */}
+            <div>
+              <Label className="text-xs sm:text-sm">필드명</Label>
+              <Input
+                value={formData.field_name}
+                onChange={(e) => setFormData({ ...formData, field_name: e.target.value })}
+                placeholder="화면에 표시될 필드명"
+                className="h-8 text-xs sm:h-10 sm:text-sm"
+              />
+            </div>
+
+            {/* 저장 테이블/컬럼 */}
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">저장 테이블 *</Label>
+                <Input
+                  value={formData.save_table}
+                  onChange={(e) => setFormData({ ...formData, save_table: e.target.value })}
+                  placeholder="예: work_orders"
+                  className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">저장 컬럼 *</Label>
+                <Input
+                  value={formData.save_column}
+                  onChange={(e) => setFormData({ ...formData, save_column: e.target.value })}
+                  placeholder="예: item_code"
+                  className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+            </div>
+
+            {/* 조인 테이블/컬럼 */}
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">조인 테이블 *</Label>
+                <Input
+                  value={formData.join_table}
+                  onChange={(e) => setFormData({ ...formData, join_table: e.target.value })}
+                  placeholder="예: item_mng"
+                  className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">조인 컬럼 *</Label>
+                <Input
+                  value={formData.join_column}
+                  onChange={(e) => setFormData({ ...formData, join_column: e.target.value })}
+                  placeholder="예: id"
+                  className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+            </div>
+
+            {/* 표시 컬럼 */}
+            <div>
+              <Label className="text-xs sm:text-sm">표시 컬럼 *</Label>
+              <Input
+                value={formData.display_column}
+                onChange={(e) => setFormData({ ...formData, display_column: e.target.value })}
+                placeholder="예: item_name (화면에 표시될 컬럼)"
+                className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+              />
+            </div>
+
+            {/* 조인 타입/정렬 */}
+            <div className="grid grid-cols-3 gap-4">
+              <div>
+                <Label className="text-xs sm:text-sm">조인 타입</Label>
+                <Select
+                  value={formData.join_type}
+                  onValueChange={(value) => setFormData({ ...formData, join_type: value })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="LEFT">LEFT JOIN</SelectItem>
+                    <SelectItem value="INNER">INNER JOIN</SelectItem>
+                    <SelectItem value="RIGHT">RIGHT JOIN</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">정렬 컬럼</Label>
+                <Input
+                  value={formData.sort_column}
+                  onChange={(e) => setFormData({ ...formData, sort_column: e.target.value })}
+                  placeholder="예: name"
+                  className="h-8 font-mono text-xs sm:h-10 sm:text-sm"
+                />
+              </div>
+              <div>
+                <Label className="text-xs sm:text-sm">정렬 방향</Label>
+                <Select
+                  value={formData.sort_direction}
+                  onValueChange={(value) => setFormData({ ...formData, sort_direction: value })}
+                >
+                  <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="ASC">오름차순</SelectItem>
+                    <SelectItem value="DESC">내림차순</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+
+            {/* 필터 조건 */}
+            <div>
+              <Label className="text-xs sm:text-sm">필터 조건 (선택)</Label>
+              <Textarea
+                value={formData.filter_condition}
+                onChange={(e) => setFormData({ ...formData, filter_condition: e.target.value })}
+                placeholder="예: is_active = 'Y'"
+                className="min-h-[60px] font-mono text-xs sm:text-sm"
+              />
+            </div>
+          </div>
+
+          <DialogFooter className="gap-2 sm:gap-0">
+            <Button
+              variant="outline"
+              onClick={() => setIsModalOpen(false)}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              취소
+            </Button>
+            <Button
+              onClick={handleSave}
+              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
+            >
+              {selectedJoin ? "수정" : "추가"}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
+
+
+
+
+
+
+
+

frontend/lib/api/entityJoin.ts

@@ -83,15 +83,26 @@ export const entityJoinApi = {
         keepStrategy: "latest" | "earliest" | "base_price" | "current_date";
         sortColumn?: string;
       }; // 🆕 중복 제거 설정
+      companyCodeOverride?: string; // 🆕 프리뷰용 회사 코드 오버라이드 (최고 관리자만 사용 가능)
     } = {},
   ): Promise<EntityJoinResponse> => {
     // 🔒 멀티테넌시: company_code 자동 필터링 활성화
-    const autoFilter = {
+    const autoFilter: {
+      enabled: boolean;
+      filterColumn: string;
+      userField: string;
+      companyCodeOverride?: string;
+    } = {
       enabled: true,
       filterColumn: "company_code",
       userField: "companyCode",
     };
 
+    // 🆕 프리뷰 모드에서 회사 코드 오버라이드 (최고 관리자만 백엔드에서 허용)
+    if (params.companyCodeOverride) {
+      autoFilter.companyCodeOverride = params.companyCodeOverride;
+    }
+
     const response = await apiClient.get(`/table-management/tables/${tableName}/data-with-joins`, {
       params: {
         page: params.page,
@@ -102,7 +113,7 @@ export const entityJoinApi = {
         search: params.search ? JSON.stringify(params.search) : undefined,
         additionalJoinColumns: params.additionalJoinColumns ? JSON.stringify(params.additionalJoinColumns) : undefined,
         screenEntityConfigs: params.screenEntityConfigs ? JSON.stringify(params.screenEntityConfigs) : undefined, // 🎯 화면별 엔티티 설정
-        autoFilter: JSON.stringify(autoFilter), // 🔒 멀티테넌시 필터링
+        autoFilter: JSON.stringify(autoFilter), // 🔒 멀티테넌시 필터링 (오버라이드 포함)
         dataFilter: params.dataFilter ? JSON.stringify(params.dataFilter) : undefined, // 🆕 데이터 필터
         excludeFilter: params.excludeFilter ? JSON.stringify(params.excludeFilter) : undefined, // 🆕 제외 필터
         deduplication: params.deduplication ? JSON.stringify(params.deduplication) : undefined, // 🆕 중복 제거 설정

frontend/lib/api/screenGroup.ts

@@ -0,0 +1,500 @@
+/**
+ * 화면 그룹 관리 API 클라이언트
+ * - 화면 그룹 (screen_groups)
+ * - 화면-그룹 연결 (screen_group_screens)
+ * - 필드 조인 (screen_field_joins)
+ * - 데이터 흐름 (screen_data_flows)
+ * - 화면-테이블 관계 (screen_table_relations)
+ */
+
+import { apiClient } from "./client";
+
+// ============================================================
+// 타입 정의
+// ============================================================
+
+export interface ScreenGroup {
+  id: number;
+  group_name: string;
+  group_code: string;
+  main_table_name?: string;
+  description?: string;
+  icon?: string;
+  display_order: number;
+  is_active: string;
+  company_code: string;
+  created_date?: string;
+  updated_date?: string;
+  writer?: string;
+  screen_count?: number;
+  screens?: ScreenGroupScreen[];
+  parent_group_id?: number | null;  // 상위 그룹 ID
+  group_level?: number;             // 그룹 레벨 (0: 대분류, 1: 중분류, 2: 소분류 ...)
+  hierarchy_path?: string;          // 계층 경로
+}
+
+export interface ScreenGroupScreen {
+  id: number;
+  group_id: number;
+  screen_id: number;
+  screen_name?: string;
+  screen_role: string;
+  display_order: number;
+  is_default: string;
+  company_code: string;
+}
+
+export interface FieldJoin {
+  id: number;
+  screen_id: number;
+  layout_id?: number;
+  component_id?: string;
+  field_name?: string;
+  save_table: string;
+  save_column: string;
+  join_table: string;
+  join_column: string;
+  display_column: string;
+  join_type: string;
+  filter_condition?: string;
+  sort_column?: string;
+  sort_direction?: string;
+  is_active: string;
+  save_table_label?: string;
+  join_table_label?: string;
+}
+
+export interface DataFlow {
+  id: number;
+  group_id?: number;
+  source_screen_id: number;
+  source_action?: string;
+  target_screen_id: number;
+  target_action?: string;
+  data_mapping?: Record<string, any>;
+  flow_type: string;
+  flow_label?: string;
+  condition_expression?: string;
+  is_active: string;
+  source_screen_name?: string;
+  target_screen_name?: string;
+  group_name?: string;
+}
+
+export interface TableRelation {
+  id: number;
+  group_id?: number;
+  screen_id: number;
+  table_name: string;
+  relation_type: string;
+  crud_operations: string;
+  description?: string;
+  is_active: string;
+  screen_name?: string;
+  group_name?: string;
+  table_label?: string;
+}
+
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  message?: string;
+  error?: string;
+  total?: number;
+  page?: number;
+  size?: number;
+  totalPages?: number;
+}
+
+
+// ============================================================
+// 화면 그룹 (screen_groups) API
+// ============================================================
+
+export async function getScreenGroups(params?: {
+  page?: number;
+  size?: number;
+  searchTerm?: string;
+}): Promise<ApiResponse<ScreenGroup[]>> {
+  try {
+    const queryParams = new URLSearchParams();
+    if (params?.page) queryParams.append("page", params.page.toString());
+    if (params?.size) queryParams.append("size", params.size.toString());
+    if (params?.searchTerm) queryParams.append("searchTerm", params.searchTerm);
+
+    const response = await apiClient.get(`/screen-groups/groups?${queryParams.toString()}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function getScreenGroup(id: number): Promise<ApiResponse<ScreenGroup>> {
+  try {
+    const response = await apiClient.get(`/screen-groups/groups/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function createScreenGroup(data: Partial<ScreenGroup>): Promise<ApiResponse<ScreenGroup>> {
+  try {
+    const response = await apiClient.post("/screen-groups/groups", data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateScreenGroup(id: number, data: Partial<ScreenGroup>): Promise<ApiResponse<ScreenGroup>> {
+  try {
+    const response = await apiClient.put(`/screen-groups/groups/${id}`, data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function deleteScreenGroup(id: number): Promise<ApiResponse<void>> {
+  try {
+    const response = await apiClient.delete(`/screen-groups/groups/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+
+// ============================================================
+// 화면-그룹 연결 (screen_group_screens) API
+// ============================================================
+
+export async function addScreenToGroup(data: {
+  group_id: number;
+  screen_id: number;
+  screen_role?: string;
+  display_order?: number;
+  is_default?: string;
+}): Promise<ApiResponse<ScreenGroupScreen>> {
+  try {
+    const response = await apiClient.post("/screen-groups/group-screens", data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateScreenInGroup(id: number, data: {
+  screen_role?: string;
+  display_order?: number;
+  is_default?: string;
+}): Promise<ApiResponse<ScreenGroupScreen>> {
+  try {
+    const response = await apiClient.put(`/screen-groups/group-screens/${id}`, data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function removeScreenFromGroup(id: number): Promise<ApiResponse<void>> {
+  try {
+    const response = await apiClient.delete(`/screen-groups/group-screens/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+
+// ============================================================
+// 필드 조인 (screen_field_joins) API
+// ============================================================
+
+export async function getFieldJoins(screenId?: number): Promise<ApiResponse<FieldJoin[]>> {
+  try {
+    const queryParams = screenId ? `?screen_id=${screenId}` : "";
+    const response = await apiClient.get(`/screen-groups/field-joins${queryParams}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function createFieldJoin(data: Partial<FieldJoin>): Promise<ApiResponse<FieldJoin>> {
+  try {
+    const response = await apiClient.post("/screen-groups/field-joins", data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateFieldJoin(id: number, data: Partial<FieldJoin>): Promise<ApiResponse<FieldJoin>> {
+  try {
+    const response = await apiClient.put(`/screen-groups/field-joins/${id}`, data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function deleteFieldJoin(id: number): Promise<ApiResponse<void>> {
+  try {
+    const response = await apiClient.delete(`/screen-groups/field-joins/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+
+// ============================================================
+// 데이터 흐름 (screen_data_flows) API
+// ============================================================
+
+export async function getDataFlows(params?: { groupId?: number; sourceScreenId?: number }): Promise<ApiResponse<DataFlow[]>> {
+  try {
+    const queryParts: string[] = [];
+    if (params?.groupId) {
+      queryParts.push(`group_id=${params.groupId}`);
+    }
+    if (params?.sourceScreenId) {
+      queryParts.push(`source_screen_id=${params.sourceScreenId}`);
+    }
+    const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
+    const response = await apiClient.get(`/screen-groups/data-flows${queryString}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function createDataFlow(data: Partial<DataFlow>): Promise<ApiResponse<DataFlow>> {
+  try {
+    const response = await apiClient.post("/screen-groups/data-flows", data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateDataFlow(id: number, data: Partial<DataFlow>): Promise<ApiResponse<DataFlow>> {
+  try {
+    const response = await apiClient.put(`/screen-groups/data-flows/${id}`, data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function deleteDataFlow(id: number): Promise<ApiResponse<void>> {
+  try {
+    const response = await apiClient.delete(`/screen-groups/data-flows/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+
+// ============================================================
+// 화면-테이블 관계 (screen_table_relations) API
+// ============================================================
+
+export async function getTableRelations(params?: {
+  screen_id?: number;
+  group_id?: number;
+}): Promise<ApiResponse<TableRelation[]>> {
+  try {
+    const queryParams = new URLSearchParams();
+    if (params?.screen_id) queryParams.append("screen_id", params.screen_id.toString());
+    if (params?.group_id) queryParams.append("group_id", params.group_id.toString());
+
+    const response = await apiClient.get(`/screen-groups/table-relations?${queryParams.toString()}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function createTableRelation(data: Partial<TableRelation>): Promise<ApiResponse<TableRelation>> {
+  try {
+    const response = await apiClient.post("/screen-groups/table-relations", data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function updateTableRelation(id: number, data: Partial<TableRelation>): Promise<ApiResponse<TableRelation>> {
+  try {
+    const response = await apiClient.put(`/screen-groups/table-relations/${id}`, data);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+export async function deleteTableRelation(id: number): Promise<ApiResponse<void>> {
+  try {
+    const response = await apiClient.delete(`/screen-groups/table-relations/${id}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+
+// ============================================================
+// 화면 레이아웃 요약 (미리보기용) API
+// ============================================================
+
+// 레이아웃 아이템 (미니어처 렌더링용)
+export interface LayoutItem {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  componentKind: string; // 정확한 컴포넌트 종류 (table-list, button-primary 등)
+  widgetType: string; // 일반적인 위젯 타입 (button, text 등)
+  label?: string;
+  bindField?: string; // 바인딩된 필드명 (컬럼명)
+  usedColumns?: string[]; // 이 컴포넌트에서 사용하는 컬럼 목록
+  joinColumns?: string[]; // 이 컴포넌트에서 조인 컬럼 목록 (isEntityJoin=true)
+}
+
+export interface ScreenLayoutSummary {
+  screenId: number;
+  screenType: 'form' | 'grid' | 'dashboard' | 'action';
+  widgetCounts: Record<string, number>;
+  totalComponents: number;
+  // 미니어처 렌더링용 레이아웃 데이터
+  layoutItems: LayoutItem[];
+  canvasWidth: number;
+  canvasHeight: number;
+}
+
+// 단일 화면 레이아웃 요약 조회
+export async function getScreenLayoutSummary(screenId: number): Promise<ApiResponse<ScreenLayoutSummary>> {
+  try {
+    const response = await apiClient.get(`/screen-groups/layout-summary/${screenId}`);
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+// 여러 화면 레이아웃 요약 일괄 조회
+export async function getMultipleScreenLayoutSummary(
+  screenIds: number[]
+): Promise<ApiResponse<Record<number, ScreenLayoutSummary>>> {
+  try {
+    const response = await apiClient.post("/screen-groups/layout-summary/batch", { screenIds });
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+
+// 필드 매핑 정보 타입
+export interface FieldMappingInfo {
+  sourceTable?: string;        // 연관 테이블명 (parentDataMapping에서 사용)
+  sourceField: string;
+  targetField: string;
+  sourceDisplayName?: string;  // 메인 테이블 한글 컬럼명
+  targetDisplayName?: string;  // 서브 테이블 한글 컬럼명
+}
+
+// 서브 테이블 정보 타입
+export interface SubTableInfo {
+  tableName: string;
+  tableLabel?: string;                        // 테이블 한글명
+  componentType: string;
+  relationType: 'lookup' | 'source' | 'join' | 'reference' | 'parentMapping' | 'rightPanelRelation';
+  fieldMappings?: FieldMappingInfo[];
+  filterColumns?: string[];                   // 필터링에 사용되는 컬럼 목록
+  // rightPanelRelation에서 추가 정보 (관계 유형 추론용)
+  originalRelationType?: 'join' | 'detail';  // 원본 relation.type
+  foreignKey?: string;                        // 디테일 테이블의 FK 컬럼
+  leftColumn?: string;                        // 마스터 테이블의 선택 기준 컬럼
+  // rightPanel.columns에서 외부 테이블 참조 정보
+  joinedTables?: string[];                    // 참조하는 외부 테이블들 (예: ['customer_mng'])
+  joinColumns?: string[];                     // 외부 테이블과 조인하는 FK 컬럼들 (예: ['customer_id'])
+  joinColumnRefs?: Array<{                    // FK 컬럼 참조 정보 (어떤 테이블.컬럼에서 오는지)
+    column: string;                           // FK 컬럼명 (예: 'customer_id')
+    columnLabel: string;                      // FK 컬럼 한글명 (예: '거래처 ID')
+    refTable: string;                         // 참조 테이블 (예: 'customer_mng')
+    refTableLabel: string;                    // 참조 테이블 한글명 (예: '거래처 관리')
+    refColumn: string;                        // 참조 컬럼 (예: 'customer_code')
+  }>;
+}
+
+// 시각적 관계 유형 (시각화에서 사용)
+export type VisualRelationType = 'filter' | 'hierarchy' | 'lookup' | 'mapping' | 'join';
+
+// 관계 유형 추론 함수
+export function inferVisualRelationType(subTable: SubTableInfo): VisualRelationType {
+  // 1. split-panel-layout의 rightPanel.relation
+  if (subTable.relationType === 'rightPanelRelation') {
+    // 원본 relation.type 기반 구분
+    if (subTable.originalRelationType === 'detail') {
+      return 'hierarchy';  // 부모-자식 계층 구조 (같은 테이블 자기 참조)
+    }
+    return 'filter';  // 마스터-디테일 필터링
+  }
+  
+  // 2. selected-items-detail-input의 parentDataMapping
+  // parentDataMapping은 FK 관계를 정의하므로 조인으로 분류
+  if (subTable.relationType === 'parentMapping') {
+    return 'join';  // FK 조인 (sourceTable.sourceField → targetTable.targetField)
+  }
+  
+  // 3. column_labels.reference_table
+  if (subTable.relationType === 'reference') {
+    return 'join';  // 실제 엔티티 조인 (LEFT JOIN 등)
+  }
+  
+  // 4. autocomplete, entity-search
+  if (subTable.relationType === 'lookup') {
+    return 'lookup';  // 코드→명칭 변환
+  }
+  
+  // 5. 기타 (source, join 등)
+  return 'join';
+}
+
+// 저장 테이블 정보 타입
+export interface SaveTableInfo {
+  tableName: string;
+  saveType: 'save' | 'edit' | 'delete' | 'transferData';
+  componentType: string;
+  isMainTable: boolean;
+  mappingRules?: Array<{
+    sourceField: string;
+    targetField: string;
+    transform?: string;
+  }>;
+}
+
+export interface ScreenSubTablesData {
+  screenId: number;
+  screenName: string;
+  mainTable: string;
+  subTables: SubTableInfo[];
+  saveTables?: SaveTableInfo[];  // 저장 대상 테이블 목록
+}
+
+// 여러 화면의 서브 테이블 정보 조회 (메인 테이블 → 서브 테이블 관계)
+export async function getScreenSubTables(
+  screenIds: number[]
+): Promise<ApiResponse<Record<number, ScreenSubTablesData>>> {
+  try {
+    const response = await apiClient.post("/screen-groups/sub-tables/batch", { screenIds });
+    return response.data;
+  } catch (error: any) {
+    return { success: false, error: error.message };
+  }
+}
+

frontend/lib/registry/components/table-list/TableListComponent.tsx

@@ -212,6 +212,8 @@ export interface TableListComponentProps {
   // 탭 관련 정보 (탭 내부의 테이블에서 사용)
   parentTabId?: string; // 부모 탭 ID
   parentTabsComponentId?: string; // 부모 탭 컴포넌트 ID
+  // 🆕 프리뷰용 회사 코드 (DynamicComponentRenderer에서 전달, 최고 관리자만 오버라이드 가능)
+  companyCode?: string;
 }
 
 // ========================================
@@ -239,6 +241,7 @@ export const TableListComponent: React.FC<TableListComponentProps> = ({
   screenId,
   parentTabId,
   parentTabsComponentId,
+  companyCode,
 }) => {
   // ========================================
   // 설정 및 스타일
@@ -1793,6 +1796,7 @@ export const TableListComponent: React.FC<TableListComponentProps> = ({
           screenEntityConfigs: Object.keys(screenEntityConfigs).length > 0 ? screenEntityConfigs : undefined, // 🎯 화면별 엔티티 설정 전달
           dataFilter: tableConfig.dataFilter, // 🆕 데이터 필터 전달
           excludeFilter: excludeFilterParam, // 🆕 제외 필터 전달
+          companyCodeOverride: companyCode, // 🆕 프리뷰용 회사 코드 오버라이드 (최고 관리자만)
         });
 
         // 실제 데이터의 item_number만 추출하여 중복 확인
@@ -1863,6 +1867,8 @@ export const TableListComponent: React.FC<TableListComponentProps> = ({
     // 🆕 RelatedDataButtons 필터 추가
     relatedButtonFilter,
     isRelatedButtonTarget,
+    // 🆕 프리뷰용 회사 코드 오버라이드
+    companyCode,
   ]);
 
   const fetchTableDataDebounced = useCallback(

frontend/package-lock.json

@@ -81,6 +81,7 @@
         "react-resizable-panels": "^3.0.6",
         "react-webcam": "^7.2.0",
         "react-window": "^2.1.0",
+        "react-zoom-pan-pinch": "^3.7.0",
         "reactflow": "^11.11.4",
         "recharts": "^3.2.1",
         "sheetjs-style": "^0.15.8",
@@ -256,6 +257,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=18"
       },
@@ -297,6 +299,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -330,6 +333,7 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -2632,6 +2636,7 @@
       "resolved": "https://registry.npmjs.org/@react-three/fiber/-/fiber-9.4.0.tgz",
       "integrity": "sha512-k4iu1R6e5D54918V4sqmISUkI5OgTw3v7/sDRKEC632Wd5g2WBtUS5gyG63X0GJO/HZUj1tsjSXfyzwrUHZl1g==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/runtime": "^7.17.8",
         "@types/react-reconciler": "^0.32.0",
@@ -3285,6 +3290,7 @@
       "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.6.tgz",
       "integrity": "sha512-gB1sljYjcobZKxjPbKSa31FUTyr+ROaBdoH+wSSs9Dk+yDCmMs+TkTV3PybRRVLC7ax7q0erJ9LvRWnMktnRAw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@tanstack/query-core": "5.90.6"
       },
@@ -3352,6 +3358,7 @@
       "resolved": "https://registry.npmjs.org/@tiptap/core/-/core-2.27.1.tgz",
       "integrity": "sha512-nkerkl8syHj44ZzAB7oA2GPmmZINKBKCa79FuNvmGJrJ4qyZwlkDzszud23YteFZEytbc87kVd/fP76ROS6sLg==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/ueberdosis"
@@ -3665,6 +3672,7 @@
       "resolved": "https://registry.npmjs.org/@tiptap/pm/-/pm-2.27.1.tgz",
       "integrity": "sha512-ijKo3+kIjALthYsnBmkRXAuw2Tswd9gd7BUR5OMfIcjGp8v576vKxOxrRfuYiUM78GPt//P0sVc1WV82H5N0PQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "prosemirror-changeset": "^2.3.0",
         "prosemirror-collab": "^1.3.1",
@@ -6165,6 +6173,7 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz",
       "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "csstype": "^3.0.2"
       }
@@ -6175,6 +6184,7 @@
       "integrity": "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==",
       "devOptional": true,
       "license": "MIT",
+      "peer": true,
       "peerDependencies": {
         "@types/react": "^19.2.0"
       }
@@ -6208,6 +6218,7 @@
       "resolved": "https://registry.npmjs.org/@types/three/-/three-0.180.0.tgz",
       "integrity": "sha512-ykFtgCqNnY0IPvDro7h+9ZeLY+qjgUWv+qEvUt84grhenO60Hqd4hScHE7VTB9nOQ/3QM8lkbNE+4vKjEpUxKg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@dimforge/rapier3d-compat": "~0.12.0",
         "@tweenjs/tween.js": "~23.1.3",
@@ -6290,6 +6301,7 @@
       "integrity": "sha512-BnOroVl1SgrPLywqxyqdJ4l3S2MsKVLDVxZvjI1Eoe8ev2r3kGDo+PcMihNmDE+6/KjkTubSJnmqGZZjQSBq/g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.46.2",
         "@typescript-eslint/types": "8.46.2",
@@ -6922,6 +6934,7 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -8072,7 +8085,8 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
       "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/d3": {
       "version": "7.9.0",
@@ -8394,6 +8408,7 @@
       "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
       "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
       "license": "ISC",
+      "peer": true,
       "engines": {
         "node": ">=12"
       }
@@ -9153,6 +9168,7 @@
       "integrity": "sha512-iy2GE3MHrYTL5lrCtMZ0X1KLEKKUjmK0kzwcnefhR66txcEmXZD2YWgR5GNdcEwkNx3a0siYkSvl0vIC+Svjmg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -9241,6 +9257,7 @@
       "integrity": "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "eslint-config-prettier": "bin/cli.js"
       },
@@ -9342,6 +9359,7 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -10492,6 +10510,7 @@
       "resolved": "https://registry.npmjs.org/immer/-/immer-10.2.0.tgz",
       "integrity": "sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "type": "opencollective",
         "url": "https://opencollective.com/immer"
@@ -11273,7 +11292,8 @@
       "version": "1.9.4",
       "resolved": "https://registry.npmjs.org/leaflet/-/leaflet-1.9.4.tgz",
       "integrity": "sha512-nxS1ynzJOmOlHp+iL3FyWqK89GtNL8U8rvlMOsQdTTssxZwCXh8N2NB3GDQOL+YR3XnWyZAxwQixURb+FA74PA==",
-      "license": "BSD-2-Clause"
+      "license": "BSD-2-Clause",
+      "peer": true
     },
     "node_modules/levn": {
       "version": "0.4.1",
@@ -12572,6 +12592,7 @@
       "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -12867,6 +12888,7 @@
       "resolved": "https://registry.npmjs.org/prosemirror-model/-/prosemirror-model-1.25.4.tgz",
       "integrity": "sha512-PIM7E43PBxKce8OQeezAs9j4TP+5yDpZVbuurd1h5phUxEKIu+G2a+EUZzIC5nS1mJktDJWzbqS23n1tsAf5QA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "orderedmap": "^2.0.0"
       }
@@ -12896,6 +12918,7 @@
       "resolved": "https://registry.npmjs.org/prosemirror-state/-/prosemirror-state-1.4.4.tgz",
       "integrity": "sha512-6jiYHH2CIGbCfnxdHbXZ12gySFY/fz/ulZE333G6bPqIZ4F+TXo9ifiR86nAHpWnfoNjOb3o5ESi7J8Uz1jXHw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "prosemirror-model": "^1.0.0",
         "prosemirror-transform": "^1.0.0",
@@ -12944,6 +12967,7 @@
       "resolved": "https://registry.npmjs.org/prosemirror-view/-/prosemirror-view-1.41.4.tgz",
       "integrity": "sha512-WkKgnyjNncri03Gjaz3IFWvCAE94XoiEgvtr0/r2Xw7R8/IjK3sKLSiDoCHWcsXSAinVaKlGRZDvMCsF1kbzjA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "prosemirror-model": "^1.20.0",
         "prosemirror-state": "^1.0.0",
@@ -13070,6 +13094,7 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.1.0.tgz",
       "integrity": "sha512-FS+XFBNvn3GTAWq26joslQgWNoFu08F4kl0J4CgdNKADkdSGXQyTCnKteIAJy96Br6YbpEU1LSzV5dYtjMkMDg==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -13139,6 +13164,7 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.1.0.tgz",
       "integrity": "sha512-Xs1hdnE+DyKgeHJeJznQmYMIBG3TKIHJJT95Q58nHLSrElKlGQqDTR2HQ9fx5CN/Gk6Vh/kupBTDLU11/nDk/g==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "scheduler": "^0.26.0"
       },
@@ -13157,6 +13183,7 @@
       "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.66.0.tgz",
       "integrity": "sha512-xXBqsWGKrY46ZqaHDo+ZUYiMUgi8suYu5kdrS20EG8KiL7VRQitEbNjm+UcrDYrNi1YLyfpmAeGjCZYXLT9YBw==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=18.0.0"
       },
@@ -13335,6 +13362,20 @@
         "react-dom": "^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/react-zoom-pan-pinch": {
+      "version": "3.7.0",
+      "resolved": "https://registry.npmjs.org/react-zoom-pan-pinch/-/react-zoom-pan-pinch-3.7.0.tgz",
+      "integrity": "sha512-UmReVZ0TxlKzxSbYiAj+LeGRW8s8LraAFTXRAxzMYnNRgGPsxCudwZKVkjvGmjtx7SW/hZamt69NUmGf4xrkXA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8",
+        "npm": ">=5"
+      },
+      "peerDependencies": {
+        "react": "*",
+        "react-dom": "*"
+      }
+    },
     "node_modules/reactflow": {
       "version": "11.11.4",
       "resolved": "https://registry.npmjs.org/reactflow/-/reactflow-11.11.4.tgz",
@@ -13470,6 +13511,7 @@
       "resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
       "integrity": "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/use-sync-external-store": "^0.0.6",
         "use-sync-external-store": "^1.4.0"
@@ -13492,7 +13534,8 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz",
       "integrity": "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/recharts/node_modules/redux-thunk": {
       "version": "3.1.0",
@@ -14516,7 +14559,8 @@
       "version": "0.180.0",
       "resolved": "https://registry.npmjs.org/three/-/three-0.180.0.tgz",
       "integrity": "sha512-o+qycAMZrh+TsE01GqWUxUIKR1AL0S8pq7zDkYOQw8GqfX8b8VoCKYUoHbhiX5j+7hr8XsuHDVU6+gkQJQKg9w==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/three-mesh-bvh": {
       "version": "0.8.3",
@@ -14604,6 +14648,7 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -14952,6 +14997,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"

frontend/package.json

@@ -89,6 +89,7 @@
     "react-resizable-panels": "^3.0.6",
     "react-webcam": "^7.2.0",
     "react-window": "^2.1.0",
+    "react-zoom-pan-pinch": "^3.7.0",
     "reactflow": "^11.11.4",
     "recharts": "^3.2.1",
     "sheetjs-style": "^0.15.8",