ec74d63120
이동된 파일: - 2025-12-02_file-attachment-feature.md - ai-config-설정.md - archive-restore-feature-analysis.md - barobill-members-migration.md - super-admin-protection.md - 명함추출로직.md - 모달창_생성시_유의사항.md - 상품관리정보.md - 수당지급.md - 영업파트너구조.md - 홈택스 매입매출 조회성공.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
329 lines
9.9 KiB
Markdown
329 lines
9.9 KiB
Markdown
# 영업파트너 구조 설계서
|
||
|
||
> 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 |
|
||
|
||
---
|
||
|
||
> **참고:** 이 문서는 영업 관련 기능 개발 시 기준 문서로 사용됩니다.
|
||
> 구조 변경 시 반드시 이 문서를 먼저 업데이트하세요.
|