# 고객/거래처/채권관리 기능

## 개요

SAM 프로젝트의 고객/거래처/채권관리 모듈은 거래처 및 고객사 정보 관리, 미수금/미지급금 채권·채무 추적,
환불/해지 요청 처리를 종합적으로 관리하는 시스템입니다.
OCR 기반 명함 인식, 부분 수금/지급 처리, 승인 워크플로우를 지원합니다.

## 메뉴 구성

| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [거래처관리](./trading-partners.md) | `/finance/partners` | 거래처(업체/프리랜서) 등록 관리 | React 18 |
| [고객사관리](./customers.md) | `/finance/customers` | 고객사 정보 및 등급 관리 | React 18 |
| [미수금관리](./receivables.md) | `/finance/receivables` | 채권 현황 및 수금 처리 | React 18 |
| [미지급금관리](./payables.md) | `/finance/payables` | 채무 현황 및 지급 처리 | React 18 |
| [환불/해지관리](./refunds.md) | `/finance/refunds` | 환불/해지 요청 및 승인 처리 | React 18 |

## 아키텍처

```
┌───────────────────────────────────────────────────────────────┐
│                  고객/거래처/채권관리 모듈                       │
├───────────┬───────────┬───────────┬───────────┬───────────────┤
│ 거래처관리 │ 고객사관리 │ 미수금관리 │ 미지급금관리│ 환불/해지관리 │
│(업체/프리) │(등급관리) │(채권추적) │(채무추적)  │(요청/승인)   │
│ OCR인식   │ VIP~Brz  │ 수금처리  │ 지급처리   │ 워크플로우    │
└─────┬─────┴─────┬─────┴─────┬─────┴─────┬─────┴───────┬──────┘
      │           │           │           │             │
      ▼           ▼           ▼           ▼             ▼
┌───────────────────────────────────────────────────────────────┐
│                     데이터베이스                                │
│  trading_partners, customers,                                 │
│  receivables, payables, refunds                               │
└───────────────────────────────────────────────────────────────┘
```

## 주요 기술 스택

| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| React 18 + Babel | 클라이언트 렌더링 UI (전 페이지) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| OCR (Claude Vision) | 명함 인식 (거래처관리) |
| MySQL 8.0 | 데이터 저장 |

## 공통 패턴

### 멀티 테넌트

모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.

### 부분 수금/지급

미수금과 미지급금은 부분 처리를 지원합니다:
```
수금/지급액 입력 → collected/paid_amount 누적
→ 전액 수금/지급: collected/paid 상태로 변경
→ 부분 수금/지급: partial 상태로 변경
```

### 상태 관리 비교

| 기능 | 상태값 |
|------|--------|
| 거래처 | active / inactive |
| 고객사 | active / inactive |
| 미수금 | outstanding → partial → collected / overdue |
| 미지급금 | unpaid → partial → paid / overdue |
| 환불/해지 | pending → approved → completed / rejected |

## 데이터베이스 테이블 요약

| 테이블 | 역할 |
|--------|------|
| `trading_partners` | 거래처 정보 (업체/프리랜서, 사업자번호, 계좌 등) |
| `customers` | 고객사 정보 (등급, 업종, 담당자 등) |
| `receivables` | 미수금 (고객별 인보이스, 수금액, 연체 추적) |
| `payables` | 미지급금 (업체별 인보이스, 지급액, 세금계산서) |
| `refunds` | 환불/해지 요청 (타입, 사유, 처리상태) |