SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bbcb9406dbddeff3c90a4f55c2aef64c4654f5e8
sam-docs/features/settlement/sales-commissions.md
김보곤 8faf5afa8b docs:정산관리 개발문서 추가 (4개 메뉴) 
- 영업수수료정산: 입금등록, 수당자동계산, 승인프로세스, 지급추적
- 컨설팅비용정산: 상담시간×시급 정산, 상태관리
- 고객사정산: 월별 매출/수수료/비용 순정산액 관리
- 구독료정산: 플랜별 과금, MRR/ARR 집계, 구독 라이프사이클

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 16:47:22 +09:00

9.9 KiB
Raw Blame History

영업수수료정산

개요

영업수수료정산은 영업파트너와 매니저의 수당을 계산하고 승인/지급하는 기능입니다. 입금 등록 시 수당 자동 계산, 승인 프로세스(대기→승인→지급), 지급 추적, 일괄 처리를 지원합니다.

  • 라우트: GET /finance/sales-commissions
  • UI 기술: Blade + HTMX (부분 업데이트, 모달)
  • 컨트롤러: SalesCommissionController (13개 메서드)
  • 서비스: SalesCommissionService (핵심 비즈니스 로직)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── SalesCommissionController.php          # 메인 컨트롤러 (13개 메서드)
├── app/Services/
│   └── SalesCommissionService.php             # 비즈니스 로직 서비스
├── app/Models/Sales/
│   ├── SalesCommission.php                    # 수수료 정산 모델
│   └── SalesCommissionDetail.php              # 상품별 상세 모델
└── resources/views/finance/sales-commission/
    ├── index.blade.php                        # 메인 페이지
    ├── stats-cards.blade.php                  # 통계 카드 (HTMX partial)
    ├── commission-table.blade.php             # 테이블 (HTMX partial)
    └── payment-form.blade.php                 # 입금 등록 폼 (HTMX partial)

api/
└── database/migrations/
    ├── 2026_01_29_170000_create_sales_commissions_table.php
    └── 2026_01_29_170100_create_sales_commission_details_table.php

라우트

// routes/web.php (finance prefix 그룹 내)
GET    /sales-commissions                → index()          목록 페이지
POST   /sales-commissions/payment        → registerPayment() 입금 등록
GET    /sales-commissions/{id}           → show()           JSON 상세
GET    /sales-commissions/{id}/detail    → detail()         모달 상세 (HTMX)
POST   /sales-commissions/{id}/approve   → approve()        승인
POST   /sales-commissions/{id}/mark-paid → markPaid()       지급완료
POST   /sales-commissions/{id}/cancel    → cancel()         취소
POST   /sales-commissions/bulk-approve   → bulkApprove()    일괄 승인
POST   /sales-commissions/bulk-mark-paid → bulkMarkPaid()   일괄 지급완료
GET    /sales-commissions/table          → table()          테이블 새로고침 (HTMX)
GET    /sales-commissions/stats          → stats()          통계 새로고침 (HTMX)
GET    /sales-commissions/payment-form   → paymentForm()    입금 폼 (HTMX)
GET    /sales-commissions/export         → export()         CSV 다운로드

컨트롤러

SalesCommissionController

메서드 HTTP 설명
index() GET 정산 목록 (필터, 페이지네이션)
show(id) GET JSON 상세 조회
detail(id) GET 모달 상세 (HTMX partial)
registerPayment() POST 입금 등록 및 수당 자동 생성
approve(id) POST 단일 승인 처리
bulkApprove() POST 일괄 승인 (체크박스 선택)
markPaid(id) POST 단일 지급완료
bulkMarkPaid() POST 일괄 지급완료
cancel(id) POST 취소 처리 (paid 상태 제외)
table() GET 테이블 부분 새로고침 (HTMX)
stats() GET 통계 카드 부분 새로고침 (HTMX)
paymentForm() GET 입금 등록 폼 모달 (HTMX)
export() GET CSV 엑셀 다운로드 (UTF-8 BOM)

서비스 클래스

SalesCommissionService

상수

const DEFAULT_PARTNER_RATE = 20.00;    // 기본 파트너 수당률 (%)
const DEFAULT_MANAGER_RATE = 5.00;     // 기본 매니저 수당률 (%)

주요 메서드

메서드 설명
getCommissions(filters, perPage) 정산 목록 (페이지네이션, 필터)
getCommissionById(id) 정산 상세 (관계 포함)
getPendingPaymentTenants() 입금 대기 테넌트 목록
createCommission(managementId, type, amount, date) 입금 등록 + 수당 생성
approve(id, approverId) 승인 처리
bulkApprove(ids, approverId) 일괄 승인
markAsPaid(id, bankReference?) 지급완료 처리
bulkMarkAsPaid(ids, bankReference?) 일괄 지급완료
cancel(id) 취소 처리
getSettlementStats(year, month) 월별 정산 통계
getPartnerCommissionSummary(partnerId) 파트너 수당 요약
getManagerCommissionSummary(userId) 매니저 수당 요약

핵심 로직

수당 자동 계산 (createCommission)

입금 등록
    ↓
1. 계약 상품 목록 조회 (sales_contract_products)
    ↓
2. 각 상품별 수당 계산:
   기본 가입비 = 등록 금액 × 2 (없을 경우)
   기준액     = 가입비 × 50%
   파트너 수당 = 기준액 × 20%
   매니저 수당 = 기준액 × 5% (매니저 있을 경우만)
    ↓
3. sales_commissions 레코드 생성
   + sales_commission_details (상품별 N건)
    ↓
4. sales_tenant_managements 입금 정보 업데이트
    ↓
5. DB 트랜잭션으로 원자적 처리

승인 프로세스

pending (대기)
    ↓  approve()
approved (승인) ← approved_by, approved_at 기록
    ↓  markAsPaid()
paid (지급완료) ← actual_payment_date, bank_reference 기록

pending/approved → cancel() → cancelled
(paid 상태에서는 취소 불가)

지급 추적 (SalesCommission 모델)

1차 납입완료일          → first_payment_date
1차 파트너 수당 지급일   → first_partner_paid_date
2차 납입완료일          → second_payment_date
2차 파트너 수당 지급일   → second_partner_paid_date
첫 구독료 입금일         → first_subscription_date
매니저 수당 지급일       → manager_paid_date

지급예정일 계산

1차 파트너 수당: 1차 납입완료 익월 10일
2차 파트너 수당: 2차 납입완료 익월 10일
매니저 수당:    첫 구독료 입금 익월 10일

모델

SalesCommission

테이블: sales_commissions

필드 타입 설명
tenant_id bigint 테넌트 ID
management_id bigint 영업 테넌트 관리 FK
payment_type enum deposit(계약금) / balance(잔금)
payment_amount decimal(14,2) 입금액
payment_date date 입금일
base_amount decimal(14,2) 수당 계산 기준액 (가입비 50%)
partner_rate decimal(5,2) 파트너 수당률 (기본 20%)
manager_rate decimal(5,2) 매니저 수당률 (기본 5%)
partner_commission decimal(14,2) 파트너 수당액
manager_commission decimal(14,2) 매니저 수당액
scheduled_payment_date date 지급예정일 (입금 익월 10일)
status enum pending / approved / paid / cancelled
actual_payment_date date 실제 지급일
partner_id bigint 영업파트너 FK
manager_user_id bigint 매니저 사용자 FK
notes text 메모
bank_reference string(100) 이체 참조번호
approved_by bigint 승인자 FK
approved_at timestamp 승인 일시

Relationships

$commission->management    // BelongsTo SalesTenantManagement
$commission->partner       // BelongsTo SalesPartner
$commission->manager       // BelongsTo User
$commission->details       // HasMany SalesCommissionDetail
$commission->approver      // BelongsTo User

주요 Scope

->pending()                                   // 대기 상태
->approved()                                  // 승인 완료
->paid()                                      // 지급 완료
->forPartner($partnerId)                      // 특정 파트너
->forManager($managerUserId)                  // 특정 매니저
->forScheduledMonth($year, $month)            // 지급예정 월
->paymentDateBetween($startDate, $endDate)    // 입금일 기간

주요 Accessor

$commission->status_label          // "대기", "승인", "지급완료", "취소"
$commission->payment_type_label    // "계약금", "잔금"
$commission->total_commission      // 파트너 + 매니저 수당 합계

SalesCommissionDetail

테이블: sales_commission_details

필드 타입 설명
commission_id bigint 정산 FK (cascade delete)
contract_product_id bigint 계약 상품 FK
registration_fee decimal(14,2) 상품 가입비
base_amount decimal(14,2) 수당 계산 기준액
partner_rate / manager_rate decimal(5,2) 수당률
partner_commission / manager_commission decimal(14,2) 수당액

뷰 구성

index.blade.php (메인 페이지)

┌─ 페이지 헤더 ──────────────────────
│  제목: "영업수수료 정산"
│  [입금 등록] [CSV 다운로드] 버튼
│
├─ 필터 영역 ────────────────────────
│  년/월 선택 | 상태 | 입금구분 | 파트너 | 검색
│
├─ 통계 카드 (HTMX partial) ────────
│  대기 금액 | 승인 금액 | 지급 금액 | 월간 합계
│  (파트너/매니저 수당 구분)
│
├─ 정산 테이블 (HTMX partial) ──────
│  ☑ | 관리ID | 입금구분 | 금액 | 입금일 | 파트너 | 수당액 | 상태 | 작업
│  └─ 체크박스: 일괄 승인/지급 선택
│  └─ 인라인 작업: 승인, 지급완료, 취소
│  └─ 페이지네이션
│
├─ 입금 등록 모달 (HTMX partial) ───
│  테넌트 선택 → 계약 상품 표시
│  입금구분(계약금/잔금) | 입금액 | 입금일
│
└─ 상세 모달 (HTMX partial) ────────
   파트너/매니저 정보, 상품별 수당 내역
   지급 추적 일정

HTMX 호환성

  • Blade + HTMX 기반 (부분 업데이트 활용)
  • 테이블, 통계 카드, 모달이 HTMX partial로 동작
  • 전체 페이지는 HX-Redirect 필요 (JavaScript 포함)