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

라우트

// 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	검색 (설명, 업체명, 메모)

주행거리 자동 갱신

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

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

Static 메서드

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

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