sam-docs/features/card-vehicle/corporate-vehicles.md

# 차량목록

## 개요

차량목록은 회사의 법인차량(법인/렌트/리스)을 등록하고 관리하는 기능입니다.
소유형태별 차량 등록, 총 주행거리 자동 계산, 차량 상태 관리 등을 지원합니다.

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

## 파일 구조

```
mng/
├── app/Http/Controllers/Finance/
│   └── CorporateVehicleController.php     # 메인 컨트롤러 (5개 메서드)
├── app/Models/
│   └── CorporateVehicle.php               # 차량 모델
└── resources/views/finance/
    └── corporate-vehicles.blade.php       # React 기반 단일 페이지

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

## 라우트

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

## 컨트롤러

### CorporateVehicleController

| 메서드 | HTTP | 설명 |
|--------|------|------|
| `index()` | GET | React 페이지 렌더링 (HX-Redirect 적용) |
| `list()` | GET | 차량 목록 (필터 + 총 주행거리 계산) |
| `store()` | POST | 차량 등록 |
| `update()` | PUT | 차량 수정 |
| `destroy()` | DELETE | 차량 삭제 |

### list() 핵심 로직

```
필터 파라미터: ownership_type, vehicle_type, status, search
    ↓
CorporateVehicle::where(tenant_id, ...)
    ↓
각 차량별 총 주행거리 계산:
  total_mileage = initial_mileage + SUM(vehicle_logs.distance_km)
    ↓
JSON 응답
```

## 모델

### CorporateVehicle

**테이블**: `corporate_vehicles`

| 필드 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | bigint | 테넌트 ID |
| `plate_number` | string(20) | 차량번호 |
| `model` | string(100) | 차량 모델명 |
| `vehicle_type` | string(20) | 차종 |
| `ownership_type` | enum | **corporate** / rent / lease |
| `year` | year | 연식 |
| `driver` | string(50) | 주 운전자 |
| `status` | enum | **active** / maintenance / disposed |
| `mileage` | int | 현재 주행거리 (정비 기준) |
| `memo` | text | 메모 |

#### 법인 전용 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `purchase_date` | date | 취득일자 |
| `purchase_price` | int | 취득가액 |

#### 렌트/리스 전용 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `contract_date` | date | 계약일자 |
| `rent_company` | string | 렌트/리스사 |
| `rent_company_tel` | string | 연락처 |
| `rent_period` | string | 계약기간 |
| `agreed_mileage` | int | 약정주행거리 |
| `vehicle_price` | int | 차량가액 |
| `residual_value` | int | 잔존가치 |
| `deposit` | int | 보증금 |
| `monthly_rent` | int | 월 렌트료 |
| `monthly_rent_tax` | int | 부가세 |
| `insurance_company` | string | 보험사 |
| `insurance_company_tel` | string | 보험사 연락처 |

#### Traits / Scope

- `SoftDeletes` 적용
- Casts: year, mileage, purchase_price, vehicle_price, residual_value, deposit, monthly_rent, monthly_rent_tax → integer

## 뷰 구성 (React)

### corporate-vehicles.blade.php

```
┌─ 페이지 헤더 ──────────────────────
│  제목: "차량목록"
│  검색 | Excel 다운로드 | 차량 등록 버튼
│
├─ 요약 카드 (4열) ──────────────────
│  총 차량 | 법인 취득가 | 월 렌트/리스비 | 총 주행거리
│
├─ 필터 바 ──────────────────────────
│  소유형태: 전체 | 법인 | 렌트 | 리스
│  상태: 전체 | 운행중 | 정비중 | 처분
│
├─ 차량 목록 테이블 (12열 그리드) ──
│  차량번호 | 차종/모델 | 소유형태 | 운전자 | 주행거리 | 상태
│  └─ 소유형태: 법인(보라), 렌트(파랑), 리스(초록) 배지
│  └─ 상태: 운행중(초록), 정비중(노랑), 처분(빨강) 배지
│
├─ 등록/수정 모달 ───────────────────
│  차량번호, 모델명, 차종, 소유형태
│  연식, 주 운전자, 상태, 메모
│  ─────────────────────────
│  [법인일 때] 취득일자, 취득가액
│  [렌트/리스일 때] 계약일, 렌트사, 계약기간,
│    약정주행, 차량가액, 잔존가치, 보증금,
│    월렌트료, 부가세, 보험사
│  ─────────────────────────
│  [삭제] [취소] [등록/저장]
│
└─ 비어있을 때: "등록된 차량이 없습니다" 안내
```

## 데이터 흐름

```
CorporateVehicle (1) ← (N) VehicleLog (총 주행거리 합산)
                     ← (N) VehicleMaintenance (주행거리 갱신)
```

### 주행거리 계산 방식

```
총 주행거리 = CorporateVehicle.mileage (정비 시 갱신 기준값)
            + SUM(vehicle_logs.distance_km) (운행일지 거리 합계)
```

## HTMX 호환성

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