sam-docs/plans/sub/contract-plan.md

계약관리 (Contract) API 연동 계획

작성일: 2026-01-08 상위 문서: construction-api-integration-plan.md 상태: ⏳ 대기

---

1. 컴포넌트 분석

1.1 파일 위치

react/src/
├── app/[locale]/(protected)/construction/project/contract/
│   └── page.tsx
└── components/business/construction/contract/
    ├── ContractListClient.tsx
    ├── actions.ts
    └── types.ts

1.2 현재 Mock 데이터

actions.ts 내 MOCK_CONTRACTS:

const MOCK_CONTRACTS: Contract[] = [
  {
    id: '1',
    contractNumber: 'CON-2025-0001',
    title: '강남 오피스텔 신축공사 계약',
    partnerId: '1',
    partnerName: '대우건설',
    contractManagerId: 'M1',
    contractManagerName: '김영수',
    constructionPmId: 'PM1',
    constructionPmName: '이철수',
    startDate: '2025-01-01',
    endDate: '2025-12-31',
    amount: 5000000000,
    status: 'active',
    stage: 'construction',
    createdAt: '2024-12-01T00:00:00Z',
    updatedAt: '2025-01-01T00:00:00Z',
  },
  // ... 총 9개 계약
];

1.3 현재 함수 목록

함수명	용도	Mock 상태
getContractList	계약 목록 조회	✅ Mock
getContractStats	계약 통계 조회	✅ Mock
getContractStageCounts	단계별 카운트	✅ Mock
getContract	계약 상세 조회	✅ Mock
deleteContract	계약 삭제	✅ Mock
deleteContracts	계약 일괄 삭제	✅ Mock
getContractDetail	계약 상세 (확장)	✅ Mock
updateContract	계약 수정	✅ Mock

---

2. API 설계

2.1 엔드포인트

Method	Endpoint	용도
GET	/api/construction/contracts	목록 조회
GET	/api/construction/contracts/stats	통계 조회
GET	/api/construction/contracts/stage-counts	단계별 카운트
GET	/api/construction/contracts/{id}	상세 조회
POST	/api/construction/contracts	등록
PUT	/api/construction/contracts/{id}	수정
DELETE	/api/construction/contracts/{id}	삭제
DELETE	/api/construction/contracts/bulk	일괄 삭제

2.2 요청/응답 스키마

목록 조회 Request:

interface GetContractListParams {
  page?: number;
  size?: number;
  startDate?: string;
  endDate?: string;
  partnerId?: string;
  contractManagerId?: string;
  constructionPmId?: string;
  status?: ContractStatus;
  stage?: ContractStage;
  search?: string;
}

목록 조회 Response:

interface ContractListResponse {
  items: Contract[];
  totalCount: number;
  page: number;
  size: number;
}

---

3. 작업 항목

3.1 Backend (API)

#	작업	상태	비고
1	ContractController 생성	⏳
2	ContractService 생성	⏳
3	ContractFormRequest 생성	⏳
4	Contract 모델 확인/수정	⏳
5	routes/api.php 등록	⏳
6	Swagger 문서 작성	⏳

3.2 Frontend (React)

#	작업	상태	비고
1	actions.ts Mock → API 변환	⏳
2	API 클라이언트 연동	⏳
3	에러 핸들링 추가	⏳
4	types.ts 정합성 확인	⏳

---

4. 타입 정의

4.1 Contract 타입

interface Contract {
  id: string;
  contractNumber: string;
  title: string;
  partnerId: string;
  partnerName: string;
  contractManagerId: string;
  contractManagerName: string;
  constructionPmId: string;
  constructionPmName: string;
  startDate: string;
  endDate: string;
  amount: number;
  status: ContractStatus;
  stage: ContractStage;
  createdAt: string;
  updatedAt: string;
}

type ContractStatus = 'active' | 'completed' | 'suspended' | 'terminated';
type ContractStage = 'contract' | 'pre_construction' | 'construction' | 'completion' | 'warranty';

---

5. 변경 이력

날짜	작업	상태
2026-01-08	문서 초안 작성	✅

---

상위 문서: construction-api-integration-plan.md