refactor: [authz] 역할/권한 API 품질 개선
- Validator::make를 FormRequest로 분리 (6개 생성) - 하드코딩 한글 문자열을 i18n 키로 교체 - RoleMenuPermission 데드코드 제거 - Role 모델 SpatieRole 상속으로 일원화 - 권한 변경 후 캐시 무효화 추가 (AccessService::bumpVersion) - 미문서화 8개 Swagger 엔드포인트 추가 - 역할/권한 라우트에 perm.map+permission 미들웨어 추가
This commit is contained in:
김보곤
@@ -3,7 +3,7 @@
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Role", description="역할 관리(목록/조회/등록/수정/삭제)")
|
||||
* @OA\Tag(name="Role", description="역할 관리(목록/조회/등록/수정/삭제/통계/활성)")
|
||||
*/
|
||||
|
||||
/**
|
||||
@@ -18,6 +18,9 @@
|
||||
* @OA\Property(property="name", type="string", example="menu-manager"),
|
||||
* @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
|
||||
* @OA\Property(property="guard_name", type="string", example="api"),
|
||||
* @OA\Property(property="is_hidden", type="boolean", example=false),
|
||||
* @OA\Property(property="permissions_count", type="integer", example=12),
|
||||
* @OA\Property(property="users_count", type="integer", example=3),
|
||||
* @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")
|
||||
* )
|
||||
@@ -47,7 +50,8 @@
|
||||
* required={"name"},
|
||||
*
|
||||
* @OA\Property(property="name", type="string", example="menu-manager", description="역할명(테넌트+가드 내 고유)"),
|
||||
* @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할")
|
||||
* @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
|
||||
* @OA\Property(property="is_hidden", type="boolean", example=false, description="숨김 여부")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
@@ -55,7 +59,19 @@
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="name", type="string", example="menu-admin"),
|
||||
* @OA\Property(property="description", type="string", nullable=true, example="설명 변경")
|
||||
* @OA\Property(property="description", type="string", nullable=true, example="설명 변경"),
|
||||
* @OA\Property(property="is_hidden", type="boolean", example=false)
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="RoleStats",
|
||||
* type="object",
|
||||
* description="역할 통계",
|
||||
*
|
||||
* @OA\Property(property="total", type="integer", example=5),
|
||||
* @OA\Property(property="visible", type="integer", example=3),
|
||||
* @OA\Property(property="hidden", type="integer", example=2),
|
||||
* @OA\Property(property="with_users", type="integer", example=4)
|
||||
* )
|
||||
*/
|
||||
class RoleApi
|
||||
@@ -64,13 +80,14 @@ class RoleApi
|
||||
* @OA\Get(
|
||||
* path="/api/v1/roles",
|
||||
* summary="역할 목록 조회",
|
||||
* description="테넌트 범위 내 역할 목록을 페이징으로 반환합니다. (q로 이름/설명 검색)",
|
||||
* description="테넌트 범위 내 역할 목록을 페이징으로 반환합니다. (q로 이름/설명 검색, is_hidden으로 필터)",
|
||||
* tags={"Role"},
|
||||
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
|
||||
* @OA\Parameter(name="size", in="query", required=false, @OA\Schema(type="integer", example=10)),
|
||||
* @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string", example="read")),
|
||||
* @OA\Parameter(name="is_hidden", in="query", required=false, description="숨김 상태 필터", @OA\Schema(type="boolean", example=false)),
|
||||
*
|
||||
* @OA\Response(response=200, description="목록 조회 성공",
|
||||
*
|
||||
@@ -208,4 +225,62 @@ public function update() {}
|
||||
* )
|
||||
*/
|
||||
public function destroy() {}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/roles/stats",
|
||||
* summary="역할 통계 조회",
|
||||
* description="테넌트 범위 내 역할 통계(전체/공개/숨김/사용자 보유)를 반환합니다.",
|
||||
* tags={"Role"},
|
||||
* 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/RoleStats"))
|
||||
* }
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
||||
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function stats() {}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/roles/active",
|
||||
* summary="활성 역할 목록 (드롭다운용)",
|
||||
* description="숨겨지지 않은 활성 역할 목록을 이름순으로 반환합니다. (id, name, description만 포함)",
|
||||
* tags={"Role"},
|
||||
* 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(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\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
||||
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function active() {}
|
||||
}
|
||||
|
||||
@@ -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