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

> 브랜치: `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%) |

#### 동적 폼 지원 설계
```tsx
// 현재 (정적 폼)
<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 특수 패턴 처리 방안

```tsx
// 특수 상세 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 기본 구조
```tsx
// 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 사용 예시

#### 기본 사용 (정적 폼)
```tsx
// 통합 방식 (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
```tsx
<IntegratedDetailTemplate
  mode="view"
  id={params.id}
  config={quoteConfig}
  fetchData={getQuote}
  renderView={(data) => <QuoteDocumentView data={data} />}
/>
```

#### 미래: 동적 폼 사용
```tsx
<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) |