# Phase 2.2 거래처관리 API 연동

**날짜**: 2026-01-09
**작업**: 거래처관리 Mock → API 연동

## 개요

시공사 페이지 API 연동 계획 Phase 2.2 - 거래처관리(partners) API 연동 완료.

## 변경 사항

### Backend (API)

#### 1. 서비스 (ClientService.php)
- `stats()` - 거래처 통계 조회 (신규)
  - total: 전체 거래처 수
  - sales: 판매 거래처 (client_type='SALES')
  - purchase: 구매 거래처 (client_type='PURCHASE')
  - both: 판매/구매 거래처 (client_type='BOTH')
  - badDebt: 악성채권 보유 거래처 수
  - normal: 정상 거래처 수
- `bulkDestroy()` - 일괄 삭제 (신규)
  - 주문 존재 시 해당 거래처는 건너뜀

#### 2. 컨트롤러 (ClientController.php)
- `stats()` - GET /api/v1/clients/stats
- `bulkDestroy()` - DELETE /api/v1/clients/bulk

#### 3. 라우트 (api.php)
```php
Route::get('/stats', [ClientController::class, 'stats']);
Route::delete('/bulk', [ClientController::class, 'bulkDestroy']);
```

### Frontend (React)

#### 1. actions.ts
- Mock 데이터 제거 (mockPartners 배열)
- API 연동 구현
  - `getPartnerList()` - GET /api/v1/clients
  - `getPartner()` - GET /api/v1/clients/{id}
  - `createPartner()` - POST /api/v1/clients
  - `updatePartner()` - PUT /api/v1/clients/{id}
  - `getPartnerStats()` - GET /api/v1/clients/stats
  - `deletePartner()` - DELETE /api/v1/clients/{id}
  - `deletePartners()` - DELETE /api/v1/clients/bulk

#### 2. 변환 함수
- `transformClientType()` - client_type → partnerType 변환
- `transformPartnerType()` - partnerType → client_type 변환
- `transformPartner()` - API 응답 → Partner 타입 변환
- `transformPartnerToApi()` - PartnerFormData → API 요청 데이터 변환

## API 매핑

| Frontend | Backend | 비고 |
|----------|---------|------|
| id | id | string ↔ int |
| partnerCode | client_code | 자동 생성 |
| businessNumber | business_no | |
| partnerName | name | |
| representative | contact_person | |
| partnerType | client_type | sales/SALES, purchase/PURCHASE, both/BOTH |
| businessType | business_type | |
| businessCategory | business_item | |
| address1 | address | |
| phone | phone | |
| mobile | mobile | |
| fax | fax | |
| email | email | |
| manager | manager_name | |
| managerPhone | manager_tel | |
| systemManager | system_manager | |
| outstandingAmount | outstanding_amount | 계산 필드 (매출-입금) |
| overdueToggle | is_overdue | |
| isBadDebt | has_bad_debt | 계산 필드 |
| isActive | is_active | |
| createdAt | created_at | |
| updatedAt | updated_at | |

### Frontend 전용 필드 (기본값 사용)
- zipCode, address2: ''
- logoUrl, logoBlob: null
- salesPaymentDay, paymentDay: 0
- creditRating, transactionGrade: ''
- memos, documents: []
- category: ''
- overdueDays: is_overdue ? 30 : 0

## 설계 결정

### 기존 Client API 재사용
- `/api/v1/clients` 기존 엔드포인트 확장 사용
- 별도의 `/api/v1/construction/partners` 생성하지 않음
- accounting/vendors 와 construction/partners 모두 Client API 사용

### 악성채권 통계
- BadDebt 테이블과 연계하여 악성채권 보유 거래처 수 계산
- 상태가 '추심중' 또는 '법적조치'인 활성 악성채권만 카운트

### 필터링 전략
- 검색(`q`): API에서 처리 (name, client_code, contact_person)
- 악성채권 필터: 프론트엔드에서 처리 (API 전체 반환 후 필터)
- 정렬: 프론트엔드에서 처리 (API 기본 정렬 사용)

## 진행률

시공사 API 연동: 4/9 (44%)
- [x] Phase 1.1 견적관리
- [x] Phase 1.2 인수인계보고서관리
- [x] Phase 2.1 현장관리
- [x] Phase 2.2 거래처관리 ← 현재 완료
- [ ] Phase 2.3 자재관리
- [ ] Phase 3.1 발주관리
- [ ] Phase 3.2 재고관리
- [ ] Phase 4.1 정산관리
- [ ] Phase 4.2 급여관리