08 — Roles y Permisos

Documento de referencia para administradores y dueños de restaurante

Sistema: ZEUMAX (ZEUMAX)
Versión: Guía de configuración de accesos, autenticación y seguridad

1. Introducción

Roles y Permisos define quién puede acceder a qué parte del sistema y qué puede hacer una vez dentro. En un restaurante moderno operan simultáneamente múltiples perfiles: clientes que hacen pedidos desde sus teléfonos, repartidores que recorren la ciudad con el GPS activo, cocineros que gestionan la preparación en tiempo real, cajeros que cobran en la caja registradora digital, managers que supervisan la operación y admins que configuran cada detalle del negocio.

ZEUMAX utiliza un sistema de autenticación múltiple (múltiples guards del backend) y autorización granular (permisos por módulo y por rol) para garantizar que cada usuario vea únicamente lo que necesita y nada más. Este documento es la guía de referencia completa para que un administrador pueda configurar, auditar y mantener los accesos de todo su equipo sin cometer errores de seguridad.

Regla de oro: Si un empleado no necesita ver algo para hacer su trabajo, no debe tener permiso para verlo.

2. Tabla Maestra de Roles del Sistema

La siguiente tabla resume todos los roles operativos del ecosistema ZEUMAX, qué guard de autenticación utilizan, en qué aplicaciones operan, cómo inician sesión, qué acciones pueden realizar y qué límites tienen explícitamente.

Nota técnica: Cada columna Guard en la tabla anterior corresponde a un sistema de autenticación independiente en el backend. Esto significa que las credenciales de un Cliente no sirven para entrar al Panel Admin, ni el PIN de un Cajero sirve para el Orden Receiver. Están completamente aislados.

3. Matriz de Permisos por App

ZEUMAX no solo separa roles, sino que dentro de cada rol define permisos granulares. A continuación se detallan los permisos configurables por aplicación.

3.1 Orden Receiver (Manager) — Permisos RBAC

El middleware CheckManagerAccess controla qué botones y pantallas ve cada manager. Los permisos se asignan desde el Panel Admin Web en la sección Empleados → Manager Users.

Cómo se configuran:
1. El Admin entra al Panel Admin Web.
2. Navega a Empleados → Manager Users.
3. Selecciona un manager existente o crea uno nuevo.
4. En la sección Permisos, marca o desmarca los checkboxes correspondientes.
5. Guarda los cambios. El manager deberá cerrar sesión y volver a entrar para que los cambios se apliquen completamente (aunque la mayoría se refrescan en caliente).

Tip práctico: Crea un perfil tipo "Recepcionista básico" con solo orders,view, orders,accept, chat,view y otro perfil "Manager de turno" con todos los permisos excepto settings,edit.

3.2 TPV — Perfiles de Permisos (TpvProfile)

Los usuarios TPV no tienen permisos individuales sueltos, sino que se agrupan en perfiles (tpv_profiles). Un perfil define un conjunto de capacidades y se asigna a uno o varios cajeros.

Cómo se configuran los perfiles TPV:
1. Desde el Panel Admin Web, ir a Configuración → TPV → Perfiles TPV.
2. Crear un nuevo perfil: asignar nombre y descripción.
3. Marcar las capacidades habilitadas para ese perfil (checkboxes por función).
4. Guardar el perfil.
5. Ir a Empleados → TPV Users y asignar el perfil deseado a cada cajero.

Importante: Si el feature flag tpv_users_enabled está desactivado en BusinessSetting, la sección TPV completa estará inaccesible para todos los usuarios. El middleware CheckTpvFeature protege esta funcionalidad.

3.3 Panel Admin — Roles Custom (admin_roles)

El sistema permite crear roles personalizados para los usuarios del Panel Admin Web. Esto es útil cuando el dueño del restaurante quiere que el equipo de marketing o finanzas acceda solo a sus áreas, sin poder tocar productos o sucursales.

Cómo se crean roles Admin:
1. En el Panel Admin Web, ir a Configuración → Roles y Permisos → Admin Roles.
2. Pulsar Crear nuevo rol.
3. Indicar nombre (ej: "Marketing") y descripción.
4. Seleccionar los módulos permitidos desde una lista de checkboxes agrupados por categoría.
5. Guardar el rol.
6. Asignar el rol al crear o editar un usuario Admin en Administradores → Usuarios Admin.

Nota de seguridad: El rol Superadmin no puede eliminarse ni restringirse. Existe al menos un Superadmin con acceso total para evitar bloqueos del sistema.

3.4 Panel Branch — Aislamiento por Sucursal (BranchAdder)

Los usuarios del Panel Branch tienen un funcionamiento especial: el middleware BranchAdder inyecta automáticamente el branch_id de su sucursal asignada en cada petición que hacen al backend. Esto significa:

• No necesitan seleccionar sucursal en cada pantalla. El sistema ya sabe de qué branch provienen.
• No pueden ver datos de otras sucursales. Aunque intenten manipular el branch_id manualmente, el middleware lo sobrescribe con su valor asignado.
• El backend filtra automáticamente. Todas las consultas a pedidos, productos, empleados, mesas y estadísticas se filtran por ese branch_id.

4. Cómo Crear y Gestionar Usuarios

Esta sección es el paso a paso práctico para un administrador que necesita dar de alta a un nuevo empleado.

4.1 Crear un Manager / Recepcionista

1. Entra al Panel Admin Web con tu cuenta Superadmin.
2. Ve al menú lateral: Empleados → Manager Users.
3. Pulsa el botón "Nuevo Manager".
4. Completa el formulario:
5. Nombre completo: obligatorio.
6. Email: obligatorio, usado para login y recuperación.
7. Teléfono: opcional, pero recomendado para OTP.
8. PIN de 4 dígitos: código numérico para acceso rápido en Orden Receiver.
9. Rol: selecciona el rol base (esto no reemplaza los permisos granulares).
10. Sucursal asignada: selecciona la branch a la que pertenecerá.
11. Permisos: marca cada checkbox granular (orders,view, orders,edit, menu,view, etc.).
12. Pulsa Guardar. El sistema enviará un email de bienvenida con instrucciones.

4.2 Crear un Perfil TPV y Asignarlo

1. En el Panel Admin Web, ve a Configuración → TPV → Perfiles TPV.
2. Pulsa "Nuevo Perfil".
3. Asigna nombre: ej. "Cajero Turno Mañana".
4. Selecciona capacidades del listado:
5. Crear pedido
6. Cobrar
7. Aplicar descuento /
8. Cancelar ítem /
9. Dividir cuenta /
10. Apertura/cierre de caja /
11. Ver informes de turno /
12. Guarda el perfil.
13. Ve a Empleados → TPV Users → Nuevo TPV User.
14. Completa: nombre, PIN, sucursal.
15. En el campo Perfil, selecciona el perfil que acabas de crear.
16. Guarda.

4.3 Crear un Rol Admin Custom

1. Ve a Configuración → Roles y Permisos → Admin Roles.
2. Pulsa "Nuevo Rol Admin".
3. Nombre: ej. "Soporte Nivel 1".
4. Descripción: ej. "Solo pedidos, chat y clientes. Sin acceso a finanzas ni configuración."
5. Marca los módulos permitidos en el árbol de permisos:
6. Pedidos
7. Chat
8. Clientes
9. Productos
10. Pagos
11. Configuración
12. Guarda.
13. Al crear un nuevo usuario Admin, selecciona este rol en el desplegable.

4.4 Activar / Desactivar un Usuario

En cualquier tabla de usuarios (Manager Users, TPV Users, Admins, Delivery Men), verás una columna Estado con un toggle switch:

• Activo (verde): el usuario puede iniciar sesión y operar normalmente.
• Inactivo (gris): el usuario queda bloqueado. No puede loguearse, pero su historial de actividad (pedidos que aceptó, ventas que cobró, chat que tuvo) se preserva intacto para auditoría.

No borres, desactiva. Eliminar un usuario elimina su historial de asociación. Desactivarlo conserva la trazabilidad de quién hizo qué.

4.5 Resetear PIN

Si un cajero o manager olvida su PIN:

1. Busca al usuario en su tabla correspondiente.
2. Pulsa el botón de menú (⋮) y selecciona "Resetear PIN".
3. El sistema genera un PIN aleatorio nuevo.
4. Puedes enviarlo por:
5. Email: el usuario recibe el PIN en su correo registrado.
6. SMS: el usuario recibe el PIN por mensaje de texto (si tiene teléfono configurado).
7. Se recomienda que el usuario cambie el PIN en su primer login.

5. Flujo de Autenticación por Tipo de Usuario

Cada perfil de usuario tiene un flujo de inicio de sesión distinto. Entenderlos ayuda a diagnosticar problemas de acceso y a capacitar al personal correctamente.

5.1 Cliente

1. El cliente abre la Web Cliente o escanea el QR de mesa.
2. Se presentan las opciones de login configuradas por el Admin en LoginSetup:
3. Email + contraseña
4. Teléfono + código OTP
5. Firebase (Google, Apple, Facebook)
6. Continuar como invitado (Guest) — el sistema genera un Guest ID automático.
7. Tras autenticarse, el backend emite un token JWT.
8. El token se almacena en cookies del navegador (o en Redux si es PWA).
9. El token expira tras el tiempo configurado (horas). El cliente debe volver a autenticarse o refrescar el token.

Nota: Los clientes Guest pueden hacer pedidos, pero para funciones como Wallet, guardar direcciones favoritas o dejar reviews, el sistema puede requerir que completen el registro completo.

5.2 Repartidor

1. Abre la app Hotpack Rider.
2. En la pantalla de login, introduce:
3. Email + password, o
4. Teléfono + código OTP (configurable por el Admin).
5. El sistema valida contra el guard auth:api.
6. Recibe un token para la API.
7. El repartidor debe estar activo (deliveryman_is_active). Si fue desactivado por el Admin, verá un mensaje de "Cuenta suspendida".
8. Mientras está online, el GPS se activa en segundo plano para permitir el tracking de entregas en tiempo real.
9. Solo recibe pedidos asignados por un Manager o por el sistema automático.

5.3 Cocinero

1. Abre la Kitchen App en la tablet o pantalla de cocina.
2. Inicia sesión con credenciales especiales: email + password o credencial rápida (si el Admin la configuró).
3. El sistema usa el guard auth:kitchen_api.
4. El backend filtra automáticamente los pedidos para mostrar solo los de la sucursal asignada al cocinero (vía relación chef_branches).
5. El cocinero ve el flujo de pedidos y puede cambiar estados: Pendiente → En preparación → Listo para entrega.
6. No puede salir de la app de cocina ni ver otras secciones del sistema.

5.4 Manager (Orden Receiver)

1. Abre la app Orden Receiver en PC o tablet.
2. En la pantalla de login, introduce su email y su PIN de 4 dígitos.
3. El sistema valida contra el guard auth:manager_api.
4. Tras el login, el middleware CheckManagerAccess evalúa su lista de permisos y oculta los botones que no puede usar.
5. Ejemplo: Si no tiene orders,accept, el botón "Aceptar pedido" no aparece.
6. Ejemplo: Si no tiene settings,edit, la pestaña de configuración está oculta.
7. El manager opera únicamente dentro de los límites de su sucursal asignada.

5.5 Cajero (TPV)

1. Abre la app TPV en el dispositivo de caja (tablet, PC táctil o caja registradora digital).
2. Inicia sesión con su PIN de acceso rápido.
3. El sistema valida contra el guard auth:tpv_api.
4. El middleware CheckTpvFeature verifica que el TPV esté habilitado a nivel global (tpv_users_enabled). Si no, muestra "TPV no disponible".
5. El middleware CheckTpvFeature también verifica qué módulos del TPV están activos (mesas, delivery, stock, etc.) y oculta los que no apliquen.
6. El cajero opera según su perfil (TpvProfile). Si su perfil no permite descuentos, el botón de descuento no aparece o está deshabilitado.

5.6 Admin / Superadmin

1. Abre el Panel Admin Web en un navegador.
2. Introduce email + password.
3. El sistema valida contra el guard admin.
4. Se crea una sesión web con cookies de sesión.
5. El Admin tiene acceso a todo el menú lateral del panel.
6. Si se creó un rol Admin custom (ej: "Marketing"), el menú se filtra para mostrar solo los módulos permitidos.

5.7 Branch Manager

1. Abre el Panel Branch Web en un navegador.
2. Introduce email + password.
3. Selecciona su sucursal de un desplegable (si tiene más de una asignada, o se autoselecciona si solo tiene una).
4. El guard branch valida sus credenciales y su vínculo con la sucursal.
5. El middleware BranchAdder inyecta el branch_id en cada petición posterior.
6. El usuario ve solo datos, pedidos, mesas y empleados de esa sucursal.

6. Middlewares y Seguridad Explícita

Los middlewares son como guardias de seguridad que revisan cada petición antes de dejarla pasar. A continuación se explica cada uno en lenguaje humano:

El Middleware BranchAdder en detalle

Este middleware es clave para la multi-sucursal:

• Inyección automática: Cuando un Branch Manager o un empleado de sucursal hace una petición, BranchAdder lee su branch_id asociado y lo añade automáticamente a los parámetros de la petición.
• Backend blindado: Los controladores del backend usan ese branch_id para filtrar todas las queries. Ni siquiera el desarrollador del frontend necesita enviarlo manualmente.
• Anti-manipulación: Si un usuario malintencionado intenta enviar un branch_id falso en la petición, el middleware lo sobrescribe con el valor real asignado en la base de datos.

Resultado: Un empleado de la sucursal "Downtown" nunca puede ver, editar ni borrar datos de la sucursal "Uptown", aunque sea intencional o accidental.

7. Configuración de Métodos de Login (LoginSetup)

El sistema permite que el Admin configure qué métodos de autenticación están disponibles para los clientes y, en parte, para los empleados. Esto se gestiona en el Panel Admin en la sección Configuración → Login y Autenticación.

Opciones configurables por el Admin

Configuración de OTP

El Admin puede ajustar:

• Duración del código: ¿Cuántos minutos es válido el OTP? (ej: 5 minutos, 10 minutos).
• Longitud del código: ¿4 dígitos, 6 dígitos?
• Vía de envío: ¿SMS, Email, o ambos?
• Intentos fallidos: ¿Cuántos intentos erróneos permitir antes de bloquear temporalmente?

Recomendación: Para mercados con buena cobertura SMS, usa OTP por teléfono. Para mercados donde el email es más confiable, activa OTP por email. Nunca desactives ambos a la vez si usas OTP.

Configuración de PIN

• Longitud: El Admin define cuántos dígitos tiene el PIN (generalmente 4).
• Requisitos: Puede exigir que el PIN no sea secuencial (ej: 1234) ni repetido (ej: 1111).
• Reseteo: Cuántas veces se puede resetear por hora/día para evitar abuso.

8. Verificación de Cuentas

ZEUMAX diferencia entre usuarios registrados y usuarios verificados. La verificación es un paso adicional que aumenta la confianza y desbloquea funciones sensibles.

Verificación de Email

1. El cliente se registra con su email.
2. El sistema envía un email de verificación con un link único.
3. El cliente abre su bandeja de entrada y hace clic en el link.
4. El sistema marca el email como verificado en la tabla email_verifications.
5. El cliente ahora tiene acceso a funciones que requieren email verificado.

Verificación de Teléfono

1. El cliente introduce su número de teléfono.
2. El sistema envía un SMS con un código OTP.
3. El cliente introduce el código en la app.
4. El sistema valida contra la tabla phone_verifications.
5. El teléfono queda verificado.

Diferencia entre verificado y no verificado

Nota: El Admin puede configurar qué funciones requieren verificación desde el Panel Admin. En algunos mercados, para cumplir normativa local, el teléfono verificado es obligatorio para delivery.

9. Modo Mantenimiento

El Modo Mantenimiento permite al Admin cerrar temporalmente el acceso público al sistema sin afectar las operaciones internas.

Cómo se activa

1. El Admin entra al Panel Admin Web.
2. Ve a Configuración → General → Modo Mantenimiento.
3. Activa el toggle "Modo Mantenimiento".
4. Opcionalmente, escribe un mensaje personalizado para los usuarios (ej: "Volvemos en 30 minutos con mejoras en el sistema").

Qué ocurre cuando está activo

Uso típico: Actualizar precios, cambiar estructura de categorías, migrar datos, aplicar hotfixes críticos, cambiar integraciones de pago.

10. Buenas Prácticas de Seguridad

La seguridad del sistema no depende solo del software, sino de los hábitos del equipo. Estas son las recomendaciones oficiales para administradores y dueños de restaurante:

10.1 No compartir PINs

• Cada empleado debe tener su propio PIN.
• El PIN es personal e intransferible.
• Si un compañero necesita cubrir un turno, el Admin debe crearle un usuario propio o reasignar temporalmente.

10.2 Cerrar sesión al final del turno

• Todos los usuarios (especialmente TPV y Manager) deben cerrar sesión antes de irse.
• No dejar la app TPV abierta con un cajero logueado si otro empleado va a usar el dispositivo.

10.3 Cambiar PIN periódicamente

• Se recomienda forzar el cambio de PIN cada 30-90 días para usuarios de TPV y Manager.
• El Admin puede resetear masivamente los PINs desde el Panel Admin si sospecha de una filtración.

10.4 Desactivar, no borrar

• Cuando un empleado deja de trabajar, desactívalo (toggle de estado), no lo elimines.
• Razón: el historial de actividad (quién cobró qué, quién aceptó qué pedido) queda ligado a ese usuario. Borrarlo rompe la trazabilidad.

10.5 Revisar logs de actividad

• El Panel Admin tiene una sección de Logs / Auditoría donde se registra:
• Quién aceptó un pedido y a qué hora.
• Quién cobró una venta, con qué método y monto.
• Quién modificó un producto o precio.
• Quién asignó un repartidor.
• Quién desactivó a un usuario.
• Revisa estos logs al menos semanalmente para detectar comportamientos anómalos.

10.6 Principio de mínimo privilegio

• Nunca des permisos "por si acaso".
• Un recepcionista nuevo no necesita settings,edit ni employees,edit.
• Un cajero de medio tiempo no necesita perfil de "Jefe de caja".
• Asigna el rol más restrictivo que permita hacer el trabajo. Es más fácil subir permisos luego que bajarlos después de un incidente.

10.7 Auditar roles Admin custom

• Si creaste roles como "Marketing" o "Soporte", revísalos cada 3 meses.
• Asegúrate de que no tengan acceso a módulos que no les corresponden por error de configuración.
• El Superadmin debe revisar quién tiene rol Superadmin. Limita este rol al mínimo indispensable (idealmente 1-2 personas).

11. Glosario Rápido de Términos

Fin del documento 08 — Roles y Permisos
Para dudas sobre configuración específica, consulte el documento 05-configuracion-inicial.md o contacte al soporte técnico de ZEUMAX.