feat: Phase 3.15 배치 서비스 Raw Query 전환 완료

4개 서비스 24개 Prisma 호출 전환 완료 배치 서비스 전환: - BatchExternalDbService (8개) - BatchExecutionLogService (7개) - BatchManagementService (5개) - BatchSchedulerService (4개) 주요 기술: - json_agg + json_build_object - 동적 WHERE 절 - 동적 UPDATE 쿼리 - PostgreSQL placeholders Phase 3 완료 문서: PHASE3.15_BATCH_SERVICES_MIGRATION.md
2025-10-01 13:30:20 +09:00
parent 3d8f70e181
commit 505f656c15
6 changed files with 406 additions and 190 deletions
--- a/PHASE3.15_BATCH_SERVICES_MIGRATION.md
+++ b/PHASE3.15_BATCH_SERVICES_MIGRATION.md
@@ -6,16 +6,75 @@

 ### 📊 기본 정보

-| 항목            | 내용                                                           |
-| --------------- | -------------------------------------------------------------- |
-| 대상 서비스     | 4개 (BatchExternalDb, ExecutionLog, Management, Scheduler)     |
-| 파일 위치       | `backend-node/src/services/batch*.ts`                          |
-| 총 파일 크기    | 2,161 라인                                                     |
-| Prisma 호출     | 24개                                                           |
-| **현재 진행률** | **0/24 (0%)** 🔄 **진행 예정**                                 |
-| 복잡도          | 높음 (외부 DB 연동, 스케줄링, 트랜잭션)                        |
-| 우선순위        | 🔴 높음 (Phase 3.15)                                           |
-| **상태**        | ⏳ **대기 중**                                                 |
+| 항목            | 내용                                                       |
+| --------------- | ---------------------------------------------------------- |
+| 대상 서비스     | 4개 (BatchExternalDb, ExecutionLog, Management, Scheduler) |
+| 파일 위치       | `backend-node/src/services/batch*.ts`                      |
+| 총 파일 크기    | 2,161 라인                                                 |
+| Prisma 호출     | 0개 (전환 완료)                                             |
+| **현재 진행률** | **24/24 (100%)** ✅ **전환 완료**                          |
+| 복잡도          | 높음 (외부 DB 연동, 스케줄링, 트랜잭션)                    |
+| 우선순위        | 🔴 높음 (Phase 3.15)                                       |
+| **상태**        | ✅ **완료**                                                |
+
+---
+
+## ✅ 전환 완료 내역
+
+### 전환된 Prisma 호출 (24개)
+
+#### 1. BatchExternalDbService (8개)
+- `getAvailableConnections()` - findMany → query
+- `getTables()` - $queryRaw → query (information_schema)
+- `getTableColumns()` - $queryRaw → query (information_schema)
+- `getExternalTables()` - findUnique → queryOne (x5)
+
+#### 2. BatchExecutionLogService (7개)
+- `getExecutionLogs()` - findMany + count → query (JOIN + 동적 WHERE)
+- `createExecutionLog()` - create → queryOne (INSERT RETURNING)
+- `updateExecutionLog()` - update → queryOne (동적 UPDATE)
+- `deleteExecutionLog()` - delete → query
+- `getLatestExecutionLog()` - findFirst → queryOne
+- `getExecutionStats()` - findMany → query (동적 WHERE)
+
+#### 3. BatchManagementService (5개)
+- `getAvailableConnections()` - findMany → query
+- `getTables()` - $queryRaw → query (information_schema)
+- `getTableColumns()` - $queryRaw → query (information_schema)
+- `getExternalTables()` - findUnique → queryOne (x2)
+
+#### 4. BatchSchedulerService (4개)
+- `loadActiveBatchConfigs()` - findMany → query (JOIN with json_agg)
+- `updateBatchSchedule()` - findUnique → query (JOIN with json_agg)
+- `getDataFromSource()` - $queryRawUnsafe → query
+- `insertDataToTarget()` - $executeRawUnsafe → query
+
+### 주요 기술적 해결 사항
+
+1. **외부 DB 연결 조회 반복**
+   - 5개의 `findUnique` 호출을 `queryOne`으로 일괄 전환
+   - 암호화/복호화 로직 유지
+
+2. **배치 설정 + 매핑 JOIN**
+   - Prisma `include` → `json_agg` + `json_build_object`
+   - `FILTER (WHERE bm.id IS NOT NULL)` 로 NULL 방지
+   - 계층적 JSON 데이터 생성
+
+3. **동적 WHERE 절 생성**
+   - 조건부 필터링 (batch_config_id, execution_status, 날짜 범위)
+   - 파라미터 인덱스 동적 관리
+
+4. **동적 UPDATE 쿼리**
+   - undefined 필드 제외
+   - 8개 필드의 조건부 업데이트
+
+5. **통계 쿼리 전환**
+   - 클라이언트 사이드 집계 유지
+   - 원본 데이터만 쿼리로 조회
+
+### 컴파일 상태
+✅ TypeScript 컴파일 성공  
+✅ Linter 오류 없음

 ---

@@ -24,12 +83,14 @@
 ### 1. BatchExternalDbService (8개 호출, 943 라인)

 **주요 기능**:
+
 - 외부 DB에서 배치 데이터 조회
 - 외부 DB로 배치 데이터 저장
 - 외부 DB 연결 관리
 - 데이터 변환 및 매핑

 **예상 Prisma 호출**:
+
 - `getExternalDbConnection()` - 외부 DB 연결 정보 조회
 - `fetchDataFromExternalDb()` - 외부 DB 데이터 조회
 - `saveDataToExternalDb()` - 외부 DB 데이터 저장
@@ -40,6 +101,7 @@
 - `getBatchExecutionStatus()` - 실행 상태 조회

 **기술적 고려사항**:
+
 - 다양한 DB 타입 지원 (PostgreSQL, MySQL, Oracle, MSSQL)
 - 연결 풀 관리
 - 트랜잭션 처리
@@ -50,12 +112,14 @@
 ### 2. BatchExecutionLogService (7개 호출, 299 라인)

 **주요 기능**:
+
 - 배치 실행 로그 생성
 - 배치 실행 이력 조회
 - 배치 실행 통계
 - 로그 정리

 **예상 Prisma 호출**:
+
 - `createExecutionLog()` - 실행 로그 생성
 - `updateExecutionLog()` - 실행 로그 업데이트
 - `getExecutionLogs()` - 실행 로그 목록 조회
@@ -65,6 +129,7 @@
 - `getFailedExecutions()` - 실패한 실행 조회

 **기술적 고려사항**:
+
 - 대용량 로그 처리
 - 통계 쿼리 최적화
 - 로그 보관 정책
@@ -75,12 +140,14 @@
 ### 3. BatchManagementService (5개 호출, 373 라인)

 **주요 기능**:
+
 - 배치 작업 설정 관리
 - 배치 작업 실행
 - 배치 작업 중지
 - 배치 작업 모니터링

 **예상 Prisma 호출**:
+
 - `getBatchJobs()` - 배치 작업 목록 조회
 - `getBatchJob()` - 배치 작업 단건 조회
 - `createBatchJob()` - 배치 작업 생성
@@ -88,6 +155,7 @@
 - `deleteBatchJob()` - 배치 작업 삭제

 **기술적 고려사항**:
+
 - JSON 설정 필드 (job_config)
 - 작업 상태 관리
 - 동시 실행 제어
@@ -98,18 +166,21 @@
 ### 4. BatchSchedulerService (4개 호출, 546 라인)

 **주요 기능**:
+
 - 배치 스케줄 설정
 - Cron 표현식 관리
 - 스케줄 실행
 - 다음 실행 시간 계산

 **예상 Prisma 호출**:
+
 - `getScheduledBatches()` - 스케줄된 배치 조회
 - `createSchedule()` - 스케줄 생성
 - `updateSchedule()` - 스케줄 수정
 - `deleteSchedule()` - 스케줄 삭제

 **기술적 고려사항**:
+
 - Cron 표현식 파싱
 - 시간대 처리
 - 실행 이력 추적
@@ -120,17 +191,23 @@
 ## 💡 통합 전환 전략

 ### Phase 1: 핵심 서비스 전환 (12개)
+
 **BatchManagementService (5개) + BatchExecutionLogService (7개)**
+
 - 배치 관리 및 로깅 기능 우선
 - 상대적으로 단순한 CRUD

 ### Phase 2: 스케줄러 전환 (4개)
+
 **BatchSchedulerService (4개)**
+
 - 스케줄 관리
 - Cron 표현식 처리

 ### Phase 3: 외부 DB 연동 전환 (8개)
+
 **BatchExternalDbService (8개)**
+
 - 가장 복잡한 서비스
 - 외부 DB 연결 및 쿼리

@@ -141,6 +218,7 @@
 ### 예시 1: 배치 실행 로그 생성

 **변경 전**:
+
 ```typescript
 const log = await prisma.batch_execution_logs.create({
  data: {
@@ -154,6 +232,7 @@ const log = await prisma.batch_execution_logs.create({
 ```

 **변경 후**:
+
 ```typescript
 const log = await queryOne<any>(
  `INSERT INTO batch_execution_logs 
@@ -167,6 +246,7 @@ const log = await queryOne<any>(
 ### 예시 2: 배치 통계 조회

 **변경 전**:
+
 ```typescript
 const stats = await prisma.batch_execution_logs.groupBy({
  by: ["status"],
@@ -179,6 +259,7 @@ const stats = await prisma.batch_execution_logs.groupBy({
 ```

 **변경 후**:
+
 ```typescript
 const stats = await query<{ status: string; count: string }>(
  `SELECT status, COUNT(*) as count
@@ -194,6 +275,7 @@ const stats = await query<{ status: string; count: string }>(
 ### 예시 3: 외부 DB 연결 및 쿼리

 **변경 전**:
+
 ```typescript
 // 연결 정보 조회
 const connection = await prisma.external_db_connections.findUnique({
@@ -205,6 +287,7 @@ const externalData = await externalDbClient.query(sql);
 ```

 **변경 후**:
+
 ```typescript
 // 연결 정보 조회
 const connection = await queryOne<any>(
@@ -219,6 +302,7 @@ const externalData = await externalDbClient.query(sql);
 ### 예시 4: 스케줄 관리

 **변경 전**:
+
 ```typescript
 const schedule = await prisma.batch_schedules.create({
  data: {
@@ -231,6 +315,7 @@ const schedule = await prisma.batch_schedules.create({
 ```

 **변경 후**:
+
 ```typescript
 const nextRun = calculateNextRun(cronExp);

@@ -248,6 +333,7 @@ const schedule = await queryOne<any>(
 ## 🔧 기술적 고려사항

 ### 1. 외부 DB 연결 관리
+
 ```typescript
 import { DatabaseConnectorFactory } from "../database/connectorFactory";

@@ -264,13 +350,14 @@ try {
 ```

 ### 2. 트랜잭션 처리
+
 ```typescript
 await transaction(async (client) => {
  // 배치 상태 업데이트
-  await client.query(
-    `UPDATE batch_jobs SET status = $1 WHERE id = $2`,
-    ["running", batchId]
-  );
+  await client.query(`UPDATE batch_jobs SET status = $1 WHERE id = $2`, [
+    "running",
+    batchId,
+  ]);

  // 실행 로그 생성
  await client.query(
@@ -282,6 +369,7 @@ await transaction(async (client) => {
 ```

 ### 3. Cron 표현식 처리
+
 ```typescript
 import cron from "node-cron";

@@ -296,6 +384,7 @@ function calculateNextRun(cronExp: string): Date {
 ```

 ### 4. 대용량 데이터 처리
+
 ```typescript
 // 스트리밍 방식으로 대용량 데이터 처리
 const stream = await query<any>(
@@ -313,6 +402,7 @@ for await (const row of stream) {
 ## 📝 전환 체크리스트

 ### BatchExternalDbService (8개)
+
 - [ ] `getExternalDbConnection()` - 연결 정보 조회
 - [ ] `fetchDataFromExternalDb()` - 외부 DB 데이터 조회
 - [ ] `saveDataToExternalDb()` - 외부 DB 데이터 저장
@@ -323,6 +413,7 @@ for await (const row of stream) {
 - [ ] `getBatchExecutionStatus()` - 실행 상태 조회

 ### BatchExecutionLogService (7개)
+
 - [ ] `createExecutionLog()` - 실행 로그 생성
 - [ ] `updateExecutionLog()` - 실행 로그 업데이트
 - [ ] `getExecutionLogs()` - 실행 로그 목록 조회
@@ -332,6 +423,7 @@ for await (const row of stream) {
 - [ ] `getFailedExecutions()` - 실패한 실행 조회

 ### BatchManagementService (5개)
+
 - [ ] `getBatchJobs()` - 배치 작업 목록 조회
 - [ ] `getBatchJob()` - 배치 작업 단건 조회
 - [ ] `createBatchJob()` - 배치 작업 생성
@@ -339,12 +431,14 @@ for await (const row of stream) {
 - [ ] `deleteBatchJob()` - 배치 작업 삭제

 ### BatchSchedulerService (4개)
+
 - [ ] `getScheduledBatches()` - 스케줄된 배치 조회
 - [ ] `createSchedule()` - 스케줄 생성
 - [ ] `updateSchedule()` - 스케줄 수정
 - [ ] `deleteSchedule()` - 스케줄 삭제

 ### 공통 작업
+
 - [ ] import 문 수정 (모든 서비스)
 - [ ] Prisma import 완전 제거 (모든 서비스)
 - [ ] 트랜잭션 로직 확인
@@ -355,15 +449,18 @@ for await (const row of stream) {
 ## 🧪 테스트 계획

 ### 단위 테스트 (24개)
+
 - 각 Prisma 호출별 1개씩

 ### 통합 테스트 (8개)
+
 - BatchExternalDbService: 외부 DB 연동 테스트 (2개)
 - BatchExecutionLogService: 로그 생성 및 조회 테스트 (2개)
 - BatchManagementService: 배치 작업 실행 테스트 (2개)
 - BatchSchedulerService: 스케줄 실행 테스트 (2개)

 ### 성능 테스트
+
 - 대용량 데이터 처리 성능
 - 동시 배치 실행 성능
 - 외부 DB 연결 풀 성능
@@ -377,7 +474,6 @@ for await (const row of stream) {
  - 트랜잭션 처리
  - 스케줄링 로직
  - 대용량 데이터 처리
-  
 - **예상 소요 시간**: 4~5시간
  - Phase 1 (BatchManagement + ExecutionLog): 1.5시간
  - Phase 2 (Scheduler): 1시간
@@ -389,6 +485,7 @@ for await (const row of stream) {
 ## ⚠️ 주의사항

 ### 중요 체크포인트
+
 1. ✅ 외부 DB 연결은 반드시 try-finally에서 해제
 2. ✅ 배치 실행 중 에러 시 롤백 처리
 3. ✅ Cron 표현식 검증 필수
@@ -396,6 +493,7 @@ for await (const row of stream) {
 5. ✅ 동시 실행 제한 확인

 ### 성능 최적화
+
 - 연결 풀 활용
 - 배치 쿼리 최적화
 - 인덱스 확인
@@ -406,4 +504,3 @@ for await (const row of stream) {
 **상태**: ⏳ **대기 중**  
 **특이사항**: 외부 DB 연동, 스케줄링, 트랜잭션 처리 포함  
 **⚠️ 주의**: 배치 시스템의 핵심 기능이므로 신중한 테스트 필수!
-