sam-docs/features/settlement/customer-settlements.md

고객사정산

개요

고객사정산은 고객사별 월간 매출, 수수료, 비용을 집계하여 순정산액을 관리하는 기능입니다. 기간별 정산 현황 추적, 정산 완료 처리, 통계 기능을 제공합니다.

• 라우트: GET /finance/customer-settlement
• UI 기술: React 18 + Babel (브라우저 트랜스파일링)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── CustomerSettlementController.php   # 메인 컨트롤러 (4개 메서드)
├── app/Models/Finance/
│   └── CustomerSettlement.php             # 고객사정산 모델
└── resources/views/finance/
    └── customer-settlement.blade.php      # React 기반 단일 페이지

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

라우트

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

// API 라우트 (customer-settlements prefix)
GET    /customer-settlements/list        → index()     목록 + 통계 (JSON)
POST   /customer-settlements/store       → store()     등록
PUT    /customer-settlements/{id}        → update()    수정
DELETE /customer-settlements/{id}        → destroy()   삭제

컨트롤러

CustomerSettlementController

메서드	HTTP	설명
index()	GET	목록 + 통계 (검색, 기간, 상태 필터)
store()	POST	정산 등록
update()	PUT	정산 수정
destroy()	DELETE	삭제 (Soft Delete)

index() 응답 구조

{
  "success": true,
  "data": [
    {
      "id": 1,
      "period": "2026-02",
      "customer": "A사",
      "totalSales": 10000000,
      "commission": 500000,
      "expense": 200000,
      "netAmount": 9300000,
      "status": "pending",
      "settledDate": null,
      "memo": ""
    }
  ],
  "stats": {
    "totalSales": 50000000,
    "totalCommission": 2500000,
    "totalNet": 45000000,
    "settledAmount": 30000000
  }
}

핵심 로직

순정산액 계산

순정산액(net_amount) = 총 매출(total_sales) - 수수료(commission) - 비용(expense)

상태 관리

pending (대기) → settled (정산완료)
→ 정산완료 시 settled_date 기록

모델

CustomerSettlement

테이블: customer_settlements

필드	타입	설명
tenant_id	bigint	테넌트 ID
period	string(7)	정산월 (YYYY-MM)
customer	string(100)	고객사명
total_sales	bigint	총 매출액
commission	bigint	수수료
expense	bigint	비용
net_amount	bigint	순정산액
status	string(20)	pending / settled
settled_date	date	정산완료일
memo	text	메모

• SoftDeletes 적용
• Casts: total_sales, commission, expense, net_amount → integer, settled_date → date
• Scope: forTenant($tenantId)

뷰 구성 (React)

customer-settlement.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "고객사정산"
│  [CSV 내보내기] [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│  총 매출 | 정산금액 | 정산완료 | 총 수수료
│
├─ 필터 영역 ────────────────────────
│  검색 (고객사명) | 기간 (YYYY-MM) | 상태 (전체/대기/정산완료)
│
├─ 정산 목록 테이블 ─────────────────
│  기간 | 고객사 | 매출 | 수수료 | 비용 | 정산액 | 상태 | 작업
│  └─ 정산액: 매출-수수료-비용 자동 계산
│  └─ 상태: 대기(노랑), 정산완료(초록) 배지
│  └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│  정산월(YYYY-MM), 고객사명
│  총 매출액, 수수료, 비용
│  → 순정산액 (자동 계산 표시)
│  상태, 정산완료일, 메모
│  [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지

데이터 흐름

React 컴포넌트
    ↓ fetch GET /finance/customer-settlements/list
CustomerSettlementController::index()
    ↓
CustomerSettlement::forTenant()
    ↓ (search, status, period 필터)
통계 계산 (totalSales, totalCommission, totalNet, settledAmount)
    ↓
JSON 응답 → React 렌더링

HTMX 호환성

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