sam-docs/features/sales/admin-prospects.md

# 고객 관리 (관리자)

## 개요

고객 관리(관리자)는 본사 관리자가 모든 영업파트너의 고객을 통합 관리하는 기능입니다.
전사 고객 현황 파악, 본사 진행상태 관리, 수당 지급 기록, 상태 변경을 지원합니다.

- **라우트**: `GET /sales/admin-prospects`
- **미들웨어**: `auth`, `hq.member` + 관리자 권한 체크
- **UI 기술**: Blade + HTMX + Tailwind CSS

## 파일 구조

```
mng/
├── app/Http/Controllers/Sales/
│   └── AdminProspectController.php       # 메인 컨트롤러 (8개 메서드)
└── resources/views/sales/admin-prospects/
    ├── index.blade.php                   # 전체 고객 목록 (460줄)
    └── partials/
        ├── content.blade.php             # 콘텐츠 새로고침
        └── show-modal.blade.php          # 고객 상세 모달
```

## 라우트

```php
// routes/web.php (sales prefix 그룹 내)
GET    /admin-prospects                           → index()              전체 고객 목록
GET    /admin-prospects/refresh                   → refresh()            HTMX 새로고침
GET    /admin-prospects/{id}/modal-show           → modalShow()          상세 모달
POST   /admin-prospects/{id}/hq-status            → updateHqStatus()     본사 진행상태 변경
POST   /admin-prospects/{id}/commission-date      → updateCommissionDate() 수당 날짜 기록
DELETE /admin-prospects/{id}/commission-date      → clearCommissionDate() 수당 날짜 초기화
DELETE /admin-prospects/{id}                      → destroy()            삭제 (슈퍼관리자)
POST   /admin-prospects/{id}/toggle-status        → toggleStatus()       상태 토글
```

## 컨트롤러

### AdminProspectController

| 메서드 | HTTP | 설명 | 권한 |
|--------|------|------|------|
| `index()` | GET | 전체 고객 목록 (필터+통계) | 관리자/슈퍼관리자 |
| `refresh()` | GET | 콘텐츠 새로고침 (HTMX) | 관리자/슈퍼관리자 |
| `modalShow()` | GET | 고객 상세 모달 (진행률 포함) | 관리자/슈퍼관리자 |
| `updateHqStatus()` | POST | 본사 진행상태 변경 | 관리자/슈퍼관리자 |
| `updateCommissionDate()` | POST | 수당 지급 날짜 기록/수정 | 관리자/슈퍼관리자 |
| `clearCommissionDate()` | DELETE | 수당 날짜 초기화 | 관리자/슈퍼관리자 |
| `toggleStatus()` | POST | 상태 토글 (영업중 ↔ 완료) | 관리자/슈퍼관리자 |
| `destroy()` | DELETE | 삭제 | 슈퍼관리자 전용 |

### 본사 진행상태 (HQ Status) 8단계

```
pending (대기)
  → review (검토)
    → planning (기획안작성)
      → coding (개발코드작성)
        → dev_test (개발테스트)
          → dev_done (개발완료)
            → int_test (통합테스트)
              → handover (인계)
```

### 수당 날짜 관리

```
updateCommissionDate():
  - 납입일(membership_paid_at) 입력 시
  - 자동 지급일 계산: 익월 10일
  - commission_paid_at 기록
```

## 모델

### SalesTenantManagement (핵심 모델)

**테이블**: `sales_tenant_managements`

| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint (FK, unique) | 테넌트 ID (1:1) |
| `tenant_prospect_id` | bigint (FK) | 가망고객 ID |
| `sales_partner_id` | bigint (FK) | 영업 담당자 ID |
| `manager_user_id` | bigint (FK) | 상담매니저 사용자 ID |
| `sales_scenario_step` | int | 영업 시나리오 단계 (1-6) |
| `manager_scenario_step` | int | 매니저 시나리오 단계 (1-6) |
| `status` | enum | 영업 상태 |
| `hq_status` | enum | 본사 진행상태 |
| `first_contact_at` | timestamp | 최초 접촉일 |
| `contracted_at` | timestamp | 계약 체결일 |
| `onboarding_completed_at` | timestamp | 온보딩 완료일 |
| `membership_fee` | decimal | 가입비 |
| `membership_paid_at` | timestamp | 가입비 입금일 |
| `membership_status` | enum | pending / partial / paid / refunded |
| `sales_commission` | decimal | 영업 수당 |
| `manager_commission` | decimal | 관리 수당 |
| `commission_paid_at` | timestamp | 수당 지급일 |
| `sales_progress` | tinyint | 영업 진행률 (%) |
| `manager_progress` | tinyint | 매니저 진행률 (%) |
| `incentive_status` | enum | pending / eligible / paid |
| `notes` | text | 메모 |

#### 영업 상태 흐름

```
prospect (잠재) → approach (접근) → negotiation (협상)
  → contracted (계약) → onboarding (온보딩) → active (활성) / churned (이탈)
```

#### 수당 상태

```
pending (대기) → eligible (지급대상) → paid (지급완료)
```

## 뷰 구성

### index.blade.php

```
┌─ 페이지 헤더 ──────────────────────
│  제목: "고객 관리"
│  [새로고침] 버튼
│
├─ 통계 카드 ────────────────────────
│  전체 | 활성 | 완료 | 인계완료
│
├─ 필터 영역 ────────────────────────
│  검색 (회사명, 사업자번호, 대표자, 연락처)
│  상태: active / expired / converted / progress_complete
│  인계: hq_status = 'handover'
│  영업파트너: registered_by 필터
│
├─ 고객 목록 테이블 ────────────────
│  회사명 | 사업자번호 | 대표자 | 영업파트너
│  영업진행률 | 매니저진행률 | 본사상태 | 작업
│  └─ 본사상태: 8단계 프로그레스바
│  └─ 작업: 상세, 상태변경, 삭제
│
└─ 상세 모달 ───────────────────────
   기본 정보 (회사명, 사업자번호, 대표자, 연락처)
   영업 진행률 (영업 시나리오, 매니저 시나리오)
   본사 진행상태 (8단계 프로그레스바 + 변경 드롭다운)
   수당 정보 (납입일, 지급일, 자동 계산)
   담당 매니저 정보
```

## HTMX 호환성

- Blade + HTMX 기반으로 **HX-Redirect 불필요**
- `hx-get`으로 부분 새로고침
- 모달로 상세 조회 및 상태 변경