refactor: [authz] 역할/권한 API 품질 개선
- Validator::make를 FormRequest로 분리 (6개 생성) - 하드코딩 한글 문자열을 i18n 키로 교체 - RoleMenuPermission 데드코드 제거 - Role 모델 SpatieRole 상속으로 일원화 - 권한 변경 후 캐시 무효화 추가 (AccessService::bumpVersion) - 미문서화 8개 Swagger 엔드포인트 추가 - 역할/권한 라우트에 perm.map+permission 미들웨어 추가
This commit is contained in:
김보곤
@@ -5,7 +5,7 @@
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="RolePermission",
|
||||
* description="역할-퍼미션 매핑(조회/부여/회수/동기화)"
|
||||
* description="역할-퍼미션 매핑(조회/부여/회수/동기화/매트릭스/토글)"
|
||||
* )
|
||||
*/
|
||||
|
||||
@@ -96,6 +96,64 @@
|
||||
* )
|
||||
* }
|
||||
* )
|
||||
*
|
||||
* @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
|
||||
{
|
||||
@@ -193,4 +251,142 @@ public function revoke() {}
|
||||
* )
|
||||
*/
|
||||
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() {}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user