feat: Items Files API 개선 - group_id 기반, 동적 field_key 지원

- GET /items/{id}/files 엔드포인트 추가 (파일 목록 조회)
- document_type을 group_id('1')로 변경 (테이블명 대신 코드 기반)
- field_key 제한 해제 (자유롭게 지정 가능)
- 품목 상세 조회 시 files 필드 포함 (field_key별 그룹핑)
- ItemFileUploadRequest FormRequest 추가
- DELETE 라우트 파라미터를 {fileId}로 변경

app/Swagger/v1/ItemsFileApi.php

@@ -5,49 +5,135 @@
 /**
  * @OA\Tag(
  *     name="Items Files",
- *     description="품목 파일 관리 API (절곡도, 시방서, 인정서) - files 테이블 기반"
+ *     description="품목 파일 관리 API - group_id 기반, field_key 동적 지원"
+ * )
+ *
+ * @OA\Schema(
+ *     schema="ItemFile",
+ *     type="object",
+ *     required={"id", "file_name", "file_path"},
+ *
+ *     @OA\Property(property="id", type="integer", example=123, description="파일 ID"),
+ *     @OA\Property(property="file_name", type="string", example="도면_v1.pdf", description="파일명"),
+ *     @OA\Property(property="file_path", type="string", example="1/items/2025/12/a1b2c3d4.pdf", description="파일 경로"),
+ *     @OA\Property(property="file_url", type="string", format="uri", example="https://api.sam.kr/api/v1/files/download/...", description="다운로드 URL"),
+ *     @OA\Property(property="file_size", type="integer", example=102400, description="파일 크기 (bytes)"),
+ *     @OA\Property(property="mime_type", type="string", example="application/pdf", description="MIME 타입"),
+ *     @OA\Property(property="field_key", type="string", example="drawing", description="필드 키"),
+ *     @OA\Property(property="created_at", type="string", format="date-time", example="2025-12-12 10:00:00", description="생성일시")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="ItemFilesGrouped",
+ *     type="object",
+ *     description="field_key별 그룹핑된 파일 목록",
+ *     example={"drawing": {{"id": 10, "file_name": "도면1.pdf", "file_path": "..."}, {"id": 11, "file_name": "도면2.pdf", "file_path": "..."}}, "certificate": {{"id": 12, "file_name": "인증서.pdf", "file_path": "..."}}}
+ * )
+ * @OA\Schema(
+ *     schema="ItemFileUploadRequest",
+ *     type="object",
+ *     required={"field_key", "file"},
+ *
+ *     @OA\Property(property="field_key", type="string", example="drawing", description="필드 키 (자유롭게 지정)"),
+ *     @OA\Property(property="file", type="string", format="binary", description="업로드할 파일 (최대 20MB)"),
+ *     @OA\Property(property="file_id", type="integer", nullable=true, example=123, description="기존 파일 ID (있으면 교체, 없으면 추가)")
  * )
  *
  * @OA\Schema(
  *     schema="ItemFileUploadResponse",
  *     type="object",
- *     required={"file_id", "file_type", "file_url", "file_path", "file_name"},
+ *     required={"file_id", "field_key", "file_url", "file_path", "file_name"},
  *
- *     @OA\Property(property="file_id", type="integer", example=123, description="files 테이블 ID"),
- *     @OA\Property(property="file_type", type="string", enum={"bending_diagram", "specification", "certification"}, example="bending_diagram", description="파일 타입"),
- *     @OA\Property(property="file_url", type="string", format="uri", example="https://api.sam.kr/api/v1/files/download/MjE3L2l0ZW1zLzIwMjUvMTIvYTFiMmMzZDRlNWY2ZzdoOC5wbmc=", description="파일 다운로드 URL"),
- *     @OA\Property(property="file_path", type="string", example="287/items/2025/12/a1b2c3d4e5f6g7h8.png", description="파일 저장 경로"),
- *     @OA\Property(property="file_name", type="string", example="절곡도_V1.jpg", description="원본 파일명"),
+ *     @OA\Property(property="file_id", type="integer", example=123, description="파일 ID"),
+ *     @OA\Property(property="field_key", type="string", example="drawing", description="필드 키"),
+ *     @OA\Property(property="file_url", type="string", format="uri", example="https://api.sam.kr/api/v1/files/download/...", description="다운로드 URL"),
+ *     @OA\Property(property="file_path", type="string", example="1/items/2025/12/a1b2c3d4.pdf", description="파일 경로"),
+ *     @OA\Property(property="file_name", type="string", example="도면_v1.pdf", description="원본 파일명"),
  *     @OA\Property(property="file_size", type="integer", example=102400, description="파일 크기 (bytes)"),
- *     @OA\Property(property="mime_type", type="string", example="image/png", description="MIME 타입"),
- *     @OA\Property(property="product", ref="#/components/schemas/Product", description="업데이트된 품목 정보")
+ *     @OA\Property(property="mime_type", type="string", example="application/pdf", description="MIME 타입"),
+ *     @OA\Property(property="replaced", type="boolean", example=false, description="기존 파일 교체 여부")
  * )
  *
  * @OA\Schema(
  *     schema="ItemFileDeleteResponse",
  *     type="object",
- *     required={"file_type", "deleted"},
+ *     required={"file_id", "deleted"},
  *
- *     @OA\Property(property="file_type", type="string", enum={"bending_diagram", "specification", "certification"}, example="bending_diagram", description="파일 타입"),
- *     @OA\Property(property="deleted", type="boolean", example=true, description="파일 삭제 여부 (soft delete)"),
- *     @OA\Property(property="product", ref="#/components/schemas/Product", description="업데이트된 품목 정보")
+ *     @OA\Property(property="file_id", type="integer", example=123, description="삭제된 파일 ID"),
+ *     @OA\Property(property="deleted", type="boolean", example=true, description="삭제 성공 여부")
  * )
  */
 class ItemsFileApi
 {
+    /**
+     * 파일 목록 조회
+     *
+     * @OA\Get(
+     *     path="/api/v1/items/{id}/files",
+     *     summary="품목 파일 목록 조회",
+     *     description="품목에 등록된 모든 파일을 field_key별로 그룹핑하여 조회합니다. 응답은 field_key를 키로 하고 파일 배열을 값으로 하는 객체입니다.",
+     *     operationId="getItemFiles",
+     *     tags={"Items Files"},
+     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true,
+     *         description="품목 ID",
+     *
+     *         @OA\Schema(type="integer", example=795)
+     *     ),
+     *
+     *     @OA\Parameter(
+     *         name="item_type",
+     *         in="query",
+     *         required=false,
+     *         description="품목 유형 (FG|PT|SM|RM|CS)",
+     *
+     *         @OA\Schema(type="string", enum={"FG", "PT", "SM", "RM", "CS"}, default="FG")
+     *     ),
+     *
+     *     @OA\Parameter(
+     *         name="field_key",
+     *         in="query",
+     *         required=false,
+     *         description="특정 field_key만 조회 (미지정 시 전체)",
+     *
+     *         @OA\Schema(type="string", example="drawing")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="파일 목록 조회 성공",
+     *
+     *         @OA\JsonContent(
+     *
+     *             @OA\Property(property="success", type="boolean", example=true),
+     *             @OA\Property(property="message", type="string", example="조회되었습니다."),
+     *             @OA\Property(property="data", ref="#/components/schemas/ItemFilesGrouped")
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="품목 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
     /**
      * 파일 업로드
      *
      * @OA\Post(
      *     path="/api/v1/items/{id}/files",
      *     summary="품목 파일 업로드",
-     *     description="품목에 파일을 업로드합니다 (절곡도/시방서/인정서). 파일은 files 테이블에 저장되고, Product에는 file_id가 참조됩니다.
+     *     description="품목에 파일을 업로드합니다.
      *
-     * **저장 경로**: `storage/app/tenants/{tenant_id}/items/{year}/{month}/{stored_name}`
+     * **동작 방식**:
+     * - `file_id` 없음 → 새 파일 추가
+     * - `file_id` 있음 → 기존 파일 soft delete 후 새 파일 추가 (교체)
      *
-     * **저장 구조**:
-     * - files 테이블: 파일 메타데이터 저장 (display_name, stored_name, file_path, file_size, mime_type 등)
-     * - products 테이블: file_id 참조 (bending_diagram, specification_file, certification_file 컬럼)",
+     * **저장 경로**: `storage/app/tenants/{tenant_id}/items/{year}/{month}/{stored_name}`",
      *     operationId="uploadItemFile",
      *     tags={"Items Files"},
      *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
@@ -68,14 +154,13 @@ class ItemsFileApi
      *             mediaType="multipart/form-data",
      *
      *             @OA\Schema(
-     *                 required={"type", "file"},
+     *                 required={"field_key", "file"},
      *
      *                 @OA\Property(
-     *                     property="type",
+     *                     property="field_key",
      *                     type="string",
-     *                     enum={"bending_diagram", "specification", "certification"},
-     *                     description="파일 타입",
-     *                     example="bending_diagram"
+     *                     description="필드 키 (자유롭게 지정)",
+     *                     example="drawing"
      *                 ),
      *                 @OA\Property(
      *                     property="file",
@@ -84,38 +169,17 @@ class ItemsFileApi
      *                     description="업로드할 파일 (이미지: jpg,png,gif,svg / 문서: pdf,doc,docx,xls,xlsx,hwp). 최대 20MB"
      *                 ),
      *                 @OA\Property(
-     *                     property="bending_details",
-     *                     type="array",
-     *                     description="절곡 상세 정보 (bending_diagram 타입일 때만)",
-     *
-     *                     @OA\Items(
-     *                         type="object",
-     *                         required={"angle", "length", "type"},
-     *
-     *                         @OA\Property(property="angle", type="number", format="float", example=90, description="절곡 각도"),
-     *                         @OA\Property(property="length", type="number", format="float", example=100.5, description="절곡 길이"),
-     *                         @OA\Property(property="type", type="string", example="V형", description="절곡 타입")
-     *                     )
+     *                     property="file_id",
+     *                     type="integer",
+     *                     nullable=true,
+     *                     description="기존 파일 ID (있으면 교체, 없으면 추가)",
+     *                     example=123
      *                 ),
      *                 @OA\Property(
-     *                     property="certification_number",
+     *                     property="item_type",
      *                     type="string",
-     *                     description="인증번호 (certification 타입일 때만)",
-     *                     example="CERT-2025-001"
-     *                 ),
-     *                 @OA\Property(
-     *                     property="certification_start_date",
-     *                     type="string",
-     *                     format="date",
-     *                     description="인증 시작일 (certification 타입일 때만)",
-     *                     example="2025-01-01"
-     *                 ),
-     *                 @OA\Property(
-     *                     property="certification_end_date",
-     *                     type="string",
-     *                     format="date",
-     *                     description="인증 종료일 (certification 타입일 때만)",
-     *                     example="2026-12-31"
+     *                     description="품목 유형 (FG|PT|SM|RM|CS)",
+     *                     example="FG"
      *                 )
      *             )
      *         )
@@ -134,7 +198,7 @@ class ItemsFileApi
      *     ),
      *
      *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="품목 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
      *     @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
      * )
      */
@@ -144,9 +208,9 @@ public function upload() {}
      * 파일 삭제
      *
      * @OA\Delete(
-     *     path="/api/v1/items/{id}/files/{type}",
+     *     path="/api/v1/items/{id}/files/{fileId}",
      *     summary="품목 파일 삭제",
-     *     description="품목의 파일을 삭제합니다 (Soft Delete). files 테이블의 deleted_at이 설정되고, products 테이블의 file_id 참조가 null로 변경됩니다.",
+     *     description="품목의 특정 파일을 삭제합니다 (Soft Delete).",
      *     operationId="deleteItemFile",
      *     tags={"Items Files"},
      *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
@@ -161,12 +225,21 @@ public function upload() {}
      *     ),
      *
      *     @OA\Parameter(
-     *         name="type",
+     *         name="fileId",
      *         in="path",
      *         required=true,
-     *         description="파일 타입",
+     *         description="파일 ID",
      *
-     *         @OA\Schema(type="string", enum={"bending_diagram", "specification", "certification"}, example="bending_diagram")
+     *         @OA\Schema(type="integer", example=123)
+     *     ),
+     *
+     *     @OA\Parameter(
+     *         name="item_type",
+     *         in="query",
+     *         required=false,
+     *         description="품목 유형 (FG|PT|SM|RM|CS)",
+     *
+     *         @OA\Schema(type="string", enum={"FG", "PT", "SM", "RM", "CS"}, default="FG")
      *     ),
      *
      *     @OA\Response(
@@ -182,8 +255,8 @@ public function upload() {}
      *     ),
      *
      *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     *     @OA\Response(response=404, description="품목 또는 파일 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
      * )
      */
     public function delete() {}
-}
+}