docs: [vehicle] 차량 사진 API 문서 추가
- vehicle-api.md에 사진 API 3개 엔드포인트 추가 (섹션 7) - corporate-vehicles.md에 사진 이관 현황 및 엔드포인트 추가
This commit is contained in:
김보곤
@@ -170,8 +170,9 @@ CorporateVehicle (1) ← (N) VehicleLog (총 주행거리 합산)
|
||||
|------|:----:|------|
|
||||
| DB 마이그레이션 | ✅ | `api/database/migrations/2026_02_02_220000_create_corporate_vehicles_table.php` |
|
||||
| MNG UI (Blade+React) | ✅ | 운영중 |
|
||||
| API REST 엔드포인트 | ❌ | 미이관 |
|
||||
| API Service/Model | ❌ | 미이관 |
|
||||
| API REST 엔드포인트 | ❌ | 미이관 (사진 API만 구현 완료) |
|
||||
| API Service/Model | 🔶 | 사진: `VehiclePhotoService`, `CorporateVehicle` 모델 구현 완료 |
|
||||
| API 차량 사진 | ✅ | `VehiclePhotoController` + `StoreVehiclePhotoRequest` 구현 완료 |
|
||||
| React UI | ❌ | 미이관 |
|
||||
|
||||
---
|
||||
@@ -187,6 +188,9 @@ POST /api/v1/corporate-vehicles 차량 등록
|
||||
PUT /api/v1/corporate-vehicles/{id} 차량 수정
|
||||
DELETE /api/v1/corporate-vehicles/{id} 차량 삭제 (SoftDelete)
|
||||
GET /api/v1/corporate-vehicles/dropdown 차량 드롭다운 목록 (id, plate_number, model)
|
||||
GET /api/v1/corporate-vehicles/{id}/photos 차량 사진 목록
|
||||
POST /api/v1/corporate-vehicles/{id}/photos 차량 사진 업로드 (최대 10장)
|
||||
DELETE /api/v1/corporate-vehicles/{id}/photos/{fileId} 차량 사진 삭제
|
||||
```
|
||||
|
||||
### 필터 파라미터
|
||||
@@ -205,3 +209,4 @@ GET /api/v1/corporate-vehicles/dropdown 차량 드롭다운 목록 (id, plate
|
||||
3. **options 컬럼**: 현재 미적용. 이관 시 렌트/리스 전용 필드를 options JSON으로 통합 검토
|
||||
4. **Auditable**: API 모델에 `Auditable` trait 적용
|
||||
5. **FormRequest**: `StoreCorporateVehicleRequest`, `UpdateCorporateVehicleRequest` 분리
|
||||
6. **차량 사진**: R2 저장, `document_type='corporate_vehicle'` 다형성 관계, 최대 10장, `StoreVehiclePhotoRequest` 동적 max 검증
|
||||
|
||||
@@ -68,6 +68,9 @@ Authorization: Bearer {token}
|
||||
| 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}` | 차량 사진 삭제 |
|
||||
|
||||
---
|
||||
|
||||
@@ -814,7 +817,128 @@ DELETE /api/v1/vehicle-maintenances/{id}
|
||||
|
||||
---
|
||||
|
||||
## 7. 데이터 관계도
|
||||
## 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 (차량 마스터)
|
||||
@@ -822,8 +946,12 @@ corporate_vehicles (차량 마스터)
|
||||
├── vehicle_logs (1:N)
|
||||
│ 운행기록 → distance_km 합산하여 차량 total_mileage 계산
|
||||
│
|
||||
└── vehicle_maintenances (1:N)
|
||||
정비기록 → mileage 입력 시 차량 mileage 기준값 갱신
|
||||
├── vehicle_maintenances (1:N)
|
||||
│ 정비기록 → mileage 입력 시 차량 mileage 기준값 갱신
|
||||
│
|
||||
└── files (1:N, polymorphic)
|
||||
사진 → document_type='corporate_vehicle', document_id=vehicle.id
|
||||
최대 10장, R2 스토리지 저장, Soft Delete
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user