diff --git a/claudedocs/영업파트너구조.md b/claudedocs/영업파트너구조.md new file mode 100644 index 00000000..7f65710f --- /dev/null +++ b/claudedocs/영업파트너구조.md @@ -0,0 +1,281 @@ +# 영업파트너 구조 설계서 + +> SAM 프로젝트 영업관리 시스템의 핵심 구조 문서 +> +> 최종 수정: 2026-01-27 + +--- + +## 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. 수당/수익 구조 + +### 4.1 수당 유형 + +| 수당 유형 | 기준 | 지급 대상 | +|-----------|------|-----------| +| **영업 수당** | 본인이 체결한 계약 | 계약 체결자 (sales 역할) | +| **관리 수당** | 하위 파트너 실적 | manager 역할 보유자 | +| **유치 수당** | 신규 파트너 유치 | recruiter 역할 보유자 | + +### 4.2 수당 계산 원칙 + +``` +1. 영업 수당: 본인 계약 × 영업 수당률 +2. 관리 수당: 하위 N단계 실적 × 단계별 관리 수당률 +3. 유치 수당: 유치한 파트너 가입비 × 유치 수당률 +``` + +### 4.3 계층별 수당 흐름 예시 + +``` +고객 계약 100만원 발생 (계약자: 박지민) + +박지민 (레벨3, sales) + → 영업 수당 20% = 20만원 + +이영희 (레벨2, 박지민의 상위) + → 관리 수당 5% = 5만원 (sales 역할이지만 상위로서) + +김철수 (레벨1, 이영희의 상위) + → 관리 수당 2% = 2만원 (레벨 차이에 따른 감소) +``` + +> **주의:** 실제 수당률은 정책에 따라 변경될 수 있음 + +--- + +## 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) + +### 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 # 사용자 모델 (영업파트너) +app/Models/Sales/SalesManagerDocument.php # 첨부 서류 모델 +app/Services/Sales/SalesManagerService.php # 영업파트너 서비스 +app/Http/Controllers/Sales/SalesManagerController.php +resources/views/sales/managers/ # 뷰 파일들 +``` + +### 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 +``` + +--- + +## 10. 변경 이력 + +| 날짜 | 변경 내용 | 작성자 | +|------|----------|--------| +| 2026-01-27 | 최초 작성 | Claude | + +--- + +> **참고:** 이 문서는 영업 관련 기능 개발 시 기준 문서로 사용됩니다. +> 구조 변경 시 반드시 이 문서를 먼저 업데이트하세요.