권혁성
db63fcff85
- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동) - 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/) - 기획팀 폴더 requests/ 생성 - plans/ → dev/dev_plans/ 이름 변경 - README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용) - resources.md 신규 (노션 링크용, assets/brochure 이관 예정) - CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동 - 전체 참조 경로 업데이트 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
373 lines
12 KiB
Markdown
373 lines
12 KiB
Markdown
# 수당 지급 시스템
|
||
|
||
> 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 |
|
||
|
||
---
|
||
|
||
> **참고:** 이 문서는 수당 관련 기능 개발 시 기준 문서로 사용됩니다.
|
||
> 수당 정책 변경 시 반드시 이 문서를 먼저 업데이트하세요.
|