sam-react-prod/claudedocs/sales/[IMPL-2025-12-04] client-management-api-integration.md

거래처관리 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. 기반 작업

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

2. 기본 훅 구현

• useClientList 훅 생성 (기본 CRUD)
• useClientGroupList 훅 생성 (그룹 CRUD)

3. 기본 페이지 연동

• 목록 조회, 페이지네이션, 검색 연동
• 기본 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: 프론트엔드 재구현 ✅ 완료

• useClientList 훅 확장

  • 새 필드들 타입 정의 추가 (19개 필드)
  • 변환 함수 업데이트 (transformClientToApiCreate, transformClientToApiUpdate, clientToFormData)

• 거래처 등록/수정 페이지 생성

  • ClientRegistration.tsx 컴포넌트 생성 (sam-design 복제)
  • ResponsiveFormTemplate 적용
  • 7개 섹션 폼 구현
    • 기본 정보 섹션
    • 연락처 정보 섹션
    • 담당자 정보 섹션
    • 발주처 설정 섹션
    • 약정 세금 섹션
    • 악성채권 정보 섹션
    • 기타 정보 섹션
  • 유효성 검사 구현
  • API 연동

• 거래처 상세 페이지 생성

  • ClientDetail.tsx 컴포넌트 생성
  • 4개 섹션 (기본정보, 연락처, 결제정보, 악성채권)
  • 삭제 확인 다이얼로그

• 라우팅 설정

  • 등록 페이지: /sales/client-management-sales-admin/new
  • 상세 페이지: /sales/client-management-sales-admin/[id]
  • 수정 페이지: /sales/client-management-sales-admin/[id]/edit

• 목록 페이지 수정

  • "거래처 등록" 버튼 → 등록 페이지 이동
  • 수정 버튼 → 수정 페이지 이동
  • 행 클릭 → 상세 페이지 이동
  • 기존 모달 삭제

---

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 테스트 및 검증