Plan de Pruebas — G5: subir lo que falta no es reemplazar lo cargado
Fecha: 2026-10-06 Decisión: ADR-011 (actualización G5) · plan de ajustes v3, entrega G5 (RV3-03, 08, 10; P3-1, P3-2, P3-3; D3-9 a) Ambiente: Dev local (./start-dev.sh) — http://localhost:5173 — o Staging con las cuentas de prueba
Qué cambió: el backend distingue subir un documento que falta de reemplazar uno ya cargado. Con la transacción pagada o cancelada, quien pagó sigue subiendo lo que falta (la papeleta firmada, sin la cual la caja no cierra), pero solo un Supervisor con alcance sobre el PDV y un Admin reemplazan. «Supervisor» se decide dentro de una misma asignación: un Supervisor del PDV B que es Cajero del PDV A no supervisa el A. Cada reemplazo deja TRANSACTION_DOCUMENT_REPLACED en Auditoría, y la subida común deja de guardar el nombre del archivo. Ver Pago con documentos, §1.6 y 2.5.
Este plan cubre las reglas del backend, la Auditoría y lo que cambia en la pantalla. Los casos 1 a 8 son las reglas (por pantalla y por API); el caso 9 mira la pantalla de G5 y el caso 10 cubre el hueco heredado de B6, pagar sin cancelar por perfil: el botón Reemplazar que solo ve quien puede, la línea «Solo consulta», los dos botones de la papeleta, los campos de una pagada deshabilitados y «Subido por» con el aviso en los documentos previos al pago. Donde un paso dice «intentar reemplazar» con alguien que no puede, la pantalla ya no ofrece el botón: el control definitivo es el
403del backend, que se prueba por API (caso 5).
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 | Paga, sube lo que falta y no reemplaza (casos 1 y 2); corrige antes de pagar (caso 4) |
supervisor@cislatam.test | Supervisor | GT-CAP-001 y GT-QUE-002, sin PDV activo | Reemplaza en los dos PDV (caso 2) |
admin@cislatam.test | Admin | Guatemala, todos los PDV | Reemplaza (caso 3) y mira Auditoría (caso 6) |
tesoreria@cislatam.test | Tesorería | Guatemala | Fondea la caja del Cajero y comprueba que no gana soportes |
Para el caso 5 hace falta un Supervisor acotado solo a GT-QUE-002, y para el caso 7 un Cajero con una segunda asignación de Supervisor en otro PDV. En dev no existen: se crean con admin@ desde Usuarios y Accesos (el usuario, en el emulador, como en dev.md, «Crear un usuario de prueba adicional»). En Staging, las cuentas son las de G0.7 del plan de ajustes v3, si ya están creadas.
Transacción de prueba: una ACCEPTED sin documentos (el seed de demo las trae). El caso 1 la paga como backoffice@, con una caja abierta hoy en Saldos y con saldo (lo carga tesoreria@). Los casos 2, 3, 5 y 6 usan esa misma transacción ya pagada.
1. Quien pagó sube lo que falta, y no pisa lo que ya está
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | Como backoffice@, abrir la caja del día en Saldos; como tesoreria@, fondearla. En Pago, buscar la ACCEPTED, completar los datos, subir Carta e identificación (anverso y reverso) y pagarla | La transacción queda PAID y descuenta la caja |
| 1.2 | Todavía como backoffice@, en la misma ficha, mirar la Carta. Después, por API, intentar reemplazarla (POST /transacciones/{id}/documentos con type=CARTA, ver el caso 5) | En la pantalla, la Carta cargada no tiene botón Reemplazar y debajo de la lista dice «Solo consulta…» (caso 9). Por API se rechaza con 403 CANNOT_REPLACE_DOCUMENTS («Ese documento ya está cargado y no se puede reemplazar. Si hay un error, pedile a un Supervisor o a un Administrador que lo corrija…»). No queda un documento nuevo: el casillero sigue mostrando el mismo archivo |
| 1.3 | Subir la Papeleta firmada (un tipo que todavía no estaba) | Se sube (201) y el badge baja Faltan N |
| 1.4 | En Saldos, Cerrar caja | La caja cierra: es el caso que no se puede romper |
| 1.5 | Mirar la Papeleta firmada que acaba de subir, y por API intentar subirla de nuevo | Ya no ofrece Reemplazar (acaba de pasar de «falta» a «cargada»). Por API, 403 CANNOT_REPLACE_DOCUMENTS: ya es un reemplazo |
2. El Supervisor del PDV reemplaza
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como supervisor@, abrir la ficha de la transacción pagada en el paso 1.1 (buscándola por MTCN) | Ve los documentos y, en la API, puede_reemplazar es true |
| 2.2 | Reemplazar la Carta subiendo otro archivo | Se sube (201); el casillero pasa a mostrar el archivo nuevo. El anterior no se borra (queda en la base y en el almacenamiento) |
| 2.3 | Reemplazar la Carta una segunda vez | 201. En Auditoría (caso 6) el segundo reemplazo apunta al documento vigente, no al original |
3. El Admin reemplaza
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Como admin@, abrir la misma ficha y reemplazar la Identificación (anverso) | 201; puede_reemplazar es true |
| 3.2 | Hacer lo mismo con una transacción cancelada que tenga documentos | Se comporta igual que una pagada: el Admin y el Supervisor del PDV reemplazan; quien la canceló y no supervisa, no |
4. Con la transacción todavía disponible, nada cambia
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Como backoffice@, en Pago, buscar otra ACCEPTED, subir la Carta y volver a subir otra Carta | Los dos pedidos responden 201: el Cajero corrige hasta «Confirmar pago» |
| 4.2 | Hacer lo mismo con la Identificación (anverso) | 201 las dos veces |
| 4.3 | Mirar Auditoría (caso 6) | El segundo asiento es Documento del pago reemplazado, con el estado aceptada |
5. Un Supervisor de otro PDV no ve la transacción
| # | Paso | Resultado esperado |
|---|---|---|
| 5.1 | Como un Supervisor asignado solo a GT-QUE-002, buscar el MTCN de una pagada que quedó en GT-CAP-001 | La búsqueda la encuentra, pero sin datos personales |
| 5.2 | Por API: GET /transacciones/{id}/documentos y POST /transacciones/{id}/documentos con esa transacción | 404 en los dos (no 403: no confirma que la transacción existe) |
TOKEN=$(curl -s -X POST 'http://localhost:9099/identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=fake-api-key' \
-H 'Content-Type: application/json' \
-d '{"email":"backoffice@cislatam.test","password":"<la de dev.md>","returnSecureToken":true}' \
| python3 -c 'import sys,json;print(json.load(sys.stdin)["idToken"])')
# El {id} sale de la URL de la ficha en Reporte individual. Con el Cajero que pagó:
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:3000/transacciones/{id}/documentos" \
| python3 -c 'import sys,json;d=json.load(sys.stdin);print("puede_subir",d["puede_subir"],"puede_reemplazar",d["puede_reemplazar"])'| # | Pedido | Resultado esperado |
|---|---|---|
| 5.3 | El pedido de arriba con backoffice@ y una PAID que pagó él | puede_subir true, puede_reemplazar false |
| 5.4 | El mismo con supervisor@ | puede_subir true, puede_reemplazar true |
| 5.5 | El mismo con tesoreria@ | 403: Tesorería no tiene Transacciones, y la unión con otro perfil no se la da |
6. Auditoría: qué queda y qué no
| # | Paso | Resultado esperado |
|---|---|---|
| 6.1 | Como admin@, Auditoría, filtrar por Documento del pago reemplazado | Un asiento por cada reemplazo de los casos 2, 3 y 4, a nombre de quien lo hizo, con el detalle «Carta de Soterex · transacción pagada» (o aceptada, cancelada). Ninguno muestra un nombre de archivo ni un id |
| 6.2 | Filtrar por Documento del pago subido | Los asientos de las subidas comunes (caso 1.3), con el tipo en palabras. Un reemplazo no deja además un asiento de subida |
| 6.3 | Subir un archivo cuyo nombre sea reconocible (por ejemplo dpi-maria-lopez.pdf) a una ACCEPTED y mirar el asiento | El asiento trae el tipo y el tamaño, no el nombre. El nombre sigue visible en el propio documento |
| 6.4 | En una base que tenga subidas anteriores a G5 (Staging), mirar Auditoría, Exportar PDF y el Historial de la ficha de esa transacción. En dev no hay: lo cubre AuditLogApiTest (caso 8), que siembra un asiento viejo con nombre de archivo | En ninguno de los tres aparece el nombre del archivo: el sistema lo oculta al mostrar, aunque el asiento lo siga teniendo en la base (H3-09) |
7. «Supervisa» es una asignación, no la suma de varias
| # | Paso | Resultado esperado |
|---|---|---|
| 7.1 | Con admin@, darle a backoffice@ una segunda asignación: rol Supervisor, Guatemala, solo GT-QUE-002 (la de Cajero en GT-CAP-001 queda como está) | Dos asignaciones en la ficha |
| 7.2 | Como backoffice@, abrir una PAID de GT-CAP-001 que haya pagado otro | La ve (su alcance de escritura es la unión de las dos), pero puede_subir y puede_reemplazar son false; subir y reemplazar responden 403 CANNOT_MANAGE_DOCUMENTS. Antes de G5 subía, porque «es Supervisor» y «tiene el PDV» se contaban cada uno por su lado |
| 7.3 | Repetir 7.2 con una PAID de GT-CAP-001 que haya pagado backoffice@ mismo | Sube lo que falta (quien pagó siempre puede) y sigue sin poder reemplazar: puede_subir true, puede_reemplazar false |
| 7.4 | Como backoffice@, abrir una PAID de GT-QUE-002 que haya pagado otro | puede_reemplazar es true: ahí sí es Supervisor |
| 7.5 | Dar a un usuario Cajero más Tesorería en Guatemala y repetir 7.2 | Igual que 7.2: Tesorería suma fondeo_caja:read, pero no hace supervisor |
| 7.6 | Con la asignación del 7.1 puesta, como backoffice@, abrir Pago y mirar el aviso «Tenés N pagos con documentación pendiente» (hace falta una PAID de GT-CAP-001 pagada por otro y una de GT-QUE-002, las dos sin la Papeleta firmada) | El aviso lista la de GT-QUE-002 (donde supervisa) y lo que pagó él mismo en GT-CAP-001; no lista la de GT-CAP-001 que pagó otro: ahí es Cajero, la ve en «Solo consulta» y no puede completarla |
Al terminar, borrar la segunda asignación de backoffice@.
8. Lo que ya prueba el CI (por API)
docker exec soterex-backend-1 php artisan test --filter 'DocumentosReemplazoApiTest|PermissionServiceTransactionScopeTest|TransactionDocumentApiTest|PagadorOtroPdvApiTest'| Test | Qué fija |
|---|---|
test_el_cajero_que_pago_no_reemplaza_un_documento_ya_cargado | 403 CANNOT_REPLACE_DOCUMENTS, sin fila ni archivo nuevos y sin asiento de reemplazo |
test_el_cajero_que_pago_sube_la_papeleta_firmada_y_cierra_la_caja | Subir lo que falta sigue permitido y el cierre de caja se destraba |
test_el_supervisor_del_pdv_reemplaza_y_queda_auditado_sin_el_nombre_del_archivo | El documento anterior queda; TRANSACTION_DOCUMENT_REPLACED con el id reemplazado, sin nombre |
test_el_admin_reemplaza · test_un_supervisor_de_otro_pdv_recibe_404 | El Admin reemplaza; el de otro PDV recibe 404 |
test_en_accepted_el_cajero_reemplaza_la_carta_y_la_identificacion | Antes de pagar el Cajero corrige |
test_el_supervisor_de_b_que_es_cajero_de_a_no_reemplaza_ni_sube_en_a | «Supervisa» dentro de una misma asignación |
test_cajero_mas_tesoreria_* · test_una_cancelada_se_comporta_igual_que_una_pagada | La unión con Tesorería no hace supervisor; CANCELLED igual que PAID |
test_la_auditoria_de_una_subida_no_guarda_el_nombre_original_del_archivo | H3-09 |
test_la_papeleta_de_una_pagada_la_descarga_un_cajero_que_no_la_pago | La papeleta sigue abierta a quien puede ver la transacción |
PermissionServiceTransactionScopeTest (assignment_holds_*, can_replace_*) | El helper de P3-2 y la regla, sin pasar por HTTP |
test_un_tipo_inventado_o_con_bytes_invalidos_da_422_y_no_500 | Un type que no es del catálogo (o que no es UTF-8) da 422, nunca 500 |
test_el_listado_y_el_pdf_no_traen_el_nombre_del_archivo_de_los_asientos_viejos · test_el_historial_de_la_ficha_no_trae_el_nombre_del_archivo_de_un_asiento_viejo | H3-09 sobre lo ya guardado: se oculta al leer (caso 6.4) |
test_pendientes_de_un_supervisor_de_b_que_es_cajero_de_a_no_cuenta_lo_ajeno_de_a | El aviso de pendientes sigue la regla de «una misma asignación» (caso 7.6) |
test_la_respuesta_de_subir_trae_quien_y_cuando_como_la_lista | La respuesta del POST trae uploaded_by (id y mail) y created_at, igual que la lista (caso 9.3) |
DocumentacionPago.spec.ts · DocumentacionPrePago.spec.ts · DatosPagoForm.spec.ts · useTransactionDocuments.spec.ts | El frontend: una acción por fila, Solo consulta, los dos botones con su formato explícito, el aviso de los previos, el estilo de deshabilitado |
9. La pantalla (G5.4 a G5.7)
Mirar cada caso a 1280 px y a 375 px (sin scroll horizontal), en claro y en oscuro.
| # | Paso | Resultado esperado |
|---|---|---|
| 9.1 | Como backoffice@, en Pago, buscar una PAID que pagó él con documentos cargados | Documentación del pago: los documentos cargados se pueden abrir y no tienen botón; los huecos vacíos (Foto del cliente, Papeleta firmada) dicen Subir. Debajo: «Solo consulta: los documentos cargados no se modifican; si hay un error, pedíselo a un Supervisor o Admin». No se ve «Subido por» |
| 9.2 | Como supervisor@ (o admin@), abrir la misma ficha (Reporte individual) | Cada documento cargado dice Reemplazar, y debajo del nombre del archivo, «Subido por mail el dd/mm». No aparece la línea «Solo consulta» |
| 9.3 | Como admin@, reemplazar la Carta; después mirar la fila sin recargar | Se reemplaza, y la fila ya dice «Subido por (el mail del Admin) el dd/mm» (la respuesta de la subida trae quién y cuándo) |
| 9.4 | Como un Cajero que no pagó esa PAID pero la puede ver (mismo PDV), entrar a la ficha. Después, como tesoreria@, intentar abrirla | Cajero: los dos botones de papeleta están y andan; tiene que bajar el PDF aunque no la pagó y esté en modo consulta (sin botón Subir ni Reemplazar). Tesorería no llega a la ficha ni a Pago (no tiene Transacciones), así que tampoco hay botones de papeleta que ofrecerle; por API el pedido de la papeleta responde 403 |
| 9.5 | En cualquiera de las anteriores, mirar la fila del título | Dos botones, Imprimir papeleta tirilla e Imprimir papeleta A4, siempre en ese orden. El del país (A4 en Guatemala) lleva la marca predeterminado. No hay flecha ni menú Descargar en otro formato |
| 9.6 | Tocar cada botón | El de tirilla baja papeleta-{mtcn}.pdf (58 mm) y el de A4 papeleta-{mtcn}-a4.pdf (hoja con dos copias), sin importar cuál es el del país. Mientras baja, ese botón dice Generando... y los dos quedan deshabilitados |
| 9.7 | A 375 px, mirar el encabezado | Título y Faltan N arriba (el badge a la derecha); los botones debajo, en una segunda línea (o segunda y tercera si no entran los dos). Nada se corta ni hay scroll horizontal |
| 9.8 | Como admin@, en Parámetros → Países, mirar el formato de recibo | Las opciones dicen A4 y Tirilla 58 mm (ya no «Térmica»). Al pasar un país a A4 o a tirilla, la marca predeterminado cambia de botón al abrir una transacción de ese país |
| 9.9 | Abrir una PAID (como cualquiera de los tres perfiles) y mirar Datos del pago | Todos los campos se ven en gris, con el texto atenuado y el cursor de «no permitido» al pasar el mouse. En oscuro, el fondo es más hundido que la tarjeta. Una ACCEPTED editable se ve como siempre |
| 9.10 | Como backoffice@, en Pago, subir la Carta a una ACCEPTED (la que dejó el paso 4.1) y volver a buscarla | En Documentos para poder pagar, el aviso de una línea: «Este documento ya estaba cargado desde el dd/mm. Verificá que corresponda a quien tenés enfrente.», y en la fila «Subido por mail el dd/mm» |
| 9.11 | Con la misma ACCEPTED, subir ahora la Identificación (anverso) en esa pantalla | Aparece su «Subido por» y el aviso sigue (la Carta es de antes); la fila nueva no lo lleva. Reemplazar la Carta hace desaparecer el aviso |
| 9.12 | Con una ACCEPTED sin documentos, subir los tres seguidos | Nunca aparece el aviso: son de este intento |
Para ver el 403 en la pantalla (carrera): abrir la ficha de una ACCEPTED como backoffice@ en una pestaña, pagarla desde otra y volver a la primera a reemplazar la Carta: el aviso dice «No se puede reemplazar ese documento» con el mensaje del backend, no el genérico de «No tenés permiso para subir soportes». Después del aviso, la pantalla vuelve a pedir lo que se puede hacer: la Carta ya no ofrece Reemplazar (sin recargar a mano), y el segundo intento no existe.
10. Pagar sin cancelar, por perfil (B6)
Hueco heredado de B6 que este plan cubre porque la pantalla es la misma: pagar (pago:write) y cancelar (transacciones:delete) son permisos distintos, y solo el Admin cancela. Hacer cada paso sobre una ACCEPTED con los datos completos y la Carta y la identificación cargadas (el seed de demo las trae), y volver a una nueva ACCEPTED para cada perfil.
| # | Paso | Resultado esperado |
|---|---|---|
| 10.1 | Como backoffice@ (Cajero), en Pago, abrir la ACCEPTED | Ve Iniciar pago. No ve Cancelar transacción |
| 10.2 | Como supervisor@, lo mismo | Ve Iniciar pago. No ve Cancelar transacción |
| 10.3 | Como admin@, lo mismo | Ve los dos: Iniciar pago y Cancelar transacción |
| 10.4 | Pagar con backoffice@ (con la caja abierta y fondeada, como en el caso 1.1) | Se paga; la transacción queda PAID |
| 10.5 | Con otra ACCEPTED, cancelar con admin@ y poner un motivo | Queda CANCELLED sin mover ningún saldo. El Admin también puede pagar (10.3), y ahí sí descuenta |
Por API, con los mismos tres usuarios y el mismo $TOKEN de arriba (uno por perfil):
curl -s -o /dev/null -w '%{http_code}\n' -X PATCH -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"motivo":"prueba"}' "http://localhost:3000/transacciones/{id}/cancel"| # | Pedido | Resultado esperado |
|---|---|---|
| 10.6 | PATCH /transacciones/{id}/cancel con backoffice@ | 403 con code PERMISSION_DENIED. La transacción sigue ACCEPTED |
| 10.7 | Lo mismo con supervisor@ | 403; sigue ACCEPTED |
| 10.8 | Lo mismo con admin@ | 200; queda CANCELLED |
| 10.9 | PATCH /transacciones/{id}/pay con tesoreria@ | 403 con code PERMISSION_DENIED: Tesorería no tiene Pago |
Lo prueban por API, con los perfiles reales del seeder, PerfilesAccesoApiTest (test_cajero, test_supervisor, test_admin_paga_y_cancela, test_pagar_exige_pago_write_* y test_cancelar_exige_transacciones_delete_*).
Qué mirar si algo sale distinto
- Un Cajero reemplaza un documento en una pagada: hay una segunda asignación suya que reúne
fondeo_caja:readytransacciones:writey cubre ese PDV (por ejemplo, Supervisor de ese PDV). No es un defecto: es esa asignación. Mirar sus asignaciones en Usuarios y Accesos. - Un Supervisor recibe
403 CANNOT_MANAGE_DOCUMENTSdonde esperaba reemplazar: su asignación de Supervisor no cubre el PDV de la transacción (o es de otro país), y en el PDV de la transacción solo tiene una asignación de Cajero. - Un Cajero ve Reemplazar en una pagada: o la transacción está
ACCEPTED(ahí corrige hasta «Confirmar pago»), o tiene una asignación de Supervisor que cubre ese PDV. Por API,puede_reemplazarlo dice (caso 5). - Ningún botón de papeleta aparece: la lista de soportes dio 404 (se pagó en otro PDV y esa persona no la pagó): en su lugar hay un aviso gris. No es una falla.
- Los campos de una pagada se ven blancos: recargar con
Ctrl+Shift+R; el estilo llega con el deploy del frontend. - En Auditoría el reemplazo no figura: el filtro de acciones se actualiza con el deploy del frontend; recargar con
Ctrl+Shift+R.

