Plan de Pruebas — Módulo Caja y prefondeo en tres capas (E4 + E4b)
Fecha: 2026-08-06 Entregas: E4 y E4-multi (ya en main) + E4b.1/E4b.2/E4b.3 (PRs #9 a #12) ADR: doc/architecture/ADR-007-prefondeo-tres-capas.md Ambiente: Dev local (./start-dev.sh) — http://localhost:5173
Por qué existe este documento
El módulo Caja nunca tuvo plan de pruebas manual. M1 a M4 tienen uno cada uno; E1 a E4 no. Caja es, de todo el sistema, lo que más plata mueve — lleva el efectivo físico de cada punto de venta — y hasta hoy se validó solo con tests automáticos.
Además, E4b cambia cosas que un test no puede juzgar: si el desglose del prefondeo país se entiende, si el aviso de sobregiro se distingue de un error que bloquea, si alguien puede confundir un fondeo con un ajuste. Eso necesita ojos.
Estado de lo automático
263 tests de backend y 50 de frontend, más Pint, vue-tsc y el build de producción. Lo que no está verificado: nada de esto se abrió en un navegador. Las pantallas de E4b.3 (Prefondeo País) y los avisos nuevos de Caja no se vieron nunca renderizados.
Usuarios
| Password | Rol | Para qué sirve acá | |
|---|---|---|---|
admin@cislatam.test | Admin123! | Admin | Configurar países, ver todo |
supervisor@cislatam.test | Super123! | Supervisor | Fondear, ajustar, cargar prefondeo país |
backoffice@cislatam.test | Backoffice123! | Backoffice | Abrir/cerrar caja y pagar |
Si hace falta un segundo Backoffice para las pruebas de concurrencia (sección 7), crealo desde Admin → Usuarios con rol Backoffice en Guatemala.
Preparación
./start-dev.shy esperar a que levante todo.- Como Admin → Ubicaciones → Países → Guatemala: módulo Caja activo, moneda local
GTQ, y "Pagar en moneda local" apagado (es el escenario real: Guatemala paga en dólares). - Verificar que Guatemala tenga al menos dos sucursales y una de ellas dos cajas (Ubicaciones → Estaciones → "+ agregar caja").
1. Configuración del país
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | Como Admin, editar Guatemala | Aparecen "Módulo Caja activo", "Moneda local" y "Pagar en moneda local" |
| 1.2 | Intentar activar el módulo Caja sin moneda local | 422 con mensaje claro, no se guarda |
| 1.3 | Dejar "Pagar en moneda local" apagado y guardar | Se guarda. La leyenda explica que apagado se paga en dólares y no hace falta TC |
| 1.4 | Como Supervisor, entrar a Ubicaciones | No tiene acceso — el ABM es solo de Admin |
2. Apertura y cierre (E4b.1)
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como Backoffice, entrar a Caja | Si hay más de una caja disponible, muestra el selector; con una sola, entra directo |
| 2.2 | Elegir una caja cerrada y tocar "Abrir caja" | Modal con el saldo inicial de solo lectura — no hay campo para tipearlo, ni pide usuario/contraseña de un Supervisor |
| 2.3 | Leer el texto del modal | Explica que si la plata física no coincide se registra un ajuste, y que la plata nueva entra por fondeo |
| 2.4 | Confirmar la apertura | Caja abierta. En la primera apertura el saldo inicial es 0,00 |
| 2.5 | Fondear 5.000 y cerrar la caja | El diálogo de cierre dice que la plata queda en la caja y que la próxima apertura arranca con ese saldo. Ya no dice "va a quedar en cero" |
| 2.6 | Volver a abrir la misma caja | El saldo inicial es 5.000, heredado del cierre. Es el corazón de E4b.1 |
| 2.7 | Mirar el historial tras el cierre | No aparece ningún movimiento de "Cierre" — el cierre ya no retira la plata |
2b. Una sola caja abierta por usuario
| # | Paso | Resultado esperado |
|---|---|---|
| 2.8 | Con una caja ya abierta a tu nombre, ir a "Cambiar de caja" e intentar abrir otra | Error 409: "Ya tenés la caja N de <sucursal> abierta a tu nombre. Cerrala antes de abrir otra." |
| 2.9 | Cerrar la primera y abrir la segunda | Funciona — es cambio de turno, no un bloqueo permanente |
| 2.10 | Con el segundo Backoffice, abrir otra caja mientras el primero tiene la suya abierta | Funciona: la regla es por usuario, no global |
3. Fondeo y ajuste (E4b.1)
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Como Supervisor, abrir el formulario de movimiento manual | El motivo es una lista desplegable cerrada — no se puede escribir uno nuevo |
| 3.2 | Ver los motivos de Fondeo | Fondeo inicial, Blindado, Transferencia financiero, Otro |
| 3.3 | Cambiar el toggle a Ajuste y ver los motivos | Faltante de arqueo, Sobrante de arqueo, Otro — y el motivo elegido antes se limpia |
| 3.4 | Elegir motivo Otro | Aparece un campo de descripción. Sin completarlo no deja guardar |
| 3.5 | Cargar un fondeo con Otro + descripción | Se guarda. En el historial se lee Otro — <descripción> bajo el tipo |
| 3.6 | Cargar un ajuste negativo (ej. -120, Faltante de arqueo) | Resta del saldo |
| 3.7 | Intentar un ajuste que deje la caja negativa | 422 — no existe "menos cero" en un cajón real |
| 3.8 | Como Backoffice, buscar el formulario de fondeo | No lo ve — fondeo y ajuste son de Supervisor/Admin |
4. Filtros y export
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Cargar más de 25 movimientos en una caja | Aparecen los controles de paginación y el total. Antes se truncaba en silencio |
| 4.2 | Navegar a la página 2 y volver | Los datos cambian; "Anterior" está deshabilitado en la página 1 |
| 4.3 | Filtrar por tipo y por motivo | El listado responde al filtro |
| 4.4 | Exportar a Excel con el filtro puesto | El archivo trae exactamente lo que estabas viendo, no todo |
| 4.5 | Abrir el export | Hay una columna Moneda. Con Guatemala pagando en dólares, no hay columna "TC aplicado" |
5. Pago y moneda (E4b.2)
| # | Paso | Resultado esperado |
|---|---|---|
| 5.1 | Con Guatemala pagando en dólares y sin ningún TC cargado, pagar una transacción | Se paga. Antes cortaba con "No hay tipo de cambio vigente" |
| 5.2 | Mirar el movimiento en el historial | El monto descontado es el nominal en USD, sin convertir, y no muestra TC |
| 5.3 | Ver los montos de la pantalla Caja | Todos llevan la moneda al lado (1,500.00 USD), no números pelados |
| 5.4 | Pagar sin tener ninguna caja abierta a tu nombre | 422 con mensaje claro |
| 5.5 | Pagar con la caja sin saldo suficiente | 422 — la caja es el único freno |
5b. Cambio de moneda (el escenario futuro)
Esto simula el día que Guatemala consiga la autorización de cambio de divisa. Hacelo sobre datos de prueba, no sobre una caja que quieras conservar.
| # | Paso | Resultado esperado |
|---|---|---|
| 5.6 | Con la caja teniendo saldo en USD, como Admin prender "Pagar en moneda local" en Guatemala y cargar un TC | Se guarda |
| 5.7 | Volver a Caja y mirar el saldo | El saldo pasa a ser el de GTQ (probablemente 0), y aparece un aviso: "Además hay X USD de una moneda anterior en esta caja" |
| 5.8 | Fondear en GTQ y pagar una transacción | El descuento se hace convertido al TC, y el movimiento muestra el TC aplicado |
| 5.9 | Mirar los movimientos viejos | Siguen rotulados en USD, no reetiquetados como GTQ |
| 5.10 | Volver a apagar la bandera al terminar | El saldo vuelve a mostrar el de USD |
6. Prefondeo en tres capas (E4b.3)
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Mirar el sidebar | Hay dos entradas: "Prefondeo Holding" y "Prefondeo País" |
| 6.2 | Entrar a Prefondeo Holding | El saldo se rotula como global de la Holding — suma de todos los países, no solo el que estás viendo |
| 6.3 | Entrar a Prefondeo País como Supervisor | Muestra el desglose de tres cifras |
| 6.4 | Verificar el desglose | Saldo del país arriba, y debajo ├─ Distribuido en cajas y └─ Disponible para distribuir, visualmente colgando del primero |
| 6.5 | Cargar un asiento de 100.000 con referencia | El saldo del país sube a 100.000 y "Disponible para distribuir" también |
| 6.6 | Fondear una caja con 20.000 | El saldo del país sigue en 100.000 (mover plata a una caja no es un gasto), "Distribuido en cajas" pasa a 20.000 y "Disponible" a 80.000 |
| 6.7 | Pagar una transacción de 500 desde esa caja | Ahí sí el saldo del país baja a 99.500 |
| 6.8 | Como Backoffice, buscar Prefondeo País | No lo ve — es de Supervisor/Admin |
6b. Saldo negativo y sobregiro
| # | Paso | Resultado esperado |
|---|---|---|
| 6.9 | En un país sin asientos de prefondeo país, pagar desde una caja con saldo | El pago se hace igual. El país queda en negativo |
| 6.10 | Mirar el saldo del país | En rojo, con una leyenda que aclara que es la deuda pendiente y no un error |
| 6.11 | Fondear una caja por encima de "Disponible para distribuir" | El fondeo se hace, y aparece un banner ámbar persistente que dice que se registró correctamente y que avises a tesorería |
| 6.12 | Comparar ese banner con un error real (ej. el ajuste negativo de 3.7) | El aviso es ámbar, en pasado, con la operación hecha; el error es rojo, en imperativo, sin guardar nada. Se tienen que distinguir de un vistazo |
| 6.13 | Descartar el banner con la × | Desaparece y no vuelve hasta el próximo fondeo con sobregiro |
7. Permisos y aislamiento
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | Como Backoffice acotado a la sucursal A, entrar a Caja | Solo ve las cajas de A |
| 7.2 | Con el id de una caja de la sucursal B, pegarle a la APIGET /caja/<id-de-B>/movimientos | 403. Este era el agujero del PR #9: antes respondía |
| 7.3 | Lo mismo con POST .../apertura y POST .../fondeo | 403 |
| 7.4 | Como Admin (sin acotar por PDV) | Puede operar cualquier caja del país |
7b. Multipaís
Requiere un segundo país con módulo Caja. Si no lo tenés, saltealo y anotalo.
| # | Paso | Resultado esperado |
|---|---|---|
| 7.5 | Con un usuario con acceso a dos países con Caja, abrir una caja del país B | Se abre |
| 7.6 | Intentar pagar una transacción del país A | 422: "La caja que tenés abierta es de otro país". Este era el peor de los bugs |
8. Regresión — países sin módulo Caja
Es lo más importante de esta ronda: Ecuador está en producción y no debe cambiar nada.
| # | Paso | Resultado esperado |
|---|---|---|
| 8.1 | En un país con módulo Caja apagado, pagar una transacción | Se paga sin pedir caja abierta ni TC |
| 8.2 | Verificar que no se creó ningún movimiento de caja | El flujo es idéntico al de M1 |
| 8.3 | Dejar el prefondeo país de ese país sin saldo e intentar pagar | 422 INSUFFICIENT_PREFUNDING — sin Caja, el país sí frena el pago |
| 8.4 | Entrar a Prefondeo País de ese país | Muestra solo el saldo, sin las dos filas de distribución (no hay cajas) |
9. Auditoría
| # | Paso | Resultado esperado |
|---|---|---|
| 9.1 | Tras hacer aperturas, cierres, fondeos y ajustes, entrar a Admin → Auditoría | Aparecen CASH_SESSION_OPENED, CASH_SESSION_CLOSED, CASH_FUNDED, CASH_ADJUSTED, COUNTRY_PREFUNDING_ENTRY_CREATED |
| 9.2 | Abrir el detalle de una apertura | No tiene datos de supervisor (ya no existe) y marca que el saldo fue heredado |
| 9.3 | Abrir el detalle de un fondeo con motivo Otro | Guarda motivo y descripción por separado |
Qué reportar
Por cada paso que falle: número del paso, qué esperabas, qué pasó, y si podés, captura. Si algo te resulta confuso aunque técnicamente funcione —sobre todo en la sección 6, que es conceptualmente lo más denso— anotalo igual: el desglose de tres cifras existe justamente porque el número solo no se entendía.
Cosas que este plan NO cubre
- Comprobantes membretados de apertura y cierre: las columnas existen pero nadie las escribe; llegan con E5. La app ya no promete que estén (se corrigió el mensaje del cierre).
- La notificación a Soterex al pagar: sigue siendo un seam para M5, no ocurre.
- Wizard de pago con documentos y papeleta: es E5.