sam-api/app/Http/Controllers/Api/V1/FileController.php

<?php

namespace App\Http\Controllers\Api\V1;

use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Services\FileService;
use Illuminate\Http\Request;

/**
 * @OA\Tag(
 *     name="Files",
 *     description="파일 관리 API"
 * )
 */
class FileController extends Controller
{
    /**
     * @OA\Post(
     *     path="/api/v1/file/upload",
     *     summary="파일 업로드",
     *     description="파일을 업로드합니다.",
     *     tags={"Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *
     *             @OA\Schema(
     *                 type="object",
     *
     *                 @OA\Property(
     *                     property="files[]",
     *                     type="array",
     *
     *                     @OA\Items(type="string", format="binary"),
     *                     description="업로드할 파일들"
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="파일 업로드 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="파일 업로드"),
     *             @OA\Property(
     *                 property="data",
     *                 type="array",
     *
     *                 @OA\Items(
     *                     type="object",
     *
     *                     @OA\Property(property="id", type="integer", example=1),
     *                     @OA\Property(property="filename", type="string", example="document.pdf"),
     *                     @OA\Property(property="path", type="string", example="/uploads/tenant/1/document.pdf"),
     *                     @OA\Property(property="size", type="integer", example=1024)
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=400,
     *         description="파일 업로드 실패",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="파일 업로드에 실패했습니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=413,
     *         description="파일 크기 초과",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="파일 크기가 너무 큽니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=415,
     *         description="지원하지 않는 파일 형식",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="허용되지 않는 파일 형식입니다.")
     *         )
     *     )
     * )
     */
    public function upload(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return FileService::uploadFiles($request->all());
        }, '파일 업로드');
    }

    /**
     * @OA\Get(
     *     path="/api/v1/file/list",
     *     summary="파일 목록 조회",
     *     description="파일 목록을 조회합니다.",
     *     tags={"Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="page",
     *         in="query",
     *         description="페이지 번호",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Parameter(
     *         name="size",
     *         in="query",
     *         description="페이지 크기",
     *
     *         @OA\Schema(type="integer", example=10)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="파일 목록 조회 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="파일 목록조회"),
     *             @OA\Property(
     *                 property="data",
     *                 type="object",
     *                 @OA\Property(property="current_page", type="integer", example=1),
     *                 @OA\Property(property="per_page", type="integer", example=10),
     *                 @OA\Property(property="total", type="integer", example=25),
     *                 @OA\Property(
     *                     property="data",
     *                     type="array",
     *
     *                     @OA\Items(
     *                         type="object",
     *
     *                         @OA\Property(property="id", type="integer", example=1),
     *                         @OA\Property(property="filename", type="string", example="document.pdf"),
     *                         @OA\Property(property="path", type="string", example="/uploads/tenant/1/document.pdf"),
     *                         @OA\Property(property="size", type="integer", example=1024),
     *                         @OA\Property(property="uploaded_at", type="string", format="date-time")
     *                     )
     *                 )
     *             )
     *         )
     *     )
     * )
     */
    public function list(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return FileService::getFiles($request->all());
        }, '파일 목록조회');
    }

    /**
     * @OA\Delete(
     *     path="/api/v1/file/delete",
     *     summary="파일 삭제",
     *     description="파일을 삭제합니다.",
     *     tags={"Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(
     *                 property="file_ids",
     *                 type="array",
     *
     *                 @OA\Items(type="integer"),
     *                 example={1, 2, 3}
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="파일 삭제 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="파일 삭제")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=404,
     *         description="파일을 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="파일을 찾을 수 없습니다.")
     *         )
     *     )
     * )
     */
    public function delete(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return FileService::deleteFiles($request->all());
        }, '파일 삭제');
    }

    /**
     * @OA\Get(
     *     path="/api/v1/file/find",
     *     summary="파일 정보 조회",
     *     description="특정 파일의 정보를 조회합니다.",
     *     tags={"Files"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="file_id",
     *         in="query",
     *         required=true,
     *         description="파일 ID",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="파일 정보 조회 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="파일 정보 조회"),
     *             @OA\Property(
     *                 property="data",
     *                 type="object",
     *                 @OA\Property(property="id", type="integer", example=1),
     *                 @OA\Property(property="filename", type="string", example="document.pdf"),
     *                 @OA\Property(property="path", type="string", example="/uploads/tenant/1/document.pdf"),
     *                 @OA\Property(property="size", type="integer", example=1024),
     *                 @OA\Property(property="mime_type", type="string", example="application/pdf"),
     *                 @OA\Property(property="uploaded_at", type="string", format="date-time")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=404,
     *         description="파일을 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="파일을 찾을 수 없습니다.")
     *         )
     *     )
     * )
     */
    public function findFile(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return FileService::findFile($request->all());
        }, '파일 정보 조회');
    }
}