sam-docs/features/crm/receivables.md

미수금관리

개요

미수금관리는 고객별 채권 현황을 추적하고 수금 처리를 관리하는 기능입니다. 인보이스별 미수금 등록, 부분/전액 수금 처리, 연체 추적, 통계 기능을 제공합니다.

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

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── ReceivableController.php           # MNG 컨트롤러 (5개 메서드)
├── app/Models/Finance/
│   └── Receivable.php                     # 미수금 모델
└── resources/views/finance/
    └── receivables.blade.php              # React 기반 단일 페이지

api/
├── app/Http/Controllers/Api/V1/
│   └── ReceivablesController.php          # API 컨트롤러 (월별 채권 현황)
├── app/Services/
│   └── ReceivablesService.php             # 비즈니스 로직 서비스
└── database/migrations/
    └── 2026_02_04_222005_create_receivables_table.php

라우트

MNG 라우트

// routes/web.php (finance prefix 그룹 내)
GET    /receivables                → 페이지 렌더링 (HX-Redirect)
GET    /receivables/list           → index()     목록 + 통계 (JSON)
POST   /receivables/store          → store()     등록
PUT    /receivables/{id}           → update()    수정
POST   /receivables/{id}/collect   → collect()   수금 처리
DELETE /receivables/{id}           → destroy()   삭제

API 라우트

// routes/api.php (v1/receivables prefix)
GET    /                           → index()              거래처별 월별 채권 현황
GET    /summary                    → summary()            채권 요약 통계
POST   /update-overdue             → updateOverdueStatus() 연체 상태 일괄 갱신
POST   /update-memos               → updateMemos()        메모 일괄 수정

컨트롤러

ReceivableController (MNG)

메서드	HTTP	설명
index()	GET	미수금 목록 (검색, 상태/카테고리 필터)
store()	POST	미수금 등록
update()	PUT	미수금 수정
collect()	POST	수금 처리 (수금액 입력 → 상태 자동 변경)
destroy()	DELETE	삭제 (Soft Delete)

collect() 수금 처리 로직

수금액 입력
    ↓
collected_amount += 수금액
    ↓
collected_amount >= amount ?
  → YES: status = 'collected' (전액 수금)
  → NO:  status = 'partial' (부분 수금)

index() 응답 구조

{
  "success": true,
  "data": [...],
  "stats": {
    "totalAmount": 50000000,
    "collectedAmount": 30000000,
    "outstandingAmount": 20000000,
    "overdueAmount": 5000000,
    "count": 25
  }
}

서비스 클래스 (API)

ReceivablesService

거래처별 월별 채권 현황을 제공하는 서비스:

메서드	설명
index(params)	거래처별 월별 매출/입금/어음/미수금 현황
summary(params)	채권 요약 통계
getCarryForwardBalance()	이월잔액 계산
getSalesByPeriods()	기간별 매출 조회
getDepositsByPeriods()	기간별 입금 조회
getBillsByPeriods()	기간별 어음 조회
calculateCumulativeReceivables()	누적 미수금 계산

모델

Receivable

테이블: receivables

필드	타입	설명
tenant_id	bigint	테넌트 ID
customer_name	string(100)	고객명
invoice_no	string(50)	인보이스 번호
issue_date	date	발급일
due_date	date	만기일
category	string(50)	카테고리
amount	bigint	총액
collected_amount	bigint	수금액
status	string	outstanding / partial / collected / overdue
description	string	설명
memo	text	메모

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

상태 흐름

outstanding (미수금)
    ├── collect() (부분) → partial (부분 수금)
    ├── collect() (전액) → collected (수금 완료)
    └── (만기일 경과)    → overdue (연체)

카테고리

서비스, 상품, 컨설팅, 기타

뷰 구성 (React)

receivables.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "미수금관리"
│  [등록] 버튼
│
├─ 통계 카드 (5열) ──────────────────
│  총액 | 수금액 | 미수금액 | 연체액 | 건수
│
├─ 필터 영역 ────────────────────────
│  검색 (고객명, 인보이스번호) | 상태 | 카테고리
│
├─ 미수금 목록 테이블 ───────────────
│  고객명 | 인보이스 | 발급일 | 만기일 | 카테고리 | 금액 | 수금액 | 상태 | 작업
│  └─ 상태: 미수금(노랑), 부분(파랑), 수금완료(초록), 연체(빨강) 배지
│  └─ 작업: 수금처리, 수정, 삭제
│
├─ 등록/수정 모달 ───────────────────
│  고객명, 인보이스번호, 발급일, 만기일
│  카테고리, 금액, 설명, 메모
│
└─ 수금 처리 모달 ───────────────────
   현재 미수금액 표시, 수금액 입력

HTMX 호환성

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