Skip to content

Plan de Pruebas — G8: perfiles, tipo de cambio y perfiles mezclados ​

Fecha: 2026-10-07 Decisión: ADR-014 §1 (Tesorería regional), §6 (la mezcla es intencional) y la actualización de G8 (tipo de cambio) · plan de ajustes v3, entrega G8 (RV3-35, 41, 47, 49, 51, 85, H3-01, H3-02, H3-04; decisiones D3-11, D3-24 a, D3-T1 y D3-T2) Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba

Qué cambió: el tipo de cambio es solo de Tesorería y Admin (el Cajero y el Supervisor lo veían de solo lectura y ya no: 403 por API, sin ítem en el menú y sin entrar por URL); Reportes deja de mostrarle el nombre del beneficiario a quien suma Cajero y Tesorería (H3-01) y ofrece solo los países donde la persona tiene ese permiso (H3-02); hay un comando de solo lectura, permisos:diferencias, que compara las 76 celdas de permisos con la matriz de fábrica (H3-04); y la documentación dice que con más de un perfil se mezclan las opciones y no hay selector de perfil. Cambia permisos de usuarios reales por una migración de datos: en Staging hay que avisar al cliente antes del deploy (runbook en staging.md). Ver el manual y el análisis funcional de Roles y Permisos, 2.3.

Antes de empezar ​

Usuarios (las contraseñas están en doc/environments/dev.md):

EmailPerfilAlcancePara qué sirve acá
backoffice@cislatam.testCajeroGT-CAP-001Ya no ve el tipo de cambio
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002Ya no ve el tipo de cambio; sí Fondeo PDVs
tesoreria@cislatam.testTesoreríaGuatemala, todos los PDVSigue viendo y cargando el tipo de cambio
admin@cislatam.testAdminGuatemala, todos los PDVSin cambios; mira Auditoría y arma las cuentas mixtas
Una cuenta mixta (mezcla@cislatam.test)La que arme cada casoLa que arme cada casoEs una sola cuenta a la que se le cambian las asignaciones entre caso y caso (sección 5). No existe en dev: se crea desde Usuarios y Accesos con admin@ (alta por correo; la contraseña se muestra una sola vez, copiarla)

La base local tiene que tener la migración. docker exec soterex-backend-1 php artisan migrate (si ya corrió, dice Nothing to migrate). No correr db:seed para "arreglar" nada: pisa permisos que se editaron desde la app (ver dev.md).

El país de las cuentas mixtas. En dev solo Guatemala está activo con módulo Caja; El Salvador (SV) y Honduras existen pero inactivos. Alcanza para estas pruebas: el selector de asignaciones los ofrece igual. Los casos de la sección 5 dicen cuándo hace falta cada uno.


1. La matriz y la migración ​

#PasoResultado esperado
1.1docker exec soterex-backend-1 php artisan migrateNothing to migrate (o aplica 2026_10_07_000236_v3_tipo_de_cambio_solo_tesoreria_y_admin). Una segunda corrida no cambia nada
1.2En Adminer: select r.name, rp.can_read, rp.can_write, rp.can_delete from role_permissions rp join roles r on r.id = rp.role_id where rp.module = 'tipo_cambio' order by r.nameAdmin t,t,t · Cajero f,f,f · Supervisor f,f,f · Tesorería t,t,f
1.3docker exec soterex-backend-1 php artisan permisos:diferenciasImprime «Matriz sembrada (RoleSeeder::MATRIX) contra role_permissions: 76 celdas (4 perfiles × 19 módulos)…» y «Sin diferencias: la base tiene exactamente la matriz del seeder.» No imprime ningún correo ni nombre de persona
1.4Con una celda cambiada a mano (por ejemplo, darle a Cajero la escritura de tipo_cambio desde Usuarios y Accesos → ficha de un Cajero → matriz), volver a correr el comandoLista una diferencia: «Cajero · tipo_cambio: la base tiene LE-, la matriz ---». El comando no escribe nada (la celda sigue como la dejaste). Restaurar la celda al terminar
1.5Como admin@, Auditoría, filtrar por la acción Permiso cambiado por un deployEn una base donde corrió la migración, hay dos eventos: Cajero · tipo_cambio y Supervisor · tipo_cambio, de L-- a ---, sin usuario y sin ningún dato personal
1.6Como admin@, abrir la ficha de un Cajero → Matriz del rolLa fila Tipo de cambio está sin ninguna casilla. En la ficha de una persona de Tesorería, con Lectura y Escritura

2. El menú y las URL de cada perfil ​

Mirar cada perfil en pantalla grande (1280 px) y en el celular (375 px).

#PerfilMenú lateralBarra del celular
2.1backoffice@ (Cajero)Caja: Pago, Reporte individual, Saldos · Documentación. No hay grupo TesoreríaTres destinos (Pago, Reporte individual, Saldos), sin «Más». Cae en Pago al entrar
2.2supervisor@ (Supervisor)General: Dashboard · Caja: Pago, Reporte individual, Saldos · Tesorería: solo Fondeo PDVs · Reportes · DocumentaciónSeis destinos, todos en la barra, sin «Más». Cae en el Dashboard
2.3tesoreria@ (Tesorería)Dashboard · Saldos · Tesorería: Prefondeo Soterex, Fondeo PDVs, Tipo de cambio · Reportes · DocumentaciónSeis destinos, sin «Más»
2.4admin@ (Admin)TodoCinco destinos y «Más», que abre los otros tres
#PasoResultado esperado
2.5Como backoffice@, escribir en la barra de direcciones /tipo-cambioNo abre: lo manda a Pago (su primera pantalla). Lo mismo con la URL vieja /admin/ubicaciones/tipo-cambio
2.6Como supervisor@, lo mismoNo abre: lo manda al Dashboard
2.7Como supervisor@, entrar a Fondeo PDVsVe solo la pestaña PDV, con los extractos de GT-CAP-001 y GT-QUE-002 (regresión de B7)
2.8Como tesoreria@ y como admin@, entrar a Tipo de cambioAbre, con el vigente y el historial. tesoreria@ puede cargar uno nuevo (si Guatemala paga en dólares, la pantalla igual funciona)
2.9Modo oscuro y 375 px en el menú de cada perfilSe lee; los destinos no se cortan

3. Por API: el tipo de cambio y que pagar siga andando ​

Cada pedido, con el token del usuario (ver «Por API», más abajo).

#PedidoResultado esperado
3.1GET /tipo-cambio/{id de Guatemala} y GET /tipo-cambio/paises con backoffice@403 los dos
3.2Lo mismo con supervisor@403 los dos
3.3Lo mismo con tesoreria@ y con admin@200 los dos; paises lista los países con módulo Caja
3.4POST /tipo-cambio/{id} con backoffice@ y con supervisor@403 (ya lo era; no puede haber un camino de escritura sin el de lectura)
3.5Como backoffice@, abrir su caja y pagar una transacción en GuatemalaPaga como siempre: el tipo de cambio no pasa por el permiso. (Un país que paga en moneda local también: lo cubre PerfilesAccesoApiTest, ver el final)
3.6Como supervisor@ (con una caja abierta o con PDV activo), pagarIgual: paga

4. Reportes: dos fugas de la mezcla (H3-01 y H3-02) ​

Hacen falta transacciones pagadas por otra persona en Guatemala (php artisan demo:reseed las deja; solo contra la base local).

#PasoResultado esperado
4.1Como supervisor@, Reportes → Estado de Situación, país GuatemalaLa columna del beneficiario muestra el nombre de cada pago
4.2Como admin@, lo mismoMuestra el nombre. El Excel también
4.3Como tesoreria@, lo mismoSin nombre (vacío), en la pantalla y en el Excel y el PDF. Sí ve MTCN, monto, comisión y PDV
4.4Con la cuenta mixta con Cajero y Tesorería en Guatemala (caso 5.2), lo mismoSin nombre, igual que Tesorería sola. Antes de G8 lo recibía
4.4bCon la cuenta mixta con Supervisor en GT-CAP-001 y Tesorería en Guatemala (sin acotar), lo mismo, mirando un pago de GT-QUE-002 (otro PDV) y uno de GT-CAP-001El pago de GT-CAP-001 sí muestra el nombre; el de GT-QUE-002 figura (MTCN, monto, comisión y PDV) pero sin nombre, en la pantalla y en el Excel y el PDF. En Reporte individual esa cuenta tampoco ve el pago de GT-QUE-002 (revisión de G8)
4.5Con la cuenta mixta con Cajero en Guatemala y Tesorería en El Salvador (caso 5.1), entrar a Reportes → Estado de Situación, Cajas y VolumenLa primera carga no da 403 (antes arrancaba en Guatemala, el primer país de la lista). Con un solo país posible, Estado de Situación y Cajas no dibujan selector y cargan El Salvador directo; Volumen sí lo muestra y ofrece «Todos los países» y El Salvador, sin Guatemala
4.6Con la misma cuenta, el selector de país del Reporte individualOfrece solo Guatemala (donde tiene transacciones): queda deshabilitado, con un único país además de «Todos los países»
4.7Lo mismo, por API: GET /reportes/situacion?country_id={Guatemala} con la cuenta del 4.5403 (Reportes no rige en Guatemala para esa cuenta). Con el id de El Salvador, 200

5. Perfiles mezclados (D3-T2): se suman, país por país, y no hay selector ​

Con admin@, en Usuarios y Accesos, abrir la ficha de la cuenta mixta. Debajo de «Roles y Asignaciones» tiene que decir que los permisos de la persona son la suma de todas sus asignaciones, país por país, y que no hay selector de perfil; y encima de la matriz de cada rol, que es una matriz por rol, no la suma de la persona. Entre caso y caso, quitar las asignaciones de la cuenta y dar las del caso siguiente (recargar la página de la persona antes de mirar).

#Asignaciones de la cuenta mixtaQué mirarResultado esperado
5.1Cajero en Guatemala (GT-CAP-001) y Tesorería en El SalvadorMenú, pantalla de inicio, encabezado, y las pantallas con paísMenú = la suma: Caja (Pago, Reporte individual, Saldos), Tesorería (Prefondeo Soterex, Fondeo PDVs, Tipo de cambio), Dashboard, Reportes y Documentación. Cae en el Dashboard (no en Pago). El encabezado, desde 1024 px, dice «Cajero · GT · Tesorería · SV». Pago opera sobre Guatemala; Prefondeo Soterex y Reportes ofrecen El Salvador. La barra del celular lleva cinco destinos y «Más»; lo que no entra en la barra está ahí
5.2Cajero y Tesorería, los dos en GuatemalaReporte individual, soportes, cajaEn el Reporte individual ve solo lo que pagó él, no lo que pagó otra persona (no es Supervisor). No puede subir un soporte a una transacción de otro (403 CANNOT_MANAGE_DOCUMENTS). Sí puede abrir una caja y fondearla y ajustarla ella misma: es la combinación a evitar del manual, y el sistema no la frena
5.3Lo mismo que 5.2: después de fondear y ajustar, mirar el rastroEn Adminer, select action, user_id, created_at from audit_logs where action in ('CASH_FUNDED', 'CASH_ADJUSTED') order by created_at desc limit 5 trae un CASH_FUNDED y un CASH_ADJUSTED con el user_id de la cuenta mixta (esas dos acciones no están en el filtro de acciones de la pantalla Auditoría; ahí se buscan por el correo de la cuenta). Y los dos movimientos de la caja quedan a su nombre en Saldos. Es el control que existe: el libro inmutable de la caja y la Auditoría
5.4Cajero en GT-CAP-001 y Supervisor en GT-QUE-002 (los dos en Guatemala)Reporte individual y SaldosEn el Reporte individual ve las transacciones resueltas de GT-CAP-001 y de GT-QUE-002, también lo que pagó otra persona en GT-CAP-001; no las de un tercer PDV (GT-MIX-003). Los saldos reales y el cierre de cajas ajenas valen solo en GT-QUE-002 (ver el plan de G6, caso 5)
5.5Admin y Cajero, los dos en GuatemalaMenú y pantalla de inicioExactamente el menú y el comportamiento de admin@: el Admin ya incluye lo del Cajero. Cae en el Dashboard
5.6Cajero en Guatemala y Admin en El SalvadorAdministraciónLa persona administra todo el sistema (Usuarios y Accesos, Parámetros, Configuración, Auditoría), no solo El Salvador: esos permisos no tienen país. Pagar, cancelar y los saldos siguen siendo por país: lo del Admin rige solo en El Salvador, y en Guatemala sigue siendo Cajero (no cancela). Es la penúltima combinación del manual
5.7Cualquiera de las anteriores, mirando el manual de la app (/documentacion/manual-usuario)Botones de PDF y texto de arribaMuestra la suma de las secciones de sus perfiles y un botón de PDF por cada perfil que tiene; arriba dice que el PDF es por perfil, no por persona
5.8No existe forma de elegir con qué perfil se entraLogin, encabezado, menúNo hay selector, ni al entrar ni en el encabezado. Es una decisión de producto (D3-T2): el manual explica por qué

6. Tesorería: un solo perfil, local o regional según sus asignaciones (D3-T1) ​

#PasoResultado esperado
6.1Dar a la cuenta mixta solo Tesorería en Guatemala (sin PDVs)En Fondeo PDVs ve los extractos de País y de PDV de Guatemala completos. En Prefondeo Soterex, si existe otro país activo o con movimientos, los extractos de la Holding salen con el aviso de extracto parcial (solo Guatemala) y la tarjeta se llama Saldo de la Holding — de sus países y suma solo Guatemala; si los demás países están inactivos y vacíos (la base de dev) no hay aviso y la tarjeta es Saldo con Soterex (G12: los casos con y sin aviso están en su plan de pruebas)
6.2Una asignación de Tesorería en Guatemala acotada a un PDVLos extractos de país (las dos Holding y País) no abren para ella (403 por API): quien tiene que ver un PDV es un Supervisor. El extracto de PDV sí
6.3Intentar cargar un tipo de cambio, un prefondeo o un fondeo en otro país (por API, con la Tesorería de Guatemala)403: las escrituras son siempre por país
6.4Buscar en Usuarios y Accesos si existe un rol «Tesorería Local» o «Regional»No existe: son cuatro roles. «Regional» es una asignación por país

7. El manual en PDF por perfil ​

#PasoResultado esperado
7.1docker exec soterex-backend-1 php artisan manual:generar-pdfGenera cuatro PDF en backend/storage/app/private/manual-pdf/ (Cajero, Supervisor, Tesorería, Admin), con la fecha de hoy. No están versionados en el repo: se regeneran con este comando o con el botón de la propia pantalla del manual
7.2Abrir los cuatroCada portada dice «Rol: …», de qué matriz salió y cuándo se generó. Cajero: 6 secciones; Supervisor: 9; Tesorería: 9; Admin: 20. Ni el del Cajero ni el del Supervisor traen la sección Tipo de cambio (el de Tesorería y el de Admin, sí)
7.3En cualquiera de los cuatro, la sección Perfiles y menúTermina con Si tiene más de una asignación: la suma, país por país, el «Admin ya incluye al Cajero», Tesorería: local o regional y las combinaciones a evitar. Ningún enlace interno queda roto (un enlace a una sección que ese perfil no tiene sale como texto)
7.4En la app, como backoffice@ y como supervisor@, el manual (/documentacion/manual-usuario)Sin la sección Tipo de cambio, ni en el índice

8. No se rompió nada de lo que ya existía ​

#PasoResultado esperado
8.1Como backoffice@, el flujo de siempre: abrir caja, buscar por MTCN, completar, pagar, imprimir la papeleta y cerrarTodo funciona
8.2Como tesoreria@, cargar un tipo de cambio nuevo y mirar el historialSe crea un registro nuevo (el historial es inmutable); el evento queda en Auditoría
8.3Como tesoreria@, fondear una caja abiertaFunciona
8.4Como supervisor@, Reportes → Estado de SituaciónVe los nombres; exporta a Excel y PDF
8.5Como admin@, Roles y Permisos en la ficha de un usuarioSe puede volver a darle la lectura del tipo de cambio al Cajero desde la matriz (es una celda, no código) y quitarla de nuevo
8.6Un usuario con una sola asignaciónNo ve ninguna diferencia respecto de antes salvo lo del tipo de cambio

Por API ​

Con el emulador de Firebase de dev. Cada pedido se corre con el token del usuario que dice el caso.

bash
login() {  # login <email> <password de dev.md>
  curl -s -X POST 'http://localhost:9099/identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=fake-api-key' \
    -H 'Content-Type: application/json' \
    -d "{\"email\":\"$1\",\"password\":\"$2\",\"returnSecureToken\":true}" \
    | python3 -c 'import sys,json;print(json.load(sys.stdin)["idToken"])'
}

TOKEN=$(login backoffice@cislatam.test '<su contraseña>')

# El id de cada país sale de /me (assignments[].country.id)
curl -s -H "Authorization: Bearer $TOKEN" 'http://localhost:3000/me' | python3 -m json.tool

# (a) tipo de cambio             -> 403 con el Cajero y el Supervisor, 200 con Tesorería y Admin
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" 'http://localhost:3000/tipo-cambio/paises'
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" 'http://localhost:3000/tipo-cambio/{id del país}'

# (b) Estado de Situación         -> 200 solo en los países donde la cuenta tiene Reportes; el nombre del beneficiario, solo en los PDVs donde es Supervisor o Admin
curl -s -H "Authorization: Bearer $TOKEN" 'http://localhost:3000/reportes/situacion?country_id={id del país}' | python3 -m json.tool | head -40
#PedidoResultado esperado
aGET /tipo-cambio/paises y GET /tipo-cambio/{país}Cajero y Supervisor 403; Tesorería y Admin 200
bGET /reportes/situacion?country_id=… con una cuenta que suma Cajero y Tesorería en ese país200, y cada fila trae beneficiary: null
cLo mismo con supervisor@ o admin@Cada fila trae el nombre en beneficiary
dGET /reportes/situacion?country_id=… con la cuenta del caso 5.1 y el país donde no tiene Reportes403

Al terminar ​

  • Quitar a la cuenta mixta todas las asignaciones (o desactivarla): una cuenta de prueba más no estorba, pero con asignaciones sueltas confunde otras pruebas.
  • Si se editó una celda para el caso 1.4, devolverla a la matriz de fábrica (permisos:diferencias tiene que volver a decir Sin diferencias).
  • Los cuatro PDF del caso 7.1 no se commitean: están ignorados por git.

Pruebas automatizadas que lo respaldan ​

bash
docker exec soterex-backend-1 php artisan test --filter PerfilesMigrationTest
docker exec soterex-backend-1 php artisan test --filter TipoCambioSoloTesoreriaMigrationTest
docker exec soterex-backend-1 php artisan test --filter PerfilesAccesoApiTest
docker exec soterex-backend-1 php artisan test --filter MeApiTest
docker exec soterex-backend-1 php artisan test --filter PermisosDiferenciasCommandTest
docker exec soterex-backend-1 php artisan test --filter ManualPdfTest
docker exec soterex-frontend-1 sh -c 'cd /app && npx vitest run src/layouts/__tests__/AppLayout.spec.ts src/router/__tests__ src/utils/__tests__/manual.spec.ts src/views/__tests__/ManualUsuarioView.spec.ts src/views/admin/__tests__/UsuariosView.spec.ts src/views/reportes/__tests__ src/views/__tests__/TransaccionesView.spec.ts'

Qué cubre cada una: PerfilesMigrationTest, que la matriz de fábrica, el JSON de doc/architecture/matriz-de-perfiles.json y el resultado de las dos migraciones (la de B6 y la de G8, encadenadas en orden) son la misma, y que correrlas de nuevo no cambia nada; TipoCambioSoloTesoreriaMigrationTest, la migración de G8 sola (las dos celdas, que pisa la edición de un Admin, que no toca ninguna otra celda, que audita cada cambio sin datos personales y que una base sin perfiles no se rompe); PerfilesAccesoApiTest, el 403 del tipo de cambio para el Cajero y el Supervisor y el 200 para Tesorería y Admin, que pagar sigue andando sin el permiso (también en un país que convierte a moneda local), el nombre del beneficiario según perfil (incluido Cajero + Tesorería) y los tests de caracterización de la mezcla: ninguna celda de ningún perfil supera al Admin, «Admin más otro perfil» recibe las mismas respuestas que el Admin solo, Cajero de un PDV más Supervisor de otro ve los dos PDVs, y Cajero más Tesorería fondea y ajusta la caja que abrió con rastro en Auditoría; MeApiTest, que /me devuelve la unión de las asignaciones y que cada una conserva las suyas (en el mismo país y en países distintos) y que con dos plazos de sesión gana el menor; PermisosDiferenciasCommandTest, el comando de solo lectura; ManualPdfTest, las secciones por perfil (6, 9, 9 y 20); y las del frontend, el menú y la barra del celular de cada perfil y de las mezclas, que el Cajero y el Supervisor no entran a /tipo-cambio por URL, la pantalla de inicio de las mezclas, que los selectores de país de Reportes y del Reporte individual ofrecen solo donde rige el permiso, y las dos notas de la ficha de usuario.

Documentación viva — se actualiza junto con el código, no es un anexo aparte.