shopit-back/docs/authorization.md

Roles y permisos

El sistema utiliza control de acceso basado en roles. Los códigos son identificadores estables para uso interno; los nombres y las descripciones pueden modificarse sin afectar las reglas de autorización.

Los permisos administrativos deben evaluarse siempre dentro del tenant correspondiente. El rol admin es la única excepción porque su alcance es toda la plataforma.

Cada registro de users contiene:

• rol_codigo: código obligatorio del rol. Su valor predeterminado es user.
• tenant_codigo: código nullable del tenant. Solamente se utiliza para usuarios con rol tenant_admin; para admin y user debe permanecer en null.

Roles

Código	Nombre	Alcance
admin	Administrador general	Administra la plataforma, todos los tenants, roles y permisos. Tiene todos los permisos.
tenant_admin	Administrador del tenant	Administra usuarios y la operación de su tenant. No puede gestionar la definición de roles.
user	Usuario	Cliente final. No tiene permisos administrativos y solamente puede operar sobre sus propios datos, carrito, pedidos y tickets.

Permisos

Código	Nombre	Descripción
tenant.ver	Ver configuración del tenant	Consultar la configuración general de un tenant.
tenant.editar	Editar configuración del tenant	Modificar datos generales, dominio, colores y recursos visuales.
usuarios.ver	Ver usuarios	Consultar los usuarios asociados al tenant.
usuarios.gestionar	Gestionar usuarios	Invitar, editar, desactivar y asignar roles permitidos a usuarios del tenant.
roles.ver	Ver roles	Consultar los roles y sus permisos.
roles.gestionar	Gestionar roles	Crear, modificar y asignar permisos a roles.
catalogo.ver	Ver catálogo	Consultar productos, variantes, categorías, marcas y bundles administrativamente.
catalogo.gestionar	Gestionar catálogo	Crear, modificar, archivar y eliminar productos, variantes, categorías, marcas y bundles.
inventario.ver	Ver inventario	Consultar stock e información de inventario.
inventario.ajustar	Ajustar inventario	Modificar el stock disponible.
pedidos.ver	Ver pedidos	Consultar los pedidos del tenant.
pedidos.gestionar	Gestionar pedidos	Modificar estados y datos operativos de pedidos.
pedidos.cancelar	Cancelar pedidos	Cancelar pedidos y liberar sus reservas de inventario.
pagos.ver	Ver pagos	Consultar el estado y la información de pagos.
pagos.gestionar	Gestionar pagos	Confirmar, rechazar o devolver pagos.
tickets.ver	Ver tickets	Consultar tickets emitidos.
tickets.gestionar	Gestionar tickets	Emitir, invalidar o regenerar tickets.
contenido.gestionar	Gestionar contenido	Administrar menús, carruseles, destacados y redes sociales.
integraciones.ver	Ver integraciones	Consultar la configuración y el estado de integraciones.
integraciones.gestionar	Gestionar integraciones	Configurar credenciales y proveedores de integraciones.
reportes.ver	Ver reportes	Consultar reportes de ventas y métricas.
reportes.exportar	Exportar reportes	Descargar reportes e información comercial.

Matriz de asignación

Permiso	admin	tenant_admin	user
tenant.ver	Sí	Sí	No
tenant.editar	Sí	Sí	No
usuarios.ver	Sí	Sí	No
usuarios.gestionar	Sí	Sí	No
roles.ver	Sí	Sí	No
roles.gestionar	Sí	No	No
catalogo.ver	Sí	Sí	No
catalogo.gestionar	Sí	Sí	No
inventario.ver	Sí	Sí	No
inventario.ajustar	Sí	Sí	No
pedidos.ver	Sí	Sí	No
pedidos.gestionar	Sí	Sí	No
pedidos.cancelar	Sí	Sí	No
pagos.ver	Sí	Sí	No
pagos.gestionar	Sí	Sí	No
tickets.ver	Sí	Sí	No
tickets.gestionar	Sí	Sí	No
contenido.gestionar	Sí	Sí	No
integraciones.ver	Sí	Sí	No
integraciones.gestionar	Sí	Sí	No
reportes.ver	Sí	Sí	No
reportes.exportar	Sí	Sí	No

Carga inicial

El seeder Database\Seeders\AuthorizationSeeder crea o actualiza este catálogo y sincroniza sus asignaciones. Puede ejecutarse de manera independiente:

php artisan db:seed --class=AuthorizationSeeder

También se ejecuta como parte de DatabaseSeeder.

Las acciones del rol user no se representan como permisos administrativos. El acceso al perfil, carrito, pedidos y tickets se autoriza comprobando que el recurso pertenezca al usuario autenticado y al tenant actual.