feat: fetchWrapper 마이그레이션 및 토큰 리프레시 캐싱 구현

- 40+ actions.ts 파일을 fetchWrapper 패턴으로 마이그레이션
- 토큰 리프레시 캐싱 로직 추가 (refresh-token.ts)
- ApiErrorContext 추가로 전역 에러 처리 개선
- HR EmployeeForm 컴포넌트 개선
- 참조함(ReferenceBox) 기능 수정
- juil 테스트 URL 페이지 추가
- claudedocs 문서 업데이트

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/components/accounting/WithdrawalManagement/actions.ts

@@ -1,21 +1,8 @@
 'use server';
 
-import { cookies } from 'next/headers';
+import { serverFetch } from '@/lib/api/fetch-wrapper';
 import type { WithdrawalRecord, WithdrawalType } from './types';
 
-// ===== API 헤더 생성 =====
-async function getApiHeaders(): Promise<HeadersInit> {
-  const cookieStore = await cookies();
-  const token = cookieStore.get('access_token')?.value;
-
-  return {
-    'Accept': 'application/json',
-    'Content-Type': 'application/json',
-    'Authorization': token ? `Bearer ${token}` : '',
-    'X-API-KEY': process.env.API_KEY || '',
-  };
-}
-
 // ===== API 응답 타입 =====
 interface WithdrawalApiData {
   id: number;
@@ -58,6 +45,22 @@ function transformApiToFrontend(apiData: WithdrawalApiData): WithdrawalRecord {
   };
 }
 
+// ===== Frontend → API 변환 =====
+function transformFrontendToApi(data: Partial<WithdrawalRecord>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (data.withdrawalDate !== undefined) result.withdrawal_date = data.withdrawalDate;
+  if (data.withdrawalAmount !== undefined) result.withdrawal_amount = data.withdrawalAmount;
+  if (data.accountName !== undefined) result.account_name = data.accountName;
+  if (data.recipientName !== undefined) result.recipient_name = data.recipientName;
+  if (data.note !== undefined) result.note = data.note || null;
+  if (data.withdrawalType !== undefined) result.withdrawal_type = data.withdrawalType;
+  if (data.vendorId !== undefined) result.vendor_id = data.vendorId ? parseInt(data.vendorId, 10) : null;
+  if (data.vendorName !== undefined) result.vendor_name = data.vendorName || null;
+
+  return result;
+}
+
 // ===== 출금 내역 조회 =====
 export async function getWithdrawals(params?: {
   page?: number;
@@ -78,111 +81,91 @@ export async function getWithdrawals(params?: {
   };
   error?: string;
 }> {
-  try {
-    const headers = await getApiHeaders();
-    const searchParams = new URLSearchParams();
+  const searchParams = new URLSearchParams();
 
-    if (params?.page) searchParams.set('page', String(params.page));
-    if (params?.perPage) searchParams.set('per_page', String(params.perPage));
-    if (params?.startDate) searchParams.set('start_date', params.startDate);
-    if (params?.endDate) searchParams.set('end_date', params.endDate);
-    if (params?.withdrawalType && params.withdrawalType !== 'all') {
-      searchParams.set('withdrawal_type', params.withdrawalType);
-    }
-    if (params?.vendor && params.vendor !== 'all') {
-      searchParams.set('vendor', params.vendor);
-    }
-    if (params?.search) searchParams.set('search', params.search);
+  if (params?.page) searchParams.set('page', String(params.page));
+  if (params?.perPage) searchParams.set('per_page', String(params.perPage));
+  if (params?.startDate) searchParams.set('start_date', params.startDate);
+  if (params?.endDate) searchParams.set('end_date', params.endDate);
+  if (params?.withdrawalType && params.withdrawalType !== 'all') {
+    searchParams.set('withdrawal_type', params.withdrawalType);
+  }
+  if (params?.vendor && params.vendor !== 'all') {
+    searchParams.set('vendor', params.vendor);
+  }
+  if (params?.search) searchParams.set('search', params.search);
 
-    const queryString = searchParams.toString();
-    const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals${queryString ? `?${queryString}` : ''}`;
+  const queryString = searchParams.toString();
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals${queryString ? `?${queryString}` : ''}`;
 
-    const response = await fetch(url, {
-      method: 'GET',
-      headers,
-      cache: 'no-store',
-    });
+  const { response, error } = await serverFetch(url, { method: 'GET' });
 
-    if (!response.ok) {
-      console.warn('[WithdrawalActions] GET withdrawals error:', response.status);
-      return {
-        success: false,
-        data: [],
-        pagination: { currentPage: 1, lastPage: 1, perPage: 20, total: 0 },
-        error: `API 오류: ${response.status}`,
-      };
-    }
-
-    const result = await response.json();
-
-    if (!result.success) {
-      return {
-        success: false,
-        data: [],
-        pagination: { currentPage: 1, lastPage: 1, perPage: 20, total: 0 },
-        error: result.message || '출금 내역 조회에 실패했습니다.',
-      };
-    }
-
-    const withdrawals = (result.data || []).map(transformApiToFrontend);
-    const meta: PaginationMeta = result.meta || {
-      current_page: 1,
-      last_page: 1,
-      per_page: 20,
-      total: withdrawals.length,
-    };
-
-    return {
-      success: true,
-      data: withdrawals,
-      pagination: {
-        currentPage: meta.current_page,
-        lastPage: meta.last_page,
-        perPage: meta.per_page,
-        total: meta.total,
-      },
-    };
-  } catch (error) {
-    console.error('[WithdrawalActions] getWithdrawals error:', error);
+  if (error) {
     return {
       success: false,
       data: [],
       pagination: { currentPage: 1, lastPage: 1, perPage: 20, total: 0 },
-      error: '서버 오류가 발생했습니다.',
+      error: error.message,
     };
   }
+
+  if (!response?.ok) {
+    console.warn('[WithdrawalActions] GET withdrawals error:', response?.status);
+    return {
+      success: false,
+      data: [],
+      pagination: { currentPage: 1, lastPage: 1, perPage: 20, total: 0 },
+      error: `API 오류: ${response?.status}`,
+    };
+  }
+
+  const result = await response.json();
+
+  if (!result.success) {
+    return {
+      success: false,
+      data: [],
+      pagination: { currentPage: 1, lastPage: 1, perPage: 20, total: 0 },
+      error: result.message || '출금 내역 조회에 실패했습니다.',
+    };
+  }
+
+  const withdrawals = (result.data || []).map(transformApiToFrontend);
+  const meta: PaginationMeta = result.meta || {
+    current_page: 1,
+    last_page: 1,
+    per_page: 20,
+    total: withdrawals.length,
+  };
+
+  return {
+    success: true,
+    data: withdrawals,
+    pagination: {
+      currentPage: meta.current_page,
+      lastPage: meta.last_page,
+      perPage: meta.per_page,
+      total: meta.total,
+    },
+  };
 }
 
 // ===== 출금 내역 삭제 =====
 export async function deleteWithdrawal(id: string): Promise<{ success: boolean; error?: string }> {
-  try {
-    const headers = await getApiHeaders();
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`;
+  const { response, error } = await serverFetch(url, { method: 'DELETE' });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`,
-      {
-        method: 'DELETE',
-        headers,
-      }
-    );
-
-    const result = await response.json();
-
-    if (!response.ok || !result.success) {
-      return {
-        success: false,
-        error: result.message || '출금 내역 삭제에 실패했습니다.',
-      };
-    }
-
-    return { success: true };
-  } catch (error) {
-    console.error('[WithdrawalActions] deleteWithdrawal error:', error);
-    return {
-      success: false,
-      error: '서버 오류가 발생했습니다.',
-    };
+  if (error) {
+    return { success: false, error: error.message };
   }
+
+  const result = await response?.json();
+
+  if (!response?.ok || !result.success) {
+    return { success: false, error: result?.message || '출금 내역 삭제에 실패했습니다.' };
+  }
+
+  return { success: true };
 }
 
 // ===== 계정과목명 일괄 저장 =====
@@ -190,38 +173,26 @@ export async function updateWithdrawalTypes(
   ids: string[],
   withdrawalType: string
 ): Promise<{ success: boolean; error?: string }> {
-  try {
-    const headers = await getApiHeaders();
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/bulk-update-type`;
+  const { response, error } = await serverFetch(url, {
+    method: 'PUT',
+    body: JSON.stringify({
+      ids: ids.map(id => parseInt(id, 10)),
+      withdrawal_type: withdrawalType,
+    }),
+  });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/bulk-update-type`,
-      {
-        method: 'PUT',
-        headers,
-        body: JSON.stringify({
-          ids: ids.map(id => parseInt(id, 10)),
-          withdrawal_type: withdrawalType,
-        }),
-      }
-    );
-
-    const result = await response.json();
-
-    if (!response.ok || !result.success) {
-      return {
-        success: false,
-        error: result.message || '계정과목명 저장에 실패했습니다.',
-      };
-    }
-
-    return { success: true };
-  } catch (error) {
-    console.error('[WithdrawalActions] updateWithdrawalTypes error:', error);
-    return {
-      success: false,
-      error: '서버 오류가 발생했습니다.',
-    };
+  if (error) {
+    return { success: false, error: error.message };
   }
+
+  const result = await response?.json();
+
+  if (!response?.ok || !result.success) {
+    return { success: false, error: result?.message || '계정과목명 저장에 실패했습니다.' };
+  }
+
+  return { success: true };
 }
 
 // ===== 출금 상세 조회 =====
@@ -230,104 +201,52 @@ export async function getWithdrawalById(id: string): Promise<{
   data?: WithdrawalRecord;
   error?: string;
 }> {
-  try {
-    const headers = await getApiHeaders();
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`;
+  const { response, error } = await serverFetch(url, { method: 'GET' });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`,
-      {
-        method: 'GET',
-        headers,
-        cache: 'no-store',
-      }
-    );
-
-    if (!response.ok) {
-      console.error('[WithdrawalActions] GET withdrawal error:', response.status);
-      return {
-        success: false,
-        error: `API 오류: ${response.status}`,
-      };
-    }
-
-    const result = await response.json();
-
-    if (!result.success || !result.data) {
-      return {
-        success: false,
-        error: result.message || '출금 내역 조회에 실패했습니다.',
-      };
-    }
-
-    return {
-      success: true,
-      data: transformApiToFrontend(result.data),
-    };
-  } catch (error) {
-    console.error('[WithdrawalActions] getWithdrawalById error:', error);
-    return {
-      success: false,
-      error: '서버 오류가 발생했습니다.',
-    };
+  if (error) {
+    return { success: false, error: error.message };
   }
-}
 
-// ===== Frontend → API 변환 =====
-function transformFrontendToApi(data: Partial<WithdrawalRecord>): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
+  if (!response?.ok) {
+    console.error('[WithdrawalActions] GET withdrawal error:', response?.status);
+    return { success: false, error: `API 오류: ${response?.status}` };
+  }
 
-  if (data.withdrawalDate !== undefined) result.withdrawal_date = data.withdrawalDate;
-  if (data.withdrawalAmount !== undefined) result.withdrawal_amount = data.withdrawalAmount;
-  if (data.accountName !== undefined) result.account_name = data.accountName;
-  if (data.recipientName !== undefined) result.recipient_name = data.recipientName;
-  if (data.note !== undefined) result.note = data.note || null;
-  if (data.withdrawalType !== undefined) result.withdrawal_type = data.withdrawalType;
-  if (data.vendorId !== undefined) result.vendor_id = data.vendorId ? parseInt(data.vendorId, 10) : null;
-  if (data.vendorName !== undefined) result.vendor_name = data.vendorName || null;
+  const result = await response.json();
 
-  return result;
+  if (!result.success || !result.data) {
+    return { success: false, error: result.message || '출금 내역 조회에 실패했습니다.' };
+  }
+
+  return { success: true, data: transformApiToFrontend(result.data) };
 }
 
 // ===== 출금 등록 =====
 export async function createWithdrawal(
   data: Partial<WithdrawalRecord>
 ): Promise<{ success: boolean; data?: WithdrawalRecord; error?: string }> {
-  try {
-    const headers = await getApiHeaders();
-    const apiData = transformFrontendToApi(data);
+  const apiData = transformFrontendToApi(data);
+  console.log('[WithdrawalActions] POST withdrawal request:', apiData);
 
-    console.log('[WithdrawalActions] POST withdrawal request:', apiData);
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals`;
+  const { response, error } = await serverFetch(url, {
+    method: 'POST',
+    body: JSON.stringify(apiData),
+  });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals`,
-      {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(apiData),
-      }
-    );
-
-    const result = await response.json();
-    console.log('[WithdrawalActions] POST withdrawal response:', result);
-
-    if (!response.ok || !result.success) {
-      return {
-        success: false,
-        error: result.message || '출금 등록에 실패했습니다.',
-      };
-    }
-
-    return {
-      success: true,
-      data: transformApiToFrontend(result.data),
-    };
-  } catch (error) {
-    console.error('[WithdrawalActions] createWithdrawal error:', error);
-    return {
-      success: false,
-      error: '서버 오류가 발생했습니다.',
-    };
+  if (error) {
+    return { success: false, error: error.message };
   }
+
+  const result = await response?.json();
+  console.log('[WithdrawalActions] POST withdrawal response:', result);
+
+  if (!response?.ok || !result.success) {
+    return { success: false, error: result?.message || '출금 등록에 실패했습니다.' };
+  }
+
+  return { success: true, data: transformApiToFrontend(result.data) };
 }
 
 // ===== 출금 수정 =====
@@ -335,42 +254,27 @@ export async function updateWithdrawal(
   id: string,
   data: Partial<WithdrawalRecord>
 ): Promise<{ success: boolean; data?: WithdrawalRecord; error?: string }> {
-  try {
-    const headers = await getApiHeaders();
-    const apiData = transformFrontendToApi(data);
+  const apiData = transformFrontendToApi(data);
+  console.log('[WithdrawalActions] PUT withdrawal request:', apiData);
 
-    console.log('[WithdrawalActions] PUT withdrawal request:', apiData);
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`;
+  const { response, error } = await serverFetch(url, {
+    method: 'PUT',
+    body: JSON.stringify(apiData),
+  });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/withdrawals/${id}`,
-      {
-        method: 'PUT',
-        headers,
-        body: JSON.stringify(apiData),
-      }
-    );
-
-    const result = await response.json();
-    console.log('[WithdrawalActions] PUT withdrawal response:', result);
-
-    if (!response.ok || !result.success) {
-      return {
-        success: false,
-        error: result.message || '출금 수정에 실패했습니다.',
-      };
-    }
-
-    return {
-      success: true,
-      data: transformApiToFrontend(result.data),
-    };
-  } catch (error) {
-    console.error('[WithdrawalActions] updateWithdrawal error:', error);
-    return {
-      success: false,
-      error: '서버 오류가 발생했습니다.',
-    };
+  if (error) {
+    return { success: false, error: error.message };
   }
+
+  const result = await response?.json();
+  console.log('[WithdrawalActions] PUT withdrawal response:', result);
+
+  if (!response?.ok || !result.success) {
+    return { success: false, error: result?.message || '출금 수정에 실패했습니다.' };
+  }
+
+  return { success: true, data: transformApiToFrontend(result.data) };
 }
 
 // ===== 거래처 목록 조회 =====
@@ -379,39 +283,30 @@ export async function getVendors(): Promise<{
   data: { id: string; name: string }[];
   error?: string;
 }> {
-  try {
-    const headers = await getApiHeaders();
+  const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/clients?per_page=100`;
+  const { response, error } = await serverFetch(url, { method: 'GET' });
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/clients?per_page=100`,
-      {
-        method: 'GET',
-        headers,
-        cache: 'no-store',
-      }
-    );
-
-    if (!response.ok) {
-      return { success: false, data: [], error: `API 오류: ${response.status}` };
-    }
-
-    const result = await response.json();
-
-    if (!result.success) {
-      return { success: false, data: [], error: result.message };
-    }
-
-    const clients = result.data?.data || result.data || [];
-
-    return {
-      success: true,
-      data: clients.map((c: { id: number; name: string }) => ({
-        id: String(c.id),
-        name: c.name,
-      })),
-    };
-  } catch (error) {
-    console.error('[WithdrawalActions] getVendors error:', error);
-    return { success: false, data: [], error: '서버 오류가 발생했습니다.' };
+  if (error) {
+    return { success: false, data: [], error: error.message };
   }
-}
+
+  if (!response?.ok) {
+    return { success: false, data: [], error: `API 오류: ${response?.status}` };
+  }
+
+  const result = await response.json();
+
+  if (!result.success) {
+    return { success: false, data: [], error: result.message };
+  }
+
+  const clients = result.data?.data || result.data || [];
+
+  return {
+    success: true,
+    data: clients.map((c: { id: number; name: string }) => ({
+      id: String(c.id),
+      name: c.name,
+    })),
+  };
+}