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

# 정비이력

## 개요

정비이력은 법인차량의 정비, 주유, 보험, 세차, 주차, 통행료 등 비용을 기록하고 관리하는 기능입니다.
카테고리별 비용 집계, 주행거리 자동 갱신, 기간별 필터링 등을 지원합니다.

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

## 파일 구조

```
mng/
├── app/Http/Controllers/Finance/
│   └── VehicleMaintenanceController.php    # 메인 컨트롤러 (6개 메서드)
├── app/Models/
│   └── VehicleMaintenance.php              # 정비이력 모델
└── resources/views/finance/
    └── vehicle-maintenance.blade.php       # React 기반 단일 페이지

api/
└── database/migrations/
    └── 2026_02_03_195000_create_vehicle_maintenances_table.php
```

## 라우트

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

## 컨트롤러

### VehicleMaintenanceController

| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `vehicles()` | GET | 전체 차량 목록 (드롭다운 선택용) |
| `list()` | GET | 정비이력 목록 (필터, 검색, 차량 관계 포함) |
| `store()` | POST | 정비 등록 + **차량 주행거리 갱신** |
| `update()` | PUT | 정비 수정 + **차량 주행거리 갱신** |
| `destroy()` | DELETE | 정비 삭제 |

### list() 필터 파라미터

| 파라미터 | 설명 |
|---------|------|
| `vehicle_id` | 차량 ID |
| `category` | 카테고리 (주유, 정비, 보험 등) |
| `start_date` / `end_date` | 기간 (기본: 최근 3개월) |
| `search` | 검색 (설명, 업체명, 메모) |

### 주행거리 자동 갱신

```php
// store() / update() 에서
if ($request->mileage) {
    $vehicle = CorporateVehicle::find($request->vehicle_id);
    $vehicle->update(['mileage' => $request->mileage]);
}
```

정비 등록/수정 시 입력한 주행거리가 해당 차량의 기준 주행거리(mileage)를 갱신합니다.

## 모델

### VehicleMaintenance

**테이블**: `vehicle_maintenances`

| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `vehicle_id` | bigint | 차량 FK (corporate_vehicles) |
| `date` | date | 정비일 |
| `category` | string(20) | 카테고리 |
| `description` | string(200) | 설명 |
| `amount` | bigint | 금액 |
| `mileage` | int | 정비 시 주행거리 |
| `vendor` | string(100) | 업체명 |
| `memo` | text | 메모 |

#### 카테고리 목록

| 카테고리 | 설명 | 아이콘/색상 |
|---------|------|------------|
| `주유` | 연료비 | Fuel / amber |
| `정비` | 차량 정비/수리 | Wrench / blue |
| `보험` | 자동차 보험료 | Shield / emerald |
| `세차` | 세차 비용 | Droplets / cyan |
| `주차` | 주차 비용 | ParkingCircle / purple |
| `통행료` | 고속도로 등 통행료 | Route / orange |
| `검사` | 정기검사/점검 | ClipboardCheck / indigo |
| `기타` | 기타 비용 | MoreHorizontal / gray |

#### Relationships

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

#### Static 메서드

```php
VehicleMaintenance::getCategories()
// ['주유', '정비', '보험', '세차', '주차', '통행료', '검사', '기타']
```

## 뷰 구성 (React)

### vehicle-maintenance.blade.php

```
┌─ 페이지 헤더 ──────────────────────
│  제목: "정비이력"
│  새로고침 | Excel 다운로드 | 정비 등록 버튼
│
├─ 요약 카드 (4열) ──────────────────
│  총 정비비용 | 주유비 | 정비비 | 기타비용
│  (기간 내 합산)
│
├─ 필터 영역 ────────────────────────
│  기간: 시작일 ~ 종료일 (기본: 최근 3개월)
│  카테고리: 전체 | 주유 | 정비 | 보험 | 세차 | 주차 | 통행료 | 검사 | 기타
│  차량: 드롭다운 선택
│  검색: 설명, 업체명 검색
│
├─ 정비이력 테이블 ──────────────────
│  날짜 | 차량 | 카테고리 | 설명 | 금액 | 주행거리 | 작업
│  └─ 카테고리: 컬러 배지 (카테고리별 고유 색상)
│  └─ 금액: 원 단위 포맷
│  └─ 작업: 수정/삭제 버튼
│
├─ 등록/수정 모달 ───────────────────
│  차량 선택, 날짜, 카테고리
│  설명, 금액, 주행거리, 업체명, 메모
│  [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: 안내 메시지
```

## 핵심 로직

### 비용 집계

```
요약 카드 계산:
  총 정비비용 = 조회 기간 내 모든 정비 금액 합계
  주유비     = category === '주유' 인 금액 합계
  정비비     = category === '정비' 인 금액 합계
  기타비용   = 나머지 카테고리 금액 합계
```

### 차량 주행거리 연동

```
정비 등록/수정 시 mileage 입력
    ↓
해당 차량(corporate_vehicles)의 mileage 필드 갱신
    ↓
차량목록에서 총 주행거리 재계산:
  total_mileage = mileage + SUM(vehicle_logs.distance_km)
```

## 데이터베이스 스키마

### vehicle_maintenances

```sql
CREATE TABLE vehicle_maintenances (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    tenant_id BIGINT NOT NULL,
    vehicle_id BIGINT NOT NULL,
    date DATE NOT NULL,
    category VARCHAR(20) NOT NULL,
    description VARCHAR(200),
    amount BIGINT UNSIGNED DEFAULT 0,
    mileage INT UNSIGNED,
    vendor VARCHAR(100),
    memo TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP,
    INDEX (tenant_id, vehicle_id, date),
    INDEX (tenant_id, category),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (vehicle_id) REFERENCES corporate_vehicles(id) ON DELETE CASCADE
);
```

## HTMX 호환성

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