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          # 고객 상세 모달

라우트

// 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으로 부분 새로고침
• 모달로 상세 조회 및 상태 변경