Roles y permisos

Lo que cada persona puede hacer dentro de la aplicación lo deciden sus roles, y lo que puede hacer un rol lo deciden los permisos marcados en él. Esta guía explica la pantalla Roles del panel de administración, cómo llega un rol a una persona y qué roles existen desde el inicio.

Los roles que existen desde el inicio

Tu producto también puede traer un rol inicial pensado para que tú lo repartas. Ese rol no se puede eliminar.

La pantalla Roles

Abre Usuarios → Roles en el panel de administración. La lista muestra cada rol por su nombre. Crear pide un nombre: minúsculas y guiones, como "support-team", que la pantalla muestra como "Support Team". Ya que el rol existe, Editar muestra sus permisos:

• Una cuadrícula con una fila por cada tipo de registro —Usuario, Rol, Anuncio, Registro de comunicación y los demás— y las columnas Crear, Ver, Actualizar y Eliminar. Marca una casilla para dar esa acción sobre ese tipo de registro. Haz clic en el encabezado de una columna para marcar la columna completa, o en el nombre de una fila para marcar la fila completa.
• Debajo, la lista Permisos, con los interruptores que no caben en la cuadrícula, como Contestar ticket o Explorar carpetas de otros usuarios, y los que agregue tu producto.
• Un módulo que está apagado en el producto no aparece ni en la cuadrícula ni en la lista, así que a un rol no se le puede dar algo que no existe. Las filas de planes, complementos y medidores son la excepción: se quedan mientras esos módulos están apagados, y marcarlas no cambia nada hasta que el módulo se enciende.

La acción Clonar de un rol lo copia con todos sus permisos bajo el mismo nombre seguido de "-copia" (luego "-copia-2", y así) y abre la copia para editarla.

Algunas casillas no tienen efecto, porque hay registros que nadie puede crear ni cambiar: los permisos sólo se pueden consultar, y un registro de comunicación sólo se puede consultar o eliminar.

Qué hace cada columna

El panel de administración sólo se abre para quien tiene el rol Administrador, salvo sus pantallas de soporte: Contestar ticket abre la bandeja de soporte y los chats del equipo, y Usar asistente el asistente, para cualquier rol. Quien llega a ellas sin el rol Administrador ve sólo el grupo Soporte del menú del panel. Dentro del panel, algunas pantallas piden más que un permiso: el historial de actividad sólo lo pueden abrir los dueños del producto, y los registros de Evento de seguimiento sólo el rol Administrador.

Darle un rol a una persona

Los roles se dan a las cuentas en Usuarios → Usuarios: el campo Rol del formulario de usuario acepta uno o varios roles, y sólo lo ve un editor que tiene el rol Administrador. Al guardar, la persona recibe una Notificación de actualización de rol que nombra los roles agregados y quitados.

La cuenta de uno de los dueños del producto no se puede eliminar desde esa pantalla.

Los dueños del producto

Los dueños del producto son una lista corta de cuentas escrita dentro del propio producto, no un rol. Reciben el rol Administrador cuando se instala el producto, que es lo que les da su acceso; estar en la lista sólo agrega algunos extras: la Dev Zone, la pantalla Diseño, el historial de actividad, actuar como otro de los dueños y la protección contra ser eliminados. Quitar una cuenta de esa lista quita los extras pero deja el rol Administrador en su lugar. Ve Sudo y superadministradores.

Para desarrolladores

Las piezas

Los roles y permisos están construidos sobre el paquete laravel-permission de Spatie. Los modelos son App\Models\Role y App\Models\Permission, sustituidos a través del bloque models de config/permission.php. Ambos extienden los modelos de Spatie, ambos hacen borrado suave, y ambos registran sus cambios en el registro de actividad. Las tablas son las del paquete por omisión (roles, permissions, model_has_roles, model_has_permissions, role_has_permissions), configuradas en config/permission.php. Todo permiso pertenece al guard web. El name de un rol se guarda como slug — Support Team se vuelve support-team — y el panel lo muestra como título, Support Team, pasado por el traductor.

Las revisiones de permisos se guardan en caché 24 horas. El paquete vacía la caché cuando un rol o permiso se guarda por sus propios métodos, y el panel la vacía otra vez después de editar o clonar un rol.

La convención de nombres

Cada permiso son dos palabras: {acción} {recurso}. La acción es una de create, retrieve, update, delete; el recurso es el singular de la tabla del modelo. El panel parte un permiso por su espacio: la primera palabra elige la columna de la cuadrícula, la segunda la fila, y cada casilla muestra el nombre exacto del permiso al pasar el cursor. Un permiso cuya primera palabra no es una de esas cuatro acciones, como answer ticket o browse media_folder, va a la lista Permisos. Los permisos que trae una instalación nueva:

El primer bloque y las filas de cobro salen de los recursos del panel de administración; los permisos de medios, carpetas, tickets y asistente salen de la clave permissions de abajo. Esos once también los crea una migración, que se los da al rol de administrador, así que un deploy que corre php artisan migrate sin los seeders también los tiene.

Lo que crea el seeder

php artisan db:seed corre, en orden, PermissionSeeder, RoleSeeder, AdminSeeder (las cuentas sudo), UserSeeder (las cuentas default_users), y los tres seeders del catálogo de cobro AddOnSeeder, PlanSeeder y MeterSeeder. Puedes correr cada uno por separado:

php artisan db:seed --class=PermissionSeeder
php artisan db:seed --class=RoleSeeder

PermissionSeeder arma su lista desde dos fuentes, ambas configuradas en el bloque Permissions de config/app.php:

Los permisos se insertan o actualizan por nombre y guard, y un permiso borrado en suave que reaparece en las fuentes se restaura. El descubrimiento lee el mapa de clases de Composer, así que corre composer dump-autoload después de agregar un recurso y antes de sembrar.

// config/app.php
'permissions' => [
    'retrieve media' => 'web',
    // ... el resto de los permisos que trae el kit
    'use assistant' => 'web',
    'export reports' => 'web',
],

RoleSeeder luego se asegura de que existan tres roles:

AdminSeeder asigna admin_role a cada correo de config('app.sudo'). Vuelve a correr los seeders cada vez que agregues un recurso o un permiso propio; son idempotentes.

La pantalla Roles

La pantalla es /admin/roles; los roles se asignan en /admin/users. Un permiso queda fuera de la cuadrícula y de la lista cuando su recurso, la segunda palabra, tiene una política en app/Policies/ cuya configuración requerida está apagada. Las políticas de cobro viven en el paquete, no en app/Policies/, así que sus filas siempre se muestran. RolePolicy impide editar o eliminar el rol de administrador y eliminar el default_role; todo lo demás sigue los permisos de role. UserPolicy prohíbe eliminar una cuenta sudo.

Políticas

Cada recurso está protegido por una política en app/Policies/ que extiende App\Policies\BasePolicy. La clase base necesita una propiedad y mapea los métodos estándar de política a permisos:

class PlanPolicy extends BasePolicy
{
    protected string $name = 'plan';
    protected $requiredConfig = 'features.plans_enabled';
}

Dos ganchos afinan eso:

• $requiredConfig nombra una clave de configuración. Cuando es falsa, before() devuelve false y toda revisión falla, también para el rol de administrador. AnnouncementPolicy usa features.announcements; las políticas de seguimiento usan features.tracking_enabled.
• extraValidation() se combina con AND en cada revisión. Sobrescríbelo para agregar una condición que aplique a todo el recurso.

Laravel resuelve la política por convención: App\Models\Plan queda protegido por App\Policies\PlanPolicy. Un modelo que vive en otro lado se registra a mano en AppServiceProvider::boot() con Gate::policy(Model::class, ModelPolicy::class), como el modelo del registro de actividad.

Las políticas incluidas y en qué se apartan de la tabla:

Proteger tu propio código

Todo lo que construyas fuera de Laravel Front usa los mismos permisos. Elige la capa que encaje:

Una pantalla Livewire. Autoriza en mount(); el fallo se vuelve un 403.

public function mount(?Plan $plan)
{
    $this->authorize($plan?->exists ? 'update' : 'create', $plan ?? Plan::class);
}

Una ruta. bootstrap/app.php registra los middleware de Spatie bajo los alias role, permission y role_or_permission, junto al can propio de Laravel:

Route::middleware('permission:export reports')->group(function () {
    Route::livewire('/reports', App\Reports::class)->name('reports');
});

Route::middleware('role_or_permission:admin|retrieve plan')->group(function () {
    // ...
});

Una vista. Oculta lo que la persona no puede hacer en vez de dejar que se tope con un 403.

@can('create plan')
    <x-button href="{{ route('admin.front.plans.create') }}">
        {{ __('New plan') }}
    </x-button>
@endcan

@can('update', $plan)
    <x-button href="{{ route('admin.front.plans.edit', $plan) }}">
        {{ __('Edit') }}
    </x-button>
@endcan

PHP plano. $user->can('delete plan'), Gate::allows('update', $plan), o $user->hasPermissionTo('export reports') para un permiso sin política detrás. Reserva $user->hasRole(config('app.admin_role')) para decisiones de presentación, como si dibujar el enlace al panel; la autorización pasa por permisos para que un rol que crees después pueda recibir la misma capacidad.

Dónde entra sudo

sudo no es un rol y no tiene permisos. Es un atributo calculado del usuario, verdadero cuando el correo está en config('app.sudo'). El seeder le da a esas cuentas el rol de administrador, que es lo que de verdad concede el acceso; el atributo en sí sólo se consulta donde el código lo nombra: la Dev Zone y la pantalla Diseño con sus entradas de la barra lateral, el registro de actividad, la protección contra eliminar un usuario sudo, actuar como otro usuario sudo (un administrador puede actuar como cualquier otra persona, pero sólo una cuenta sudo puede actuar como una cuenta sudo), y mover archivos entre discos en la biblioteca de medios cuando MULTIMEDIA_DISK_CHANGE es sudo. Quitar un correo de la lista quita esos extras pero deja el rol en su lugar.