docs: [equipment] 사진 API 스펙 업데이트 (GCS→R2)

- 프론트엔드 요청 문서: 사진 업로드 API 상세 스펙 추가
- multipart/form-data files[] 배열 형식 명시
- 검증 규칙, Request/Response 예시 추가
- GCS 언급을 Cloudflare R2로 수정
- features/equipment README 동일 수정

features/equipment/README.md

@@ -355,15 +355,19 @@ equipment/
 
 ### 5.5 설비 사진
 
-- 최대 10장
-- 업로드 시 자동 압축 (MNG에서 구현, API에서는 `File` 모델 연동)
-- GCS(Google Cloud Storage)에 저장
+- 최대 10장 (설비당)
+- Cloudflare R2에 저장 (`Storage::disk('r2')`)
+- 저장 경로: `{tenantId}/equipment/{year}/{month}/{storedName}`
+- 다중 업로드 지원 (`files[]` multipart/form-data)
+- 허용 확장자: jpg, jpeg, png, gif, bmp, webp (최대 10MB/파일)
+- 삭제 시 soft delete (`softDeleteFile()`) 적용
+- MNG는 GCS + 자동 압축, API는 R2 직접 저장
 
 ### 5.6 엑셀 Import (MNG 전용)
 
 - 한글/영문 헤더 자동 매핑
 - 중복 처리: skip 또는 overwrite 선택
-- 엑셀 내 이미지(Drawing) 자동 추출 후 GCS 업로드
+- 엑셀 내 이미지(Drawing) 자동 추출 후 저장 (MNG: GCS, API: R2 예정)
 - API에서는 미구현 (Phase 2+ 검토)
 
 ---

requests/equipment-frontend-request.md

@@ -443,12 +443,83 @@ toggle과 같은 Body + `result` 필드 추가 (`good` / `bad` / `repaired` / `n
 
 #### `GET /v1/equipment/{id}/photos` — 사진 목록
 
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "데이터를 불러왔습니다.",
+  "data": [
+    {
+      "id": 1,
+      "file_name": "IMG_001.jpg",
+      "file_path": "1/equipment/2026/03/a1b2c3d4e5f6g7h8.jpg",
+      "file_url": "/api/v1/files/1/download",
+      "file_size": 524288,
+      "mime_type": "image/jpeg",
+      "created_at": "2026-03-12 10:30:00"
+    }
+  ]
+}
+```
+
 #### `POST /v1/equipment/{id}/photos` — 사진 업로드
 
-> 기존 파일 업로드 API(`/v1/file/upload`)를 사용하여 업로드한 후, 이 엔드포인트로 연결하는 방식. 상세 구현은 기존 파일 업로드 모듈 참고.
+> **multipart/form-data** 형식으로 직접 업로드한다. 별도 파일 업로드 API를 거치지 않는다.
+
+**Request (multipart/form-data):**
+
+| 필드 | 타입 | 필수 | 설명 |
+|------|------|:----:|------|
+| `files[]` | file[] | O | 이미지 파일 배열 (다중 업로드) |
+
+**검증 규칙:**
+- 허용 확장자: `jpg, jpeg, png, gif, bmp, webp`
+- 파일당 최대 크기: 10MB
+- 설비당 최대 사진 수: 10장 (현재 사진 수 + 업로드 수 ≤ 10)
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "사진이 업로드되었습니다.",
+  "data": [
+    {
+      "id": 15,
+      "file_name": "IMG_001.jpg",
+      "file_path": "1/equipment/2026/03/a1b2c3d4e5f6g7h8.jpg",
+      "file_url": "/api/v1/files/15/download",
+      "file_size": 524288,
+      "mime_type": "image/jpeg",
+      "created_at": "2026-03-12 10:30:00"
+    }
+  ]
+}
+```
+
+**프론트엔드 구현 참고:**
+```typescript
+// 다중 파일 업로드 예시
+const formData = new FormData();
+selectedFiles.forEach(file => formData.append('files[]', file));
+await api.post(`/v1/equipment/${id}/photos`, formData, {
+  headers: { 'Content-Type': 'multipart/form-data' }
+});
+```
 
 #### `DELETE /v1/equipment/{id}/photos/{fileId}` — 사진 삭제
 
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "삭제되었습니다.",
+  "data": { "file_id": 15, "deleted": true }
+}
+```
+
 ---
 
 ## 4. 화면별 구현 가이드
@@ -681,9 +752,13 @@ toggle과 같은 Body + `result` 필드 추가 (`good` / `bad` / `repaired` / `n
 
 ### 5.5 설비 사진
 
-- 최대 10장
-- GCS(Google Cloud Storage)에 저장
-- 기존 파일 업로드 모듈 사용
+- 최대 10장 (설비당)
+- Cloudflare R2에 저장 (`Storage::disk('r2')`)
+- `POST /v1/equipment/{id}/photos`로 직접 업로드 (`files[]` multipart)
+- 허용 확장자: jpg, jpeg, png, gif, bmp, webp
+- 파일당 최대 10MB
+- 사진 URL: `/api/v1/files/{id}/download`
+- 삭제 시 soft delete 처리
 
 ---