ADR-029: La bóveda del PDV y los traspasos entre cajas
Date: 2026-10-19 Status: Accepted — decisiones D5-3 a D5-10 del plan de la respuesta del 14/10 (doc/plans/2026-10-19-ajustes-v3-respuesta-14-oct.md, que entra a main con el PR de la sesión A) (entrega L3), tomadas como valor por defecto, sin respuesta del cliente a las cuatro preguntas que siguen abiertas (QC-42 a QC-45). Qué está hecho: el backend completo (migraciones, reglas, extractos y reportes), las pantallas (Saldos, Fondeo PDVs, Estaciones/PDV, Reportes → Cajas y Cierres por día, Auditoría) y la documentación: el manual (30-caja, 32-caja-fondeo, 33-caja-traspasos, 41-prefondeo-pais, 01-perfiles-y-menu), el análisis funcional de Caja, el plan de prueba manual y doc/environments/staging.md. Qué queda abierto: las cuatro preguntas del cliente (§9) y verlo en Staging con usuarios reales: el deploy cambia permisos de usuarios reales (§4). Extends: ADR-005 y ADR-007 (el saldo se deriva del ledger, el ledger es inmutable y mover plata dentro del país no descuenta el saldo del país: nada de eso cambia), ADR-013 (la regla del día), ADR-014 (la matriz, con un módulo nuevo), ADR-015 (los extractos) y ADR-022 (la «caja operable» y la baja). Numeración: este es el 029 y no el 024: los ADR 024 a 028 están reservados por los branches de la migración a Azure, que no se mergearon.
Context
Fondeo PDVs (Prefondeo 2, J3) dejó a Tesorería mandar plata «a una caja» y exigía que esa caja estuviera abierta hoy. Magaly Benavides (CIS-EC) contestó el 14/10 que no es lo que quieren: «Tesorería prefondea al PDV, pero el dinero le llega al PDV y recién ahí se decide a qué caja/s se distribuye el dinero, es necesario tener una caja 0 / bóveda / líder donde llegue el dinero para el PDV y de esa caja se pase dinero al resto de cajas. Igualmente debe poder pasarse dinero entre cajas o del resto de las cajas a la cero, por ejemplo para cuando un operador no haya pagado y el otro se haya quedado sin fondos.» Y, a la pregunta de si alcanza con fondear una caja ya abierta: «plata al PDV primero, y después se reparte, con la posibilidad de no repartir todo en las cajas».
Es una capa más entre el país y la caja (ADR-007 tenía tres: Holding, país y caja) y una operación que antes no existía: mover plata dentro de un PDV.
Decision
1. La bóveda es una CashBox con number = 0 — sin columna nueva
Holding (global)
└── Prefondeo País (disponible para distribuir = saldo del país − lo repartido)
└── PDV: BÓVEDA (caja 0) ← Tesorería manda la plata acá (FONDEO, sin caja abierta, sin sesión)
├── Caja 1 ← traspaso desde la bóveda (o entre cajas, o de vuelta a la bóveda)
└── Caja 2La unicidad (station_id, number) que ya existía garantiza una por PDV; las cajas operativas siguen siendo 1, 2, 3… y su número no se reutiliza (addCashBoxForStation() toma max(number) + 1 y con solo la bóveda da 1). Una sola definición en el modelo: CashBox::NUMBER_BOVEDA, isBoveda(), scopeBoveda(), scopeOperativas() y etiqueta() («Bóveda» o «Caja N»: «Caja 0» no existe como nombre). Para el ledger es una caja como cualquiera: su saldo se deriva sumando cash_movements y cuenta en CountryPrefundingService::distributedInCashBoxes() sin cambiar esa fórmula (plata del país que ya está en el PDV). Ningún saldo se guarda.
No la crea un observer del modelo ni cambia el default de number (los tests y helpers que arman PDV y cajas a mano dependen del default 1): la crean CashBoxService::ensureCashBoxForStation() (al dar de alta un PDV con Caja, al activar el módulo Caja de un país y al mudar un PDV a un país con Caja) y una migración de datos idempotente para los PDV existentes. ensureCashBoxesForCountry() ya no usa doesntHave('cashBox'): con la bóveda presente esa pregunta no distingue «un PDV sin cajas» de «un PDV con solo la bóveda».
2. La bóveda no tiene sesión y no paga (D5-4)
No se abre, no se cierra, no tiene día (ADR-013 no la alcanza). Sus movimientos —el fondeo de Tesorería, los traspasos y los ajustes— tienen cash_movements.cash_session_id = null. La invariante: es null si y solo si la caja es la bóveda. No hay un CHECK portable que la exprese (la migración tiene que correr también en MySQL), así que la fijan el código y un test.
aperturaycierrede la bóveda: 422CASH_BOX_IS_VAULT. Sin eso, quien tengaapertura_cierre_caja:writeen el PDV (un Cajero incluido) la abriría, vería su saldo ypay()escribiría unPAGOcontra ella.pay(), segunda guarda: aunque llegara una sesión de la bóveda de otro lado,applyCashBoxDiscountresponde 422CASH_BOX_IS_VAULT. UnPAGOsale solo de una caja operativa con sesión abierta hoy. Su 422 de saldo (INSUFFICIENT_CASH_BALANCE) ahora manda a pedirle fondos al Supervisor a la bóveda.fondeoyajustesobre la bóveda: mismo permiso (fondeo_caja:write), mismo alcance por PDV, sin sesión. Se bloquea la fila decash_boxesde la bóveda y se exige que sea operable (su PDV activo, su país con módulo Caja): sin sesión, nada más lo dice. El ajuste no la deja en negativo y el avisoOVER_COUNTRY_PREFUNDINGdel fondeo sigue siendo un aviso (ADR-007 §3).- La bóveda sigue siendo «operable» (
CashBox::scopeOperable()): no se la saca de ahí para esconderla, porque la línea del país con alcance parcial (la suma de las cajas visibles) dejaría de coincidir con la de alcance completo (distributedInCashBoxes(), que suma todo el ledger). El Cajero no la ve por otro motivo (§5).
3. Un traspaso son dos filas con signo, de suma cero (D5-6, D5-7)
POST /caja/traspaso escribe, en una transacción, dos filas TRASPASO (como AJUSTE, una sola clase de fila con signo): negativa en la caja de origen y positiva en la de destino, con el mismo transfer_id, cada una con su counterpart_cash_box_id, la misma moneda (la de pago del país: si no, lo distribuido no sumaría cero), un motivo del catálogo cerrado (Reposición de fondos, Devolución de fondos, Otro con descripción) y un evento de Auditoría CASH_TRANSFERRED (PDV, las dos cajas, monto, moneda, motivo y transfer_id: ningún dato de una persona más que quién lo hizo). Suma cero dentro del PDV: no cambia el saldo del país ni lo distribuido en cajas.
| Regla | Código (422) |
|---|---|
| Origen y destino distintos | TRANSFER_SAME_BOX |
| Del mismo PDV (entre PDV no hay traspasos) | TRANSFER_DIFFERENT_STATION |
| Operables | CASH_BOX_INACTIVE |
| Cada extremo que NO es la bóveda tiene una sesión abierta hoy (D5-6); la bóveda no necesita ninguna | CASH_SESSION_CLOSED, CASH_SESSION_FROM_PREVIOUS_DAY |
| El monto no supera el saldo de origen: no existe «menos cero» en un cajón | TRANSFER_EXCEEDS_BALANCE |
El monto es positivo y de a lo sumo dos decimales. Una caja ya cerrada no manda ni recibe: para sacarle plata hay que reabrirla (ADR-013: el saldo final de un día no se mueve después de cerrado). El rechazo por saldo no revela cuánto hay a quien no ve los saldos de las cajas (A5.3).
Concurrencia. El traspaso tiene que serializarse con un pago y con otro traspaso de las mismas cajas. pay() bloquea la sesión de la caja del operador; el traspaso bloquea, en orden fijo por cash_box_id (para que dos traspasos en sentido contrario no se traben entre sí), la sesión abierta de cada extremo operativo y la fila de cash_boxes de la bóveda, y relee los saldos adentro de la transacción. Con las dos bloqueadas, ningún pago ni traspaso puede cambiarlo hasta el commit. Un test de saldo justo no deja pasar dos traspasos que juntos exceden el saldo.
4. El permiso traspaso_caja (D5-3)
Módulo nuevo en la matriz. Valores [leer, escribir, borrar]: Cajero [0,0,0] · Supervisor [1,1,0] (de sus PDV) · Tesorería [1,1,0] · Admin [1,1,1]. «Líder» del PDV es el Supervisor; el caso es de mostrador (un operador sin fondos a mitad de día) y esperar a Tesorería dejaría al PDV sin poder resolverlo; el Cajero no, porque dejaría mover la plata de la caja de otro. El Supervisor no gana por esto el fondeo ni el ajuste: eso sigue siendo fondeo_caja:write.
El alcance fino lo aplica el controller como en el resto de Caja (hasStationScope, con el módulo traspaso_caja), sobre las dos cajas: un Supervisor no traspasa en un PDV que no es suyo (403), una Tesorería de un solo país no traspasa en otro (G12).
Llega a las bases existentes por una migración de datos (EnsureRolePermissions::forModule; el deploy corre migrate y no los seeders, ver Staging), además de RoleSeeder::MATRIX, PermissionModules, doc/architecture/matriz-de-perfiles.json y la tabla de ADR-014. Cambia permisos de usuarios reales: el Supervisor gana «Pasar plata entre cajas» y el deploy deja un evento de Auditoría ROLE_PERMISSION_GRANTED_BY_MIGRATION por cada celda que otorga (tres), como pasó con B6 y G8. php artisan permisos:diferencias (ahora 80 celdas) tiene que decir «Sin diferencias».
5. Quién ve la bóveda (D5-3)
GET /caja/disponibles la manda solo a quien ve todas las cajas de su PDV (canSeeAllCashBoxes: Supervisor, Tesorería y Admin), con is_vault: true, session: null y primera de cada PDV. El Cajero nunca la recibe, ni su saldo, ni siquiera su existencia (ni con balance: null) en las listas de cajas. Una salvedad que se aceptó: el historial de SU caja trae la contraparte de un traspaso, así que un Cajero al que un Supervisor le pasó plata lee «Traspaso desde Bóveda» y el id de esa caja; con ese id todo lo demás responde 403 (movimientos, reporte) o 422 (CASH_BOX_IS_VAULT), sin saldo ni efecto contable. El frontend no lo adivina por number === 0: lo dice is_vault. GET /caja/totales-pdv: el total del PDV incluye la bóveda (con el desglose boveda_balance y cajas_balance), pero «cajas abiertas» y total_cash_boxes no la cuentan; un PDV cuya única caja operable es la bóveda tiene tarjeta (Tesorería tiene que poder fondearlo).
6. Se mantiene fondear directo una caja abierta (D5-5)
Fondear una caja abierta desde Saldos sigue andando, como atajo: no se rompe nada ya aprobado (Saldos 6). Lo que cambia es el camino principal: Fondeo PDVs, pestaña PDV, «Fondear PDV» manda la plata a la bóveda y reemplaza al formulario «Fondear caja» de J3 (D5-9). Se le pregunta al cliente (QC-43).
7. Los extractos no muestran los traspasos (D5-8); los reportes los suman
ADR-015 §3: los extractos son vistas derivadas del ledger y su último saldo corrido tiene que dar lo que da el servicio de saldos.
- Extracto del país y del PDV: sin
TRASPASO. En el país y en el PDV suman cero y solo meterían dos líneas que se anulan, con débitos y créditos inflados. El saldo corrido sigue cerrando contraCashBoxService::balanceForStation()y contraavailableToDistribute(). Un fondeo a la bóveda SÍ aparece: es plata que entra al PDV y sale de lo disponible del país. Sí aparecen los traspasos en el historial de cada caja (con «hacia Caja 2» / «desde Bóveda»). - El extracto del PDV rotula la caja «Bóveda» (y los del país,
Sucursal · Bóveda). - Reportes → Cajas: la bóveda es una fila más, rotulada «Bóveda», con
session_status = NONE(se lee «—»). Resumen y Cierres por día sumantraspaso(neto, con signo, en pantalla y en el Excel/PDF) para que apertura + fondeos + ajustes + traspasos + pagos = cierre siga cerrando. La bóveda no sale en Cierres por día (no tiene sesiones). - El rango (
TreasuryStatementService::RANK) tiene el crédito antes que el débito paraCASH_TRASPASOpor si algún día se muestran.
8. Dar de baja un PDV o apagar el módulo Caja con plata en la bóveda (D5-10)
La bóveda es una CashBox y suma en hasBalance(): una bóveda con plata bloquea desactivar el PDV, mudarlo de país o apagar el módulo del país (STATION_HAS_CASH_BALANCE, COUNTRY_HAS_CASH_BALANCE, ADR-022 §5). Pero el camino que esos errores documentaban («abrí la caja, ajustá con Retiro por baja de caja, cerrala») es imposible para la bóveda: no se abre. Se resuelve así: el ajuste negativo con el motivo «Retiro por baja de caja» se acepta sobre la bóveda sin sesión (mismo permiso, fondeo_caja:write) y los mensajes distinguen el caso («la bóveda se ajusta directo, sin abrirla»). La bóveda no se activa ni se desactiva desde Estaciones/PDV (CASH_BOX_IS_VAULT). Sacar plata de la bóveda hacia Tesorería no es una operación propia (QC-45).
9. Las cuatro preguntas para el cliente
| QC | Pregunta | Si no contestan (lo implementado) |
|---|---|---|
| QC-42 | El circuito y quién puede pasar plata | Supervisor (de sus PDV), Tesorería y Administrador; el cajero no |
| QC-43 | ¿Se sigue pudiendo fondear una caja abierta directamente? | Se puede, como atajo |
| QC-44 | ¿Alcanza con que las dos cajas estén abiertas ese día? | Sí; la bóveda no necesita sesión |
| QC-45 | ¿Hace falta devolver plata del PDV al país como operación propia? | Un ajuste de la bóveda con motivo «Otro» y descripción |
10. Las migraciones son portables
Solo el schema builder de Laravel: nada de SQL de un motor (::, ILIKE, índices parciales, jsonb). Hay una migración a Azure/MySQL abierta (PRs #110 a #118) que se trae main por merge y no tiene que romperse por esto. cash_session_id pasa a nullable con ->nullable()->change(); la migración de las bóvedas usa el modelo con firstOrCreate; down() de la primera corta antes de tocar nada si ya hay movimientos sin sesión (el ledger es inmutable).
Alternatives Considered
- Una columna
is_vaultencash_boxes. Descartada: el número 0 ya es único por PDV, y una segunda forma de saber lo mismo se desalinea. - La bóveda con sesión diaria (D5-4 b). Descartada: es un fondo y no un cajón con un operador; exigirle apertura obligaría a Tesorería a esperar a que alguien la abra para mandarle plata.
- Que todo fondeo pase por la bóveda (D5-5 b). Descartada por ahora: rompería Saldos 6, ya aprobado. Se pregunta (QC-43).
- Mostrar los traspasos en los extractos (D5-8 b). Descartada: duplican líneas e inflan débitos y créditos; sí están en el historial de cada caja.
- Una operación propia «sacar de la bóveda hacia Tesorería» (D5-10 b). Descartada: reusa el ajuste con motivo de baja (G7) sin una operación nueva. Se pregunta (QC-45).
- Cajero con permiso de traspaso (D5-3 c). Descartada: dejaría a un cajero mover plata de la caja de otro.
doesntHave('cashBox')y un observer que cree la bóveda sola. Descartados: el primero deja de distinguir PDV sin cajas del de solo la bóveda y el segundo rompe decenas de tests que arman cajas a mano.
Consequences
- El deploy a Staging cambia permisos de usuarios reales y crea una bóveda por cada PDV de un país con Caja (en cero). Hay que avisar antes (ver Staging y el plan de prueba). Las cajas abiertas del deploy no se tocan.
- «Distribuido en cajas» de la tarjeta del país pasa a llamarse «Distribuido en PDVs» (es solo la etiqueta; el número es el mismo, y ahora incluye lo que está en las bóvedas).
- Una bóveda con plata bloquea dar de baja un PDV y apagar el módulo Caja; se vacía con un ajuste de «Retiro por baja de caja» sin abrirla.
- Los reportes de Cajas ganan una fila por PDV (la bóveda) y una columna («Traspasos»); los archivos exportados cambian de forma.
- G13 (confirmación de recepción) sigue diferida: la plata llega a la bóveda sin que nadie la confirme. Si el cliente la quiere después, se apoya en la bóveda.
- Lo que se vigiló al implementar (la lista de riesgos de L3.7): el pago contra una bóveda abierta (doble guarda), el fondeo sin sesión, el bloqueo al desactivar, los totales de reportes que no conciliaban, las bóvedas que no nacían solas, los tres rótulos de tipo de movimiento (ahora una sola copia en
CashMovement::TYPE_LABELS), la moneda de las dos patas y el N+1 de/caja/disponibles.
Riesgos conocidos que se dejaron (revisión independiente, 2026-10-19)
- Un traspaso no es idempotente. Si una respuesta se pierde después de un commit exitoso y el cliente reintenta, la plata se mueve dos veces (si hay saldo). El botón se deshabilita mientras espera, pero eso no cubre un reintento de HTTP. Un
Idempotency-Keyguardado junto altransfer_idlo resolvería; no se hizo porque ningún otro endpoint de dinero del sistema lo tiene y es un cambio de contrato que corresponde decidir con el resto. - Segregación de funciones. El Supervisor tiene
pago:writeytraspaso_caja:write: puede pasarse plata de la bóveda a su propia caja abierta y pagar con ella, o vaciar a la bóveda la caja de un Cajero, sin tope ni segunda persona. Todo dejaCASH_TRANSFERREDen la Auditoría (con quién, cuánto, entre qué cajas y por qué motivo). Es la decisión que hay que tener presente al contestar QC-42. - Perfiles mezclados. Con Supervisor en un PDV y Cajero en otro, la pantalla puede ofrecer el bloque de traspaso en el PDV donde solo es Cajero y el servidor responde 403 con su mensaje: ruido de UX, sin fuga ni efecto contable.
exists:cash_boxes,idcorre antes del chequeo de alcance, así que quien tienetraspaso_caja:writedistingue «este uuid es una caja» de «no existe». Un uuid no se adivina; queda como está.

