sam-react-prod/claudedocs/guides/[GUIDE] common-page-patterns.md

SAM 프로젝트 공통 페이지/컴포넌트 패턴 가이드

신규 페이지·모달 작업 시 이 문서를 참고하여 기존 구조와 일관성을 유지한다.

---

목차

1. 공통 컴포넌트 맵
2. 검색 모달 (SearchableSelectionModal)
3. 리스트 페이지
4. 상세/폼 페이지
5. API 연동 패턴
6. 페이지 라우팅 구조

---

1. 공통 컴포넌트 맵

Organisms (src/components/organisms/)

컴포넌트	용도	주요 Props
PageHeader	페이지 제목, 설명, 아이콘, 액션 버튼	title, description, icon, actions
PageLayout	최대 너비 래퍼 + 버전 정보	children, maxWidth?
StatCards	통계 카드 그리드	stats[], onStatClick?
SearchFilter	검색 입력 + 모바일 필터	searchTerm, onSearchChange, placeholder
DataTable	테이블 + 페이지네이션 + 정렬	columns, renderRow, pagination
MobileCard / ListMobileCard	모바일 카드 레이아웃	id, title, infoGrid, badges
EmptyState	빈 상태 (아이콘 + 메시지 + 액션)	icon, title, description, action
FormSection	카드 래퍼 (아이콘 + 제목 + 설명)	icon, title, description
FormFieldGrid	반응형 필드 그리드 (1~4열)	cols, children
FormActions	저장/취소 버튼 그룹	onSave, onCancel, isSaving
SearchableSelectionModal	검색 → 목록 → 선택 모달	fetchData, renderItem, mode

Molecules (src/components/molecules/)

컴포넌트	용도
StatusBadge	상태 뱃지 (색상 자동)
TableActions	테이블 행 액션 버튼
StandardDialog / ConfirmDialog	확인/경고 다이얼로그
YearQuarterFilter	연도/분기 필터
MobileFilter	모바일 필터 UI

Templates (src/components/templates/)

컴포넌트	용도
UniversalListPage	리스트 페이지 올인원 템플릿

---

2. 검색 모달

언제 사용하나

"검색 → 목록 → 선택" 패턴이 필요할 때 → SearchableSelectionModal<T> 사용. Dialog + Input + 리스트를 직접 조합하지 않는다.

위치

src/components/organisms/SearchableSelectionModal/
├── SearchableSelectionModal.tsx  — 메인 컴포넌트
├── useSearchableData.ts         — 검색+로딩 훅
├── types.ts                     — Props 인터페이스
└── index.ts

핵심 Props

SearchableSelectionModal<T>
  // 필수
  open: boolean
  onOpenChange: (open: boolean) => void
  title: ReactNode
  fetchData: (query: string) => Promise<T[]>  // API 호출 위임
  keyExtractor: (item: T) => string
  renderItem: (item: T, isSelected: boolean) => ReactNode
  mode: 'single' | 'multiple'
  onSelect: single → (item: T) | multiple → (items: T[])

  // 검색 설정
  searchPlaceholder?: string
  searchMode?: 'debounce' | 'enter'       // 기본: debounce
  validateSearch?: (q: string) => boolean  // 유효성 검사
  loadOnOpen?: boolean                     // 열릴 때 자동 로드

  // 메시지
  emptyQueryMessage?: string
  invalidSearchMessage?: string
  noResultMessage?: string
  loadingMessage?: string

  // 레이아웃
  dialogClassName?: string
  listContainerClassName?: string
  listWrapper?: (children, selectState?) => ReactNode  // Table 등 커스텀 구조
  infoText?: (items, isLoading) => ReactNode

  // 다중선택 전용
  confirmLabel?: string
  allowSelectAll?: boolean

패턴별 예제

A. 단일선택 + 디바운스 검색 (가장 일반적)

// 품목 검색, 거래처 검색 등
<SearchableSelectionModal<ItemType>
  open={open}
  onOpenChange={setOpen}
  title="품목 검색"
  searchPlaceholder="품목코드 또는 품목명 검색..."
  fetchData={async (q) => fetchItems({ search: q, per_page: 50 })}
  keyExtractor={(item) => item.id}
  validateSearch={(q) => /[a-zA-Z가-힣0-9]/.test(q)}
  emptyQueryMessage="검색어를 입력하세요"
  dialogClassName="sm:max-w-[500px]"
  mode="single"
  onSelect={(item) => { /* 선택 처리 */ }}
  renderItem={(item) => (
    <div className="p-3 hover:bg-blue-50 transition-colors">
      <span className="font-semibold">{item.code}</span>
      <span className="text-sm text-gray-600 ml-2">{item.name}</span>
    </div>
  )}
/>

B. 단일선택 + 카드 UI + 열릴 때 자동 로드

// 수주 선택, 견적 선택 등
<SearchableSelectionModal<OrderType>
  open={open}
  onOpenChange={setOpen}
  title="수주 선택"
  fetchData={async (q) => { /* API 호출 + toast 에러 처리 */ }}
  keyExtractor={(order) => order.id}
  loadOnOpen                                    // ← 열릴 때 전체 로드
  dialogClassName="sm:max-w-lg"
  listContainerClassName="max-h-[400px] overflow-y-auto space-y-2"
  mode="single"
  onSelect={onSelect}
  renderItem={(order) => (
    <div className="p-4 border rounded-lg hover:bg-muted/50 transition-colors">
      {/* 카드형 UI */}
    </div>
  )}
/>

C. 다중선택 + Enter 검색 + 테이블

// 수주 다중선택 (체크박스 테이블)
<SearchableSelectionModal<OrderSelectItem>
  open={open}
  onOpenChange={setOpen}
  title="수주 선택"
  fetchData={handleFetchData}
  keyExtractor={(item) => item.id}
  searchMode="enter"                            // ← 수동 검색
  loadOnOpen
  dialogClassName="sm:max-w-2xl"
  listContainerClassName="max-h-[400px] overflow-y-auto border rounded-md"
  mode="multiple"
  onSelect={onSelect}
  confirmLabel="선택"
  allowSelectAll
  listWrapper={(children, selectState) => (     // ← Table 구조 래핑
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead className="w-10">
            {selectState && (
              <Checkbox
                checked={selectState.isAllSelected}
                onCheckedChange={selectState.onToggleAll}
              />
            )}
          </TableHead>
          <TableHead>수주번호</TableHead>
          <TableHead>현장명</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>{children}</TableBody>
    </Table>
  )}
  renderItem={(item, isSelected) => (
    <TableRow className="cursor-pointer hover:bg-muted/50">
      <TableCell onClick={(e) => e.stopPropagation()}>
        <Checkbox checked={isSelected} />
      </TableCell>
      <TableCell>{item.orderNumber}</TableCell>
      <TableCell>{item.siteName}</TableCell>
    </TableRow>
  )}
/>

기존 모달 → 공통 컴포넌트 매핑

기존 모달	위치	패턴
ItemSearchModal	quotes/	A (단일 + 디바운스)
SupplierSearchModal	material/ReceivingManagement/	A (단일 + 디바운스)
SalesOrderSelectModal	production/WorkOrders/	B (단일 + 카드 + loadOnOpen)
QuotationSelectDialog	orders/	B (단일 + 카드 + loadOnOpen)
OrderSelectModal	quality/InspectionManagement/	C (다중 + Enter + 테이블)

---

3. 리스트 페이지

방법 1: UniversalListPage 템플릿 (권장)

src/components/templates/UniversalListPage에 config 객체를 전달하는 올인원 방식.

'use client';

import { UniversalListPage } from '@/components/templates/UniversalListPage';
import type { UniversalListPageConfig } from '@/components/templates/UniversalListPage';

export default function MyListPage() {
  const config: UniversalListPageConfig<MyItem> = {
    title: '목록 제목',
    description: '설명',
    icon: ListIcon,
    basePath: '/path/to/list',
    idField: 'id',

    // 통계
    stats: [
      { label: '전체', value: totalCount, icon: Users },
    ],

    // 탭
    tabs: [
      { value: 'all', label: '전체', count: totalCount },
      { value: 'active', label: '활성', count: activeCount },
    ],

    // 테이블 컬럼
    columns: [
      { key: 'name', label: '이름' },
      { key: 'status', label: '상태' },
    ],

    // 검색
    searchPlaceholder: '이름, 코드 검색...',
    searchFilter: (item, q) => item.name.includes(q),
    tabFilter: (item, tab) => tab === 'all' || item.status === tab,

    // 렌더링
    renderTableRow,
    renderMobileCard,
    headerActions: () => <Button>신규</Button>,
  };

  return <UniversalListPage config={config} initialData={data} />;
}

방법 2: Organisms 직접 조합

UniversalListPage가 맞지 않는 경우 organisms를 직접 조합.

'use client';

import { PageLayout, PageHeader, StatCards, SearchFilter, DataTable, EmptyState } from '@/components/organisms';

export function MyList() {
  return (
    <PageLayout>
      <PageHeader title="제목" description="설명" actions={<Button>신규</Button>} />
      <StatCards stats={stats} />
      <SearchFilter searchTerm={q} onSearchChange={setQ} placeholder="검색..." />
      {data.length > 0 ? (
        <DataTable columns={columns} renderRow={renderRow} pagination={pagination} />
      ) : (
        <EmptyState icon={FileX} title="데이터 없음" />
      )}
    </PageLayout>
  );
}

리스트 페이지 공통 규칙

• 검색 디바운스: 300ms
• 테이블 컬럼 순서: 체크박스 → 번호 → 데이터 컬럼 → 작업
• 번호 계산: (currentPage - 1) * pageSize + index + 1
• 모바일: ListMobileCard 또는 MobileCard 사용
• 빈 상태: EmptyState 사용 (검색 결과 없음 vs 데이터 없음 구분)
• 삭제 확인: ConfirmDialog 사용 (alert 금지)

---

4. 상세/폼 페이지

표준 구조

'use client';

import { useState, useEffect, useCallback } from 'react';
import { useRouter } from 'next/navigation';
import { toast } from 'sonner';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';

interface DetailProps {
  id?: string;
  mode: 'view' | 'edit' | 'new';
}

export function MyDetail({ id, mode }: DetailProps) {
  const isViewMode = mode === 'view';
  const isNewMode = mode === 'new';
  const router = useRouter();

  // 상태 (모든 hook은 최상단에 — 조건부 return 전에)
  const [isLoading, setIsLoading] = useState(!isNewMode);
  const [isSaving, setIsSaving] = useState(false);
  const [formData, setFormData] = useState({ name: '', code: '' });

  // 데이터 로드 (view/edit)
  useEffect(() => {
    if (!id || isNewMode) { setIsLoading(false); return; }
    getDetail(id).then(data => {
      setFormData(data);
      setIsLoading(false);
    });
  }, [id, isNewMode]);

  // 저장
  const handleSubmit = async () => {
    setIsSaving(true);
    try {
      if (isNewMode) await create(formData);
      else await update(id!, formData);
      toast.success('저장되었습니다.');
      router.back();
    } catch {
      toast.error('저장에 실패했습니다.');
    } finally {
      setIsSaving(false);
    }
  };

  if (isLoading) return <Skeleton />;

  return (
    <div className="container mx-auto py-6 max-w-4xl">
      {/* 헤더 */}
      <div className="mb-6">
        <h1 className="text-2xl font-bold">
          {isNewMode ? '신규 등록' : isViewMode ? '상세 보기' : '수정'}
        </h1>
      </div>

      {/* 섹션 1 */}
      <Card className="mb-6">
        <CardHeader><CardTitle>기본 정보</CardTitle></CardHeader>
        <CardContent className="space-y-4">
          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
            <div className="space-y-2">
              <Label>이름</Label>
              <Input
                value={formData.name}
                onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
                disabled={isViewMode}
              />
            </div>
          </div>
        </CardContent>
      </Card>

      {/* 하단 버튼 */}
      <div className="flex justify-end gap-3">
        <Button variant="outline" onClick={() => router.back()}>취소</Button>
        {isViewMode ? (
          <Button onClick={() => router.push(`?mode=edit`)}>수정</Button>
        ) : (
          <Button onClick={handleSubmit} disabled={isSaving}>
            {isSaving ? '저장 중...' : '저장'}
          </Button>
        )}
      </div>
    </div>
  );
}

상세/폼 페이지 공통 규칙

• 모드: view | edit | new 3가지
• Hook 규칙: 모든 hook은 최상단, 조건부 return은 그 아래
• 레이아웃: Card > CardHeader + CardContent 섹션 단위
• 필드 그리드: grid grid-cols-1 md:grid-cols-2 gap-4
• disabled: view 모드에서 모든 입력 비활성화
• 알림: toast.success() / toast.error() (sonner)
• 네비게이션: router.back() 또는 router.push()
• 로딩: Skeleton 컴포넌트 사용
• Select 버그 대응: <Select key={...}> 패턴 (CLAUDE.md 참조)

---

5. API 연동 패턴

Server Action 파일 구조

src/components/[domain]/[feature]/
├── index.tsx        — 메인 컴포넌트 (또는 리스트)
├── [Feature]Detail.tsx  — 상세/폼
├── actions.ts       — Server Actions (API 호출)
└── types.ts         — 타입 정의

Server Action 패턴

'use server';

import { cookies } from 'next/headers';

const API_BASE = process.env.BACKEND_API_URL;

export async function getList(params?: { q?: string; page?: number; size?: number }) {
  const cookieStore = await cookies();
  const token = cookieStore.get('access_token')?.value;
  if (!token) redirect('/login');

  const searchParams = new URLSearchParams();
  if (params?.q) searchParams.set('q', params.q);
  // ...

  const res = await fetch(`${API_BASE}/endpoint?${searchParams}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  const data = await res.json();
  return { success: true, data: data.data };
}

클라이언트에서 호출

// useEffect에서 호출
useEffect(() => {
  getList({ q: searchTerm })
    .then(result => {
      if (result.success) setData(result.data);
      else toast.error(result.error);
    });
}, [searchTerm]);

// SearchableSelectionModal의 fetchData에서 호출
const handleFetchData = useCallback(async (query: string) => {
  const result = await getList({ q: query });
  if (result.success) return result.data;
  toast.error(result.error);
  return [];
}, []);

---

6. 페이지 라우팅 구조

src/app/[locale]/(protected)/[domain]/
├── [list-page]/
│   └── page.tsx              → <ListComponent />
├── [detail-page]/
│   ├── [id]/
│   │   └── page.tsx          → <DetailComponent id={id} mode="view|edit" />
│   └── new/
│       └── page.tsx          → <DetailComponent mode="new" />

page.tsx 패턴

// 리스트
'use client';
import { MyList } from '@/components/[domain]/[Feature]';
export default function Page() { return <MyList />; }

// 상세 (view/edit)
'use client';
import { useParams, useSearchParams } from 'next/navigation';
export default function Page() {
  const { id } = useParams();
  const mode = useSearchParams().get('mode') === 'edit' ? 'edit' : 'view';
  return <MyDetail id={id as string} mode={mode} />;
}

// 신규
'use client';
export default function Page() { return <MyDetail mode="new" />; }

---

변경 이력

날짜	내용
2026-02-10	초기 작성: 검색 모달, 리스트, 상세/폼, API 패턴