Skip to content

Plan de Pruebas — G7: administrar cajas (activar y desactivar) y la línea de país de Saldos ​

Fecha: 2026-10-06 Decisión: ADR-022 · plan de ajustes v3, entrega G7 (RV3-29, RV3-30, H3-06; decisión D3-14 a) y G6.C (RV3-28; QC-15 y QC-16 con su valor por defecto) Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba

Qué cambió: una caja se desactiva y se reactiva desde un panel nuevo, «Administrar», de Parámetros → Estaciones / PDV (nunca se borra); una caja desactivada desaparece de Saldos y no se puede abrir, pero sigue en Reportes → Cajas marcada Inactiva; no se desactiva con una sesión abierta ni con plata adentro (hay que dejarla en cero con un ajuste negativo de motivo nuevo, Retiro por baja de caja); agregar una caja, desactivar un PDV y mover un PDV de país validan lo que antes no validaban (H3-06), y desactivar un PDV, mudarlo de país o apagar el módulo Caja de su país se rechaza con una caja abierta o con plata en sus cajas (misma regla que la baja de una caja); y Saldos muestra, arriba de las tarjetas por PDV, una línea por país con la plata que hay en sus cajas. No hay permisos nuevos ni cambios en la matriz: el panel va bajo abm_estaciones (solo Admin). Ver el manual de Estaciones, el flujo 2.7 y las pantallas 4.5 y 4.6 del análisis funcional de Caja.

Antes de desplegar a Staging (una sola vez, lo corre Carlos) ​

El deploy agrega la columna cash_boxes.active con default true: ninguna caja existente cambia de estado y ningún permiso cambia. Una sola cosa para mirar antes, porque la regla nueva impide crearla pero no arregla las que ya existen: una caja que quedó abierta en un PDV que ya estaba inactivo. Esa caja deja de aparecer en Saldos del operador (su PDV no es operable) y no hay forma de cerrarla desde la pantalla. La consulta, de solo lectura y sin datos personales:

sql
select st.internal_code, cb.number, s.opened_at
from cash_sessions s
join cash_boxes cb on cb.id = s.cash_box_id
join stations st on st.id = cb.station_id
where s.status = 'OPEN' and st.active = false;

Si no devuelve filas, no hay nada que hacer. Si devuelve alguna: un Admin reactiva el PDV (Parámetros → Estaciones / PDV), la caja vuelve a verse, se la cierra y recién ahí se vuelve a desactivar el PDV.

Lo mismo con dos casos más, que la regla nueva tampoco arregla en lo que ya existe (cash_boxes.active no existía): una caja abierta en un país con el módulo Caja apagado, y plata en las cajas de un PDV inactivo o de un país con el módulo apagado. Esas cajas no son operables, no figuran en Saldos y nadie puede cerrarlas ni retirarles la plata desde la pantalla. Las consultas, también de solo lectura y sin datos personales (el saldo mira solo la moneda del ledger de cada caja, sin importar cuál sea):

sql
-- (b) cajas abiertas en un país sin módulo Caja
select co.iso_code, st.internal_code, cb.number, s.opened_at
from cash_sessions s
join cash_boxes cb on cb.id = s.cash_box_id
join stations st on st.id = cb.station_id
join countries co on co.id = st.country_id
where s.status = 'OPEN' and co.modulo_caja = false;

-- (c) plata en cajas de un PDV inactivo o de un país sin módulo Caja (por moneda del ledger)
select co.iso_code, st.internal_code, cb.number, m.currency, sum(m.amount_local) as saldo
from cash_movements m
join cash_boxes cb on cb.id = m.cash_box_id
join stations st on st.id = cb.station_id
join countries co on co.id = st.country_id
where st.active = false or co.modulo_caja = false
group by co.iso_code, st.internal_code, cb.number, m.currency
having sum(m.amount_local) <> 0;

(b) se arregla como (a): reactivar el módulo Caja del país, cerrar la caja y volver a apagarlo. (c) no rompe nada —la plata sigue en el ledger, en Reportes → Cajas y en Distribuido en cajas—, pero la franja de país de Saldos (caso 8) va a ser mayor que la suma de las tarjetas mientras ese PDV siga inactivo; reactivar el PDV la hace volver a su tarjeta.

Antes de empezar ​

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

EmailRolAlcancePara qué sirve acá
admin@cislatam.testAdminGuatemala, todos los PDVAdministra las cajas (única cuenta con abm_estaciones:write), mira Auditoría y Reportes
backoffice@cislatam.testCajeroSolo GT-CAP-001El Cajero A: abre y cierra cajas
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002Ve los Totales por PDV y la línea de país con alcance parcial
tesoreria@cislatam.testTesoreríaGuatemalaFondea y ajusta cajas (no las abre ni las cierra) y mira Fondeo PDVs

Cajas del PDV de pruebas. Con admin@, en Parámetros → Estaciones / PDV, la fila de GT-CAP-001 tiene que tener tres cajas activas: Administrar → + agregar caja las dos que falten (el caso 1 lo recorre). Las cajas nuevas nacen cerradas y en cero. El caso 6 deja una de ellas con plata.

Cajas abiertas de pruebas anteriores. Antes de empezar, en Saldos cerrar (con admin@, que puede con todas) cualquier caja de GT-CAP-001 que haya quedado abierta, y confirmar que nadie tiene una caja abierta a su nombre: la regla de una caja abierta por usuario haría fallar los pasos de apertura.

Herramientas. Adminer (http://localhost:8081) para mirar la base y la metadata de Auditoría; la sección Por API de más abajo para los pedidos que la pantalla no ofrece.


1. El panel «Administrar» y el alta ​

#PasoResultado esperado
1.1Como admin@, Parámetros → Estaciones / PDV, mirar la columna Cajas de GT-CAP-001Dice cuántas cajas activas tiene («1 caja», «3 cajas»), y trae los botones Administrar y + agregar caja. Un PDV de un país sin módulo Caja muestra —
1.2Tocar AdministrarDiálogo «Cajas de …» con todas las cajas del PDV, cada una con su estado Activa (o Inactiva), un texto que dice que una caja no se borra, se desactiva, y los botones Desactivar por caja, + agregar caja y Cerrar. El foco queda en Cerrar
1.3Dentro del panel, tocar + agregar caja (hasta tener Caja 1, 2 y 3)Aparece la caja siguiente, Activa. Se anuncia el resultado («Caja 2 agregada.») y la celda de la tabla pasa a «2 cajas» sin recargar la pantalla
1.4Auditoría, mirar el último eventoCaja agregada, a nombre de admin@, con el detalle «Caja 2» y sin ningún monto
1.5Con admin@, abrir el panel con la Caja 1 abierta por el Cajero A (antes, backoffice@ la abre en Saldos)La Caja 1 dice «Abierta ahora por backoffice@cislatam.test» y «Para desactivarla, primero hay que cerrarla.» Sin botón Desactivar. Las otras cajas sí lo tienen
1.6Cerrar la Caja 1 como A y volver a abrir el panelYa no dice «Abierta ahora por» y vuelve a ofrecer Desactivar (el panel pide la lista cada vez que se abre)
1.7Cerrar el panel con CerrarSe cierra y la celda de la tabla sigue diciendo lo mismo. Al abrirlo de nuevo, la lista se pide otra vez

2. Desactivar una caja cerrada y en cero ​

Con las tres cajas de GT-CAP-001 cerradas y en cero (si alguna tiene plata, ver el caso 6).

#PasoResultado esperado
2.1En el panel, tocar Desactivar en la Caja 3La fila muestra una confirmación en la misma fila: «¿Desactivar la Caja 3?», «Deja de aparecer en Saldos y no se puede abrir. Conserva su número y su historial, y se puede volver a activar.», con Cancelar y Desactivar. No se abre un segundo diálogo encima
2.2Tocar CancelarLa confirmación se cierra, la caja sigue Activa y el foco vuelve al botón Desactivar de esa caja
2.3Volver a tocar Desactivar y confirmarLa Caja 3 pasa a Inactiva y el botón pasa a Activar. Se anuncia «Caja 3 desactivada.». La celda dice «2 cajas · 1 inactiva» (cuenta solo las activas y avisa de la de baja)
2.4Como backoffice@ (Cajero A), entrar a SaldosVe la Caja 1 y la Caja 2 de GT-CAP-001 (con selector). No ve la Caja 3
2.5Como supervisor@, Saldos → Totales por PDV, tarjeta de GT-CAP-001Dice «0 de 2 cajas abiertas» (el total cuenta solo las cajas operables) y, al entrar al PDV, las tarjetas son las de la Caja 1 y la Caja 2
2.6Intentar abrir la Caja 3 por API (pedido c de más abajo)422 CASH_BOX_INACTIVE, con el texto «La Caja 3 de … no se puede abrir: está desactivada.». En Adminer, cash_sessions no tiene una sesión nueva de esa caja
2.7Como admin@, Reportes → Cajas, elegir Guatemala y el rango de hoyLa Caja 3 figura en el resumen, con la etiqueta Inactiva en Estado (no Abierta ni Cerrada). El Excel y el PDF del resumen también dicen Inactiva
2.8Reportes → Cierres por día, rango que incluya las sesiones que tuvo esa caja (si tuvo)Sus filas siguen apareciendo igual: la baja no borra la historia
2.9Auditoría, último eventoCaja desactivada, a nombre de admin@, detalle «Caja 3». En Adminer, la metadata del evento CASH_BOX_DEACTIVATED es solo {station_id, number}: ningún monto
2.10Pedir de nuevo active: false sobre la Caja 3 por API (pedido b)200 con active: false y ningún evento nuevo en Auditoría

3. Reactivar ​

#PasoResultado esperado
3.1En el panel, Activar en la Caja 3Confirmación «¿Activar la Caja 3?» con «Vuelve a aparecer en Saldos y se puede abrir, con el saldo que tenía.». Al confirmar pasa a Activa, se anuncia «Caja 3 activada.» y la celda vuelve a «3 cajas»
3.2Como Cajero A, en SaldosLa Caja 3 vuelve a aparecer con su número y su saldo, y se puede abrir y cerrar como cualquier otra
3.3AuditoríaCaja activada, detalle «Caja 3», sin montos

4. El número no se reutiliza ​

#PasoResultado esperado
4.1Desactivar la Caja 3 (la última) y tocar + agregar cajaLa caja nueva es la Caja 4, no la 3. La Caja 3 sigue en la lista como Inactiva
4.2Reactivar la Caja 3Vuelve con su número; el PDV tiene Caja 1, 2, 3 y 4

5. Una caja abierta no se desactiva ​

#PasoResultado esperado
5.1Como Cajero A, abrir la Caja 2 (con la Caja 1 cerrada). Como admin@, pedir el PATCH active: false sobre la Caja 2 por API (pedido b)409 CASH_BOX_HAS_OPEN_SESSION, «La Caja 2 tiene una sesión abierta. Cerrala antes de desactivarla.». La caja sigue activa y abierta
5.2Panel desactualizado: con la Caja 2 cerrada, abrir el panel como admin@; en otra sesión, A abre la Caja 2; en el panel del Admin, que todavía muestra Desactivar, tocarlo y confirmarEn la fila de la caja, un aviso con el texto del backend («La Caja 2 tiene una sesión abierta. Cerrala antes de desactivarla.») y la lista se actualiza sola: la caja pasa a decir «Abierta ahora por backoffice@…» y ya no ofrece el botón
5.3Desactivar contra abrir, al mismo tiempo (la carrera real; el test automático fija el orden de las consultas, no dos procesos). Con la Caja 2 cerrada, lanzar a la vez, desde dos terminales, el POST /caja/{id}/apertura del Cajero A y el PATCH active: false de admin@ (repetirlo unas veces)Siempre una de dos: o la apertura da 201 y el PATCH da 409 CASH_BOX_HAS_OPEN_SESSION, o el PATCH da 200 y la apertura da 422 CASH_BOX_INACTIVE. Nunca la apertura con 201 y el PATCH con 200
5.4Después de cada repetición, en Adminer: select count(*) from cash_boxes cb join cash_sessions s on s.cash_box_id = cb.id where s.status = 'OPEN' and cb.active = false;0: no puede haber una caja inactiva con una sesión abierta. Reactivar la caja y cerrar la sesión si quedó abierta antes de seguir
5.5Cerrar la Caja 2 abierta por ALa caja vuelve a poder desactivarse

6. Una caja con plata no se desactiva: se la deja en cero ​

Es el camino que decidió Carlos (D3-14 a) y el que más personas toca: abre un Cajero, un Supervisor o un Admin, ajusta Tesorería o un Admin, cierra quien tenga el permiso y desactiva un Admin. Se usa la Caja 2 de GT-CAP-001.

#PasoResultado esperado
6.1Como A, abrir la Caja 2. Como tesoreria@, en Saldos, elegir la Caja 2 y fondearla con 100 y el motivo Fondeo inicial. Como A, cerrarlaLa Caja 2 queda cerrada con saldo 100
6.2Como admin@, en el panel, Desactivar la Caja 2 y confirmarEn la fila, un aviso con el texto «La Caja 2 todavía tiene plata. Dejala en cero con un ajuste de motivo «Retiro por baja de caja» (hay que abrirla para ajustarla y cerrarla después) y volvé a desactivarla.», más la lista «Para dejarla en cero:» con los cuatro pasos (abrir desde Saldos, ajuste negativo con ese motivo, cerrar, volver acá y desactivar). El aviso no dice cuánto hay. La caja sigue Activa
6.3Como A, abrir la Caja 2 (hereda el saldo, 100)Abierta, con 100
6.4Como tesoreria@, en la Caja 2, cambiar el formulario a Ajuste y mirar los motivosLa lista trae Faltante de arqueo, Sobrante de arqueo, Retiro por baja de caja y Otro (en ese orden). En Fondeo el motivo nuevo no figura
6.5Elegir el motivo Retiro por baja de caja, antes de cargar el monto; después cargar un ajuste de +100Al elegir el motivo, el formulario avisa «Saca plata de la caja para dejarla en cero antes de darla de baja: cargá el monto en negativo.» (con Faltante de arqueo no aparece). Con +100 queda rechazado: el formulario muestra el error del backend (422, «El retiro por baja de caja saca plata de la caja: el monto tiene que ser negativo.»). El saldo sigue en 100 y no hay un movimiento nuevo
6.6Cargar un ajuste de −100 con el motivo Retiro por baja de cajaNotificación Caja ajustada. El saldo de la Caja 2 pasa a 0. En el historial figura el movimiento con su motivo; filtrando por motivo Retiro por baja de caja sale solo ese
6.7Como tesoreria@, Fondeo PDVs → País (Guatemala), comparando con lo que decía antes del ajuste de 6.6El Distribuido en cajas bajó 100 y el Disponible para distribuir subió 100; el saldo del país no cambió (un ajuste no es un pago). El retiro aparece como un movimiento con su signo en el extracto
6.8Como A, cerrar la Caja 2Cerrada, saldo 0
6.9Como admin@, Desactivar la Caja 2Funciona: pasa a Inactiva
6.10Auditoría, mirar los últimos eventos del díaEl ajuste figura como CASH_ADJUSTED (esa acción todavía no tiene etiqueta en español ni está en el filtro) y su metadata lleva el monto y el motivo, como todos los ajustes. La desactivación de 6.9 no lleva monto: es «Caja desactivada» con el detalle «Caja 2»
6.11Reactivar la Caja 2 al terminarVuelve con saldo 0; el resto de los planes de prueba la usan
6.12Mirar el aviso de 6.2 de nuevo (con plata, antes de retirarla)Debajo de los cuatro pasos hay una nota: «Si la caja guarda efectivo en una moneda anterior del país, el retiro no lo alcanza (el ajuste se registra en la moneda vigente): pedí soporte.» Es el único caso sin salida por estos pasos; hoy ningún país cambió de moneda, así que no se arma a mano (lo cubre StationApiTest)

7. Los tres huecos de H3-06 (PDV, país y Caja 1) ​

Con un PDV de pruebas sin caja abierta y con sus cajas en cero: desactivar un PDV con plata en alguna caja da 409 (caso 7.10), y los PDV de demostración suelen tener saldo. Lo más simple es crear un PDV nuevo en Guatemala para la prueba (nace con su Caja 1 y sin saldo); si no, usar uno cuyas cajas estén en cero. Dejarlo activo al terminar.

#PasoResultado esperado
7.1Como admin@, desactivar el PDV (botón de la fila → confirmar) y abrir su panel de cajasUn aviso: «Este PDV está inactivo: ninguna de sus cajas se puede abrir hasta que se reactive, estén activas o no.», y + agregar caja deshabilitado
7.2Intentar agregar una caja a ese PDV por API (pedido d)422 STATION_INACTIVE, «Este PDV está inactivo: reactivalo antes de agregarle cajas.»
7.3Con el PDV inactivo, como Cajero o Supervisor con alcance a él, mirar SaldosSus cajas no figuran: no son operables. Tampoco se pueden abrir por API (422 CASH_BOX_INACTIVE, «…su PDV está inactivo.»). Desactivar el PDV no desactivó sus cajas: en el panel siguen Activas
7.4Reactivar el PDVSus cajas vuelven solas a Saldos, sin tocar nada
7.5Abrir una caja de un PDV (Cajero A) e intentar desactivar el PDV como admin@409 STATION_HAS_OPEN_CASH_BOX: arriba de la tabla de estaciones, «Este PDV tiene una caja abierta. Hay que cerrarla antes de desactivarlo.». El PDV sigue activo y la lista de PDV no desaparece
7.6Con el mismo PDV, editar otro campo (el responsable, por ejemplo) y guardar con la caja abiertaGuarda: reenviar active: true en cada guardado no se frena por tener una caja abierta
7.7Cerrar la caja y desactivar el PDVFunciona. Reactivarlo al terminar
7.8Agregar una caja a un PDV de un país sin módulo Caja (Ecuador) por API (pedido d)422 CASH_MODULE_DISABLED, «El país de este PDV no opera con módulo Caja: no se le pueden agregar cajas.». En la pantalla, esa fila muestra — en Cajas
7.9Si hay un PDV en un país sin módulo Caja: editarlo y cambiarle el país a GuatemalaAl guardar, el PDV tiene una Caja 1 (panel → «1 caja»). Si después se le desactiva esa Caja 1 y se renombra el PDV (sin tocar el país), la Caja 1 no vuelve: solo se crea al cambiar de país. Cubierto por StationApiTest; no hace falta armarlo a mano si no hay un PDV a mano
7.10Con una caja de un PDV con saldo (la Caja 2 con 100, como en 6.1), desactivar el PDV como admin@409 STATION_HAS_CASH_BALANCE: arriba de la tabla de estaciones, «Este PDV tiene plata en sus cajas. Dejalas en cero con un ajuste de motivo «Retiro por baja de caja» (…) antes de desactivarlo.», sin ningún monto. El PDV sigue activo. Después de dejar en cero todas las cajas del PDV (casos 6.3 a 6.8), se desactiva
7.11Con una caja abierta (o con plata), cambiarle el país al PDV y guardar409 (STATION_HAS_OPEN_CASH_BOX o STATION_HAS_CASH_BALANCE), con «…antes de moverlo de país.» en el aviso del formulario. El PDV sigue en su país
7.12Parámetros → Países, editar un país con módulo Caja que tiene una caja abierta (o con plata) en un PDV activo y apagar el módulo Caja409 COUNTRY_HAS_OPEN_CASH_BOX o COUNTRY_HAS_CASH_BALANCE, con el texto en el formulario y sin ningún monto. El módulo sigue prendido. Con las cajas cerradas y en cero, se apaga. Reactivarlo al terminar (ojo: reactivar le crea su Caja 1 a los PDV que no tengan ninguna caja)
7.13Activar una caja dada de baja en un PDV inactivo (panel)La confirmación dice «Queda activa, pero no aparece en Saldos ni se puede abrir mientras el PDV esté inactivo.» (no «Vuelve a aparecer en Saldos…») y el anuncio «Caja N activada, pero no se puede abrir mientras el PDV esté inactivo.»

8. La línea de país en Saldos ​

#PasoResultado esperado
8.1Como admin@, Saldos → Totales por PDVArriba de las tarjetas por PDV, una franja «Guatemala · USD …», con separador de miles y dos decimales («USD 24,878.53»)
8.2Sumar a mano las tarjetas por PDV visiblesEl total de la franja es la suma de los saldos de las tarjetas, salvo que haya un PDV inactivo con plata en sus cajas (solo uno que ya estaba así antes de G7): ese PDV no tiene tarjeta pero su plata cuenta en la franja, igual que en Distribuido en cajas (ver «Antes de desplegar», consulta c)
8.3Como tesoreria@, Fondeo PDVs → País, mirar Distribuido en cajas de GuatemalaEl mismo número que la franja de 8.1. Es la misma cuenta, no una parecida
8.4Hacer un fondeo a una caja (Tesorería) y recargar Saldos como admin@La franja sube lo mismo que el fondeo y coincide otra vez con Distribuido en cajas
8.5Como supervisor@, Saldos → Totales por PDVSi el Supervisor ve todos los PDV de Guatemala que tienen caja, la franja dice «Guatemala · USD …». Si hay otro PDV con cajas que no ve (revisar en Parámetros → Estaciones / PDV), dice «Total de tus PDV · USD …» y el número es la suma de sus tarjetas, menor que el Distribuido en cajas del país
8.6Como backoffice@ (Cajero)No hay franja ni totales: el Cajero no tiene fondeo_caja:read
8.7Al entrar a las cajas de un PDV (tocar una tarjeta)La franja no se muestra: es de la pantalla de totales. Al volver a Totales por PDV, reaparece
8.8Pantalla angosta (375 px) y modo oscuroLa franja se lee en los dos temas, entra sin scroll horizontal y el separador no queda pegado («Guatemala · USD …», no «Guatemala·USD …»)
8.9Por API, GET /caja/totales-pdv como admin@Trae countries[] con un objeto por país: country {id, iso_code, name}, currency, total y scope_complete: true. Con supervisor@ y alcance parcial, scope_complete: false
8.10Durante el caso 6: anotar la franja antes del fondeo de 6.1, después del fondeo y después del retiro de 6.6Sube 100 con el fondeo y baja 100 con el retiro, hasta quedar donde empezó. En cada paso sigue coincidiendo con Distribuido en cajas de Fondeo PDVs

9. No se rompió nada de lo que ya existía ​

#PasoResultado esperado
9.1Como A, abrir una caja, pagar una transacción y cerrar la cajaTodo funciona como siempre
9.2Como admin@, desactivar y reactivar una estación (no una caja)Funciona como siempre, con su evento en Auditoría
9.3Sin permiso: un usuario que no es Admin intenta el PATCH de una caja por API (pedido e)403
9.4El PATCH con una caja que no es del PDV de la URL (pedido f)404 CASH_BOX_NOT_FOUND, «Esa caja no es de este PDV.»
9.5El PATCH sin active (o con un valor que no es booleano)422 de validación
9.6Auditoría, desplegar el filtro de accionesFiguran Caja agregada, Caja desactivada y Caja activada
9.7Panel en 375 px y modo oscuroSe lee entero, los botones se pueden tocar y los bordes de cada caja se ven en los dos temas
9.8Como un usuario con abm_estaciones de solo lectura (si existe una cuenta así; si no, lo cubre el test)La celda dice Ver en vez de Administrar, no hay + agregar caja y el panel lista las cajas sin botones de cambio

Por API ​

Con el emulador de Firebase de dev. {estacion} es el id del PDV (de GET /admin/estaciones) y {caja} el de la caja (de GET /admin/estaciones/{estacion}/cajas, o de GET /caja/disponibles para una caja activa). Cada pedido se corre con el token del usuario que dice el caso.

bash
login() {  # login <email> <password de dev.md>
  curl -s -X POST 'http://localhost:9099/identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=fake-api-key' \
    -H 'Content-Type: application/json' \
    -d "{\"email\":\"$1\",\"password\":\"$2\",\"returnSecureToken\":true}" \
    | python3 -c 'import sys,json;print(json.load(sys.stdin)["idToken"])'
}

TOKEN_ADMIN=$(login admin@cislatam.test '<su contraseña>')
TOKEN_A=$(login backoffice@cislatam.test '<su contraseña>')

# (a) la lista de cajas de un PDV, con active y quién la tiene abierta (opened_by)
curl -s -H "Authorization: Bearer $TOKEN_ADMIN" "http://localhost:3000/admin/estaciones/{estacion}/cajas" | python3 -m json.tool

# (b) desactivar (o reactivar con "active": true)
curl -s -X PATCH -H "Authorization: Bearer $TOKEN_ADMIN" -H 'Content-Type: application/json' \
  -d '{"active": false}' "http://localhost:3000/admin/estaciones/{estacion}/cajas/{caja}"

# (c) intentar abrir una caja (la desactivada da 422 CASH_BOX_INACTIVE)
curl -s -X POST -H "Authorization: Bearer $TOKEN_A" "http://localhost:3000/caja/{caja}/apertura"

# (d) agregar una caja (en un PDV inactivo o de un país sin módulo Caja da 422)
curl -s -X POST -H "Authorization: Bearer $TOKEN_ADMIN" "http://localhost:3000/admin/estaciones/{estacion}/cajas"

# (e) el mismo PATCH con un usuario sin abm_estaciones:write (A) -> 403
curl -s -X PATCH -H "Authorization: Bearer $TOKEN_A" -H 'Content-Type: application/json' \
  -d '{"active": false}' "http://localhost:3000/admin/estaciones/{estacion}/cajas/{caja}"

# (f) una caja de OTRO PDV en la URL -> 404 CASH_BOX_NOT_FOUND
curl -s -X PATCH -H "Authorization: Bearer $TOKEN_ADMIN" -H 'Content-Type: application/json' \
  -d '{"active": false}' "http://localhost:3000/admin/estaciones/{otro-estacion}/cajas/{caja}"
#PedidoResultado esperado
aGET /admin/estaciones/{estacion}/cajasPor caja: id, station_id, number, active, created_at y opened_by ({id, email} o null). Las inactivas se listan
bPATCH …/cajas/{caja} con active: false200 {data: {id, station_id, number, active: false, …}} sobre una caja cerrada y en cero; 409 CASH_BOX_HAS_OPEN_SESSION con una sesión abierta; 409 CASH_BOX_HAS_BALANCE con plata (en cualquier moneda); 200 sin evento si ya estaba inactiva
cPOST /caja/{caja}/apertura sobre una caja desactivada, de un PDV inactivo o de un país sin módulo Caja422 CASH_BOX_INACTIVE, con el texto de cuál de las tres razones es
dPOST …/cajas422 CASH_MODULE_DISABLED o 422 STATION_INACTIVE según el caso; con un PDV activo de un país con módulo Caja, 201 con la caja nueva y active: true
eEl PATCH con un usuario sin abm_estaciones:write403
fEl PATCH con una caja que no es del PDV de la URL404 CASH_BOX_NOT_FOUND
gPUT /admin/estaciones/{estacion} con {"active": false} sobre un PDV con una caja abierta, o con country_id de otro país409 STATION_HAS_OPEN_CASH_BOX; con plata en alguna caja, 409 STATION_HAS_CASH_BALANCE (sin ningún monto en el texto)
hPOST /caja/{caja}/ajuste con el motivo Retiro por baja de caja y monto positivo422 en amount; con monto negativo, 201
iPOST /caja/{caja}/fondeo con el motivo Retiro por baja de caja422: no es un motivo de fondeo
jGET /caja/motivos?type=AJUSTETrae Retiro por baja de caja, antes de Otro; con type=FONDEO, no
kPUT /admin/paises/{pais} con {"modulo_caja": false} sobre un país con una caja abierta, o con plata, en un PDV activo409 COUNTRY_HAS_OPEN_CASH_BOX o COUNTRY_HAS_CASH_BALANCE (sin ningún monto en el texto); el módulo sigue prendido

Al terminar ​

  • Cerrar con admin@ cualquier caja que haya quedado abierta, y reactivar las cajas y los PDV que se hayan desactivado para las pruebas (caso 2, 3, 4, 6 y 7). En una base de dev, las cajas sobrantes (Caja 3 o 4) pueden quedar: no estorban, pero en Reportes → Cajas figuran, y las que estén Inactivas se ven marcadas.
  • Si la Caja 2 quedó con saldo distinto de cero por una prueba interrumpida, dejarla en cero con el motivo Retiro por baja de caja antes de seguir con otros planes.
  • Dejar a A y a supervisor@ activos.

Pruebas automatizadas que lo respaldan ​

bash
docker exec soterex-backend-1 php artisan test --filter StationApiTest
docker exec soterex-backend-1 php artisan test --filter CashBoxApiTest
docker exec soterex-backend-1 php artisan test --filter CajaReportesApiTest
docker exec soterex-backend-1 php artisan test --filter CountryApiTest
docker exec soterex-backend-1 php artisan test --filter PerfilesAccesoApiTest
docker exec soterex-frontend-1 sh -c 'cd /app && npx vitest run src/views/admin/__tests__/EstacionesView.spec.ts src/utils/__tests__/cajasEstacion.spec.ts src/views/reportes/__tests__/CajasView.spec.ts src/views/__tests__/CajaView.spec.ts src/views/admin/__tests__/AuditoriaView.spec.ts'

Qué cubre cada una: StationApiTest, el PATCH (permiso, activar y desactivar con su auditoría sin montos, sesión abierta, saldo, efectivo en otra moneda, caja de otro PDV, idempotencia, el número que no se reutiliza), el alta en un país sin módulo o en un PDV inactivo, desactivar un PDV o mudarlo de país con una caja abierta o con plata (y que un PDV ya inactivo o de un país sin módulo no se frene), mover un PDV a un país con módulo Caja, el listado con active y opened_by y los tests de serialización (el lock va primero, tanto en el PATCH como al desactivar un PDV; la decisión es la de la caja bloqueada, para desactivar y para reactivar); CountryApiTest, apagar el módulo Caja con cajas abiertas o con plata; CashBoxApiTest, disponibles y totales-pdv sin cajas inactivas, de un PDV inactivo ni de un país sin módulo Caja, la apertura de una caja inactiva (422) y su test de carrera, el motivo nuevo (catálogo, signo, no es de fondeo, filtro del historial), el flujo completo de la baja de una caja con plata y el bloque countries[] (coincide con distributedInCashBoxes y con las tarjetas, alcance parcial, perfiles mezclados, nunca suma entre países ni monedas); CajaReportesApiTest, el resumen con la caja inactiva marcada, el export que dice Inactiva y que Cierres por día, el detalle, el PDF y Distribuido en cajas siguen viendo la caja de baja; PerfilesAccesoApiTest, que el listado del panel, el alta y la baja de una caja dan 403 a Cajero, Supervisor y Tesorería y funcionan para el Admin; y las del frontend, la celda «N cajas · M inactivas · Administrar», el panel con sus estados y quién la tiene abierta, la confirmación, los 409 con los pasos para dejarla en cero, el alta desde el panel y desde la celda, desactivar un PDV con una caja abierta, el rótulo Inactiva de Reportes, las etiquetas de Auditoría y la línea de país (el rótulo completo y el parcial, varios países sin sumar monedas, y que no se dibuje sin países ni para quien no ve totales).

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