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
```

## 라우트

```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() 응답 구조

```json
{
  "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

```php
->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 네비게이션 시 전체 페이지 리로드 필수