# 카드/차량관리 기능

## 개요

SAM 프로젝트의 카드/차량관리 모듈은 법인카드 관리, 카드 사용내역 조회, 차량 관리, 운행일지, 정비이력을 종합적으로 관리하는 시스템입니다.
바로빌 API 연동을 통한 카드거래 자동 수집, 카드별 사용금액 집계, 차량 운행/정비 기록 관리 기능을 제공합니다.

## 메뉴 구성

| 메뉴 | 경로 | 설명 | UI 기술 |
|------|------|------|---------|
| [법인카드관리](./corporate-cards.md) | `/finance/corporate-cards` | 법인카드 등록/조회, 요약 대시보드 | React 18 |
| [카드사용내역](./card-transactions.md) | `/finance/card-transactions` | 바로빌 연동 카드거래 조회 및 회계 분류 | React 18 |
| [차량목록](./corporate-vehicles.md) | `/finance/corporate-vehicles` | 법인/렌트/리스 차량 등록 관리 | React 18 |
| [차량일지](./vehicle-logs.md) | `/finance/vehicle-logs` | 차량 운행기록 관리 | React 18 |
| [정비이력](./vehicle-maintenance.md) | `/finance/vehicle-maintenance` | 차량 정비/주유/보험 등 비용 관리 | React 18 |

## 아키텍처

```
┌───────────────────────────────────────────────────────────────┐
│                     카드/차량관리 모듈                          │
├──────────────────────┬────────────────────────────────────────┤
│    카드 관리 영역      │           차량 관리 영역                │
│                      │                                        │
│  ┌────────────────┐  │  ┌──────────┐  ┌────────┐  ┌────────┐ │
│  │ 법인카드관리    │  │  │ 차량목록  │  │ 차량일지 │  │ 정비이력│ │
│  │ (카드 CRUD)    │  │  │(차량CRUD)│  │(운행기록)│  │(비용기록)│ │
│  └───────┬────────┘  │  └────┬─────┘  └────┬───┘  └───┬────┘ │
│          │           │       │              │          │      │
│  ┌───────▼────────┐  │       └──────────────┼──────────┘      │
│  │ 카드사용내역    │  │                      │                 │
│  │(바로빌 연동)   │  │                      │                 │
│  └───────┬────────┘  │                      │                 │
├──────────┼───────────┴──────────────────────┼─────────────────┤
│          ▼                                  ▼                 │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │                    데이터베이스                            │ │
│  │  corporate_cards, card_transactions,                     │ │
│  │  barobill_card_transactions, corporate_card_prepayments  │ │
│  │  corporate_vehicles, vehicle_logs, vehicle_maintenances  │ │
│  └──────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
```

## 주요 기술 스택

| 기술 | 용도 |
|------|------|
| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
| React 18 + Babel | 클라이언트 렌더링 UI (전 페이지) |
| Tailwind CSS + Lucide | 스타일링 및 아이콘 |
| Barobill SOAP API | 카드거래 실시간 연동 |
| MySQL 8.0 | 데이터 저장 |

## 데이터 흐름

```
바로빌 SOAP API ──────────────────────────────┐
(CARD.asmx: 카드거래 자동 수집)                  │
                                               ▼
카드 관리:  corporate_cards ← 매칭 → barobill_card_transactions
           (카드번호 하이픈 제거 후 매칭)
                    │
                    ├── barobill_card_transaction_splits (분개)
                    ├── barobill_card_transaction_hides (숨김)
                    ├── barobill_card_transaction_amount_logs (수정이력)
                    └── corporate_card_prepayments (선불결제)

차량 관리:  corporate_vehicles
                    │
                    ├── vehicle_logs (운행기록 → distance_km 합산)
                    └── vehicle_maintenances (정비기록 → mileage 갱신)
```

## 공통 모델/패턴

### 멀티 테넌트

모든 테이블은 `tenant_id` 기반으로 데이터를 격리합니다.

### React 18 + Babel

모든 페이지는 브라우저 트랜스파일링 방식의 React 18을 사용합니다:
- `@push('scripts')` 블록에 React/Babel/Lucide 스크립트 포함
- `@verbatim` + `<script type="text/babel">` 패턴
- HTMX 네비게이션 시 HX-Redirect 필수 (전체 페이지 리로드)

### 카드번호 매칭 로직

```
corporate_cards.card_number  ←매칭→  barobill_card_transactions.card_num
(예: "9438-8309-3638-4247")         (예: "9438830936384247")
→ 하이픈 제거 후 매칭: str_replace('-', '', $cardNumber)
```

## 데이터베이스 테이블 요약

### 카드 관련

| 테이블 | 역할 |
|--------|------|
| `corporate_cards` | 법인카드 정보 (카드명, 카드사, 번호, 한도 등) |
| `corporate_card_prepayments` | 월별 선불결제 금액 |
| `card_transactions` | 수동 입력 카드거래 |
| `barobill_card_transactions` | 바로빌 자동 수집 카드거래 |
| `barobill_card_transaction_splits` | 카드거래 분개 (1거래→N계정과목) |
| `barobill_card_transaction_hides` | 거래 숨김 처리 |
| `barobill_card_transaction_amount_logs` | 거래 금액 수정 이력 |

### 차량 관련

| 테이블 | 역할 |
|--------|------|
| `corporate_vehicles` | 법인/렌트/리스 차량 정보 |
| `vehicle_logs` | 차량 운행기록 (출발/도착, 거리, 용도) |
| `vehicle_maintenances` | 정비/주유/보험 등 비용 기록 |