# 상세 페이지 훅 마이그레이션 계획서

> 작성일: 2026-02-05
> 상태: 계획 수립

---

## 1. 개요

### 1.1 목적
- 상세/등록/수정 페이지의 반복 코드를 공통 훅으로 통합
- 코드 일관성 확보 및 유지보수성 향상
- 서비스 런칭 전 기술 부채 최소화

### 1.2 생성된 공통 훅
| 훅 | 위치 | 역할 |
|----|------|------|
| `useDetailPageState` | `src/hooks/useDetailPageState.ts` | 페이지 상태 관리 (mode, id, navigation) |
| `useDetailData` | `src/hooks/useDetailData.ts` | 데이터 로딩 + 로딩/에러 상태 |
| `useCRUDHandlers` | `src/hooks/useCRUDHandlers.ts` | 등록/수정/삭제 + toast/redirect |
| `useDetailPermissions` | `src/hooks/useDetailPermissions.ts` | 권한 체크 |

### 1.3 테스트 완료
- [x] `BillDetail.tsx` → `BillDetailV2.tsx` 마이그레이션 성공
- [x] 조회/수정/등록 모드 정상 작동 확인
- [x] 유효성 검사 정상 작동 확인

---

## 2. 마이그레이션 대상

### 2.1 전체 현황
| 구분 | 개수 | 비고 |
|------|------|------|
| IntegratedDetailTemplate 사용 | 47개 | 훅 마이그레이션 대상 |
| 레거시/커스텀 패턴 | 36개 | 별도 검토 (이번 범위 외) |
| **총계** | 83개 | |

### 2.2 복잡도별 분류
| 복잡도 | 기준 | 개수 |
|--------|------|------|
| 단순 | < 200줄, useState 3~4개 | 12개 |
| 보통 | 200~500줄, useState 5~7개 | 18개 |
| 복잡 | > 500줄, useState 8~11개 | 17개 |

---

## 3. 도메인별 대상 목록

### 3.1 회계관리 (10개)

| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `accounting/BadDebtCollection/BadDebtDetail.tsx` | 966 | 복잡 | ⬜ |
| 2 | `accounting/BillManagement/BillDetail.tsx` | 474 | 보통 | ✅ 완료 |
| 3 | `accounting/CardTransactionInquiry/CardTransactionDetailClient.tsx` | 138 | 단순 | ⬜ |
| 4 | `accounting/DepositManagement/DepositDetailClientV2.tsx` | 143 | 단순 | ⬜ |
| 5 | `accounting/PurchaseManagement/PurchaseDetail.tsx` | 698 | 복잡 | ⬜ |
| 6 | `accounting/SalesManagement/SalesDetail.tsx` | 581 | 복잡 | ⬜ |
| 7 | `accounting/VendorLedger/VendorLedgerDetail.tsx` | 385 | 보통 | ⬜ |
| 8 | `accounting/VendorManagement/VendorDetail.tsx` | 683 | 복잡 | ⬜ |
| 9 | `accounting/VendorManagement/VendorDetailClient.tsx` | 585 | 복잡 | ⬜ |
| 10 | `accounting/WithdrawalManagement/WithdrawalDetail.tsx` | 327 | 보통 | ⬜ |

### 3.2 건설관리 (13개)

| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `construction/bidding/BiddingDetailForm.tsx` | 544 | 복잡 | ⬜ |
| 2 | `construction/contract/ContractDetailForm.tsx` | 546 | 복잡 | ⬜ |
| 3 | `construction/estimates/EstimateDetailForm.tsx` | 763 | 복잡 | ⬜ |
| 4 | `construction/handover-report/HandoverReportDetailForm.tsx` | 699 | 복잡 | ⬜ |
| 5 | `construction/issue-management/IssueDetailForm.tsx` | 627 | 복잡 | ⬜ |
| 6 | `construction/item-management/ItemDetailClient.tsx` | 486 | 보통 | ⬜ |
| 7 | `construction/labor-management/LaborDetailClientV2.tsx` | 120 | 단순 | ⬜ |
| 8 | `construction/management/ConstructionDetailClient.tsx` | 739 | 복잡 | ⬜ |
| 9 | `construction/order-management/OrderDetailForm.tsx` | 275 | 보통 | ⬜ |
| 10 | `construction/pricing-management/PricingDetailClientV2.tsx` | 134 | 단순 | ⬜ |
| 11 | `construction/progress-billing/ProgressBillingDetailForm.tsx` | 193 | 단순 | ⬜ |
| 12 | `construction/site-management/SiteDetailForm.tsx` | 385 | 보통 | ⬜ |
| 13 | `construction/structure-review/StructureReviewDetailForm.tsx` | 392 | 보통 | ⬜ |

### 3.3 기타 도메인 (24개)

#### 고객센터 (3개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `customer-center/EventManagement/EventDetail.tsx` | 101 | 단순 | ⬜ |
| 2 | `customer-center/InquiryManagement/InquiryDetail.tsx` | 357 | 보통 | ⬜ |
| 3 | `customer-center/NoticeManagement/NoticeDetail.tsx` | 101 | 단순 | ⬜ |

#### 인사관리 (1개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `hr/EmployeeManagement/EmployeeDetail.tsx` | 221 | 단순 | ⬜ |

#### 자재관리 (2개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `material/ReceivingManagement/ReceivingDetail.tsx` | ~350 | 보통 | ⬜ |
| 2 | `material/StockStatus/StockStatusDetail.tsx` | ~300 | 보통 | ⬜ |

#### 주문관리 (2개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `orders/OrderSalesDetailEdit.tsx` | 735 | 복잡 | ⬜ |
| 2 | `orders/OrderSalesDetailView.tsx` | 668 | 복잡 | ⬜ |

#### 출고관리 (2개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `outbound/ShipmentManagement/ShipmentDetail.tsx` | 670 | 복잡 | ⬜ |
| 2 | `outbound/VehicleDispatchManagement/VehicleDispatchDetail.tsx` | 180 | 단순 | ⬜ |

#### 생산관리 (1개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `production/WorkOrders/WorkOrderDetail.tsx` | 531 | 복잡 | ⬜ |

#### 품질관리 (1개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `quality/InspectionManagement/InspectionDetail.tsx` | 949 | 복잡 | ⬜ |

#### 설정 (2개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `settings/PermissionManagement/PermissionDetail.tsx` | 455 | 보통 | ⬜ |
| 2 | `settings/PopupManagement/PopupDetailClientV2.tsx` | 198 | 단순 | ⬜ |

#### 거래처 (1개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `clients/ClientDetailClientV2.tsx` | 252 | 단순 | ⬜ |

#### 기타 (9개)
| # | 파일 | 라인 | 복잡도 | 상태 |
|---|------|------|--------|------|
| 1 | `board/BoardManagement/BoardDetail.tsx` | 119 | 단순 | ⬜ |
| 2 | `process-management/ProcessDetail.tsx` | 346 | 보통 | ⬜ |
| 3 | `process-management/StepDetail.tsx` | 143 | 단순 | ⬜ |
| 4 | `settings/AccountManagement/AccountDetail.tsx` | 355 | 보통 | ⬜ |
| 5 | `accounting/DepositManagement/DepositDetail.tsx` | 327 | 보통 | ⬜ |
| 6 | `clients/ClientDetail.tsx` | 253 | 보통 | ⬜ |
| 7 | `construction/labor-management/LaborDetailClient.tsx` | 471 | 보통 | ⬜ |
| 8 | `construction/pricing-management/PricingDetailClient.tsx` | 464 | 보통 | ⬜ |
| 9 | `quotes/LocationDetailPanel.tsx` | 826 | 복잡 | ⬜ |

---

## 4. 작업 방식

### 4.1 Git 브랜치 전략
```
main
  └── feature/detail-hooks-migration
        ├── 회계관리 커밋
        ├── 건설관리 커밋
        └── 기타 도메인 커밋
```

### 4.2 파일별 작업 순서
1. 파일 읽기 및 현재 패턴 파악
2. `useDetailData` 적용 (데이터 로딩 부분)
3. `useCRUDHandlers` 적용 (CRUD 핸들러 부분)
4. 개별 useState → 통합 formData 객체로 변환 (선택)
5. 기능 테스트
6. 커밋

### 4.3 적용할 변경 패턴

#### Before (기존)
```tsx
const [data, setData] = useState(null);
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState(null);

useEffect(() => {
  fetchData(id).then(result => {
    if (result.success) setData(result.data);
    else setError(result.error);
  }).finally(() => setIsLoading(false));
}, [id]);

const handleSubmit = async () => {
  const result = await updateData(id, formData);
  if (result.success) {
    toast.success('저장되었습니다.');
    router.push('/list');
  } else {
    toast.error(result.error);
  }
};
```

#### After (신규)
```tsx
const { data, isLoading, error } = useDetailData(id, fetchData);

const { handleUpdate, isSubmitting } = useCRUDHandlers({
  onUpdate: updateData,
  successRedirect: '/list',
  successMessages: { update: '저장되었습니다.' },
});
```

---

## 5. 일정 계획

| Phase | 대상 | 파일 수 | 예상 기간 |
|-------|------|---------|----------|
| Phase 1 | 회계관리 | 10개 | 1일 |
| Phase 2 | 건설관리 | 13개 | 1.5일 |
| Phase 3 | 기타 도메인 | 24개 | 2일 |
| Phase 4 | 통합 테스트 | - | 1일 |
| **총계** | | **47개** | **약 5~6일** |

---

## 6. 체크리스트

### 6.1 사전 준비
- [x] 공통 훅 4개 생성 완료
- [x] 테스트 마이그레이션 (BillDetail) 완료
- [x] 계획서 작성
- [ ] 브랜치 생성

### 6.2 Phase 1: 회계관리 (0/10)
- [ ] BadDebtDetail.tsx
- [x] BillDetail.tsx ✅
- [ ] CardTransactionDetailClient.tsx
- [ ] DepositDetailClientV2.tsx
- [ ] PurchaseDetail.tsx
- [ ] SalesDetail.tsx
- [ ] VendorLedgerDetail.tsx
- [ ] VendorDetail.tsx
- [ ] VendorDetailClient.tsx
- [ ] WithdrawalDetail.tsx

### 6.3 Phase 2: 건설관리 (0/13)
- [ ] BiddingDetailForm.tsx
- [ ] ContractDetailForm.tsx
- [ ] EstimateDetailForm.tsx
- [ ] HandoverReportDetailForm.tsx
- [ ] IssueDetailForm.tsx
- [ ] ItemDetailClient.tsx
- [ ] LaborDetailClientV2.tsx
- [ ] ConstructionDetailClient.tsx
- [ ] OrderDetailForm.tsx
- [ ] PricingDetailClientV2.tsx
- [ ] ProgressBillingDetailForm.tsx
- [ ] SiteDetailForm.tsx
- [ ] StructureReviewDetailForm.tsx

### 6.4 Phase 3: 기타 도메인 (0/24)
- [ ] EventDetail.tsx
- [ ] InquiryDetail.tsx
- [ ] NoticeDetail.tsx
- [ ] EmployeeDetail.tsx
- [ ] ReceivingDetail.tsx
- [ ] StockStatusDetail.tsx
- [ ] OrderSalesDetailEdit.tsx
- [ ] OrderSalesDetailView.tsx
- [ ] ShipmentDetail.tsx
- [ ] VehicleDispatchDetail.tsx
- [ ] WorkOrderDetail.tsx
- [ ] InspectionDetail.tsx
- [ ] PermissionDetail.tsx
- [ ] PopupDetailClientV2.tsx
- [ ] ClientDetailClientV2.tsx
- [ ] BoardDetail.tsx
- [ ] ProcessDetail.tsx
- [ ] StepDetail.tsx
- [ ] AccountDetail.tsx
- [ ] DepositDetail.tsx
- [ ] ClientDetail.tsx
- [ ] LaborDetailClient.tsx
- [ ] PricingDetailClient.tsx
- [ ] LocationDetailPanel.tsx

### 6.5 완료 후
- [ ] 전체 기능 테스트
- [ ] 코드 리뷰
- [ ] PR 머지
- [ ] BillDetailV2.tsx 정리 (원본으로 교체)

---

## 7. 위험 요소 및 대응

| 위험 | 가능성 | 대응 |
|------|--------|------|
| 기존 기능 손상 | 중 | 파일별 테스트, Git 롤백 준비 |
| 예상보다 복잡한 파일 | 중 | 복잡한 파일은 부분 적용 허용 |
| 타입 에러 | 높 | 래퍼 함수로 타입 호환성 확보 |

---

## 8. 참고 자료

- 공통 훅 소스: `src/hooks/index.ts`
- 테스트 케이스: `BillDetailV2.tsx`
- 기존 템플릿: `IntegratedDetailTemplate.tsx`
