# 견적관리 API 연동 작업계획서

> **작성일**: 2025-12-04
> **목적**: 견적관리 페이지 API 연동 및 기능 구현
> **선행 조건**: 백엔드 API 완료 후 진행
> **참조**: `[API-2025-12-04] quote-api-request.md`

---

## 1. 작업 개요

### 1.1 현재 상태
| 항목 | 상태 | 비고 |
|------|------|------|
| 목록 페이지 UI | ✅ 완료 | sam-design 마이그레이션 완료 |
| 등록/수정 화면 | ⏳ 대기 | sam-design 마이그레이션 필요 |
| 상세 화면 | ⏳ 대기 | sam-design 마이그레이션 필요 |
| API 연동 | ❌ 미완료 | 백엔드 API 대기중 |
| 자동 산출 | ❌ 미완료 | 백엔드 수식 엔진 대기중 |

### 1.2 작업 목표
1. API 훅 생성 (useQuoteList, useQuote, useQuoteCalculation)
2. 목록 페이지 API 연동
3. 등록/수정 화면 마이그레이션 및 API 연동
4. 상세 화면 마이그레이션 및 API 연동
5. 자동 산출 기능 연동

---

## 2. 작업 단계

### Phase 1: 기반 작업 (백엔드 API 완료 후)

#### 1.1 API Proxy 확인
- [ ] `/api/proxy/[...path]` 라우트에 quotes 엔드포인트 지원 확인
- [ ] PATCH 메서드 지원 확인 (상태 변경용)

#### 1.2 타입 정의
- [ ] `/src/types/quote.ts` 생성
  - Quote 인터페이스
  - QuoteItem 인터페이스
  - QuoteRevision 인터페이스
  - QuoteFormData 인터페이스
  - QuoteCalculationRequest/Response 인터페이스

---

### Phase 2: API 훅 생성

#### 2.1 useQuoteList 훅
```
파일: /src/hooks/useQuoteList.ts
```

**기능:**
- [ ] 목록 조회 (페이지네이션, 검색, 필터)
- [ ] 단건 삭제
- [ ] 일괄 삭제
- [ ] 상태 필터링 (전체/최초작성/수정중/최종확정/수주전환)

**구현 내용:**
```typescript
export function useQuoteList() {
  return {
    quotes,
    pagination,
    isLoading,
    error,
    fetchQuotes,
    deleteQuote,
    bulkDeleteQuotes,
  };
}
```

#### 2.2 useQuote 훅
```
파일: /src/hooks/useQuote.ts
```

**기능:**
- [ ] 단건 조회 (품목, 이력 포함)
- [ ] 생성
- [ ] 수정 (이력 자동 생성)
- [ ] 최종확정
- [ ] 수주전환
- [ ] 견적번호 생성

**구현 내용:**
```typescript
export function useQuote() {
  return {
    quote,
    isLoading,
    isSaving,
    error,
    fetchQuote,
    createQuote,
    updateQuote,
    finalizeQuote,
    convertToOrder,
    generateQuoteNumber,
  };
}
```

#### 2.3 useQuoteCalculation 훅
```
파일: /src/hooks/useQuoteCalculation.ts
```

**기능:**
- [ ] 자동 견적 산출 요청
- [ ] 재계산 요청
- [ ] 계산 결과 변환

**구현 내용:**
```typescript
export function useQuoteCalculation() {
  return {
    calculationResult,
    isCalculating,
    error,
    calculate,
    recalculate,
    clearResult,
  };
}
```

---

### Phase 3: 목록 페이지 API 연동

```
파일: /src/app/[locale]/(protected)/sales/quote-management/page.tsx
```

#### 3.1 기존 목업 데이터 교체
- [ ] SAMPLE_QUOTES 삭제
- [ ] useQuoteList 훅 연결
- [ ] useEffect로 초기 데이터 로드

#### 3.2 페이지네이션 연동
- [ ] currentPage, totalPages API 연결
- [ ] 페이지 변경 시 fetchQuotes 호출

#### 3.3 검색/필터 연동
- [ ] 검색어 디바운스 처리 (300ms)
- [ ] 탭(상태) 변경 시 필터 적용
- [ ] 검색 파라미터 API 전달

#### 3.4 삭제 기능 연동
- [ ] 단건 삭제 API 연결
- [ ] 일괄 삭제 API 연결
- [ ] 삭제 후 목록 새로고침

#### 3.5 통계 데이터 연동
- [ ] 이번 달 견적 금액
- [ ] 진행중 견적 금액
- [ ] 이번 주 신규 견적
- [ ] 이번 달 수주 전환율

---

### Phase 4: 등록/수정 화면 마이그레이션

#### 4.1 컴포넌트 마이그레이션
```
소스: sam-design/QuoteManagement3Write.tsx (1,790줄)
타겟: /src/app/[locale]/(protected)/sales/quote-management/write/page.tsx
```

- [ ] 기본 정보 섹션 마이그레이션
- [ ] 발주처 선택 (직접입력 포함)
- [ ] 현장 선택 (직접입력 포함)
- [ ] 자동 산출 섹션 연동

#### 4.2 라우팅 설정
```
/sales/quote-management/write       → 신규 등록
/sales/quote-management/[id]/edit   → 수정
```

#### 4.3 자동 산출 연동 (핵심)
- [ ] useQuoteCalculation 훅 연결
- [ ] 제품 선택 → 오픈사이즈 입력 → 자동 산출 호출
- [ ] 계산 결과 BOM 테이블 표시
- [ ] 품목별 수량/단가 수정 가능

#### 4.4 저장 로직
- [ ] 신규 등록: createQuote API 호출
- [ ] 수정: updateQuote API 호출 (수정사유 입력 필요)
- [ ] 저장 후 목록 또는 상세로 이동

---

### Phase 5: 상세 화면 마이그레이션

#### 5.1 컴포넌트 마이그레이션
```
소스: sam-design/QuoteManagement3Detail.tsx (878줄)
타겟: /src/app/[locale]/(protected)/sales/quote-management/[id]/page.tsx
```

- [ ] 기본 정보 표시
- [ ] 자동 산출 정보 표시
- [ ] BOM 계산 결과 테이블
- [ ] 수정 이력 표시

#### 5.2 액션 버튼 연동
- [ ] 수정 버튼 → edit 페이지로 이동
- [ ] 최종확정 → finalizeQuote API
- [ ] 수주전환 → convertToOrder API

#### 5.3 문서 출력 (Phase 6에서 진행)
- [ ] 견적서 PDF
- [ ] 산출내역서 PDF
- [ ] 발주서 PDF

---

### Phase 6: 문서 출력 기능 (Optional)

#### 6.1 견적서 다이얼로그
- [ ] QuoteCalculationReport 컴포넌트 마이그레이션
- [ ] PDF 다운로드 기능

#### 6.2 산출내역서 다이얼로그
- [ ] 표시 옵션 (산출내역서/소요자재 체크박스)
- [ ] PDF 다운로드 기능

#### 6.3 발주서 다이얼로그
- [ ] PurchaseOrderDocument 컴포넌트 마이그레이션
- [ ] PDF 다운로드 기능

---

## 3. 파일 구조

```
src/
├── types/
│   └── quote.ts                    # 타입 정의
├── hooks/
│   ├── useQuoteList.ts            # 목록 훅
│   ├── useQuote.ts                # CRUD 훅
│   └── useQuoteCalculation.ts     # 자동 산출 훅
└── app/[locale]/(protected)/sales/quote-management/
    ├── page.tsx                    # 목록 (기존)
    ├── write/
    │   └── page.tsx               # 등록
    ├── [id]/
    │   ├── page.tsx               # 상세
    │   └── edit/
    │       └── page.tsx           # 수정
    └── components/
        ├── QuoteForm.tsx          # 등록/수정 폼
        ├── QuoteDetail.tsx        # 상세 뷰
        ├── QuoteCalculation.tsx   # 자동 산출 섹션
        ├── QuoteBOMTable.tsx      # BOM 테이블
        └── QuoteDocuments.tsx     # 문서 출력 다이얼로그
```

---

## 4. 체크리스트

### Phase 1: 기반 작업
- [ ] API Proxy 확인
- [ ] 타입 정의 파일 생성

### Phase 2: API 훅
- [ ] useQuoteList.ts 생성
- [ ] useQuote.ts 생성
- [ ] useQuoteCalculation.ts 생성

### Phase 3: 목록 API 연동
- [ ] 목업 데이터 삭제
- [ ] 훅 연결 및 초기 로드
- [ ] 페이지네이션 연동
- [ ] 검색/필터 연동
- [ ] 삭제 기능 연동
- [ ] 통계 데이터 연동

### Phase 4: 등록/수정 화면
- [ ] write/page.tsx 생성
- [ ] [id]/edit/page.tsx 생성
- [ ] QuoteForm 컴포넌트 생성
- [ ] 발주처/현장 선택 기능
- [ ] 자동 산출 연동
- [ ] 저장 로직 연동

### Phase 5: 상세 화면
- [ ] [id]/page.tsx 생성
- [ ] QuoteDetail 컴포넌트 생성
- [ ] 최종확정/수주전환 연동
- [ ] 수정 이력 표시

### Phase 6: 문서 출력 (Optional)
- [ ] 견적서 PDF
- [ ] 산출내역서 PDF
- [ ] 발주서 PDF

---

## 5. 의존성

### 5.1 백엔드 API 의존
| API | 필요 시점 | 상태 |
|-----|----------|------|
| 견적 CRUD | Phase 2 | ⏳ 대기 |
| 자동 산출 | Phase 4 | ⏳ 대기 |
| 상태 변경 | Phase 5 | ⏳ 대기 |
| 문서 출력 | Phase 6 | ⏳ 대기 |

### 5.2 프론트엔드 의존
| 컴포넌트 | 상태 | 비고 |
|----------|------|------|
| IntegratedListTemplateV2 | ✅ 완료 | 목록 템플릿 |
| useClientList | ✅ 완료 | 발주처 선택 |
| useClientGroupList | ✅ 완료 | 발주처 그룹 |

---

## 6. 예상 작업량

| Phase | 작업 내용 | 예상 시간 |
|-------|----------|----------|
| Phase 1 | 기반 작업 | 1-2시간 |
| Phase 2 | API 훅 생성 | 2-3시간 |
| Phase 3 | 목록 API 연동 | 2-3시간 |
| Phase 4 | 등록/수정 마이그레이션 | 4-6시간 |
| Phase 5 | 상세 화면 마이그레이션 | 2-3시간 |
| Phase 6 | 문서 출력 (Optional) | 2-3시간 |
| **총합** | | **13-20시간** |

---

## 7. 참고 문서

- `[API-2025-12-04] quote-api-request.md` - API 요청서
- `[PLAN-2025-12-02] sales-pages-migration.md` - 마이그레이션 계획
- `/src/hooks/useClientList.ts` - 거래처 훅 참고
- sam-design/QuoteManagement3Write.tsx - 등록/수정 소스
- sam-design/QuoteManagement3Detail.tsx - 상세 화면 소스
