sam-react-prod/claudedocs/guides/[PLAN] universal-detail-component.md

상세/등록/수정 페이지 통합 컴포넌트 계획

브랜치: feature/universal-detail-component 작성일: 2026-01-17 상태: 계획 수립 완료

1. 개요

1.1 목표

• 등록/상세/수정 페이지를 IntegratedDetailTemplate 통합 컴포넌트로 정리
• 기존 API 연결 코드는 그대로 유지 (actions.ts)
• UI/레이아웃만 통합하여 유지보수성 향상
• 미래 동적 폼 전환에 대비한 확장 가능한 설계

1.2 기대 효과

• 코드 중복 제거
• UI/UX 일관성 확보 (버튼 위치, 입력필드 스타일, 그리드 레이아웃)
• 유지보수 용이성 증가 (한 파일에서 전체 스타일 관리)
• 새 페이지 추가 시 개발 시간 단축
• 동적 폼 전환 시 껍데기(레이아웃) 재사용 가능

1.3 미래 동적 폼 전환 대비

⚠️ 중요: 최종 목표는 모든 페이지가 품목기준관리처럼 동적 폼으로 전환되는 것

현재 vs 미래 구조

┌─────────────────────────────────────────────────┐
│  IntegratedDetailTemplate (껍데기 - 재사용)      │
│  ├── 헤더 레이아웃        ← 동적 폼에서도 사용   │
│  ├── 버튼 배치/위치       ← 동적 폼에서도 사용   │
│  ├── 그리드 시스템        ← 동적 폼에서도 사용   │
│  └── 공통 스타일          ← 동적 폼에서도 사용   │
├─────────────────────────────────────────────────┤
│  내부 폼 영역 (교체 가능)                        │
│                                                  │
│  현재: 정적 config 기반 폼    ← 나중에 폐기      │
│  미래: 동적 폼 (기준관리 기반) ← 교체            │
└─────────────────────────────────────────────────┘

재사용률 분석

작업	동적 폼 전환 시
헤더/버튼 레이아웃	✅ 재사용 (70%)
그리드 시스템	✅ 재사용
공통 스타일	✅ 재사용
정적 config 정의	❌ 폐기 (30%)

동적 폼 지원 설계

// 현재 (정적 폼)
<IntegratedDetailTemplate
  mode="edit"
  config={popupConfig}  // 필드 정의
  onSubmit={updatePopup}
/>

// 미래 (동적 폼) - 껍데기는 그대로, 내부만 교체
<IntegratedDetailTemplate
  mode="edit"
  renderForm={(props) => (
    <DynamicForm
      기준관리ID={123}
      {...props}
    />
  )}
  onSubmit={updatePopup}
/>

---

2. 현황 분석

2.1 전체 통계

항목	개수
전체 페이지 (page.tsx)	205개
등록 페이지 (new/create)	32개
수정 페이지 ([id]/edit)	30개
상세 페이지 ([id])	47개
통합 대상	109개
제외 (동적 폼)	3개 (품목관리)

2.2 테스트 URL 페이지

• 일반 모듈: http://localhost:3000/dev/test-urls (60개)
• 건설 모듈: http://localhost:3000/dev/construction-test-urls (19개)

---

3. 패턴 분류

3.1 패턴 A: 완전 CRUD (19개 모듈, 57개 페이지)

구성: /new + /[id] + /[id]/edit

모듈	경로
사원관리	hr/employee-management
카드관리	hr/card-management
거래처관리	sales/client-management-sales-admin
견적관리	sales/quote-management
수주관리	sales/order-management-sales
단가관리	sales/pricing-management
작업지시관리	production/work-orders
스크린생산	production/screen-production
팝업관리	settings/popup-management
공정관리	master-data/process-management
출하관리	outbound/shipments
검사관리	quality/inspections
Q&A	customer-center/qna
게시판관리	board/board-management
악성채권추심	accounting/bad-debt-collection
거래처(입찰)	construction/project/bidding/partners
현장설명회	construction/project/bidding/site-briefings
계약관리	construction/project/contract
이슈관리	construction/project/issue-management

3.2 패턴 B: 등록+상세 (8개 모듈, 16개 페이지)

구성: /new + /[id] (수정은 상세에서 mode로 처리)

모듈	경로	비고
어음관리	accounting/bills	mode=edit
매출관리	accounting/sales	mode=edit
거래처(회계)	accounting/vendors	mode=edit
계좌관리	settings/accounts
권한관리	settings/permissions
품목(건설)	construction/order/base-info/items
노임(건설)	construction/order/base-info/labor
단가(건설)	construction/order/base-info/pricing

3.3 패턴 C: 상세+수정 (9개 모듈, 18개 페이지)

구성: /[id] + /[id]/edit (등록은 리스트에서 처리)

모듈	경로
기성청구관리	construction/billing/progress-billing-management
발주관리	construction/order/order-management
현장관리	construction/order/site-management
구조검토관리	construction/order/structure-review
입찰관리	construction/project/bidding
견적관리(건설)	construction/project/bidding/estimates
시공관리	construction/project/construction-management
인수인계보고서	construction/project/contract/handover-report
견적테스트	sales/quote-management/test

3.4 패턴 D: 상세만 (10개 모듈, 10개 페이지)

구성: /[id] only (조회 전용)

모듈	경로	비고
입금관리	accounting/deposits	조회 전용
매입관리	accounting/purchase	조회 전용
거래처원장	accounting/vendor-ledger	조회 전용
출금관리	accounting/withdrawals	조회 전용
공지사항	customer-center/notices	조회 전용
이벤트	customer-center/events	조회 전용
입고관리	material/receiving-management	조회 전용
재고현황	material/stock-status	조회 전용
프로젝트관리	construction/project/management	조회 전용
생산주문	sales/order-management-sales/production-orders	조회 전용

---

4. 통합 제외 대상

4.1 동적 폼 사용 모듈 (완전 제외)

🔴 품목관리는 이미 동적 폼(DynamicItemForm)을 사용하므로 통합 대상에서 완전 제외

모듈	경로	제외 이유
품목관리	items	DynamicItemForm 사용 (품목기준관리 기반 동적 폼)

품목관리 특수성

items/
├── create/page.tsx     → DynamicItemForm (mode="create") ← 동적 폼
├── [id]/page.tsx       → ItemDetailClient (카드형 조회)  ← 특수 UI
└── [id]/edit/page.tsx  → DynamicItemForm (mode="edit")   ← 동적 폼

제외 이유:

1. 동적 폼 구조: 필드가 품목기준관리 API 설정에 따라 동적 생성
2. 복잡한 비즈니스 로직: FG/PT/SM/RM/CS 각각 다른 코드 생성 규칙
3. BOM 관리: 부품표(BOM) 별도 API 호출 및 관리
4. 데이터 변환: 400줄+ 변환 로직 (mapApiResponseToFormData)

💡 미래 방향: 다른 페이지들도 품목관리처럼 동적 폼으로 전환 예정

4.2 특수 상세 UI 모듈 (상세만 제외)

🟡 상세 페이지가 문서 모달/카드형 등 특수 UI → 상세는 유지, 등록/수정만 통합

문서 모달 기반 상세

모듈	경로	사용 컴포넌트	문서 유형
기안함	approval/draft	DocumentDetailModal	품의서, 지출결의서, 지출예상내역서
수주관리	sales/order-management-sales	OrderDocumentModal	계약서, 거래명세서, 발주서
견적관리	sales/quote-management	QuoteDocument, PurchaseOrderDocument	견적서, 산출내역서, 발주서

특수 상세 UI

모듈	경로	사용 컴포넌트	특수 요소
작업지시관리	production/work-orders	WorkOrderDetail	공정 진행 단계(ProcessSteps) + WorkLogModal
스크린생산	production/screen-production	ItemDetailClient	카드형 조회 (품목 상세)

4.3 특수 패턴 처리 방안

// 특수 상세 UI가 필요한 경우 → renderView prop 사용
<IntegratedDetailTemplate
  mode="view"
  id={params.id}
  config={quoteManagementConfig}
  fetchData={getQuote}
  // 🔑 커스텀 상세 UI 렌더링
  renderView={(data) => <QuoteDocumentView data={data} />}
/>

// 등록/수정은 통합 템플릿 사용
<IntegratedDetailTemplate
  mode="create"
  config={quoteManagementConfig}
  onSubmit={createQuote}
  // 기본 폼 UI 사용
/>

4.4 통합 방향 요약

구분	상세(view)	등록(create)	수정(edit)
일반 패턴	✅ 통합	✅ 통합	✅ 통합
특수 상세 UI	❌ 기존 유지	✅ 통합	✅ 통합
동적 폼 (품목관리)	❌ 제외	❌ 제외	❌ 제외

---

5. 기존 Mode 패턴 분석

이미 mode 파라미터를 사용하는 페이지들 → 디자인만 통일 필요

5.1 회계 모듈 (URL 파라미터 방식)

모듈	경로	컴포넌트	mode 처리
어음관리	accounting/bills	BillDetail	?mode=edit
매출관리	accounting/sales	SalesDetail	?mode=edit
입금관리	accounting/deposits	DepositDetail	?mode=view (조회 전용)
매입관리	accounting/purchase	PurchaseDetail	?mode=view (조회 전용)
거래처관리	accounting/vendors	VendorDetail	?mode=edit
출금관리	accounting/withdrawals	WithdrawalDetail	?mode=view (조회 전용)

5.2 건설 모듈 (Props 방식)

모듈	경로	컴포넌트	mode 처리
기성청구관리	construction/billing	ProgressBillingDetailForm	mode="view"
발주관리	construction/order	OrderDetailForm	mode="view"
현장관리	construction/site	SiteDetailForm	mode="view"
구조검토	construction/structure-review	StructureReviewDetailForm	mode="view"
입찰관리	construction/bidding	BiddingDetailForm	mode="view"
견적관리(건설)	construction/estimates	EstimateDetailForm	mode="view"
계약관리	construction/contract	ContractDetailForm	mode="view"
이슈관리	construction/issue	IssueDetailForm	mode="view"
인수인계	construction/handover	HandoverReportDetailForm	mode="view"

5.3 통합 시 고려사항

• URL 파라미터 방식 → Props 방식으로 통일 권장
• 기존 컴포넌트 내부 로직은 유지
• IntegratedDetailTemplate이 mode를 관리하고 하위 컴포넌트에 전달

---

6. 통합 컴포넌트 설계

6.1 기본 구조

// IntegratedDetailTemplate
interface IntegratedDetailTemplateProps {
  mode: 'create' | 'edit' | 'view';
  id?: string;
  config: DetailPageConfig;

  // API 연결 (기존 actions.ts 그대로 사용)
  fetchData?: (id: string) => Promise<any>;
  onSubmit?: (data: any) => Promise<any>;
  onDelete?: (id: string) => Promise<any>;

  // 🔑 커스텀 렌더링 (특수 케이스 & 미래 동적 폼 대비)
  renderView?: (data: any) => React.ReactNode;
  renderForm?: (data: any, mode: 'create' | 'edit') => React.ReactNode;
}

interface DetailPageConfig {
  title: string;
  backUrl: string;
  fields: FieldConfig[];
  permissions?: {
    canEdit?: boolean;
    canDelete?: boolean;
  };
}

6.2 사용 예시

기본 사용 (정적 폼)

// 통합 방식 (1개 설정 + 3개 라우트)
<IntegratedDetailTemplate
  mode="create"
  config={popupManagementConfig}
  onSubmit={createPopup}           // 기존 actions.ts
/>

<IntegratedDetailTemplate
  mode="view"
  id={params.id}
  config={popupManagementConfig}
  fetchData={getPopup}             // 기존 actions.ts
/>

<IntegratedDetailTemplate
  mode="edit"
  id={params.id}
  config={popupManagementConfig}
  fetchData={getPopup}             // 기존 actions.ts
  onSubmit={updatePopup}           // 기존 actions.ts
/>

커스텀 상세 UI

<IntegratedDetailTemplate
  mode="view"
  id={params.id}
  config={quoteConfig}
  fetchData={getQuote}
  renderView={(data) => <QuoteDocumentView data={data} />}
/>

미래: 동적 폼 사용

<IntegratedDetailTemplate
  mode="edit"
  id={params.id}
  fetchData={getData}
  onSubmit={updateData}
  renderForm={(data, mode) => (
    <DynamicForm
      기준관리ID={123}
      mode={mode}
      initialData={data}
    />
  )}
/>

6.3 핵심 원칙

• ✅ API 연결 코드 변경 없음 (actions.ts 그대로)
• ✅ 기존 기능 100% 유지
• ✅ UI/레이아웃만 통합
• ✅ 설정(config)만 다르게 전달
• ✅ renderView/renderForm으로 커스텀 렌더링 지원
• ✅ 미래 동적 폼 전환 대비 확장 가능한 구조

---

7. 구현 계획

Phase 1: 프로토타입 (3개 모듈)

목표: 통합 템플릿 구조 검증

순서	모듈	복잡도	선정 이유
1	settings/popup-management	낮음	단순 폼 구조
2	hr/card-management	낮음	기본 CRUD
3	master-data/process-management	낮음	공정 기본 정보

Phase 2: 설정 모듈 확장 (4개)

settings/accounts
settings/permissions
board/board-management
accounting/bad-debt-collection

Phase 3: HR/판매 모듈 (6개)

hr/employee-management
sales/client-management-sales-admin
sales/quote-management (등록/수정만, 상세는 renderView)
sales/order-management-sales (등록/수정만, 상세는 renderView)
sales/pricing-management
customer-center/qna

Phase 4: 생산/출고/품질 모듈 (4개)

production/work-orders (등록/수정만, 상세는 renderView)
production/screen-production (등록/수정만, 상세는 renderView)
outbound/shipments
quality/inspections

Phase 5: 건설 모듈 (6개)

construction/project/bidding/partners
construction/project/bidding/site-briefings
construction/project/contract
construction/project/issue-management
construction/order/base-info/pricing
construction/order/base-info/labor

Phase 6: 나머지 패턴 (B, C, D)

• 패턴 B: mode 파라미터 처리 추가
• 패턴 C: 등록 없는 케이스 처리
• 패턴 D: 조회 전용 모드

---

8. 파일 구조 계획

src/components/templates/
├── IntegratedListTemplateV2/     # 기존 리스트 템플릿
│   ├── index.tsx
│   ├── types.ts
│   └── ...
│
└── IntegratedDetailTemplate/     # 새 상세 템플릿
    ├── index.tsx                 # 메인 컴포넌트
    ├── types.ts                  # 타입 정의
    ├── DetailHeader.tsx          # 헤더 (제목, 뒤로가기, 액션버튼)
    ├── DetailForm.tsx            # 폼 렌더링 (정적 config 기반)
    ├── DetailView.tsx            # 조회 모드 렌더링
    ├── FieldRenderer.tsx         # 필드 타입별 렌더링
    ├── GridLayout.tsx            # 그리드 레이아웃 (2열, 3열)
    └── hooks/
        ├── useDetailPage.ts      # 공통 로직 훅
        └── useFormHandler.ts     # 폼 제출 처리 훅

---

9. 마이그레이션 체크리스트

모듈별 마이그레이션 단계

• 기존 컴포넌트 분석
• config 파일 작성
• 등록 페이지 마이그레이션
• 상세 페이지 마이그레이션
• 수정 페이지 마이그레이션
• 기능 테스트
• 기존 파일 정리

Phase 1 체크리스트

• IntegratedDetailTemplate 기본 구조 구현
• settings/popup-management 마이그레이션
• hr/card-management 마이그레이션
• master-data/process-management 마이그레이션
• 템플릿 구조 검증 및 수정

---

10. 참고 자료

관련 파일

• 리스트 템플릿: src/components/templates/IntegratedListTemplateV2/
• 테스트 URL 목록: claudedocs/[REF] all-pages-test-urls.md
• 건설 테스트 URL: claudedocs/[REF] construction-pages-test-urls.md
• 동적 폼 참고: src/components/items/DynamicItemForm/

기존 mode 패턴 참고

• accounting/vendors/[id]/page.tsx → VendorDetail (mode 파라미터)
• accounting/bills/[id]/page.tsx → BillDetail (mode 파라미터)
• hr/employee-management/[id]/page.tsx → EmployeeForm (mode 파라미터)

---

11. 변경 이력

날짜	내용
2026-01-17	초기 계획 수립
2026-01-17	특이 패턴 분석 추가 (문서 모달, 특수 상세 UI)
2026-01-17	품목관리(items) 동적 폼으로 인한 완전 제외 결정
2026-01-17	미래 동적 폼 전환 대비 설계 추가 (renderForm prop)