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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="Permission",
 *   description="부서/역할/사용자 단위의 메뉴 권한 매트릭스 조회 API"
 * )
 */

/**
 * =========================
 *  메뉴 매트릭스 스키마
 * =========================
 */

/**
 * @OA\Schema(
 *   schema="MenuMatrixAction",
 *   type="object",
 *
 *   @OA\Property(property="permission_id", type="integer", example=1),
 *   @OA\Property(property="permission_code", type="string", example="menu:16.view"),
 *   @OA\Property(property="guard_name", type="string", example="api"),
 *   @OA\Property(property="state", type="string", enum={"allow","deny","none"}, example="allow"),
 *   @OA\Property(property="is_allowed", type="integer", enum={0,1}, example=1)
 * )
 *
 * @OA\Schema(
 *   schema="MenuMatrixNode",
 *   type="object",
 *
 *   @OA\Property(property="menu_id", type="integer", example=16),
 *   @OA\Property(property="parent_id", type="integer", nullable=true, example=10),
 *   @OA\Property(property="name", type="string", example="스크린 작업"),
 *   @OA\Property(property="path", type="string", example="/tenant/production/screen_work.php"),
 *   @OA\Property(property="type", type="string", example="workflow"),
 *   @OA\Property(
 *     property="actions",
 *     type="object",
 *     @OA\Property(property="view", ref="#/components/schemas/MenuMatrixAction"),
 *     @OA\Property(property="create", ref="#/components/schemas/MenuMatrixAction"),
 *     @OA\Property(property="update", ref="#/components/schemas/MenuMatrixAction"),
 *     @OA\Property(property="delete", ref="#/components/schemas/MenuMatrixAction"),
 *     @OA\Property(property="approve", ref="#/components/schemas/MenuMatrixAction")
 *   ),
 *   @OA\Property(
 *     property="children",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/MenuMatrixNode")
 *   )
 * )
 *
 * @OA\Schema(
 *   schema="MenuMatrixPayload",
 *   type="object",
 *
 *   @OA\Property(
 *     property="actions",
 *     type="array",
 *
 *     @OA\Items(type="string", example="view")
 *   ),
 *
 *   @OA\Property(
 *     property="tree",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/MenuMatrixNode")
 *   )
 * )
 */
class PermissionApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/permissions/departments/{dept_id}/menu-matrix",
     *   summary="부서 메뉴 권한 매트릭스",
     *   description="부서 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
     *   tags={"Permission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="dept_id", in="path", required=true, description="부서 ID", @OA\Schema(type="integer", example=1)),
     *
     *   @OA\Response(
     *     response=200,
     *     description="부서 메뉴 권한 매트릭스 조회 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(
     *
     *           @OA\Property(property="data", ref="#/components/schemas/MenuMatrixPayload")
     *         )
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function deptMenuMatrix() {}

    /**
     * @OA\Get(
     *   path="/api/v1/permissions/roles/{role_id}/menu-matrix",
     *   summary="역할 메뉴 권한 매트릭스",
     *   description="스파티 기본 Role 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
     *   tags={"Permission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="role_id", in="path", required=true, description="역할 ID", @OA\Schema(type="integer", example=3)),
     *
     *   @OA\Response(
     *     response=200,
     *     description="역할 메뉴 권한 매트릭스 조회 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(
     *
     *           @OA\Property(property="data", ref="#/components/schemas/MenuMatrixPayload")
     *         )
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function roleMenuMatrix() {}

    /**
     * @OA\Get(
     *   path="/api/v1/permissions/users/{user_id}/menu-matrix",
     *   summary="사용자 메뉴 권한 매트릭스",
     *   description="사용자 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
     *   tags={"Permission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="user_id", in="path", required=true, description="사용자 ID", @OA\Schema(type="integer", example=12)),
     *
     *   @OA\Response(
     *     response=200,
     *     description="유저 메뉴 권한 매트릭스 조회 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(
     *
     *           @OA\Property(property="data", ref="#/components/schemas/MenuMatrixPayload")
     *         )
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="사용자 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function userMenuMatrix() {}
}