sam-docs/features/card-vehicle

카드/차량관리 기능

개요

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

메뉴 구성

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