sam-docs/features/crm/refunds.md

환불/해지관리

개요

환불/해지관리는 고객의 환불 또는 해지 요청을 접수하고 승인 프로세스를 관리하는 기능입니다. 요청 등록, 사유 분류, 승인/거절 워크플로우, 환불액 추적을 지원합니다.

• 라우트: GET /finance/refunds
• UI 기술: React 18 + Babel (브라우저 트랜스파일링)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── RefundController.php               # 메인 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│   └── Refund.php                         # 환불/해지 모델
└── resources/views/finance/
    └── refunds.blade.php                  # React 기반 단일 페이지

api/
└── database/migrations/
    └── 2026_02_04_223406_create_refunds_table.php

라우트

// routes/web.php (finance prefix 그룹 내)
GET    /refunds                    → 페이지 렌더링 (HX-Redirect)
GET    /refunds/list               → index()     목록 + 통계 (JSON)
POST   /refunds/store              → store()     요청 등록
PUT    /refunds/{id}               → update()    요청 수정
POST   /refunds/{id}/process       → process()   요청 처리 (승인/완료/거절)
DELETE /refunds/{id}               → destroy()   삭제

컨트롤러

RefundController

메서드	HTTP	설명
index()	GET	목록 (검색, 상태/타입 필터)
store()	POST	환불/해지 요청 등록
update()	PUT	요청 수정
process()	POST	요청 처리 (approved/completed/rejected)
destroy()	DELETE	삭제 (Soft Delete)

process() 처리 로직

POST /refunds/{id}/process
{
    "action": "approved" | "completed" | "rejected",
    "refundAmount": 500000,   // (완료 시) 실제 환불액
    "note": "처리 비고"
}
    ↓
status 변경 + process_date 기록

index() 응답 구조

{
  "success": true,
  "data": [...],
  "stats": {
    "pendingCount": 5,
    "completedCount": 20,
    "rejectedCount": 3,
    "totalRefundAmount": 15000000
  }
}

모델

Refund

테이블: refunds

필드	타입	설명
tenant_id	bigint	테넌트 ID
type	string	refund(환불) / cancel(해지)
customer_name	string(100)	고객명
request_date	date	요청일
product_name	string(100)	상품명
original_amount	bigint	원금액
refund_amount	bigint	환불금액
reason	string(100)	사유
status	string	pending / approved / completed / rejected
process_date	date	처리일
note	text	비고

• SoftDeletes 적용
• Scope: forTenant($tenantId)
• Index: (tenant_id, status), (tenant_id, type)

요청 타입

타입	설명
refund	환불 (금액 반환)
cancel	해지 (서비스 종료)

상태 흐름

pending (대기)
    ├── process(approved)  → approved (승인)
    │       ↓
    │   process(completed) → completed (완료) + 환불액/처리일 기록
    │
    └── process(rejected)  → rejected (거절) + 처리일 기록

사유 목록

사유	설명
서비스 불만족	서비스 품질 관련
결제 오류	잘못된 결제
사업 종료	고객 사업 종료
경쟁사 이전	타사 이전
중복 결제	이중 결제
기타	기타 사유

뷰 구성 (React)

refunds.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "환불/해지관리"
│  [등록] 버튼
│
├─ 통계 카드 (4열) ──────────────────
│  대기 | 완료 | 거절 | 총 환불액
│
├─ 필터 영역 ────────────────────────
│  검색 (고객명, 상품명) | 상태 (전체/대기/승인/완료/거절) | 타입 (환불/해지)
│
├─ 요청 목록 테이블 ─────────────────
│  타입 | 고객명 | 요청일 | 상품명 | 원금 | 환불액 | 사유 | 상태 | 처리일 | 작업
│  └─ 타입: 환불(빨강), 해지(주황) 배지
│  └─ 상태: 대기(노랑), 승인(파랑), 완료(초록), 거절(빨강) 배지
│  └─ 작업: 처리, 수정, 삭제
│
├─ 등록/수정 모달 ───────────────────
│  타입(환불/해지), 고객명, 요청일, 상품명
│  원금액, 환불금액, 사유(드롭다운), 비고
│
└─ 처리 모달 ────────────────────────
   요청 정보 표시
   액션 선택: 승인 | 완료 | 거절
   환불액 (완료 시), 비고

HTMX 호환성

• React 기반 페이지이므로 HX-Redirect 필요
• @push('scripts') 블록에 React/Babel 스크립트 포함