sam-docs/dev/guides/수당지급.md

# 수당 지급 시스템

> SAM 프로젝트 영업파트너 수당 지급 시스템 기술 문서
>
> 최종 수정: 2026-01-30

---

## 1. 개요

### 1.1 목적
이 문서는 SAM 영업관리 시스템의 **수당 계산 및 지급 프로세스**를 정의합니다.

### 1.2 수당 유형

| 수당 유형 | 수당률/금액 | 대상 | 기준 |
|-----------|-------------|------|------|
| **판매자 수당** | 20% | 가망고객 등록자 | 가입비의 50% 기준 |
| **매니저 수당** | 5% | 지정된 매니저 | 가입비의 50% 기준 |
| **협업지원금** | 메뉴당 2,000원 | 2단계 상위 파트너 | 가입비 완납 시 |

---

## 2. 수당 계산 로직

### 2.1 기본 공식

```
기준 금액 = 총 가입비 ÷ 2 (50%)

판매자 수당 = 기준 금액 × 20%
매니저 수당 = 기준 금액 × 5%
```

### 2.2 계산 예시

```
총 가입비: 10,000,000원
기준 금액: 5,000,000원 (50%)

판매자 수당: 5,000,000 × 20% = 1,000,000원
매니저 수당: 5,000,000 × 5% = 250,000원
```

### 2.3 입금 구분별 수당

| 입금 구분 | 코드 | 설명 |
|-----------|------|------|
| **계약금** | `deposit` | 계약 시 선입금 |
| **잔금** | `balance` | 계약 후 잔여금 |

각 입금 시점마다 별도의 수당이 생성됩니다.

---

## 3. 협업지원금

### 3.1 도입 배경

**다단계 판매법 준수**: 다단계 판매법에서는 2단계 이상의 수당 지급이 금지되어 있습니다.
이를 준수하면서도 상위 파트너의 기여를 인정하기 위해 "수당"이 아닌 "지원금" 형태로 지급합니다.

### 3.2 지급 대상

계약 체결자(판매자) 기준 **2단계 상위 파트너** (할아버지 파트너)

```
할아버지 파트너 ← 협업지원금 수령
    │
    ↓ (유치)
아버지 파트너
    │
    ↓ (유치)
손자 파트너 ← 테넌트 계약 체결 (판매자 수당 20%)
    │
    ↓
테넌트 계약
```

### 3.3 산출 기준

| 항목 | 내용 |
|------|------|
| **산출 공식** | 테넌트 메뉴 개수 × 2,000원 |
| **지급 시점** | 가입비 완납 시 |
| **지급 대상** | 계약자의 parent의 parent (2단계 상위) |

### 3.4 계산 예시

```
[상황]
- 손자 파트너가 테넌트 A와 계약 체결
- 테넌트 A에 메뉴 50개 생성
- 가입비 1,000만원 완납

[수당/지원금 지급]
손자 파트너 (판매자):  500만원 × 20% = 100만원
매니저 (지정된 경우):  500만원 × 5%  = 25만원
할아버지 파트너:       50개 × 2,000원 = 10만원 (협업지원금)
```

### 3.5 지급 조건

1. 계약자(손자)의 parent_id가 존재해야 함 (아버지 파트너)
2. 아버지 파트너의 parent_id가 존재해야 함 (할아버지 파트너)
3. 가입비가 **완납**되어야 함
4. 테넌트에 메뉴가 생성되어 있어야 함

> **주의**: 1단계 상위(아버지)는 협업지원금 대상이 아님.
> 직접 유치한 파트너의 계약에 대해서는 별도 수당 정책 없음 (다단계법 준수).

---

## 4. 수당 지급 프로세스

### 3.1 상태 흐름

```
┌─────────┐     ┌──────────┐     ┌─────────┐     ┌───────────┐
│  입금   │ ──▶ │  대기    │ ──▶ │  승인   │ ──▶ │ 지급완료  │
│ 등록    │     │ pending  │     │ approved│     │   paid    │
└─────────┘     └──────────┘     └─────────┘     └───────────┘
                      │
                      ▼
                ┌──────────┐
                │   취소   │
                │cancelled │
                └──────────┘
```

### 3.2 상태별 설명

| 상태 | 코드 | 설명 |
|------|------|------|
| **대기** | `pending` | 입금 등록 후 승인 대기 중 |
| **승인** | `approved` | 본사 승인 완료, 지급 예정 |
| **지급완료** | `paid` | 실제 지급 완료 |
| **취소** | `cancelled` | 취소됨 (대기/승인 상태에서만 가능) |

### 3.3 지급예정일 계산

```php
// 입금일 익월 10일
$scheduledPaymentDate = $paymentDate->addMonth()->day(10);
```

**예시:**
- 1월 15일 입금 → 2월 10일 지급예정
- 1월 31일 입금 → 2월 10일 지급예정

---

## 4. 데이터베이스 구조

### 4.1 sales_commissions 테이블

```sql
CREATE TABLE sales_commissions (
    id                      BIGINT UNSIGNED PRIMARY KEY,
    tenant_id               BIGINT UNSIGNED NOT NULL,
    management_id           BIGINT UNSIGNED NOT NULL,

    -- 입금 정보
    payment_type            ENUM('deposit', 'balance') NOT NULL,
    payment_amount          DECIMAL(15,2) NOT NULL,
    payment_date            DATE NOT NULL,

    -- 수당 계산
    base_amount             DECIMAL(15,2) NOT NULL,      -- 기준 금액 (가입비의 50%)
    partner_rate            DECIMAL(5,2) DEFAULT 20.00,  -- 판매자 수당률
    manager_rate            DECIMAL(5,2) DEFAULT 5.00,   -- 매니저 수당률
    partner_commission      DECIMAL(15,2) NOT NULL,      -- 판매자 수당액
    manager_commission      DECIMAL(15,2) NOT NULL,      -- 매니저 수당액

    -- 지급 정보
    scheduled_payment_date  DATE NOT NULL,               -- 지급예정일 (익월 10일)
    actual_payment_date     DATE NULL,                   -- 실제 지급일
    status                  ENUM('pending', 'approved', 'paid', 'cancelled'),

    -- 담당자
    partner_id              BIGINT UNSIGNED NOT NULL,    -- 영업파트너 ID
    manager_user_id         BIGINT UNSIGNED NULL,        -- 매니저 사용자 ID

    -- 승인 정보
    approved_by             BIGINT UNSIGNED NULL,
    approved_at             TIMESTAMP NULL,

    -- 기타
    bank_reference          VARCHAR(100) NULL,           -- 이체 참조번호
    notes                   TEXT NULL,

    created_at              TIMESTAMP,
    updated_at              TIMESTAMP,
    deleted_at              TIMESTAMP NULL
);
```

### 4.2 sales_commission_details 테이블 (상품별 상세)

```sql
CREATE TABLE sales_commission_details (
    id                      BIGINT UNSIGNED PRIMARY KEY,
    commission_id           BIGINT UNSIGNED NOT NULL,
    contract_product_id     BIGINT UNSIGNED NOT NULL,

    registration_fee        DECIMAL(15,2) NOT NULL,      -- 상품 가입비
    base_amount             DECIMAL(15,2) NOT NULL,      -- 기준 금액
    partner_rate            DECIMAL(5,2) NOT NULL,       -- 상품별 판매자 수당률
    manager_rate            DECIMAL(5,2) NOT NULL,       -- 상품별 매니저 수당률
    partner_commission      DECIMAL(15,2) NOT NULL,      -- 판매자 수당액
    manager_commission      DECIMAL(15,2) NOT NULL,      -- 매니저 수당액

    created_at              TIMESTAMP,
    updated_at              TIMESTAMP
);
```

---

## 5. 서비스 클래스

### 5.1 SalesCommissionService

경로: `app/Services/SalesCommissionService.php`

#### 주요 메서드

| 메서드 | 설명 |
|--------|------|
| `createCommission()` | 입금 등록 시 수당 생성 |
| `approve()` | 수당 승인 처리 |
| `markAsPaid()` | 지급완료 처리 |
| `bulkApprove()` | 일괄 승인 |
| `bulkMarkAsPaid()` | 일괄 지급완료 |
| `cancel()` | 취소 처리 |
| `getPartnerCommissionSummary()` | 영업파트너 수당 요약 |
| `getManagerCommissionSummary()` | 매니저 수당 요약 |

#### 수당 생성 예시

```php
$commission = $this->commissionService->createCommission(
    managementId: $management->id,
    paymentType: 'deposit',      // 계약금
    paymentAmount: 5000000,      // 500만원
    paymentDate: '2026-01-30'
);
```

### 5.2 수당 요약 조회

```php
// 영업파트너 요약
$summary = $this->commissionService->getPartnerCommissionSummary($partnerId);
// [
//     'scheduled_this_month' => 1000000,  // 이번 달 지급예정
//     'total_received' => 5000000,        // 누적 수령
//     'pending_amount' => 500000,         // 대기중
//     'contracts_this_month' => 3,        // 이번 달 계약 건수
// ]

// 매니저 요약
$summary = $this->commissionService->getManagerCommissionSummary($managerUserId);
```

---

## 6. 대시보드 통계

### 6.1 영업파트너 대시보드

경로: `/sales/salesmanagement/dashboard`

#### 표시 항목

| 항목 | 설명 |
|------|------|
| 총 가입비 | 나와 관련된 계약의 총 입금액 |
| 총 수당 | 판매자 수당 + 매니저 수당 합계 |
| 지급 완료 비율 | (지급완료 수당 / 총 수당) × 100 |
| 전체 건수 | 관련 계약 건수 |
| 승인 대기 | pending 상태 건수 |
| 지급 대기 | approved 상태 건수 |

#### 역할별 수당 표시

```
┌─────────────────────────────────────────────┐
│  판매자 수당 (20%)                           │
│  ├─ 총액: 1,000,000원                       │
│  ├─ 지급완료: 500,000원                     │
│  ├─ 승인완료: 300,000원                     │
│  └─ 대기중: 200,000원                       │
├─────────────────────────────────────────────┤
│  매니저 수당 (5%)                            │
│  ├─ 총액: 250,000원                         │
│  ├─ 지급완료: 100,000원                     │
│  ├─ 승인완료: 100,000원                     │
│  └─ 대기중: 50,000원                        │
└─────────────────────────────────────────────┘
```

### 6.2 내 계약 현황 조회 범위

대시보드에 표시되는 계약:
1. **내가 등록한 가망고객** → 전환된 테넌트 (판매자 수당 20%)
2. **내 하위 파트너가 등록한 가망고객** → 전환된 테넌트
3. **내가 매니저로 지정된 계약** (매니저 수당 5%)

```php
// 1) 내가 등록한 가망고객에서 전환된 tenant_id
$registeredTenantIds = TenantProspect::whereIn('registered_by', $partnerIds)
    ->where('status', 'converted')
    ->pluck('tenant_id');

// 2) 내가 매니저로 지정된 tenant_id
$managedTenantIds = SalesTenantManagement::where('manager_user_id', $currentUserId)
    ->pluck('tenant_id');
```

---

## 7. API 엔드포인트

### 7.1 수당 정산 관리

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/sales/commissions` | 정산 목록 조회 |
| GET | `/sales/commissions/{id}` | 정산 상세 조회 |
| POST | `/sales/commissions` | 입금 등록 (수당 생성) |
| POST | `/sales/commissions/{id}/approve` | 승인 처리 |
| POST | `/sales/commissions/{id}/paid` | 지급완료 처리 |
| POST | `/sales/commissions/{id}/cancel` | 취소 처리 |
| POST | `/sales/commissions/bulk-approve` | 일괄 승인 |
| POST | `/sales/commissions/bulk-paid` | 일괄 지급완료 |

---

## 8. 관련 파일

### 모델
```
app/Models/Sales/SalesCommission.php         # 수당 정산 모델
app/Models/Sales/SalesCommissionDetail.php   # 수당 상세 내역
app/Models/Sales/SalesPartner.php            # 영업파트너 (누적 수당 저장)
app/Models/Sales/SalesTenantManagement.php   # 테넌트별 영업 관리
```

### 서비스
```
app/Services/SalesCommissionService.php      # 수당 정산 서비스
```

### 컨트롤러
```
app/Http/Controllers/Sales/SalesCommissionController.php   # 수당 정산 관리
app/Http/Controllers/Sales/SalesDashboardController.php    # 대시보드
```

---

## 9. 변경 이력

| 날짜 | 변경 내용 | 작성자 |
|------|----------|--------|
| 2026-01-30 | 최초 작성 | Claude |

---

> **참고:** 이 문서는 수당 관련 기능 개발 시 기준 문서로 사용됩니다.
> 수당 정책 변경 시 반드시 이 문서를 먼저 업데이트하세요.