sam-docs/dev/guides/영업파트너구조.md

영업파트너 구조 설계서

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 참조

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 참조

---

5. 데이터베이스 구조

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

-- 기존 컬럼
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 테이블

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 테이블

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

---

6. 기능 구현 현황

6.1 완료된 기능

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

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

---

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