feat(WEB): UniversalListPage 전체 마이그레이션 및 코드 정리

- UniversalListPage/IntegratedListTemplateV2 컴포넌트 기능 개선
- 회계, HR, 건설, 고객센터, 결재, 설정 등 전체 리스트 컴포넌트 마이그레이션
- 테스트 페이지 및 미사용 API 라우트 정리 (board-test, order-management-test 등)
- 미들웨어 토큰 갱신 로직 개선
- AuthenticatedLayout 구조 개선
- claudedocs 문서 업데이트

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

src/components/settings/PaymentHistoryManagement/PaymentHistoryClient.tsx

@@ -1,5 +1,13 @@
 'use client';
 
+/**
+ * 결제내역 - UniversalListPage 마이그레이션
+ *
+ * 기존 IntegratedListTemplateV2 → UniversalListPage config 기반으로 변환
+ * - 서버 사이드 페이지네이션 (getPayments API)
+ * - 검색 숨김, 체크박스 숨김
+ */
+
 import { useState, useMemo, useCallback } from 'react';
 import { Receipt, FileText } from 'lucide-react';
 import { Button } from '@/components/ui/button';
@@ -13,9 +21,12 @@ import {
   DialogFooter,
 } from '@/components/ui/dialog';
 import {
-  IntegratedListTemplateV2,
-  type TableColumn,
-} from '@/components/templates/IntegratedListTemplateV2';
+  UniversalListPage,
+  type UniversalListConfig,
+  type SelectionHandlers,
+  type RowClickHandlers,
+  type ListParams,
+} from '@/components/templates/UniversalListPage';
 import { ListMobileCard, InfoField } from '@/components/organisms/ListMobileCard';
 import { getPayments } from './actions';
 import type { PaymentHistory, SortOption } from './types';
@@ -37,209 +48,184 @@ export function PaymentHistoryClient({
   initialPagination,
 }: PaymentHistoryClientProps) {
   // ===== 상태 관리 =====
-  const [searchQuery, setSearchQuery] = useState('');
   const [sortOption, setSortOption] = useState<SortOption>('latest');
-  const [currentPage, setCurrentPage] = useState(initialPagination.currentPage);
-  const [data, setData] = useState<PaymentHistory[]>(initialData);
-  const [totalPages, setTotalPages] = useState(initialPagination.lastPage);
-  const [totalItems, setTotalItems] = useState(initialPagination.total);
-  const [isLoading, setIsLoading] = useState(false);
   const itemsPerPage = initialPagination.perPage;
 
   // 거래명세서 팝업 상태
   const [showInvoiceDialog, setShowInvoiceDialog] = useState(false);
   const [selectedPaymentId, setSelectedPaymentId] = useState<string | null>(null);
 
-  // ===== 페이지 변경 핸들러 =====
-  const handlePageChange = useCallback(async (page: number) => {
-    setIsLoading(true);
-    try {
-      const result = await getPayments({ page, perPage: itemsPerPage });
-      if (result.success) {
-        setData(result.data);
-        setCurrentPage(result.pagination.currentPage);
-        setTotalPages(result.pagination.lastPage);
-        setTotalItems(result.pagination.total);
-      }
-    } catch (error) {
-      if (isNextRedirectError(error)) throw error;
-      console.error('[PaymentHistoryClient] Page change error:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [itemsPerPage]);
-
-  // ===== 필터링된 데이터 (클라이언트 사이드 필터링) =====
-  const filteredData = useMemo(() => {
-    let result = [...data];
-
-    // 검색 필터 (클라이언트 사이드)
-    if (searchQuery) {
-      result = result.filter(item =>
-        item.subscriptionName.includes(searchQuery) ||
-        item.paymentMethod.includes(searchQuery) ||
-        item.paymentDate.includes(searchQuery)
-      );
-    }
-
-    // 정렬
-    switch (sortOption) {
-      case 'latest':
-        result.sort((a, b) => new Date(b.paymentDate).getTime() - new Date(a.paymentDate).getTime());
-        break;
-      case 'oldest':
-        result.sort((a, b) => new Date(a.paymentDate).getTime() - new Date(b.paymentDate).getTime());
-        break;
-      case 'amountHigh':
-        result.sort((a, b) => b.amount - a.amount);
-        break;
-      case 'amountLow':
-        result.sort((a, b) => a.amount - b.amount);
-        break;
-    }
-
-    return result;
-  }, [data, searchQuery, sortOption]);
-
   // ===== 거래명세서 버튼 클릭 =====
   const handleViewInvoice = useCallback((paymentId: string) => {
     setSelectedPaymentId(paymentId);
     setShowInvoiceDialog(true);
   }, []);
 
-  // ===== 테이블 컬럼 =====
-  const tableColumns: TableColumn[] = useMemo(() => [
-    { key: 'paymentDate', label: '결제일' },
-    { key: 'subscriptionName', label: '구독명' },
-    { key: 'paymentMethod', label: '결제 수단' },
-    { key: 'subscriptionPeriod', label: '구독 기간' },
-    { key: 'amount', label: '금액', className: 'text-right' },
-    { key: 'invoice', label: '거래명세서', className: 'text-center' },
-  ], []);
+  // ===== UniversalListPage Config =====
+  const config: UniversalListConfig<PaymentHistory> = useMemo(
+    () => ({
+      // 페이지 기본 정보
+      title: '결제내역',
+      description: '결제 내역을 확인합니다',
+      icon: Receipt,
+      basePath: '/settings/payment-history',
 
-  // ===== 테이블 행 렌더링 =====
-  const renderTableRow = useCallback((item: PaymentHistory, index: number) => {
-    const isLatest = index === 0; // 최신 항목 (초록색 버튼)
+      // ID 추출
+      idField: 'id',
 
-    return (
-      <TableRow
-        key={item.id}
-        className="hover:bg-muted/50"
-      >
-        {/* 결제일 */}
-        <TableCell>{item.paymentDate}</TableCell>
-        {/* 구독명 */}
-        <TableCell>{item.subscriptionName}</TableCell>
-        {/* 결제 수단 */}
-        <TableCell>{item.paymentMethod}</TableCell>
-        {/* 구독 기간 */}
-        <TableCell>
-          {item.subscriptionPeriod.start && item.subscriptionPeriod.end
-            ? `${item.subscriptionPeriod.start} ~ ${item.subscriptionPeriod.end}`
-            : '-'}
-        </TableCell>
-        {/* 금액 */}
-        <TableCell className="text-right font-medium">
-          {item.amount.toLocaleString()}원
-        </TableCell>
-        {/* 거래명세서 */}
-        <TableCell className="text-center">
-          {item.canViewInvoice ? (
-            <Button
-              size="sm"
-              variant={isLatest ? 'default' : 'secondary'}
-              className={isLatest ? 'bg-emerald-600 hover:bg-emerald-700' : ''}
-              onClick={() => handleViewInvoice(item.id)}
-            >
-              <FileText className="h-4 w-4 mr-1" />
-              거래명세서
-            </Button>
-          ) : (
-            <span className="text-muted-foreground text-sm">-</span>
-          )}
-        </TableCell>
-      </TableRow>
-    );
-  }, [handleViewInvoice]);
+      // API 액션 (서버 사이드 페이지네이션)
+      actions: {
+        getList: async (params?: ListParams) => {
+          try {
+            const result = await getPayments({
+              page: params?.page || 1,
+              perPage: itemsPerPage,
+            });
 
-  // ===== 모바일 카드 렌더링 =====
-  const renderMobileCard = useCallback((
-    item: PaymentHistory,
-    index: number,
-    globalIndex: number,
-    isSelected: boolean,
-    onToggle: () => void
-  ) => {
-    const isLatest = globalIndex === 1;
+            if (result.success) {
+              return {
+                success: true,
+                data: result.data,
+                totalCount: result.pagination.total,
+                totalPages: result.pagination.lastPage,
+              };
+            }
+            return { success: false, error: '데이터 로드 중 오류가 발생했습니다.' };
+          } catch (error) {
+            if (isNextRedirectError(error)) throw error;
+            return { success: false, error: '데이터 로드 중 오류가 발생했습니다.' };
+          }
+        },
+      },
 
-    return (
-      <ListMobileCard
-        id={item.id}
-        title={`${item.subscriptionName} - ${item.paymentDate}`}
-        isSelected={false}
-        onToggleSelection={() => {}}
-        infoGrid={
-          <div className="grid grid-cols-2 gap-3">
-            <InfoField label="결제일" value={item.paymentDate} />
-            <InfoField label="구독명" value={item.subscriptionName} />
-            <InfoField label="결제 수단" value={item.paymentMethod} />
-            <InfoField label="금액" value={`${item.amount.toLocaleString()}원`} />
-            <div className="col-span-2">
-              <InfoField
-                label="구독 기간"
-                value={
-                  item.subscriptionPeriod.start && item.subscriptionPeriod.end
-                    ? `${item.subscriptionPeriod.start} ~ ${item.subscriptionPeriod.end}`
-                    : '-'
-                }
-              />
-            </div>
-          </div>
-        }
-        actions={
-          item.canViewInvoice ? (
-            <Button
-              size="sm"
-              variant={isLatest ? 'default' : 'secondary'}
-              className={isLatest ? 'bg-emerald-600 hover:bg-emerald-700' : ''}
-              onClick={() => handleViewInvoice(item.id)}
-            >
-              <FileText className="h-4 w-4 mr-1" />
-              거래명세서
-            </Button>
-          ) : null
-        }
-      />
-    );
-  }, [handleViewInvoice]);
+      // 테이블 컬럼
+      columns: [
+        { key: 'paymentDate', label: '결제일' },
+        { key: 'subscriptionName', label: '구독명' },
+        { key: 'paymentMethod', label: '결제 수단' },
+        { key: 'subscriptionPeriod', label: '구독 기간' },
+        { key: 'amount', label: '금액', className: 'text-right' },
+        { key: 'invoice', label: '거래명세서', className: 'text-center' },
+      ],
+
+      // 서버 사이드 페이지네이션
+      clientSideFiltering: false,
+      itemsPerPage,
+
+      // 검색 숨김
+      hideSearch: true,
+
+      // 체크박스/번호 숨김
+      showCheckbox: false,
+      showRowNumber: false,
+
+      // 테이블 행 렌더링
+      renderTableRow: (
+        item: PaymentHistory,
+        index: number,
+        globalIndex: number,
+        handlers: SelectionHandlers & RowClickHandlers<PaymentHistory>
+      ) => {
+        const isLatest = index === 0;
+
+        return (
+          <TableRow
+            key={item.id}
+            className="hover:bg-muted/50"
+          >
+            {/* 결제일 */}
+            <TableCell>{item.paymentDate}</TableCell>
+            {/* 구독명 */}
+            <TableCell>{item.subscriptionName}</TableCell>
+            {/* 결제 수단 */}
+            <TableCell>{item.paymentMethod}</TableCell>
+            {/* 구독 기간 */}
+            <TableCell>
+              {item.subscriptionPeriod.start && item.subscriptionPeriod.end
+                ? `${item.subscriptionPeriod.start} ~ ${item.subscriptionPeriod.end}`
+                : '-'}
+            </TableCell>
+            {/* 금액 */}
+            <TableCell className="text-right font-medium">
+              {item.amount.toLocaleString()}원
+            </TableCell>
+            {/* 거래명세서 */}
+            <TableCell className="text-center">
+              {item.canViewInvoice ? (
+                <Button
+                  size="sm"
+                  variant={isLatest ? 'default' : 'secondary'}
+                  className={isLatest ? 'bg-emerald-600 hover:bg-emerald-700' : ''}
+                  onClick={() => handleViewInvoice(item.id)}
+                >
+                  <FileText className="h-4 w-4 mr-1" />
+                  거래명세서
+                </Button>
+              ) : (
+                <span className="text-muted-foreground text-sm">-</span>
+              )}
+            </TableCell>
+          </TableRow>
+        );
+      },
+
+      // 모바일 카드 렌더링
+      renderMobileCard: (
+        item: PaymentHistory,
+        index: number,
+        globalIndex: number,
+        handlers: SelectionHandlers & RowClickHandlers<PaymentHistory>
+      ) => {
+        const isLatest = globalIndex === 1;
+
+        return (
+          <ListMobileCard
+            key={item.id}
+            id={item.id}
+            title={`${item.subscriptionName} - ${item.paymentDate}`}
+            isSelected={false}
+            onToggleSelection={() => {}}
+            infoGrid={
+              <div className="grid grid-cols-2 gap-3">
+                <InfoField label="결제일" value={item.paymentDate} />
+                <InfoField label="구독명" value={item.subscriptionName} />
+                <InfoField label="결제 수단" value={item.paymentMethod} />
+                <InfoField label="금액" value={`${item.amount.toLocaleString()}원`} />
+                <div className="col-span-2">
+                  <InfoField
+                    label="구독 기간"
+                    value={
+                      item.subscriptionPeriod.start && item.subscriptionPeriod.end
+                        ? `${item.subscriptionPeriod.start} ~ ${item.subscriptionPeriod.end}`
+                        : '-'
+                    }
+                  />
+                </div>
+              </div>
+            }
+            actions={
+              item.canViewInvoice ? (
+                <Button
+                  size="sm"
+                  variant={isLatest ? 'default' : 'secondary'}
+                  className={isLatest ? 'bg-emerald-600 hover:bg-emerald-700' : ''}
+                  onClick={() => handleViewInvoice(item.id)}
+                >
+                  <FileText className="h-4 w-4 mr-1" />
+                  거래명세서
+                </Button>
+              ) : null
+            }
+          />
+        );
+      },
+    }),
+    [itemsPerPage, handleViewInvoice]
+  );
 
   return (
     <>
-      <IntegratedListTemplateV2
-        title="결제내역"
-        description="결제 내역을 확인합니다"
-        icon={Receipt}
-        hideSearch={true}
-        tableColumns={tableColumns}
-        data={filteredData}
-        totalCount={totalItems}
-        allData={filteredData}
-        selectedItems={new Set()}
-        onToggleSelection={() => {}}
-        onToggleSelectAll={() => {}}
-        getItemId={(item: PaymentHistory) => item.id}
-        renderTableRow={renderTableRow}
-        renderMobileCard={renderMobileCard}
-        showCheckbox={false}
-        showRowNumber={false}
-        pagination={{
-          currentPage,
-          totalPages,
-          totalItems,
-          itemsPerPage,
-          onPageChange: handlePageChange,
-        }}
-      />
+      <UniversalListPage config={config} initialData={initialData} />
 
       {/* ===== 거래명세서 안내 다이얼로그 ===== */}
       <Dialog open={showInvoiceDialog} onOpenChange={setShowInvoiceDialog}>

src/components/settings/PaymentHistoryManagement/index.tsx

@@ -13,9 +13,10 @@ import {
   DialogFooter,
 } from '@/components/ui/dialog';
 import {
-  IntegratedListTemplateV2,
+  UniversalListPage,
+  type UniversalListConfig,
   type TableColumn,
-} from '@/components/templates/IntegratedListTemplateV2';
+} from '@/components/templates/UniversalListPage';
 import { ListMobileCard, InfoField } from '@/components/organisms/ListMobileCard';
 import type { PaymentHistory, SortOption } from './types';
 
@@ -95,7 +96,12 @@ export function PaymentHistoryManagement({
   ], []);
 
   // ===== 테이블 행 렌더링 =====
-  const renderTableRow = useCallback((item: PaymentHistory, index: number) => {
+  const renderTableRow = useCallback((
+    item: PaymentHistory,
+    index: number,
+    globalIndex: number,
+    handlers: { isSelected: boolean; onToggle: () => void; onRowClick?: () => void }
+  ) => {
     const isLatest = index === 0; // 최신 항목 (초록색 버튼)
 
     return (
@@ -138,8 +144,7 @@ export function PaymentHistoryManagement({
     item: PaymentHistory,
     index: number,
     globalIndex: number,
-    isSelected: boolean,
-    onToggle: () => void
+    handlers: { isSelected: boolean; onToggle: () => void; onRowClick?: () => void }
   ) => {
     const isLatest = globalIndex === 1;
 
@@ -197,40 +202,37 @@ export function PaymentHistoryManagement({
   //   </div>
   // );
 
-  return (
-    <>
-      <IntegratedListTemplateV2
-        title="결제내역"
-        description="결제 내역을 확인합니다"
-        icon={Receipt}
-        hideSearch={true}
-        // ===== 검색/필터 (주석처리: 필요시 활성화) =====
-        // searchValue={searchQuery}
-        // onSearchChange={setSearchQuery}
-        // searchPlaceholder="구독명, 결제 수단, 결제일 검색..."
-        // tableHeaderActions={tableHeaderActions}
-        tableColumns={tableColumns}
-        data={paginatedData}
-        totalCount={filteredData.length}
-        allData={filteredData}
-        selectedItems={new Set()}
-        onToggleSelection={() => {}}
-        onToggleSelectAll={() => {}}
-        getItemId={(item: PaymentHistory) => item.id}
-        renderTableRow={renderTableRow}
-        renderMobileCard={renderMobileCard}
-        showCheckbox={false}
-        showRowNumber={false}
-        pagination={{
-          currentPage,
-          totalPages,
-          totalItems: filteredData.length,
-          itemsPerPage,
-          onPageChange: setCurrentPage,
-        }}
-      />
+  // ===== UniversalListPage 설정 =====
+  const paymentHistoryConfig: UniversalListConfig<PaymentHistory> = {
+    title: '결제내역',
+    description: '결제 내역을 확인합니다',
+    icon: Receipt,
+    basePath: '/payment-history',
 
-      {/* ===== 거래명세서 안내 다이얼로그 ===== */}
+    idField: 'id',
+
+    actions: {
+      getList: async () => ({
+        success: true,
+        data: data,
+        totalCount: data.length,
+      }),
+    },
+
+    columns: tableColumns,
+
+    hideSearch: true,
+    showCheckbox: false,
+    showRowNumber: false,
+
+    itemsPerPage,
+
+    clientSideFiltering: true,
+
+    renderTableRow,
+    renderMobileCard,
+
+    renderDialogs: () => (
       <Dialog open={showInvoiceDialog} onOpenChange={setShowInvoiceDialog}>
         <DialogContent>
           <DialogHeader>
@@ -252,6 +254,21 @@ export function PaymentHistoryManagement({
           </DialogFooter>
         </DialogContent>
       </Dialog>
-    </>
+    ),
+  };
+
+  return (
+    <UniversalListPage<PaymentHistory>
+      config={paymentHistoryConfig}
+      initialData={filteredData}
+      initialTotalCount={filteredData.length}
+      externalPagination={{
+        currentPage,
+        totalPages,
+        totalItems: filteredData.length,
+        itemsPerPage,
+        onPageChange: setCurrentPage,
+      }}
+    />
   );
 }