Plan — stepper visual de documentos en Pago + validación de subida/preview

Fecha: 2026-09-11 Alcance: cambio de UI (no de negocio) sobre DocumentacionPago.vue, más validación de que subida y preview funcionan para los 9 tipos de documento.

Contexto

DocumentacionPago.vue ya existe (E5a/E5b, mergeado a main en el PR #18) y se usa en dos lugares: la ficha de la transacción y la pantalla Pago, que es la que opera el ejecutivo de cuentas (rol Backoffice del sistema — no hay un rol "ejecutivo de cuentas" separado, es el nombre de negocio del mismo rol). Hoy los 9 tipos de documento se muestran como una lista de casilleros (frontend/src/components/DocumentacionPago.vue:164-209), no como un wizard.

Restricción de negocio — no se toca, es la parte más importante de este plan

El Análisis Funcional dice, dos veces, que esto es deliberado:

"No hay wizard de pasos obligatorios [...] Se construyó un formulario y una lista de casilleros que se pueden completar en cualquier orden y en cualquier momento, incluso días después" — 00-resumen.md §0.3

"El pago no se bloquea por documentos faltantes. Es la decisión de diseño más importante del paquete [...] no es una concesión de comodidad" — 01-flujo-del-pago.md §1.4

La razón: cuando el operador llega a subir los escaneos, la plata ya salió del cajón. Frenar el registro por falta de un documento no evita el problema, lo convierte en un descuadre de caja.

Confirmado con Carlos (2026-09-11): el pedido es solo visual. Cambiar la lista de casilleros por un stepper (1, 2, 3...) más guiado para el operador, pero:

• Sigue siendo 100% salteable — cualquier paso se puede subir en cualquier orden.
• El pago nunca depende de completar los pasos — ya está pagado cuando se llega acá.
• Se puede completar días después, igual que hoy.
• No hay "paso bloqueado" ni "Siguiente" deshabilitado por falta de datos.

Qué cambia

1. DocumentacionPago.vue — reemplazar el <ul> de casilleros por una presentación de pasos numerados (visual: número/check por tipo, con el estado tilde/pendiente/opcional que ya existe hoy). Mantener intacto:
   • El filtro por deliveryType (tiposVisibles, líneas 41-49) — 4 tipos en efectivo, 9 en transferencia.
   • El tratamiento especial de SELFIE (opcional, ícono neutro, nunca cuenta para completitud).
   • El badge Completa / Faltan N.
   • El texto de descargo: "El pago ya quedó registrado. Podés completar los soportes que falten..." — sigue siendo necesario, quizás más todavía con un stepper (para que no se lea como "tenés que terminar los pasos para que el pago valga").
   • La lógica de preview sin cambios (abrirPreview/cerrarPreview, líneas 108-130) — blob + Bearer, nunca <img src> directo, revoca el object URL al cerrar. No tocar esto, es manejo de PII.
   • canUpload para modo consulta (Supervisor viendo una transacción de otro PDV, por ejemplo).
2. 02-datos-y-documentos.md §2.7` ("Cómo se ve en pantalla") — actualizar la descripción para reflejar el stepper nuevo, pero reafirmando explícitamente que sigue sin ser bloqueante — para que nadie lea "ahora es un wizard" y asuma que también se volvió obligatorio. Sugerencia de texto: "se muestra como una secuencia de pasos numerados (visual), no como una lista plana — pero sigue sin ser un wizard bloqueante: cualquier paso se completa en cualquier orden, y el pago nunca depende de esto".
3. No tocar el backend. Es un cambio de presentación puro — el contrato de la API (TransactionDocumentController, permisos, auditoría, documentacion_completa/faltan) no cambia.

Validación — subida y preview de cada documento

No hay test de frontend para este componente (frontend/src no tiene ningún *document*.spec.*). Sí existe backend/tests/Feature/TransactionDocumentApiTest.php.

1. Correr la suite de backend existente y confirmar que sigue en verde (no debería romperse, es un cambio de frontend, pero confirma la base antes de tocar nada).
2. Levantar el stack local (./start-dev.sh — ver doc/environments/dev.md) y ejercitar a mano, contra una transacción PAID, los 9 tipos:
   • Al menos un PDF y al menos una imagen (JPG o PNG) — confirmar que el PDF abre en <iframe> y la imagen en <img> dentro del modal de preview.
   • La SELFIE — confirmar que nunca aparece como obligatoria ni afecta el badge de completitud.
   • Los 4 tipos de TRANSFERENCIA — confirmar que no aparecen con EFECTIVO y sí con TRANSFERENCIA, y que cambiar el medio de pago recalcula Faltan N en el momento.
   • Reemplazar un documento ya subido — confirmar que el anterior no se borra (no hay endpoint de baja) y que el nuevo aparece como el vigente en pantalla.
   • Un archivo inválido (ej. un .exe renombrado a .pdf) — confirmar el mensaje "El archivo no es válido..." en vez del error crudo del backend.
   • Cerrar el preview y confirmar (DevTools → Memory o simplemente inspeccionar) que no queda un object URL colgado — es lo que revoca cerrarPreview().
3. Si aparece algo roto: arreglarlo es parte de este plan, no un hallazgo aparte para después.
4. Agregar doc/qa/2026-09-11-e5-pago-documentos-plan-de-pruebas.md con los casos de arriba, en el mismo formato que ya usan M1–M4 (doc/qa/2026-07-25-m1-transacciones-plan-de-pruebas.md como referencia de formato) — el paquete de Pago con documentos es el único de los ya mergeados que no tiene uno.

Qué NO hacer

• No introducir bloqueo del pago por documentos ni de un paso por otro. Si en el camino parece que "hace falta" para que el stepper tenga sentido, es una señal de que se está reabriendo R3 sin querer — parar y volver a preguntar, no decidirlo solo.
• No tocar el backend, los permisos, ni la lógica de auditoría.
• No agregar borrado de documentos.
• No mergear a main sin OK explícito — abrir el PR y avisar en el chat alcanza.

Entregable

Un PR contra main, con:

• El componente con el stepper visual, sin romper canUpload/permisos/preview.
• La doc actualizada (02-datos-y-documentos.md §2.7).
• El plan de QA nuevo en doc/qa/.
• Confirmación en la descripción del PR de que se probaron a mano los 9 tipos (o los casos que se hayan podido probar en el entorno local) y el resultado de la suite de backend.