SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: [authz] 역할/권한 API 품질 개선

Browse Source 
- Validator::make를 FormRequest로 분리 (6개 생성)
- 하드코딩 한글 문자열을 i18n 키로 교체
- RoleMenuPermission 데드코드 제거
- Role 모델 SpatieRole 상속으로 일원화
- 권한 변경 후 캐시 무효화 추가 (AccessService::bumpVersion)
- 미문서화 8개 Swagger 엔드포인트 추가
- 역할/권한 라우트에 perm.map+permission 미들웨어 추가
This commit is contained in:
김보곤
2026-02-20 21:59:26 +09:00
parent 555fd196f5
commit 1dd9057540
21 changed files with 1400 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
app/Http/Controllers/Api/V1/RoleController.php
View File

@@ -4,28 +4,30 @@
use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Http\Requests\Authz\RoleIndexRequest;
use App\Http\Requests\Authz\RoleStoreRequest;
use App\Http\Requests\Authz\RoleUpdateRequest;
use App\Services\Authz\RoleService;
use Illuminate\Http\Request;
class RoleController extends Controller
{
/**
* 역할 목록 조회
*/
public function index(Request $request)
public function index(RoleIndexRequest $request)
{
return ApiResponse::handle(function () use ($request) {
return RoleService::index($request->all());
return RoleService::index($request->validated());
}, __('message.fetched'));
}
/**
* 역할 생성
*/
public function store(Request $request)
public function store(RoleStoreRequest $request)
{
return ApiResponse::handle(function () use ($request) {
return RoleService::store($request->all());
return RoleService::store($request->validated());
}, __('message.created'));
}
@@ -42,10 +44,10 @@ public function show($id)
/**
* 역할 수정
*/
public function update(Request $request, $id)
public function update(RoleUpdateRequest $request, $id)
{
return ApiResponse::handle(function () use ($request, $id) {
return RoleService::update((int) $id, $request->all());
return RoleService::update((int) $id, $request->validated());
}, __('message.updated'));
}

29
app/Http/Controllers/Api/V1/RolePermissionController.php
View File

@@ -4,37 +4,38 @@
use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Http\Requests\Authz\RolePermissionGrantRequest;
use App\Http\Requests\Authz\RolePermissionToggleRequest;
use App\Services\Authz\RolePermissionService;
use Illuminate\Http\Request;
class RolePermissionController extends Controller
{
public function index($id, Request $request)
public function index($id)
{
return ApiResponse::handle(function () use ($id) {
return RolePermissionService::list((int) $id);
}, '역할 퍼미션 목록 조회');
}, __('message.fetched'));
}
public function grant($id, Request $request)
public function grant($id, RolePermissionGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return RolePermissionService::grant((int) $id, $request->all());
}, '역할 퍼미션 부여');
return RolePermissionService::grant((int) $id, $request->validated());
}, __('message.updated'));
}
public function revoke($id, Request $request)
public function revoke($id, RolePermissionGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return RolePermissionService::revoke((int) $id, $request->all());
}, '역할 퍼미션 회수');
return RolePermissionService::revoke((int) $id, $request->validated());
}, __('message.updated'));
}
public function sync($id, Request $request)
public function sync($id, RolePermissionGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return RolePermissionService::sync((int) $id, $request->all());
}, '역할 퍼미션 동기화');
return RolePermissionService::sync((int) $id, $request->validated());
}, __('message.updated'));
}
/**
@@ -60,10 +61,10 @@ public function matrix($id)
/**
* 특정 메뉴의 특정 권한 토글
*/
public function toggle($id, Request $request)
public function toggle($id, RolePermissionToggleRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return RolePermissionService::toggle((int) $id, $request->all());
return RolePermissionService::toggle((int) $id, $request->validated());
}, __('message.updated'));
}

22
app/Http/Controllers/Api/V1/UserRoleController.php
View File

@@ -4,8 +4,8 @@
use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Http\Requests\Authz\UserRoleGrantRequest;
use App\Services\Authz\UserRoleService;
use Illuminate\Http\Request;
class UserRoleController extends Controller
{
@@ -13,27 +13,27 @@ public function index($id)
{
return ApiResponse::handle(function () use ($id) {
return UserRoleService::list((int) $id);
}, '사용자의 역할 목록 조회');
}, __('message.fetched'));
}
public function grant($id, Request $request)
public function grant($id, UserRoleGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return UserRoleService::grant((int) $id, $request->all());
}, '사용자에게 역할 부여');
return UserRoleService::grant((int) $id, $request->validated());
}, __('message.updated'));
}
public function revoke($id, Request $request)
public function revoke($id, UserRoleGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return UserRoleService::revoke((int) $id, $request->all());
}, '사용자의 역할 회수');
return UserRoleService::revoke((int) $id, $request->validated());
}, __('message.updated'));
}
public function sync($id, Request $request)
public function sync($id, UserRoleGrantRequest $request)
{
return ApiResponse::handle(function () use ($id, $request) {
return UserRoleService::sync((int) $id, $request->all());
}, '사용자의 역할 동기화');
return UserRoleService::sync((int) $id, $request->validated());
}, __('message.updated'));
}
}

23
app/Http/Requests/Authz/RoleIndexRequest.php Normal file
View File

@@ -0,0 +1,23 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
class RoleIndexRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'page' => 'sometimes|integer|min:1',
'size' => 'sometimes|integer|min:1|max:100',
'q' => 'sometimes|nullable|string|max:100',
'is_hidden' => 'sometimes|boolean',
];
}
}

38
app/Http/Requests/Authz/RolePermissionGrantRequest.php Normal file
View File

@@ -0,0 +1,38 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
class RolePermissionGrantRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'permission_names' => 'sometimes|array',
'permission_names.*' => 'string|min:1',
'menus' => 'sometimes|array',
'menus.*' => 'integer|min:1',
'actions' => 'sometimes|array',
'actions.*' => [
'string', Rule::in(config('authz.menu_actions', ['view', 'create', 'update', 'delete', 'approve'])),
],
];
}
public function withValidator($validator): void
{
$validator->after(function ($validator) {
$data = $this->all();
if (empty($data['permission_names']) && (empty($data['menus']) || empty($data['actions']))) {
$validator->errors()->add('permission_names', __('error.role.permission_input_required'));
}
});
}
}

24
app/Http/Requests/Authz/RolePermissionToggleRequest.php Normal file
View File

@@ -0,0 +1,24 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
class RolePermissionToggleRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
$permissionTypes = config('authz.menu_actions', ['view', 'create', 'update', 'delete', 'approve', 'export', 'manage']);
return [
'menu_id' => 'required|integer|min:1',
'permission_type' => ['required', 'string', Rule::in($permissionTypes)],
];
}
}

31
app/Http/Requests/Authz/RoleStoreRequest.php Normal file
View File

@@ -0,0 +1,31 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
class RoleStoreRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
$tenantId = (int) app('tenant_id');
$guard = 'api';
return [
'name' => [
'required', 'string', 'max:100',
Rule::unique('roles', 'name')->where(fn ($q) => $q
->where('tenant_id', $tenantId)
->where('guard_name', $guard)),
],
'description' => 'nullable|string|max:255',
'is_hidden' => 'sometimes|boolean',
];
}
}

32
app/Http/Requests/Authz/RoleUpdateRequest.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
class RoleUpdateRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
$tenantId = (int) app('tenant_id');
$guard = 'api';
$roleId = (int) $this->route('id');
return [
'name' => [
'sometimes', 'string', 'max:100',
Rule::unique('roles', 'name')
->where(fn ($q) => $q->where('tenant_id', $tenantId)->where('guard_name', $guard))
->ignore($roleId),
],
'description' => 'sometimes|nullable|string|max:255',
'is_hidden' => 'sometimes|boolean',
];
}
}

33
app/Http/Requests/Authz/UserRoleGrantRequest.php Normal file
View File

@@ -0,0 +1,33 @@
<?php
namespace App\Http\Requests\Authz;
use Illuminate\Foundation\Http\FormRequest;
class UserRoleGrantRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'role_names' => 'sometimes|array',
'role_names.*' => 'string|min:1',
'role_ids' => 'sometimes|array',
'role_ids.*' => 'integer|min:1',
];
}
public function withValidator($validator): void
{
$validator->after(function ($validator) {
$data = $this->all();
if (empty($data['role_names']) && empty($data['role_ids'])) {
$validator->errors()->add('role_names', __('error.role.role_input_required'));
}
});
}
}

25
app/Models/Permissions/Role.php
View File

@@ -8,13 +8,13 @@
use App\Models\Tenants\Tenant;
use App\Traits\Auditable;
use App\Traits\BelongsToTenant;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
use Spatie\Permission\Models\Role as SpatieRole;
/**
* @mixin IdeHelperRole
*/
class Role extends Model
class Role extends SpatieRole
{
use Auditable, BelongsToTenant, SoftDeletes;
@@ -34,14 +34,6 @@ class Role extends Model
'tenant_id' => 'integer',
];
/**
* 관계: 메뉴 권한 (다대다)
*/
public function menuPermissions()
{
return $this->hasMany(RoleMenuPermission::class, 'role_id');
}
/**
* 관계: 테넌트
*/
@@ -71,19 +63,6 @@ public function users()
);
}
/**
* 관계: 권한 (role_has_permissions 테이블 통해)
*/
public function permissions()
{
return $this->belongsToMany(
Permission::class,
'role_has_permissions',
'role_id',
'permission_id'
);
}
/**
* 스코프: 공개된 역할만
*/

27
app/Models/Permissions/RoleMenuPermission.php
View File

@@ -1,27 +0,0 @@
<?php
namespace App\Models\Permissions;
use App\Models\Commons\IdeHelperRoleMenuPermission;
use App\Models\Commons\Menu;
use Illuminate\Database\Eloquent\Model;
/**
* @mixin IdeHelperRoleMenuPermission
*/
class RoleMenuPermission extends Model
{
protected $fillable = [
'role_id', 'menu_id', 'access', 'read', 'write', 'export', 'approve',
];
public function role()
{
return $this->belongsTo(Role::class, 'role_id');
}
public function menu()
{
return $this->belongsTo(Menu::class, 'menu_id');
}
}

121
app/Services/Authz/RolePermissionService.php
View File

@@ -2,10 +2,8 @@
namespace App\Services\Authz;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use App\Models\Permissions\Role;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;
use Spatie\Permission\PermissionRegistrar;
class RolePermissionService
@@ -18,6 +16,13 @@ protected static function setTeam(int $tenantId): void
app(PermissionRegistrar::class)->setPermissionsTeamId($tenantId);
}
/** 권한 캐시 무효화 */
protected static function invalidateCache(int $tenantId): void
{
AccessService::bumpVersion($tenantId);
app(PermissionRegistrar::class)->forgetCachedPermissions();
}
/** 역할 로드 (테넌트/가드 검증) */
protected static function loadRoleOrError(int $roleId, int $tenantId): ?Role
{
@@ -37,7 +42,6 @@ protected static function resolvePermissionNames(int $tenantId, array $params):
$names = [];
if (! empty($params['permission_names']) && is_array($params['permission_names'])) {
// 문자열 배열만 추림
foreach ($params['permission_names'] as $n) {
if (is_string($n) && $n !== '') {
$names[] = trim($n);
@@ -83,7 +87,7 @@ public static function list(int $roleId)
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
@@ -104,37 +108,20 @@ public static function grant(int $roleId, array $params = [])
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
}
// 유효성: 두 방식 중 하나만 요구하진 않지만, 최소 하나는 있어야 함
$v = Validator::make($params, [
'permission_names' => 'sometimes|array',
'permission_names.*' => 'string|min:1',
'menus' => 'sometimes|array',
'menus.*' => 'integer|min:1',
'actions' => 'sometimes|array',
'actions.*' => [
'string', Rule::in(config('authz.menu_actions', ['view', 'create', 'update', 'delete', 'approve'])),
],
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['permission_names']) && (empty($params['menus']) || empty($params['actions']))) {
return ['error' => 'permission_names 또는 menus+actions 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolvePermissionNames($tenantId, $params);
if (empty($names)) {
return ['error' => '유효한 퍼미션이 없습니다.', 'code' => 422];
return ['error' => __('error.role.no_valid_permissions'), 'code' => 422];
}
// Spatie: 이름 배열 부여 OK (teams 컨텍스트 적용됨)
$role->givePermissionTo($names);
self::invalidateCache($tenantId);
return 'success';
}
@@ -145,35 +132,20 @@ public static function revoke(int $roleId, array $params = [])
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'permission_names' => 'sometimes|array',
'permission_names.*' => 'string|min:1',
'menus' => 'sometimes|array',
'menus.*' => 'integer|min:1',
'actions' => 'sometimes|array',
'actions.*' => [
'string', Rule::in(config('authz.menu_actions', ['view', 'create', 'update', 'delete', 'approve'])),
],
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['permission_names']) && (empty($params['menus']) || empty($params['actions']))) {
return ['error' => 'permission_names 또는 menus+actions 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolvePermissionNames($tenantId, $params);
if (empty($names)) {
return ['error' => '유효한 퍼미션이 없습니다.', 'code' => 422];
return ['error' => __('error.role.no_valid_permissions'), 'code' => 422];
}
$role->revokePermissionTo($names);
self::invalidateCache($tenantId);
return 'success';
}
@@ -184,32 +156,16 @@ public static function sync(int $roleId, array $params = [])
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'permission_names' => 'sometimes|array',
'permission_names.*' => 'string|min:1',
'menus' => 'sometimes|array',
'menus.*' => 'integer|min:1',
'actions' => 'sometimes|array',
'actions.*' => [
'string', Rule::in(config('authz.menu_actions', ['view', 'create', 'update', 'delete', 'approve'])),
],
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['permission_names']) && (empty($params['menus']) || empty($params['actions']))) {
return ['error' => 'permission_names 또는 menus+actions 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolvePermissionNames($tenantId, $params); // 존재하지 않으면 생성
// 동기화
$names = self::resolvePermissionNames($tenantId, $params);
$role->syncPermissions($names);
self::invalidateCache($tenantId);
return 'success';
}
@@ -226,7 +182,7 @@ public static function matrix(int $roleId)
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
@@ -276,7 +232,6 @@ public static function menus()
->orderBy('id', 'asc')
->get(['id', 'parent_id', 'name', 'url', 'icon', 'sort_order', 'is_active']);
// 트리 구조를 플랫한 배열로 변환 (depth 정보 포함)
$flatMenus = self::flattenMenuTree($menus->toArray(), null, 0);
return [
@@ -298,7 +253,6 @@ protected static function flattenMenuTree(array $menus, ?int $parentId = null, i
$menu['has_children'] = count(array_filter($menus, fn ($m) => $m['parent_id'] === $menu['id'])) > 0;
$result[] = $menu;
// 자식 메뉴 재귀적으로 추가
$children = self::flattenMenuTree($menus, $menu['id'], $depth + 1);
$result = array_merge($result, $children);
}
@@ -313,15 +267,7 @@ public static function toggle(int $roleId, array $params = [])
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'menu_id' => 'required|integer|min:1',
'permission_type' => ['required', 'string', Rule::in(self::getPermissionTypes())],
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
$menuId = (int) $params['menu_id'];
@@ -345,14 +291,12 @@ public static function toggle(int $roleId, array $params = [])
->exists();
if ($exists) {
// 권한 제거
\Illuminate\Support\Facades\DB::table('role_has_permissions')
->where('role_id', $roleId)
->where('permission_id', $permission->id)
->delete();
$newValue = false;
} else {
// 권한 부여
\Illuminate\Support\Facades\DB::table('role_has_permissions')->insert([
'role_id' => $roleId,
'permission_id' => $permission->id,
@@ -363,6 +307,8 @@ public static function toggle(int $roleId, array $params = [])
// 하위 메뉴에 권한 전파
self::propagateToChildren($roleId, $menuId, $permissionType, $newValue, $tenantId);
self::invalidateCache($tenantId);
return [
'menu_id' => $menuId,
'permission_type' => $permissionType,
@@ -386,7 +332,6 @@ protected static function propagateToChildren(int $roleId, int $parentMenuId, st
]);
if ($value) {
// 권한 부여
$exists = \Illuminate\Support\Facades\DB::table('role_has_permissions')
->where('role_id', $roleId)
->where('permission_id', $permission->id)
@@ -399,14 +344,12 @@ protected static function propagateToChildren(int $roleId, int $parentMenuId, st
]);
}
} else {
// 권한 제거
\Illuminate\Support\Facades\DB::table('role_has_permissions')
->where('role_id', $roleId)
->where('permission_id', $permission->id)
->delete();
}
// 재귀적으로 하위 메뉴 처리
self::propagateToChildren($roleId, $child->id, $permissionType, $value, $tenantId);
}
}
@@ -418,7 +361,7 @@ public static function allowAll(int $roleId)
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
@@ -438,7 +381,6 @@ public static function allowAll(int $roleId)
'tenant_id' => $tenantId,
]);
// 권한 부여
$exists = \Illuminate\Support\Facades\DB::table('role_has_permissions')
->where('role_id', $roleId)
->where('permission_id', $permission->id)
@@ -453,6 +395,8 @@ public static function allowAll(int $roleId)
}
}
self::invalidateCache($tenantId);
return 'success';
}
@@ -463,7 +407,7 @@ public static function denyAll(int $roleId)
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
@@ -491,6 +435,8 @@ public static function denyAll(int $roleId)
}
}
self::invalidateCache($tenantId);
return 'success';
}
@@ -501,7 +447,7 @@ public static function reset(int $roleId)
$role = self::loadRoleOrError($roleId, $tenantId);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
self::setTeam($tenantId);
@@ -522,7 +468,6 @@ public static function reset(int $roleId)
'tenant_id' => $tenantId,
]);
// 권한 부여
$exists = \Illuminate\Support\Facades\DB::table('role_has_permissions')
->where('role_id', $roleId)
->where('permission_id', $permission->id)
@@ -536,6 +481,8 @@ public static function reset(int $roleId)
}
}
self::invalidateCache($tenantId);
return 'success';
}
}

45
app/Services/Authz/RoleService.php
View File

@@ -4,8 +4,6 @@
use App\Models\Permissions\Role;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Spatie\Permission\PermissionRegistrar;
class RoleService
@@ -51,28 +49,13 @@ public static function store(array $params = [])
$tenantId = (int) app('tenant_id');
$userId = app('api_user');
$v = Validator::make($params, [
'name' => [
'required', 'string', 'max:100',
Rule::unique('roles', 'name')->where(fn ($q) => $q
->where('tenant_id', $tenantId)
->where('guard_name', self::$guard)),
],
'description' => 'nullable|string|max:255',
'is_hidden' => 'sometimes|boolean',
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
// Spatie 팀(테넌트) 컨텍스트
app(PermissionRegistrar::class)->setPermissionsTeamId($tenantId);
$role = Role::create([
'tenant_id' => $tenantId,
'guard_name' => self::$guard,
'name' => $v->validated()['name'],
'name' => $params['name'],
'description' => $params['description'] ?? null,
'is_hidden' => $params['is_hidden'] ?? false,
'created_by' => $userId,
@@ -92,7 +75,7 @@ public static function show(int $id)
->find($id);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
return $role;
@@ -109,25 +92,10 @@ public static function update(int $id, array $params = [])
->find($id);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
$v = Validator::make($params, [
'name' => [
'sometimes', 'string', 'max:100',
Rule::unique('roles', 'name')
->where(fn ($q) => $q->where('tenant_id', $tenantId)->where('guard_name', self::$guard))
->ignore($role->id),
],
'description' => 'sometimes|nullable|string|max:255',
'is_hidden' => 'sometimes|boolean',
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
$updateData = $v->validated();
$updateData = $params;
$updateData['updated_by'] = $userId;
$role->fill($updateData)->save();
@@ -146,7 +114,7 @@ public static function destroy(int $id)
->find($id);
if (! $role) {
return ['error' => '역할을 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.not_found'), 'code' => 404];
}
DB::transaction(function () use ($role, $userId) {
@@ -158,6 +126,9 @@ public static function destroy(int $id)
$role->delete();
});
AccessService::bumpVersion($tenantId);
app(PermissionRegistrar::class)->forgetCachedPermissions();
return 'success';
}

80
app/Services/Authz/UserRoleService.php
View File

@@ -3,8 +3,7 @@
namespace App\Services\Authz;
use App\Models\Members\User;
use Illuminate\Support\Facades\Validator;
use Spatie\Permission\Models\Role;
use App\Models\Permissions\Role;
use Spatie\Permission\PermissionRegistrar;
class UserRoleService
@@ -17,6 +16,13 @@ protected static function setTeam(int $tenantId): void
app(PermissionRegistrar::class)->setPermissionsTeamId($tenantId);
}
/** 권한 캐시 무효화 */
protected static function invalidateCache(int $tenantId): void
{
AccessService::bumpVersion($tenantId);
app(PermissionRegistrar::class)->forgetCachedPermissions();
}
/** 유저 로드 (존재 체크) */
protected static function loadUserOrError(int $userId): ?User
{
@@ -54,14 +60,13 @@ protected static function resolveRoleNames(int $tenantId, array $params): array
// 정제
$names = array_values(array_unique(array_filter($names)));
// 존재 확인(필요시 에러 처리 확장 가능)
// 존재 확인
if (! empty($names)) {
$count = Role::query()
Role::query()
->where('tenant_id', $tenantId)
->where('guard_name', self::$guard)
->whereIn('name', $names)
->count();
// if ($count !== count($names)) { ... 필요시 상세 에러 반환 }
}
return $names;
@@ -74,12 +79,11 @@ public static function list(int $userId)
$user = self::loadUserOrError($userId);
if (! $user) {
return ['error' => '사용자를 찾을 수 없습니다.', 'code' => 404];
return ['error' => __('error.role.user_not_found'), 'code' => 404];
}
self::setTeam($tenantId);
// 현재 테넌트의 역할만
$builder = $user->roles()
->where('roles.tenant_id', $tenantId)
->where('roles.guard_name', self::$guard)
@@ -96,30 +100,19 @@ public static function grant(int $userId, array $params = [])
$user = self::loadUserOrError($userId);
if (! $user) {
return ['error' => '사용자를 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'role_names' => 'sometimes|array',
'role_names.*' => 'string|min:1',
'role_ids' => 'sometimes|array',
'role_ids.*' => 'integer|min:1',
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['role_names']) && empty($params['role_ids'])) {
return ['error' => 'role_names 또는 role_ids 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.user_not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolveRoleNames($tenantId, $params);
if (empty($names)) {
return ['error' => '유효한 역할이 없습니다.', 'code' => 422];
return ['error' => __('error.role.no_valid_roles'), 'code' => 422];
}
$user->assignRole($names); // teams 컨텍스트 적용됨
$user->assignRole($names);
self::invalidateCache($tenantId);
return 'success';
}
@@ -131,30 +124,19 @@ public static function revoke(int $userId, array $params = [])
$user = self::loadUserOrError($userId);
if (! $user) {
return ['error' => '사용자를 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'role_names' => 'sometimes|array',
'role_names.*' => 'string|min:1',
'role_ids' => 'sometimes|array',
'role_ids.*' => 'integer|min:1',
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['role_names']) && empty($params['role_ids'])) {
return ['error' => 'role_names 또는 role_ids 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.user_not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolveRoleNames($tenantId, $params);
if (empty($names)) {
return ['error' => '유효한 역할이 없습니다.', 'code' => 422];
return ['error' => __('error.role.no_valid_roles'), 'code' => 422];
}
$user->removeRole($names); // 배열 허용
$user->removeRole($names);
self::invalidateCache($tenantId);
return 'success';
}
@@ -166,32 +148,20 @@ public static function sync(int $userId, array $params = [])
$user = self::loadUserOrError($userId);
if (! $user) {
return ['error' => '사용자를 찾을 수 없습니다.', 'code' => 404];
}
$v = Validator::make($params, [
'role_names' => 'sometimes|array',
'role_names.*' => 'string|min:1',
'role_ids' => 'sometimes|array',
'role_ids.*' => 'integer|min:1',
]);
if ($v->fails()) {
return ['error' => $v->errors()->first(), 'code' => 422];
}
if (empty($params['role_names']) && empty($params['role_ids'])) {
return ['error' => 'role_names 또는 role_ids 중 하나는 필요합니다.', 'code' => 422];
return ['error' => __('error.role.user_not_found'), 'code' => 404];
}
self::setTeam($tenantId);
$names = self::resolveRoleNames($tenantId, $params);
if (empty($names)) {
// 정책상 빈 목록 sync 허용 시: $user->syncRoles([]) 로 전부 제거 가능
return ['error' => '유효한 역할이 없습니다.', 'code' => 422];
return ['error' => __('error.role.no_valid_roles'), 'code' => 422];
}
$user->syncRoles($names);
self::invalidateCache($tenantId);
return 'success';
}
}

83
app/Swagger/v1/RoleApi.php
View File

@@ -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() {}
}

198
app/Swagger/v1/RolePermissionApi.php
View File

@@ -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() {}
}