sam-api/app/Swagger/v1/ItemsFileApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Items 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", "field_key", "file_url", "file_path", "file_name"},
 *
 *     @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="application/pdf", description="MIME 타입"),
 *     @OA\Property(property="replaced", type="boolean", example=false, description="기존 파일 교체 여부")
 * )
 *
 * @OA\Schema(
 *     schema="ItemFileDeleteResponse",
 *     type="object",
 *     required={"file_id", "deleted"},
 *
 *     @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="품목에 파일을 업로드합니다.
     *
     * **동작 방식**:
     * - `file_id` 없음 → 새 파일 추가
     * - `file_id` 있음 → 기존 파일 soft delete 후 새 파일 추가 (교체)
     *
     * **저장 경로**: `storage/app/tenants/{tenant_id}/items/{year}/{month}/{stored_name}`",
     *     operationId="uploadItemFile",
     *     tags={"Items Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="품목 ID",
     *
     *         @OA\Schema(type="integer", example=795)
     *     ),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *
     *             @OA\Schema(
     *                 required={"field_key", "file"},
     *
     *                 @OA\Property(
     *                     property="field_key",
     *                     type="string",
     *                     description="필드 키 (자유롭게 지정)",
     *                     example="drawing"
     *                 ),
     *                 @OA\Property(
     *                     property="file",
     *                     type="string",
     *                     format="binary",
     *                     description="업로드할 파일 (이미지: jpg,png,gif,svg / 문서: pdf,doc,docx,xls,xlsx,hwp). 최대 20MB"
     *                 ),
     *                 @OA\Property(
     *                     property="file_id",
     *                     type="integer",
     *                     nullable=true,
     *                     description="기존 파일 ID (있으면 교체, 없으면 추가)",
     *                     example=123
     *                 ),
     *                 @OA\Property(
     *                     property="item_type",
     *                     type="string",
     *                     description="품목 유형 (FG|PT|SM|RM|CS)",
     *                     example="FG"
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @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/ItemFileUploadResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @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"))
     * )
     */
    public function upload() {}

    /**
     * 파일 삭제
     *
     * @OA\Delete(
     *     path="/api/v1/items/{id}/files/{fileId}",
     *     summary="품목 파일 삭제",
     *     description="품목의 특정 파일을 삭제합니다 (Soft Delete).",
     *     operationId="deleteItemFile",
     *     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="fileId",
     *         in="path",
     *         required=true,
     *         description="파일 ID",
     *
     *         @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(
     *         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/ItemFileDeleteResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="품목 또는 파일 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function delete() {}
}