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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Items Files",
 *     description="품목 파일 관리 API (절곡도, 시방서, 인정서)"
 * )
 *
 * @OA\Schema(
 *     schema="ItemFileUploadResponse",
 *     type="object",
 *     required={"file_type", "file_url", "file_path", "file_name"},
 *
 *     @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="http://api.sam.kr/storage/items/P-001/bending_diagram/abc123.jpg", description="파일 URL"),
 *     @OA\Property(property="file_path", type="string", example="items/P-001/bending_diagram/abc123.jpg", description="파일 경로"),
 *     @OA\Property(property="file_name", type="string", example="절곡도_V1.jpg", description="원본 파일명"),
 *     @OA\Property(property="product", ref="#/components/schemas/Product", description="업데이트된 품목 정보")
 * )
 *
 * @OA\Schema(
 *     schema="ItemFileDeleteResponse",
 *     type="object",
 *     required={"file_type", "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="파일 삭제 여부"),
 *     @OA\Property(property="product", ref="#/components/schemas/Product", description="업데이트된 품목 정보")
 * )
 */
class ItemsFileApi
{
    /**
     * 파일 업로드
     *
     * @OA\Post(
     *     path="/api/v1/items/{code}/files",
     *     summary="품목 파일 업로드",
     *     description="품목에 파일을 업로드합니다 (절곡도/시방서/인정서)",
     *     operationId="uploadItemFile",
     *     tags={"Items Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="code",
     *         in="path",
     *         required=true,
     *         description="품목 코드",
     *
     *         @OA\Schema(type="string", example="P-001")
     *     ),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *
     *             @OA\Schema(
     *                 required={"type", "file"},
     *
     *                 @OA\Property(
     *                     property="type",
     *                     type="string",
     *                     enum={"bending_diagram", "specification", "certification"},
     *                     description="파일 타입",
     *                     example="bending_diagram"
     *                 ),
     *                 @OA\Property(
     *                     property="file",
     *                     type="string",
     *                     format="binary",
     *                     description="업로드할 파일 (절곡도: jpg,png,gif,svg / 문서: pdf,doc,docx,xls,xlsx,hwp)"
     *                 ),
     *                 @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="절곡 타입")
     *                     )
     *                 ),
     *
     *                 @OA\Property(
     *                     property="certification_number",
     *                     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"
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @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="존재하지 않는 URI 또는 데이터", @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/{code}/files/{type}",
     *     summary="품목 파일 삭제",
     *     description="품목의 파일을 삭제합니다",
     *     operationId="deleteItemFile",
     *     tags={"Items Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="code",
     *         in="path",
     *         required=true,
     *         description="품목 코드",
     *
     *         @OA\Schema(type="string", example="P-001")
     *     ),
     *
     *     @OA\Parameter(
     *         name="type",
     *         in="path",
     *         required=true,
     *         description="파일 타입",
     *
     *         @OA\Schema(type="string", enum={"bending_diagram", "specification", "certification"}, example="bending_diagram")
     *     ),
     *
     *     @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="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function delete() {}
}