# 거래처관리 API 연동 체크리스트

> **작성일**: 2025-12-04
> **목적**: 거래처관리 페이지 API 연동 및 sam-design 기준 UI 구현
> **최종 업데이트**: 2025-12-04 ✅ 구현 완료

---

## ✅ 구현 완료 상태

> **완료**: sam-design 기준으로 전체 페이지 재구현 완료
> - 등록, 수정, 상세 보기 페이지 생성
> - 목록 페이지에서 모달 삭제 및 페이지 기반 네비게이션으로 변경

### sam-design 참조 파일
- `sam-design/src/components/ClientRegistration.tsx`
- `sam-design/src/components/templates/ResponsiveFormTemplate.tsx`

---

## 작업 현황

### ✅ 1차 완료 작업 (기본 API 연동)

#### 1. 기반 작업
- [x] API 분석 문서 생성 (`[API-2025-12-04] client-api-analysis.md`)
- [x] Catch-all API Proxy 확인 (`/api/proxy/[...path]` 존재)
- [x] PATCH 메서드 프록시 추가 - toggle 엔드포인트용
- [x] 백엔드 1차 필드 추가 완료 (business_no, business_type, business_item)

#### 2. 기본 훅 구현
- [x] useClientList 훅 생성 (기본 CRUD)
- [x] useClientGroupList 훅 생성 (그룹 CRUD)

#### 3. 기본 페이지 연동
- [x] 목록 조회, 페이지네이션, 검색 연동
- [x] 기본 CRUD 연동 (생성, 수정, 삭제)

---

### ✅ 2차 완료 작업 (sam-design 기준 재구현) - 2025-12-04

#### Phase 1: 백엔드 API 필드 추가 요청 ⏳ 대기중

**추가 요청 필드 (총 19개)**:

| 섹션 | 필드명 | 설명 | 프론트 지원 |
|------|--------|------|------------|
| 기본 정보 | `client_type` | 거래처 유형 (매입/매출/매입매출) | ✅ |
| 연락처 | `mobile` | 모바일 번호 | ✅ |
| 연락처 | `fax` | 팩스 번호 | ✅ |
| 담당자 | `manager_name` | 담당자명 | ✅ |
| 담당자 | `manager_tel` | 담당자 전화 | ✅ |
| 담당자 | `system_manager` | 시스템 관리자 | ✅ |
| 발주처 | `account_id` | 계정 ID | ✅ |
| 발주처 | `account_password` | 비밀번호 | ✅ |
| 발주처 | `purchase_payment_day` | 매입 결제일 | ✅ |
| 발주처 | `sales_payment_day` | 매출 결제일 | ✅ |
| 약정세금 | `tax_agreement` | 세금 약정 여부 | ✅ |
| 약정세금 | `tax_amount` | 약정 금액 | ✅ |
| 약정세금 | `tax_start_date` | 약정 시작일 | ✅ |
| 약정세금 | `tax_end_date` | 약정 종료일 | ✅ |
| 악성채권 | `bad_debt` | 악성채권 여부 | ✅ |
| 악성채권 | `bad_debt_amount` | 악성채권 금액 | ✅ |
| 악성채권 | `bad_debt_receive_date` | 채권 발생일 | ✅ |
| 악성채권 | `bad_debt_end_date` | 채권 만료일 | ✅ |
| 악성채권 | `bad_debt_progress` | 진행 상태 | ✅ |
| 기타 | `memo` | 메모 | ✅ |

> **참고**: 프론트엔드는 모든 필드를 지원하도록 구현 완료. 백엔드 API 필드 추가 후 즉시 사용 가능.

---

#### Phase 2: 프론트엔드 재구현 ✅ 완료

- [x] **useClientList 훅 확장**
  - [x] 새 필드들 타입 정의 추가 (19개 필드)
  - [x] 변환 함수 업데이트 (transformClientToApiCreate, transformClientToApiUpdate, clientToFormData)

- [x] **거래처 등록/수정 페이지 생성**
  - [x] `ClientRegistration.tsx` 컴포넌트 생성 (sam-design 복제)
  - [x] ResponsiveFormTemplate 적용
  - [x] 7개 섹션 폼 구현
    - [x] 기본 정보 섹션
    - [x] 연락처 정보 섹션
    - [x] 담당자 정보 섹션
    - [x] 발주처 설정 섹션
    - [x] 약정 세금 섹션
    - [x] 악성채권 정보 섹션
    - [x] 기타 정보 섹션
  - [x] 유효성 검사 구현
  - [x] API 연동

- [x] **거래처 상세 페이지 생성**
  - [x] `ClientDetail.tsx` 컴포넌트 생성
  - [x] 4개 섹션 (기본정보, 연락처, 결제정보, 악성채권)
  - [x] 삭제 확인 다이얼로그

- [x] **라우팅 설정**
  - [x] 등록 페이지: `/sales/client-management-sales-admin/new`
  - [x] 상세 페이지: `/sales/client-management-sales-admin/[id]`
  - [x] 수정 페이지: `/sales/client-management-sales-admin/[id]/edit`

- [x] **목록 페이지 수정**
  - [x] "거래처 등록" 버튼 → 등록 페이지 이동
  - [x] 수정 버튼 → 수정 페이지 이동
  - [x] 행 클릭 → 상세 페이지 이동
  - [x] 기존 모달 삭제

---

## API 엔드포인트 정리

### Client (거래처) API
| Method | Endpoint | 설명 | 프록시 |
|--------|----------|------|--------|
| `GET` | `/api/proxy/clients` | 목록 조회 | ✅ |
| `GET` | `/api/proxy/clients/{id}` | 단건 조회 | ✅ |
| `POST` | `/api/proxy/clients` | 생성 | ✅ |
| `PUT` | `/api/proxy/clients/{id}` | 수정 | ✅ |
| `DELETE` | `/api/proxy/clients/{id}` | 삭제 | ✅ |
| `PATCH` | `/api/proxy/clients/{id}/toggle` | 활성/비활성 | ✅ |

### Client Group (거래처 그룹) API
| Method | Endpoint | 설명 | 프록시 |
|--------|----------|------|--------|
| `GET` | `/api/proxy/client-groups` | 목록 조회 | ✅ |
| `POST` | `/api/proxy/client-groups` | 생성 | ✅ |
| `PUT` | `/api/proxy/client-groups/{id}` | 수정 | ✅ |
| `DELETE` | `/api/proxy/client-groups/{id}` | 삭제 | ✅ |

---

## 파일 변경 목록

### 1차 완료
| 파일 | 작업 | 상태 |
|------|------|------|
| `/src/app/api/proxy/[...path]/route.ts` | PATCH 메서드 추가 | ✅ |
| `/src/hooks/useClientList.ts` | 기본 CRUD 훅 | ✅ |
| `/src/hooks/useClientGroupList.ts` | 그룹 CRUD 훅 | ✅ |

### 2차 완료
| 파일 | 작업 | 상태 |
|------|------|------|
| `/src/hooks/useClientList.ts` | 확장 필드 추가 (19개) | ✅ 완료 |
| `/src/components/clients/ClientRegistration.tsx` | 신규 생성 (sam-design 복제) | ✅ 완료 |
| `/src/components/clients/ClientDetail.tsx` | 상세 보기 컴포넌트 | ✅ 완료 |
| `/src/components/ui/radio-group.tsx` | RadioGroup UI 컴포넌트 | ✅ 완료 |
| `/src/app/[locale]/(protected)/sales/client-management-sales-admin/new/page.tsx` | 등록 페이지 | ✅ 완료 |
| `/src/app/[locale]/(protected)/sales/client-management-sales-admin/[id]/page.tsx` | 상세 페이지 | ✅ 완료 |
| `/src/app/[locale]/(protected)/sales/client-management-sales-admin/[id]/edit/page.tsx` | 수정 페이지 | ✅ 완료 |
| `/src/app/[locale]/(protected)/sales/client-management-sales-admin/page.tsx` | 목록 페이지 (모달 삭제, 페이지 이동) | ✅ 완료 |

---

## 참고 문서

- `[API-2025-12-04] client-api-analysis.md` - 백엔드 API 상세 분석 및 추가 요청
- `sam-design/src/components/ClientRegistration.tsx` - UI 참조
- `sam-design/src/components/templates/ResponsiveFormTemplate.tsx` - 템플릿 참조

---

## 다음 단계 (백엔드 의존)

백엔드에서 19개 필드 추가 완료 후:
1. API 응답에서 새 필드들 확인
2. 필요시 변환 함수 조정
3. UI 테스트 및 검증