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):
| Rol | Alcance | Para qué sirve acá | |
|---|---|---|---|
backoffice@cislatam.test | Cajero | Solo GT-CAP-001 | Es el Cajero A: abre la caja y se va sin cerrarla |
| Un segundo Cajero de GT-CAP-001 | Cajero | Solo GT-CAP-001 | Es 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.test | Supervisor | GT-CAP-001 y GT-QUE-002 | Cierra la caja de A |
admin@cislatam.test | Admin | Guatemala, todos los PDV | Cierra cualquiera, mira Auditoría, da de baja usuarios |
tesoreria@cislatam.test | Tesorería | Guatemala | No 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
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | Como Cajero A (backoffice@), en Saldos, tocar Abrir caja de la Caja 1 de GT-CAP-001 y confirmar | Notificación Caja abierta. Debajo del estado, «Abierta el dd/mm/aaaa hh:mm por vos» |
| 1.2 | Como Cajero B, entrar a Saldos. Con una caja: se ve la vista operativa. Con selector: mirar la tarjeta de la Caja 1 | El 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.3 | Seguir como B, en la Caja 1 de A | No 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.4 | Como A, volver a mirar la tarjeta de la misma caja | Dice «Abierta por vos» y A ve su saldo real. Sí tiene Cerrar caja |
| 1.5 | Como supervisor@, entrar a Saldos (abre en Totales por PDV), elegir GT-CAP-001, mirar la tarjeta de la Caja 1 y tocarla | En 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.6 | Como tesoreria@, mirar la misma caja | Ve quién la tiene y el saldo, sin botones de abrir ni de cerrar |
| 1.7 | Cajero 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.8 | Volver 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.9 | A hace el mismo Abrir por API sobre su propia caja | 409 CASH_ALREADY_OPEN con «Ya tenés abierta la Caja 1 de …» (sin su correo) |
| 1.10 | Con la pantalla de B abierta, A cierra su caja y otra persona (por ejemplo el Supervisor) la abre; B toca Abrir caja | No 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.
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como B, en la Caja 1 de A | No se ofrece Cerrar caja (ver 1.3) |
| 2.2 | Como 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.3 | Mirar la caja como A y como admin@ en Auditoría | La caja de A sigue abierta; no hay ningún evento CASH_SESSION_CLOSED nuevo |
| 2.4 | Con una papeleta firmada pendiente de un pago de A, repetir 2.2 como B | 403 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.5 | Como tesoreria@, el mismo POST al cierre | 403 PERMISSION_DENIED (no tiene apertura_cierre_caja) |
| 2.6 | Pantalla 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 confirmar | Notificació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.7 | Dos 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 confirma | Notificació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
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Como supervisor@, en la Caja 1 de A, tocar Cerrar caja | El 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.2 | Confirmar (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.3 | Con una papeleta firmada pendiente de un pago de A: el cierre del Supervisor | 422 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.4 | Como admin@, Auditoría, filtrar por la acción Cierre de caja | Aparece 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.5 | Como A, en Pago, buscar una ACCEPTED con los datos y los documentos completos y Iniciar pago → Confirmar pago | 422 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.6 | Como A, en Saldos, abrir la caja | Hereda el saldo con el que la cerró el Supervisor (el mismo número que mostraba al cerrarse). Ya puede pagar |
| 3.7 | Control: como A, cerrar su propia caja | Cierra. En Auditoría, el evento de A tiene cierre_ajeno: false |
| 3.8 | Control: 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>'.
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Como A, en Saldos | Aviso á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.2 | Como B, en Saldos, en la misma caja | El 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.3 | Como B, el POST al cierre por API | 403 CASH_CLOSE_NOT_OWNER; la sesión sigue OPEN |
| 4.4 | Como tesoreria@, mirar la caja vencida | El 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.5 | Como supervisor@, en la caja vencida | El 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.6 | Como admin@, probar lo mismo con otra caja vencida de A | Cierra |
| 4.7 | Como A, después, abrir de nuevo | Hereda 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:
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é comprueba | Resultado esperado |
|---|---|---|
| 5.1 | Supervisor del PDV A y Cajero del PDV B | Ve 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.2 | Supervisor del PDV A y Tesorería del país entero | Sigue viendo todo (regresión) |
| 5.3 | Cierre de la caja que abrió otro, en el PDV A: Cajero de A | 403 |
| 5.4 | Lo mismo con Supervisor de A | 200, y el evento queda con cierre_ajeno |
| 5.5 | Lo mismo con Supervisor de otro PDV | 403 PERMISSION_DENIED (el alcance por PDV lo corta antes) |
| 5.6 | Lo mismo con quien es Cajero de A y Supervisor de B | 403: junta las dos capacidades, pero la que supervisa es la de B |
| 5.7 | Lo mismo con quien es Cajero de A y Tesorería del país | 403: la apertura viene de una asignación y fondeo_caja:read de la otra |
| 5.8 | Lo mismo con Tesorería sola | 403 (no tiene apertura_cierre_caja) |
| 5.9 | Lo mismo con Admin | 200 |
| 5.10 | GET /caja/disponibles con 4 cajas abiertas por 4 usuarios distintos, GET /caja/totales-pdv con 3 y el resumen de Reportes → Cajas con 4 | Las 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.11 | GET /caja/disponibles, la sesión de cada caja | Trae opened_by y can_close, y no trae opened_by_supervisor_id |
| 5.12 | Quien 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.13 | Dos 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.14 | Entrar a Saldos | Los 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.15 | Tocar la caja de B, abrirla, y volver con Totales por PDV | Se 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.16 | La 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
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Que A tenga una caja abierta. Como admin@, en Usuarios y Accesos, desactivar a A | La 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.2 | Descartar el aviso con la X | Desaparece |
| 6.3 | Mirar la caja de A como supervisor@ | Sigue abierta (la baja no cierra nada). El Supervisor la cierra con Cerrar caja |
| 6.4 | Reactivar a A y volver a desactivarlo sin caja abierta | Sin aviso. Tampoco hay aviso al editar a un usuario que no se da de baja |
| 6.5 | Dejar a A activo al terminar | El resto de los planes de prueba lo usan |
7. No se rompió nada de lo que ya existía
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | A abre, paga una transacción y cierra su caja | Todo funciona como siempre. El evento de cierre tiene cierre_ajeno: false |
| 7.2 | A abre una segunda caja con la primera abierta | 409 USER_ALREADY_HAS_OPEN_CASH_BOX, en el modal, como siempre |
| 7.3 | Como tesoreria@, fondear una caja abierta por A | Funciona; la caja sigue siendo de A |
| 7.4 | Como admin@, Reportes → Cierres por día | Muestra, por cada apertura, quién la cerró; los cierres ajenos aparecen a nombre de quien cerró |
| 7.5 | Como un Cajero, Saldos en una caja cerrada de su PDV | Abrir caja como siempre; el selector dice «Caja cerrada» y no «Abierta por» |
| 7.6 | Pantalla angosta (375 px) y modo oscuro, en las tarjetas con «Abierta por» y en el aviso | El correo largo parte sin romper el diseño; los textos se leen en los dos temas |
| 7.7 | Con 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 PDV | 409 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.8 | Como admin@, Auditoría, desplegar el filtro de acciones | Figura 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.
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| # | Pedido | Resultado esperado con B (Cajero) sobre la caja abierta por A |
|---|---|---|
| a | POST /caja/{id}/apertura | 409, code: CASH_ALREADY_OPEN, message «La Caja 1 de … la tiene abierta backoffice@cislatam.test.», opened_by: {id, email} |
| b | POST /caja/{id}/cierre | 403, code: CASH_CLOSE_NOT_OWNER |
| c | GET /caja/disponibles | La caja trae session.opened_by (id y correo de A) y session.can_close: false; balance y opening_balance en null |
| d | Los 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
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.

