From fcbeccb4db2c4130aa61493959af79fec84e18f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sat, 14 Feb 2026 19:49:39 +0900 Subject: [PATCH] =?UTF-8?q?docs:=EB=8B=A8=EC=B2=B4(=EA=B7=B8=EB=A3=B9)=20?= =?UTF-8?q?=EC=88=98=EB=8B=B9=20=EC=B2=B4=EA=B3=84=20=ED=86=B5=ED=95=A9=20?= =?UTF-8?q?=EB=B3=80=EA=B2=BD=20=EB=B3=B4=EA=B3=A0=EC=84=9C=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- docs/GROUP_COMMISSION_CHANGELOG.md | 328 +++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 docs/GROUP_COMMISSION_CHANGELOG.md diff --git a/docs/GROUP_COMMISSION_CHANGELOG.md b/docs/GROUP_COMMISSION_CHANGELOG.md new file mode 100644 index 00000000..94c21018 --- /dev/null +++ b/docs/GROUP_COMMISSION_CHANGELOG.md @@ -0,0 +1,328 @@ +# 단체(그룹) 수당 체계 통합 - 변경 보고서 + +> 작성일: 2026-02-14 +> 적용 버전: develop 브랜치 + +--- + +## 1. 변경 배경 + +기존 영업파트너 수당 체계(개인 20%, 매니저 5%)에 **"단체(그룹)"** 가입 프로세스를 추가합니다. + +### 변경 전 수당 체계 + +| 역할 | 수당률 | 기준 | +|------|--------|------| +| 영업파트너 | 20% | 기준금액(개발비의 50%) | +| 매니저 | 5% | 기준금액(개발비의 50%) | + +### 변경 후 수당 체계 + +| 가입 유형 | 단체 수당 | 유치 영업파트너 수당 | 매니저 수당 | +|-----------|----------|-------------------|------------| +| **개인 가입** (기존 그대로) | - | 20% | 5% | +| **단체 가입** (신규) | 30% | 3% | 0% | + +- 기준금액 산정 방식은 기존과 동일 (개발비의 50%) +- 2단계 분할 지급(1차/2차) 방식도 기존과 동일 +- 기존 개인 파트너의 수당 계산에는 영향 없음 + +--- + +## 2. 수정 파일 상세 + +### 2-1. DB 마이그레이션 (API 프로젝트) + +**파일**: `api/database/migrations/2026_02_15_100000_add_group_commission_support.php` (신규 생성) + +#### sales_partners 테이블 추가 컬럼 + +| 컬럼명 | 타입 | 설명 | +|--------|------|------| +| `referrer_partner_id` | BIGINT UNSIGNED NULL | 이 단체를 유치한 영업파트너 ID (FK → sales_partners.id) | + +#### sales_commissions 테이블 추가 컬럼 + +| 컬럼명 | 타입 | 기본값 | 설명 | +|--------|------|--------|------| +| `referrer_partner_id` | BIGINT UNSIGNED NULL | NULL | 유치수당 받을 파트너 ID (FK → sales_partners.id) | +| `referrer_rate` | DECIMAL(5,2) | 0 | 유치 수당률 (%) | +| `referrer_commission` | DECIMAL(14,2) | 0 | 유치 수당액 | +| `first_referrer_paid_at` | DATE NULL | NULL | 1차 유치수당 지급일 | +| `second_referrer_paid_at` | DATE NULL | NULL | 2차 유치수당 지급일 | + +- 롤백(`down`) 메서드도 포함되어 있어 `php artisan migrate:rollback`으로 원복 가능 + +--- + +### 2-2. SalesPartner 모델 (MNG) + +**파일**: `mng/app/Models/Sales/SalesPartner.php` + +#### 변경 사항 + +| 항목 | 변경 내용 | +|------|----------| +| `$fillable` | `referrer_partner_id` 추가 | +| `referrer()` 관계 | BelongsTo(SalesPartner) - 이 단체를 유치한 영업파트너 | +| `referredGroups()` 관계 | HasMany(SalesPartner) - 이 영업파트너가 유치한 단체 목록 | +| `isGroup()` 헬퍼 | `referrer_partner_id !== null`이면 단체로 판단 | + +#### 사용 예시 + +```php +$partner = SalesPartner::find(1); + +// 단체 여부 확인 +$partner->isGroup(); // true or false + +// 유치한 영업파트너 조회 +$partner->referrer; // SalesPartner 인스턴스 + +// 이 파트너가 유치한 단체 목록 +$partner->referredGroups; // Collection +``` + +--- + +### 2-3. SalesCommission 모델 (MNG) + +**파일**: `mng/app/Models/Sales/SalesCommission.php` + +#### 변경 사항 + +| 항목 | 변경 내용 | +|------|----------| +| `$fillable` | `referrer_partner_id`, `referrer_rate`, `referrer_commission`, `first_referrer_paid_at`, `second_referrer_paid_at` 추가 | +| `$casts` | `referrer_rate` → decimal:2, `referrer_commission` → decimal:2, 날짜 필드들 → date | +| `referrerPartner()` 관계 | BelongsTo(SalesPartner) - 유치수당 받을 영업파트너 | +| `getTotalCommissionAttribute()` | 기존 `partner + manager`에서 **`+ referrer_commission`** 추가 | +| `recordFirstReferrerPaid()` | 1차 유치수당 지급 기록 메서드 (신규) | +| `recordSecondReferrerPaid()` | 2차 유치수당 지급 기록 메서드 (신규) | +| `isFirstReferrerPaid()` | 1차 유치수당 지급 완료 여부 (신규) | +| `isSecondReferrerPaid()` | 2차 유치수당 지급 완료 여부 (신규) | +| `isFullyPaid()` | 유치수당이 있는 경우(`referrer_partner_id` 존재 시) 유치수당 지급 여부도 포함하여 판단 | + +#### isFullyPaid() 동작 변경 + +``` +# 변경 전 +파트너 1차 지급 + 파트너 2차 지급 + 매니저 지급 = 완료 + +# 변경 후 +파트너 1차 지급 + 파트너 2차 지급 + 매니저 지급 ++ (유치수당이 있으면) 유치 1차 지급 + 유치 2차 지급 = 완료 +``` + +--- + +### 2-4. SalesCommissionService (MNG) + +**파일**: `mng/app/Services/SalesCommissionService.php` + +#### 변경 사항 + +| 항목 | 변경 내용 | +|------|----------| +| 상수 추가 | `DEFAULT_GROUP_RATE = 30.00` (단체 수당률) | +| 상수 추가 | `DEFAULT_REFERRER_RATE = 3.00` (유치 수당률) | +| `createCommission()` | 단체/개인 분기 로직 추가 | + +#### createCommission() 수당 계산 로직 변경 + +``` +# 변경 전 (단순 계산) +partnerRate = partner.commission_rate ?? 20% +managerRate = partner.manager_commission_rate ?? 5% + +# 변경 후 (단체/개인 분기) +IF 단체(isGroup): + partnerRate = partner.commission_rate ?? 30% + managerRate = 0% + referrerId = partner.referrer_partner_id + referrerRate = 3% +ELSE 개인: + partnerRate = partner.commission_rate ?? 20% + managerRate = partner.manager_commission_rate ?? 5% + referrerId = null + referrerRate = 0% + +partnerCommission = baseAmount × (partnerRate / 100) +managerCommission = (매니저 있고 managerRate > 0) ? baseAmount × (managerRate / 100) : 0 +referrerCommission = (referrerId 있고 referrerRate > 0) ? baseAmount × (referrerRate / 100) : 0 +``` + +#### 수당 계산 예시 + +기준금액 100만원인 경우: + +| 가입 유형 | 단체/파트너 수당 | 유치 수당 | 매니저 수당 | 합계 | +|-----------|----------------|----------|------------|------| +| 개인 가입 | 200,000원 (20%) | 0원 | 50,000원 (5%) | 250,000원 | +| 단체 가입 | 300,000원 (30%) | 30,000원 (3%) | 0원 | 330,000원 | + +--- + +### 2-5. SalesManagerService (MNG) + +**파일**: `mng/app/Services/Sales/SalesManagerService.php` + +#### 변경 사항 - createSalesPartner() + +| 항목 | 변경 내용 | +|------|----------| +| `partner_type` | `$data['partner_type'] ?? 'individual'`로 변경 (기존: 고정 `'individual'`) | +| `referrer_partner_id` | `$data['referrer_partner_id'] ?? null` 추가 | +| 단체 수당률 자동 설정 | `partner_type === 'corporate'`이면 `commission_rate = 30.00`, `manager_commission_rate = 0` 자동 설정 | + +--- + +### 2-6. SalesManagerController (MNG) + +**파일**: `mng/app/Http/Controllers/Sales/SalesManagerController.php` + +#### 변경 사항 + +| 메서드 | 변경 내용 | +|--------|----------| +| `create()` | `$activePartners` 변수 추가 - 활성 개인 파트너 목록 조회 후 뷰에 전달 | +| `store()` | validation에 `partner_type` (nullable, in:individual,corporate), `referrer_partner_id` (nullable, exists:sales_partners,id) 추가 | + +--- + +### 2-7. create.blade.php (MNG) + +**파일**: `mng/resources/views/sales/managers/create.blade.php` + +#### 변경 사항 + +"사업자 정보" 섹션과 "역할 및 조직" 섹션 사이에 **"파트너 유형"** 섹션 추가: + +- **유형 선택** 라디오 버튼: 개인(individual) / 단체(corporate) +- **유치 영업파트너 선택** 드롭다운: `partner_type = corporate`일 때만 표시 (Alpine.js `x-show` 사용) +- 드롭다운에는 `$activePartners` 목록 표시 (활성 상태의 개인 파트너만) +- 안내 문구: "단체 가입 시: 단체 30%, 유치 파트너 3%, 매니저 0%" + +--- + +### 2-8. SalesDashboardController (MNG) + +**파일**: `mng/app/Http/Controllers/Sales/SalesDashboardController.php` + +#### 변경 사항 - getDashboardData() + +| 항목 | 변경 내용 | +|------|----------| +| 유치수당 조회 추가 | `SalesCommission::where('referrer_partner_id', $partnerId)` - 내가 유치 파트너인 건의 수당 조회 | +| 유치수당 계산 | `$referrerCommissionTotal`, `$referrerCommissionPaid`, `$referrerCommissionPending`, `$referrerCommissionApproved` 계산 | +| `commissionByRole` 배열 | "협업지원금" 항목 → **"유치수당"** 항목으로 교체 (rate: 3, color: purple, 실제 금액 표시) | +| `$totalCommission` | 기존 `파트너 + 매니저` → **`파트너 + 매니저 + 유치수당`** 으로 합산 | +| `$paidCommission` | 기존 `파트너 지급완료 + 매니저 지급완료` → **`+ 유치수당 지급완료`** 합산 | + +#### 대시보드 카드 변경 + +``` +# 변경 전 +[판매자 20% (녹색)] [관리자 1개월구독료 (파란색)] [협업지원금 별도 (보라색)] + +# 변경 후 +[판매자 20% (녹색)] [관리자 1개월구독료 (파란색)] [유치수당 3% (보라색)] +``` + +- "협업지원금" 카드는 금액 없이 "운영팀 산정"으로 표시되었음 +- "유치수당" 카드는 실제 유치수당 합계 금액이 표시됨 + +--- + +### 2-9. commission-by-role.blade.php (MNG) + +**파일**: `mng/resources/views/sales/dashboard/partials/commission-by-role.blade.php` + +#### 변경 사항 + +| 항목 | 변경 내용 | +|------|----------| +| 배경 색상 | `purple` 조건 추가: `bg-purple-50 border-purple-200` | +| 아이콘 색상 | `purple` 조건 추가: `text-purple-600` | +| 텍스트 색상 | `purple` 조건 추가: `text-purple-800` | +| 수당률 색상 | `purple` 조건 추가: `text-purple-600` | +| 금액 색상 | `purple` 조건 추가: `text-purple-700` | + +--- + +## 3. 데이터 흐름 (단체 등록 ~ 수당 계산) + +``` +1. 파트너 등록 폼 (create.blade.php) + └─ 유형: "단체" 선택 + └─ 유치 파트너: 기존 개인 파트너 선택 + └─ 제출 (store) + +2. SalesManagerController::store() + └─ validation (partner_type, referrer_partner_id) + └─ SalesManagerService::createSalesPartner() 호출 + +3. SalesManagerService::createSalesPartner() + └─ User 생성 + └─ SalesPartner 생성: + └─ partner_type = 'corporate' + └─ referrer_partner_id = 선택한 파트너 ID + └─ commission_rate = 30.00 (자동 설정) + └─ manager_commission_rate = 0 (자동 설정) + +4. 계약 후 입금 등록 시 + └─ SalesCommissionService::createCommission() + └─ $partner->isGroup() = true + └─ partnerRate = 30% + └─ managerRate = 0% + └─ referrerRate = 3% + └─ SalesCommission 생성 (유치수당 정보 포함) + +5. 유치 파트너 대시보드 + └─ SalesDashboardController::getDashboardData() + └─ myCommissionsAsReferrer 조회 + └─ "유치수당" 카드에 금액 표시 + └─ 총 수당에 유치수당 합산 +``` + +--- + +## 4. 기존 기능과의 호환성 + +| 항목 | 영향 | +|------|------| +| 기존 개인 파트너 수당 계산 | 영향 없음 (20%/5% 유지) | +| 기존 수당 정산 목록 | 영향 없음 (referrer 필드는 NULL 기본값) | +| 기존 대시보드 | "협업지원금" → "유치수당" 카드 이름/동작 변경 | +| isFullyPaid() | 기존 개인 파트너는 동작 동일. 단체 건만 유치수당 지급까지 확인 | +| 총 수당(getTotalCommissionAttribute) | 유치수당 포함 합산으로 변경 | + +--- + +## 5. 서버 배포 시 필요한 작업 + +### API 프로젝트 +```bash +cd /home/webservice/api +git pull +php artisan migrate +``` + +### MNG 프로젝트 +```bash +cd /home/webservice/mng +git pull +php artisan config:clear +``` + +--- + +## 6. 검증 체크리스트 + +- [ ] 마이그레이션 실행 후 DB 컬럼 확인 (sales_partners.referrer_partner_id, sales_commissions 5개 컬럼) +- [ ] 파트너 등록 폼에서 "단체" 선택 시 유치 파트너 드롭다운 표시 +- [ ] 단체로 파트너 등록 시 `sales_partners.referrer_partner_id`, `commission_rate=30`, `manager_commission_rate=0` 확인 +- [ ] 단체의 계약 입금 등록 시 수당 계산: 단체 30%, 유치 3%, 매니저 0% +- [ ] 유치 파트너 대시보드에서 "유치수당" 카드(보라색) 표시 확인 +- [ ] 기존 개인 파트너 수당 계산 영향 없는지 확인 (20%/5% 유지) +- [ ] 총 수당 합계에 유치수당이 포함되는지 확인