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/approval/ReferenceBox/actions.ts

@@ -9,8 +9,8 @@
 
 'use server';
 
-import { cookies } from 'next/headers';
-import type { ReferenceRecord, ApprovalType, DocumentStatus, ReadStatus } from './types';
+import { serverFetch } from '@/lib/api/fetch-wrapper';
+import type { ReferenceRecord, ApprovalType, DocumentStatus } from './types';
 
 // ============================================
 // API 응답 타입 정의
@@ -72,21 +72,6 @@ interface ReferenceStepApiData {
 // 헬퍼 함수
 // ============================================
 
-/**
- * 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 상태 → 프론트엔드 상태 변환
  */
@@ -156,7 +141,6 @@ export async function getReferences(params?: {
   sort_dir?: 'asc' | 'desc';
 }): Promise<{ data: ReferenceRecord[]; total: number; lastPage: number }> {
   try {
-    const headers = await getApiHeaders();
     const searchParams = new URLSearchParams();
 
     if (params?.page) searchParams.set('page', String(params.page));
@@ -173,12 +157,16 @@ export async function getReferences(params?: {
 
     const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/approvals/reference?${searchParams.toString()}`;
 
-    const response = await fetch(url, {
+    const { response, error } = await serverFetch(url, {
       method: 'GET',
-      headers,
-      cache: 'no-store',
     });
 
+    // serverFetch handles 401 with redirect, so we just check for other errors
+    if (error || !response) {
+      console.error('[ReferenceBoxActions] GET reference error:', error?.message);
+      return { data: [], total: 0, lastPage: 1 };
+    }
+
     if (!response.ok) {
       console.error('[ReferenceBoxActions] GET reference error:', response.status);
       return { data: [], total: 0, lastPage: 1 };
@@ -228,16 +216,20 @@ export async function getReferenceSummary(): Promise<{ all: number; read: number
  */
 export async function markAsRead(id: string): Promise<{ success: boolean; error?: string }> {
   try {
-    const headers = await getApiHeaders();
+    const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/approvals/${id}/read`;
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/approvals/${id}/read`,
-      {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({}),
-      }
-    );
+    const { response, error } = await serverFetch(url, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+
+    // serverFetch handles 401 with redirect
+    if (error || !response) {
+      return {
+        success: false,
+        error: error?.message || '열람 처리에 실패했습니다.',
+      };
+    }
 
     const result = await response.json();
 
@@ -263,16 +255,20 @@ export async function markAsRead(id: string): Promise<{ success: boolean; error?
  */
 export async function markAsUnread(id: string): Promise<{ success: boolean; error?: string }> {
   try {
-    const headers = await getApiHeaders();
+    const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/approvals/${id}/unread`;
 
-    const response = await fetch(
-      `${process.env.NEXT_PUBLIC_API_URL}/api/v1/approvals/${id}/unread`,
-      {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({}),
-      }
-    );
+    const { response, error } = await serverFetch(url, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+
+    // serverFetch handles 401 with redirect
+    if (error || !response) {
+      return {
+        success: false,
+        error: error?.message || '미열람 처리에 실패했습니다.',
+      };
+    }
 
     const result = await response.json();
 

src/components/approval/ReferenceBox/index.tsx

@@ -5,7 +5,6 @@ import {
   Files,
   Eye,
   EyeOff,
-  Check,
   BookOpen,
 } from 'lucide-react';
 import { toast } from 'sonner';
@@ -44,19 +43,22 @@ import {
 } from '@/components/templates/IntegratedListTemplateV2';
 import { DateRangeSelector } from '@/components/molecules/DateRangeSelector';
 import { ListMobileCard, InfoField } from '@/components/organisms/ListMobileCard';
+import { DocumentDetailModal } from '@/components/approval/DocumentDetail';
+import type { DocumentType, ProposalDocumentData, ExpenseReportDocumentData, ExpenseEstimateDocumentData } from '@/components/approval/DocumentDetail/types';
 import type {
   ReferenceTabType,
   ReferenceRecord,
   SortOption,
   FilterOption,
+  ApprovalType,
 } from './types';
 import {
   REFERENCE_TAB_LABELS,
   SORT_OPTIONS,
   FILTER_OPTIONS,
   APPROVAL_TYPE_LABELS,
-  DOCUMENT_STATUS_LABELS,
-  DOCUMENT_STATUS_COLORS,
+  READ_STATUS_LABELS,
+  READ_STATUS_COLORS,
 } from './types';
 
 // ===== 통계 타입 =====
@@ -86,6 +88,10 @@ export function ReferenceBox() {
   const [markReadDialogOpen, setMarkReadDialogOpen] = useState(false);
   const [markUnreadDialogOpen, setMarkUnreadDialogOpen] = useState(false);
 
+  // ===== 문서 상세 모달 상태 =====
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [selectedDocument, setSelectedDocument] = useState<ReferenceRecord | null>(null);
+
   // API 데이터
   const [data, setData] = useState<ReferenceRecord[]>([]);
   const [totalCount, setTotalCount] = useState(0);
@@ -252,6 +258,87 @@ export function ReferenceBox() {
     setMarkUnreadDialogOpen(false);
   }, [selectedItems, loadData, loadSummary]);
 
+  // ===== 문서 클릭/상세 보기 핸들러 =====
+  const handleDocumentClick = useCallback((item: ReferenceRecord) => {
+    setSelectedDocument(item);
+    setIsModalOpen(true);
+  }, []);
+
+  // ===== ApprovalType → DocumentType 변환 =====
+  const getDocumentType = (approvalType: ApprovalType): DocumentType => {
+    switch (approvalType) {
+      case 'expense_estimate': return 'expenseEstimate';
+      case 'expense_report': return 'expenseReport';
+      default: return 'proposal';
+    }
+  };
+
+  // ===== ReferenceRecord → 모달용 데이터 변환 =====
+  const convertToModalData = (item: ReferenceRecord): ProposalDocumentData | ExpenseReportDocumentData | ExpenseEstimateDocumentData => {
+    const docType = getDocumentType(item.approvalType);
+    const drafter = {
+      id: 'drafter-1',
+      name: item.drafter,
+      position: item.drafterPosition,
+      department: item.drafterDepartment,
+      status: 'approved' as const,
+    };
+    const approvers = [{
+      id: 'approver-1',
+      name: '결재자',
+      position: '부장',
+      department: '경영지원팀',
+      status: 'approved' as const,
+    }];
+
+    switch (docType) {
+      case 'expenseEstimate':
+        return {
+          documentNo: item.documentNo,
+          createdAt: item.draftDate,
+          items: [
+            { id: '1', expectedPaymentDate: '2025-11-05', category: '통신 서비스', amount: 550000, vendor: 'KT', account: '국민 123-456-789012 홍길동' },
+            { id: '2', expectedPaymentDate: '2025-11-12', category: '인건 대행', amount: 2500000, vendor: '에이치알코리아', account: '신한 110-123-456789 (주)에이치알' },
+          ],
+          totalExpense: 3050000,
+          accountBalance: 25000000,
+          finalDifference: 21950000,
+          approvers,
+          drafter,
+        };
+      case 'expenseReport':
+        return {
+          documentNo: item.documentNo,
+          createdAt: item.draftDate,
+          requestDate: item.draftDate,
+          paymentDate: item.draftDate,
+          items: [
+            { id: '1', no: 1, description: '업무용 택시비', amount: 50000, note: '고객사 미팅' },
+            { id: '2', no: 2, description: '식대', amount: 30000, note: '팀 회식' },
+          ],
+          cardInfo: '삼성카드 **** 1234',
+          totalAmount: 80000,
+          attachments: [],
+          approvers,
+          drafter,
+        };
+      default:
+        return {
+          documentNo: item.documentNo,
+          createdAt: item.draftDate,
+          vendor: '거래처',
+          vendorPaymentDate: item.draftDate,
+          title: item.title,
+          description: item.title,
+          reason: '업무상 필요',
+          estimatedCost: 1000000,
+          attachments: [],
+          approvers,
+          drafter,
+        };
+    }
+  };
+
   // ===== 통계 카드 =====
   const statCards: StatCard[] = useMemo(() => [
     { label: '전체', value: `${stats.all}건`, icon: Files, iconColor: 'text-blue-500' },
@@ -267,7 +354,7 @@ export function ReferenceBox() {
   ], [stats]);
 
   // ===== 테이블 컬럼 =====
-  // 문서번호, 문서유형, 제목, 기안자, 기안일시, 상태, 확인
+  // 문서번호, 문서유형, 제목, 기안자, 기안일시, 상태
   const tableColumns: TableColumn[] = useMemo(() => [
     { key: 'no', label: '번호', className: 'w-[60px] text-center' },
     { key: 'documentNo', label: '문서번호' },
@@ -276,7 +363,6 @@ export function ReferenceBox() {
     { key: 'drafter', label: '기안자' },
     { key: 'draftDate', label: '기안일시' },
     { key: 'status', label: '상태', className: 'text-center' },
-    { key: 'confirm', label: '확인', className: 'w-[80px] text-center' },
   ], []);
 
   // ===== 테이블 행 렌더링 =====
@@ -284,8 +370,12 @@ export function ReferenceBox() {
     const isSelected = selectedItems.has(item.id);
 
     return (
-      <TableRow key={item.id} className="hover:bg-muted/50">
-        <TableCell className="text-center">
+      <TableRow
+        key={item.id}
+        className="hover:bg-muted/50 cursor-pointer"
+        onClick={() => handleDocumentClick(item)}
+      >
+        <TableCell className="text-center" onClick={(e) => e.stopPropagation()}>
           <Checkbox checked={isSelected} onCheckedChange={() => toggleSelection(item.id)} />
         </TableCell>
         <TableCell className="text-center">{globalIndex}</TableCell>
@@ -297,18 +387,13 @@ export function ReferenceBox() {
         <TableCell>{item.drafter}</TableCell>
         <TableCell>{item.draftDate}</TableCell>
         <TableCell className="text-center">
-          <Badge className={DOCUMENT_STATUS_COLORS[item.documentStatus]}>
-            {DOCUMENT_STATUS_LABELS[item.documentStatus]}
+          <Badge className={READ_STATUS_COLORS[item.readStatus]}>
+            {READ_STATUS_LABELS[item.readStatus]}
           </Badge>
         </TableCell>
-        <TableCell className="text-center">
-          {item.readStatus === 'read' && (
-            <Check className="h-4 w-4 mx-auto text-green-600" />
-          )}
-        </TableCell>
       </TableRow>
     );
-  }, [selectedItems, toggleSelection]);
+  }, [selectedItems, toggleSelection, handleDocumentClick]);
 
   // ===== 모바일 카드 렌더링 =====
   const renderMobileCard = useCallback((
@@ -325,14 +410,9 @@ export function ReferenceBox() {
         headerBadges={
           <div className="flex gap-1">
             <Badge variant="outline">{APPROVAL_TYPE_LABELS[item.approvalType]}</Badge>
-            <Badge className={DOCUMENT_STATUS_COLORS[item.documentStatus]}>
-              {DOCUMENT_STATUS_LABELS[item.documentStatus]}
+            <Badge className={READ_STATUS_COLORS[item.readStatus]}>
+              {READ_STATUS_LABELS[item.readStatus]}
             </Badge>
-            {item.readStatus === 'read' ? (
-              <Badge className="bg-gray-100 text-gray-800">열람</Badge>
-            ) : (
-              <Badge className="bg-blue-100 text-blue-800">미열람</Badge>
-            )}
           </div>
         }
         isSelected={isSelected}
@@ -505,6 +585,17 @@ export function ReferenceBox() {
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
+
+      {/* 문서 상세 모달 */}
+      {selectedDocument && (
+        <DocumentDetailModal
+          open={isModalOpen}
+          onOpenChange={setIsModalOpen}
+          documentType={getDocumentType(selectedDocument.approvalType)}
+          data={convertToModalData(selectedDocument)}
+          mode="reference"
+        />
+      )}
     </>
   );
 }