Skip to content

Plan de Pruebas — G6: quién opera cada caja y quién la cierra ​

Fecha: 2026-10-06 Decisión: ADR-021 (reemplaza en parte a ADR-013 §5) · plan de ajustes v3, entrega G6 (RV3-24 a 27, H3-03, H3-12; decisiones D3-12 B y D3-13 i) Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba

Qué cambió: cada caja abierta dice quién la tiene; solo la cierra quien la abrió, un Supervisor o un Admin del PDV (antes, cualquier usuario con el permiso de cerrar cajas sobre ese PDV); la pantalla ofrece Cerrar caja únicamente a quien puede; a quien le cierran la caja, el pago le responde que no tiene una abierta; el Supervisor de un PDV deja de ver los saldos de otro PDV donde es Cajero; y la baja de un usuario con una caja abierta lo avisa. No hay permisos nuevos ni cambios en la matriz: lo que cambia rige desde el deploy. Ver el manual, el flujo 2.2 y la secuencia 3.6 del análisis funcional de Caja.

Antes de empezar ​

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

EmailRolAlcancePara qué sirve acá
backoffice@cislatam.testCajeroSolo GT-CAP-001Es el Cajero A: abre la caja y se va sin cerrarla
Un segundo Cajero de GT-CAP-001CajeroSolo GT-CAP-001Es el Cajero B: el compañero que no puede cerrar la caja de A. En dev no existe: se crea desde Usuarios y Accesos con admin@ (alta por correo; la contraseña se muestra una sola vez, copiarla) y se le asigna Cajero, Guatemala, PDV GT-CAP-001. En Staging, la cuenta equivalente es la que crea G0.7 del plan de ajustes v3, si ya está creada
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002Cierra la caja de A
admin@cislatam.testAdminGuatemala, todos los PDVCierra cualquiera, mira Auditoría, da de baja usuarios
tesoreria@cislatam.testTesoreríaGuatemalaNo abre ni cierra cajas: control

Los perfiles mezclados (Supervisor de un PDV y Cajero de otro; Cajero más Tesorería) no existen en dev: los cubren los tests (caso 5). Si G0.7 ya creó las cuentas en Staging, el caso 5 también se puede recorrer por pantalla.

Una caja por PDV. En dev, GT-CAP-001 tiene una sola caja, así que el sistema entra directo a la vista operativa, sin selector. Para ver las tarjetas del selector hay que sumarle una Caja 2 desde Parámetros → Estaciones / PDV con admin@ (sección Cajas por estación): los casos 1.2 y 1.5 dicen qué mirar en cada modo.

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.


1. La caja dice quién la tiene ​

#PasoResultado esperado
1.1Como Cajero A (backoffice@), en Saldos, tocar Abrir caja de la Caja 1 de GT-CAP-001 y confirmarNotificación Caja abierta. Debajo del estado, «Abierta el dd/mm/aaaa hh:mm por vos»
1.2Como Cajero B, entrar a Saldos. Con una caja: se ve la vista operativa. Con selector: mirar la tarjeta de la Caja 1El estado es Caja abierta y dice «Abierta por backoffice@cislatam.test» (en la tarjeta del selector y en la vista operativa: «Abierta el … por backoffice@…»). El saldo está oculto (—): no es suyo, y aun así ve quién la tiene
1.3Seguir como B, en la Caja 1 de ANo hay botón Abrir caja (la caja ya está abierta) ni Cerrar caja. En su lugar, una tarjeta gris con el ícono de información: «La abrió backoffice@cislatam.test: solo esa persona, un Supervisor o un Admin pueden cerrarla.» El panel de la derecha dice «No podés ver el detalle de esta caja: solo se ve el de la que tenés abierta» (no «Sin movimientos todavía») y no ofrece exportar
1.4Como A, volver a mirar la tarjeta de la misma cajaDice «Abierta por vos» y A ve su saldo real. Sí tiene Cerrar caja
1.5Como supervisor@, entrar a Saldos (abre en Totales por PDV), elegir GT-CAP-001, mirar la tarjeta de la Caja 1 y tocarlaEn la tarjeta, «Abierta por backoffice@cislatam.test» y el saldo real; en la vista operativa, el mismo dato y el botón Cerrar caja
1.6Como tesoreria@, mirar la misma cajaVe quién la tiene y el saldo, sin botones de abrir ni de cerrar
1.7Cajero B hace el Abrir por API (ver «Por API», pedido a)409 CASH_ALREADY_OPEN con el mensaje «La Caja 1 de … la tiene abierta backoffice@cislatam.test.» y opened_by con el id y el correo de A
1.8Volver a mirar la caja de A: Adminer, select count(*) from cash_sessions where cash_box_id = '<id de la caja>' and status = 'OPEN'1. La sesión de A quedó intacta, con su opening_balance y su fecha de apertura
1.9A hace el mismo Abrir por API sobre su propia caja409 CASH_ALREADY_OPEN con «Ya tenés abierta la Caja 1 de …» (sin su correo)
1.10Con la pantalla de B abierta, A cierra su caja y otra persona (por ejemplo el Supervisor) la abre; B toca Abrir cajaNo pasa nada malo: B ve la notificación «La caja ya está abierta» con el correo de quien la tiene, el modal se cierra y la pantalla se pone al día, sin botón de abrir

2. B no puede cerrar la caja de A ​

Empezar con la Caja 1 abierta por A (si el caso 1.10 la dejó abierta por otra persona, cerrarla con admin@ y que A la abra de nuevo). Opcional: que A pague una transacción con esa caja y deje la papeleta firmada sin subir, para el paso 2.4.

#PasoResultado esperado
2.1Como B, en la Caja 1 de ANo se ofrece Cerrar caja (ver 1.3)
2.2Como B, hacer el POST /caja/{id}/cierre por API (pedido b)403 con code: CASH_CLOSE_NOT_OWNER y el mensaje «Esta caja la abrió otra persona. Solo quien la abrió, un Supervisor o un Admin pueden cerrarla.»
2.3Mirar la caja como A y como admin@ en AuditoríaLa caja de A sigue abierta; no hay ningún evento CASH_SESSION_CLOSED nuevo
2.4Con una papeleta firmada pendiente de un pago de A, repetir 2.2 como B403 igual (no un 422 PENDING_PAYMENT_DOCUMENTS): quien no puede cerrar la caja no se entera de qué pagos de otro tienen documentos sin subir
2.5Como tesoreria@, el mismo POST al cierre403 PERMISSION_DENIED (no tiene apertura_cierre_caja)
2.6Pantalla desactualizada: con la Caja 1 cerrada, B la abre y no recarga; en otra sesión, supervisor@ cierra esa caja y A la abre. En la pantalla de B, que todavía muestra Cerrar caja, tocarlo y confirmarNotificación de error «No se pudo cerrar la caja» con el mensaje del 403; la pantalla se refresca y deja de ofrecer el botón
2.7Dos que pueden cerrar la misma: que A y supervisor@ tengan abierta la pantalla de la Caja 1 de A; A la cierra; supervisor@, que todavía ve Cerrar caja, lo toca y confirmaNotificación de error con «No hay una sesión de caja abierta para esta sucursal.»; la pantalla se refresca y pasa a Caja cerrada (ya no dice Caja abierta ni ofrece Cerrar caja)

3. El Supervisor la cierra, y queda auditado ​

#PasoResultado esperado
3.1Como supervisor@, en la Caja 1 de A, tocar Cerrar cajaEl diálogo muestra el texto de siempre más: «Esta caja la abrió backoffice@cislatam.test: esa persona no va a poder pagar hasta volver a abrirla. El cierre queda registrado a tu nombre.»
3.2Confirmar (si A dejó una papeleta firmada pendiente, ver 3.3)Notificación Caja cerrada. La caja pasa a Caja cerrada con el mismo saldo que tenía
3.3Con una papeleta firmada pendiente de un pago de A: el cierre del Supervisor422 PENDING_PAYMENT_DOCUMENTS con el MTCN y qué falta: el control de documentos rige igual para el Supervisor. Subir la papeleta firmada desde Pago o la ficha de la transacción (puede: es Supervisor de ese PDV) y volver a cerrar: ahora cierra
3.4Como admin@, Auditoría, filtrar por la acción Cierre de cajaAparece el cierre a nombre de supervisor@, con el detalle «cerró la caja que abrió otra persona» y sin el saldo final. En Adminer, ese CASH_SESSION_CLOSED trae cierre_ajeno: true, opened_by_user_id el de A y from_previous_day: false
3.5Como A, en Pago, buscar una ACCEPTED con los datos y los documentos completos y Iniciar pago → Confirmar pago422 NO_CASH_BOX_OPEN_FOR_USER: «No tenés ninguna caja abierta a tu nombre — abrí una desde Saldos antes de pagar.» No se descontó nada y la transacción sigue ACCEPTED
3.6Como A, en Saldos, abrir la cajaHereda el saldo con el que la cerró el Supervisor (el mismo número que mostraba al cerrarse). Ya puede pagar
3.7Control: como A, cerrar su propia cajaCierra. En Auditoría, el evento de A tiene cierre_ajeno: false
3.8Control: como admin@, abrir una caja con otro usuario y cerrarla con admin@Cierra, con cierre_ajeno: true: el Admin cierra cualquiera

4. La caja vencida de un cajero ausente ​

Es el caso que motivó el cambio de regla (ADR-013 §5): A se fue sin cerrar. Se arma igual que en el plan de pruebas de G4a (paso 1.9): A abre su caja y, en Adminer, se atrasa un día la sesión: update cash_sessions set opened_at = opened_at - interval '1 day' where status = 'OPEN' and opened_by_user_id = '<id de A>'.

#PasoResultado esperado
4.1Como A, en SaldosAviso ámbar fijo «Esta caja quedó abierta desde el dd/mm/aaaa. Cerrala y abrila de nuevo para operar hoy.» con el botón Cerrar caja dentro
4.2Como B, en Saldos, en la misma cajaEl aviso dice «Esta caja quedó abierta desde el dd/mm/aaaa.» y «Hasta que se cierre no se puede pagar, fondear ni ajustar con ella.» sin el botón y sin «Cerrala y abrila». Agrega: «Esta caja la abrió backoffice@cislatam.test: solo esa persona, un Supervisor o un Admin pueden cerrarla. Pedile a un Supervisor o un Admin que la cierre.» No hay link a Pago ni la línea de pagos pendientes
4.3Como B, el POST al cierre por API403 CASH_CLOSE_NOT_OWNER; la sesión sigue OPEN
4.4Como tesoreria@, mirar la caja vencidaEl aviso, sin botón y sin «Cerrala y abrila de nuevo»: dice «Esta caja la abrió backoffice@cislatam.test: solo esa persona, un Supervisor o un Admin pueden cerrarla. Pedile a un Supervisor o un Admin que la cierre.» (Tesorería mira la caja de otro: no le habla como a su dueña)
4.5Como supervisor@, en la caja vencidaEl aviso trae Cerrar caja y dice «La abrió backoffice@cislatam.test. Al cerrarla el saldo se mantiene y esa persona la puede abrir de nuevo para operar hoy.» Sin «Cerrala y abrila de nuevo» ni «Hasta que la cierres» ni sus propios pagos pendientes: no es su caja. Tocarlo: la confirmación avisa que la abrió A y que quedará a su nombre. Cierra (con la regla de documentos de 3.3 si corresponde; si se frena, el aviso dice qué MTCN faltan y «Hay que subir lo que falta y volver a cerrar»)
4.6Como admin@, probar lo mismo con otra caja vencida de ACierra
4.7Como A, después, abrir de nuevoHereda el saldo, no se tipea, y vuelve a operar

5. Perfiles mezclados (H3-03 y el cierre ajeno) ​

Con más de una asignación, «es Supervisor» se decide por PDV y dentro de una misma asignación. Lo prueba el CI, por API, con los roles reales de RoleSeeder:

bash
docker exec soterex-backend-1 php artisan test --filter PermissionServiceCajaTest
docker exec soterex-backend-1 php artisan test --filter CashBoxApiTest
docker exec soterex-backend-1 php artisan test --filter PerfilesAccesoApiTest
#Qué compruebaResultado esperado
5.1Supervisor del PDV A y Cajero del PDV BVe el saldo real de las cajas de A; en B, balance: null en la caja de otro; el historial de B da 403 CASH_BOX_BALANCE_HIDDEN; totales-pdv trae solo A
5.2Supervisor del PDV A y Tesorería del país enteroSigue viendo todo (regresión)
5.3Cierre de la caja que abrió otro, en el PDV A: Cajero de A403
5.4Lo mismo con Supervisor de A200, y el evento queda con cierre_ajeno
5.5Lo mismo con Supervisor de otro PDV403 PERMISSION_DENIED (el alcance por PDV lo corta antes)
5.6Lo mismo con quien es Cajero de A y Supervisor de B403: junta las dos capacidades, pero la que supervisa es la de B
5.7Lo mismo con quien es Cajero de A y Tesorería del país403: la apertura viene de una asignación y fondeo_caja:read de la otra
5.8Lo mismo con Tesorería sola403 (no tiene apertura_cierre_caja)
5.9Lo mismo con Admin200
5.10GET /caja/disponibles con 4 cajas abiertas por 4 usuarios distintos, GET /caja/totales-pdv con 3 y el resumen de Reportes → Cajas con 4Las sesiones se traen con una consulta y los operadores con una, no una por caja (H3-12); pasar de 2 a 6 cajas no suma consultas a las cajas, los PDV ni las sesiones
5.11GET /caja/disponibles, la sesión de cada cajaTrae opened_by y can_close, y no trae opened_by_supervisor_id
5.12Quien abrió una caja y hoy tiene un perfil sin apertura_cierre_caja (por ejemplo, Tesorería)can_close: false y el POST al cierre da 403 PERMISSION_DENIED: el botón no se ofrece donde la ruta rechaza
5.13Dos aperturas de la misma caja que chocan en el índice único (la carrera)409 CASH_ALREADY_OPEN con quién la tiene; si la que ganó ya se cerró cuando se la va a leer, el mismo 409 sin nombre. Una sola sesión abierta

Con las cuentas mixtas de G0.7 en Staging, recorrerlo por pantalla (el caso 5.14 de abajo): el Supervisor de A que es Cajero de B ve, en Saldos, saldo real en A y «—» en la caja de otro en B, y solo ve Cerrar caja sobre cajas ajenas de A.

#Paso (cuenta mixta: Supervisor de A y Cajero de B)Resultado esperado
5.14Entrar a SaldosLos Totales por PDV traen solo el PDV A. Debajo, «Otras cajas a tu alcance» con las cajas de B (sin saldo, «—»): el Cajero de B no queda sin entrada a su caja
5.15Tocar la caja de B, abrirla, y volver con Totales por PDVSe opera como Cajero (abre, cierra la suya); el saldo de B sigue en «—» salvo el de la caja que abrió él. Al volver aparecen otra vez los totales de A y las otras cajas
5.16La cuenta inversa (Cajero de A y Supervisor de B)Los totales traen B; la caja de A aparece en «Otras cajas a tu alcance»

6. La baja de un usuario con una caja abierta ​

#PasoResultado esperado
6.1Que A tenga una caja abierta. Como admin@, en Usuarios y Accesos, desactivar a ALa baja se hace. Aparece un aviso que no se va solo, «Quedó una caja abierta», con el texto «Este usuario tiene abierta la Caja 1 de … Como ya no puede entrar, esa caja solo la puede cerrar un Supervisor o un Admin del PDV: avisales para que no quede trabada.»
6.2Descartar el aviso con la XDesaparece
6.3Mirar la caja de A como supervisor@Sigue abierta (la baja no cierra nada). El Supervisor la cierra con Cerrar caja
6.4Reactivar a A y volver a desactivarlo sin caja abiertaSin aviso. Tampoco hay aviso al editar a un usuario que no se da de baja
6.5Dejar a A activo al terminarEl resto de los planes de prueba lo usan

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

#PasoResultado esperado
7.1A abre, paga una transacción y cierra su cajaTodo funciona como siempre. El evento de cierre tiene cierre_ajeno: false
7.2A abre una segunda caja con la primera abierta409 USER_ALREADY_HAS_OPEN_CASH_BOX, en el modal, como siempre
7.3Como tesoreria@, fondear una caja abierta por AFunciona; la caja sigue siendo de A
7.4Como admin@, Reportes → Cierres por díaMuestra, por cada apertura, quién la cerró; los cierres ajenos aparecen a nombre de quien cerró
7.5Como un Cajero, Saldos en una caja cerrada de su PDVAbrir caja como siempre; el selector dice «Caja cerrada» y no «Abierta por»
7.6Pantalla angosta (375 px) y modo oscuro, en las tarjetas con «Abierta por» y en el avisoEl correo largo parte sin romper el diseño; los textos se leen en los dos temas
7.7Con A con su caja abierta en GT-CAP-001, que admin@ le cambie la asignación a otro PDV (Usuarios y Accesos) y que A intente abrir una caja de ese otro PDV409 USER_ALREADY_HAS_OPEN_CASH_BOX con «…ya no tenés acceso a ese PDV para cerrarla: pedile a un Supervisor o un Admin de … que la cierre antes de abrir otra.» (no «Cerrala»). La cierra supervisor@ o admin@. No hay aviso al reasignar: queda como punto abierto (pregunta #22). Restaurar la asignación de A al terminar
7.8Como admin@, Auditoría, desplegar el filtro de accionesFigura Cierre de caja

Por API ​

Con el emulador de Firebase de dev. {id} es el cash_box_id: sale de GET /caja/disponibles o de la URL de la ficha en Adminer. 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_B=$(login <email de B> '<su contraseña>')

# (a) B intenta abrir la caja que tiene abierta A  -> 409 CASH_ALREADY_OPEN, con quién la tiene
curl -s -X POST -H "Authorization: Bearer $TOKEN_B" 'http://localhost:3000/caja/{id}/apertura'

# (b) B intenta cerrar la caja que abrió A          -> 403 CASH_CLOSE_NOT_OWNER
curl -s -X POST -H "Authorization: Bearer $TOKEN_B" 'http://localhost:3000/caja/{id}/cierre'

# (c) qué puede hacer B sobre cada caja             -> session.opened_by, session.can_close
curl -s -H "Authorization: Bearer $TOKEN_B" 'http://localhost:3000/caja/disponibles' | python3 -m json.tool
#PedidoResultado esperado con B (Cajero) sobre la caja abierta por A
aPOST /caja/{id}/apertura409, code: CASH_ALREADY_OPEN, message «La Caja 1 de … la tiene abierta backoffice@cislatam.test.», opened_by: {id, email}
bPOST /caja/{id}/cierre403, code: CASH_CLOSE_NOT_OWNER
cGET /caja/disponiblesLa caja trae session.opened_by (id y correo de A) y session.can_close: false; balance y opening_balance en null
dLos mismos pedidos (b) y (c) con supervisor@(b) 200; (c) can_close: true y balance real

Al terminar ​

  • Cerrar con admin@ cualquier caja que haya quedado abierta (y las vencidas que armó el caso 4).
  • Dejar a A, B y supervisor@ activos. Borrar a B no hace falta: una cuenta de prueba más no estorba.
  • Si se tocó la fecha de una sesión en Adminer (caso 4), no hay nada que revertir: la sesión ya está cerrada.

Pruebas automatizadas que lo respaldan ​

bash
docker exec soterex-backend-1 php artisan test --filter CashBoxApiTest
docker exec soterex-backend-1 php artisan test --filter PerfilesAccesoApiTest
docker exec soterex-backend-1 php artisan test --filter PermissionServiceCajaTest
docker exec soterex-backend-1 php artisan test --filter UserApiTest
docker exec soterex-backend-1 php artisan test --filter CajaReportesApiTest
docker exec soterex-frontend-1 sh -c 'cd /app && npx vitest run src/views/__tests__/CajaView.spec.ts src/components/__tests__/AvisoCajaVencida.spec.ts src/views/admin/__tests__/UsuariosView.spec.ts src/views/admin/__tests__/AuditoriaView.spec.ts'

Qué cubre cada una: CashBoxApiTest, el cierre ajeno por perfil, el 403 antes de los documentos, can_close (también para quien abrió la caja y ya no la puede operar), opened_by, el 409 con quién la tiene (incluida la carrera del índice único), el pago de quien perdió la caja y el conteo de consultas; CajaReportesApiTest, el conteo de consultas del resumen; PerfilesAccesoApiTest, la fila POST /caja/{abierta por otro}/cierre (Cajero 403, Supervisor 200, Tesorería 403, Admin 200) y el Supervisor de un PDV que es Cajero de otro; PermissionServiceCajaTest, las dos funciones solas, incluida la regla de la misma asignación; UserApiTest, el aviso de la baja; y las del frontend, que el botón Cerrar caja no aparece sobre una caja ajena para el Cajero y sí para quien puede, los textos de «Abierta por» y los avisos de la caja vencida según quién mira (dueño, Supervisor, Cajero, Tesorería), las «Otras cajas a tu alcance» de los perfiles mezclados, el detalle oculto de una caja ajena, el 409 CASH_NOT_OPEN al cerrar, las anclas del recorrido guiado y la etiqueta del cierre en Auditoría.

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