동적변수 기능 추가

mrjung72 · mrjung72 · commit 4d28e73aca33 · 2025-08-20T23:23:12.000+09:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,74 @@
 # SQL2Excel 버전 히스토리
 
+## v1.2.2 - 동적 변수 시스템 추가 (2025-08-20)
+
+### ✨ 새로운 기능
+- **🔄 동적 변수 시스템**: 데이터베이스에서 실시간으로 값을 조회하여 동적 쿼리 생성
+- **📊 3가지 동적 변수 타입**: `column_identified`, `key_value_pairs`, 기본 타입 지원
+- **🔗 시각 함수 통합**: 동적 변수에서 `CURRENT_TIMESTAMP`, `CURRENT_DATE` 등 시각 함수 사용 가능
+- **🌐 환경 변수 지원**: 동적 변수에서 환경 변수 사용 가능
+- **🐛 디버그 모드**: `DEBUG_VARIABLES=true` 환경 변수로 변수 치환 과정 상세 로깅
+
+### 🔄 동적 변수 타입별 기능
+
+#### 1. column_identified 타입
+- 각 컬럼별로 배열 생성
+- `${변수명.컬럼명}` 형태로 특정 컬럼의 값들만 사용
+- 예시: `${customerData.CustomerID}`, `${customerData.Region}`
+
+#### 2. key_value_pairs 타입
+- 첫 번째 컬럼을 키로, 두 번째 컬럼을 값으로 생성
+- `${변수명.키명}` 형태로 키 값들만 사용
+- 예시: `${productPrices.ProductID}`
+
+#### 3. 기본 타입
+- 첫 번째 컬럼의 값들을 배열로 생성
+- `${변수명}` 형태로 전체 배열 사용
+- 예시: `${activeCategories}`
+
+### 📝 사용 예시
+```xml
+<!-- 동적 변수 정의 -->
+<dynamicVars>
+  <dynamicVar name="customerData" type="column_identified" description="고객 데이터 컬럼별 분류">
+    <![CDATA[
+      SELECT CustomerID, CustomerName, City, Region
+      FROM Customers WHERE IsActive = 1
+    ]]>
+  </dynamicVar>
+  
+  <dynamicVar name="productPrices" type="key_value_pairs" description="상품별 가격 정보">
+    <![CDATA[
+      SELECT ProductID, UnitPrice
+      FROM Products WHERE Discontinued = 0
+    ]]>
+  </dynamicVar>
+</dynamicVars>
+
+<!-- 동적 변수 사용 -->
+<sheet name="고객주문분석">
+  <![CDATA[
+    SELECT * FROM Orders 
+    WHERE CustomerID IN (${customerData.CustomerID})
+      AND Region IN (${customerData.Region})
+      AND ProductID IN (${productPrices.ProductID})
+  ]]>
+</sheet>
+```
+
+### 🔧 개선사항
+- **변수 치환 우선순위**: 동적 변수 > 일반 변수 > 시각 함수 > 환경 변수 순서로 처리
+- **SQL 인젝션 방지**: 모든 변수 값에 대해 적절한 이스케이핑 처리
+- **오류 처리 강화**: 동적 변수 처리 중 오류 발생 시 빈 배열로 대체하여 안전성 확보
+- **성능 최적화**: 동적 변수는 DB 연결 후, 시트 처리 전에 한 번만 실행
+
+### 📚 문서화
+- **README.md 업데이트**: 동적 변수 기능 소개 및 예시 추가
+- **USER_MANUAL.md 확장**: 동적 변수 상세 사용법 및 타입별 설명 추가
+- **예제 파일 추가**: `queries-with-dynamic-variables.xml`, `queries-with-dynamic-variables.json` 생성
+
+---
+
 ## v1.2.1 - 문서화 개선 (2025-08-11)
 
 ### 📚 문서화
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ SQL 쿼리 결과를 엑셀 파일로 생성하는 Node.js 기반 도구입니
 - 🎨 **엑셀 스타일링**: 헤더/데이터 영역 각각 폰트, 색상, 테두리, 정렬 등 세부 스타일 설정
 - 🔗 **다중 DB 연결**: 시트별로 다른 데이터베이스 연결 가능
 - 📝 **변수 시스템**: 쿼리 내 변수 사용으로 동적 쿼리 생성
+- 🔄 **동적 변수**: 데이터베이스에서 실시간으로 값을 조회하여 동적 쿼리 생성
 - 🔄 **쿼리 재사용**: 공통 쿼리 정의 후 여러 시트에서 재사용
 - 📋 **자동 목차**: 목차 시트 자동 생성 및 하이퍼링크 제공
 - 📊 **집계 기능**: 지정 컬럼의 값별 건수 자동 집계 및 표시
@@ -79,7 +80,7 @@ node src/excel-cli.js help
 
 ## 💡 사용 예시
 
-### XML 설정 파일 예시
+### XML 설정 파일 예시 (동적 변수 포함)
 ```xml
 <queries>
   <excel db="sampleDB" output="output/매출보고서.xlsx">
@@ -89,10 +90,28 @@ node src/excel-cli.js help
     </header>
   </excel>
   
+  <!-- 일반 변수 -->
+  <vars>
+    <var name="startDate">2024-01-01</var>
+    <var name="endDate">2024-12-31</var>
+  </vars>
+  
+  <!-- 동적 변수 -->
+  <dynamicVars>
+    <dynamicVar name="activeCustomers" type="column_identified" description="활성 고객 목록">
+      <![CDATA[
+        SELECT CustomerID, CustomerName, Region
+        FROM Customers WHERE IsActive = 1
+      ]]>
+    </dynamicVar>
+  </dynamicVars>
+  
   <sheet name="월별매출" use="true" aggregateColumn="Month">
     <![CDATA[
       SELECT MONTH(OrderDate) as Month, SUM(TotalAmount) as Sales
-      FROM Orders WHERE YEAR(OrderDate) = 2024
+      FROM Orders 
+      WHERE YEAR(OrderDate) = 2024
+        AND CustomerID IN (${activeCustomers.CustomerID})
       GROUP BY MONTH(OrderDate)
     ]]>
   </sheet>
@@ -119,4 +138,4 @@ node src/excel-cli.js export --xml ./queries/sales-report.xml \
 
 ---
 
-**버전**: v1.2.1 | **최종 업데이트**: 2025-01-15
+**버전**: v1.2.2 | **최종 업데이트**: 2025-08-20
diff --git a/USER_MANUAL.md b/USER_MANUAL.md
@@ -356,13 +356,14 @@ db-test.bat
 
 ### 6. 변수 시스템
 
-#### 변수 정의 및 사용
+#### 일반 변수 정의 및 사용
 ```xml
 <!-- 변수 정의 -->
 <vars>
   <var name="startDate">2024-01-01</var>
   <var name="endDate">2024-12-31</var>
   <var name="targetRegion">서울</var>
+  <var name="regionList">["서울", "부산", "대구"]</var>
 </vars>
 
 <!-- 쿼리에서 변수 사용 -->
@@ -372,6 +373,7 @@ db-test.bat
     WHERE Region = '${targetRegion}' 
       AND SaleDate >= '${startDate}' 
       AND SaleDate <= '${endDate}'
+      AND Region IN (${regionList})
   ]]>
 </sheet>
 ```
@@ -381,6 +383,84 @@ db-test.bat
 node src/excel-cli.js export --xml queries.xml --var "startDate=2024-06-01" --var "endDate=2024-06-30"
 ```
 
+### 7. 동적 변수 시스템
+
+#### 동적 변수 정의
+동적 변수는 데이터베이스에서 실시간으로 값을 조회하여 쿼리에 사용할 수 있는 고급 변수 시스템입니다.
+
+```xml
+<!-- 동적 변수 정의 -->
+<dynamicVars>
+  <!-- column_identified 타입: 각 컬럼별로 배열 생성 -->
+  <dynamicVar name="customerData" type="column_identified" description="고객 데이터 컬럼별 분류">
+    <![CDATA[
+      SELECT CustomerID, CustomerName, City, Region
+      FROM Customers WHERE IsActive = 1
+    ]]>
+  </dynamicVar>
+  
+  <!-- key_value_pairs 타입: 첫 번째 컬럼을 키로, 두 번째 컬럼을 값으로 -->
+  <dynamicVar name="productPrices" type="key_value_pairs" description="상품별 가격 정보">
+    <![CDATA[
+      SELECT ProductID, UnitPrice
+      FROM Products WHERE Discontinued = 0
+    ]]>
+  </dynamicVar>
+  
+  <!-- 기본 타입: 첫 번째 컬럼의 값들을 배열로 -->
+  <dynamicVar name="activeCategories" description="활성 카테고리 목록">
+    <![CDATA[
+      SELECT CategoryID FROM Categories WHERE IsActive = 1
+    ]]>
+  </dynamicVar>
+</dynamicVars>
+```
+
+#### 동적 변수 사용 방법
+
+**1. column_identified 타입 사용**
+```sql
+-- ${customerData.CustomerID} 형태로 특정 컬럼의 값들만 사용
+SELECT * FROM Orders 
+WHERE CustomerID IN (${customerData.CustomerID})
+  AND Region IN (${customerData.Region})
+```
+
+**2. key_value_pairs 타입 사용**
+```sql
+-- ${productPrices.ProductID} 형태로 키 값들만 사용
+SELECT * FROM OrderDetails 
+WHERE ProductID IN (${productPrices.ProductID})
+```
+
+**3. 기본 타입 사용**
+```sql
+-- ${activeCategories} 형태로 전체 배열 사용
+SELECT * FROM Products 
+WHERE CategoryID IN (${activeCategories})
+```
+
+#### 동적 변수 타입별 특징
+
+| 타입 | 설명 | 사용법 | 예시 |
+|------|------|--------|------|
+| `column_identified` | 각 컬럼별로 배열 생성 | `${변수명.컬럼명}` | `${customerData.CustomerID}` |
+| `key_value_pairs` | 키-값 쌍으로 생성 | `${변수명.키명}` | `${productPrices.ProductID}` |
+| 기본 (없음) | 첫 번째 컬럼의 값들을 배열로 | `${변수명}` | `${activeCategories}` |
+
+#### 시각 함수와 조합 사용
+```xml
+<dynamicVar name="recentOrders" description="최근 주문 정보">
+  <![CDATA[
+    SELECT OrderID, OrderNumber
+    FROM Orders 
+    WHERE OrderDate >= '${startDate}' 
+      AND OrderDate <= '${endDate}'
+      AND OrderDate >= DATEADD(day, -30, '${CURRENT_DATE}')
+  ]]>
+</dynamicVar>
+```
+
 ## 📋 CLI 명령어 참조
 
 ### 1. export - 엑셀 파일 생성
@@ -504,6 +584,6 @@ node src/excel-cli.js help
 
 ---
 
-**📝 버전**: v1.2.1  
-**📅 최종 업데이트**: 2025-01-15  
+**📝 버전**: v1.2.2
+**📅 최종 업데이트**: 2025-08-20
 **🔧 주요 기능**: 멀티시트 엑셀 생성, 스타일링, 다중 DB 연결, 쿼리 재사용, 자동 목차
diff --git a/queries/queries-with-dynamic-variables.json b/queries/queries-with-dynamic-variables.json
@@ -0,0 +1,74 @@
+{
+  "excel": {
+    "db": "sampleDB",
+    "output": "d:/temp/동적변수_테스트_2024.xlsx",
+    "separateToc": false,
+    "maxRows": 20,
+    "style": "modern"
+  },
+  "vars": {
+    "envType": "운영",
+    "startDate": "2024-01-01",
+    "endDate": "2024-06-30",
+    "regionList": ["서울", "부산"],
+    "statusList": ["ACTIVE", "PENDING", "COMPLETED"],
+    "categoryIds": [1, 2, 3, 5],
+    "maxRows": 1000
+  },
+  "dynamicVars": [
+    {
+      "name": "customerData",
+      "type": "column_identified",
+      "description": "고객 데이터 컬럼별 분류",
+      "query": "SELECT CustomerID, CustomerName, City, Region, CustomerType FROM SampleDB.dbo.Customers WHERE IsActive = 1 ORDER BY CustomerID"
+    },
+    {
+      "name": "orderDetails",
+      "type": "key_value_pairs",
+      "description": "주문상세 정보",
+      "query": "SELECT OrderID, OrderDetailID FROM SampleDB.dbo.OrderDetails ORDER BY OrderID"
+    },
+    {
+      "name": "activeOrders",
+      "description": "활성 주문 목록",
+      "query": "SELECT OrderID FROM SampleDB.dbo.Orders WHERE OrderStatus = 'Pending' ORDER BY OrderID"
+    },
+    {
+      "name": "recentOrders",
+      "description": "최근 주문 정보",
+      "query": "SELECT OrderID, OrderNumber, OrderDate FROM SampleDB.dbo.Orders WHERE OrderDate >= '${startDate}' AND OrderDate <= '${endDate}' AND OrderDate >= DATEADD(day, -30, '${CURRENT_DATE}') ORDER BY OrderDate DESC"
+    }
+  ],
+  "sheets": [
+    {
+      "name": "${envType}_동적변수_테스트",
+      "use": true,
+      "aggregateColumn": "지역",
+      "maxRows": 100,
+      "db": "sampleDB",
+      "query": "SELECT c.CustomerID as 고객ID, c.CustomerName as 고객명, c.City as 도시, c.Region as 지역, c.CustomerType as 고객유형 FROM SampleDB.dbo.Customers c WHERE c.CustomerID IN (${customerData.CustomerID}) AND c.Region IN (${regionList}) ORDER BY c.CustomerID"
+    },
+    {
+      "name": "주문상세_동적변수_테스트2",
+      "use": true,
+      "aggregateColumn": "주문상태",
+      "query": "SELECT o.OrderID as 주문ID, o.OrderNumber as 주문번호, o.OrderStatus as 주문상태, od.OrderDetailID as 상세ID, FORMAT(o.TotalAmount, 'N0') as 총금액 FROM SampleDB.dbo.Orders o INNER JOIN SampleDB.dbo.OrderDetails od ON o.OrderID = od.OrderID WHERE o.OrderID IN (${orderDetails.OrderID}) AND o.OrderID IN (${activeOrders}) ORDER BY o.OrderID DESC"
+    },
+    {
+      "name": "주문상세_동적변수_테스트",
+      "use": true,
+      "aggregateColumn": "주문상태",
+      "query": "SELECT o.OrderNumber as 주문번호, FORMAT(o.OrderDate, 'yyyy-MM-dd') as 주문일, o.OrderStatus as 주문상태, c.CustomerName as 고객명, FORMAT(o.TotalAmount, 'N0') as 총금액 FROM SampleDB.dbo.Orders o INNER JOIN SampleDB.dbo.Customers c ON o.CustomerID = c.CustomerID WHERE o.OrderID IN (${recentOrders.OrderID}) AND o.OrderStatus IN (${statusList}) ORDER BY o.OrderDate DESC"
+    },
+    {
+      "name": "복합_동적변수_테스트",
+      "use": true,
+      "query": "SELECT c.CustomerName as 고객명, c.Region as 지역, COUNT(o.OrderID) as 주문건수, FORMAT(SUM(o.TotalAmount), 'N0') as 총주문금액 FROM SampleDB.dbo.Customers c INNER JOIN SampleDB.dbo.Orders o ON c.CustomerID = o.CustomerID WHERE c.CustomerID IN (${customerData.CustomerID}) AND c.Region IN (${customerData.Region}) AND o.OrderID IN (${activeOrders}) AND o.OrderDate >= '${startDate}' AND o.OrderDate <= '${endDate}' GROUP BY c.CustomerName, c.Region ORDER BY 총주문금액 DESC"
+    },
+    {
+      "name": "시각함수_동적변수_테스트",
+      "use": true,
+      "query": "SELECT '현재시각' as 구분, '${CURRENT_TIMESTAMP}' as 현재시각, '${CURRENT_DATE}' as 현재날짜, '${CURRENT_TIME}' as 현재시간, '${UNIX_TIMESTAMP}' as 유닉스타임스탬프, '${GETDATE}' as SQL서버_GETDATE UNION ALL SELECT '동적변수_테스트' as 구분, CONVERT(VARCHAR, GETDATE(), 120) as 현재시각, CONVERT(VARCHAR, GETDATE(), 23) as 현재날짜, CONVERT(VARCHAR, GETDATE(), 108) as 현재시간, DATEDIFF(SECOND, '1970-01-01', GETDATE()) as 유닉스타임스탬프, GETDATE() as SQL서버_GETDATE"
+    }
+  ]
+}
diff --git a/queries/queries-with-dynamic-variables.xml b/queries/queries-with-dynamic-variables.xml
diff --git a/src/index.js b/src/index.js
