<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="RolePermission",
 *   description="역할-퍼미션 매핑(조회/부여/회수/동기화/매트릭스/토글)"
 * )
 */

/**
 * @OA\Schema(
 *   schema="PermissionBrief",
 *   type="object",
 *   description="퍼미션 요약",
 *   required={"id","name","guard_name"},
 *
 *   @OA\Property(property="id", type="integer", example=15),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="name", type="string", example="menu:101.view"),
 *   @OA\Property(property="guard_name", type="string", example="api"),
 *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-16 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-16 10:00:00")
 * )
 *
 * @OA\Schema(
 *   schema="PermissionList",
 *   type="array",
 *
 *   @OA\Items(ref="#/components/schemas/PermissionBrief")
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionGrantRequest",
 *   type="object",
 *   description="역할에 퍼미션 부여. 방법 A: permission_names 배열. 방법 B: menus + actions 조합.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.create"})
 *     ),
 *
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101,102}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"view","create","update","delete"})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionRevokeRequest",
 *   type="object",
 *   description="역할에서 퍼미션 회수. 방법 A: permission_names 배열. 방법 B: menus + actions 조합.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.create"})
 *     ),
 *
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"create"})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionSyncRequest",
 *   type="object",
 *   description="역할의 퍼미션을 전달된 목록으로 완전히 교체(동기화). 방법 A 또는 B.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.update"})
 *     ),
 *
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101,102}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"view","update"})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="PermissionMenuTree",
 *   type="object",
 *   description="권한 매트릭스용 메뉴 트리",
 *
 *   @OA\Property(property="menus", type="array",
 *
 *     @OA\Items(type="object",
 *
 *       @OA\Property(property="id", type="integer", example=1),
 *       @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
 *       @OA\Property(property="name", type="string", example="대시보드"),
 *       @OA\Property(property="url", type="string", nullable=true, example="/dashboard"),
 *       @OA\Property(property="icon", type="string", nullable=true, example="dashboard"),
 *       @OA\Property(property="sort_order", type="integer", example=1),
 *       @OA\Property(property="is_active", type="boolean", example=true),
 *       @OA\Property(property="depth", type="integer", example=0),
 *       @OA\Property(property="has_children", type="boolean", example=true)
 *     )
 *   ),
 *   @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"})
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionMatrix",
 *   type="object",
 *   description="역할의 권한 매트릭스",
 *
 *   @OA\Property(property="role", type="object",
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="name", type="string", example="admin"),
 *     @OA\Property(property="description", type="string", nullable=true, example="관리자")
 *   ),
 *   @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"}),
 *   @OA\Property(property="permissions", type="object", description="메뉴ID를 키로 한 권한 맵",
 *     example={"101": {"view": true, "create": true}, "102": {"view": true}},
 *     additionalProperties=true
 *   )
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionToggleRequest",
 *   type="object",
 *   required={"menu_id","permission_type"},
 *
 *   @OA\Property(property="menu_id", type="integer", example=101, description="메뉴 ID"),
 *   @OA\Property(property="permission_type", type="string", example="view", description="권한 유형 (view, create, update, delete, approve, export, manage)")
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionToggleResponse",
 *   type="object",
 *
 *   @OA\Property(property="menu_id", type="integer", example=101),
 *   @OA\Property(property="permission_type", type="string", example="view"),
 *   @OA\Property(property="granted", type="boolean", example=true, description="토글 후 권한 부여 상태")
 * )
 */
class RolePermissionApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할의 퍼미션 목록 조회",
     *   description="해당 역할에 현재 부여된 퍼미션 목록을 반환합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @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/PermissionList"))
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function list() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할에 퍼미션 부여",
     *   description="퍼미션 이름 배열 또는 메뉴ID+액션 조합으로 역할에 권한을 부여합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionGrantRequest")),
     *
     *   @OA\Response(response=200, description="부여 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function grant() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할에서 퍼미션 회수",
     *   description="퍼미션 이름 배열 또는 메뉴ID+액션 조합으로 권한을 회수합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionRevokeRequest")),
     *
     *   @OA\Response(response=200, description="회수 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function revoke() {}

    /**
     * @OA\Put(
     *   path="/api/v1/roles/{id}/permissions/sync",
     *   summary="역할의 퍼미션 동기화(교체)",
     *   description="전달된 목록으로 역할의 권한을 완전히 교체합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionSyncRequest")),
     *
     *   @OA\Response(response=200, description="동기화 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function sync() {}

    /**
     * @OA\Get(
     *   path="/api/v1/role-permissions/menus",
     *   summary="권한 매트릭스용 메뉴 트리 조회",
     *   description="활성 메뉴를 플랫 배열(depth 포함)로 반환하고, 사용 가능한 권한 유형 목록을 함께 반환합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PermissionMenuTree"))
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function menus() {}

    /**
     * @OA\Get(
     *   path="/api/v1/roles/{id}/permissions/matrix",
     *   summary="역할의 권한 매트릭스 조회",
     *   description="해당 역할에 부여된 메뉴별 권한 매트릭스를 반환합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @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/RolePermissionMatrix"))
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function matrix() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions/toggle",
     *   summary="특정 메뉴의 특정 권한 토글",
     *   description="지정한 메뉴+권한 유형의 부여 상태를 반전합니다. 하위 메뉴에 재귀적으로 전파합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionToggleRequest")),
     *
     *   @OA\Response(response=200, description="토글 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/RolePermissionToggleResponse"))
     *       }
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function toggle() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions/allow-all",
     *   summary="모든 권한 허용",
     *   description="해당 역할에 모든 활성 메뉴의 모든 권한 유형을 일괄 부여합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function allowAll() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions/deny-all",
     *   summary="모든 권한 거부",
     *   description="해당 역할의 모든 메뉴 권한을 일괄 제거합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function denyAll() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions/reset",
     *   summary="기본 권한으로 초기화 (view만 허용)",
     *   description="해당 역할의 모든 권한을 제거한 후, 모든 활성 메뉴에 view 권한만 부여합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function reset() {}
}
