975 lines
25 KiB
Markdown
975 lines
25 KiB
Markdown
# 차량관리 API 명세
|
|
|
|
> **작성일**: 2026-03-12
|
|
> **상태**: API 이관 예정 (MNG에서 운영중, API 엔드포인트 미구현)
|
|
> **Base URL**: `api.codebridge-x.com` (운영) / `api.dev.codebridge-x.com` (개발)
|
|
|
|
---
|
|
|
|
## 1. 개요
|
|
|
|
법인/렌트/리스 차량을 등록하고, 운행일지와 정비이력을 관리하는 API이다.
|
|
멀티테넌트 구조로 테넌트별 데이터 격리가 적용된다.
|
|
|
|
### 1.1 인증
|
|
|
|
모든 요청에 다음 헤더가 필요하다:
|
|
|
|
```
|
|
X-API-KEY: {api_key}
|
|
Authorization: Bearer {token}
|
|
```
|
|
|
|
### 1.2 공통 응답 형식
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "조회 성공",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
에러 시:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "에러 메시지"
|
|
}
|
|
```
|
|
|
|
### 1.3 메뉴 구성
|
|
|
|
| 메뉴 | 설명 | 섹션 |
|
|
|------|------|------|
|
|
| 차량목록 | 법인/렌트/리스 차량 등록 관리 | [3. 차량목록 API](#3-차량목록-api) |
|
|
| 차량일지 | 운행기록 관리 및 월별 통계 | [4. 차량일지 API](#4-차량일지-api) |
|
|
| 정비이력 | 정비/주유/보험 등 비용 관리 | [5. 정비이력 API](#5-정비이력-api) |
|
|
|
|
### 1.4 엔드포인트 요약
|
|
|
|
| # | Method | Path | 설명 |
|
|
|---|--------|------|------|
|
|
| 1 | GET | `/api/v1/corporate-vehicles` | 차량 목록 |
|
|
| 2 | POST | `/api/v1/corporate-vehicles` | 차량 등록 |
|
|
| 3 | GET | `/api/v1/corporate-vehicles/{id}` | 차량 상세 |
|
|
| 4 | PUT | `/api/v1/corporate-vehicles/{id}` | 차량 수정 |
|
|
| 5 | DELETE | `/api/v1/corporate-vehicles/{id}` | 차량 삭제 |
|
|
| 6 | GET | `/api/v1/corporate-vehicles/dropdown` | 차량 드롭다운 목록 |
|
|
| 7 | GET | `/api/v1/vehicle-logs` | 운행기록 목록 |
|
|
| 8 | POST | `/api/v1/vehicle-logs` | 운행기록 등록 |
|
|
| 9 | GET | `/api/v1/vehicle-logs/{id}` | 운행기록 상세 |
|
|
| 10 | PUT | `/api/v1/vehicle-logs/{id}` | 운행기록 수정 |
|
|
| 11 | DELETE | `/api/v1/vehicle-logs/{id}` | 운행기록 삭제 |
|
|
| 12 | GET | `/api/v1/vehicle-logs/summary` | 월별 용도별 통계 |
|
|
| 13 | GET | `/api/v1/vehicle-maintenances` | 정비이력 목록 |
|
|
| 14 | POST | `/api/v1/vehicle-maintenances` | 정비이력 등록 |
|
|
| 15 | GET | `/api/v1/vehicle-maintenances/{id}` | 정비이력 상세 |
|
|
| 16 | PUT | `/api/v1/vehicle-maintenances/{id}` | 정비이력 수정 |
|
|
| 17 | DELETE | `/api/v1/vehicle-maintenances/{id}` | 정비이력 삭제 |
|
|
| 18 | GET | `/api/v1/corporate-vehicles/{id}/photos` | 차량 사진 목록 |
|
|
| 19 | POST | `/api/v1/corporate-vehicles/{id}/photos` | 차량 사진 업로드 (최대 10장) |
|
|
| 20 | DELETE | `/api/v1/corporate-vehicles/{id}/photos/{fileId}` | 차량 사진 삭제 |
|
|
|
|
---
|
|
|
|
## 2. 데이터 모델
|
|
|
|
### 2.1 CorporateVehicle (차량)
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"plate_number": "12가 3456",
|
|
"model": "에쿠스",
|
|
"vehicle_type": "승용차",
|
|
"ownership_type": "corporate",
|
|
"year": 2024,
|
|
"driver": "홍길동",
|
|
"status": "active",
|
|
"mileage": 15000,
|
|
"memo": "대표이사 전용",
|
|
"purchase_date": "2024-01-15",
|
|
"purchase_price": 85000000,
|
|
"contract_date": null,
|
|
"rent_company": null,
|
|
"rent_company_tel": null,
|
|
"rent_period": null,
|
|
"agreed_mileage": null,
|
|
"vehicle_price": 0,
|
|
"residual_value": 0,
|
|
"deposit": 0,
|
|
"monthly_rent": 0,
|
|
"monthly_rent_tax": 0,
|
|
"insurance_company": null,
|
|
"insurance_company_tel": null,
|
|
"log_distance": 2350,
|
|
"total_mileage": 17350,
|
|
"created_at": "2026-01-15T09:00:00.000000Z",
|
|
"updated_at": "2026-03-10T14:30:00.000000Z"
|
|
}
|
|
```
|
|
|
|
#### 필드 설명 — 공통
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `plate_number` | string(20) | ✅ | 차량번호 |
|
|
| `model` | string(100) | ✅ | 차량 모델명 |
|
|
| `vehicle_type` | string(20) | ✅ | 차종 |
|
|
| `ownership_type` | enum | ✅ | 소유형태 |
|
|
| `year` | int | | 연식 |
|
|
| `driver` | string(50) | | 주 운전자 |
|
|
| `status` | enum | | 상태 (기본: `active`) |
|
|
| `mileage` | int | | 기준 주행거리 (정비 시 갱신, 기본: 0) |
|
|
| `memo` | text | | 메모 |
|
|
|
|
#### 필드 설명 — 법인 전용 (`ownership_type = "corporate"`)
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| `purchase_date` | date | 취득일자 |
|
|
| `purchase_price` | int | 취득가액 (원) |
|
|
|
|
#### 필드 설명 — 렌트/리스 전용 (`ownership_type = "rent" or "lease"`)
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| `contract_date` | date | 계약일자 |
|
|
| `rent_company` | string(100) | 렌트/리스 회사명 |
|
|
| `rent_company_tel` | string(20) | 회사 연락처 |
|
|
| `rent_period` | string(20) | 계약기간 |
|
|
| `agreed_mileage` | string(20) | 약정주행거리 |
|
|
| `vehicle_price` | int | 차량가액 (원) |
|
|
| `residual_value` | int | 잔존가치 (원) |
|
|
| `deposit` | int | 보증금 (원) |
|
|
| `monthly_rent` | int | 월 렌트료 공급가 (원) |
|
|
| `monthly_rent_tax` | int | 월 렌트료 부가세 (원) |
|
|
| `insurance_company` | string(100) | 보험사명 |
|
|
| `insurance_company_tel` | string(20) | 보험사 연락처 |
|
|
|
|
#### 계산 필드 (API 응답에만 포함, 저장 안 함)
|
|
|
|
| 필드 | 계산식 | 설명 |
|
|
|------|--------|------|
|
|
| `log_distance` | `SUM(vehicle_logs.distance_km)` | 운행일지 거리 합계 |
|
|
| `total_mileage` | `mileage + log_distance` | 총 주행거리 |
|
|
|
|
#### Enum 값
|
|
|
|
**ownership_type (소유형태)**:
|
|
|
|
| 값 | 라벨 | UI 배지 색상 |
|
|
|----|------|:----------:|
|
|
| `corporate` | 법인 | 보라 (purple) |
|
|
| `rent` | 렌트 | 파랑 (blue) |
|
|
| `lease` | 리스 | 초록 (green) |
|
|
|
|
**vehicle_type (차종)**:
|
|
|
|
| 값 | 설명 |
|
|
|----|------|
|
|
| `승용차` | 일반 승용차 |
|
|
| `승합차` | 승합차 |
|
|
| `화물차` | 화물차 |
|
|
| `SUV` | SUV |
|
|
|
|
**status (상태)**:
|
|
|
|
| 값 | 라벨 | UI 배지 색상 |
|
|
|----|------|:----------:|
|
|
| `active` | 운행중 | 초록 (green) |
|
|
| `maintenance` | 정비중 | 노랑 (yellow) |
|
|
| `disposed` | 처분 | 빨강 (red) |
|
|
|
|
---
|
|
|
|
### 2.2 VehicleLog (운행기록)
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"logDate": "2026-03-12",
|
|
"vehicleId": 1,
|
|
"plateNumber": "12가 3456",
|
|
"model": "에쿠스",
|
|
"department": "영업부",
|
|
"driverName": "홍길동",
|
|
"tripType": "business",
|
|
"departureType": "office",
|
|
"departureName": "본사",
|
|
"departureAddress": "서울시 강남구 테헤란로 123",
|
|
"arrivalType": "client",
|
|
"arrivalName": "거래처A",
|
|
"arrivalAddress": "경기도 성남시 분당구 판교로 456",
|
|
"distanceKm": 45,
|
|
"note": "거래처방문"
|
|
}
|
|
```
|
|
|
|
#### 필드 설명
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `vehicleId` | int | ✅ | 차량 ID (FK → corporate_vehicles) |
|
|
| `logDate` | date | ✅ | 운행일 |
|
|
| `driverName` | string(50) | ✅ | 운전자명 |
|
|
| `tripType` | enum | ✅ | 운행 용도 |
|
|
| `distanceKm` | int | ✅ | 운행거리 (km, 0 이상) |
|
|
| `department` | string(50) | | 부서 |
|
|
| `departureType` | enum | | 출발지 유형 |
|
|
| `departureName` | string(100) | | 출발지명 |
|
|
| `departureAddress` | string(200) | | 출발지 주소 |
|
|
| `arrivalType` | enum | | 도착지 유형 |
|
|
| `arrivalName` | string(100) | | 도착지명 |
|
|
| `arrivalAddress` | string(200) | | 도착지 주소 |
|
|
| `note` | string(200) | | 비고 |
|
|
|
|
> **참고**: `plateNumber`, `model`은 차량 관계에서 자동 포함된 읽기 전용 필드이다.
|
|
|
|
#### Enum 값
|
|
|
|
**tripType (운행 용도)**:
|
|
|
|
| 값 | 라벨 | UI 배지 색상 |
|
|
|----|------|:----------:|
|
|
| `commute_to` | 출근용 | 초록 (green) |
|
|
| `commute_from` | 퇴근용 | 파랑 (blue) |
|
|
| `business` | 업무용 | 보라 (purple) |
|
|
| `personal` | 비업무 | 회색 (gray) |
|
|
| `commute_round` | 출퇴근 왕복 | 초록 (green) |
|
|
| `business_round` | 업무용 왕복 | 보라 (purple) |
|
|
| `personal_round` | 비업무 왕복 | 회색 (gray) |
|
|
|
|
**departureType / arrivalType (위치 유형)**:
|
|
|
|
| 값 | 라벨 |
|
|
|----|------|
|
|
| `home` | 자택 |
|
|
| `office` | 회사 |
|
|
| `client` | 거래처 |
|
|
| `other` | 기타 |
|
|
|
|
**비고 프리셋 옵션** (버튼으로 빠른 입력):
|
|
|
|
```json
|
|
["거래처방문", "제조시설등", "회의참석", "판촉활동", "교육등"]
|
|
```
|
|
|
|
---
|
|
|
|
### 2.3 VehicleMaintenance (정비이력)
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"date": "2026-03-10",
|
|
"vehicleId": 1,
|
|
"plateNumber": "12가 3456",
|
|
"model": "에쿠스",
|
|
"category": "주유",
|
|
"description": "LPG 충전",
|
|
"amount": 85000,
|
|
"mileage": 17350,
|
|
"vendor": "SK에너지 강남점",
|
|
"memo": null
|
|
}
|
|
```
|
|
|
|
#### 필드 설명
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `vehicleId` | int | ✅ | 차량 ID (FK → corporate_vehicles) |
|
|
| `date` | date | ✅ | 정비일 |
|
|
| `category` | string(20) | ✅ | 카테고리 |
|
|
| `amount` | int | ✅ | 금액 (원, 0 이상) |
|
|
| `description` | string(200) | | 설명 |
|
|
| `mileage` | int | | 정비 시 주행거리 (입력 시 차량 mileage 자동 갱신) |
|
|
| `vendor` | string(100) | | 업체명 |
|
|
| `memo` | text | | 메모 |
|
|
|
|
#### 카테고리 목록
|
|
|
|
| 카테고리 | 아이콘 | UI 배지 색상 |
|
|
|---------|--------|:----------:|
|
|
| `주유` | Fuel | amber |
|
|
| `정비` | Wrench | blue |
|
|
| `보험` | Shield | emerald |
|
|
| `세차` | Droplets | cyan |
|
|
| `주차` | ParkingCircle | purple |
|
|
| `통행료` | Route | orange |
|
|
| `검사` | ClipboardCheck | indigo |
|
|
| `기타` | MoreHorizontal | gray |
|
|
|
|
---
|
|
|
|
## 3. 차량목록 API
|
|
|
|
### 3.1 차량 목록 조회
|
|
|
|
```
|
|
GET /api/v1/corporate-vehicles
|
|
```
|
|
|
|
**쿼리 파라미터**:
|
|
|
|
| 파라미터 | 타입 | 기본값 | 설명 |
|
|
|---------|------|-------|------|
|
|
| `ownership_type` | string | `all` | `corporate` / `rent` / `lease` / `all` |
|
|
| `vehicle_type` | string | `all` | 승용차 / 승합차 / 화물차 / SUV / `all` |
|
|
| `status` | string | `all` | `active` / `maintenance` / `disposed` / `all` |
|
|
| `search` | string | | 차량번호, 모델, 운전자 검색 |
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"plate_number": "12가 3456",
|
|
"model": "에쿠스",
|
|
"vehicle_type": "승용차",
|
|
"ownership_type": "corporate",
|
|
"year": 2024,
|
|
"driver": "홍길동",
|
|
"status": "active",
|
|
"mileage": 15000,
|
|
"memo": null,
|
|
"purchase_date": "2024-01-15",
|
|
"purchase_price": 85000000,
|
|
"log_distance": 2350,
|
|
"total_mileage": 17350
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3.2 차량 등록
|
|
|
|
```
|
|
POST /api/v1/corporate-vehicles
|
|
```
|
|
|
|
**요청 Body**:
|
|
|
|
```json
|
|
{
|
|
"plate_number": "12가 3456",
|
|
"model": "에쿠스",
|
|
"vehicle_type": "승용차",
|
|
"ownership_type": "corporate",
|
|
"year": 2024,
|
|
"driver": "홍길동",
|
|
"status": "active",
|
|
"mileage": 15000,
|
|
"memo": "대표이사 전용",
|
|
"purchase_date": "2024-01-15",
|
|
"purchase_price": 85000000
|
|
}
|
|
```
|
|
|
|
**유효성 검증**:
|
|
|
|
| 필드 | 규칙 |
|
|
|------|------|
|
|
| `plate_number` | required, string, max:20 |
|
|
| `model` | required, string, max:100 |
|
|
| `vehicle_type` | required, string, max:20 |
|
|
| `ownership_type` | required, in:corporate,rent,lease |
|
|
|
|
**응답** (201):
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "차량이 등록되었습니다.",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
### 3.3 차량 상세
|
|
|
|
```
|
|
GET /api/v1/corporate-vehicles/{id}
|
|
```
|
|
|
|
### 3.4 차량 수정
|
|
|
|
```
|
|
PUT /api/v1/corporate-vehicles/{id}
|
|
```
|
|
|
|
요청 Body는 등록과 동일. 유효성 검증도 동일.
|
|
|
|
### 3.5 차량 삭제
|
|
|
|
```
|
|
DELETE /api/v1/corporate-vehicles/{id}
|
|
```
|
|
|
|
SoftDelete 적용 (복구 가능).
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "차량이 삭제되었습니다."
|
|
}
|
|
```
|
|
|
|
### 3.6 차량 드롭다운 목록
|
|
|
|
```
|
|
GET /api/v1/corporate-vehicles/dropdown
|
|
```
|
|
|
|
차량일지, 정비이력에서 차량 선택 드롭다운에 사용. 간소화된 필드만 반환.
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{ "id": 1, "plate_number": "12가 3456", "model": "에쿠스" },
|
|
{ "id": 2, "plate_number": "56나 7890", "model": "스타리아" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 차량일지 API
|
|
|
|
### 4.1 운행기록 목록
|
|
|
|
```
|
|
GET /api/v1/vehicle-logs
|
|
```
|
|
|
|
**쿼리 파라미터**:
|
|
|
|
| 파라미터 | 타입 | 기본값 | 설명 |
|
|
|---------|------|-------|------|
|
|
| `vehicle_id` | int | `all` | 차량 ID |
|
|
| `year` | int | 현재년 | 연도 |
|
|
| `month` | int | 현재월 | 월 |
|
|
| `trip_type` | string | `all` | 운행 용도 |
|
|
| `search` | string | | 운전자, 부서, 출발지, 도착지, 비고 검색 |
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"logDate": "2026-03-12",
|
|
"vehicleId": 1,
|
|
"plateNumber": "12가 3456",
|
|
"model": "에쿠스",
|
|
"department": "영업부",
|
|
"driverName": "홍길동",
|
|
"tripType": "business",
|
|
"departureType": "office",
|
|
"departureName": "본사",
|
|
"departureAddress": "서울시 강남구 테헤란로 123",
|
|
"arrivalType": "client",
|
|
"arrivalName": "거래처A",
|
|
"arrivalAddress": "경기도 성남시 분당구 판교로 456",
|
|
"distanceKm": 45,
|
|
"note": "거래처방문"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
> **참고**: 응답 필드명은 camelCase를 사용한다 (MNG 기존 패턴 유지).
|
|
|
|
### 4.2 운행기록 등록
|
|
|
|
```
|
|
POST /api/v1/vehicle-logs
|
|
```
|
|
|
|
**요청 Body**:
|
|
|
|
```json
|
|
{
|
|
"vehicle_id": 1,
|
|
"log_date": "2026-03-12",
|
|
"department": "영업부",
|
|
"driver_name": "홍길동",
|
|
"trip_type": "business",
|
|
"departure_type": "office",
|
|
"departure_name": "본사",
|
|
"departure_address": "서울시 강남구 테헤란로 123",
|
|
"arrival_type": "client",
|
|
"arrival_name": "거래처A",
|
|
"arrival_address": "경기도 성남시 분당구 판교로 456",
|
|
"distance_km": 45,
|
|
"note": "거래처방문"
|
|
}
|
|
```
|
|
|
|
**유효성 검증**:
|
|
|
|
| 필드 | 규칙 |
|
|
|------|------|
|
|
| `vehicle_id` | required, exists:corporate_vehicles,id |
|
|
| `log_date` | required, date |
|
|
| `driver_name` | required, string, max:50 |
|
|
| `trip_type` | required, in:commute_to,commute_from,business,personal,commute_round,business_round,personal_round |
|
|
| `distance_km` | required, integer, min:0 |
|
|
|
|
**응답** (201):
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "운행기록이 등록되었습니다.",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
### 4.3 운행기록 상세
|
|
|
|
```
|
|
GET /api/v1/vehicle-logs/{id}
|
|
```
|
|
|
|
### 4.4 운행기록 수정
|
|
|
|
```
|
|
PUT /api/v1/vehicle-logs/{id}
|
|
```
|
|
|
|
요청 Body/유효성 검증은 등록과 동일.
|
|
|
|
### 4.5 운행기록 삭제
|
|
|
|
```
|
|
DELETE /api/v1/vehicle-logs/{id}
|
|
```
|
|
|
|
### 4.6 월별 용도별 통계
|
|
|
|
```
|
|
GET /api/v1/vehicle-logs/summary
|
|
```
|
|
|
|
**쿼리 파라미터**:
|
|
|
|
| 파라미터 | 타입 | 설명 |
|
|
|---------|------|------|
|
|
| `vehicle_id` | int | 차량 ID (생략 시 전체) |
|
|
| `year` | int | 연도 |
|
|
| `month` | int | 월 |
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"byType": {
|
|
"commute_to": { "label": "출근용", "count": 5, "distance": 125 },
|
|
"commute_from": { "label": "퇴근용", "count": 5, "distance": 130 },
|
|
"business": { "label": "업무용", "count": 10, "distance": 280 },
|
|
"personal": { "label": "비업무", "count": 2, "distance": 45 }
|
|
},
|
|
"total": {
|
|
"count": 22,
|
|
"distance": 580
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 정비이력 API
|
|
|
|
### 5.1 정비이력 목록
|
|
|
|
```
|
|
GET /api/v1/vehicle-maintenances
|
|
```
|
|
|
|
**쿼리 파라미터**:
|
|
|
|
| 파라미터 | 타입 | 기본값 | 설명 |
|
|
|---------|------|-------|------|
|
|
| `vehicle_id` | int | `all` | 차량 ID |
|
|
| `category` | string | `all` | 카테고리 (주유, 정비, 보험 등) |
|
|
| `start_date` | date | 3개월 전 | 시작일 |
|
|
| `end_date` | date | 오늘 | 종료일 |
|
|
| `search` | string | | 설명, 업체명, 메모 검색 |
|
|
|
|
**응답**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"date": "2026-03-10",
|
|
"vehicleId": 1,
|
|
"plateNumber": "12가 3456",
|
|
"model": "에쿠스",
|
|
"category": "주유",
|
|
"description": "LPG 충전",
|
|
"amount": 85000,
|
|
"mileage": 17350,
|
|
"vendor": "SK에너지 강남점",
|
|
"memo": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 5.2 정비이력 등록
|
|
|
|
```
|
|
POST /api/v1/vehicle-maintenances
|
|
```
|
|
|
|
**요청 Body**:
|
|
|
|
```json
|
|
{
|
|
"vehicle_id": 1,
|
|
"date": "2026-03-10",
|
|
"category": "주유",
|
|
"description": "LPG 충전",
|
|
"amount": 85000,
|
|
"mileage": 17350,
|
|
"vendor": "SK에너지 강남점",
|
|
"memo": null
|
|
}
|
|
```
|
|
|
|
**유효성 검증**:
|
|
|
|
| 필드 | 규칙 |
|
|
|------|------|
|
|
| `vehicle_id` | required, exists:corporate_vehicles,id |
|
|
| `date` | required, date |
|
|
| `category` | required, string, max:20 |
|
|
| `amount` | required, numeric, min:0 |
|
|
|
|
**부수 효과**: `mileage` 값이 있으면 해당 차량의 `corporate_vehicles.mileage`를 자동 갱신한다.
|
|
|
|
**응답** (201):
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "정비 이력이 등록되었습니다.",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
### 5.3 정비이력 상세
|
|
|
|
```
|
|
GET /api/v1/vehicle-maintenances/{id}
|
|
```
|
|
|
|
### 5.4 정비이력 수정
|
|
|
|
```
|
|
PUT /api/v1/vehicle-maintenances/{id}
|
|
```
|
|
|
|
요청 Body/유효성 검증은 등록과 동일. `mileage` 갱신 부수 효과도 동일.
|
|
|
|
### 5.5 정비이력 삭제
|
|
|
|
```
|
|
DELETE /api/v1/vehicle-maintenances/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. UI 구현 가이드
|
|
|
|
### 6.1 차량목록 화면
|
|
|
|
```
|
|
┌─ 페이지 헤더 ──────────────────────
|
|
│ 제목: "차량목록"
|
|
│ 검색 | Excel 다운로드 | 차량 등록 버튼
|
|
│
|
|
├─ 요약 카드 (4열) ──────────────────
|
|
│ 총 차량 | 법인 취득가 | 월 렌트/리스비 | 총 주행거리
|
|
│
|
|
├─ 필터 바 ──────────────────────────
|
|
│ 소유형태: 전체 | 법인 | 렌트 | 리스
|
|
│ 상태: 전체 | 운행중 | 정비중 | 처분
|
|
│
|
|
├─ 차량 목록 테이블 ─────────────────
|
|
│ 차량번호 | 차종/모델 | 소유형태 | 운전자 | 주행거리 | 상태
|
|
│
|
|
├─ 등록/수정 모달 ───────────────────
|
|
│ 차량번호, 모델명, 차종, 소유형태
|
|
│ 연식, 주 운전자, 상태, 메모
|
|
│ ─────────────────────────
|
|
│ [법인] 취득일자, 취득가액
|
|
│ [렌트/리스] 계약일, 렌트사, 계약기간,
|
|
│ 약정주행, 차량가액, 잔존가치, 보증금,
|
|
│ 월렌트료, 부가세, 보험사
|
|
│ ─────────────────────────
|
|
│ [삭제] [취소] [등록/저장]
|
|
└────────────────────────────────────
|
|
```
|
|
|
|
**요약 카드 계산**:
|
|
|
|
| 카드 | 계산식 |
|
|
|------|--------|
|
|
| 총 차량 | 전체 차량 수 |
|
|
| 법인 취득가 | `ownership_type = 'corporate'`인 차량의 `purchase_price` 합계 |
|
|
| 월 렌트/리스비 | `ownership_type in ('rent','lease')`인 차량의 `monthly_rent + monthly_rent_tax` 합계 |
|
|
| 총 주행거리 | 전체 차량의 `total_mileage` 합계 |
|
|
|
|
**조건부 폼 필드**:
|
|
- `ownership_type = "corporate"` → 법인 전용 필드 표시
|
|
- `ownership_type = "rent" or "lease"` → 렌트/리스 전용 필드 표시
|
|
|
|
---
|
|
|
|
### 6.2 차량일지 화면
|
|
|
|
```
|
|
┌─ 페이지 헤더 ──────────────────────
|
|
│ 차량 선택 드롭다운 (현재 주행거리 표시)
|
|
│ 연/월 선택 | CSV 다운로드 | 기록 추가 버튼
|
|
│
|
|
├─ 용도별 통계 카드 ─────────────────
|
|
│ 출근 | 퇴근 | 업무 | 비업무
|
|
│ 건수 + 총 거리(km)
|
|
│
|
|
├─ 운행기록 테이블 ──────────────────
|
|
│ 날짜 | 차량 | 부서/이름 | 용도 | 출발지 | 도착지 | 거리 | 비고
|
|
│
|
|
├─ 등록/수정 모달 ───────────────────
|
|
│ 차량 선택, 날짜, 부서, 운전자, 용도
|
|
│ 출발지: 유형 + 이름 + 주소
|
|
│ 도착지: 유형 + 이름 + 주소
|
|
│ 운행거리(km)
|
|
│ 비고: 프리셋 버튼 + 자유 입력
|
|
│ [삭제] [취소] [등록/저장]
|
|
└────────────────────────────────────
|
|
```
|
|
|
|
**특수 기능 (프론트엔드에서 처리)**:
|
|
|
|
| 기능 | 설명 |
|
|
|------|------|
|
|
| 기록 복사 | 기존 기록을 복제하여 새 날짜로 등록 (API는 일반 POST) |
|
|
| 출발↔도착 교환 | 출발지/도착지 swap + tripType 자동 전환 (`commute_to` ↔ `commute_from`) |
|
|
| 비고 프리셋 | 5개 버튼 클릭 시 비고 필드에 텍스트 입력 |
|
|
|
|
---
|
|
|
|
### 6.3 정비이력 화면
|
|
|
|
```
|
|
┌─ 페이지 헤더 ──────────────────────
|
|
│ 제목: "정비이력"
|
|
│ 새로고침 | CSV 다운로드 | 정비 등록 버튼
|
|
│
|
|
├─ 요약 카드 (4열) ──────────────────
|
|
│ 총 정비비용 | 주유비 | 정비비 | 기타비용
|
|
│
|
|
├─ 필터 영역 ────────────────────────
|
|
│ 기간: 시작일 ~ 종료일 (기본: 최근 3개월)
|
|
│ 카테고리: 전체 | 주유 | 정비 | 보험 | 세차 | 주차 | 통행료 | 검사 | 기타
|
|
│ 차량: 드롭다운 선택
|
|
│ 검색: 설명, 업체명 검색
|
|
│
|
|
├─ 정비이력 테이블 ──────────────────
|
|
│ 날짜 | 차량 | 카테고리 | 설명 | 금액 | 주행거리 | 작업
|
|
│
|
|
├─ 등록/수정 모달 ───────────────────
|
|
│ 차량 선택, 날짜, 카테고리
|
|
│ 설명, 금액, 주행거리, 업체명, 메모
|
|
│ [삭제] [취소] [등록/저장]
|
|
└────────────────────────────────────
|
|
```
|
|
|
|
**요약 카드 계산** (조회된 목록 데이터 기준):
|
|
|
|
| 카드 | 계산식 |
|
|
|------|--------|
|
|
| 총 정비비용 | 전체 `amount` 합계 |
|
|
| 주유비 | `category = '주유'`인 `amount` 합계 |
|
|
| 정비비 | `category = '정비'`인 `amount` 합계 |
|
|
| 기타비용 | 총 정비비용 - 주유비 - 정비비 |
|
|
|
|
---
|
|
|
|
## 7. 차량 사진 API
|
|
|
|
### 7.1 사진 목록 조회
|
|
|
|
```
|
|
GET /api/v1/corporate-vehicles/{id}/photos
|
|
```
|
|
|
|
**응답 예시**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "조회 성공",
|
|
"data": [
|
|
{
|
|
"id": 42,
|
|
"file_name": "차량_전면.jpg",
|
|
"file_path": "1/corporate-vehicles/2026/03/a1b2c3d4e5f6.jpg",
|
|
"file_url": "/api/v1/files/42/download",
|
|
"file_size": 2048576,
|
|
"mime_type": "image/jpeg",
|
|
"created_at": "2026-03-12 15:30:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 7.2 사진 업로드
|
|
|
|
```
|
|
POST /api/v1/corporate-vehicles/{id}/photos
|
|
Content-Type: multipart/form-data
|
|
```
|
|
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
|
|---------|------|:----:|------|
|
|
| `files[]` | file[] | ✅ | 이미지 파일 (다중 업로드) |
|
|
|
|
**제약조건**:
|
|
|
|
| 항목 | 값 |
|
|
|------|------|
|
|
| 최대 보유 수량 | 10장 / 차량 |
|
|
| 허용 확장자 | jpg, jpeg, png, gif, bmp, webp |
|
|
| 파일 크기 제한 | 10MB / 파일 |
|
|
| 동적 max 계산 | `max = 10 - 현재 사진 수` |
|
|
|
|
**응답 예시** (업로드된 파일 목록 반환):
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "등록 성공",
|
|
"data": [
|
|
{
|
|
"id": 43,
|
|
"file_name": "차량_후면.jpg",
|
|
"file_path": "1/corporate-vehicles/2026/03/f6e5d4c3b2a1.jpg",
|
|
"file_url": "/api/v1/files/43/download",
|
|
"file_size": 1536000,
|
|
"mime_type": "image/jpeg",
|
|
"created_at": "2026-03-12 16:00:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**에러 응답** (10장 초과 시):
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "사진은 최대 10장까지 등록할 수 있습니다."
|
|
}
|
|
```
|
|
|
|
### 7.3 사진 삭제
|
|
|
|
```
|
|
DELETE /api/v1/corporate-vehicles/{id}/photos/{fileId}
|
|
```
|
|
|
|
**응답 예시**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "삭제 성공",
|
|
"data": {
|
|
"file_id": 42,
|
|
"deleted": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7.4 UI 구현 가이드 — 사진
|
|
|
|
```
|
|
┌─ 차량 상세/수정 페이지 ───────────────
|
|
│
|
|
├─ 사진 영역 ──────────────────────────
|
|
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
|
|
│ │ 📷 │ │ 📷 │ │ 📷 │ │ + │
|
|
│ │ 사진1 │ │ 사진2 │ │ 사진3 │ │ 추가 │
|
|
│ └──────┘ └──────┘ └──────┘ └──────┘
|
|
│ * 최대 10장 (n/10 표시)
|
|
│ * 사진 클릭 → 확대 보기
|
|
│ * 삭제 버튼 (X) 각 사진에 표시
|
|
│ * 드래그앤드롭 또는 파일 선택으로 업로드
|
|
│
|
|
```
|
|
|
|
**특수 기능**:
|
|
- 다중 파일 선택 지원 (`multiple` attribute)
|
|
- 업로드 전 미리보기 (FileReader API)
|
|
- 남은 업로드 가능 수량 = 10 - 현재 사진 수
|
|
- 업로드 가능 수량 초과 시 파일 선택 차단
|
|
|
|
---
|
|
|
|
## 8. 데이터 관계도
|
|
|
|
```
|
|
corporate_vehicles (차량 마스터)
|
|
│
|
|
├── vehicle_logs (1:N)
|
|
│ 운행기록 → distance_km 합산하여 차량 total_mileage 계산
|
|
│
|
|
├── vehicle_maintenances (1:N)
|
|
│ 정비기록 → mileage 입력 시 차량 mileage 기준값 갱신
|
|
│
|
|
└── files (1:N, polymorphic)
|
|
사진 → document_type='corporate_vehicle', document_id=vehicle.id
|
|
최대 10장, R2 스토리지 저장, Soft Delete
|
|
```
|
|
|
|
```
|
|
총 주행거리 계산:
|
|
total_mileage = corporate_vehicles.mileage (정비 시 갱신되는 기준값)
|
|
+ SUM(vehicle_logs.distance_km) (운행일지 거리 합계)
|
|
```
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [차량목록 기능 상세](../../features/card-vehicle/corporate-vehicles.md)
|
|
- [차량일지 기능 상세](../../features/card-vehicle/vehicle-logs.md)
|
|
- [정비이력 기능 상세](../../features/card-vehicle/vehicle-maintenance.md)
|
|
- [카드/차량관리 모듈 README](../../features/card-vehicle/README.md)
|
|
|
|
---
|
|
|
|
**최종 업데이트**: 2026-03-12
|