sam-docs/features/crm/trading-partners.md

거래처관리

개요

거래처관리는 회사의 거래처(업체/프리랜서)를 등록하고 관리하는 기능입니다. 업종별 분류, 사업자번호/계좌 관리, OCR 명함 인식을 지원합니다.

• 라우트: GET /finance/partners
• 라우트 이름: finance.partners
• UI 기술: React 18 + Babel (브라우저 트랜스파일링)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── TradingPartnerController.php       # 메인 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│   └── TradingPartner.php                 # 거래처 모델
├── app/Services/
│   └── TradingPartnerOcrService.php       # OCR 명함 인식 서비스
└── resources/views/finance/
    └── partners.blade.php                 # React 기반 단일 페이지

api/
└── database/migrations/
    └── 2026_02_04_221050_create_trading_partners_table.php

라우트

// routes/web.php (finance prefix 그룹 내)
GET    /partners            → 페이지 렌더링 (HX-Redirect)

// API 라우트 (partners prefix)
GET    /partners/list       → index()     거래처 목록 (JSON)
POST   /partners/store      → store()     거래처 등록
POST   /partners/ocr        → ocr()       OCR 명함 인식
PUT    /partners/{id}       → update()    거래처 수정
DELETE /partners/{id}       → destroy()   거래처 삭제

컨트롤러

TradingPartnerController

메서드	HTTP	설명
index()	GET	거래처 목록 (검색, 타입/카테고리/상태 필터)
store()	POST	거래처 등록 (name, type, category 필수)
update()	PUT	거래처 수정
ocr()	POST	OCR 명함 인식 (이미지 → 거래처 정보 추출)
destroy()	DELETE	거래처 삭제 (Soft Delete)

index() 응답 구조

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "ABC 솔루션",
      "type": "vendor",
      "category": "IT/소프트웨어",
      "bizNo": "123-45-67890",
      "bankAccount": "우리은행 1002-xxx-xxxxx",
      "contact": "02-1234-5678",
      "email": "info@abc.co.kr",
      "manager": "김담당",
      "managerPhone": "010-1234-5678",
      "status": "active",
      "memo": ""
    }
  ],
  "stats": {
    "total": 50,
    "vendor": 35,
    "freelancer": 15,
    "active": 42
  }
}

모델

TradingPartner

테이블: trading_partners

필드	타입	설명
tenant_id	bigint	테넌트 ID
name	string(100)	거래처명
type	string	vendor(업체) / freelancer(프리랜서)
category	string(50)	업종 카테고리
biz_no	string	사업자번호
bank_account	string	계좌 정보
contact	string	연락처
email	string	이메일
manager	string	담당자명
manager_phone	string	담당자 연락처
status	string	active / inactive
memo	text	메모

• SoftDeletes 적용
• Scope: active(), forTenant($tenantId)

뷰 구성 (React)

partners.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "거래처관리"
│  [CSV 내보내기] [OCR 등록] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│  전체 | 업체 | 프리랜서 | 활성
│
├─ 필터 영역 ────────────────────────
│  검색 (거래처명, 담당자) | 타입 (업체/프리랜서) | 카테고리 | 상태
│
├─ 거래처 목록 테이블 ───────────────
│  거래처명 | 타입 | 카테고리 | 사업자번호 | 계좌 | 담당자 | 상태 | 작업
│  └─ 타입: 업체(파랑), 프리랜서(보라) 배지
│
├─ 등록/수정 모달 ───────────────────
│  거래처명, 타입(업체/프리랜서), 카테고리
│  사업자번호, 계좌정보, 연락처, 이메일
│  담당자, 담당자 연락처, 상태, 메모
│
└─ OCR 모달 ─────────────────────────
   명함 이미지 업로드 → AI 인식 → 자동 필드 채우기

OCR 명함 인식

TradingPartnerOcrService

명함 이미지를 Claude Vision API로 분석하여 거래처 정보를 자동 추출합니다:

• 이미지(Base64) → Claude Vision API 호출
• 회사명, 담당자명, 연락처, 이메일, 주소 등 추출
• 추출 결과를 등록 폼에 자동 입력

HTMX 호환성

• React 기반 페이지이므로 HX-Redirect 필요
• @push('scripts') 블록에 React/Babel 스크립트 포함