# 영업파트너 구조 설계서

> SAM 프로젝트 영업관리 시스템의 핵심 구조 문서
>
> 최종 수정: 2026-01-30

---

## 1. 개요

### 1.1 목적
이 문서는 SAM 영업관리 시스템의 **영업파트너 조직 구조**를 정의합니다.
모든 영업 관련 기능 개발 시 이 구조를 기준으로 해석하고 구현합니다.

### 1.2 핵심 원칙

| 원칙 | 설명 |
|------|------|
| **직위 단일화** | 모든 영업 담당자는 "영업파트너"라는 동일한 직위 |
| **계층 무한 확장** | 상위-하위 유치 관계는 무한 깊이까지 허용 |
| **역할 분리** | 직위와 역할을 분리하여 유연한 업무 할당 |
| **역할 위임 가능** | 상위 파트너가 하위 파트너에게 역할 위임 가능 |

---

## 2. 핵심 개념 정의

### 2.1 직위 (Position)
- **영업파트너**: 모든 영업 담당자의 공통 직위
- 별도의 직위 구분 없음 (매니저, 팀장 등은 역할로 처리)

### 2.2 계층 (Hierarchy)
- **유치 관계**: 상위 파트너가 하위 파트너를 유치(추천)
- **parent_id**: 나를 유치한 상위 파트너
- **레벨**: 최상위(레벨1)부터 무한 깊이까지

```
레벨1: 최상위 영업파트너 (parent_id = null)
레벨2: 레벨1이 유치한 파트너
레벨3: 레벨2가 유치한 파트너
...
레벨N: 무한 확장 가능
```

### 2.3 역할 (Role)
직위와 별개로 **수행하는 업무**를 정의합니다.

| 역할 코드 | 역할명 | 설명 |
|-----------|--------|------|
| `sales` | 영업 | 가망고객 발굴, 상담, 계약 체결 |
| `manager` | 매니저 | 하위 파트너 관리, 실적 취합, 승인 처리 |
| `recruiter` | 유치담당 | 새로운 영업파트너 유치 활동 |

**특징:**
- 한 파트너가 **복수의 역할** 보유 가능
- 역할은 **위임 가능** (상위 → 하위)
- 역할에 따라 **수당 구조**가 달라질 수 있음

---

## 3. 조직 구조 예시

### 3.1 기본 구조

```
영업파트너 김철수 (레벨1, parent_id: null)
│   역할: sales, manager, recruiter
│
├── 영업파트너 이영희 (레벨2, parent_id: 김철수)
│   │   역할: sales, recruiter
│   │
│   ├── 영업파트너 박지민 (레벨3, parent_id: 이영희)
│   │       역할: sales
│   │
│   └── 영업파트너 최민수 (레벨3, parent_id: 이영희)
│           역할: sales
│
└── 영업파트너 정수연 (레벨2, parent_id: 김철수)
        역할: sales, manager  ← 김철수가 매니저 역할 위임
```

### 3.2 역할 위임 시나리오

**시나리오: 김철수가 매니저 역할을 정수연에게 위임**

| 변경 전 | 변경 후 |
|---------|---------|
| 김철수: sales, **manager**, recruiter | 김철수: sales, recruiter |
| 정수연: sales | 정수연: sales, **manager** |

**결과:**
- 정수연이 김철수 하위 파트너들의 관리 업무 수행
- 수당 구조에 따라 매니저 수당도 정수연에게 지급

---

## 4. 수당/수익 구조

> **상세 내용:** [수당지급.md](./수당지급.md) 참조

### 4.1 수당 유형

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

### 4.2 수당 계산 원칙

```
기준 금액 = 총 개발비의 50%

1. 판매자 수당: 기준 금액 × 20% (가망고객 등록자)
2. 매니저 수당: 기준 금액 × 5% (매니저로 지정된 파트너)
```

### 4.3 수당 흐름 예시

```
고객 계약 (개발비 1,000만원)
  └─ 기준 금액: 500만원 (개발비의 50%)

김철수 (가망고객 등록자, 판매자)
  → 판매자 수당: 500만원 × 20% = 100만원

이영희 (김철수가 지정한 매니저)
  → 매니저 수당: 500만원 × 5% = 25만원
```

### 4.4 수당 지급 프로세스

```
1. 입금 등록 → SalesCommission 생성 (status: pending)
2. 본사 승인 → status: approved
3. 지급 완료 → status: paid + 누적 수당 업데이트
```

> **참고:** 자세한 수당 시스템 구현 내용은 [수당지급.md](./수당지급.md) 참조

---

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

### 5.1 users 테이블 (기존 + 확장)

```sql
-- 기존 컬럼
id, user_id, name, email, phone, password, is_active, ...

-- 영업파트너 확장 컬럼
parent_id           -- 상위 파트너 (유치자) ID
approval_status     -- 승인 상태: pending, approved, rejected
approved_by         -- 승인 처리자 ID
approved_at         -- 승인 일시
rejection_reason    -- 반려 사유
```

### 5.2 user_roles 테이블

```sql
id
user_id             -- 사용자 ID
tenant_id           -- 테넌트 ID
role_id             -- 역할 ID (roles 테이블 참조)
assigned_at         -- 역할 할당 일시
assigned_by         -- 역할 할당자 (위임 시)
```

### 5.3 roles 테이블 (영업 관련)

| id | name | description |
|----|------|-------------|
| - | sales | 영업 - 가망고객 발굴, 계약 체결 |
| - | manager | 매니저 - 하위 파트너 관리, 승인 |
| - | recruiter | 유치담당 - 신규 파트너 유치 |

### 5.4 sales_manager_documents 테이블

```sql
id
tenant_id
user_id             -- 영업파트너 ID
file_path           -- 파일 저장 경로
original_name       -- 원본 파일명
document_type       -- 문서 유형: id_card, business_license, contract, etc.
description         -- 설명
uploaded_by         -- 업로더
```

---

## 6. 기능 구현 현황

### 6.1 완료된 기능

- [x] 영업파트너 등록 (User 통합)
- [x] 상위-하위 계층 구조 (parent_id)
- [x] 역할 기반 시스템 (sales, manager, recruiter)
- [x] 멀티파일 업로드 (첨부 서류)
- [x] 본사 승인 프로세스 (pending → approved/rejected)
- [x] 역할 위임 기능 (상위 → 하위)
- [x] 역할 부여/제거 기능
- [x] 추천인(유치자) 관리
- [x] **수당 자동 계산 (판매자 20%, 매니저 5%)**
- [x] **수당 정산 시스템 (SalesCommission)**
- [x] **수당 승인/지급 프로세스**
- [x] **대시보드 통계 (실적, 수당 현황)**
- [x] **가망고객 등록/관리**
- [x] **테넌트 전환 프로세스**

### 6.2 구현 예정 기능

- [ ] 조직도 시각화 (트리 뷰)
- [ ] 유치 실적 관리
- [ ] 성과 분석 리포트

---

## 7. 개발 로드맵

### Phase 1: 기반 구조 (완료)
- 영업파트너 = User 통합
- parent_id 계층 구조
- 역할 시스템 (roles)
- 승인 프로세스

### Phase 2: 역할 위임 기능
- 역할 위임 UI
- 위임 이력 관리
- 위임 알림

### Phase 3: 수당 시스템
- 수당 정책 설정
- 계층별 수당 자동 계산
- 수당 지급 승인 프로세스
- 수당 내역 조회

### Phase 4: 조직 관리 고도화
- 조직도 시각화 (트리 구조)
- 하위 파트너 실적 대시보드
- 유치 실적 통계
- 성과 분석 리포트

### Phase 5: 파트너 포털
- 영업파트너 전용 앱/웹
- 본인 실적 조회
- 하위 파트너 현황
- 수당 내역 조회

---

## 8. 용어 정리

| 용어 | 정의 |
|------|------|
| **영업파트너** | SAM 영업 조직의 모든 구성원 (직위) |
| **상위 파트너** | 나를 유치한 파트너 (parent) |
| **하위 파트너** | 내가 유치한 파트너 (children) |
| **유치** | 새로운 영업파트너를 조직에 등록시키는 행위 |
| **위임** | 상위 파트너가 하위 파트너에게 역할을 넘기는 행위 |
| **레벨** | 최상위부터의 계층 깊이 (레벨1 = 최상위) |
| **영업 역할** | 가망고객 발굴, 계약 체결 업무 |
| **매니저 역할** | 하위 파트너 관리, 승인 업무 |

---

## 9. 관련 파일 경로

### MNG 프로젝트

#### 모델
```
app/Models/User.php                          # 사용자 모델 (영업파트너, parent_id)
app/Models/Sales/SalesPartner.php            # 영업파트너 정보
app/Models/Sales/SalesManagerDocument.php    # 첨부 서류 모델
app/Models/Sales/SalesCommission.php         # 수당 정산 모델
app/Models/Sales/SalesCommissionDetail.php   # 수당 상세 내역
app/Models/Sales/SalesTenantManagement.php   # 테넌트별 영업 관리
app/Models/Sales/TenantProspect.php          # 가망고객 모델
```

#### 서비스
```
app/Services/SalesCommissionService.php      # 수당 정산 서비스
app/Services/Sales/SalesManagerService.php   # 영업파트너 서비스
```

#### 컨트롤러
```
app/Http/Controllers/Sales/SalesManagerController.php      # 영업파트너 관리
app/Http/Controllers/Sales/SalesDashboardController.php    # 대시보드
app/Http/Controllers/Sales/SalesProspectController.php     # 가망고객 관리
app/Http/Controllers/Sales/SalesCommissionController.php   # 수당 정산
```

#### 뷰
```
resources/views/sales/managers/              # 영업파트너 관리
resources/views/sales/dashboard/             # 대시보드
resources/views/sales/prospects/             # 가망고객 관리
resources/views/sales/commissions/           # 수당 정산
```

### API 프로젝트
```
database/migrations/2026_01_27_200000_add_sales_manager_fields_to_users_table.php
database/migrations/2026_01_27_200100_create_sales_manager_documents_table.php
database/migrations/..._create_sales_commissions_table.php
database/migrations/..._create_tenant_prospects_table.php
```

---

## 10. 변경 이력

| 날짜 | 변경 내용 | 작성자 |
|------|----------|--------|
| 2026-01-27 | 최초 작성 | Claude |
| 2026-01-27 | 역할 위임/부여/제거 기능 구현 완료 | Claude |
| 2026-01-30 | 수당 구조 업데이트 (판매자 20%, 매니저 5%) | Claude |
| 2026-01-30 | 수당 시스템 구현 완료 반영 | Claude |
| 2026-01-30 | 관련 파일 경로 업데이트 | Claude |

---

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