sam-docs/features/card-vehicle/corporate-cards.md

법인카드관리

개요

법인카드관리는 회사의 법인카드(신용/체크)를 등록하고 관리하는 기능입니다. 카드 CRUD, 결제일 휴일 조정, 바로빌 기반 사용금액 집계, 선불결제 관리 등을 지원합니다.

• 라우트: GET /finance/corporate-cards
• 라우트 이름: finance.corporate-cards
• UI 기술: React 18 + Babel (브라우저 트랜스파일링)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── CorporateCardController.php        # 메인 컨트롤러 (7개 메서드)
├── app/Models/Finance/
│   ├── CorporateCard.php                  # 법인카드 모델
│   └── CorporateCardPrepayment.php        # 선불결제 모델
├── app/Models/Barobill/
│   ├── CardTransaction.php                # 바로빌 카드거래 모델
│   └── CardTransactionHide.php            # 거래 숨김 모델
├── app/Models/System/
│   └── Holiday.php                        # 휴일 모델
└── resources/views/finance/
    └── corporate-cards.blade.php          # React 기반 단일 페이지

api/
└── database/migrations/
    ├── 2026_01_30_180000_create_corporate_cards_table.php
    └── 2026_02_11_100000_create_corporate_card_prepayments_table.php

라우트

// routes/web.php (finance prefix 그룹 내)
Route::get('/corporate-cards', fn() => ...)->name('corporate-cards');

// API 라우트 (corporate-cards prefix)
GET    /list                → index()          카드 목록 조회
GET    /summary             → summary()        요약 데이터 (결제일, 사용금액 등)
POST   /prepayment          → updatePrepayment() 선불결제 수정
POST   /store               → store()          카드 등록
PUT    /{id}                → update()         카드 수정
POST   /{id}/deactivate     → deactivate()     카드 비활성화
DELETE /{id}                → destroy()        카드 영구삭제

컨트롤러

CorporateCardController

메서드	HTTP	설명
index()	GET	카드 목록 JSON 반환
store()	POST	카드 등록
update()	PUT	카드 수정
deactivate()	POST	비활성화 (status → inactive)
destroy()	DELETE	영구삭제 (forceDelete)
summary()	GET	요약 데이터 (결제일, 사용금액, 선불결제)
updatePrepayment()	POST	선불결제 금액 수정 (upsert)

summary() 응답 구조

{
  "success": true,
  "data": {
    "paymentDate": "2026-02-19",
    "paymentDay": 15,
    "originalDate": "2026-02-15",
    "isAdjusted": true,
    "billingPeriod": { "start": "2026-01-01", "end": "2026-02-19" },
    "billingUsage": 3500000,
    "cardUsages": { "9438830936384247": 1200000, "1234567890123456": 2300000 },
    "prepaidAmount": 500000,
    "prepaidMemo": "2월 선결제"
  }
}

핵심 로직

휴일 조정 결제일 계산 (getAdjustedPaymentDate)

당월 payment_day (예: 15일)
    ↓
Carbon 날짜 생성
    ↓
holidays 테이블에서 해당 기간 휴일 조회
    ↓
토/일/공휴일이면 다음 날로 반복 이동
    ↓
영업일 결제일 반환 (예: 15일→토→17일(월))

사용금액 계산 (calculateBillingUsage)

청구기간: 전월 1일 ~ 당월 결제일(휴일조정)
    ↓
corporate_cards에서 활성 카드번호 수집
    ↓
카드번호 정규화 (하이픈 제거)
    ↓
barobill_card_transactions 조회 (use_date 범위)
    ↓
숨긴 거래 제외 (barobill_card_transaction_hides)
    ↓
approval_type별 합산:
  - '1' (승인): + approval_amount
  - '2' (취소): - approval_amount
    ↓
총 사용금액 반환

잔여 한도 계산

잔여 한도 = 총 한도 - 사용금액 + 선불결제

모델

CorporateCard

테이블: corporate_cards

필드	타입	설명
tenant_id	bigint	테넌트 ID
card_name	string(100)	카드명 (예: "업무용 법인카드")
card_company	string(50)	카드사 (삼성, 현대 등)
card_number	string(30)	카드번호 (하이픈 포함)
card_type	enum	credit / debit
payment_day	tinyint	결제일 (기본: 15)
credit_limit	decimal(15,2)	사용한도
current_usage	decimal(15,2)	현재 사용액
card_holder_name	string(100)	이용자명 (법인 명의)
actual_user	string(100)	실사용자
expiry_date	string(10)	유효기간 (YY/MM)
cvc	string(10)	CVC
status	enum	active / inactive
memo	text	메모

주요 Scope

->active()         // status = 'active'
->forTenant($id)   // tenant_id 필터

CorporateCardPrepayment

테이블: corporate_card_prepayments

필드	타입	설명
tenant_id	bigint	테넌트 ID
year_month	string(7)	"2026-02" 형식
amount	decimal(15,0)	선불결제 금액
memo	string(200)	메모

• Unique: [tenant_id, year_month]
• getOrCreate(tenantId, yearMonth): 조회 또는 기본값(0) 생성

뷰 구성 (React)

corporate-cards.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "법인카드 등록/조회"
│  버튼: "카드 등록" (보라색)
│
├─ 요약 카드 (2열 / lg:6열) ─────────
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│  │등록카드│ │총 한도│ │매월   │ │사용  │ │선불  │ │잔여  │
│  │      │ │      │ │결제일 │ │금액  │ │결제  │ │한도  │
│  │3장   │ │50백만│ │2/19  │ │35백만│ │5백만 │ │20백만│
│  │활성2 │ │신용  │ │(수)  │ │1/1~  │ │[수정]│ │한도- │
│  │      │ │기준  │ │15→조정│ │2/19  │ │      │ │사용+ │
│  │      │ │      │ │      │ │기준  │ │      │ │선결제│
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
│
├─ 검색 및 필터 ─────────────────────
│  검색창 | 전체 | 활성 | 비활성
│
├─ 카드 목록 테이블 ─────────────────
│  카드명(카드사) | 카드번호 | 실사용자 | 사용현황(진행바) | 상태
│  └─ 신용: 사용률 % + 프로그레스 바
│  └─ 체크: 사용금액 표시
│
├─ 등록/수정 모달 ───────────────────
│  카드명, 카드사, 카드종류, 카드번호, 이용자명
│  유효기간, CVC, 상태, 실사용자
│  결제일(신용만), 사용한도(신용만), 메모
│  [비활성화] [영구삭제] [취소] [등록/저장]
│
└─ 선불결제 수정 모달 ───────────────
   금액 입력 (3자리 콤마), 메모 (선택)
   [취소] [저장]

React 주요 기능

기능	설명
요약 카드 6개	등록카드, 총한도, 매월결제일, 사용금액, 선불결제, 잔여한도
카드별 사용률	billingUsage 기준 프로그레스 바 표시
선불결제 인라인 수정	수정 버튼 → 모달 → 금액/메모 입력 → 즉시 반영
상태 필터	전체 / 활성 / 비활성
카드 검색	카드명, 카드사, 이용자명, 실사용자 검색

HTMX 호환성

• React 기반 페이지이므로 HX-Redirect 필요
• @push('scripts') 블록에 React/Babel 스크립트 포함
• HTMX 네비게이션 시 전체 페이지 리로드 필수