(김준회) 결재 템플릿 에디터 및 결재 워크플로 공통함수 작성, 실사의뢰 결재 연결 예시 작성

7 files changed, 1089 insertions, 0 deletions

diff --git a/lib/approval/approval-polling-service.ts b/lib/approval/approval-polling-service.ts
new file mode 100644
index 00000000..d2ee16cb
--- /dev/null
+++ b/lib/approval/approval-polling-service.ts
@@ -0,0 +1,307 @@
+/**
+ * Knox 결재 상태 폴링 서비스
+ * 
+ * 기능:
+ * - 1분마다 진행중인(pending) 결재를 조회
+ * - Knox API로 상태 일괄 확인 (최대 1000건씩 배치)
+ * - 상태 변경 시 DB 업데이트 및 후속 처리
+ * 
+ * 흐름:
+ * Cron (1분) → checkPendingApprovals() → Knox API 조회 → 상태 업데이트 → executeApprovedAction()
+ * 
+ * 기존 syncApprovalStatusAction과의 차이점:
+ * - syncApprovalStatusAction: UI에서 수동으로 트리거 (on-demand)
+ * - checkPendingApprovals: 백그라운드 cron job (1분마다 자동)
+ * - checkPendingApprovals: 결재 완료/반려 시 자동으로 후속 처리 실행
+ */
+
+import cron from 'node-cron';
+import db from '@/db/db';
+import { eq, and, inArray } from 'drizzle-orm';
+import { executeApprovedAction, handleRejectedAction } from './approval-workflow';
+
+/**
+ * Pending 상태의 결재들을 조회하고 상태 동기화
+ * 
+ * 처리 로직 (syncApprovalStatusAction 기반):
+ * 1. DB에서 진행중인 결재 조회 (암호화중~진행중)
+ * 2. Knox API로 일괄 상태 확인 (최대 1000건씩 배치)
+ * 3. 상태가 변경된 경우 DB 업데이트
+ * 4. 완결/반려로 변경 시 후속 처리 (executeApprovedAction/handleRejectedAction)
+ */
+export async function checkPendingApprovals() {
+  console.log('[Approval Polling] Starting approval status check...');
+
+  try {
+    // 동적 import로 스키마 및 Knox API 로드
+    const { approvalLogs } = await import('@/db/schema/knox/approvals');
+    const { getApprovalStatus } = await import('@/lib/knox-api/approval/approval');
+    const { upsertApprovalStatus } = await import('@/lib/knox-api/approval/service');
+    
+    // 1. 진행중인 결재건들 조회 (암호화중~진행중까지)
+    // 암호화중(-2), 예약상신(-1), 보류(0), 진행중(1) 상태만 조회
+    // 완결(2), 반려(3), 상신취소(4), 전결(5), 후완결(6)은 제외
+    const pendingApprovals = await db
+      .select({
+        apInfId: approvalLogs.apInfId,
+        status: approvalLogs.status,
+      })
+      .from(approvalLogs)
+      .where(
+        and(
+          eq(approvalLogs.isDeleted, false),
+          inArray(approvalLogs.status, ['-2', '-1', '0', '1'])
+        )
+      );
+
+    if (pendingApprovals.length === 0) {
+      console.log('[Approval Polling] No pending approvals found');
+      return {
+        success: true,
+        message: 'No pending approvals',
+        checked: 0,
+        updated: 0,
+        executed: 0,
+      };
+    }
+
+    console.log(`[Approval Polling] Found ${pendingApprovals.length} pending approvals to check`);
+
+    // 2. Knox API 호출을 위한 요청 데이터 구성
+    const apinfids = pendingApprovals.map(approval => ({
+      apinfid: approval.apInfId
+    }));
+
+    // 3. Knox API로 결재 상황 조회 (최대 1000건씩 배치 처리)
+    const batchSize = 1000;
+    let updated = 0;
+    let executed = 0;
+    const failed: string[] = [];
+
+    for (let i = 0; i < apinfids.length; i += batchSize) {
+      const batch = apinfids.slice(i, i + batchSize);
+      
+      try {
+        console.log(`[Approval Polling] Processing batch ${Math.floor(i / batchSize) + 1} (${batch.length} items)`);
+        
+        const statusResponse = await getApprovalStatus({
+          apinfids: batch
+        });
+
+        if (statusResponse.result === 'success' && statusResponse.data) {
+          // 4. 조회된 상태로 데이터베이스 업데이트 및 후속 처리
+          for (const statusData of statusResponse.data) {
+            try {
+              // 기존 데이터 찾기
+              const currentApproval = pendingApprovals.find(
+                approval => approval.apInfId === statusData.apInfId
+              );
+              
+              if (!currentApproval) {
+                console.warn(`[Approval Polling] Approval not found in local list: ${statusData.apInfId}`);
+                continue;
+              }
+
+              const oldStatus = currentApproval.status;
+              const newStatus = statusData.status;
+
+              // 상태가 변경된 경우에만 처리
+              if (oldStatus !== newStatus) {
+                console.log(`[Approval Polling] Status changed: ${statusData.apInfId} (${oldStatus} → ${newStatus})`);
+                
+                // DB 상태 업데이트
+                await upsertApprovalStatus(statusData.apInfId, newStatus);
+                updated++;
+
+                // 5. 후속 처리 - 완결 상태로 변경된 경우
+                // 완결(2), 전결(5), 후완결(6)
+                if (['2', '5', '6'].includes(newStatus)) {
+                  try {
+                    await executeApprovedAction(currentApproval.apInfId);
+                    executed++;
+                    console.log(`[Approval Polling] ✅ Executed approved action: ${statusData.apInfId}`);
+                  } catch (execError) {
+                    console.error(`[Approval Polling] ❌ Failed to execute action: ${statusData.apInfId}`, execError);
+                    // 실행 실패는 별도로 기록하되 폴링은 계속 진행
+                  }
+                }
+                
+                // 반려된 경우
+                else if (newStatus === '3') {
+                  try {
+                    await handleRejectedAction(currentApproval.apInfId, '결재가 반려되었습니다');
+                    console.log(`[Approval Polling] ⛔ Handled rejected action: ${statusData.apInfId}`);
+                  } catch (rejectError) {
+                    console.error(`[Approval Polling] Failed to handle rejection: ${statusData.apInfId}`, rejectError);
+                  }
+                }
+                
+                // 상신취소된 경우
+                else if (newStatus === '4') {
+                  try {
+                    await handleRejectedAction(currentApproval.apInfId, '결재가 취소되었습니다');
+                    console.log(`[Approval Polling] 🚫 Handled cancelled action: ${statusData.apInfId}`);
+                  } catch (cancelError) {
+                    console.error(`[Approval Polling] Failed to handle cancellation: ${statusData.apInfId}`, cancelError);
+                  }
+                }
+              }
+            } catch (updateError) {
+              console.error(`[Approval Polling] Update failed for ${statusData.apInfId}:`, updateError);
+              failed.push(statusData.apInfId);
+            }
+          }
+        } else {
+          console.error('[Approval Polling] Knox API returned error:', statusResponse);
+          batch.forEach(item => failed.push(item.apinfid));
+        }
+      } catch (batchError) {
+        console.error('[Approval Polling] Batch processing failed:', batchError);
+        batch.forEach(item => failed.push(item.apinfid));
+      }
+    }
+
+    const summary = {
+      success: true,
+      message: `Polling completed: ${updated} updated, ${executed} executed${failed.length > 0 ? `, ${failed.length} failed` : ''}`,
+      checked: pendingApprovals.length,
+      updated,
+      executed,
+      failed: failed.length,
+    };
+
+    console.log('[Approval Polling] Summary:', summary);
+    
+    return summary;
+    
+  } catch (error) {
+    console.error('[Approval Polling] Error during approval status check:', error);
+    return {
+      success: false,
+      message: `Polling failed: ${error}`,
+      checked: 0,
+      updated: 0,
+      executed: 0,
+      failed: 0,
+    };
+  }
+}
+
+/**
+ * 결재 폴링 스케줄러 시작
+ * 1분마다 pending 결재 상태 확인
+ * 
+ * instrumentation.ts에서 호출됨
+ */
+export async function startApprovalPollingScheduler() {
+  console.log('[Approval Polling] Starting approval polling scheduler...');
+
+  // 1분마다 실행 (cron: '* * * * *')
+  const task = cron.schedule(
+    '* * * * *', // 매분 실행
+    async () => {
+      try {
+        await checkPendingApprovals();
+      } catch (error) {
+        console.error('[Approval Polling] Scheduled task failed:', error);
+      }
+    },
+    {
+      timezone: 'Asia/Seoul',
+    }
+  );
+
+  // 앱 시작 시 즉시 한 번 실행 (선택사항)
+  // await checkPendingApprovals();
+
+  console.log('[Approval Polling] Scheduler started - running every minute');
+  
+  return task;
+}
+
+/**
+ * 특정 결재의 상태를 즉시 확인 (수동 트리거용)
+ * UI에서 "상태 새로고침" 버튼 클릭 시 사용
+ * 
+ * @param apInfId - Knox 결재 ID
+ * @returns 결재 상태 및 업데이트 여부
+ */
+export async function checkSingleApprovalStatus(apInfId: string) {
+  console.log(`[Approval Polling] Checking single approval: ${apInfId}`);
+
+  try {
+    // 동적 import로 스키마 및 Knox API 로드
+    const { approvalLogs } = await import('@/db/schema/knox/approvals');
+    const { getApprovalStatus } = await import('@/lib/knox-api/approval/approval');
+    const { upsertApprovalStatus } = await import('@/lib/knox-api/approval/service');
+
+    // 1. DB에서 결재 정보 조회
+    const approvalLog = await db.query.approvalLogs.findFirst({
+      where: eq(approvalLogs.apInfId, apInfId),
+    });
+
+    if (!approvalLog) {
+      throw new Error(`Approval log not found for apInfId: ${apInfId}`);
+    }
+
+    const oldStatus = approvalLog.status;
+
+    // 2. Knox API로 현재 상태 조회 (단건)
+    const statusResponse = await getApprovalStatus({
+      apinfids: [{ apinfid: apInfId }]
+    });
+
+    if (statusResponse.result !== 'success' || !statusResponse.data || statusResponse.data.length === 0) {
+      throw new Error(`Failed to fetch Knox status for ${apInfId}`);
+    }
+
+    const knoxStatus = statusResponse.data[0];
+    const newStatus = knoxStatus.status;
+
+    // 3. 상태가 변경된 경우 업데이트 및 후속 처리
+    let executed = false;
+    if (oldStatus !== newStatus) {
+      console.log(`[Approval Polling] Single check - Status changed: ${apInfId} (${oldStatus} → ${newStatus})`);
+      
+      // DB 상태 업데이트
+      await upsertApprovalStatus(apInfId, newStatus);
+
+      // 4. 후속 처리
+      // 완결(2), 전결(5), 후완결(6)
+      if (['2', '5', '6'].includes(newStatus)) {
+        try {
+          await executeApprovedAction(approvalLog.apInfId);
+          executed = true;
+          console.log(`[Approval Polling] ✅ Single check - Executed approved action: ${apInfId}`);
+        } catch (execError) {
+          console.error(`[Approval Polling] ❌ Single check - Failed to execute action: ${apInfId}`, execError);
+        }
+      }
+      // 반려(3)
+      else if (newStatus === '3') {
+        await handleRejectedAction(approvalLog.apInfId, '결재가 반려되었습니다');
+        console.log(`[Approval Polling] ⛔ Single check - Handled rejected action: ${apInfId}`);
+      }
+      // 상신취소(4)
+      else if (newStatus === '4') {
+        await handleRejectedAction(approvalLog.apInfId, '결재가 취소되었습니다');
+        console.log(`[Approval Polling] 🚫 Single check - Handled cancelled action: ${apInfId}`);
+      }
+    } else {
+      console.log(`[Approval Polling] Single check - No status change: ${apInfId} (${oldStatus})`);
+    }
+
+    return {
+      success: true,
+      apInfId,
+      oldStatus,
+      newStatus,
+      updated: oldStatus !== newStatus,
+      executed,
+    };
+  } catch (error) {
+    console.error(`[Approval Polling] Failed to check single approval status for ${apInfId}:`, error);
+    throw error;
+  }
+}
+
diff --git a/lib/approval/approval-workflow.ts b/lib/approval/approval-workflow.ts
new file mode 100644
index 00000000..cc8914f9
--- /dev/null
+++ b/lib/approval/approval-workflow.ts
@@ -0,0 +1,272 @@
+/**
+ * 결재 워크플로우 관리 모듈
+ * 
+ * 주요 기능:
+ * 1. 결재가 필요한 액션을 pending 상태로 저장
+ * 2. Knox 결재 시스템에 상신
+ * 3. 결재 완료 시 저장된 액션 실행
+ * 
+ * 흐름:
+ * withApproval() → Knox 상신 → [폴링으로 상태 감지] → executeApprovedAction()
+ */
+
+import db from '@/db/db';
+import { eq } from 'drizzle-orm';
+import { pendingActions } from '@/db/schema/knox/pending-actions';
+
+import type { ApprovalConfig } from './types';
+import type { ApprovalLine } from '@/lib/knox-api/approval/approval';
+
+/**
+ * 액션 핸들러 타입 정의
+ * payload를 받아서 실제 비즈니스 로직을 수행하는 함수
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ActionHandler = (payload: any) => Promise<any>;
+
+/**
+ * 액션 타입별 핸들러 저장소
+ * registerActionHandler()로 등록된 핸들러들이 여기 저장됨
+ */
+const actionHandlers = new Map<string, ActionHandler>();
+
+/**
+ * 특정 액션 타입에 대한 핸들러 등록
+ * 
+ * @example
+ * registerActionHandler('vendor_investigation_request', async (payload) => {
+ *   return await createInvestigation(payload);
+ * });
+ */
+export function registerActionHandler(actionType: string, handler: ActionHandler) {
+  actionHandlers.set(actionType, handler);
+}
+
+/**
+ * 등록된 핸들러 조회 (디버깅/테스트용)
+ */
+export function getRegisteredHandlers() {
+  return Array.from(actionHandlers.keys());
+}
+
+/**
+ * 결재가 필요한 액션을 래핑하는 공통 함수
+ * 
+ * 사용법:
+ * ```typescript
+ * const result = await withApproval(
+ *   'vendor_investigation_request',
+ *   { vendorId: 123, reason: '실사 필요' },
+ *   {
+ *     title: '실사 요청 결재',
+ *     description: 'ABC 협력업체 실사 요청',
+ *     templateName: '협력업체 실사 요청',
+ *     variables: { '수신자이름': '결재자', ... },
+ *     currentUser: { id: 1, epId: 'EP001' }
+ *   }
+ * );
+ * ```
+ * 
+ * @param actionType - 액션 타입 (핸들러 등록 시 사용한 키)
+ * @param actionPayload - 액션 실행에 필요한 데이터
+ * @param approvalConfig - 결재 상신 설정 (템플릿명, 변수 포함)
+ * @returns pendingActionId, approvalId, status
+ */
+export async function withApproval<T>(
+  actionType: string,
+  actionPayload: T,
+  approvalConfig: ApprovalConfig
+) {
+  // 핸들러가 등록되어 있는지 확인
+  if (!actionHandlers.has(actionType)) {
+    throw new Error(`No handler registered for action type: ${actionType}`);
+  }
+
+  try {
+    // 1. 템플릿 조회 및 변수 치환
+    const { getApprovalTemplateByName, replaceTemplateVariables } = await import('./template-utils');
+    const template = await getApprovalTemplateByName(approvalConfig.templateName);
+    
+    let content: string;
+    if (!template) {
+      console.warn(`[Approval Workflow] Template not found: ${approvalConfig.templateName}`);
+      // 템플릿이 없으면 기본 내용 사용
+      content = approvalConfig.description || '결재 요청';
+    } else {
+      // 템플릿 변수 치환
+      content = await replaceTemplateVariables(template.content, approvalConfig.variables);
+    }
+
+    // 2. Knox 결재 상신 (apInfId 생성, 치환된 content 사용)
+    const { 
+      submitApproval, 
+      createSubmitApprovalRequest,
+      createApprovalLine
+    } = await import('@/lib/knox-api/approval/approval');
+    
+    // 결재선 생성
+    const aplns: ApprovalLine[] = [];
+    
+    // 기안자 (현재 사용자)
+    if (approvalConfig.currentUser.epId) {
+      const drafterLine = await createApprovalLine(
+        {
+          epId: approvalConfig.currentUser.epId,
+          emailAddress: approvalConfig.currentUser.email,
+        },
+        '0', // 기안
+        '0'  // seq
+      );
+      aplns.push(drafterLine);
+    }
+    
+    // 결재자들
+    if (approvalConfig.approvers && approvalConfig.approvers.length > 0) {
+      for (let i = 0; i < approvalConfig.approvers.length; i++) {
+        const approverLine = await createApprovalLine(
+          { epId: approvalConfig.approvers[i] },
+          '1', // 승인
+          String(i + 1)
+        );
+        aplns.push(approverLine);
+      }
+    }
+    
+    // 결재 요청 생성
+    const submitRequest = await createSubmitApprovalRequest(
+      content, // 치환된 템플릿 content
+      approvalConfig.title,
+      aplns,
+      {
+        contentsType: 'HTML', // HTML 템플릿 사용
+      }
+    );
+    
+    // Knox 결재 상신
+    await submitApproval(
+      submitRequest,
+      {
+        userId: String(approvalConfig.currentUser.id),
+        epId: approvalConfig.currentUser.epId || '',
+        emailAddress: approvalConfig.currentUser.email || '',
+      }
+    );
+
+    // 3. Pending Action 생성 (approvalLog의 apInfId로 연결)
+    // Knox에서 apInfId를 반환하지 않고, 요청 시 생성한 apInfId를 사용
+    const [pendingAction] = await db.insert(pendingActions).values({
+      apInfId: submitRequest.apInfId,
+      actionType,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      actionPayload: actionPayload as any,
+      status: 'pending',
+      createdBy: approvalConfig.currentUser.id,
+    }).returning();
+
+    return {
+      pendingActionId: pendingAction.id,
+      approvalId: submitRequest.apInfId,
+      status: 'pending_approval',
+    };
+
+  } catch (error) {
+    console.error('Failed to create approval workflow:', error);
+    throw error;
+  }
+}
+
+/**
+ * 결재가 승인된 액션을 실행
+ * 폴링 서비스에서 호출됨
+ * 
+ * @param apInfId - Knox 결재 ID (approvalLogs의 primary key)
+ * @returns 액션 실행 결과
+ */
+export async function executeApprovedAction(apInfId: string) {
+  try {
+    // 1. apInfId로 pendingAction 조회
+    const pendingAction = await db.query.pendingActions.findFirst({
+      where: eq(pendingActions.apInfId, apInfId),
+    });
+
+    if (!pendingAction) {
+      console.log(`[Approval Workflow] No pending action found for approval: ${apInfId}`);
+      return null; // 결재만 있고 실행할 액션이 없는 경우
+    }
+
+    // 이미 실행되었거나 실패한 액션은 스킵
+    if (['executed', 'failed'].includes(pendingAction.status)) {
+      console.log(`[Approval Workflow] Pending action already processed: ${apInfId} (${pendingAction.status})`);
+      return null;
+    }
+
+    // 2. 등록된 핸들러 조회
+    const handler = actionHandlers.get(pendingAction.actionType);
+    if (!handler) {
+      throw new Error(`Handler not found for action type: ${pendingAction.actionType}`);
+    }
+
+    // 3. 실제 액션 실행
+    console.log(`[Approval Workflow] Executing action: ${pendingAction.actionType} (${apInfId})`);
+    const result = await handler(pendingAction.actionPayload);
+    
+    // 4. 실행 완료 상태 업데이트
+    await db.update(pendingActions)
+      .set({ 
+        status: 'executed',
+        executedAt: new Date(),
+        executionResult: result,
+      })
+      .where(eq(pendingActions.apInfId, apInfId));
+
+    console.log(`[Approval Workflow] ✅ Successfully executed: ${pendingAction.actionType} (${apInfId})`);
+    return result;
+
+  } catch (error) {
+    console.error(`[Approval Workflow] ❌ Failed to execute action for ${apInfId}:`, error);
+    
+    // 실패 상태 업데이트
+    await db.update(pendingActions)
+      .set({ 
+        status: 'failed',
+        errorMessage: error instanceof Error ? error.message : String(error),
+        executedAt: new Date(),
+      })
+      .where(eq(pendingActions.apInfId, apInfId));
+    
+    throw error;
+  }
+}
+
+/**
+ * 결재 반려 시 처리
+ * 
+ * @param apInfId - Knox 결재 ID (approvalLogs의 primary key)
+ * @param reason - 반려 사유
+ */
+export async function handleRejectedAction(apInfId: string, reason?: string) {
+  try {
+    const pendingAction = await db.query.pendingActions.findFirst({
+      where: eq(pendingActions.apInfId, apInfId),
+    });
+
+    if (!pendingAction) {
+      console.log(`[Approval Workflow] No pending action found for rejected approval: ${apInfId}`);
+      return; // 결재만 있고 실행할 액션이 없는 경우
+    }
+
+    await db.update(pendingActions)
+      .set({ 
+        status: 'rejected',
+        errorMessage: reason,
+        executedAt: new Date(),
+      })
+      .where(eq(pendingActions.apInfId, apInfId));
+    
+    // TODO: 요청자에게 알림 발송 등 추가 처리
+  } catch (error) {
+    console.error(`[Approval Workflow] Failed to handle rejected action for approval ${apInfId}:`, error);
+    throw error;
+  }
+}
+
diff --git a/lib/approval/example-usage.ts b/lib/approval/example-usage.ts
new file mode 100644
index 00000000..357f3ef1
--- /dev/null
+++ b/lib/approval/example-usage.ts
@@ -0,0 +1,187 @@
+/**
+ * 결재 워크플로우 사용 예시 (템플릿 기반)
+ * 
+ * 이 파일은 실제 사용 방법을 보여주는 예시입니다.
+ * 실제 구현 시 각 서버 액션에 적용하면 됩니다.
+ * 
+ * 업데이트: 템플릿 및 변수 치환 지원
+ */
+
+import { registerActionHandler, withApproval } from './approval-workflow';
+import {
+  htmlTableConverter,
+  htmlDescriptionList,
+} from './template-utils';
+
+// ============================================================================
+// 1단계: 액션 핸들러 등록
+// ============================================================================
+
+/**
+ * 실사 요청의 실제 비즈니스 로직
+ * 결재 승인 후 실행될 함수
+ */
+async function createInvestigationInternal(payload: {
+  vendorId: number;
+  vendorName: string;
+  reason: string;
+  scheduledDate: Date;
+}) {
+  // 실제 DB 작업 등 비즈니스 로직
+  console.log('Creating investigation:', payload);
+  
+  // const result = await db.insert(vendorInvestigations).values({
+  //   vendorId: payload.vendorId,
+  //   reason: payload.reason,
+  //   scheduledDate: payload.scheduledDate,
+  //   status: 'scheduled',
+  // }).returning();
+  
+  return { success: true, investigationId: 123 };
+}
+
+// 핸들러 등록 (앱 시작 시 한 번만 실행되면 됨)
+registerActionHandler('vendor_investigation_request', createInvestigationInternal);
+
+// ============================================================================
+// 2단계: 결재가 필요한 서버 액션 작성
+// ============================================================================
+
+/**
+ * 사용자가 호출하는 서버 액션
+ * 결재를 거쳐서 실사 요청을 생성 (템플릿 기반)
+ */
+export async function createInvestigationWithApproval(data: {
+  vendorId: number;
+  vendorName: string;
+  reason: string;
+  scheduledDate: Date;
+  currentUser: { id: number; epId: string | null };
+  approvers?: string[]; // Knox EP ID 배열
+}) {
+  'use server'; // Next.js 15 server action
+
+  // 1. 템플릿 변수 생성 (HTML 변환 포함)
+  const summaryTable: string = await htmlTableConverter(
+    [
+      { 항목: '협력업체명', 내용: data.vendorName },
+      { 항목: '실사 사유', 내용: data.reason },
+      { 항목: '예정일', 내용: data.scheduledDate.toLocaleDateString('ko-KR') },
+    ],
+    [
+      { key: '항목', label: '항목' },
+      { key: '내용', label: '내용' },
+    ]
+  );
+
+  const basicInfo: string = await htmlDescriptionList([
+    { label: '협력업체명', value: data.vendorName },
+    { label: '실사 사유', value: data.reason },
+  ]);
+
+  const variables: Record<string, string> = {
+    수신자이름: '결재자',
+    협력업체명: data.vendorName,
+    '실사의뢰 요약 테이블 1': summaryTable,
+    '실사의뢰 기본정보': basicInfo,
+    '실사의뢰 요약 문구': `${data.vendorName}에 대한 실사를 요청합니다.`,
+  };
+
+  // 2. 결재 워크플로우 시작 (템플릿 사용)
+  const result = await withApproval(
+    'vendor_investigation_request',
+    {
+      vendorId: data.vendorId,
+      vendorName: data.vendorName,
+      reason: data.reason,
+      scheduledDate: data.scheduledDate,
+    },
+    {
+      title: `실사 요청 - ${data.vendorName}`,
+      description: `협력업체 ${data.vendorName}에 대한 실사 요청`,
+      templateName: '협력업체 실사 요청', // 한국어 템플릿명
+      variables, // 치환할 변수들
+      approvers: data.approvers,
+      currentUser: data.currentUser,
+    }
+  );
+
+  return result;
+}
+
+// ============================================================================
+// 3단계: UI에서 호출
+// ============================================================================
+
+/**
+ * 클라이언트 컴포넌트에서 사용 예시
+ * 
+ * ```tsx
+ * const handleSubmit = async (formData) => {
+ *   try {
+ *     const result = await createInvestigationWithApproval({
+ *       vendorId: formData.vendorId,
+ *       vendorName: formData.vendorName,
+ *       reason: formData.reason,
+ *       scheduledDate: new Date(formData.scheduledDate),
+ *       currentUser: session.user,
+ *       approvers: selectedApprovers, // 결재선
+ *     });
+ * 
+ *     // 결재 상신 완료
+ *     alert(`결재가 상신되었습니다. 결재 ID: ${result.approvalId}`);
+ *     
+ *     // 결재 현황 페이지로 이동하거나 대기 상태 표시
+ *     router.push(`/approval/status/${result.approvalId}`);
+ *   } catch (error) {
+ *     console.error('Failed to submit approval:', error);
+ *   }
+ * };
+ * ```
+ */
+
+// ============================================================================
+// 다른 액션 타입 예시
+// ============================================================================
+
+/**
+ * 발주 요청 핸들러
+ */
+async function createPurchaseOrderInternal(payload: {
+  vendorId: number;
+  items: Array<{ itemId: number; quantity: number }>;
+  totalAmount: number;
+}) {
+  console.log('Creating purchase order:', payload);
+  return { success: true, orderId: 456 };
+}
+
+registerActionHandler('purchase_order_request', createPurchaseOrderInternal);
+
+/**
+ * 계약 승인 핸들러
+ */
+async function approveContractInternal(payload: {
+  contractId: number;
+  approverComments: string;
+}) {
+  console.log('Approving contract:', payload);
+  return { success: true, contractId: payload.contractId };
+}
+
+registerActionHandler('contract_approval', approveContractInternal);
+
+// ============================================================================
+// 추가 유틸리티
+// ============================================================================
+
+/**
+ * 결재 상태를 수동으로 확인 (UI에서 "새로고침" 버튼용)
+ */
+export async function refreshApprovalStatus(apInfId: string) {
+  'use server';
+  
+  const { checkSingleApprovalStatus } = await import('./approval-polling-service');
+  return await checkSingleApprovalStatus(apInfId);
+}
+
diff --git a/lib/approval/handlers-registry.ts b/lib/approval/handlers-registry.ts
new file mode 100644
index 00000000..1e8140e5
--- /dev/null
+++ b/lib/approval/handlers-registry.ts
@@ -0,0 +1,49 @@
+/**
+ * 결재 액션 핸들러 중앙 등록소
+ * 
+ * 모든 결재 가능한 액션의 핸들러를 한 곳에서 등록
+ * instrumentation.ts 또는 Next.js middleware에서 import하여 초기화
+ */
+
+import { registerActionHandler } from './approval-workflow';
+
+/**
+ * 모든 핸들러를 등록하는 초기화 함수
+ * 앱 시작 시 한 번만 호출
+ */
+export async function initializeApprovalHandlers() {
+  console.log('[Approval Handlers] Registering all handlers...');
+
+  // 1. PQ 실사 관련 핸들러
+  const { 
+    requestPQInvestigationInternal,
+    reRequestPQInvestigationInternal
+  } = await import('@/lib/vendor-investigation/handlers');
+  
+  // PQ 실사의뢰 핸들러 등록
+  registerActionHandler('pq_investigation_request', requestPQInvestigationInternal);
+  
+  // PQ 실사 재의뢰 핸들러 등록
+  registerActionHandler('pq_investigation_rerequest', reRequestPQInvestigationInternal);
+
+  // 2. 발주 요청 핸들러
+  // const { createPurchaseOrderInternal } = await import('@/lib/purchase-order/handlers');
+  // registerActionHandler('purchase_order_request', createPurchaseOrderInternal);
+
+  // 3. 계약 승인 핸들러
+  // const { approveContractInternal } = await import('@/lib/contract/handlers');
+  // registerActionHandler('contract_approval', approveContractInternal);
+
+  // ... 추가 핸들러 등록
+
+  console.log('[Approval Handlers] All handlers registered successfully');
+}
+
+/**
+ * 등록된 모든 핸들러 목록 조회 (디버깅용)
+ */
+export async function listRegisteredHandlers() {
+  const { getRegisteredHandlers } = await import('./approval-workflow');
+  return await getRegisteredHandlers();
+}
+
diff --git a/lib/approval/index.ts b/lib/approval/index.ts
new file mode 100644
index 00000000..644c5fa8
--- /dev/null
+++ b/lib/approval/index.ts
@@ -0,0 +1,34 @@
+/**
+ * 결재 워크플로우 모듈 Export
+ * 
+ * 사용 방법:
+ * 1. registerActionHandler()로 액션 핸들러 등록
+ * 2. withApproval()로 결재가 필요한 액션 래핑
+ * 3. 폴링 서비스가 자동으로 상태 확인 및 실행
+ */
+
+export {
+  registerActionHandler,
+  getRegisteredHandlers,
+  withApproval,
+  executeApprovedAction,
+  handleRejectedAction,
+  type ActionHandler,
+} from './approval-workflow';
+
+export {
+  startApprovalPollingScheduler,
+  checkPendingApprovals,
+  checkSingleApprovalStatus,
+} from './approval-polling-service';
+
+export {
+  getApprovalTemplateByName,
+  replaceTemplateVariables,
+  htmlTableConverter,
+  htmlListConverter,
+  htmlDescriptionList,
+} from './template-utils';
+
+export type { TemplateVariables, ApprovalConfig, ApprovalResult } from './types';
+
diff --git a/lib/approval/template-utils.ts b/lib/approval/template-utils.ts
new file mode 100644
index 00000000..a39f8ac4
--- /dev/null
+++ b/lib/approval/template-utils.ts
@@ -0,0 +1,215 @@
+/**
+ * 결재 템플릿 유틸리티 함수
+ * 
+ * 기능:
+ * - 템플릿 이름으로 조회
+ * - 변수 치환 ({{변수명}})
+ * - HTML 변환 유틸리티 (테이블, 리스트)
+ */
+
+'use server';
+
+import db from '@/db/db';
+import { eq } from 'drizzle-orm';
+import { approvalTemplates } from '@/db/schema/knox/approvals';
+
+/**
+ * 템플릿 이름으로 조회
+ * 
+ * @param name - 템플릿 이름 (한국어)
+ * @returns 템플릿 객체 또는 null
+ */
+export async function getApprovalTemplateByName(name: string) {
+  try {
+    const [template] = await db
+      .select()
+      .from(approvalTemplates)
+      .where(eq(approvalTemplates.name, name))
+      .limit(1);
+
+    return template || null;
+  } catch (error) {
+    console.error(`[Template Utils] Failed to get template: ${name}`, error);
+    return null;
+  }
+}
+
+/**
+ * 템플릿 변수 치환
+ * 
+ * {{변수명}} 형태의 변수를 실제 값으로 치환
+ * 
+ * @param content - 템플릿 HTML 내용
+ * @param variables - 변수 매핑 객체
+ * @returns 치환된 HTML
+ * 
+ * @example
+ * ```typescript
+ * const content = "<p>{{이름}}님, 안녕하세요</p>";
+ * const variables = { "이름": "홍길동" };
+ * const result = await replaceTemplateVariables(content, variables);
+ * // "<p>홍길동님, 안녕하세요</p>"
+ * ```
+ */
+export async function replaceTemplateVariables(
+  content: string,
+  variables: Record<string, string>
+): Promise<string> {
+  let result = content;
+
+  Object.entries(variables).forEach(([key, value]) => {
+    // {{변수명}} 패턴을 전역으로 치환
+    const pattern = new RegExp(`\\{\\{${escapeRegex(key)}\\}\\}`, 'g');
+    result = result.replace(pattern, value);
+  });
+
+  // 치환되지 않은 변수 로그 (디버깅용)
+  const remainingVariables = result.match(/\{\{[^}]+\}\}/g);
+  if (remainingVariables && remainingVariables.length > 0) {
+    console.warn(
+      '[Template Utils] Unmatched variables found:',
+      remainingVariables
+    );
+  }
+
+  return result;
+}
+
+/**
+ * 정규식 특수문자 이스케이프
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * 배열 데이터를 HTML 테이블로 변환 (공통 유틸)
+ * 
+ * @param data - 테이블 데이터 배열
+ * @param columns - 컬럼 정의 (키, 라벨)
+ * @returns HTML 테이블 문자열
+ * 
+ * @example
+ * ```typescript
+ * const data = [
+ *   { name: "홍길동", age: 30 },
+ *   { name: "김철수", age: 25 }
+ * ];
+ * const columns = [
+ *   { key: "name", label: "이름" },
+ *   { key: "age", label: "나이" }
+ * ];
+ * const html = await htmlTableConverter(data, columns);
+ * ```
+ */
+export async function htmlTableConverter(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data: Array<Record<string, any>>,
+  columns: Array<{ key: string; label: string }>
+): Promise<string> {
+  if (!data || data.length === 0) {
+    return '<p class="text-gray-500">데이터가 없습니다.</p>';
+  }
+
+  const headerRow = columns
+    .map(
+      (col) =>
+        `<th class="border border-gray-300 px-4 py-2 bg-gray-100 font-semibold text-left">${col.label}</th>`
+    )
+    .join('');
+
+  const bodyRows = data
+    .map((row) => {
+      const cells = columns
+        .map((col) => {
+          const value = row[col.key];
+          const displayValue =
+            value !== undefined && value !== null ? String(value) : '-';
+          return `<td class="border border-gray-300 px-4 py-2">${displayValue}</td>`;
+        })
+        .join('');
+      return `<tr>${cells}</tr>`;
+    })
+    .join('');
+
+  return `
+    <table class="w-full border-collapse border border-gray-300 my-4">
+      <thead>
+        <tr>${headerRow}</tr>
+      </thead>
+      <tbody>
+        ${bodyRows}
+      </tbody>
+    </table>
+  `;
+}
+
+/**
+ * 배열을 HTML 리스트로 변환
+ * 
+ * @param items - 리스트 아이템 배열
+ * @param ordered - 순서 있는 리스트 여부 (기본: false)
+ * @returns HTML 리스트 문자열
+ * 
+ * @example
+ * ```typescript
+ * const items = ["첫 번째", "두 번째", "세 번째"];
+ * const html = await htmlListConverter(items, true);
+ * ```
+ */
+export async function htmlListConverter(
+  items: string[],
+  ordered: boolean = false
+): Promise<string> {
+  if (!items || items.length === 0) {
+    return '<p class="text-gray-500">항목이 없습니다.</p>';
+  }
+
+  const listItems = items
+    .map((item) => `<li class="mb-1">${item}</li>`)
+    .join('');
+
+  const tag = ordered ? 'ol' : 'ul';
+  const listClass = ordered
+    ? 'list-decimal list-inside my-4'
+    : 'list-disc list-inside my-4';
+
+  return `<${tag} class="${listClass}">${listItems}</${tag}>`;
+}
+
+/**
+ * 키-값 쌍을 HTML 정의 목록으로 변환
+ * 
+ * @param items - 키-값 쌍 배열
+ * @returns HTML dl 태그
+ * 
+ * @example
+ * ```typescript
+ * const items = [
+ *   { label: "협력업체명", value: "ABC 주식회사" },
+ *   { label: "사업자등록번호", value: "123-45-67890" }
+ * ];
+ * const html = await htmlDescriptionList(items);
+ * ```
+ */
+export async function htmlDescriptionList(
+  items: Array<{ label: string; value: string }>
+): Promise<string> {
+  if (!items || items.length === 0) {
+    return '<p class="text-gray-500">정보가 없습니다.</p>';
+  }
+
+  const listItems = items
+    .map(
+      (item) => `
+      <div class="flex border-b border-gray-200 py-2">
+        <dt class="w-1/3 font-semibold text-gray-700">${item.label}</dt>
+        <dd class="w-2/3 text-gray-900">${item.value}</dd>
+      </div>
+    `
+    )
+    .join('');
+
+  return `<dl class="my-4">${listItems}</dl>`;
+}
+
diff --git a/lib/approval/types.ts b/lib/approval/types.ts
new file mode 100644
index 00000000..7f3fe52b
--- /dev/null
+++ b/lib/approval/types.ts
@@ -0,0 +1,25 @@
+/**
+ * 결재 워크플로우 타입 정의
+ */
+
+export type TemplateVariables = Record<string, string>;
+
+export interface ApprovalConfig {
+  title: string;
+  description?: string;
+  templateName: string;
+  variables: TemplateVariables;
+  approvers?: string[];
+  currentUser: { 
+    id: number; 
+    epId: string | null;
+    email?: string;
+  };
+}
+
+export interface ApprovalResult {
+  pendingActionId: number;
+  approvalId: string;
+  status: 'pending_approval';
+}
+