8faf5afa8b
- 영업수수료정산: 입금등록, 수당자동계산, 승인프로세스, 지급추적 - 컨설팅비용정산: 상담시간×시급 정산, 상태관리 - 고객사정산: 월별 매출/수수료/비용 순정산액 관리 - 구독료정산: 플랜별 과금, MRR/ARR 집계, 구독 라이프사이클 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
166 lines
4.6 KiB
Markdown
166 lines
4.6 KiB
Markdown
# 고객사정산
|
|
|
|
## 개요
|
|
|
|
고객사정산은 고객사별 월간 매출, 수수료, 비용을 집계하여 순정산액을 관리하는 기능입니다.
|
|
기간별 정산 현황 추적, 정산 완료 처리, 통계 기능을 제공합니다.
|
|
|
|
- **라우트**: `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
|
|
```
|
|
|
|
## 라우트
|
|
|
|
```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() 응답 구조
|
|
|
|
```json
|
|
{
|
|
"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 스크립트 포함
|