# 수당 지급 시스템 > 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 | --- > **참고:** 이 문서는 수당 관련 기능 개발 시 기준 문서로 사용됩니다. > 수당 정책 변경 시 반드시 이 문서를 먼저 업데이트하세요.