# 인수인계보고서관리 (Handover Report) API 연동 계획

> **작성일**: 2026-01-08
> **상위 문서**: [construction-api-integration-plan.md](../construction-api-integration-plan.md)
> **상태**: ✅ 완료
> **마지막 업데이트**: 2026-01-09

---

## 1. 컴포넌트 분석

### 1.1 파일 위치
```
react/src/
├── app/[locale]/(protected)/construction/project/contract/handover-report/
│   └── page.tsx
└── components/business/construction/handover-report/
    ├── HandoverReportListClient.tsx
    ├── HandoverReportDetailForm.tsx
    ├── actions.ts
    ├── types.ts
    ├── index.ts
    └── modals/
        ├── HandoverReportDocumentModal.tsx
        └── index.ts
```

### 1.2 현재 Mock 데이터

**actions.ts 내 MOCK_REPORTS:**
```typescript
const MOCK_REPORTS: HandoverReport[] = [
  {
    id: '1',
    reportNumber: '123123',
    partnerName: '통신공사',
    siteName: '서울역사 통신공사',
    // ... 총 7개 보고서
  },
];

const MOCK_REPORT_DETAILS: Record<string, HandoverReportDetail> = {
  '1': { ... },
  '2': { ... },
};
```

### 1.3 현재 함수 목록

| 함수명 | 용도 | Mock 상태 |
|--------|------|:--------:|
| `getHandoverReportList` | 보고서 목록 조회 | ✅ Mock |
| `getHandoverReportStats` | 보고서 통계 조회 | ✅ Mock |
| `deleteHandoverReport` | 보고서 삭제 | ✅ Mock |
| `deleteHandoverReports` | 보고서 일괄 삭제 | ✅ Mock |
| `getHandoverReportDetail` | 보고서 상세 조회 | ✅ Mock |
| `updateHandoverReport` | 보고서 수정 | ✅ Mock |

---

## 2. API 설계

### 2.1 엔드포인트 (실제 구현됨)

| Method | Endpoint | 용도 | 상태 |
|--------|----------|------|:----:|
| GET | `/api/v1/construction/handover-reports` | 목록 조회 | ✅ |
| GET | `/api/v1/construction/handover-reports/stats` | 통계 조회 | ✅ |
| GET | `/api/v1/construction/handover-reports/{id}` | 상세 조회 | ✅ |
| POST | `/api/v1/construction/handover-reports` | 등록 | ✅ |
| PUT | `/api/v1/construction/handover-reports/{id}` | 수정 | ✅ |
| DELETE | `/api/v1/construction/handover-reports/{id}` | 삭제 | ✅ |
| DELETE | `/api/v1/construction/handover-reports/bulk` | 일괄 삭제 | ✅ |

### 2.2 요청/응답 스키마

**목록 조회 Request:**
```typescript
interface GetHandoverReportListParams {
  page?: number;
  size?: number;
  startDate?: string;
  endDate?: string;
  contractId?: string;
  partnerId?: string;
  status?: HandoverReportStatus;
  search?: string;
}
```

---

## 3. 작업 항목

### 3.1 Backend (API) ✅ 완료

| # | 작업 | 상태 | 파일 |
|---|------|:----:|------|
| 1 | HandoverReportController 생성 | ✅ | `api/app/Http/Controllers/Api/V1/Construction/HandoverReportController.php` |
| 2 | HandoverReportService 생성 | ✅ | `api/app/Services/Construction/HandoverReportService.php` |
| 3 | HandoverReportFormRequest 생성 | ✅ | `api/app/Http/Requests/Construction/HandoverReport*.php` |
| 4 | HandoverReport 모델 생성 | ✅ | `api/app/Models/Construction/HandoverReport*.php` |
| 5 | routes/api.php 등록 | ✅ | 라인 438-446 |
| 6 | Migrations 생성 | ✅ | 3개 테이블 (reports, managers, items) |

### 3.2 Frontend (React) ✅ 완료

| # | 작업 | 상태 | 비고 |
|---|------|:----:|------|
| 1 | actions.ts Mock → API 변환 | ✅ | 7개 함수 완료 (create 추가) |
| 2 | API 클라이언트 연동 | ✅ | apiRequest 헬퍼 구현 |
| 3 | 에러 핸들링 추가 | ✅ | try-catch + 에러 메시지 |
| 4 | types.ts 정합성 확인 | ✅ | 타입 검사 통과 |

---

## 4. 타입 정의

### 4.1 HandoverReport 타입 (현재 types.ts)

```typescript
interface HandoverReport {
  id: string;
  reportNumber: string;
  partnerName: string;
  siteName: string;
  contractManagerName: string;
  constructionPMName: string | null;
  totalSites: number;
  contractAmount: number;
  contractStartDate: string;
  contractEndDate: string;
  status: HandoverReportStatus;
  contractId: string;
  createdAt: string;
  updatedAt: string;
}

type HandoverReportStatus = 'pending' | 'completed';
```

---

## 5. 변경 이력

| 날짜 | 작업 | 상태 |
|------|------|------|
| 2026-01-08 | 문서 초안 작성 | ✅ |
| 2026-01-09 | Backend 완료 확인, Frontend 작업 시작 | ✅ |
| 2026-01-09 | Frontend actions.ts API 연동 완료 | ✅ |

---

*상위 문서: [construction-api-integration-plan.md](../construction-api-integration-plan.md)*