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.
docker compose exec backend php artisan migrate --seed
docker compose exec backend php artisan demo:reseedPara elegir una PAID de cada PDV (la primera de cada uno):
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
| Password | Rol | Alcance | |
|---|---|---|---|
backoffice@cislatam.test | Backoffice123! | Backoffice | Solo GT-CAP-001 |
supervisor@cislatam.test | Super123! | Supervisor | GT-CAP-001 + GT-QUE-002 |
admin@cislatam.test | Admin123! | Admin | Guatemala, todos los PDVs |
1. Base en verde antes de tocar nada
| # | Paso | Resultado esperado |
|---|---|---|
| 1.1 | Correr 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.2 | Correr docker compose exec frontend npm run test | Los 51 tests de frontend pasan (incluye PagoView.spec.ts, que renderiza DocumentacionPago) |
| 1.3 | Correr docker compose exec frontend npm run build | Compila sin errores de TypeScript (vue-tsc -b) |
2. El stepper visual — no bloqueante
| # | Paso | Resultado esperado |
|---|---|---|
| 2.1 | Como 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.2 | Mirar los círculos de un documento ya subido vs. uno pendiente y obligatorio vs. la selfie sin subir | Subido: 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.3 | Subir los documentos fuera de orden (ej. el 5° antes que el 1°) | Sube sin problema — ningún paso bloquea a otro |
| 2.4 | Con documentos faltantes, mirar si hay algún botón "Siguiente" o similar deshabilitado | No existe tal botón — cada casillero tiene su propio Subir/Reemplazar, independiente de los demás |
| 2.5 | Con 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.6 | Subir todos los obligatorios (4 en efectivo) | El badge pasa de Faltan N a Completa |
3. Subida y preview de los 9 tipos
| # | Paso | Resultado esperado |
|---|---|---|
| 3.1 | Subir un PDF (ej. Carta de Soterex) | Se guarda, aparece el nombre del archivo debajo del tipo, círculo pasa a verde con tilde |
| 3.2 | Click en el nombre del archivo PDF subido | Abre un modal de preview con un <iframe> — confirmar en DevTools o Network que el src es blob:..., nunca una URL directa al archivo |
| 3.3 | Subir una imagen (JPG o PNG, ej. Identificación anverso) | Igual que 3.1 |
| 3.4 | Click en el nombre de la imagen subida | Preview en <img>, también con src blob:... |
| 3.5 | Cerrar 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.6 | Subir la selfie | Se 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.7 | 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. |
| 3.8 | Subir 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.9 | Con los 8 obligatorios + selfie subidos (solo sobre el fixture de 3.7) | Badge Completa |
| 3.10 | Reemplazar 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.11 | Subir 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.12 | Como un usuario sin permiso de escritura sobre transacciones, o (sobre una pagada) como un Cajero que no la pagó, mirar la sección | Modo 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:
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
| # | Paso | Resultado esperado |
|---|---|---|
| 4.1 | Despué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.2 | Después de los previews de 3.2/3.4 | Una 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 dosPAIDfijas, MTCN0000000001en GT-CAP-001 y0000000002en GT-QUE-002). Ese seeder ya no existe: para reproducirlos hoy se usa unaPAIDde GT-CAP-001 y otra de GT-QUE-002 de la demo (la consulta de «Antes de empezar»), sin MTCN fijos.
| # | Bug | Cómo se veía | Fix |
|---|---|---|---|
| 5.1 | El badge Faltan N no se recalculaba al cambiar el medio de pago en la misma sesión | Despué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 subida | watch sobre deliveryType que vuelve a pedir el estado al backend |
| 5.2 | Al 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 anterior | Buscar una PAID completa de GT-CAP-001 y después otra sin documentos mostraba "Completa" con los archivos de la primera | watch sobre transactionId (agrupado con 5.1) que vuelve a pedir el estado y cierra cualquier preview abierto |
| 5.3 | Si 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 404 | Como Backoffice (GT-CAP-001), buscar una PAID del PDV GT-QUE-002 | No 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_typeal 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.

