# 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:

```bash
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.