sam-docs/features/sales/partners.md

# 파트너관리

## 개요

파트너관리는 영업파트너(판매자/매니저)의 등록, 수정, 역할 관리, 서류 관리를 수행하는 기능입니다.
파트너 등록 신청, 서류 업로드, 역할 부여/위임, 계층 구조(추천인) 관리를 지원합니다.

- **라우트**: `GET /sales/managers`
- **미들웨어**: `auth`, `hq.member`
- **UI 기술**: Blade + HTMX + Alpine.js + Tailwind CSS

## 파일 구조

```
mng/
├── app/Http/Controllers/Sales/
│   └── SalesManagerController.php        # 메인 컨트롤러 (425줄)
├── app/Services/Sales/
│   └── SalesManagerService.php           # 비즈니스 로직 서비스
├── app/Models/Sales/
│   ├── SalesPartner.php                  # 영업파트너 모델
│   └── SalesManagerDocument.php          # 파트너 서류 모델
└── resources/views/sales/managers/
    ├── index.blade.php                   # 파트너 목록
    ├── create.blade.php                  # 등록 폼
    ├── show.blade.php                    # 상세 페이지
    ├── edit.blade.php                    # 수정 폼
    └── partials/
        ├── show-modal.blade.php          # 상세 모달
        └── edit-modal.blade.php          # 수정 모달

api/
└── database/migrations/
    └── 2026_01_29_100000_create_sales_partners_table.php
```

## 라우트

```php
// routes/web.php (sales prefix 그룹 내)

// Resource 라우트
GET    /managers                         → index()     파트너 목록
GET    /managers/create                  → create()    등록 폼
POST   /managers                         → store()     등록 처리
GET    /managers/{id}                    → show()      상세 페이지
GET    /managers/{id}/edit               → edit()      수정 폼
PUT    /managers/{id}                    → update()    수정 처리
DELETE /managers/{id}                    → destroy()   비활성화 (관리자)

// 추가 라우트
GET    /managers/{id}/modal-show         → modalShow()        상세 모달
GET    /managers/{id}/modal-edit         → modalEdit()        수정 모달
POST   /managers/{id}/approve            → approve()          승인
POST   /managers/{id}/reject             → reject()           반려
POST   /managers/{id}/delegate-role      → delegateRole()     역할 위임
POST   /managers/{id}/assign-role        → assignRole()       역할 부여
POST   /managers/{id}/remove-role        → removeRole()       역할 제거
GET    /managers/{id}/documents/{docId}/download → downloadDocument() 서류 다운로드
DELETE /managers/{id}/documents/{docId}  → deleteDocument()   서류 삭제
```

## 컨트롤러

### SalesManagerController

| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | 파트너 목록 (현재 사용자 유치분) |
| `create()` | GET | 등록 폼 |
| `store()` | POST | 파트너 등록 (서류 업로드 포함) |
| `show()` | GET | 상세 페이지 |
| `edit()` | GET | 수정 폼 |
| `update()` | PUT | 정보 수정 |
| `destroy()` | DELETE | 비활성화 (관리자 전용) |
| `modalShow()` | GET | 상세 모달 (HTMX) |
| `modalEdit()` | GET | 수정 모달 (HTMX) |
| `delegateRole()` | POST | 상담매니저 역할 위임 |
| `assignRole()` | POST | 역할 부여 (sales/manager) |
| `removeRole()` | POST | 역할 제거 |
| `downloadDocument()` | GET | 서류 파일 다운로드 |
| `deleteDocument()` | DELETE | 서류 파일 삭제 |

### SalesManagerService

| 메서드 | 설명 |
|--------|------|
| `getSalesPartners()` | 필터 적용 파트너 목록 조회 |
| `getStats()` | 파트너 통계 계산 |
| `getApprovalStats()` | 승인 관련 통계 |
| `createSalesPartner()` | 파트너 생성 |
| `updateSalesPartner()` | 파트너 수정 |
| `approve()` | 승인 처리 |
| `reject()` | 반려 처리 |

## 모델

### SalesPartner

**테이블**: `sales_partners`

| 필드 | 타입 | 설명 |
|------|------|------|
| `user_id` | bigint (FK) | 연결된 사용자 ID |
| `partner_code` | string | 파트너 고유 코드 (SP + 연도 + 순번) |
| `partner_type` | string | individual(개인) / corporate(법인) |
| `commission_rate` | decimal(5,2) | 기본 수수료율 |
| `manager_commission_rate` | decimal(5,2) | 관리자 수수료율 |
| `bank_name` | string | 은행명 |
| `account_number` | string | 계좌번호 |
| `account_holder` | string | 예금주 |
| `status` | string | pending / active / inactive / suspended |
| `approved_at` | timestamp | 승인 일시 |
| `approved_by` | bigint (FK) | 승인자 ID |
| `total_contracts` | int | 총 계약 건수 (캐시) |
| `total_commission` | decimal | 총 수당 (캐시) |

- SoftDeletes 적용

### SalesManagerDocument

**테이블**: `sales_manager_documents`

- 파트너 등록 시 필수 서류 관리 (신분증, 통장사본 등)
- `DOCUMENT_TYPES` 상수로 서류 타입 정의

### 파트너 계층 구조

```
User 모델의 parent_id를 통한 다단계 구조:

추천인 (parent)
  └── 영업파트너 (children)
       └── 하위 파트너 (children)
```

## 뷰 구성

```
┌─ 페이지 헤더 ──────────────────────
│  제목: "파트너관리"
│  [등록] 버튼
│
├─ 통계 카드 ────────────────────────
│  전체 | 활성 | 대기중 | 비활성
│
├─ 필터 영역 ────────────────────────
│  검색 (이름, 아이디) | 상태 필터 | 타입 필터
│
├─ 파트너 목록 테이블 ───────────────
│  이름 | 파트너코드 | 타입 | 수수료율 | 계약수 | 상태 | 작업
│  └─ 작업: 상세, 수정, 역할관리, 승인/반려
│
├─ 등록 폼 ─────────────────────────
│  사용자 정보, 파트너 타입, 수수료율
│  계좌 정보, 서류 업로드
│
└─ 상세/수정 모달 ──────────────────
   파트너 정보, 계층, 서류 목록, 역할 관리
```

## HTMX 호환성

- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- 모달로 상세/수정 처리
- HTMX 또는 JavaScript AJAX 호출