Matriz de Roles / Permisos (configurable por Admin)
Análisis Funcional: Integración Soterex — parte 3 de 8. ← Sitemap · Índice · Siguiente: User Flows →
Definición (2026-07-24): la matriz de roles no es fija — es un módulo de configuración editable por el rol Admin (ABM Roles y Permisos, agregado al Sitemap). Para cada módulo/recurso del sistema, el Admin puede activar/desactivar 3 permisos por rol: Leer (L), Escribir (E), Borrar (B), con toggles on/off.
Regla de dependencia confirmada por el cliente: si Borrar = ON, entonces Escribir se activa automáticamente y no puede desactivarse mientras Borrar siga ON (Borrar depende de Escribir). Por consistencia del mismo patrón, se asume además que Escribir = ON requiere Leer = ON (no se puede escribir algo que no se puede leer) — a confirmar con el cliente, queda como sub-punto de la Pregunta Abierta #5.
Esto significa que el módulo de roles pasa a ser datos de configuración (seed), no un requisito fijo de negocio. Los 3 roles detectados en la charla (Backoffice, Supervisor, Admin) se cargan como valores iniciales por defecto, editables luego desde ABM Roles y Permisos.
2.1 Matriz por defecto (seed inicial, editable desde Admin)
Actualizada el 2026-08-05 para reflejar el seed real (
backend/database/seeders/RoleSeeder.php) después de E2, E3 y E4. La versión original (2026-07-24) no tenía los módulos de Caja, Pago ni Tipo de Cambio, y listaba un "% comisión por país" que ya no existe.
| Módulo / Recurso | Backoffice (L/E/B) | Supervisor (L/E/B) | Admin (L/E/B) |
|---|---|---|---|
| Transacciones (listado + detalle) | —·E·— ⑴ | L·E·— | L·E·B |
| Pago (búsqueda exacta acotada) ⑵ | L·—·— | —·—·— | L·—·— |
| Cambio de estado a PAID | — (incluido en Escribir de Transacciones) | idem | idem |
| Cancelar transacción | — (incluido en Escribir de Transacciones) | idem | idem |
| Prefondeo Holding (asientos globales) ⑶ | —·—·— | L·E·— | L·E·B |
| Prefondeo País (asientos por país) ⑷ | —·—·— | L·E·— | L·E·B |
| Caja (listado, movimientos, reporte) | L·E·— | L·E·— | L·E·B |
| Apertura / cierre de caja ⑸ | L·E·— | L·E·— | L·E·B |
| Fondeo y ajuste de caja | —·—·— | L·E·— | L·E·B |
| Tipo de cambio | L·—·— | L·E·— | L·E·B |
| Reportes contables (estado de situación, cajas) | —·—·— | L·—·— | L·—·— |
| Dashboard de volumen/comparativas por país y PDV | —·—·— | L·—·— | L·—·— |
| ABM Usuarios | —·—·— | —·—·— | L·E·B |
| ABM Países ⑹ | —·—·— | —·—·— | L·E·B |
| ABM Estaciones / PDV | —·—·— | —·—·— | L·E·B |
| ABM Configuración (timeout sesión) | —·—·— | —·—·— | L·E·B |
| ABM Roles y Permisos | —·—·— | —·—·— | L·E·B |
| ABM Asignación de Roles Multipaís/PDV | —·—·— | —·—·— | L·E·B |
| Logs de auditoría (movimientos y logins) | L·—·— ⑺ | L·—·— | L·—·— |
⑴ Sin Leer, con Escribir — no es un error. Por la decisión #1 del plan v2, Backoffice deja de ver la pantalla general de Transacciones y opera solo desde "Pago"; pero pagar y cancelar pegan a los mismos endpoints, gateados por transacciones:write. ⑵ Pantalla nueva de E2. Supervisor no la tiene: usa la pantalla completa de Transacciones. ⑶ Es el módulo prefondeo que ya existe. Renombrado a "Holding" el 2026-08-05 (ADR-007) — descuenta principal + comisión. ⑷ Módulo prefondeo_pais, agregado por E4b y ya en main. Descuenta solo principales, lo carga tesorería. Los valores de esta fila son los que siembra RoleSeeder. ⑸ Ya no requiere autorización de un Supervisor (2026-08-05, ADR-007): la ejecuta el operador con su propia sesión. ⑹ Ya no incluye "% comisión por país": el campo se eliminó (ADR-005) — la comisión la fija Soterex por transacción. Sí incluye el flag del módulo Caja, la moneda local y la moneda de pago. ⑺ Confirmado con Carlos (2026-07-29): el mockup final de la pantalla Pago muestra Auditoría en el sidebar de Backoffice.
Esta tabla es el seed inicial, no una regla rígida: el Admin puede reconfigurar cualquier celda desde
ABM Roles y Permisos, respetando la dependencia Borrar→Escribir(→Leer).
2.2 ¿Se necesita UI/UX en esta etapa?
No. En esta fase (Análisis Funcional del Product Owner) alcanza con dejar definida la regla de negocio (matriz configurable, dependencia Borrar→Escribir) y el módulo en el sitemap. El diseño visual del componente de toggles (cómo se ve la grilla, si se bloquea visualmente el toggle de Escribir cuando Borrar está ON, etc.) es responsabilidad del agente ui-engineer en la etapa de diseño, y ya quedó anotado como señal de handoff (ver Señales de Handoff).
2.3 Asignación de Roles Multipaís / Multi-PDV (confirmado 2026-07-24)
Esta es una dimensión adicional a la matriz L/E/B de 2.1 (que define qué puede hacer cada rol) — acá se define qué rol tiene cada usuario, en qué país, y en qué PDV, y también debe ser editable desde Admin (ABM Asignación de Roles Multipaís/PDV).
Reglas confirmadas por el cliente:
- Un mismo usuario puede tener roles distintos en distintos países (ej: Admin en Guatemala y Supervisor en otro país).
- Un Supervisor puede estar a cargo de más de un PDV.
- Toda esta lógica de asignación (usuario × país × rol, y supervisor × PDVs) debe ser editable, no fija.
Nota de diseño para el
architect: esto implica que el control de acceso no es simplemente "Usuario → Rol", sino "Usuario → (País, Rol, [PDVs])" — cada sesión/consulta debe filtrar datos según el conjunto de países/PDVs donde el usuario tiene un rol asignado.
2.4 ⚠️ CORRECCIÓN (2026-07-25): el PDV de una transacción NO se conoce al ingresar — se asigna recién al resolverla
Esto corrige una implementación ya hecha en M1 — quedó documentado acá porque afecta directamente el alcance por PDV descripto en 2.3, y porque el criterio de aceptación original de M1 ("el listado no muestra transacciones... sin PDV") es exactamente el error inverso: si las transacciones entran sin PDV (como corresponde), esa regla haría que ningún Backoffice viera jamás una transacción pendiente.
Regla correcta:
- Soterex/
SendRequestno informa PDV — a esa altura es imposible saberlo. Una transacciónACCEPTEDrecién ingresada no tiene PDV asignado, solo país. - Todas las transacciones
ACCEPTEDde un país conforman una bolsa compartida — cualquier Backoffice/Supervisor con acceso a ese país (sin importar a qué PDV específico esté asignado) puede verlas y tomarlas. - El PDV recién se define cuando un usuario la resuelve (la pasa a
PAIDoCANCELLED): en ese momento se graba qué usuario y de qué PDV la resolvió (el PDV activo de ese usuario en su sesión — ver la pregunta nueva más abajo sobre qué pasa si el usuario tiene más de un PDV asignado). - El acotamiento por PDV de la matriz de permisos (2.3) aplica a transacciones ya resueltas (para reporting/auditoría por PDV), no a las
ACCEPTEDpendientes — esas son visibles a nivel país para cualquier Backoffice/Supervisor con acceso a ese país.
Requisito reforzado — verificación hasta el último momento: como ahora varios cajeros de distintos PDVs pueden estar mirando la misma transacción pendiente al mismo tiempo (comparten la bolsa del país), el riesgo de que dos personas intenten resolver la misma transacción a la vez sube — no es un caso raro, es esperable. El sistema tiene que volver a verificar el estado actual de la transacción justo antes de confirmar el cambio (no alcanza con haberlo chequeado cuando se abrió la pantalla) — si otro usuario ya la resolvió un instante antes, se rechaza el cambio con un error claro ("esta transacción ya fue procesada por [otro usuario]") y se refresca el listado, en vez de permitir un doble procesamiento.
2.5 ⚠️ NUEVO (2026-07-25): la comisión es información restringida — solo Reportes y el Dashboard de Supervisor
Regla de negocio confirmada por el cliente: el monto de la comisión CIS de una transacción no se muestra en ningún lugar operativo del sistema — ni en el listado de Transacciones, ni en el detalle de una transacción, ni en el modal de confirmación de pago/cancelación. Se muestra únicamente en:
- Reportes (estado de situación contable, agregados).
- Dashboard, pero solo para el rol Supervisor (no para Backoffice ni cualquier otro rol que entre al Dashboard).
Por qué importa más que un cambio visual: esto no se resuelve solo ocultando el campo en el frontend — si el backend sigue devolviendo fee/comision en la respuesta de la API para cualquier usuario, alcanza con abrir las DevTools del navegador para verlo igual. La restricción tiene que aplicarse en el backend, condicionando qué campos incluye la respuesta según el rol del usuario que hace el request — el frontend ocultando el campo es una capa extra, no la protección real.
Alcance de la restricción — qué SÍ sigue visible:
- ABM Países (donde el Admin configura el % de comisión editable por país) — esto es configuración del sistema, no una "revelación" de la comisión de una transacción puntual. Se asume que sigue visible/editable para Admin sin cambios. A confirmar con el cliente si esta lectura es correcta o si también hay que restringir esta pantalla.
Módulos afectados (a auditar y corregir):
GET /api/transaccionesyGET /api/transacciones/{id}— el campo de comisión no debe venir en la respuesta salvo que el usuario sea Supervisor consultando desde el contexto de Reportes/Dashboard.- Listado de Transacciones (columna "Comisión") — sacar para todos los roles excepto el caso de uso de Reportes.
- Detalle de Transacción — sacar el dato de comisión de la vista.
- Modal de confirmación de pago/cancelación (el "recibo") — sacar la fila de comisión por completo, no mostrarla ni siquiera al Supervisor en este flujo puntual (la regla es "Reportes y Dashboard", no "donde sea que el Supervisor esté parado").