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):
| Perfil | Alcance | Para qué sirve acá | |
|---|---|---|---|
tesoreria@cislatam.test | Tesorería | Guatemala, todos los PDV | Fondear PDVs, pasar plata, ver los extractos |
supervisor@cislatam.test | Supervisor | GT-CAP-001 y GT-QUE-002 | Pasar plata en sus PDVs; no puede en otro |
backoffice@cislatam.test | Cajero | Su PDV | Comprobar que no ve la bóveda ni el bloque |
admin@cislatam.test | Admin | Guatemala | Todo, 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
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | php artisan permisos:diferencias | «Sin diferencias» (la matriz, el seeder y la base coinciden) |
| 1.2 | Entrar como backoffice@ → Caja › Saldos | No ve ninguna tarjeta Bóveda del PDV; en su caja no hay bloque Pasar plata entre cajas |
| 1.3 | Por API como backoffice@: POST /caja/traspaso con dos cajas cualesquiera | 403 |
| 1.4 | Entrar como supervisor@ → Saldos | Ve la tarjeta Bóveda del PDV (Caja 0) con el rótulo Fondo del PDV de cada PDV suyo |
| 1.5 | Como supervisor@, abrir la bóveda | No ve el bloque Movimiento manual (fondear y ajustar son de Tesorería) y sí Pasar plata entre cajas |
| 1.6 | Como tesoreria@, abrir la bóveda | Ve Movimiento manual y Pasar plata entre cajas; ningún botón de abrir ni cerrar caja |
| 1.7 | Documentació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
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como admin@, abrir la bóveda en Saldos | No hay botón Abrir caja ni Cerrar caja; no hay estado «abierta/cerrada» ni «vencida» |
| 2.2 | Por API: POST /caja/{id de la bóveda}/apertura | 422 CASH_BOX_IS_VAULT |
| 2.3 | Por API: POST /caja/{id}/cierre sobre la bóveda | 422 CASH_BOX_IS_VAULT |
| 2.4 | Un operador sin caja abierta intenta pagar, con el PDV teniendo 5.000 en la bóveda | El pago se rechaza por no tener caja abierta: la bóveda no cubre un pago |
| 2.5 | Por API: PATCH /admin/estaciones/{pdv}/cajas/{bóveda} con active: false | 422 CASH_BOX_IS_VAULT (la bóveda no se activa ni se desactiva) |
| 2.6 | Parámetros › Estaciones (Admin), el detalle del PDV | Lista 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.
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Mirar el formulario | Se llama Fondear PDV (no Fondear caja), dice que la plata llega a la bóveda y no pide elegir una caja |
| 3.2 | Con todas las cajas del PDV cerradas, fondear 5.000 con el motivo de la lista | Se registra: «PDV fondeado: la plata llegó a su bóveda.» |
| 3.3 | Mirar el extracto del PDV | Hay una línea de fondeo en la caja Bóveda del PDV, con el saldo corrido |
| 3.4 | En Saldos (como tesoreria@), la tarjeta del PDV | Bóveda 5,000.00 · Cajas …, con el total sumado |
| 3.5 | Fondear un monto que deje al país en negativo disponible | El fondeo se registra y aparece el aviso Fondeaste por encima del prefondeo del país (no bloquea) |
| 3.6 | Fondeo PDVs › País: Distribuido en cajas | Subió exactamente lo fondeado; el saldo del país no cambió |
| 3.7 | Como supervisor@, Fondeo PDVs › PDV | Ve el extracto pero no el formulario Fondear PDV |
| 3.8 | Un PDV de un país sin módulo Caja | El 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.
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Desde Bóveda, hacia Caja 1, 4.000, motivo Reposición de fondos → Pasar plata | Se registra. La bóveda queda en 1.000; la Caja 1 sube 4.000 |
| 4.2 | Mirar el historial de las dos | Dos 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.3 | El total del PDV en Totales por PDV | Igual que antes del traspaso; solo cambia el desglose Bóveda 1,000.00 · Cajas … |
| 4.4 | Fondeo PDVs › País | Distribuido en cajas, Disponible y saldo del país no cambian |
| 4.5 | Pagar 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.6 | Caja 1 hacia Caja 2, con Otro y sin descripción | Rechazo: «con el motivo "Otro" hace falta una descripción» |
| 4.7 | Lo mismo, con descripción | Se registra |
| 4.8 | Pasar de la Caja 2 a la bóveda con Devolución de fondos | Se registra; la bóveda recibe |
| 4.9 | Pasar más de lo que tiene el origen | 422 TRANSFER_EXCEEDS_BALANCE; el mensaje no dice el saldo si el usuario no ve los saldos |
| 4.10 | Origen y destino iguales (por API) | 422 TRANSFER_SAME_BOX |
| 4.11 | Dos cajas de PDVs distintos (por API, con un usuario que tenga alcance en ambos) | 422 TRANSFER_DIFFERENT_STATION |
| 4.12 | Cerrar la Caja 2 y pasar plata hacia o desde ella | 422 CASH_SESSION_CLOSED ("abrila antes de pasarle o sacarle plata") |
| 4.13 | Una caja que quedó abierta de ayer | 422 CASH_SESSION_FROM_PREVIOUS_DAY; la bóveda, en cambio, sigue operando |
| 4.14 | Una caja dada de baja | 422 CASH_BOX_INACTIVE |
| 4.15 | Cambiar el monto a 0, negativo o con tres decimales | Rechazo de validación |
| 4.16 | supervisor@ 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
| # | Paso | Resultado esperado |
|---|---|---|
| 5.1 | Extracto del PDV | No tiene líneas de traspaso; sí el fondeo de la bóveda y los pagos |
| 5.2 | Extracto del país (disponible para distribuir) | No tiene líneas de traspaso |
| 5.3 | Extracto de la Holding y de Soterex ↔ CIS Holding | Sin ningún cambio |
| 5.4 | Totales por PDV: «N de M cajas abiertas» | No cuenta la bóveda |
| 5.5 | Exportar a Excel y a PDF el extracto del PDV | Los dos exports cuadran con la pantalla y la bóveda figura con su nombre |
6. Reportes y Auditoría
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Reportes › Cajas, resumen | Columna 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.2 | Reportes › Cajas, detalle y export | Los traspasos se rotulan «hacia Caja N» / «desde Bóveda» |
| 6.3 | Cierres por día | La bóveda no aparece (no cierra) y hay una columna Traspasos por sesión; apertura + fondeos + ajustes + traspasos − pagos = saldo final |
| 6.4 | Auditoría, filtrando por Traspaso entre cajas | Un evento por traspaso, con el PDV, las dos cajas, el monto y el motivo; lo carga quien lo hizo |
| 6.5 | Auditoría de un fondeo a la bóveda | El mismo evento de fondeo de caja de siempre, sobre la bóveda |
7. Casos de borde
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | Ajuste de la bóveda con el motivo Retiro por baja de caja y monto negativo | Se acepta (para vaciarla antes de dar de baja el PDV); un monto positivo con ese motivo, no |
| 7.2 | Intentar desactivar un PDV con plata en la bóveda | 409 STATION_HAS_CASH_BALANCE: el mensaje nombra la bóveda y dice que se vacía con el ajuste, sin abrirla |
| 7.3 | Dos pestañas pasando plata de la misma caja al mismo tiempo, por un monto que juntos supera el saldo | Uno se registra y el otro recibe TRANSFER_EXCEEDS_BALANCE: nunca quedan saldos negativos |
| 7.4 | Pagar con una caja mientras otro la vacía con un traspaso | Uno 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.

