# 품목 파일 업로드 기능 구현 체크리스트

**생성일**: 2025-12-05
**상태**: 🔄 진행중

---

## 📋 개요

품목 등록/수정 시 파일 업로드 기능이 누락되어 있음. 백엔드 API는 구현되어 있으나 프론트엔드에서 호출하지 않음.

### 대상 파일 타입

| 타입 | API type 값 | 대상 품목 | 허용 확장자 | 최대 크기 |
|------|------------|----------|------------|----------|
| 절곡/조립 전개도 | `bending_diagram` | PT (BENDING, ASSEMBLY) | jpg,jpeg,png,gif,bmp,svg,webp | 10MB |
| 시방서 | `specification` | FG | pdf,doc,docx,xls,xlsx,hwp | 20MB |
| 인정서 | `certification` | FG | pdf,doc,docx,xls,xlsx,hwp | 20MB |

### 백엔드 API

- **업로드**: `POST /api/v1/items/{id}/files` (multipart/form-data)
- **삭제**: `DELETE /api/v1/items/{id}/files/{type}`

### DB 컬럼 (Product 모델)

```
bending_diagram, bending_details
specification_file, specification_file_name
certification_file, certification_file_name
certification_number, certification_start_date, certification_end_date
```

---

## Phase 1: 프록시 API 수정

- [x] **1.1** `/api/proxy/[...path]/route.ts` multipart/form-data 지원 추가 ✅
  - `executeBackendRequest` 함수에 `isFormData` 파라미터 추가
  - multipart/form-data일 때 FormData 그대로 전달
  - Content-Type 헤더 생략하여 boundary 자동 설정

---

## Phase 2: 파일 업로드 API 함수 생성

- [x] **2.1** `src/lib/api/items.ts`에 파일 업로드/삭제 함수 추가 ✅
  - `uploadItemFile(itemId, file, type, options?)` - 프록시 경유, ID 기반
  - `deleteItemFile(itemId, type)` - 프록시 경유, ID 기반
  - `UploadFileOptions` 인터페이스: certification 필드, bendingDetails 지원
  - 레거시 함수 deprecated 처리

---

## Phase 3: DynamicItemForm 수정 (등록 모드)

- [x] **3.1** `handleFormSubmit` 수정 - 품목 생성 후 파일 업로드 로직 추가 ✅
  - 품목 생성 → ID 반환 → 파일 업로드
  - `types.ts`에 `ItemSaveResult` 인터페이스 추가
  - `create/page.tsx`에서 ID 반환하도록 수정
- [x] **3.2** PT (절곡/조립): `bendingDiagramFile` 업로드 연동 ✅
  - `uploadItemFile(itemId, bendingDiagramFile, 'bending_diagram')` 호출
  - bendingDetails 옵션 지원
- [x] **3.3** FG (제품): `specificationFile`, `certificationFile` 업로드 연동 ✅
  - 시방서: `uploadItemFile(itemId, specificationFile, 'specification')`
  - 인정서: `uploadItemFile(itemId, certificationFile, 'certification', { certificationNumber, ... })`
- [x] **3.4** 에러 처리: 품목은 생성됐는데 파일 업로드 실패 시 처리 ✅
  - 파일 업로드 실패 시 경고 alert 표시
  - 품목 저장은 완료되므로 리다이렉트 진행

---

## Phase 4: DynamicItemForm 수정 (수정 모드)

- [x] **4.1** 기존 파일 정보 로드 및 표시 ✅
  - `edit/page.tsx` `mapApiResponseToFormData`에 파일 필드 추가
  - `bending_diagram`, `specification_file`, `certification_file` 등 매핑
- [x] **4.2** 파일 업로드 (새 파일로 교체) ✅
  - `edit/page.tsx`에서 `itemId` prop 전달
  - 동일한 파일 업로드 로직 적용 (등록/수정 공용)
- [ ] **4.3** 파일 삭제 기능 추가 (DELETE API 호출) - Phase 5로 이동
- [x] **4.4** edit/page.tsx에서 파일 관련 initialData 매핑 ✅

---

## Phase 5: 기존 파일 표시 및 UI 개선

### 5-A. 상세 페이지 파일 표시

- [x] **5.1** `/items/[id]/page.tsx` - `mapApiResponseToItemMaster`에 파일 필드 추가 ✅
  - `bendingDiagram` (전개도 이미지 URL)
  - `specificationFile`, `specificationFileName` (시방서)
  - `certificationFile`, `certificationFileName` (인정서)
  - `certificationNumber`, `certificationStartDate`, `certificationEndDate` (인정 정보)

- [x] **5.2** `ItemDetailClient.tsx` - 파일 표시 UI 추가 ✅
  - PT(절곡/조립): 전개도 이미지 표시 (`<img>` 태그) + 절곡 상세정보 테이블
  - FG(제품): 시방서/인정서 파일명 표시 (Badge + 다운로드 링크)
  - FG(제품): 인정 정보 표시 (인정번호, 유효기간)

### 5-B. 수정 페이지 기존 파일 표시

- [x] **5.3** `DynamicItemForm/index.tsx` - 기존 파일 표시 UI 추가 ✅
  - FG(제품): 기존 시방서/인정서 파일명 표시
  - initialData에서 파일 정보 로드 (useEffect)
  - `getStorageUrl` 헬퍼 함수로 URL 변환

- [x] **5.4** 파일 삭제 버튼 추가 ✅
  - `deleteItemFile` API 호출
  - 삭제 확인 다이얼로그 (confirm)
  - 삭제 중 로딩 상태 표시

### 5-C. 추가 개선 (선택)

- [ ] **5.5** 업로드 진행 상태 표시 (로딩 스피너)
- [ ] **5.6** 파일 크기/확장자 validation (프론트엔드)
- [x] **5.7** 파일 다운로드 링크 추가 ✅ (상세/수정 페이지 모두)

---

## Phase 6: 테스트

- [ ] **6.1** 등록 모드: PT 절곡품 이미지 업로드 테스트
- [ ] **6.2** 등록 모드: PT 조립품 이미지 업로드 테스트
- [ ] **6.3** 등록 모드: FG 시방서/인정서 업로드 테스트
- [ ] **6.4** 수정 모드: 기존 파일 표시 테스트
- [ ] **6.5** 수정 모드: 파일 교체 테스트
- [ ] **6.6** 수정 모드: 파일 삭제 테스트

---

## 참고 파일

### 프론트엔드
- `/src/app/api/proxy/[...path]/route.ts` - 프록시 API
- `/src/lib/api/items.ts` - API 함수
- `/src/components/items/DynamicItemForm/index.tsx` - 메인 폼
- `/src/components/items/ItemForm/BendingDiagramSection.tsx` - 전개도 섹션
- `/src/app/[locale]/(protected)/items/create/page.tsx` - 등록 페이지
- `/src/app/[locale]/(protected)/items/[id]/edit/page.tsx` - 수정 페이지

### 백엔드
- `/app/Http/Controllers/Api/V1/ItemsFileController.php` - 파일 업로드 컨트롤러
- `/app/Http/Requests/ItemsFileUploadRequest.php` - 요청 검증
- `/app/Models/Products/Product.php` - Product 모델

---

## 작업 로그

| 날짜 | 작업 내용 | 완료 |
|------|----------|:----:|
| 2025-12-05 | 체크리스트 생성, 현황 분석 완료 | ✅ |
| 2025-12-05 | Phase 1: 프록시 API multipart/form-data 지원 추가 | ✅ |
| 2025-12-05 | Phase 2: 파일 업로드/삭제 API 함수 생성 | ✅ |
| 2025-12-05 | Phase 3: 등록 모드 파일 업로드 연동 완료 | ✅ |
| 2025-12-05 | Phase 4: 수정 모드 파일 업로드 연동 완료 | ✅ |
| 2025-12-05 | 빌드 테스트 통과 | ✅ |
| 2025-12-05 | Phase 5: 기존 파일 표시 UI 구현 완료 | ✅ |
| | - 상세 페이지: 전개도 이미지, 시방서/인정서 표시 | |
| | - 수정 페이지: 기존 파일 미리보기 + 삭제 기능 | |
| | | |
