(김준회) 공통 컴포넌트 이해를 위한 문서 추가

3 files changed, 1021 insertions, 24 deletions

diff --git a/lib/approval/CRONJOB_CONTEXT_FIX.md b/lib/approval/CRONJOB_CONTEXT_FIX.md
new file mode 100644
index 00000000..a8169a5e
--- /dev/null
+++ b/lib/approval/CRONJOB_CONTEXT_FIX.md
@@ -0,0 +1,278 @@
+# Cronjob Request Context 문제 해결
+
+## 🔍 문제 상황
+
+결재 완료 후 `pendingActions`에서 핸들러를 호출할 때, **node-cron의 cronjob이 함수를 호출하므로 Request Context가 없어** 다음 문제가 발생했습니다:
+
+```
+❌ Error: `headers` was called outside a request scope.
+❌ Error: Invariant: static generation store missing in revalidateTag
+```
+
+### 발생 위치
+
+- `lib/vendors/service.ts` - `approveVendors()`, `rejectVendors()`
+- Next.js의 `headers()`, `revalidateTag()` 등의 API 사용
+
+### 근본 원인
+
+```typescript
+Cronjob (node-cron)
+  ↓ (Request Context 없음)
+ApprovalExecutionSaga
+  ↓
+Handler (예: approveVendorWithMDGInternal)
+  ↓
+approveVendors() 
+  ↓ headers() ❌  - AsyncLocalStorage에 접근 불가
+  ↓ revalidateTag() ❌ - Static generation store 없음
+```
+
+## ✅ 해결 방법
+
+### 1. API 기반 Revalidation 사용
+
+Request Context가 없는 환경에서는 **내부 API를 호출**하여 캐시를 무효화합니다.
+
+```typescript
+// ❌ Before: 직접 호출 (Request Context 필요)
+revalidateTag("vendors");
+revalidateTag("users");
+
+// ✅ After: API 호출 (Request Context 불필요)
+const { revalidateApprovalRelatedCaches } = await import('@/lib/revalidation-utils');
+await revalidateApprovalRelatedCaches();
+```
+
+### 2. 환경변수로 BaseURL 구성
+
+`headers()`를 사용하는 대신 환경변수를 사용합니다.
+
+```typescript
+// ❌ Before: headers()로 동적 구성
+const headersList = await headers();
+const host = headersList.get('host') || 'localhost:3000';
+const protocol = headersList.get('x-forwarded-proto') || 'http';
+const baseUrl = `${protocol}://${host}`;
+
+// ✅ After: 환경변수 사용
+const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000';
+```
+
+## 📁 변경된 파일
+
+### 1. 새로 추가된 파일
+
+#### `lib/revalidation-utils.ts`
+Request Context가 없는 환경에서 캐시를 무효화하기 위한 유틸리티 함수들:
+
+```typescript
+// 범용 revalidation
+await revalidateViaCronJob({ tags: ['vendors', 'users'] });
+
+// 특정 도메인별 revalidation
+await revalidateVendorCaches();
+await revalidateUserCaches();
+await revalidateApprovalRelatedCaches();
+```
+
+### 2. 수정된 파일
+
+#### `lib/vendors/service.ts`
+
+**approveVendors() 함수:**
+- ✅ `headers()` 제거 → `process.env.NEXT_PUBLIC_BASE_URL` 사용
+- ✅ `revalidateTag()` 제거 → `revalidateApprovalRelatedCaches()` 사용
+
+**rejectVendors() 함수:**
+- ✅ `headers()` 제거 → `process.env.NEXT_PUBLIC_BASE_URL` 사용
+- ✅ `revalidateTag()` 제거 → `revalidateVendorCaches()`, `revalidateUserCaches()` 사용
+
+## 🔧 설정 필요
+
+### 환경변수 설정
+
+`.env` 파일에 다음 환경변수를 추가하세요:
+
+```bash
+# 애플리케이션 Base URL (이메일 링크 등에 사용)
+NEXT_PUBLIC_BASE_URL=https://your-domain.com
+
+# Revalidation API 보안 (선택사항)
+REVALIDATION_SECRET=your-secret-key
+```
+
+**개발 환경:**
+```bash
+NEXT_PUBLIC_BASE_URL=http://localhost:3000
+```
+
+**프로덕션 환경:**
+```bash
+NEXT_PUBLIC_BASE_URL=https://evcp.your-company.com
+```
+
+## 🎯 작동 방식
+
+### 1. Cronjob에서 핸들러 실행
+
+```typescript
+// lib/approval/approval-polling-service.ts
+const saga = new ApprovalExecutionSaga(apInfId);
+await saga.execute(); // ← Request Context 없음
+```
+
+### 2. 핸들러에서 Service 함수 호출
+
+```typescript
+// lib/vendors/approval-handlers.ts
+export async function approveVendorWithMDGInternal(payload) {
+  // MDG 전송...
+  
+  const approveResult = await approveVendors({
+    ids: payload.vendorIds,
+    userId: payload.userId,
+  }); // ← Request Context 없는 상태로 호출됨
+}
+```
+
+### 3. Service에서 API 기반 Revalidation
+
+```typescript
+// lib/vendors/service.ts
+export async function approveVendors(input) {
+  await db.transaction(async (tx) => {
+    // 1. 벤더 승인 처리
+    // 2. 이메일 발송 (✅ 환경변수 사용)
+    const baseUrl = process.env.NEXT_PUBLIC_BASE_URL;
+    const loginUrl = `${baseUrl}/${userLang}/login`;
+  });
+  
+  // 3. 캐시 무효화 (✅ API 호출 사용)
+  const { revalidateApprovalRelatedCaches } = await import('@/lib/revalidation-utils');
+  await revalidateApprovalRelatedCaches();
+}
+```
+
+### 4. Revalidation Utils에서 내부 API 호출
+
+```typescript
+// lib/revalidation-utils.ts
+export async function revalidateViaCronJob(options) {
+  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000';
+  
+  const response = await fetch(`${baseUrl}/api/revalidate/approval`, {
+    method: 'POST',
+    body: JSON.stringify({
+      tags: options.tags,
+      secret: process.env.REVALIDATION_SECRET,
+    }),
+  });
+  
+  return response.json();
+}
+```
+
+### 5. API Route에서 실제 Revalidation 실행
+
+```typescript
+// app/api/revalidate/approval/route.ts
+export async function POST(request: NextRequest) {
+  // ✅ 여기는 HTTP Request Context가 있음!
+  const { tags } = await request.json();
+  
+  for (const tag of tags) {
+    revalidateTag(tag); // ✅ Request Context가 있으므로 작동함
+  }
+  
+  return Response.json({ success: true });
+}
+```
+
+## 📊 흐름도
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Cronjob (node-cron) - 1분마다                        │
+│ Request Context: ❌ 없음                             │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│ ApprovalExecutionSaga                                │
+│ - Knox 결재 상태 확인                                │
+│ - 승인된 경우 Handler 실행                           │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│ approveVendorWithMDGInternal()                       │
+│ - MDG 전송                                           │
+│ - approveVendors() 호출                              │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│ approveVendors() - lib/vendors/service.ts            │
+│ ✅ baseUrl = process.env.NEXT_PUBLIC_BASE_URL        │
+│ ✅ await revalidateViaCronJob({ tags: [...] })      │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│ revalidateViaCronJob() - lib/revalidation-utils.ts  │
+│ ✅ fetch('/api/revalidate/approval', ...)           │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│ POST /api/revalidate/approval                        │
+│ Request Context: ✅ 있음!                            │
+│ ✅ revalidateTag() 사용 가능                         │
+└─────────────────────────────────────────────────────┘
+```
+
+## 🚨 주의사항
+
+### 1. 환경변수 설정 필수
+
+`NEXT_PUBLIC_BASE_URL`이 설정되지 않으면 `http://localhost:3000`이 기본값으로 사용됩니다. 프로덕션에서는 반드시 설정하세요.
+
+### 2. 이메일 링크 정확성
+
+이메일에 포함되는 링크가 올바른 도메인을 가리키는지 확인하세요:
+
+```typescript
+// 로그인 링크 예시
+https://evcp.your-company.com/ko/login
+
+// 비밀번호 재설정 링크 예시
+https://evcp.your-company.com/ko/auth/reset-password?token=xxxxx
+```
+
+### 3. Revalidation API 보안
+
+`REVALIDATION_SECRET`을 설정하여 외부에서 무단으로 캐시를 무효화하는 것을 방지할 수 있습니다 (선택사항).
+
+### 4. 다른 Service 함수에도 적용
+
+`lib/vendors/service.ts`의 다른 함수들도 동일한 패턴을 사용해야 할 수 있습니다:
+
+- `requestPQVendors()` - line 3210-3215에 `revalidateTag()` 사용
+- 기타 `headers()` 또는 `revalidateTag()`를 사용하는 함수들
+
+필요시 동일한 패턴으로 수정하세요.
+
+## 🎉 결과
+
+이제 cronjob에서 핸들러가 실행되어도 다음과 같이 정상 작동합니다:
+
+```bash
+✅ [ExecutionSaga] Step 5: Executing action
+✅ [Vendor Approval Handler] MDG 전송 성공
+✅ [Vendor Approval Handler] 벤더 승인 완료
+✅ [Revalidation] Cache invalidated: vendors, users, roles
+✅ [ExecutionSaga] ✓ Action executed
+```
+
+## 📚 참고 자료
+
+- [Next.js Dynamic APIs](https://nextjs.org/docs/messages/next-dynamic-api-wrong-context)
+- [Next.js Revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/revalidating)
+- [AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage)
+
diff --git a/lib/approval/README.md b/lib/approval/README.md
index 40f783c9..7e62a1d7 100644
--- a/lib/approval/README.md
+++ b/lib/approval/README.md
@@ -360,29 +360,56 @@ export async function requestMyActionWithApproval(data: {
 }
 ```
 
-### Step 4: UI에서 호출
+### Step 4: UI에서 호출 (미리보기 다이얼로그 사용)
+
+**⚠️ 중요: 모든 결재 상신은 반드시 미리보기 다이얼로그를 거쳐야 합니다.**
+
+사용자가 결재 문서 내용을 확인하고 결재선을 직접 설정하는 과정이 필수입니다.
 
 ```typescript
-// components/my-feature/my-dialog.tsx
+// components/my-feature/my-dialog-with-preview.tsx
 'use client';
 
+import { useState } from 'react';
+import { ApprovalPreviewDialog } from '@/lib/approval/client'; // ⚠️ /client에서 import
 import { requestMyActionWithApproval } from '@/lib/my-feature/approval-actions';
 import { useSession } from 'next-auth/react';
 
-export function MyDialog() {
+export function MyDialogWithPreview() {
   const { data: session } = useSession();
+  const [showPreview, setShowPreview] = useState(false);
+  const [previewData, setPreviewData] = useState(null);
+  
+  const handleApproveClick = async (formData) => {
+    // 1. 템플릿 변수 준비
+    const variables = await prepareTemplateVariables(formData);
+    
+    // 2. 미리보기 데이터 설정
+    setPreviewData({
+      variables,
+      title: `내 기능 요청 - ${formData.id}`,
+      description: `ID ${formData.id}에 대한 승인 요청`,
+      formData, // 나중에 사용할 데이터 저장
+    });
+    
+    // 3. 미리보기 다이얼로그 열기
+    setShowPreview(true);
+  };
   
-  const handleSubmit = async (formData) => {
+  const handlePreviewConfirm = async (approvalData: {
+    approvers: string[];
+    title: string;
+    description?: string;
+  }) => {
     try {
       const result = await requestMyActionWithApproval({
-        id: formData.id,
-        reason: formData.reason,
+        ...previewData.formData,
         currentUser: {
           id: Number(session?.user?.id),
           epId: session?.user?.epId || null,
           email: session?.user?.email || undefined,
         },
-        approvers: selectedApprovers,
+        approvers: approvalData.approvers, // 미리보기에서 설정한 결재선
       });
       
       if (result.status === 'pending_approval') {
@@ -393,10 +420,40 @@ export function MyDialog() {
     }
   };
   
-  return <form onSubmit={handleSubmit}>...</form>;
+  return (
+    <>
+      <Button onClick={handleApproveClick}>결재 요청</Button>
+      
+      {/* 결재 미리보기 다이얼로그 */}
+      {previewData && session?.user?.epId && (
+        <ApprovalPreviewDialog
+          open={showPreview}
+          onOpenChange={setShowPreview}
+          templateName="내 기능 템플릿"
+          variables={previewData.variables}
+          title={previewData.title}
+          description={previewData.description}
+          currentUser={{
+            id: Number(session.user.id),
+            epId: session.user.epId,
+            name: session.user.name || undefined,
+            email: session.user.email || undefined,
+          }}
+          onConfirm={handlePreviewConfirm}
+        />
+      )}
+    </>
+  );
 }
 ```
 
+**미리보기 다이얼로그가 필수인 이유:**
+- ✅ 결재 문서 내용 최종 확인 (데이터 정확성 검증)
+- ✅ 결재선(결재자) 직접 선택 (올바른 결재 경로 설정)
+- ✅ 결재 제목/설명 커스터마이징 (명확한 의사소통)
+- ✅ 사용자가 결재 내용을 인지하고 책임감 있게 상신
+- ✅ 반응형 UI (Desktop: Dialog, Mobile: Drawer)
+
 ---
 
 ## 📚 API 레퍼런스
@@ -522,6 +579,74 @@ async function replaceTemplateVariables(
 ): Promise<string>
 ```
 
+### UI 컴포넌트
+
+#### ApprovalPreviewDialog
+
+결재 문서 미리보기 및 결재선 설정 다이얼로그 컴포넌트입니다.
+
+```typescript
+interface ApprovalPreviewDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  templateName: string;                    // DB에서 조회할 템플릿 이름
+  variables: Record<string, string>;       // 템플릿 변수
+  title: string;                           // 결재 제목
+  description?: string;                    // 결재 설명
+  currentUser: {
+    id: number;
+    epId: string;
+    name?: string;
+    email?: string;
+    deptName?: string;
+  };
+  defaultApprovers?: string[];             // 초기 결재선 (EP ID 배열)
+  onConfirm: (data: {
+    approvers: string[];
+    title: string;
+    description?: string;
+  }) => Promise<void>;
+  allowTitleEdit?: boolean;                // 제목 수정 허용 (기본: true)
+  allowDescriptionEdit?: boolean;          // 설명 수정 허용 (기본: true)
+}
+```
+
+**주요 기능:**
+- 템플릿 실시간 미리보기 (변수 자동 치환)
+- 결재선 선택 UI (ApprovalLineSelector 통합)
+- 제목/설명 수정
+- 반응형 디자인 (Desktop: Dialog, Mobile: Drawer)
+- 로딩 상태 자동 처리
+
+**사용 예시:**
+
+```typescript
+// ⚠️ 클라이언트 컴포넌트는 반드시 /client에서 import
+import { ApprovalPreviewDialog } from '@/lib/approval/client';
+
+<ApprovalPreviewDialog
+  open={showPreview}
+  onOpenChange={setShowPreview}
+  templateName="벤더 가입 승인 요청"
+  variables={{
+    '업체명': 'ABC 협력업체',
+    '담당자': '홍길동',
+    '요청일': '2024-11-06',
+  }}
+  title="협력업체 가입 승인"
+  description="ABC 협력업체의 가입을 승인합니다."
+  currentUser={{
+    id: 1,
+    epId: 'EP001',
+    name: '김철수',
+    email: 'kim@example.com',
+  }}
+  onConfirm={async ({ approvers, title, description }) => {
+    await submitApproval(approvers);
+  }}
+/>
+```
+
 ### 캐시 관리
 
 ```typescript
@@ -544,32 +669,35 @@ async function revalidateAllApprovalCaches(): Promise<void>
 
 ```
 lib/approval/
-├── approval-saga.ts              # Saga 클래스 (메인 로직)
+├── approval-saga.ts              # Saga 클래스 (메인 로직) [서버]
 │   ├── ApprovalSubmissionSaga    # 결재 상신
 │   ├── ApprovalExecutionSaga     # 액션 실행
 │   └── ApprovalRejectionSaga     # 반려 처리
 │
-├── approval-workflow.ts          # 핸들러 레지스트리
+├── approval-workflow.ts          # 핸들러 레지스트리 [서버]
 │   ├── registerActionHandler()
 │   ├── getRegisteredHandlers()
 │   └── ensureHandlersInitialized()
 │
-├── approval-polling-service.ts   # 폴링 서비스
+├── approval-polling-service.ts   # 폴링 서비스 [서버]
 │   ├── startApprovalPollingScheduler()
 │   ├── checkPendingApprovals()
 │   └── checkSingleApprovalStatus()
 │
-├── handlers-registry.ts          # 핸들러 중앙 등록소
+├── handlers-registry.ts          # 핸들러 중앙 등록소 [서버]
 │   └── initializeApprovalHandlers()
 │
-├── template-utils.ts             # 템플릿 유틸리티
+├── template-utils.ts             # 템플릿 유틸리티 [서버]
 │   ├── getApprovalTemplateByName()
 │   ├── replaceTemplateVariables()
 │   ├── htmlTableConverter()
 │   ├── htmlListConverter()
 │   └── htmlDescriptionList()
 │
-├── cache-utils.ts                # 캐시 관리
+├── approval-preview-dialog.tsx   # 결재 미리보기 다이얼로그 [클라이언트]
+│   └── ApprovalPreviewDialog     # 템플릿 미리보기 + 결재선 설정
+│
+├── cache-utils.ts                # 캐시 관리 [서버]
 │   ├── revalidateApprovalLogs()
 │   ├── revalidatePendingActions()
 │   └── revalidateApprovalDetail()
@@ -579,11 +707,31 @@ lib/approval/
 │   ├── ApprovalResult
 │   └── TemplateVariables
 │
-├── index.ts                      # 공개 API Export
+├── index.ts                      # 서버 전용 API Export
+├── client.ts                     # 클라이언트 컴포넌트 Export ⚠️
 │
 └── README.md                     # 이 문서
 ```
 
+### Import 경로 가이드
+
+**⚠️ 중요: 서버/클라이언트 코드는 반드시 분리해서 import 해야 합니다.**
+
+```typescript
+// ✅ 서버 액션 또는 서버 컴포넌트에서
+import { 
+  ApprovalSubmissionSaga,
+  getApprovalTemplateByName,
+  htmlTableConverter
+} from '@/lib/approval';
+
+// ✅ 클라이언트 컴포넌트에서
+import { ApprovalPreviewDialog } from '@/lib/approval/client';
+
+// ❌ 잘못된 사용 (서버 코드가 클라이언트 번들에 포함됨)
+import { ApprovalPreviewDialog } from '@/lib/approval';
+```
+
 ---
 
 ## 🛠️ 개발 가이드
@@ -635,6 +783,217 @@ INSERT INTO approval_templates (name, content, description) VALUES (
 
 끝! 폴링 서비스가 자동으로 처리합니다.
 
+### ⚠️ Request Context 주의사항 (필수)
+
+**핵심: 결재 핸들러는 Cronjob 환경에서 실행됩니다!**
+
+결재 승인 후 실행되는 핸들러는 **폴링 서비스(Cronjob)**에 의해 호출됩니다.  
+이 환경에서는 **Request Context가 존재하지 않으므로** 다음 함수들을 **절대 사용할 수 없습니다**:
+
+```typescript
+// ❌ Cronjob 환경에서 사용 불가
+import { headers } from 'next/headers';
+import { getServerSession } from 'next-auth';
+
+export async function myHandler(payload) {
+  const headersList = headers();              // ❌ Error: headers() called outside request scope
+  const session = await getServerSession();   // ❌ Error: cannot access request
+  revalidatePath('/some-path');               // ❌ Error: revalidatePath outside request scope
+}
+```
+
+#### 올바른 해결 방법
+
+**1. 유저 정보가 필요한 경우 → Payload에 포함**
+
+```typescript
+// ✅ 결재 상신 시 currentUser를 payload에 포함
+export async function requestWithApproval(data: RequestData) {
+  const saga = new ApprovalSubmissionSaga(
+    'my_action',
+    {
+      id: data.id,
+      currentUser: {  // ⚠️ 핸들러에서 필요한 유저 정보 포함
+        id: session.user.id,
+        name: session.user.name,
+        email: session.user.email,
+        epId: session.user.epId,
+      },
+    },
+    { ... }
+  );
+}
+
+// ✅ 핸들러에서 payload의 currentUser 사용
+export async function myHandlerInternal(payload: {
+  id: number;
+  currentUser: {
+    id: string | number;
+    name?: string | null;
+    email?: string | null;
+    epId?: string | null;
+  };
+}) {
+  // payload에서 유저 정보 사용
+  const userId = payload.currentUser.id;
+  
+  // DB 작업
+  await db.insert(myTable).values({
+    createdBy: userId,
+    ...
+  });
+}
+```
+
+**2. Session/Payload 분기 처리 (기존 함수 호환)**
+
+기존 함수를 cronjob과 일반 환경에서 모두 사용하려면 분기 처리:
+
+```typescript
+// ✅ Session/Payload 분기 처리
+export async function myServiceFunction({
+  id,
+  currentUser: providedUser  // 선택적 파라미터
+}: {
+  id: number;
+  currentUser?: {
+    id: string | number;
+    name?: string | null;
+    email?: string | null;
+  };
+}) {
+  let currentUser;
+
+  if (providedUser) {
+    // ✅ Cronjob 환경: payload에서 받은 유저 정보 사용
+    currentUser = providedUser;
+  } else {
+    // ✅ 일반 환경: session에서 유저 정보 가져오기
+    const session = await getServerSession(authOptions);
+    if (!session?.user) {
+      throw new Error("인증이 필요합니다.");
+    }
+    currentUser = session.user;
+  }
+  
+  // 이제 currentUser 안전하게 사용 가능
+  await db.insert(...).values({
+    createdBy: currentUser.id,
+    ...
+  });
+}
+```
+
+**3. Revalidate는 API 경로 사용**
+
+```typescript
+// ❌ 직접 호출 불가
+revalidatePath('/my-path');
+
+// ✅ API 경로를 통해 호출
+await fetch('/api/revalidate/my-resource', {
+  method: 'POST',
+});
+```
+
+#### 실제 사례: RFQ 발송
+
+```typescript
+// lib/rfq-last/service.ts
+export interface SendRfqParams {
+  rfqId: number;
+  vendors: VendorForSend[];
+  attachmentIds: number[];
+  currentUser?: {  // ⚠️ Cronjob 환경을 위한 선택적 파라미터
+    id: string | number;
+    name?: string | null;
+    email?: string | null;
+    epId?: string | null;
+  };
+}
+
+export async function sendRfqToVendors({
+  rfqId,
+  vendors,
+  attachmentIds,
+  currentUser: providedUser
+}: SendRfqParams) {
+  let currentUser;
+
+  if (providedUser) {
+    // ✅ Cronjob 환경: payload에서 받은 유저 정보 사용
+    currentUser = providedUser;
+  } else {
+    // ✅ 일반 환경: session에서 유저 정보 가져오기
+    const session = await getServerSession(authOptions);
+    if (!session?.user) {
+      throw new Error("인증이 필요합니다.");
+    }
+    currentUser = session.user;
+  }
+  
+  // ... 나머지 로직
+}
+
+// lib/rfq-last/approval-handlers.ts
+export async function sendRfqWithApprovalInternal(payload: {
+  rfqId: number;
+  vendors: any[];
+  attachmentIds: number[];
+  currentUser: {  // ⚠️ 필수 정보
+    id: string | number;
+    name?: string | null;
+    email?: string | null;
+    epId?: string | null;
+  };
+}) {
+  // ✅ payload의 currentUser를 서비스 함수에 전달
+  const result = await sendRfqToVendors({
+    rfqId: payload.rfqId,
+    vendors: payload.vendors,
+    attachmentIds: payload.attachmentIds,
+    currentUser: payload.currentUser,  // ⚠️ 전달
+  });
+  
+  return result;
+}
+
+// lib/rfq-last/approval-actions.ts
+export async function requestRfqSendWithApproval(data: RfqSendApprovalData) {
+  const saga = new ApprovalSubmissionSaga(
+    'rfq_send_with_attachments',
+    {
+      rfqId: data.rfqId,
+      vendors: data.vendors,
+      attachmentIds: data.attachmentIds,
+      currentUser: {  // ⚠️ payload에 포함
+        id: data.currentUser.id,
+        name: data.currentUser.name,
+        email: data.currentUser.email,
+        epId: data.currentUser.epId,
+      },
+    },
+    { ... }
+  );
+}
+```
+
+#### 체크리스트
+
+새로운 결재 핸들러를 작성할 때 다음을 확인하세요:
+
+- [ ] 핸들러 함수에서 `headers()` 사용하지 않음
+- [ ] 핸들러 함수에서 `getServerSession()` 직접 호출하지 않음
+- [ ] 핸들러 함수에서 `revalidatePath()` 직접 호출하지 않음
+- [ ] 유저 정보가 필요하면 payload에 `currentUser` 포함
+- [ ] 기존 서비스 함수는 session/payload 분기 처리
+- [ ] 캐시 무효화는 API 경로 사용
+
+#### 참고 문서
+
+- [CRONJOB_CONTEXT_FIX.md](./CRONJOB_CONTEXT_FIX.md) - Request Context 문제 상세 해결 가이드
+- [Next.js Dynamic API Error](https://nextjs.org/docs/messages/next-dynamic-api-wrong-context)
+
 ### 테스트하기
 
 ```typescript
@@ -878,10 +1237,87 @@ const saga = new ApprovalSubmissionSaga(...);
 await saga.execute();
 ```
 
+### 7. Request Context 오류 (headers/session) ⚠️
+
+**증상:**
+```
+Error: `headers` was called outside a request scope
+Error: Cannot access request in cronjob context
+```
+
+**원인:** 결재 핸들러는 Cronjob 환경에서 실행되므로 Request Context가 없음
+
+**해결:**
+
+```typescript
+// ❌ 잘못된 코드
+export async function myHandler(payload) {
+  const session = await getServerSession(authOptions);  // ❌ Error!
+  const userId = session.user.id;
+}
+
+// ✅ 올바른 코드 - payload에서 유저 정보 사용
+export async function myHandler(payload: {
+  id: number;
+  currentUser: {
+    id: string | number;
+    name?: string | null;
+    email?: string | null;
+  };
+}) {
+  const userId = payload.currentUser.id;  // ✅ OK
+}
+
+// ✅ 결재 상신 시 currentUser 포함
+const saga = new ApprovalSubmissionSaga(
+  'my_action',
+  {
+    id: data.id,
+    currentUser: {  // ⚠️ 필수
+      id: session.user.id,
+      name: session.user.name,
+      email: session.user.email,
+      epId: session.user.epId,
+    },
+  },
+  { ... }
+);
+```
+
+**기존 서비스 함수 호환:**
+
+```typescript
+// ✅ Session/Payload 분기 처리
+export async function myServiceFunction({
+  id,
+  currentUser: providedUser
+}: {
+  id: number;
+  currentUser?: { id: string | number; ... };
+}) {
+  let currentUser;
+
+  if (providedUser) {
+    // Cronjob 환경
+    currentUser = providedUser;
+  } else {
+    // 일반 환경
+    const session = await getServerSession(authOptions);
+    currentUser = session.user;
+  }
+  
+  // 안전하게 사용
+  await db.insert(...).values({ createdBy: currentUser.id });
+}
+```
+
+**자세한 내용:** [Request Context 주의사항](#️-request-context-주의사항-필수) 섹션 참조
+
 ---
 
 ## 📖 추가 문서
 
+- **[CRONJOB_CONTEXT_FIX.md](./CRONJOB_CONTEXT_FIX.md)** - Request Context 문제 상세 해결 가이드 ⚠️
 - **[SAGA_PATTERN.md](./SAGA_PATTERN.md)** - Saga 패턴 상세 설명 및 리팩터링 과정
 - **[README_CACHE.md](./README_CACHE.md)** - 캐시 전략 및 관리 방법
 - **[USAGE_PATTERN_ANALYSIS.md](./USAGE_PATTERN_ANALYSIS.md)** - 실제 사용 패턴 분석 및 개선 제안
@@ -895,6 +1331,7 @@ await saga.execute();
 - ✅ 비즈니스 액션에 결재 승인이 필요한 경우
 - ✅ Knox 결재 시스템과 자동 연동이 필요한 경우
 - ✅ 결재 승인 후 자동으로 액션을 실행하고 싶은 경우
+- ✅ **모든 결재는 미리보기 다이얼로그를 통해 상신해야 함 (필수)**
 
 ### 왜 Saga 패턴인가?
 - ✅ Knox는 외부 시스템 → 일반 트랜잭션 불가
@@ -904,27 +1341,56 @@ await saga.execute();
 ### 어떻게 사용하는가?
 
 1. **핸들러 작성 및 등록** (1회)
-2. **Saga로 결재 상신** (필요할 때마다)
-3. **폴링이 자동 실행** (설정만 하면 끝)
+2. **UI에서 미리보기 다이얼로그 열기** (필수)
+3. **사용자가 결재선 설정 후 상신**
+4. **폴링이 자동 실행** (설정만 하면 끝)
 
-### 코드 3줄 요약
+### 코드 요약
 
 ```typescript
-// 1. 핸들러 등록
+// 1. 핸들러 등록 (서버 시작 시 1회)
 registerActionHandler('my_action', myActionHandler);
 
-// 2. 결재 상신
-const saga = new ApprovalSubmissionSaga('my_action', payload, config);
-const result = await saga.execute();
+// 2. UI에서 미리보기 다이얼로그 열기
+const { variables } = await prepareTemplateVariables(data);
+setShowPreview(true);
+
+// 3. 사용자가 확인 후 결재 상신
+<ApprovalPreviewDialog
+  templateName="내 템플릿"
+  variables={variables}
+  onConfirm={async ({ approvers }) => {
+    await submitApproval(approvers);
+  }}
+/>
 
-// 3. 끝! (폴링이 자동 실행)
+// 4. 끝! (폴링이 자동 실행)
 ```
 
 ---
 
 ## 📝 변경 이력
 
-### 2024-11 - Saga 패턴 전면 리팩터링
+### 2024-11-06 - Request Context 호환성 개선 (RFQ 발송)
+- ✅ Cronjob 환경에서 Request Context 오류 해결
+- ✅ `headers()`, `getServerSession()` 호출 문제 수정
+- ✅ Session/Payload 분기 처리 패턴 도입
+- ✅ `currentUser`를 payload에 포함하는 표준 패턴 확립
+- ✅ 기존 서비스 함수 호환성 유지 (선택적 `currentUser` 파라미터)
+- ✅ RFQ 발송 핸들러에 적용 및 검증
+- ✅ README에 "Request Context 주의사항" 섹션 추가
+- ✅ 트러블슈팅 가이드 업데이트
+
+### 2024-11-06 - 결재 미리보기 다이얼로그 도입
+- ✅ `ApprovalPreviewDialog` 공통 컴포넌트 추가
+- ✅ 모든 결재 상신은 미리보기를 거치도록 프로세스 변경
+- ✅ 사용자가 결재 문서와 결재선을 확인하는 필수 단계 추가
+- ✅ 템플릿 실시간 미리보기 및 변수 치환 기능
+- ✅ 결재선 선택 UI 통합 (ApprovalLineSelector)
+- ✅ 반응형 디자인 (Desktop: Dialog, Mobile: Drawer)
+- ✅ 서버/클라이언트 코드 분리 (`index.ts` / `client.ts`)
+
+### 2024-11-05 - Saga 패턴 전면 리팩터링
 - ✅ 기존 래퍼 함수 제거
 - ✅ Saga Orchestrator 클래스 도입
 - ✅ 비즈니스 프로세스 명시화 (7단계)
diff --git a/lib/approval/README_CACHE.md b/lib/approval/README_CACHE.md
new file mode 100644
index 00000000..b7bee00f
--- /dev/null
+++ b/lib/approval/README_CACHE.md
@@ -0,0 +1,253 @@
+# 결재 시스템 캐시 무효화 가이드
+
+## 문제 상황
+
+Next.js는 서버 컴포넌트의 데이터 fetch 결과를 자동으로 캐시합니다. 결재 시스템에서 `withApproval()`로 결재를 상신하거나 폴링 서비스가 결재를 승인/반려 처리해도 캐시가 무효화되지 않아 페이지에 최신 데이터가 표시되지 않는 문제가 있었습니다.
+
+특히 **백그라운드 프로세스** (폴링 서비스)에서는 Next.js의 `revalidateTag`를 직접 사용할 수 없습니다. `revalidateTag`는 request 컨텍스트가 필요한데, 백그라운드에서는 이 컨텍스트가 존재하지 않기 때문입니다.
+
+## 해결 방법
+
+API 라우트를 통한 캐시 무효화 시스템을 구축했습니다.
+
+### 1. 캐시 태그 시스템
+
+결재 관련 데이터에 캐시 태그를 추가:
+
+```typescript
+// lib/approval-log/service.ts
+export async function getApprovalLogList(input: ListInput) {
+  return unstable_cache(
+    async () => {
+      // ... 데이터 조회 로직
+    },
+    [cacheKey],
+    {
+      tags: ['approval-logs'], // 🏷️ 캐시 태그
+      revalidate: 60, // 60초마다 자동 재검증 (폴백)
+    }
+  )();
+}
+```
+
+### 2. 캐시 무효화 API
+
+백그라운드에서도 사용 가능한 API 라우트:
+
+```typescript
+// app/api/revalidate/approval/route.ts
+export async function POST(request: NextRequest) {
+  const { tags } = await request.json();
+  
+  // 캐시 태그 무효화
+  for (const tag of tags) {
+    revalidateTag(tag);
+  }
+  
+  return NextResponse.json({ success: true });
+}
+```
+
+### 3. 캐시 무효화 헬퍼 함수
+
+편리하게 사용할 수 있는 유틸리티:
+
+```typescript
+// lib/approval/cache-utils.ts
+
+// 결재 로그 캐시 무효화
+export async function revalidateApprovalLogs() {
+  await fetch('/api/revalidate/approval', {
+    method: 'POST',
+    body: JSON.stringify({ tags: ['approval-logs'] })
+  });
+}
+
+// 모든 결재 관련 캐시 무효화
+export async function revalidateAllApprovalCaches() {
+  await fetch('/api/revalidate/approval', {
+    method: 'POST',
+    body: JSON.stringify({
+      tags: ['approval-logs', 'pending-actions', 'approval-templates']
+    })
+  });
+}
+```
+
+### 4. 워크플로우에 통합
+
+결재 상신/승인/반려 시 자동으로 캐시 무효화:
+
+```typescript
+// lib/approval/approval-workflow.ts
+
+export async function withApproval(...) {
+  // ... 결재 상신 로직
+  
+  // 캐시 무효화
+  await revalidateApprovalLogs();
+  
+  return result;
+}
+
+export async function executeApprovedAction(apInfId: string) {
+  // ... 액션 실행 로직
+  
+  // 캐시 무효화 (백그라운드에서도 동작! ✨)
+  await revalidateApprovalLogs();
+  
+  return result;
+}
+
+export async function handleRejectedAction(apInfId: string, reason?: string) {
+  // ... 반려 처리 로직
+  
+  // 캐시 무효화
+  await revalidateApprovalLogs();
+}
+```
+
+## 동작 원리
+
+```mermaid
+sequenceDiagram
+    participant BG as 백그라운드 프로세스<br/>(폴링 서비스)
+    participant API as API 라우트<br/>/api/revalidate/approval
+    participant Cache as Next.js 캐시
+    participant Page as 결재 로그 페이지
+
+    BG->>BG: 결재 승인 처리
+    BG->>API: POST /api/revalidate/approval<br/>{ tags: ['approval-logs'] }
+    API->>Cache: revalidateTag('approval-logs')
+    Cache-->>Cache: 캐시 무효화 ✅
+    
+    Note over Page: 사용자가 페이지 접속
+    Page->>Cache: 데이터 요청
+    Cache->>Page: 최신 데이터 반환 🎉
+```
+
+## 사용 예시
+
+### 예시 1: 새로운 결재 액션에 캐시 무효화 추가
+
+```typescript
+// lib/my-feature/approval-actions.ts
+'use server';
+
+import { withApproval } from '@/lib/approval';
+
+export async function myActionWithApproval(data: MyData) {
+  // withApproval이 자동으로 캐시 무효화를 처리합니다
+  return await withApproval('my_action', data, {
+    templateName: '나의 액션 결재',
+    variables: { ... },
+    currentUser: { ... }
+  });
+}
+```
+
+### 예시 2: 수동으로 캐시 무효화
+
+```typescript
+import { revalidateApprovalLogs } from '@/lib/approval';
+
+// 필요한 시점에 수동으로 호출
+await revalidateApprovalLogs();
+```
+
+### 예시 3: 여러 캐시 동시 무효화
+
+```typescript
+import { revalidateApprovalCache } from '@/lib/approval';
+
+await revalidateApprovalCache([
+  'approval-logs',
+  'pending-actions',
+  'my-custom-cache'
+]);
+```
+
+## 캐시 태그 규칙
+
+| 태그 이름 | 적용 대상 | 무효화 시점 |
+|----------|---------|-----------|
+| `approval-logs` | 결재 로그 목록 | 결재 상신/승인/반려 시 |
+| `pending-actions` | 대기 중인 액션 목록 | 액션 실행/반려 시 |
+| `approval-log-${apInfId}` | 특정 결재 상세 | 해당 결재 상태 변경 시 |
+| `approval-templates` | 결재 템플릿 목록 | 템플릿 생성/수정/삭제 시 |
+
+## 보안 (선택사항)
+
+환경 변수로 시크릿 키를 설정하여 무단 접근 방지:
+
+```env
+# .env.local
+REVALIDATION_SECRET=your-secret-key-here
+```
+
+```typescript
+// lib/approval/cache-utils.ts
+await fetch('/api/revalidate/approval', {
+  method: 'POST',
+  body: JSON.stringify({
+    tags: ['approval-logs'],
+    secret: process.env.REVALIDATION_SECRET
+  })
+});
+```
+
+## 장점
+
+✅ **백그라운드 프로세스 지원**: 폴링 서비스에서도 캐시 무효화 가능  
+✅ **공통 솔루션**: 모든 결재 관련 페이지에 자동 적용  
+✅ **유연성**: 필요한 캐시만 선택적으로 무효화  
+✅ **신뢰성**: API 호출 실패해도 60초 후 자동 재검증 (폴백)  
+✅ **확장성**: 새로운 캐시 태그 추가 용이  
+
+## 주의사항
+
+⚠️ **과도한 무효화 방지**: 너무 자주 캐시를 무효화하면 성능 저하 발생  
+⚠️ **에러 처리**: 캐시 무효화 실패는 치명적이지 않으므로 로그만 남기고 진행  
+⚠️ **개발 환경**: 개발 환경에서는 캐싱이 비활성화될 수 있음  
+
+## 트러블슈팅
+
+### 문제: 캐시가 무효화되지 않음
+
+1. API 라우트가 올바르게 호출되는지 확인:
+   ```bash
+   # 로그 확인
+   [Approval Workflow] Revalidating cache after approval submission
+   [Cache Revalidation] Tag revalidated: approval-logs
+   ```
+
+2. 캐시 태그가 올바르게 설정되었는지 확인:
+   ```typescript
+   // getApprovalLogList에 tags: ['approval-logs'] 있는지 확인
+   ```
+
+3. 환경 변수 확인:
+   ```bash
+   # NEXT_PUBLIC_BASE_URL이 올바르게 설정되어 있는지
+   ```
+
+### 문제: API 호출이 실패함
+
+```typescript
+// cache-utils.ts에서 에러 로그 확인
+[Approval Cache] Failed to revalidate cache: Error: ...
+```
+
+원인:
+- 네트워크 이슈
+- 잘못된 BASE_URL
+- 시크릿 키 불일치
+
+해결: 로그를 확인하고 환경 변수를 점검하세요.
+
+## 참고 자료
+
+- [Next.js Caching Documentation](https://nextjs.org/docs/app/building-your-application/caching)
+- [revalidateTag API Reference](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
+- [unstable_cache API Reference](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)
+