Skip to content

Plan de Pruebas — E5: Pago con documentos (stepper visual) ​

Fecha: 2026-09-11 Alcance: doc/plans/2026-09-11-stepper-documentos-pago-y-validacion.md — stepper visual en DocumentacionPago.vue + validación de subida/preview de los 9 tipos de documento. Ambiente: Dev local (./start-dev.sh) — http://localhost:5173

Superado en parte por G5 (2026-10-06). Este plan es del stepper de E5, anterior a los cuatro perfiles de B6 y a la regla de reemplazo de G5: sobre una transacción pagada, «reemplazar» un documento ya cargado es solo del Supervisor con alcance del PDV y del Admin (el Cajero que pagó solo sube lo que falta), y un reemplazo deja su propia constancia. Los pasos 3.10, 3.12 y 4.1 ya están corregidos abajo; para las reglas completas y la pantalla actual, ver el plan de pruebas de G5.

Antes de empezar ​

Este plan necesita los datos de demo: el seeder de demo siembra ≈95 transacciones PAID de los últimos 60 días repartidas entre los PDV, y las primeras 18 traen los datos del pago y tres documentos (Carta e Identificación anverso y reverso). No hay MTCN fijos: dependen de lo que sembró demo:reseed (la numeración arranca en 0000000101), así que donde el plan dice «una PAID de tu PDV» se la busca con la consulta de abajo, no a mano.

bash
docker compose exec backend php artisan migrate --seed
docker compose exec backend php artisan demo:reseed

Para elegir una PAID de cada PDV (la primera de cada uno):

bash
docker compose exec postgres psql -U postgres -d soterex -c \
  "SELECT s.internal_code AS pdv, min(t.mtcn) AS mtcn
   FROM transactions t JOIN stations s ON s.id = t.station_id
   WHERE t.status = 'PAID' GROUP BY s.internal_code ORDER BY 1;"

Ojo con las PAID sin PDV: el seeder deja unas pocas a propósito (la primera de todas entre ellas), resueltas por el Supervisor, que tiene dos PDV en su alcance. Un usuario acotado por PDV, como Backoffice, no las alcanza (los documentos le dan 404): no sirven para este plan salvo como Admin, y la consulta de arriba ya las deja afuera porque une con stations.

Usuarios de prueba ​

EmailPasswordRolAlcance
backoffice@cislatam.testBackoffice123!BackofficeSolo GT-CAP-001
supervisor@cislatam.testSuper123!SupervisorGT-CAP-001 + GT-QUE-002
admin@cislatam.testAdmin123!AdminGuatemala, todos los PDVs

1. Base en verde antes de tocar nada ​

#PasoResultado esperado
1.1Correr docker compose exec backend php artisan test (o el filtro --filter=TransactionDocumentApiTest)Los 12 tests de TransactionDocumentApiTest pasan, y la suite completa de backend (287 tests) también
1.2Correr docker compose exec frontend npm run testLos 51 tests de frontend pasan (incluye PagoView.spec.ts, que renderiza DocumentacionPago)
1.3Correr docker compose exec frontend npm run buildCompila sin errores de TypeScript (vue-tsc -b)

2. El stepper visual — no bloqueante ​

#PasoResultado esperado
2.1Como Backoffice, buscar la PAID de GT-CAP-001 (tu PDV, la de la consulta de «Antes de empezar»)Se ve el formulario "Datos del pago" y, debajo, "Documentación del pago" como una secuencia de círculos numerados 1, 2, 3... conectados por una línea vertical neutra — no una lista plana de casilleros
2.2Mirar los círculos de un documento ya subido vs. uno pendiente y obligatorio vs. la selfie sin subirSubido: círculo verde con tilde. Pendiente y obligatorio: círculo con borde de alerta y el número. Selfie sin subir: círculo con borde neutro y el número — nunca de alerta
2.3Subir los documentos fuera de orden (ej. el 5° antes que el 1°)Sube sin problema — ningún paso bloquea a otro
2.4Con documentos faltantes, mirar si hay algún botón "Siguiente" o similar deshabilitadoNo existe tal botón — cada casillero tiene su propio Subir/Reemplazar, independiente de los demás
2.5Con documentos faltantes, leer el texto debajo del stepper"El pago ya quedó registrado. Podés completar los soportes que falten desde acá cuando los tengas — no hace falta rehacer nada."
2.6Subir todos los obligatorios (4 en efectivo)El badge pasa de Faltan N a Completa

3. Subida y preview de los 9 tipos ​

#PasoResultado esperado
3.1Subir un PDF (ej. Carta de Soterex)Se guarda, aparece el nombre del archivo debajo del tipo, círculo pasa a verde con tilde
3.2Click en el nombre del archivo PDF subidoAbre un modal de preview con un <iframe> — confirmar en DevTools o Network que el src es blob:..., nunca una URL directa al archivo
3.3Subir una imagen (JPG o PNG, ej. Identificación anverso)Igual que 3.1
3.4Click en el nombre de la imagen subidaPreview en <img>, también con src blob:...
3.5Cerrar el preview (botón × o click afuera)El modal se cierra y el blob: URL queda revocado (un fetch posterior a esa URL falla) — no queda memoria colgada
3.6Subir la selfieSe guarda igual que cualquier otro tipo, pero nunca cuenta para Faltan N ni para Completa — subida o no, el badge no cambia por ella
3.7Cambiar "Medio de pago" a Transferencia bancaria y click en "Guardar datos" Ya no se puede hacer (G3, 2026-10-05): la opción Transferencia no existe en la pantalla y el backend responde 422 («El medio de pago solo puede ser efectivo.»). Antes de G3 ya tampoco aplicaba a una PAID: desde A3 su medio de pago es inmutable. Para ver los 4 casilleros, abrir una PAID que ya esté por transferencia (ver «Fixture de una PAID por transferencia», debajo de esta tabla)En la ficha de esa PAID aparecen los 4 casilleros (Formulario de enrolamiento, Cartola bancaria, Solicitud de pago por transferencia, Confirmación de acreditación) como pasos 6 a 9, con el badge en Faltan 5 (la papeleta firmada, que el seeder de demo no sube, más los cuatro de transferencia), y el medio de pago en solo lectura como Transferencia bancaria con su cuenta. El badge se recalcula al toque (ver bug fijado en §5.1 — antes quedaba con el valor viejo hasta la próxima subida) — sigue valiendo para el badge al subir, no al cambiar el medio
3.8Subir los 4 tipos de transferencia (solo sobre el fixture de 3.7)Igual que 3.1/3.3 — PDF o imagen, cualquiera de los dos formatos anda
3.9Con los 8 obligatorios + selfie subidos (solo sobre el fixture de 3.7)Badge Completa
3.10Reemplazar un documento ya subido (botón Reemplazar del mismo tipo), como Supervisor o Admin (sobre una pagada, el Cajero que la pagó no tiene ese botón: G5)El nuevo archivo pasa a ser el vigente en pantalla; el anterior no se borra — sigue en la base y en el almacenamiento (no hay endpoint de baja, R8)
3.11Subir un archivo inválido (ej. un ejecutable renombrado a .pdf, o cualquier archivo que no sea PDF/JPG/PNG real)Notificación roja: "El archivo no es válido: tiene que ser PDF, JPG o PNG, de hasta 20 MB." — no el error crudo del backend. El documento previamente subido en ese casillero (si había) sigue intacto
3.12Como un usuario sin permiso de escritura sobre transacciones, o (sobre una pagada) como un Cajero que no la pagó, mirar la secciónModo consulta: se ven los documentos y se puede abrir el preview, pero no aparece ningún botón Subir/Reemplazar. El Supervisor no está acá: tiene escritura y reemplaza (G5)

Fixture de una PAID por transferencia (casos 3.7 a 3.9; solo en la base local de dev, nunca en Staging). El seeder de demo ya no siembra pagos por transferencia, así que para probar la historia hay que armar uno a mano. Esto escribe una columna que la app protege como inmutable, y por eso es solo para pruebas locales:

bash
docker compose exec postgres psql -U postgres -d soterex -c \
  "UPDATE transactions SET delivery_type = 'TRANSFERENCIA', bank_account = '0000-000000-0'
   WHERE id = (SELECT t.id FROM transactions t JOIN stations s ON s.id = t.station_id
               WHERE t.status = 'PAID' AND t.delivery_type = 'EFECTIVO' AND s.internal_code = 'GT-CAP-001'
               ORDER BY t.mtcn LIMIT 1)
   RETURNING mtcn;"

La subconsulta elige una PAID de GT-CAP-001 con datos del pago (una de las primeras de la demo) a propósito: es el PDV de Backoffice, así que se puede correr el caso como Backoffice. Elegir «la primera PAID por MTCN» a secas da la PAID sin PDV del seeder, que Backoffice no alcanza (los documentos le dan 404 y la ficha no trae los datos del pago): solo el Admin la vería.

El RETURNING imprime el MTCN de la PAID que quedó por transferencia (es el que hay que buscar en Pago): si no imprime ninguna fila, el UPDATE no tocó nada y no hay fixture (por ejemplo, la base no tiene datos de demo: php artisan demo:reseed). El MTCN no es fijo: depende de lo que haya sembrado el seeder de demo, por eso se elige con la consulta y no a mano.

Para dejarla como estaba: un UPDATE con delivery_type = 'EFECTIVO', bank_account = NULL sobre ese MTCN. Una PAID de demo en efectivo muestra Faltan 1 (le falta la papeleta firmada: el seeder sube solo la Carta y la Identificación anverso y reverso); convertida a transferencia pasa a Faltan 5 (la papeleta más los cuatro de transferencia).

4. Auditoría ​

#PasoResultado esperado
4.1Después de las subidas de la sección 3, revisar Auditoría (o la tabla audit_logs)Una entrada TRANSACTION_DOCUMENT_UPLOADED por cada subida de un tipo que faltaba, y una TRANSACTION_DOCUMENT_REPLACED por cada reemplazo (un reemplazo no deja además una de subida). Ninguna trae el nombre del archivo (G5)
4.2Después de los previews de 3.2/3.4Una entrada TRANSACTION_DOCUMENT_VIEWED por cada documento abierto — la lectura queda auditada, no solo la subida

5. Bugs encontrados en este QA y su estado ​

Los primeros tres se encontraron probando este mismo cambio y se arreglaron en este PR (están dentro de DocumentacionPago.vue, el archivo que este plan tenía que tocar). El cuarto es preexistente, de otro componente, y queda documentado sin arreglar — ver la nota al final.

Los casos se encontraron en 2026-09, sobre la base que sembraba la vieja TransactionSeeder (con dos PAID fijas, MTCN 0000000001 en GT-CAP-001 y 0000000002 en GT-QUE-002). Ese seeder ya no existe: para reproducirlos hoy se usa una PAID de GT-CAP-001 y otra de GT-QUE-002 de la demo (la consulta de «Antes de empezar»), sin MTCN fijos.

#BugCómo se veíaFix
5.1El badge Faltan N no se recalculaba al cambiar el medio de pago en la misma sesiónDespués de guardar "Transferencia bancaria", la lista de casilleros pasaba a 9 tipos pero el badge seguía mostrando el conteo de efectivo (4) hasta la próxima subidawatch sobre deliveryType que vuelve a pedir el estado al backend
5.2Al buscar otra transacción sin recargar la pantalla, DocumentacionPago no se remontaba (mismo v-if="PAID") y quedaban los documentos/badge de la transacción anteriorBuscar una PAID completa de GT-CAP-001 y después otra sin documentos mostraba "Completa" con los archivos de la primerawatch sobre transactionId (agrupado con 5.1) que vuelve a pedir el estado y cierra cualquier preview abierto
5.3Si el GET de documentos fallaba (ej. 404 por PDV fuera de alcance — ver 5.4), el catch dejaba faltan/completa en su valor inicial ([]/false) y la pantalla mostraba Faltan 0 — parecía decir "no falta nada"Buscar, como Backoffice de GT-CAP-001, una PAID de GT-QUE-002 (ver 5.4)Estado de error explícito: en vez del stepper y el badge, un texto "No se pudo cargar la documentación de esta transacción." (Nota 2026-10-06, G2.3: el 404 por alcance de PDV ya no muestra este texto rojo: muestra en gris el aviso de que se pagó en otro punto de venta y no ofrece la papeleta. El texto rojo queda para las demás fallas: red, 5xx y 403. Ver plan de pruebas de G2.)
5.4(Preexistente, disparador de 5.3, comportamiento correcto de backend) La búsqueda de Pago no acota por PDV, pero el endpoint de documentos sí (§1.6 del Análisis Funcional) — una transacción PAID de otro PDV aparece en el resultado de búsqueda pero sus documentos dan 404Como Backoffice (GT-CAP-001), buscar una PAID del PDV GT-QUE-002No es un bug de este PR — es la regla intencional de §1.6. Lo que sí era un bug era cómo el frontend mostraba ese 404 (ver 5.3, ya arreglado). (Nota 2026-10-06, G2.1/G2.3: si quien busca es quien PAGÓ esa transacción, ya no recibe el 404 y ve sus soportes; el resto sigue como está y la pantalla le explica que se pagó en otro PDV.)

Limitación conocida — no arreglada en este PR ​

Al volver a buscar una transacción cuyo delivery_type ya estaba guardado (ej. TRANSFERENCIA), el formulario "Datos del pago" no lo recupera — el combo "Medio de pago" aparece en blanco y el stepper vuelve a mostrar solo los 4 tipos de efectivo, escondiendo los 4 de transferencia que sí hacen falta (aunque el badge Faltan N, que sale de otro endpoint, siga siendo correcto si no se cambia nada). La causa: PagoSearchResource excluye a propósito los campos de "Datos del pago" (Backoffice tampoco tiene permiso de lectura general de transacciones para pedirlos por otra vía). Arreglarlo de raíz implica tocar el backend (exponer esos campos) o el modelo de permisos — explícitamente fuera del alcance de este plan ("cambio de UI puro", "no tocar el backend"). Queda para un plan aparte.

6. Qué NO es parte de este cambio (no reportar como bug) ​

  • El wizard de bloqueo por documentos no existe a propósito — es la regla R3/§1.4, no un faltante.
  • El borrado de documentos no existe a propósito (R8) — reemplazar es la única forma de corregir un escaneo mal subido.
  • La limitación de §5 (recuperar delivery_type al re-buscar) es conocida, ver arriba.

Cómo reportarme el feedback ​

Para cada punto que falle, con el número de la tabla alcanza (ej. "3.11 no mostró el mensaje traducido"). Si es algo visual, una captura ayuda pero no es obligatoria.

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