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

<?php

namespace App\Swagger\v1;

use OpenApi\Annotations as OA;

/**
 * @OA\Tag(name="Folder", description="폴더 관리")
 *
 * ========= 스키마 정의 =========
 *
 * @OA\Schema(
 *   schema="Folder",
 *   type="object",
 *   description="폴더 모델",
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="folder_key", type="string", example="product", description="폴더 키 (영문 소문자, 숫자, 하이픈, 언더스코어만 허용)"),
 *   @OA\Property(property="folder_name", type="string", example="생산관리", description="폴더 표시명"),
 *   @OA\Property(property="description", type="string", nullable=true, example="생산 관련 문서", maxLength=500),
 *   @OA\Property(property="display_order", type="integer", example=1, description="정렬 순서"),
 *   @OA\Property(property="is_active", type="boolean", example=true),
 *   @OA\Property(property="icon", type="string", nullable=true, example="icon-production", maxLength=50),
 *   @OA\Property(property="color", type="string", nullable=true, example="#3B82F6", description="색상 코드 (#RRGGBB 형식)"),
 *   @OA\Property(property="created_by", type="integer", example=1),
 *   @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
 *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-01-01T00:00:00Z"),
 *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-01-01T00:00:00Z")
 * )
 *
 * @OA\Schema(
 *   schema="FolderStoreRequest",
 *   type="object",
 *   required={"folder_key", "folder_name"},
 *   description="폴더 생성 요청",
 *
 *   @OA\Property(property="folder_key", type="string", pattern="^[a-z0-9_-]+$", maxLength=50, example="accounting", description="폴더 키 (영문 소문자, 숫자, 하이픈, 언더스코어만)"),
 *   @OA\Property(property="folder_name", type="string", maxLength=100, example="회계", description="폴더 표시명"),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=500, example="회계 관련 문서"),
 *   @OA\Property(property="display_order", type="integer", nullable=true, minimum=0, example=10, description="정렬 순서 (미지정 시 자동)"),
 *   @OA\Property(property="is_active", type="boolean", nullable=true, example=true),
 *   @OA\Property(property="icon", type="string", nullable=true, maxLength=50, example="icon-accounting"),
 *   @OA\Property(property="color", type="string", nullable=true, pattern="^#[0-9A-Fa-f]{6}$", example="#10B981")
 * )
 *
 * @OA\Schema(
 *   schema="FolderUpdateRequest",
 *   type="object",
 *   description="폴더 수정 요청",
 *
 *   @OA\Property(property="folder_key", type="string", pattern="^[a-z0-9_-]+$", maxLength=50, example="accounting"),
 *   @OA\Property(property="folder_name", type="string", maxLength=100, example="회계"),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=500, example="회계 관련 문서"),
 *   @OA\Property(property="display_order", type="integer", minimum=0, example=5),
 *   @OA\Property(property="is_active", type="boolean", example=true),
 *   @OA\Property(property="icon", type="string", nullable=true, maxLength=50, example="icon-accounting"),
 *   @OA\Property(property="color", type="string", nullable=true, pattern="^#[0-9A-Fa-f]{6}$", example="#10B981")
 * )
 *
 * @OA\Schema(
 *   schema="FolderReorderRequest",
 *   type="object",
 *   required={"orders"},
 *   description="폴더 순서 변경 요청",
 *
 *   @OA\Property(
 *     property="orders",
 *     type="array",
 *     description="폴더 ID와 순서 배열",
 *
 *     @OA\Items(
 *       type="object",
 *       required={"id", "display_order"},
 *
 *       @OA\Property(property="id", type="integer", example=1),
 *       @OA\Property(property="display_order", type="integer", example=0)
 *     ),
 *     example={
 *       {"id": 1, "display_order": 0},
 *       {"id": 2, "display_order": 1},
 *       {"id": 3, "display_order": 2}
 *     }
 *   )
 * )
 */
class FolderApi
{
    /**
     * 폴더 목록 조회
     *
     * @OA\Get(
     *     path="/api/v1/folders",
     *     summary="폴더 목록 조회",
     *     description="테넌트의 모든 폴더를 display_order 순으로 조회합니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="폴더 목록 조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Folder"))
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패")
     * )
     */
    public function index() {}

    /**
     * 폴더 생성
     *
     * @OA\Post(
     *     path="/api/v1/folders",
     *     summary="폴더 생성",
     *     description="새로운 폴더를 생성합니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/FolderStoreRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="폴더 생성 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Folder")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="유효성 검증 실패"),
     *     @OA\Response(response=409, description="중복된 folder_key")
     * )
     */
    public function store() {}

    /**
     * 폴더 상세 조회
     *
     * @OA\Get(
     *     path="/api/v1/folders/{id}",
     *     summary="폴더 상세 조회",
     *     description="폴더 ID로 상세 정보를 조회합니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="폴더 ID",
     *
     *         @OA\Schema(type="integer")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="폴더 조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Folder")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="폴더를 찾을 수 없음")
     * )
     */
    public function show() {}

    /**
     * 폴더 수정
     *
     * @OA\Put(
     *     path="/api/v1/folders/{id}",
     *     summary="폴더 수정",
     *     description="폴더 정보를 수정합니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="폴더 ID",
     *
     *         @OA\Schema(type="integer")
     *     ),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/FolderUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="폴더 수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Folder")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="유효성 검증 실패"),
     *     @OA\Response(response=404, description="폴더를 찾을 수 없음"),
     *     @OA\Response(response=409, description="중복된 folder_key")
     * )
     */
    public function update() {}

    /**
     * 폴더 삭제/비활성화
     *
     * @OA\Delete(
     *     path="/api/v1/folders/{id}",
     *     summary="폴더 삭제",
     *     description="폴더를 비활성화합니다. 파일이 있는 폴더는 삭제할 수 없습니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="폴더 ID",
     *
     *         @OA\Schema(type="integer")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="폴더 삭제 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Folder")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="폴더에 파일이 있어 삭제 불가"),
     *     @OA\Response(response=404, description="폴더를 찾을 수 없음")
     * )
     */
    public function destroy() {}

    /**
     * 폴더 순서 변경
     *
     * @OA\Post(
     *     path="/api/v1/folders/reorder",
     *     summary="폴더 순서 변경",
     *     description="여러 폴더의 표시 순서를 일괄 변경합니다.",
     *     tags={"Folder"},
     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/FolderReorderRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="순서 변경 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Folder"))
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="유효성 검증 실패"),
     *     @OA\Response(response=404, description="일부 폴더를 찾을 수 없음")
     * )
     */
    public function reorder() {}
}