# 정산관리 기능

## 개요

SAM 프로젝트의 정산관리 모듈은 영업수수료, 컨설팅비용, 고객사별 정산, 구독료 등
다양한 정산 업무를 종합적으로 관리하는 시스템입니다.
입금 등록, 수당 자동 계산, 승인 프로세스, 지급 추적, 통계 기능을 제공합니다.

## 메뉴 구성

| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [영업수수료정산](./sales-commissions.md) | `/finance/sales-commissions` | 영업파트너/매니저 수당 정산 | Blade + HTMX |
| [컨설팅비용정산](./consulting-fees.md) | `/finance/consulting-fee` | 컨설턴트별 상담수수료 관리 | React 18 |
| [고객사정산](./customer-settlements.md) | `/finance/customer-settlement` | 고객사별 매출/비용 정산 | React 18 |
| [구독료정산](./subscriptions.md) | `/finance/subscription` | 구독 플랜별 과금 관리 | React 18 |

## 아키텍처

```
┌───────────────────────────────────────────────────────────────┐
│                       정산관리 모듈                             │
├───────────────┬───────────────┬───────────────┬───────────────┤
│ 영업수수료정산  │ 컨설팅비용정산 │  고객사정산    │  구독료정산    │
│ (Blade+HTMX)  │ (React 18)   │ (React 18)   │ (React 18)   │
│               │              │              │               │
│ 입금등록      │ 상담기록     │ 월별정산     │ 플랜관리      │
│ 수당자동계산  │ 시급계산     │ 매출/비용    │ MRR/ARR      │
│ 승인프로세스  │ 상태관리     │ 순정산액     │ 과금주기      │
│ 지급추적     │              │              │ 사용자수      │
└───────┬───────┴───────┬───────┴───────┬───────┴───────┬───────┘
        │               │               │               │
        ▼               ▼               ▼               ▼
┌───────────────────────────────────────────────────────────────┐
│                     데이터베이스                                │
│  sales_commissions, sales_commission_details,                 │
│  consulting_fees, customer_settlements, subscriptions         │
└───────────────────────────────────────────────────────────────┘
```

## 주요 기술 스택

| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| Blade + HTMX | 영업수수료정산 UI (부분 업데이트, 모달) |
| React 18 + Babel | 컨설팅/고객사/구독료 UI (브라우저 트랜스파일링) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| MySQL 8.0 | 데이터 저장 |

## 데이터 흐름

```
영업수수료정산:
  sales_tenant_managements (계약) → 입금 등록
      ↓
  sales_commissions (수당 자동 계산)
      ├── sales_commission_details (상품별 상세)
      └── 승인 → 지급완료 프로세스

컨설팅비용정산:
  consulting_fees (상담시간 × 시급 = 정산액)

고객사정산:
  customer_settlements (매출 - 수수료 - 비용 = 순정산액)

구독료정산:
  subscriptions (플랜별 월정액 × 과금주기)
```

## 공통 패턴

### 멀티 테넌트

모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.
컨트롤러에서 `session('selected_tenant_id', 1)`로 현재 테넌트를 결정합니다.

### 상태 관리

| 기능 | 상태값 |
|------|--------|
| 영업수수료 | pending → approved → paid / cancelled |
| 컨설팅비용 | pending / paid |
| 고객사정산 | pending / settled |
| 구독료 | active / trial / cancelled / expired / suspended |

### CSV 내보내기

모든 기능에서 CSV 내보내기를 지원합니다:
- 영업수수료: 서버 사이드 (UTF-8 BOM 인코딩)
- 컨설팅/고객사/구독: 클라이언트 사이드 (React)

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

| 테이블 | 역할 |
|--------|------|
| `sales_commissions` | 영업수수료 정산 (입금, 수당, 승인, 지급) |
| `sales_commission_details` | 상품별 수당 상세 내역 |
| `consulting_fees` | 컨설팅 상담수수료 기록 |
| `customer_settlements` | 고객사별 월간 정산 |
| `subscriptions` | 구독 플랜 및 과금 관리 |
| `customers` | 고객사 마스터 (참조) |