sam-docs/plans/sub/handover-report-plan.md

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

작성일: 2026-01-08 상위 문서: 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:

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:

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)

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