From 0e6d4e6adf403870916faaae23da5e01b67187f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?=
 <lightone2017@codebridge-x.com>
Date: Thu, 12 Mar 2026 22:26:40 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20[vehicle]=20=EC=B0=A8=EB=9F=89=20?=
 =?UTF-8?q?=EC=82=AC=EC=A7=84=20API=20=EB=AC=B8=EC=84=9C=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- vehicle-api.md에 사진 API 3개 엔드포인트 추가 (섹션 7)
- corporate-vehicles.md에 사진 이관 현황 및 엔드포인트 추가
---
 features/card-vehicle/corporate-vehicles.md |   9 +-
 frontend/api-specs/vehicle-api.md           | 134 +++++++++++++++++++-
 2 files changed, 138 insertions(+), 5 deletions(-)

diff --git a/features/card-vehicle/corporate-vehicles.md b/features/card-vehicle/corporate-vehicles.md
index fdc9d6a..46906a0 100644
--- a/features/card-vehicle/corporate-vehicles.md
+++ b/features/card-vehicle/corporate-vehicles.md
@@ -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 검증
diff --git a/frontend/api-specs/vehicle-api.md b/frontend/api-specs/vehicle-api.md
index 1941db2..5adeb8c 100644
--- a/frontend/api-specs/vehicle-api.md
+++ b/frontend/api-specs/vehicle-api.md
@@ -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
 ```
 
 ```