Roles y permisos del equipo

Lo que una persona puede hacer dentro de un equipo lo decide su rol en ese equipo. Esta guía dice con qué roles nace un equipo, cómo escribe más y qué deja hacer a un miembro cada permiso de la pantalla Roles.

Dos conjuntos de roles separados

El panel de administración tiene sus propios roles, que da quien opera el producto. Cada equipo tiene sus propios roles, que escribe el equipo. Los dos nunca se mezclan: ser administrador del producto no dice nada de lo que la persona puede hacer dentro de un equipo, y ser propietario de un equipo no dice nada del panel de administración. La misma cuenta puede ser las dos cosas.

Los roles con los que nace un equipo

Todo equipo nuevo empieza con dos roles:

El propietario

El propietario es la persona que creó el equipo. El propietario siempre puede ver, agregar, cambiar y quitar miembros, diga lo que diga su rol, y es el único que puede eliminar el equipo. Todo lo demás —la configuración, los archivos y el espacio, los roles, los planes y la facturación— el propietario lo alcanza a través del rol Administrador, que tiene todos los permisos. Si tu producto le retiene un permiso a ese rol, el propietario tampoco lo tiene. No hay manera de hacer propietario a otra persona: el equipo lo creó una persona y sigue siendo suyo.

Roles que escribe el equipo

La pantalla Roles del equipo lista sus roles. Está en el menú del equipo, en el grupo Equipo junto a Miembros, para cada miembro cuyo rol puede ver roles. Un rol creado ahí pertenece sólo a este equipo: su nombre tiene que ser único dentro del equipo, y los demás equipos nunca lo ven. El formulario pide un nombre y muestra cada permiso en una cuadrícula de casillas:

• Una fila por cada tipo de registro, como Miembros o Rol, con las columnas Crear, Ver, Actualizar y Eliminar. 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 Editar ajustes o Administrar planes.

Un miembro que puede crear roles puede Clonar uno desde la lista: la copia conserva los permisos y recibe un nombre que no choca con otro.

Eliminar un rol que tiene un miembro deja a ese miembro sin rol en el equipo; dale otro primero desde la lista de miembros.

Qué deja hacer cada permiso

Las pantallas de miembros, roles, archivos y espacio piden cada una sólo su propio permiso; Administrar planes abre las pantallas de cobro y nada más.

Para desarrolladores

• Los roles del panel de administración están en el guard web y los del equipo en el guard team, sobre el modo de equipos de Spatie Permission. Cómo se elige el conjunto correcto en cada petición está en El contexto del equipo.

• Los roles iniciales se declaran en config/app.php:

  'team_owner_role' => 'administrator',
  'team_default_role' => 'user',
  'team_roles' => [
      'user' => [
          'retrieve members',
      ],
  ],
  

  Cuando se crea un equipo, cada rol de team_roles se crea dentro de él con los permisos listados, y el rol nombrado en team_owner_role se crea con todos los permisos del guard team y se asigna al creador. team_default_role tiene que ser una de las claves de team_roles. Una clave agregada a team_roles llega sólo a los equipos creados después; escribe una migración para crearla en los que ya existen.

• El propietario es el usuario en creator_user_id. Sólo UserTeamPolicy, la política de las pantallas de miembros, deja pasar al propietario sin consultar un permiso, y sólo TeamPolicy::delete() está reservado al propietario. Cualquier otra pantalla —configuración, medios, espacio, roles, facturación— pide su permiso, y el propietario pasa porque el rol de propietario se crea con todos los permisos team salvo los listados en team_restricted_permissions:

  'team_restricted_permissions' => [ // Team permissions the owner must NOT receive on signup
  ],
  

  Un permiso listado ahí falta en el rol de propietario de cada equipo creado después, así que el propietario es rechazado donde se pide.

• La pantalla de roles es el recurso con alcance de equipo en /team/roles. Pone $menu_group = 'Team', así que la barra lateral del equipo la lista en el grupo Equipo para los miembros cuyo rol tiene retrieve role.

• Los permisos del equipo se declaran en config/app.php → permissions, cada uno con su guard:

  'permissions' => [
      'retrieve members' => 'team',
      'create members' => 'team',
      'update members' => 'team',
      'delete members' => 'team',
      'edit settings' => 'team',
      'manage plans' => 'team',
      'manage media' => 'team',
      'view_team ticket' => 'team',
  ],
  

  Corre php artisan db:seed --class=PermissionSeeder después de agregar uno y existe para todos los equipos, pero ningún rol lo tiene todavía: el seeder sólo crea permisos. Un equipo creado después lo recibe en su rol de propietario. Para los equipos que ya existen, escribe una migración que se lo dé a cada rol de propietario, como hace 2026_10_14_100001_create_the_manage_media_permission_of_the_team_guard.php con manage media, y déjalo fuera cuando el permiso esté en team_restricted_permissions. Con discover_front_permissions encendido, el seeder también crea retrieve, create, update y delete para cada recurso de Laravel Front, en el guard que declara el recurso: un recurso bajo app/Front/Resources/Team/ los recibe en el guard team. Ve Construye un CRUD con alcance de equipo. allow_permisisons_deletion borra al sembrar cualquier permiso que ya no esté declarado ni descubierto.

• Las filas y los interruptores de la cuadrícula son los nombres de permiso pasados por el traductor: edit settings se muestra como Editar ajustes, y la segunda palabra de un permiso create/retrieve/update/delete nombra su fila.

• Dentro de una petición bajo /team el contexto ya es el del equipo, así que las políticas y los helpers de la base funcionan tal cual:

  $this->authorize('viewAny', UserTeam::class);
  auth()->user()->hasPermissionTo('edit settings', 'team');
  

  Pasa el guard cuando llames a Spatie directamente, como en la segunda línea, porque el guard predeterminado del usuario es web. En un job en cola, un comando o un modal cargado fuera de la petición, define primero el contexto; El contexto del equipo explica cómo.