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):
| Perfil | Alcance | Para qué sirve acá | |
|---|---|---|---|
backoffice@cislatam.test | Cajero | GT-CAP-001 | Ya no ve el tipo de cambio |
supervisor@cislatam.test | Supervisor | GT-CAP-001 y GT-QUE-002 | Ya no ve el tipo de cambio; sí Fondeo PDVs |
tesoreria@cislatam.test | Tesorería | Guatemala, todos los PDV | Sigue viendo y cargando el tipo de cambio |
admin@cislatam.test | Admin | Guatemala, todos los PDV | Sin cambios; mira Auditoría y arma las cuentas mixtas |
Una cuenta mixta (mezcla@cislatam.test) | La que arme cada caso | La que arme cada caso | Es 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
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | docker exec soterex-backend-1 php artisan migrate | Nothing to migrate (o aplica 2026_10_07_000236_v3_tipo_de_cambio_solo_tesoreria_y_admin). Una segunda corrida no cambia nada |
| 1.2 | En 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.name | Admin t,t,t · Cajero f,f,f · Supervisor f,f,f · Tesorería t,t,f |
| 1.3 | docker exec soterex-backend-1 php artisan permisos:diferencias | Imprime «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.4 | Con 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 comando | Lista 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.5 | Como admin@, Auditoría, filtrar por la acción Permiso cambiado por un deploy | En 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.6 | Como admin@, abrir la ficha de un Cajero → Matriz del rol | La 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).
| # | Perfil | Menú lateral | Barra del celular |
|---|---|---|---|
| 2.1 | backoffice@ (Cajero) | Caja: Pago, Reporte individual, Saldos · Documentación. No hay grupo Tesorería | Tres destinos (Pago, Reporte individual, Saldos), sin «Más». Cae en Pago al entrar |
| 2.2 | supervisor@ (Supervisor) | General: Dashboard · Caja: Pago, Reporte individual, Saldos · Tesorería: solo Fondeo PDVs · Reportes · Documentación | Seis destinos, todos en la barra, sin «Más». Cae en el Dashboard |
| 2.3 | tesoreria@ (Tesorería) | Dashboard · Saldos · Tesorería: Prefondeo Soterex, Fondeo PDVs, Tipo de cambio · Reportes · Documentación | Seis destinos, sin «Más» |
| 2.4 | admin@ (Admin) | Todo | Cinco destinos y «Más», que abre los otros tres |
| # | Paso | Resultado esperado |
|---|---|---|
| 2.5 | Como backoffice@, escribir en la barra de direcciones /tipo-cambio | No abre: lo manda a Pago (su primera pantalla). Lo mismo con la URL vieja /admin/ubicaciones/tipo-cambio |
| 2.6 | Como supervisor@, lo mismo | No abre: lo manda al Dashboard |
| 2.7 | Como supervisor@, entrar a Fondeo PDVs | Ve solo la pestaña PDV, con los extractos de GT-CAP-001 y GT-QUE-002 (regresión de B7) |
| 2.8 | Como tesoreria@ y como admin@, entrar a Tipo de cambio | Abre, con el vigente y el historial. tesoreria@ puede cargar uno nuevo (si Guatemala paga en dólares, la pantalla igual funciona) |
| 2.9 | Modo oscuro y 375 px en el menú de cada perfil | Se 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).
| # | Pedido | Resultado esperado |
|---|---|---|
| 3.1 | GET /tipo-cambio/{id de Guatemala} y GET /tipo-cambio/paises con backoffice@ | 403 los dos |
| 3.2 | Lo mismo con supervisor@ | 403 los dos |
| 3.3 | Lo mismo con tesoreria@ y con admin@ | 200 los dos; paises lista los países con módulo Caja |
| 3.4 | POST /tipo-cambio/{id} con backoffice@ y con supervisor@ | 403 (ya lo era; no puede haber un camino de escritura sin el de lectura) |
| 3.5 | Como backoffice@, abrir su caja y pagar una transacción en Guatemala | Paga 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.6 | Como supervisor@ (con una caja abierta o con PDV activo), pagar | Igual: 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).
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Como supervisor@, Reportes → Estado de Situación, país Guatemala | La columna del beneficiario muestra el nombre de cada pago |
| 4.2 | Como admin@, lo mismo | Muestra el nombre. El Excel también |
| 4.3 | Como tesoreria@, lo mismo | Sin nombre (vacío), en la pantalla y en el Excel y el PDF. Sí ve MTCN, monto, comisión y PDV |
| 4.4 | Con la cuenta mixta con Cajero y Tesorería en Guatemala (caso 5.2), lo mismo | Sin nombre, igual que Tesorería sola. Antes de G8 lo recibía |
| 4.4b | Con 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-001 | El 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.5 | Con 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 Volumen | La 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.6 | Con la misma cuenta, el selector de país del Reporte individual | Ofrece solo Guatemala (donde tiene transacciones): queda deshabilitado, con un único país además de «Todos los países» |
| 4.7 | Lo mismo, por API: GET /reportes/situacion?country_id={Guatemala} con la cuenta del 4.5 | 403 (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 mixta | Qué mirar | Resultado esperado |
|---|---|---|---|
| 5.1 | Cajero en Guatemala (GT-CAP-001) y Tesorería en El Salvador | Menú, pantalla de inicio, encabezado, y las pantallas con país | Menú = 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.2 | Cajero y Tesorería, los dos en Guatemala | Reporte individual, soportes, caja | En 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.3 | Lo mismo que 5.2: después de fondear y ajustar, mirar el rastro | En 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.4 | Cajero en GT-CAP-001 y Supervisor en GT-QUE-002 (los dos en Guatemala) | Reporte individual y Saldos | En 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.5 | Admin y Cajero, los dos en Guatemala | Menú y pantalla de inicio | Exactamente el menú y el comportamiento de admin@: el Admin ya incluye lo del Cajero. Cae en el Dashboard |
| 5.6 | Cajero en Guatemala y Admin en El Salvador | Administración | La 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.7 | Cualquiera de las anteriores, mirando el manual de la app (/documentacion/manual-usuario) | Botones de PDF y texto de arriba | Muestra 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.8 | No existe forma de elegir con qué perfil se entra | Login, 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)
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Dar 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.2 | Una asignación de Tesorería en Guatemala acotada a un PDV | Los 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.3 | Intentar 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.4 | Buscar 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
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | docker exec soterex-backend-1 php artisan manual:generar-pdf | Genera 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.2 | Abrir los cuatro | Cada 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.3 | En 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.4 | En 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
| # | Paso | Resultado esperado |
|---|---|---|
| 8.1 | Como backoffice@, el flujo de siempre: abrir caja, buscar por MTCN, completar, pagar, imprimir la papeleta y cerrar | Todo funciona |
| 8.2 | Como tesoreria@, cargar un tipo de cambio nuevo y mirar el historial | Se crea un registro nuevo (el historial es inmutable); el evento queda en Auditoría |
| 8.3 | Como tesoreria@, fondear una caja abierta | Funciona |
| 8.4 | Como supervisor@, Reportes → Estado de Situación | Ve los nombres; exporta a Excel y PDF |
| 8.5 | Como admin@, Roles y Permisos en la ficha de un usuario | Se 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.6 | Un usuario con una sola asignación | No 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.
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| # | Pedido | Resultado esperado |
|---|---|---|
| a | GET /tipo-cambio/paises y GET /tipo-cambio/{país} | Cajero y Supervisor 403; Tesorería y Admin 200 |
| b | GET /reportes/situacion?country_id=… con una cuenta que suma Cajero y Tesorería en ese país | 200, y cada fila trae beneficiary: null |
| c | Lo mismo con supervisor@ o admin@ | Cada fila trae el nombre en beneficiary |
| d | GET /reportes/situacion?country_id=… con la cuenta del caso 5.1 y el país donde no tiene Reportes | 403 |
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:diferenciastiene 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
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.

