Skip to content

Plan de Pruebas — L3: la bóveda del PDV y pasar plata entre cajas ​

Fecha: 2026-10-19 Decisión: ADR-029 (bóveda como caja 0, traspasos de suma cero, permiso traspaso_caja) · enmienda a ADR-007, ADR-013 y ADR-014 · plan de la ronda 3, entrega L3 · análisis funcional de Caja, 1.11 Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba (ver «En Staging», al final)

Qué cambió, en cuatro frases: cada PDV con módulo Caja tiene una bóveda (la «Caja 0» del cliente), que guarda plata pero no abre, no cierra y no paga; Tesorería fondea al PDV, no a una caja (Fondear PDV manda la plata a la bóveda, sin caja abierta); un Supervisor, Tesorería o un Admin reparte esa plata a las cajas con Pasar plata entre cajas (suma cero, dentro de un mismo PDV); y hay un permiso nuevo, Traspasos entre cajas (Pasar plata), que el Cajero no tiene. Lo que no cambia: ningún saldo se guarda (siguen derivados del libro de movimientos), el pago valida solo la caja operativa, y el saldo del país no baja al pasar plata del país a una bóveda ni de la bóveda a una caja.

Este plan no se probó en Staging: lo que sigue verificado a mano es lo de dev que figura en el PR.

Antes de empezar ​

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

EmailPerfilAlcancePara qué sirve acá
tesoreria@cislatam.testTesoreríaGuatemala, todos los PDVFondear PDVs, pasar plata, ver los extractos
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002Pasar plata en sus PDVs; no puede en otro
backoffice@cislatam.testCajeroSu PDVComprobar que no ve la bóveda ni el bloque
admin@cislatam.testAdminGuatemalaTodo, más la Auditoría y los ABM

Qué crea la migración. Al aplicar las migraciones de L3 cada PDV activo de un país con módulo Caja recibe una bóveda (en dev: las de Guatemala), con saldo cero, y los perfiles reciben el permiso traspaso_caja (Cajero 0, Supervisor 1/1/0, Tesorería 1/1/0, Admin 1/1/1). No hace falta correr un seeder.

Preparar el escenario. Dos cajas abiertas hoy en el mismo PDV (por ejemplo GT-QUE-002: la Caja 1 del Supervisor y la Caja 2 que abre backoffice@). Si una está vencida, hay que cerrarla y abrirla de nuevo antes de empezar (ADR-013).


1. Permisos y menú por perfil ​

#PasoResultado esperado
1.1php artisan permisos:diferencias«Sin diferencias» (la matriz, el seeder y la base coinciden)
1.2Entrar como backoffice@ → Caja › SaldosNo ve ninguna tarjeta Bóveda del PDV; en su caja no hay bloque Pasar plata entre cajas
1.3Por API como backoffice@: POST /caja/traspaso con dos cajas cualesquiera403
1.4Entrar como supervisor@ → SaldosVe la tarjeta Bóveda del PDV (Caja 0) con el rótulo Fondo del PDV de cada PDV suyo
1.5Como supervisor@, abrir la bóvedaNo ve el bloque Movimiento manual (fondear y ajustar son de Tesorería) y sí Pasar plata entre cajas
1.6Como tesoreria@, abrir la bóvedaVe Movimiento manual y Pasar plata entre cajas; ningún botón de abrir ni cerrar caja
1.7Documentación › Manual del Usuario como supervisor@Hay un capítulo nuevo, Pasar plata entre cajas; con backoffice@, no

2. La bóveda no abre, no cierra y no paga ​

#PasoResultado esperado
2.1Como admin@, abrir la bóveda en SaldosNo hay botón Abrir caja ni Cerrar caja; no hay estado «abierta/cerrada» ni «vencida»
2.2Por API: POST /caja/{id de la bóveda}/apertura422 CASH_BOX_IS_VAULT
2.3Por API: POST /caja/{id}/cierre sobre la bóveda422 CASH_BOX_IS_VAULT
2.4Un operador sin caja abierta intenta pagar, con el PDV teniendo 5.000 en la bóvedaEl pago se rechaza por no tener caja abierta: la bóveda no cubre un pago
2.5Por API: PATCH /admin/estaciones/{pdv}/cajas/{bóveda} con active: false422 CASH_BOX_IS_VAULT (la bóveda no se activa ni se desactiva)
2.6Parámetros › Estaciones (Admin), el detalle del PDVLista sus cajas; la bóveda figura como Bóveda del PDV (Caja 0) y no tiene el interruptor de activar

3. Fondear un PDV (la plata cae en la bóveda) ​

Entrar como tesoreria@ → Tesorería › Fondeo PDVs › PDV, elegir GT-QUE-002.

#PasoResultado esperado
3.1Mirar el formularioSe llama Fondear PDV (no Fondear caja), dice que la plata llega a la bóveda y no pide elegir una caja
3.2Con todas las cajas del PDV cerradas, fondear 5.000 con el motivo de la listaSe registra: «PDV fondeado: la plata llegó a su bóveda.»
3.3Mirar el extracto del PDVHay una línea de fondeo en la caja Bóveda del PDV, con el saldo corrido
3.4En Saldos (como tesoreria@), la tarjeta del PDVBóveda 5,000.00 · Cajas …, con el total sumado
3.5Fondear un monto que deje al país en negativo disponibleEl fondeo se registra y aparece el aviso Fondeaste por encima del prefondeo del país (no bloquea)
3.6Fondeo PDVs › País: Distribuido en cajasSubió exactamente lo fondeado; el saldo del país no cambió
3.7Como supervisor@, Fondeo PDVs › PDVVe el extracto pero no el formulario Fondear PDV
3.8Un PDV de un país sin módulo CajaEl formulario dice que el PDV no tiene bóveda y no deja fondear

4. Pasar plata entre cajas ​

Como supervisor@ (o tesoreria@), Saldos › GT-QUE-002, la bóveda con 5.000 y las dos cajas abiertas.

#PasoResultado esperado
4.1Desde Bóveda, hacia Caja 1, 4.000, motivo Reposición de fondos → Pasar plataSe registra. La bóveda queda en 1.000; la Caja 1 sube 4.000
4.2Mirar el historial de las dosDos líneas con la misma hora y el mismo motivo: Traspaso hacia Caja 1 (negativa, en la bóveda) y Traspaso desde Bóveda (positiva, en la Caja 1)
4.3El total del PDV en Totales por PDVIgual que antes del traspaso; solo cambia el desglose Bóveda 1,000.00 · Cajas …
4.4Fondeo PDVs › PaísDistribuido en cajas, Disponible y saldo del país no cambian
4.5Pagar una transacción desde la Caja 1 con la plata que se le pasóEl pago sale; la Caja 1 baja el principal y la bóveda no se mueve
4.6Caja 1 hacia Caja 2, con Otro y sin descripciónRechazo: «con el motivo "Otro" hace falta una descripción»
4.7Lo mismo, con descripciónSe registra
4.8Pasar de la Caja 2 a la bóveda con Devolución de fondosSe registra; la bóveda recibe
4.9Pasar más de lo que tiene el origen422 TRANSFER_EXCEEDS_BALANCE; el mensaje no dice el saldo si el usuario no ve los saldos
4.10Origen y destino iguales (por API)422 TRANSFER_SAME_BOX
4.11Dos cajas de PDVs distintos (por API, con un usuario que tenga alcance en ambos)422 TRANSFER_DIFFERENT_STATION
4.12Cerrar la Caja 2 y pasar plata hacia o desde ella422 CASH_SESSION_CLOSED ("abrila antes de pasarle o sacarle plata")
4.13Una caja que quedó abierta de ayer422 CASH_SESSION_FROM_PREVIOUS_DAY; la bóveda, en cambio, sigue operando
4.14Una caja dada de baja422 CASH_BOX_INACTIVE
4.15Cambiar el monto a 0, negativo o con tres decimalesRechazo de validación
4.16supervisor@ pasa plata en un PDV que no es suyo (por API)403, aunque las dos cajas existan y sean del mismo PDV

5. Extractos y totales ​

#PasoResultado esperado
5.1Extracto del PDVNo tiene líneas de traspaso; sí el fondeo de la bóveda y los pagos
5.2Extracto del país (disponible para distribuir)No tiene líneas de traspaso
5.3Extracto de la Holding y de Soterex ↔ CIS HoldingSin ningún cambio
5.4Totales por PDV: «N de M cajas abiertas»No cuenta la bóveda
5.5Exportar a Excel y a PDF el extracto del PDVLos dos exports cuadran con la pantalla y la bóveda figura con su nombre

6. Reportes y Auditoría ​

#PasoResultado esperado
6.1Reportes › Cajas, resumenColumna Traspasos (neto por caja); para un PDV, la suma de la columna da 0. La bóveda es una fila más, sin estado de sesión
6.2Reportes › Cajas, detalle y exportLos traspasos se rotulan «hacia Caja N» / «desde Bóveda»
6.3Cierres por díaLa bóveda no aparece (no cierra) y hay una columna Traspasos por sesión; apertura + fondeos + ajustes + traspasos − pagos = saldo final
6.4Auditoría, filtrando por Traspaso entre cajasUn evento por traspaso, con el PDV, las dos cajas, el monto y el motivo; lo carga quien lo hizo
6.5Auditoría de un fondeo a la bóvedaEl mismo evento de fondeo de caja de siempre, sobre la bóveda

7. Casos de borde ​

#PasoResultado esperado
7.1Ajuste de la bóveda con el motivo Retiro por baja de caja y monto negativoSe acepta (para vaciarla antes de dar de baja el PDV); un monto positivo con ese motivo, no
7.2Intentar desactivar un PDV con plata en la bóveda409 STATION_HAS_CASH_BALANCE: el mensaje nombra la bóveda y dice que se vacía con el ajuste, sin abrirla
7.3Dos pestañas pasando plata de la misma caja al mismo tiempo, por un monto que juntos supera el saldoUno se registra y el otro recibe TRANSFER_EXCEEDS_BALANCE: nunca quedan saldos negativos
7.4Pagar con una caja mientras otro la vacía con un traspasoUno espera al otro: el que llegó segundo ve el saldo real

En Staging ​

Al desplegar L3 cambian los permisos de usuarios reales: el Supervisor y Tesorería reciben el módulo Traspasos entre cajas (Pasar plata), y el deploy deja un evento de Auditoría ROLE_PERMISSION_GRANTED_BY_MIGRATION por cada cambio. Se crea además una bóveda vacía por PDV activo. Antes de promover, avisar a Magaly y a Teresa; el detalle y los pasos están en doc/environments/staging.md.

Al terminar ​

La bóveda y los traspasos que se hayan creado en dev quedan en el libro de movimientos (que no se edita): no hace falta limpiar nada si se probó en dev; en Staging, avisar para no mezclar la plata de prueba con la del cliente.

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