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

## 라우트

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

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

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

#### Static 메서드

```php
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 스크립트 포함