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 지급예정일 계산

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

예시:

• 1월 15일 입금 → 2월 10일 지급예정
• 1월 31일 입금 → 2월 10일 지급예정

---

4. 데이터베이스 구조

4.1 sales_commissions 테이블

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 테이블 (상품별 상세)

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()	매니저 수당 요약

수당 생성 예시

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

5.2 수당 요약 조회

// 영업파트너 요약
$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%)

// 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

---

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