sam-docs/features/card-vehicle/vehicle-logs.md

차량일지

개요

차량일지는 법인차량의 운행기록을 관리하는 기능입니다. 출발/도착지, 운행 거리, 용도(출퇴근/업무/비업무), 월별 통계 등을 지원합니다.

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

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── VehicleLogController.php           # 메인 컨트롤러 (7개 메서드)
├── app/Models/
│   └── VehicleLog.php                     # 운행기록 모델
└── resources/views/finance/
    └── vehicle-logs.blade.php             # React 기반 단일 페이지

api/
└── database/migrations/
    ├── 2026_02_03_100000_create_vehicle_logs_table.php
    └── 2026_02_03_133000_modify_vehicle_logs_trip_type_enum.php

라우트

// routes/web.php (finance prefix 그룹 내)
GET    /vehicle-logs            → index()     페이지 렌더링
GET    /vehicle-logs/vehicles   → vehicles()  차량 목록 (드롭다운용)
GET    /vehicle-logs/list       → list()      운행기록 목록 (JSON)
GET    /vehicle-logs/summary    → summary()   월별 통계
POST   /vehicle-logs            → store()     기록 등록
PUT    /vehicle-logs/{id}       → update()    기록 수정
DELETE /vehicle-logs/{id}       → destroy()   기록 삭제

컨트롤러

VehicleLogController

메서드	HTTP	설명
index()	GET	React 페이지 렌더링 (HX-Redirect 적용)
vehicles()	GET	전체 차량 목록 (드롭다운 선택용)
list()	GET	운행기록 목록 (필터, 검색)
summary()	GET	월별 용도별 통계 (건수, 거리)
store()	POST	운행기록 등록
update()	PUT	운행기록 수정
destroy()	DELETE	운행기록 삭제

list() 필터 파라미터

파라미터	설명
vehicle_id	차량 ID
year / month	연/월
trip_type	운행 용도
search	검색 (운전자, 부서, 출발지, 도착지, 비고)

summary() 응답 구조

{
  "success": true,
  "data": [
    { "trip_type": "business", "count": 15, "total_distance": 450 },
    { "trip_type": "commute_to", "count": 22, "total_distance": 330 },
    { "trip_type": "commute_from", "count": 22, "total_distance": 330 },
    { "trip_type": "personal", "count": 3, "total_distance": 45 }
  ]
}

모델

VehicleLog

테이블: vehicle_logs

필드	타입	설명
tenant_id	bigint	테넌트 ID
vehicle_id	bigint	차량 FK (corporate_vehicles)
log_date	date	운행일
department	string(50)	부서
driver_name	string(50)	운전자명
trip_type	enum	운행 용도 (아래 참조)
departure_type	string	출발지 유형
departure_name	string	출발지명
departure_address	string	출발지 주소
arrival_type	string	도착지 유형
arrival_name	string	도착지명
arrival_address	string	도착지 주소
distance_km	int	운행거리 (km)
note	string(200)	비고

운행 용도 (trip_type)

값	설명
commute_to	출근용
commute_from	퇴근용
business	업무용
personal	비업무
commute_round	출퇴근 왕복
business_round	업무용 왕복
personal_round	비업무 왕복

위치 유형 (departure_type / arrival_type)

값	설명
home	자택
office	회사
client	거래처
other	기타

Relationships

$log->vehicle    // BelongsTo CorporateVehicle
$log->tenant     // BelongsTo Tenant

Static 메서드

VehicleLog::getTripTypes()      // 용도 라벨 배열
VehicleLog::getLocationTypes()  // 위치 유형 라벨 배열
VehicleLog::getNoteOptions()    // 미리 정의된 비고 옵션

뷰 구성 (React)

vehicle-logs.blade.php

┌─ 페이지 헤더 ──────────────────────
│  차량 선택 드롭다운 (현재 주행거리 표시)
│  연/월 선택 | Excel 다운로드 | 기록 추가 버튼
│
├─ 용도별 통계 카드 ─────────────────
│  출근 | 퇴근 | 업무 | 비업무
│  건수 + 총 거리(km)
│
├─ 운행기록 테이블 ──────────────────
│  날짜 | 차량 | 부서/이름 | 용도 | 출발지 | 도착지 | 거리 | 비고
│  └─ 용도: 출근(초록), 퇴근(파랑), 업무(보라), 비업무(회색) 배지
│  └─ 복사 버튼 (이전 기록 복제)
│  └─ 출발↔도착 교환 버튼 (trip_type도 자동 전환)
│
├─ 등록/수정 모달 ───────────────────
│  차량 선택, 날짜, 부서, 운전자, 용도
│  출발지: 유형 + 이름 + 주소
│  도착지: 유형 + 이름 + 주소
│  운행거리(km)
│  비고: 미리 정의된 옵션 버튼 + 자유 입력
│  [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지

특수 기능

기능	설명
기록 복사	이전 운행기록을 새 날짜로 복제
출발↔도착 교환	출발지와 도착지를 스왑, trip_type도 자동 전환 (commute_to ↔ commute_from)
미리 정의 비고	버튼 클릭으로 빠른 비고 입력 + 자유 텍스트
용도별 통계	월별 용도별 건수 및 총 거리 집계

HTMX 호환성

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