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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Items Files",
 *     description="품목 파일 관리 API (절곡도, 시방서, 인정서) - files 테이블 기반"
 * )
 *
 * @OA\Schema(
 *     schema="ItemFileUploadResponse",
 *     type="object",
 *     required={"file_id", "file_type", "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_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\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="파일 삭제 여부 (soft delete)"),
 *     @OA\Property(property="product", ref="#/components/schemas/Product", description="업데이트된 품목 정보")
 * )
 */
class ItemsFileApi
{
    /**
     * 파일 업로드
     *
     * @OA\Post(
     *     path="/api/v1/items/{id}/files",
     *     summary="품목 파일 업로드",
     *     description="품목에 파일을 업로드합니다 (절곡도/시방서/인정서). 파일은 files 테이블에 저장되고, Product에는 file_id가 참조됩니다.
     *
     * **저장 경로**: `storage/app/tenants/{tenant_id}/items/{year}/{month}/{stored_name}`
     *
     * **저장 구조**:
     * - files 테이블: 파일 메타데이터 저장 (display_name, stored_name, file_path, file_size, mime_type 등)
     * - products 테이블: file_id 참조 (bending_diagram, specification_file, certification_file 컬럼)",
     *     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={"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). 최대 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="절곡 타입")
     *                     )
     *                 ),
     *                 @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/{id}/files/{type}",
     *     summary="품목 파일 삭제",
     *     description="품목의 파일을 삭제합니다 (Soft Delete). files 테이블의 deleted_at이 설정되고, products 테이블의 file_id 참조가 null로 변경됩니다.",
     *     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="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() {}
}