Skip to content

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 403 del backend, que se prueba por API (caso 5).

Antes de empezar ​

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

EmailRolAlcancePara qué sirve acá
backoffice@cislatam.testCajeroSolo GT-CAP-001Paga, sube lo que falta y no reemplaza (casos 1 y 2); corrige antes de pagar (caso 4)
supervisor@cislatam.testSupervisorGT-CAP-001 y GT-QUE-002, sin PDV activoReemplaza en los dos PDV (caso 2)
admin@cislatam.testAdminGuatemala, todos los PDVReemplaza (caso 3) y mira Auditoría (caso 6)
tesoreria@cislatam.testTesoreríaGuatemalaFondea 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á ​

#PasoResultado esperado
1.1Como 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 pagarlaLa transacción queda PAID y descuenta la caja
1.2Todaví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.3Subir la Papeleta firmada (un tipo que todavía no estaba)Se sube (201) y el badge baja Faltan N
1.4En Saldos, Cerrar cajaLa caja cierra: es el caso que no se puede romper
1.5Mirar la Papeleta firmada que acaba de subir, y por API intentar subirla de nuevoYa 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 ​

#PasoResultado esperado
2.1Como 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.2Reemplazar la Carta subiendo otro archivoSe sube (201); el casillero pasa a mostrar el archivo nuevo. El anterior no se borra (queda en la base y en el almacenamiento)
2.3Reemplazar la Carta una segunda vez201. En Auditoría (caso 6) el segundo reemplazo apunta al documento vigente, no al original

3. El Admin reemplaza ​

#PasoResultado esperado
3.1Como admin@, abrir la misma ficha y reemplazar la Identificación (anverso)201; puede_reemplazar es true
3.2Hacer lo mismo con una transacción cancelada que tenga documentosSe 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 ​

#PasoResultado esperado
4.1Como backoffice@, en Pago, buscar otra ACCEPTED, subir la Carta y volver a subir otra CartaLos dos pedidos responden 201: el Cajero corrige hasta «Confirmar pago»
4.2Hacer lo mismo con la Identificación (anverso)201 las dos veces
4.3Mirar 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 ​

#PasoResultado esperado
5.1Como un Supervisor asignado solo a GT-QUE-002, buscar el MTCN de una pagada que quedó en GT-CAP-001La búsqueda la encuentra, pero sin datos personales
5.2Por API: GET /transacciones/{id}/documentos y POST /transacciones/{id}/documentos con esa transacción404 en los dos (no 403: no confirma que la transacción existe)
bash
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"])'
#PedidoResultado esperado
5.3El pedido de arriba con backoffice@ y una PAID que pagó élpuede_subir true, puede_reemplazar false
5.4El mismo con supervisor@puede_subir true, puede_reemplazar true
5.5El 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 ​

#PasoResultado esperado
6.1Como admin@, Auditoría, filtrar por Documento del pago reemplazadoUn 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.2Filtrar por Documento del pago subidoLos asientos de las subidas comunes (caso 1.3), con el tipo en palabras. Un reemplazo no deja además un asiento de subida
6.3Subir un archivo cuyo nombre sea reconocible (por ejemplo dpi-maria-lopez.pdf) a una ACCEPTED y mirar el asientoEl asiento trae el tipo y el tamaño, no el nombre. El nombre sigue visible en el propio documento
6.4En 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 archivoEn 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 ​

#PasoResultado esperado
7.1Con 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.2Como backoffice@, abrir una PAID de GT-CAP-001 que haya pagado otroLa 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.3Repetir 7.2 con una PAID de GT-CAP-001 que haya pagado backoffice@ mismoSube lo que falta (quien pagó siempre puede) y sigue sin poder reemplazar: puede_subir true, puede_reemplazar false
7.4Como backoffice@, abrir una PAID de GT-QUE-002 que haya pagado otropuede_reemplazar es true: ahí sí es Supervisor
7.5Dar a un usuario Cajero más Tesorería en Guatemala y repetir 7.2Igual 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) ​

bash
docker exec soterex-backend-1 php artisan test --filter 'DocumentosReemplazoApiTest|PermissionServiceTransactionScopeTest|TransactionDocumentApiTest|PagadorOtroPdvApiTest'
TestQué fija
test_el_cajero_que_pago_no_reemplaza_un_documento_ya_cargado403 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_cajaSubir 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_archivoEl documento anterior queda; TRANSACTION_DOCUMENT_REPLACED con el id reemplazado, sin nombre
test_el_admin_reemplaza · test_un_supervisor_de_otro_pdv_recibe_404El Admin reemplaza; el de otro PDV recibe 404
test_en_accepted_el_cajero_reemplaza_la_carta_y_la_identificacionAntes 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_pagadaLa unión con Tesorería no hace supervisor; CANCELLED igual que PAID
test_la_auditoria_de_una_subida_no_guarda_el_nombre_original_del_archivoH3-09
test_la_papeleta_de_una_pagada_la_descarga_un_cajero_que_no_la_pagoLa 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_500Un 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_viejoH3-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_aEl 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_listaLa 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.tsEl 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.

#PasoResultado esperado
9.1Como backoffice@, en Pago, buscar una PAID que pagó él con documentos cargadosDocumentació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.2Como 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.3Como admin@, reemplazar la Carta; después mirar la fila sin recargarSe 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.4Como un Cajero que no pagó esa PAID pero la puede ver (mismo PDV), entrar a la ficha. Después, como tesoreria@, intentar abrirlaCajero: 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.5En cualquiera de las anteriores, mirar la fila del títuloDos 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.6Tocar cada botónEl 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.7A 375 px, mirar el encabezadoTí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.8Como admin@, en Parámetros → Países, mirar el formato de reciboLas 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.9Abrir una PAID (como cualquiera de los tres perfiles) y mirar Datos del pagoTodos 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.10Como backoffice@, en Pago, subir la Carta a una ACCEPTED (la que dejó el paso 4.1) y volver a buscarlaEn 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.11Con la misma ACCEPTED, subir ahora la Identificación (anverso) en esa pantallaAparece 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.12Con una ACCEPTED sin documentos, subir los tres seguidosNunca 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.

#PasoResultado esperado
10.1Como backoffice@ (Cajero), en Pago, abrir la ACCEPTEDVe Iniciar pago. No ve Cancelar transacción
10.2Como supervisor@, lo mismoVe Iniciar pago. No ve Cancelar transacción
10.3Como admin@, lo mismoVe los dos: Iniciar pago y Cancelar transacción
10.4Pagar con backoffice@ (con la caja abierta y fondeada, como en el caso 1.1)Se paga; la transacción queda PAID
10.5Con otra ACCEPTED, cancelar con admin@ y poner un motivoQueda 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):

bash
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"
#PedidoResultado esperado
10.6PATCH /transacciones/{id}/cancel con backoffice@403 con code PERMISSION_DENIED. La transacción sigue ACCEPTED
10.7Lo mismo con supervisor@403; sigue ACCEPTED
10.8Lo mismo con admin@200; queda CANCELLED
10.9PATCH /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:read y transacciones:write y 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_DOCUMENTS donde 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_reemplazar lo 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.

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