sam-docs/features/settlement

정산관리 기능

개요

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

메뉴 구성

메뉴	경로	설명	UI 기술
영업수수료정산	/finance/sales-commissions	영업파트너/매니저 수당 정산	Blade + HTMX
컨설팅비용정산	/finance/consulting-fee	컨설턴트별 상담수수료 관리	React 18
고객사정산	/finance/customer-settlement	고객사별 매출/비용 정산	React 18
구독료정산	/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	고객사 마스터 (참조)