Skip to content

ADR-013: La caja opera solo el día en que se abrió ​

Date: 2026-10-02 Status: Accepted — la decisión de fondo (bloquear, no cerrar solo) es la P1 del plan de ajustes v2, confirmada por Carlos el 2026-10-02. Implementado en la entrega B3 del plan (PR 1). Extends: ADR-007 §4, §5 y §5b — no los supersede: la apertura sigue siendo de un solo usuario, el saldo inicial sigue heredándose y el cierre sigue sin generar movimiento. Este ADR agrega cuándo se puede operar con una sesión abierta. Ver también: ADR-008 (documentación del pago) y A6.3 del plan v1 (el cierre exige la papeleta firmada). Superseded in part by: ADR-021 — §5: la caja vencida (y cualquier otra) ya no la destraba un compañero; solo quien la abrió, un Supervisor o un Admin del PDV.

Context ​

Hoy nada obliga a cerrar la caja. TransactionController::pay() busca la sesión OPEN del usuario y no mira cuándo se abrió: se puede pagar hoy con una caja abierta hace un mes. fondeo y ajuste tampoco miran la fecha. El reporte de Cajas muestra el saldo actual, no el de cada día.

El 2026-10-01 el cliente (Magaly Benavides, CIS-EC) contestó la pregunta que le dejamos sobre el tema:

"Sí se requiere que haya una apertura y cierre diario de caja para control de saldos finales por día"

Lo que el cliente quiere no es una formalidad: quiere el saldo final de cada día. Y ese número solo existe si cada día tiene su propia sesión. Con una caja abierta tres días seguidos el sistema sabe cuánto hay ahora, pero no cuánto había al cierre de ayer: el closing_balance de ayer nunca se escribió.

Dos restricciones condicionan cómo se fuerza el cierre diario:

  1. El scheduler está apagado en staging. Un cierre automático necesitaría prenderlo (Terraform, costo) en un ambiente que hoy no lo tiene.
  2. El cierre exige documentación completa (A6.3, confirmado por el cliente en el mismo mail): una caja con un pago cuya papeleta firmada no se subió no se puede cerrar (PENDING_PAYMENT_DOCUMENTS). La papeleta firmada es un papel que alguien tiene que escanear y subir, así que un proceso automático a medianoche no puede cumplir esa condición.

Decision ​

1. Bloqueo en línea, sin cierre automático ​

Una sesión OPEN cuyo opened_at cae en un día calendario anterior al de hoy es una sesión vencida. Una caja con la sesión vencida no paga ni recibe fondeos o ajustes hasta que alguien la cierre y la vuelva a abrir. No hay cierre automático.

Operación sobre una caja con sesión vencidaResultado
Pagar (pay(), solo países con módulo Caja)422 CASH_SESSION_FROM_PREVIOUS_DAY, antes de descontar nada
Fondear (POST /caja/{id}/fondeo)422 CASH_SESSION_FROM_PREVIOUS_DAY
Ajustar (POST /caja/{id}/ajuste)422 CASH_SESSION_FROM_PREVIOUS_DAY
Cerrar (POST /caja/{id}/cierre)Funciona igual que siempre, incluido el bloqueo por PENDING_PAYMENT_DOCUMENTS
Abrir de nuevo, ya cerradaFunciona igual: hereda el saldo (ADR-007 §5)
Subir documentos pendientesSigue permitido: es justo lo que destraba el cierre
Leer (listado, movimientos, reportes)Sin cambios

Los países sin módulo Caja no cambian: pay() no mira ninguna sesión.

El 422 trae el código, un mensaje en español con la fecha de apertura ("Esta caja quedó abierta desde el 02/10/2026. Cerrala y abrila de nuevo para operar hoy."), opened_on (Y-m-d) y cash_box_id.

Se bloquean también fondeo y ajuste, no solo pay(). Si sobre una caja vencida se pudiera fondear o ajustar, el saldo final de ese día seguiría moviéndose después de terminado el día, y el closing_balance que se escriba al cerrar no sería el del cierre contable de ayer sino el de cuando alguien se acuerde de cerrar. Bloquear lo que escribe en el ledger "sella" el día.

2. "Día" es la fecha calendario de America/Guatemala (P2) ​

"Día" es la fecha calendario en la zona horaria de la app (config('app.timezone'), America/Guatemala, UTC-6 sin horario de verano). No se agrega zona horaria por país: hoy el único país con Caja es Guatemala.

Por qué importa decirlo: a las 18:00 de Guatemala ya es el día siguiente en UTC. Una regla calculada en UTC cerraría la caja en plena tarde, y una abierta a las 20:00 locales parecería "del día de mañana". Y este proyecto ya tuvo un bug de seis horas de timezone (2026-08-04, DatabaseTimezoneTest): opened_at es un timestamp sin zona que se guarda como hora de pared local, y la regla tiene que compararse contra esa hora de pared.

La regla vive en una sola función, CashSession::isFromPreviousDay() (con openedOn() para la fecha de apertura en hora local). Los controllers no comparan fechas a mano. Los tests cubren el borde de medianoche (23:59 → 00:01, 00:01 → 23:59) y los dos casos donde la fecha UTC y la local difieren.

3. Una caja abierta hoy que cruza la medianoche queda vencida ​

Si el cajero abrió a las 18:00 y sigue pagando a las 00:02, a las 00:00 la caja pasó a vencida y su siguiente pago da 422. Es lo esperado y es el costo de la decisión (P1): hay que cerrar y volver a abrir, y el saldo se hereda, así que la plata no se mueve. Hay que decírselo al operador en el manual y en el aviso de la pantalla.

4. La combinación con documentos pendientes ​

Una caja de ayer con una papeleta firmada sin subir no se puede cerrar (A6.3) y ahora tampoco se puede pagar con ella. Las dos cosas pasan juntas y el aviso de la pantalla tiene que decir ambas, con el camino a los pagos pendientes. Es lo que el cliente confirmó el 2026-10-01 ("Sí, confirmado" sobre el bloqueo del cierre): se cierra la caja cuando está la documentación.

El bloqueo del pago siguiente por documentos pendientes no existe (C2 del plan: el pago siguiente no se bloquea) y este ADR no lo introduce: lo que bloquea es el día, no los documentos.

5. Quién puede destrabar una caja vencida ​

⚠️ Reemplazado por ADR-021 (2026-10-06). Desde G6 el cierre sí exige ser quien abrió la caja, o un Supervisor o un Admin del PDV (403 CASH_CLOSE_NOT_OWNER para el resto). Lo que sigue es lo que se decidió en su momento; las dos precisiones de privacidad y trazabilidad de más abajo siguen vigentes.

El cierre no exige ser quien abrió: lo hace cualquiera con apertura_cierre_caja:write sobre ese PDV, así que si el cajero no vino hoy, un compañero o un Supervisor con alcance sobre el PDV puede cerrarla. Lo que sí puede frenarlo es la documentación pendiente de los pagos de esa sesión (punto 4).

Dos precisiones de privacidad y trazabilidad, porque ahora es un flujo previsto que cierre alguien que no abrió la caja:

  • Quien cierra la caja de otro no ve su saldo si no le correspondía. La respuesta del cierre aplica el mismo ocultamiento que GET /caja/disponibles (A5.3/D11): opening_balance y closing_balance llegan en null salvo para Supervisor/Admin (fondeo_caja:read) o para quien abrió esa sesión. El saldo igual queda registrado en la sesión; se oculta lo que se muestra, no lo que se guarda. (Desde G6, ADR-021, ese ocultamiento se sacó de la respuesta del cierre: solo cierran quien abrió y quien supervisa el PDV, y los dos ven el saldo, así que no se alcanzaba.)
  • El cierre tardío queda marcado en la auditoría. CASH_SESSION_CLOSED suma a su metadata from_previous_day (bool) y opened_by_user_id (quién abrió): quien revisa el reporte de Cierres por día no tiene que cruzar con CASH_SESSION_OPENED para saber que alguien destrabó una caja ajena. Un id de usuario y un booleano; ningún dato personal ni monto nuevo.

6. Lo que expone el backend para que el front solo refleje ​

GET /caja/disponibles suma a la session abierta from_previous_day (bool calculado en el backend) y opened_on (Y-m-d en hora local), además del opened_at que ya viajaba, y a la station su country_id (la caja vencida bloquea el pago solo de su país, y /me no sirve para saberlo: su country_stations viene vacío para quien tiene PDVs acotados). GET /caja/totales-pdv suma stale_cash_boxes (cuántas de las abiertas de un PDV están vencidas). El front no calcula si una caja está vencida: si lo recalculara con su propio reloj, tendría una segunda definición de "día".

Las dos claves viajan también cuando el saldo está oculto (un Cajero que mira una caja que no abrió): el aviso no depende de poder ver el saldo.

Pago no tiene endpoint propio. La sesión que le importa a pay() es la OPEN abierta por el propio usuario (ADR-007 §5b: una por usuario). El front la saca de GET /caja/disponibles, quedándose con la session cuyo opened_by_user_id es el del usuario logueado; para eso hace falta caja:read, que quien paga con Caja ya tiene. Si por falta de ese permiso o por una pantalla abierta que cruzó la medianoche el front no se enteró, el 422 de pay() es el respaldo: trae opened_on, cash_box_id y country_id (el de la caja, no el de la transacción rechazada: este corte va antes que CASH_BOX_COUNTRY_MISMATCH), y la pantalla se pone al día con eso. Con una caja vencida de un país con Caja, el front bloquea de antemano solo los pagos de ese país; si el operador tuviera además otro país con Caja, el 422 del backend es la barrera. Cuando el backend y el front discrepan, manda el backend.

Un solo detalle se duplica a propósito: el texto del aviso. Lo arma CashBoxService::fromPreviousDayError() para el 422 y mensajeCajaVencida() (frontend/src/utils/cajaVencida.ts) para el aviso fijo, porque el aviso tiene que verse sin haber hecho una operación rechazada. Si se cambia el texto de uno, se cambia el otro.

7. Reporte "Cierres por día" ​

GET /reportes/cajas/cierres (+ /export, Excel y PDF): una fila por sesión (cada apertura de caja, en su día de apertura) con saldo inicial, fondeos, ajustes, cantidad y total de pagos, hora de cierre y saldo final (closing_balance). Una sesión sin cerrar se muestra como Sin cerrar y sin saldo final. Todo se deriva del ledger de la sesión (cash_movements.cash_session_id); no se guarda ningún saldo nuevo (ADR-005, ADR-007). Invariante verificada por test: el saldo final de un día coincide con el saldo inicial de la sesión siguiente de esa caja, que es lo que ADR-007 §5 ya garantiza por herencia.

Si una caja se abrió más de una vez el mismo día (cambio de turno: se cierra y se vuelve a abrir, R17) salen dos filas de la misma caja y día, ordenadas por hora de apertura: el saldo final del día de esa caja es el de la última.

Una sesión abierta el día D y cerrada el D+1 (porque estaba vencida) aparece en D, con su hora de cierre del D+1: el reporte agrupa por día de apertura, que es el día que ese saldo final le corresponde. El closing_balance de esa sesión es el saldo del cierre contable de D justamente por el punto 1: desde la medianoche nada pudo escribir en el ledger de esa caja, así que cerrar tarde no lo cambia.

Cómo se consulta:

  • Rango. from y to son obligatorios y cuentan días de apertura en hora local, con los dos extremos inclusivos (una fecha o un instante: solo importa el día de America/Guatemala). to anterior a from da 422. Un from en UTC (…T02:30:00Z) es el día anterior en Guatemala, y se recorta después de pasarlo a la zona de la app.
  • Permisos y alcance. El mismo reportes:read y el mismo alcance por país y PDV que el resto de Reportes → Cajas; no hay un permiso aparte.
  • Filas y totales. Una fila por sesión, ordenada por día, PDV y caja. closing_balance es null si la sesión sigue OPEN; from_previous_day distingue "Sin cerrar · Vencida" de "Sin cerrar · En curso". Los totales (fondeos, ajustes, cantidad y total de pagos) salen de los movimientos de esa sesión, con signo: el total de pagos y los ajustes negativos restan, igual que en el resumen. La moneda de cada fila es la de los movimientos de la sesión, no la vigente del país: una sesión histórica en quetzales no se re-rotula en dólares si el país cambió de moneda de pago.
  • Exportación. /reportes/cajas/cierres/export?format=xlsx|pdf usa los mismos filtros, devuelve todo sin paginar y se audita como REPORT_EXPORTED. Las columnas son Fecha, PDV, Caja, Apertura, Saldo inicial, Fondeos, Ajustes, Pagos (cant.), Pagos (total), Cierre y Saldo final. El PDF sale apaisado (A4 horizontal) para que los montos no se partan en dos líneas; el Detalle de Cajas y el reporte de movimientos de una caja (GET /caja/{id}/reporte, siete u ocho columnas) también salen apaisados (la misma razón). Estado de Situación, el Resumen de Cajas y Auditoría siguen en vertical y entran. Una sesión sin cerrar dice en la columna Cierre Sin cerrar · Vencida o Sin cerrar · En curso (como la pantalla, para que el archivo también diga qué caja quedó trabada) y Sin cerrar en Saldo final.

Alternatives Considered ​

  • Cierre automático con un cron a medianoche. Es la lectura más literal de "cierre diario" y fue lo primero que se evaluó. Descartado por tres razones: (a) el scheduler está apagado en staging; (b) un cierre automático no puede esperar la papeleta firmada que exige el cierre (A6.3), así que habría que decidir entre cerrar con documentos pendientes —contradiciendo lo que el cliente confirmó— o dejar sin cerrar justo las cajas con pagos incompletos, que son las que más importan; (c) quién firma el cierre: hoy el closed_by_user_id es una persona que cierra su caja, y un cierre del sistema produciría un closing_balance que nadie revisó.
  • Cierre perezoso: el primer pago del día siguiente cierra la caja vieja y abre una nueva. Mezcla una operación de plata (cerrar) dentro de otra (pagar), con los mismos problemas de documentación y de autoría del cron, y oculta al cajero que su caja de ayer nunca se cerró. Descartado.
  • Bloquear solo pay(). Deja fondeo y ajuste moviendo el saldo de un día ya terminado (ver punto 1). Descartado.
  • Vencimiento por ventana de 24 horas desde la apertura. Una caja abierta a las 15:00 vencería a las 15:00 del día siguiente y mezclaría dos días en una misma sesión: no da "saldo final por día".
  • Zona horaria por país. Correcto en el largo plazo, innecesario hoy (un solo país con Caja). Cuando entre un país con Caja en otra zona hace falta countries.timezone y que openedOn() / isFromPreviousDay() la usen: es el único lugar que cambia, porque la definición está en una función.
  • Hora de corte configurable (que el "día" termine a las 03:00, por ejemplo, para turnos nocturnos). El cliente no lo pidió y las agencias de Guatemala no operan de madrugada. No se diseña.

Consequences ​

  • Positive: existe el saldo final de cada día, que es lo que pidió el cliente, sin tocar el modelo de saldos ni la infraestructura. Una caja que se olvidó abierta deja de poder operar en silencio.
  • Positive: la regla es una sola función y el borde de medianoche está testeado contra el bug que este proyecto ya tuvo (hora de pared local vs. UTC).
  • Negative: el cajero que opera de noche se encuentra con la caja trabada a las 00:00 (punto 3), y si dejó un pago con la papeleta pendiente tiene que subirla antes de poder cerrar y seguir. Es el costo de la P1 y el cliente lo confirmó, pero es la parte de esta decisión más probable de generar un reclamo.
  • Negative: si nadie cierra, el día queda "Sin cerrar" en el reporte y esa caja no opera. No hay red de seguridad automática: depende de que el Supervisor revise stale_cash_boxes.
  • Neutral, y es una nota de deploy: al desplegar esta entrega, toda caja que esté abierta desde un día anterior queda vencida (en staging puede haber sesiones de las pruebas de QA que quedaron abiertas). Hay que cerrarlas una vez para que se pueda operar. No es un bug: es la regla aplicándose a los datos existentes.
  • Neutral: las sesiones de la demo (demo:reseed) se abren siempre "hoy", acotadas a la medianoche local, para que una corrida de madrugada no deje cajas de demo nacidas vencidas.
  • Neutral: el texto del aviso vive en dos lugares (punto 6). Es duplicación aceptada y no una segunda definición de "día": lo que se duplica es la redacción, no la regla.

Si se revierte ​

A cierre automático. Es otra entrega, con sus propias decisiones, y este ADR deja listo lo que va a necesitar:

  1. Prender el scheduler en staging y producción (Terraform) y definir la hora de corte.
  2. Decidir qué hacer con los documentos pendientes: cerrar igual y marcar la sesión, o dejar sin cerrar las que tienen pagos incompletos. Es una decisión de negocio, no técnica.
  3. Definir el autor del cierre (un usuario "sistema") y cómo se audita un closing_balance que nadie arqueó.
  4. Reusar CashSession::isFromPreviousDay() como el predicado que elige qué sesiones cerrar. El bloqueo en línea de este ADR puede quedar como defensa en profundidad.

A sin restricción de día. Quitar los tres chequeos de isFromPreviousDay() (en pay(), fondeo y ajuste). El reporte de Cierres por día sigue funcionando, pero con cajas abiertas varios días mostrará filas "Sin cerrar" largas y ningún saldo final por día.

Actualización — L3 (2026-10-19, ADR-029): la bóveda del PDV no está sujeta a la regla del día ​

La bóveda de cada PDV (la CashBox con number = 0) no abre ni cierra: no tiene sesión y por lo tanto no tiene «día». Esta regla —una sesión abierta un día anterior solo se puede cerrar— no la alcanza: se la puede fondear, ajustar y pasarle o sacarle plata cualquier día. Lo que sí rige es sobre las cajas operativas que participan de un traspaso: cada extremo que no es la bóveda tiene que tener una sesión abierta hoy, con el mismo 422 CASH_SESSION_FROM_PREVIOUS_DAY de pay(), fondeo y ajuste (la función es CashBoxService::fromPreviousDayError()). Para sacarle plata a una caja ya cerrada hay que reabrirla: el saldo final de un día no se mueve después de cerrado, que es lo que esta regla protege.

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