ADR-014: Cuatro perfiles y separación de pagar y cancelar
Date: 2026-10-02 Status: Accepted — decisiones P3 a P6 y P11 del plan de ajustes v2, confirmadas por Carlos el 2026-10-02 (en particular: el Admin cancela y paga). Implementado en la entrega B6 del plan (PR 2). Supersedes in part: ADR-007 (tesorería operando con el rol Supervisor), ADR-005 (fondeo de caja y tipo de cambio para el Supervisor), y las decisiones del plan de ajustes v1 y del plan v2 que se listan en Qué reemplaza. Extends: ADR-011 §4 (la señal fondeo_caja:read que decide quién «supervisa» pasa a evaluarse dentro de una misma asignación; ver el punto 6). Updated: 2026-10-06 (G6, ver el final) y 2026-10-07 (G8, plan de ajustes v3): Tesorería es un único perfil regional por asignación (§1, D3-T1), la mezcla de perfiles es intencional y no hay selector (§6, D3-T2) y el tipo de cambio sale del Cajero y del Supervisor (§2, §9, Consequences y la actualización del final, D3-11).
Context
El 2026-10-01 el cliente (Magaly Benavides, CIS-EC) contestó la pregunta sobre perfiles y menús que le dejamos en la entrega v1:
«El backoffice de hoy pasa a ser cajero, ya no se necesita perfil de backoffice porque los permisos los tiene el Administrador»
y sobre quién accede a qué: Reportes para todos menos el cajero, Auditoría solo para el Administrador, y el Supervisor no fondea cajas (lo que quiere es verlas).
Lo que existía:
- Tres roles sembrados por
RoleSeeder: Backoffice, Supervisor y Admin. «Los perfiles no se tocan» fue una decisión de Carlos del 2026-09-28 y valía para la entrega v1. - Tesorería no tenía perfil propio. Quien carga el prefondeo (Holding y país) y fondea las cajas operaba con el rol Supervisor (decisión de Carlos del 2026-08-06, plan E4b: «no se crea un rol Tesorería aparte»). Eso le daba al Supervisor de un PDV acceso a plata que no es de su PDV.
- Pagar y cancelar eran el mismo permiso:
PATCH .../payyPATCH .../cancelestaban gateados portransacciones:write. El permisotransacciones:deleteexistía, lo tenía solo el Admin y no lo consultaba nadie. - Una regla de acceso se decidía por el nombre del rol:
DashboardController::isSupervisorForCountrycomparabarole->name === 'Supervisor'para mostrar la comisión. - La ficha de usuario no podía editar tres módulos (
pago,prefondeo_pais,abm_catalogos) porque la lista de módulos estaba escrita a mano en el frontend.
Decision
1. Cuatro perfiles
| Perfil | Quién es | Qué hace |
|---|---|---|
| Cajero | El Backoffice de hoy | Busca y paga en Pago, opera su caja (apertura y cierre), ve solo lo que resolvió él. No cancela, no ve Reportes ni Auditoría |
| Supervisor | Supervisa uno o más PDV | Lo del Cajero, más ver los saldos y movimientos de las cajas de su PDV, Reportes y Dashboard. No fondea ni ajusta cajas, no carga prefondeos, no edita el tipo de cambio, no cancela |
| Tesorería | (nuevo) Quien mueve la plata | Carga el prefondeo Holding y país, fondea las cajas, edita el tipo de cambio, ve Reportes y Dashboard. No ve Pago ni Transacciones |
| Admin | Quien en los documentos del cliente es el «Backoffice central / regional» (P4) | Todo. Paga y cancela (decisión de Carlos del 2026-10-02) |
P4. Donde los documentos del cliente dicen «Backoffice» (central o regional), en la app es Admin. El rol sigue llamándose Admin. Si el cliente quiere un quinto perfil, es una fila nueva en la matriz, sin código.
Actualización (2026-10-04, D3-T1, plan de ajustes v3 — G8): Tesorería es un único perfil, regional por asignación. Donde la hoja de menús del cliente escribe «Tesorería Local o Regional según corresponda» se lee «Tesorería»: no existe una «Tesorería Local» y no se crea otro rol. «Regional» no es un atributo del rol ni una entidad: es la asignación (usuario × país × rol × PDVs opcionales). Lo que sigue de ahí:
- El alcance de cada módulo son los países de las asignaciones que lo permiten (
PermissionService::allowedCountryIds). Regional es Tesorería con una asignación sin acotar por PDV en cada país activo; local, asignada a un país. No existe una asignación «todos los países» (country_ides obligatorio): una persona regional necesita una asignación por país, y al dar de alta un país nuevo hay que sumárselo.- La Holding es global (ADR-007 §1) y solo se ve completa con cobertura de todos los países; con menos, el extracto es parcial y lo avisa (ADR-015 §5). Desde G12 (2026-10-07) la tarjeta de saldo sigue la misma regla: quien cubre un solo país ve el saldo de ese país y no el global, y «cobertura de todos los países» no cuenta a un país inactivo sin movimientos.
- Las escrituras son siempre por país (prefondeo, fondeo y ajuste de caja, tipo de cambio): una Tesorería de Guatemala no carga nada en otro país.
- Una persona con Tesorería en un solo país ve completos el extracto País y los de PDV de ese país: «CIS Guatemala solo su estado de cuenta» queda cubierto por el alcance de la asignación, sin un rol aparte. Lo que esa asignación no esconde —y que el cliente no pidió quitar, QC-32 por defecto— es la porción de su país de los dos extractos de la Holding, con el aviso de «parcial». (G12, 2026-10-07: la tarjeta de saldo, que mostraba el de todos los países, ahora muestra el de los suyos; ver el punto 2.)
- Una asignación acotada por PDV no lee los extractos de país entero (ADR-015 §5, pregunta #20 de las abiertas de Caja): las asignaciones de Tesorería se dan siempre por país entero, y quien tiene que ver un PDV solo es un Supervisor.
- No se puede dar a una persona de Tesorería solo lectura de un país: los permisos son del rol y la matriz es compartida. El alcance es lo único que la acota.
- Un solo perfil no separa «quien manda» de «quien recibe»: la misma persona puede cargar el envío de la Holding a un país y recibirlo. Hoy el control es detectivo (libro inmutable y Auditoría); lo que lo distinguiría sin rol nuevo son las confirmaciones de recepción (G13).
- El Dashboard de una Tesorería de un solo país muestra el KPI «Saldo de prefondeo» y la comisión (
prefondeo:read); queda pendiente de la definición del escenario de prefondeo y no se toca.En la matriz no cambia nada: las cinco filas del cliente donde participa Tesorería ya las cubre el rol.
2. La matriz objetivo
L leer, E escribir, B borrar. En negrita, lo que cambia respecto de la matriz anterior.
| Módulo | Cajero | Supervisor | Tesorería | Admin |
|---|---|---|---|---|
pago | L E | L E | — | L E |
transacciones | L E | L E | — | L E B |
caja | L E | L E | L | L E B |
apertura_cierre_caja | L E | L E | — | L E B |
fondeo_caja | — | L (sin E) | L E | L E B |
traspaso_caja (L3, ADR-029) | — | L E | L E | L E B |
prefondeo | — | — | L E | L E B |
prefondeo_pais | — | — | L E | L E B |
tipo_cambio | L | L (sin E) | L E | L E B |
reportes | — | L | L | L |
reporte_cumplimiento | — | — | — | L |
dashboard | — | L | L | L |
auditoria | — | — | — | L |
abm_* (los siete) | — | — | — | L E B |
La matriz es el seed (RoleSeeder::MATRIX) y sigue siendo editable por el Admin desde la app. Los siete abm_* son abm_usuarios, abm_paises, abm_estaciones, abm_catalogos, abm_configuracion, abm_roles_permisos y abm_asignacion_roles.
Actualización (G8, 2026-10-07, D3-11): la fila
tipo_cambiode esta tabla es la que dejó B6. Desde G8 queda—para el Cajero,—para el Supervisor, yL E(Tesorería) yL E B(Admin) sin cambios: la lectura que B6 les había dejado al Cajero y al Supervisor era decisión nuestra, no un pedido del cliente, y su hoja de menús reserva el tipo de cambio a Administrador y Tesorería. Ver la actualización del final de este ADR.
3. Backoffice pasa a Cajero: se renombra la fila, no se crea un rol (P3)
La migración de datos cambia el name de la fila Backoffice a Cajero. role_assignments apunta por role_id, así que las asignaciones de todos los usuarios se conservan sin tocarlas, igual que el timeout de sesión que el rol tenga configurado.
Esto es lo más peligroso de la entrega, por una razón concreta: RoleSeeder busca el rol por nombre (updateOrCreate(['name' => ...])). Si alguien cambia la clave de MATRIX de Backoffice a Cajero y corre el seeder sin haber renombrado antes la fila, el seeder crea un rol Cajero nuevo y vacío y deja a todos los usuarios en Backoffice, con los permisos viejos, sin ningún error. Por eso el renombre es de la fila, va primero en la migración, y el seeder tiene la misma salvaguarda.
4. Pagar y cancelar dejan de ser el mismo permiso (P5, P6)
| Acción | Permiso | Antes |
|---|---|---|
Pagar (PATCH .../pay) | pago:write | transacciones:write |
Cancelar (PATCH .../cancel) | transacciones:delete | transacciones:write |
Cargar los datos del pago (.../datos-pago) | transacciones:write | igual |
| Subir y ver soportes | transacciones:write | igual |
Se valida en la ruta (perm:) y en el controller (authorizeScope): el backend manda, el botón que no se dibuja no es un control. El resultado:
- Cajero y Supervisor pagan y no cancelan (403 por API).
- Admin paga y cancela. La versión original del plan lo dejaba en solo lectura de Pago; Carlos lo cambió el 2026-10-02 («cancela y paga»): la celda
pagode Admin esL E. - Tesorería ni paga ni cancela ni abre una transacción: no tiene ninguno de los dos módulos.
- Cancelar queda solo para el Admin porque
transacciones:deletees el único permiso de la matriz que hoy tiene solo él. Darlo a otro perfil es una celda, sin código. - La cancelación que pide Soterex por la API (
POST /api/c2p/v1/Cancel, ADR-012) no pasa por estos permisos y no cambia: la autenticación es de máquina, no de persona.
Una consecuencia operativa, no un defecto: un Cajero que se equivocó de transacción ya no puede cancelarla; tiene que pedírselo a un Admin.
5. La comisión del Dashboard se decide por permiso (P11)
isSupervisorForCountry desaparece. El KPI de comisión del Dashboard lo ve quien tiene prefondeo:read en el país, que es el mismo permiso que ya decide si se ve el saldo de prefondeo: Tesorería y Admin. El Supervisor deja de verla (decisión de Carlos). Antes la veía solo el rol llamado Supervisor —ni siquiera el Admin—, y un rol creado a mano con los mismos permisos no la veía.
6. Quién «supervisa» se decide por permiso, y dentro de una misma asignación
ADR-011 §4 eligió fondeo_caja:read como la señal de «alcance amplio, supervisa» frente a «opera una caja puntual», y dejó anotado que un perfil Tesorería con esa capacidad seguiría funcionando sin tocar el código. Ahora Tesorería tiene fondeo_caja L E, así que fondeo_caja:read ya no distingue «Supervisor/Admin» de «Tesorería». Se revisó cada consumidor:
| Consumidor | Qué decide | Tesorería |
|---|---|---|
CashBoxController::canSeeBalance | Ver el saldo real de todas las cajas del alcance | Sí, a propósito: es lo que necesita para fondear. Acotado por caja:read y por PDV |
isScopedToOwnTransactions | Que el listado de Transacciones se acote a lo propio | No aplica: sin transacciones:read no llega al listado (403) |
canManageTransactionDocuments | Subir soportes de lo que resolvió otro | No aplica: exige transacciones:write (403 en la ruta) |
PagoController::pendientes | Alcance de los pagos con documentación pendiente | Vacío: los países salen de pago:read / transacciones:read |
El riesgo real no es Tesorería sola sino Tesorería más Cajero en el mismo país: los permisos de un usuario son la unión de sus asignaciones, y la señal «supervisa» se calculaba sobre esa unión. Un usuario con las dos asignaciones habría pasado a ver todas las transacciones del país y a subir soportes de las de otros, solo porque la asignación de Tesorería le suma fondeo_caja:read. Se corrige separando dos preguntas que antes eran una:
- «¿Ve el saldo de todas las cajas?» (
PermissionService::canSeeAllCashBoxes) →fondeo_caja:readen el país. Lo usa Caja. (Desde G6, 2026-10-06: en una asignación que cubra el PDV de la caja, no en el país; ver la actualización del final de este ADR y ADR-021.) - «¿Supervisa transacciones?» (
PermissionService::isSupervisorTier) →fondeo_caja:readytransacciones:readen la misma asignación. Lo usan el listado, los soportes y los pendientes. - «¿Cierra la caja que abrió otra persona?» (
PermissionService::canCloseCashSession, G6) → quien la abrió, oapertura_cierre_caja:writeyfondeo_caja:readen la misma asignación que cubra el PDV de la caja: el Supervisor y el Admin, y no Tesorería ni un Cajero que sume Tesorería. Es el tercer uso de la misma idea; el detalle está en ADR-021.
Un usuario con más de un perfil: la mezcla es intencional (2026-10-04, D3-T2)
El cliente pidió, en la hoja Menús y perfiles (ítem 1, RV3-49), «una opción de consulta de con qué perfil se quiere ingresar» para quien tiene más de un perfil. Decisión de Carlos (2026-10-04): está bien que se mezclen las opciones —la unión de permisos de las asignaciones, como desde B6— y no se construye un selector de perfil ni una «asignación activa». El pedido queda cerrado como decisión de producto; se le contesta al cliente que el comportamiento es intencional y por qué, y se documenta (manual, ficha de usuario, esta sección). No hay ADR nuevo: se registra acá.
Qué es «la mezcla» hoy. Una sola persona con varias asignaciones recibe:
| Qué | Regla | Dónde vive |
|---|---|---|
| Menú, rutas y manual en pantalla | La unión global de las asignaciones, sin mirar el país | PermissionService::effectiveModules; meStore.canRead |
| Datos y acciones | Se deciden por país: una asignación da el permiso solo en su país | PermissionService::allows(…, $countryId), allowedCountryIds; el frontend ofrece solo los países con countriesWithAccess(módulo) |
| Alcance por PDV | Dentro de un país se une por acción; una asignación sin acotar que da el permiso alcanza todo el país | PermissionService::allowedStationIds |
| «Supervisa transacciones» y «supervisa una caja» | Dentro de una misma asignación (que cubra el PDV), nunca sobre la unión | isSupervisorTier, assignmentHolds (este punto, y ADR-021) |
| Timeout de sesión | El menor de los plazos propios de sus roles (el rol sin plazo propio no cuenta; si ninguno lo tiene, rige el general); el propio de la persona, si lo tiene, manda | resolveSessionTimeoutMinutes |
| Pantalla de inicio | La primera ruta legible: solo un Cajero que no tiene otro perfil cae en Pago; Cajero + Tesorería cae en el Dashboard | firstAllowedRoute() |
| Encabezado | «Rol · PAÍS» por asignación, desde 1024 px | AppLayout.vue |
| Manual | En pantalla, la unión; el PDF es por rol, no por persona (se arma con la matriz sembrada de cada rol) | ManualPdfService |
Alternativa descartada: un selector de perfil (o una «asignación activa»). Por qué no:
- Dentro de un mismo país no hay nada que el cliente haya definido. Lo que el cliente confirmó el 2026-07-24 es que una persona tiene roles distintos por país y que un Supervisor puede estar a cargo de varios PDVs (análisis funcional,
02-roles-permisos.md§2.3). Que dentro de un mismo país se sumen las opciones es el diseño de este ADR desde B6 y no se les había consultado: la captura del cliente de «Cajero y Admin» en el mismo país (img 31) es justo el caso que esa confirmación no cubre. El argumento para no hacer el selector es técnico, no de autoridad. - Una Tesorería regional necesita todas sus asignaciones en el mismo pedido para ver la Holding global (D3-T1): con una «asignación activa» tendría que ir cambiando de contexto para sumar los países.
- Un selector solo escondería opciones; no agregaría control. La persona seguiría teniendo ambos permisos, y el backend también: el control no está en qué perfil se elige sino en qué asignaciones se le dan a cada persona. Para que fuera control real habría que mandar la asignación activa en cada pedido y hacer que cada
allows(), cadaperm:y cada controller filtren por ella: toca el middleware,/me, todos los controllers y el frontend, y suma una forma nueva de equivocarse (un pedido sin contexto). - Con B6, el Admin contiene todo lo del Cajero: «Cajero más Admin» ve exactamente el menú del Admin, que es la captura que el cliente mandó como ejemplo de «mezcla».
Qué cuesta no tenerlo. Quien tiene dos perfiles ve un menú más largo del que usa a diario, y no puede «verse como» uno solo (para eso se le dejan solo las asignaciones que necesita). Las combinaciones sensibles dependen de quien da las asignaciones, y hoy nada las avisa ni las impide (más abajo). Se reabre si la mezcla produce un riesgo que ni la documentación ni una advertencia cubran.
Lo que sí corresponde hacer, y no es un selector. (1) Documentarlo: el manual, la ficha de usuario (que dice que los permisos son la suma de las asignaciones, país por país, y que la matriz que dibuja es por rol) y esta sección. (2) Cerrar las tres fugas que causaba la unión: H3-01 (el nombre del beneficiario en el Estado de Situación se decidía con allows(transacciones:read) sobre la unión, así que un Cajero + Tesorería lo recibía; desde G8 se decide con «es Supervisor» dentro de una misma asignación y por PDV —stationIdsWhereAssignmentHolds(SUPERVISOR_DE_TRANSACCIONES), la señal que usa el listado, pero contestada fila por fila—, porque por país no alcanza: un Supervisor de un PDV que además es Tesorería lee Reportes de todo el país y recibiría el nombre de los pagos de PDVs donde no supervisa), H3-02 (el selector de país de Estado de Situación, Cajas, Volumen y Reporte individual ofrecía países donde el permiso no rige y la primera carga daba 403; desde G8 ofrece solo donde el permiso de esa pantalla rige) y H3-03 (el saldo de Saldos, cerrada en G6). (3) Evaluar «supervisor» dentro de una misma asignación en todo lo nuevo que lo necesite.
Combinaciones sensibles (decisión D3-24 (a), 2026-10-04: solo documentadas; no hay advertencia al asignar ni control preventivo en el backend). Todas, con asignaciones del mismo país salvo que se diga otra cosa:
| Combinación | Qué pasa | Cobertura |
|---|---|---|
| Cajero + Tesorería | Fondea y ajusta la caja con la que paga (fondeo_caja:write no compara con quien abrió la sesión): arma toda la cadena del dinero. El control es el libro inmutable y la Auditoría (CASH_FUNDED, CASH_ADJUSTED), que es lo que ADR-007 §4 eligió | Documentada; test de caracterización test_cajero_mas_tesoreria_fondea_y_ajusta_la_caja_que_abrio_y_queda_en_auditoria. Un control preventivo (D3-24 c) se descartó: cambia una regla de caja que Tesorería pidió detectiva y también tocaría al Admin |
| Cajero + Tesorería, soportes, listado y Estado de Situación | No se eleva a «supervisor» por sumar permisos: en el Reporte individual ve solo lo que pagó, no sube soportes ajenos y en el Estado de Situación no ve el nombre del beneficiario | Tests test_cajero_mas_tesoreria_en_el_mismo_pais_sigue_acotado_a_lo_propio y test_cajero_mas_tesoreria_no_lee_el_nombre_del_beneficiario_en_el_estado_de_situacion (H3-01) |
| Supervisor de un PDV + Tesorería (revisión de G8) | Tesorería le abre el Estado de Situación de todos los PDVs del país, pero el nombre del beneficiario solo le llega en los pagos de su PDV (y en la bolsa compartida, que el listado también le muestra); en los demás ve el MTCN y los montos, sin el nombre. Es el caso de transición «quien hacía tesorería con el rol Supervisor» si conserva su PDV | Test test_supervisor_de_un_pdv_mas_tesoreria_lee_el_nombre_solo_de_los_pagos_de_su_pdv |
| Cajero de un PDV + Supervisor de otro | En el Reporte individual ve las transacciones resueltas de los dos PDVs, también lo que pagó otra persona en el PDV donde solo es Cajero (el listado evalúa «supervisa» por país y une el alcance de PDV de las dos asignaciones); los saldos de caja, el cierre de cajas ajenas, el reemplazo de soportes y el nombre del beneficiario en el Estado de Situación sí se deciden por PDV y dentro de una misma asignación, así que valen solo en el PDV donde es Supervisor | Test de caracterización test_cajero_de_un_pdv_mas_supervisor_de_otro_ve_las_transacciones_resueltas_de_los_dos (si el listado pasa a evaluarse por PDV, ese test cambia a propósito) |
| Supervisor + Tesorería | El estado de tesorería anterior a B6: paga, abre cajas y supervisa, más mueve la plata | Documentada en el manual |
| Admin + cualquier perfil (mismo país) | Sin riesgo: la unión es Admin; solo suma alcance de PDV y un PDV activo | Tests de caracterización: ninguna celda de ningún perfil supera al Admin, y Admin + X recibe las mismas respuestas que el Admin solo |
| Perfil bajo en un país + Admin en otro | Pagar, cancelar y los saldos son por país, pero los ABMs, la Configuración y la Auditoría no tienen país (los gatea perm: sobre cualquier asignación): con Admin en un solo país, la persona los tiene para todo el sistema. Para abm_asignacion_roles ya estaba dicho en Consequences | Documentada |
| Dos asignaciones del mismo país con un PDV activo distinto | El PDV que se graba al pagar es el de la asignación más antigua (G4, ADR-020) | Test PermissionServiceTransactionScopeTest::test_el_pdv_activo_de_la_asignacion_mas_antigua_gana_en_cualquier_orden_de_lectura |
7. La lista de módulos sale del backend (B6.6)
GET /admin/roles-permisos devuelve, además de los roles, modules: la lista completa y ordenada de los módulos de la matriz con su etiqueta en español. La fuente es App\Support\PermissionModules; un test falla si RoleSeeder::MATRIX tiene un módulo sin etiqueta o la lista tiene uno que la matriz no conoce. La ficha de usuario y la pantalla de roles dibujan lo que reciben: un módulo nuevo ya no puede quedar fuera de la pantalla.
8. Cómo llega a las bases existentes
Por migración de datos (2026_10_02_130000_b6_perfiles_y_matriz_de_cuatro_roles.php), no por «correr el seeder»: el deploy solo corre migrate, y RoleSeeder pisa lo que un Admin editó desde la app. En este orden y dentro de una transacción:
- Renombra la fila
BackofficeaCajero(y le cambia la descripción). Si no existeBackoffice, o ya está renombrada, no hace nada. Si existen los dos roles yBackofficetodavía tiene usuarios, falla y corta el deploy: elegir un ganador a ciegas movería gente de rol. - Crea el rol
Tesorería, solo en una base que ya tiene alguno de los perfiles (una base vacía, como la de los tests o unmigratelimpio antes dedb:seed, no recibe roles de más). - Fija celda por celda los cambios de la matriz, sin los eventos del modelo (
RolePermission::withoutEvents): el hooksavingfuerzacan_delete ⇒ can_write ⇒ can_ready ya rompió la pantalla Pago una vez.
Las reglas: las celdas que no están en la lista no se tocan (un permiso que el Admin editó en otra celda queda como está); las que sí están en la lista se fijan al valor objetivo aunque el Admin las haya editado, porque es una política que pidió el cliente y no una sugerencia; es idempotente; y deja un evento de Auditoría sin usuario por cada cambio (ROLE_RENAMED_BY_MIGRATION, ROLE_CREATED_BY_MIGRATION, ROLE_PERMISSION_GRANTED_BY_MIGRATION, ROLE_PERMISSION_CHANGED_BY_MIGRATION), con nombres de rol, módulo y marcas, nada más.
RoleSeeder::MATRIX y DESCRIPTIONS quedan iguales al resultado de la migración, para las bases nuevas, y un test compara las dos celda por celda sobre una base con la matriz vieja.
9. El menú se ordena por lo que hace cada perfil (B6.4)
El cliente también pidió reorganizar el menú. Cambian las etiquetas y la agrupación; no cambian las claves de módulo, los name de las rutas ni los data-tour (renombrarlos tocaría rutas, controllers, base, manual y todos los tests, y no aporta nada). Cada ítem sigue a su permiso: no hay ningún caso escrito para un perfil.
| Grupo | Ítem | Antes | Módulo que lo habilita |
|---|---|---|---|
| General | Dashboard | igual | dashboard |
| Caja (antes «Operación») | Pago | igual | pago |
| Reporte individual | Transacciones | transacciones | |
| Saldos | Caja | caja | |
| Tesorería (nuevo) | Prefondeo Soterex | Prefondeo Holding | prefondeo |
| Fondeo PDVs | Prefondeo País | prefondeo_pais | |
| Tipo de cambio | pestaña de Ubicaciones | tipo_cambio | |
| Reportes | Reportes | igual | reportes o reporte_cumplimiento |
| Administración | Usuarios y Accesos | igual | abm_usuarios, abm_roles_permisos o abm_asignacion_roles |
| Parámetros | Ubicaciones | abm_paises, abm_estaciones o abm_catalogos | |
| Configuración | igual | abm_configuracion | |
| Auditoría | estaba en «Operación» | auditoria | |
| Documentación | Funcional, Manual del Usuario, Referencia de API | igual | — |
Lo que hay que saber de cómo quedó, porque no sale de la tabla:
- «Fondeo PDVs» se habilita hoy solo con
prefondeo_pais. El plan lo previó paraprefondeo_paisofondeo_caja; la segunda mitad llega con B7, que le suma a esa pantalla la pestaña de movimientos por PDV (la que leefondeo_caja). Abrirla antes dejaría entrar al Supervisor —que leefondeo_cajapero noprefondeo_pais— a una pantalla que el backend le responde con 403. Actualización (B7, 2026-10-02): hecho. La ruta y el ítem se abren aprefondeo_paisofondeo_caja, y el Supervisor ve solo la pestaña PDV de sus PDVs; ver ADR-015 §10. La decisión de arriba no cambia: se cumplió la segunda mitad que estaba prevista. - Tipo de cambio tiene ruta propia,
/tipo-cambio(mismoname,admin-tipo-cambio). La URL vieja,/admin/ubicaciones/tipo-cambio, redirige. «Parámetros» conserva el path/admin/ubicacionesy pierde esa pestaña (le quedan Países, Estaciones / PDV y Catálogos). Como el Cajero y el Supervisor leen el tipo de cambio, el grupo «Tesorería» les muestra un único ítem: es consecuencia literal de la matriz, y se saca con una celda. Actualización (G8, 2026-10-07): se sacó. Desde G8 el Cajero no ve el grupo «Tesorería» y el Supervisor ve solo «Fondeo PDVs»; ver la actualización del final. - A qué pantalla cae cada perfil lo sigue decidiendo
firstAllowedRoute()(la primera ruta que puede leer, en el orden del sitemap), no el nombre del rol: el Cajero en Pago; Supervisor, Tesorería y Admin en el Dashboard. Una Tesorería sin Dashboard caería en Prefondeo Soterex. - La barra inferior del celular suma los destinos de Tesorería (sin ellos ese perfil no podía llegar a Fondeo PDVs ni a Tipo de cambio desde un teléfono). El Admin tiene ocho destinos y no entran en 375 px: la barra muestra cinco y un botón «Más» abre el panel con el resto, con los nombres completos. Desde B7, con Fondeo PDVs abierto, el Supervisor también tiene siete y pasa por lo mismo. (Desde G8, 2026-10-07, sin el tipo de cambio, el Supervisor vuelve a tener seis y le entran todos en la barra, sin «Más»; el Cajero tiene tres.)
Qué reemplaza
| Decisión anterior | Dónde estaba | Qué pasa ahora |
|---|---|---|
| Tesorería opera con el rol Supervisor, sin rol aparte | Carlos, 2026-08-06 (plan E4b); comentario de RoleSeeder | Tesorería es un perfil propio |
| Solo el Supervisor fondea y ajusta cajas | Plan v2 decisión #11 / #7; ADR-005 | Fondean Tesorería y Admin; el Supervisor ve |
| El tipo de cambio lo editan Admin y Supervisor | Plan v2 decisión #16; ADR-005 | Lo editan Tesorería y Admin; el Supervisor y el Cajero leen (desde G8, 2026-10-07, tampoco lo leen: es solo de Tesorería y Admin) |
| Auditoría visible para Backoffice y Supervisor | Carlos, 2026-07-29 (mockup de Pago) | Solo Admin |
| «Los perfiles no se tocan» | Carlos, 2026-09-28 (ajustes v1) | Valía para la entrega v1 |
| Prefondeo Holding y País visibles para el Supervisor | Matriz del 2026-08-05 | Solo Tesorería y Admin |
| La comisión del Dashboard la ve solo el rol Supervisor | doc/plans/2026-07-25-restringir-comision.md | La ve quien tiene prefondeo:read |
Pagar y cancelar con transacciones:write | E2 | pago:write y transacciones:delete |
Consequences
- El deploy cambia permisos de usuarios reales de staging en el momento en que corre la migración. Quien hoy carga prefondeos o fondea cajas con rol Supervisor (tesorería) pierde ese acceso hasta que se le asigne el rol Tesorería desde Asignación de Roles. Hay que avisarle a Magaly antes del deploy y tener las asignaciones listas.
- Los Cajeros pierden Auditoría; los Supervisores pierden Auditoría, Prefondeo (los dos) y la edición del tipo de cambio y de los fondeos; los Cajeros y los Supervisores no pueden cancelar. Los Supervisores ganan la pantalla Pago (
pagoL·E): como pagar ahora exigepago:write, hace falta para que sigan pudiendo pagar; sigue cayendo en el Dashboard, que va antes en el orden de inicio. - Los Admin pasan a poder pagar (necesitan una caja abierta a su nombre, como cualquiera en un país con módulo Caja) y a ver la comisión en el Dashboard.
- Tesorería nace sin usuarios: hasta que alguien le asigne el rol, nadie puede cargar prefondeos que no sea Admin.
- Los permisos de un usuario son la unión de sus asignaciones. A quien hoy opera prefondeos con el rol Supervisor y se le suma Tesorería, la asignación de Supervisor le sigue dando lo que el Supervisor conserva (Pago, Transacciones, apertura y cierre de caja). Si tesorería no tiene que operar transacciones, hay que quitarle la asignación de Supervisor, no solo sumarle la de Tesorería. Lo que el sistema sí evita (punto 6) es que la combinación Cajero + Tesorería amplíe lo que ve de transacciones.
- Reportes y lo que ve cada perfil (revisión de B6). El Estado de Situación y su export traen, por cada pago, MTCN, monto, comisión y PDV a cualquiera con
reportes:read, y desde esta entrega eso incluye a Tesorería, que no tiene permiso sobre transacciones. Se decidió así, por dato:- El nombre del beneficiario solo sale para quien tiene
transacciones:readen el país (Supervisor, Admin). A Tesorería le lleganullen la pantalla y en el Excel/PDF: es un dato de ventanilla que no necesita para conciliar, y es lo que prescribe el plan para los extractos de B7 (MTCN y montos, nunca datos del beneficiario). Es reversible: se saca el chequeo del nombre deReportesController::loadSituacionData. (Desde G8 el chequeo es «Supervisor o Admin de ese PDV, dentro de una misma asignación», notransacciones:readsobre la unión: ver el punto 6.) - La comisión sigue viajando en Reportes, donde siempre estuvo y donde el dato debe verse (restringir-comision). P11 la saca del Dashboard del Supervisor, no de Reportes.
- Abierta, para Carlos: el Supervisor sigue viendo el prefondeo de Soterex por el Estado de Situación. Perdió
prefondeo(el menú y/prefondeolo esconden y responden 403), pero conservareportes:read, y el Estado de Situación trae los asientos de prefondeo del país, el total cargado, el saldo actual y, sin filtro de PDV, el saldo inicial y el balance final de cada fila (C10 lo pidió el cliente en esa pantalla). No se cambió porque ocultarlo deja al Supervisor sin la columna «Balance final» que el cliente pidió para ese reporte, y esa es una decisión de producto, no de la matriz. Un test (PerfilesAccesoApiTest) fija el comportamiento de hoy para que cambiarlo no sea un accidente. Si se decide cerrarlo, la opción es omitir deloadSituacionDatalos asientos,prefunding_total,balance,opening_balancey el corrido cuando el usuario no tieneprefondeo:readen el país (y ajustar el test).
- El nombre del beneficiario solo sale para quien tiene
- El tipo de cambio se valida por país. El gate de la ruta (
perm:tipo_cambio) pasa si cualquier asignación del usuario tiene el permiso; la revisión de B6 encontró queExchangeRateControllerno volvía a preguntar en el país de la URL, así que un Tesorería de un país podía fijarle el tipo de cambio a otro. Ahoraindex()ystore()piden el permiso en el país (403PERMISSION_DENIED), como Prefondeo y Prefondeo País;paises()no responde 403: lista solo los países donde el usuario tienetipo_cambio:read. (Desde G8 el gate de la ruta,perm:tipo_cambio,read, ya no lo pasa el Cajero ni el Supervisor: ambos endpoints les dan 403.) abm_asignacion_roles:writeequivale a ser Admin. Asignar un rol a un usuario no comprueba que el actor tenga los permisos del rol (editar la matriz sí:PERMISSION_ESCALATION_DENIED). Con la matriz sembrada solo el Admin tiene ese permiso, así que no hay escalada hoy; si un Admin se lo delega a otro perfil desde la ficha de usuario —B6.6 lo facilita, ahora se editan los 19 módulos—, ese perfil puede darse el rol Admin. Endurecerlo (rechazar asignar un rol con celdas que el actor no tiene) es una mejora aparte, fuera de B6.- La migración pisa las nueve celdas de su lista aunque un Admin las haya editado (punto 8): es la política que pidió el cliente y no un valor inicial, pero choca con la regla general de que una migración de datos no pisa lo que editó un Admin. Queda registrado en Auditoría con el antes y el después de cada celda, y staging.md trae una consulta de solo lectura para ver, antes del deploy, cuáles celdas se van a pisar.
- Revisión de seguridad. B6 pasó, antes del PR, por dos revisiones dedicadas a permisos y privacidad (2026-10-02). Sus hallazgos se resolvieron en la misma rama —alcance por país del tipo de cambio, nombre del beneficiario en Reportes, contraseña de la cuenta de Tesorería de Staging, tests de pagar y cancelar entre países— o quedaron escritos acá como decisiones abiertas (el prefondeo del Supervisor en Reportes,
abm_asignacion_roles). - El manual en PDF por rol pasa a generar cuatro documentos (el comando itera
RoleSeeder::MATRIX). - Los textos del frontend que nombran roles y pantallas, el menú (punto 9), los botones de Pago y la ficha de usuario se resolvieron en la misma entrega; las claves de módulo, los
namede las rutas y losdata-tourno cambian. - El Cajero ve el grupo «Tesorería» con un solo ítem («Tipo de cambio», en solo lectura), y el Supervisor, desde B7, con dos: «Fondeo PDVs» (solo la pestaña PDV, la de sus PDVs; ADR-015 §10) y «Tipo de cambio». Lo veían antes dentro de «Ubicaciones». Si no lo quieren, es la celda
tipo_cambiode esos dos perfiles. No lo quisieron (su hoja de menús reserva el tipo de cambio a Administrador y Tesorería): desde G8 (2026-10-07) el Cajero no ve el grupo «Tesorería» y el Supervisor ve solo «Fondeo PDVs». - Los datos de prueba cambian con el perfil.
DevUserSeederyStagingTestUsersSeedersuman atesoreria@cislatam.test(el Cajero conserva el mailbackoffice@, que ya existe en Firebase), y la demo (demo:reseed) firma los prefondeos, el tipo de cambio y los fondeos de caja con ese usuario, no con el Supervisor. Correr el seeder de Staging, que crea una cuenta en el Firebase real, lo decide Carlos.
Alternatives Considered
- Crear un rol
Cajeronuevo y dejarBackofficecomo estaba. Descartada: obliga a reasignar a mano a todos los usuarios (el error exacto que se quería evitar) y deja un rol fantasma en la lista. - Un permiso nuevo para cancelar (
transacciones_cancelar). Descartada:transacciones:deleteya existe, ya es de uso exclusivo del Admin y nadie lo consultaba. Una clave de módulo nueva toca rutas, base, manual y tests para expresar lo mismo. - Dejar a Tesorería como Supervisor con permisos editados a mano. Descartada: es exactamente el estado del que se parte, y el Supervisor de un PDV vería plata que no es de su PDV.
- Una columna «es supervisor» en la asignación, en lugar de derivarlo de permisos. Descartada por la misma razón que en ADR-011: es un concepto nuevo para algo que la matriz ya sabe decir.
- Que el Admin solo cancele, sin pagar (la versión original de P6). Reemplazada por la decisión de Carlos del 2026-10-02.
- Un permiso propio para la comisión del Dashboard, en lugar de
prefondeo:read. Descartada: quien ve el saldo del Holding ya ve de dónde sale la comisión; un permiso más para la misma audiencia es ruido.
Revertir
Todo es una celda de la matriz, editable desde la app, excepto el renombre (que es de datos y no necesita reversa: el nombre Cajero es el que pidió el cliente). La separación de pagar y cancelar se revierte cambiando dos perm: de routes/api.php y el módulo que consulta authorizeScope en pay() y cancel(). El menú es la lista NAV de frontend/src/layouts/AppLayout.vue y las rutas de frontend/src/router/index.ts: volver al agrupamiento anterior no toca permisos.
Actualización — G6 (2026-10-06): ver los saldos de las cajas se decide por PDV
El punto 6 dice que «¿ve el saldo de todas las cajas?» (canSeeAllCashBoxes) es fondeo_caja:read en el país. Con perfiles mezclados eso era demasiado: un Supervisor del PDV A que además es Cajero del PDV B veía el saldo y los movimientos reales de las cajas de B (H3-03). Ahora la pregunta lleva el PDV de la caja y la responde una asignación que cubra ese PDV (PermissionService::assignmentHolds), y GET /caja/totales-pdv cruza el alcance de caja:read con el de fondeo_caja:read. La fila de canSeeBalance de la tabla del punto 6 sigue igual para Tesorería (ve todo lo que alcanza su caja:read). La decisión, la regla de quién cierra una caja ajena (que usa la misma idea de «una misma asignación») y las consecuencias están en ADR-021.
Actualización — G8 (2026-10-07): el tipo de cambio sale del Cajero y del Supervisor
Decisión D3-11 (a), de Carlos (plan de ajustes v3, RV3-35 y RV3-47): el tipo de cambio es de Tesorería y Admin. B6 le había dejado la lectura al Cajero y al Supervisor (§9: «si no lo quieren, es la celda tipo_cambio de esos dos perfiles»); la hoja de menús del cliente lo reserva a Administrador y Tesorería, y nada operativo lo necesita: pay() lee el tipo de cambio vigente por ExchangeRateService, sin pasar por el permiso, y Guatemala paga en dólares.
| Módulo | Perfil | Antes (B6) | Desde G8 |
|---|---|---|---|
tipo_cambio | Cajero | L | — |
tipo_cambio | Supervisor | L | — |
tipo_cambio | Tesorería · Admin | L E · L E B | igual |
- Qué cambia.
GET /tipo-cambio/{pais}yGET /tipo-cambio/paisesresponden 403 al Cajero y al Supervisor y 200 a Tesorería y Admin; el ítem «Tipo de cambio» desaparece de su menú, no entran por la URL (/tipo-cambioni la vieja/admin/ubicaciones/tipo-cambio), la barra del celular del Cajero baja a tres destinos y el manual en PDF pierde la sección (Cajero 6 secciones, Supervisor 9; Tesorería 9 y Admin 20 no cambian). Pagar no cambia, tampoco en un país que convierte a moneda local: lo cubre un test que paga como Cajero y como Supervisor. - Cómo llega a las bases existentes: por una migración de datos nueva (
2026_10_07_000236_v3_tipo_de_cambio_solo_tesoreria_y_admin.php); la de B6 ya corrió en Staging y no se edita. Es la misma mecánica del punto 8: fija las dos celdas a 0/0/0, pisa lo que un Admin haya editado en esas dos (es una política del cliente, no un valor inicial), no toca ninguna otra celda, escribe sin los eventos del modelo (RolePermission::withoutEvents), deja unROLE_PERMISSION_CHANGED_BY_MIGRATIONpor celda, es idempotente y no tienedown()(devolver la lectura sería abrir un acceso con unmigrate:rollback).RoleSeeder::MATRIXydoc/architecture/matriz-de-perfiles.jsoncambian en el mismo commit, yPerfilesMigrationTestcompara matriz, JSON y el resultado de las dos migraciones encadenadas, en orden (si se agrega otra migración que mueva la matriz, se encadena después de estas dos enmigrar()). - Cambia permisos de usuarios reales de Staging en el momento del deploy, igual que B6: el cliente está probando con cuentas de Cajero y de Supervisor. Hay que avisarle antes (pregunta QC-17 del plan) y recién entonces mergear y desplegar; el runbook, con las consultas de solo lectura, está en staging.md.
- Para ver la matriz entera, no solo estas dos celdas: el comando de solo lectura
php artisan permisos:diferenciascompara las 80 celdas (76 hasta L3, ADR-029) derole_permissionsconRoleSeeder::MATRIX(H3-04), sin imprimir ningún dato personal. La consulta previa de B6 cubría nueve celdas. - Revertir es una celda en Roles y Permisos (o una migración nueva): no hace falta tocar código.

