# Prototipo de ejecución — FEAT-009 Mensaje de éxito con descargas de recibo y planilla de inscripción

- **Rama:** p-feature/exito-pago-recibo-planilla-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/009-exito-pago-recibo-planilla-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-29
- **Estado:** consolidado (smoke manual pendiente)

## Resumen

Se implementó el bloque de éxito del Paso 4 de nuevo ingreso con las descargas del recibo existente y de una planilla de inscripción nueva en PDF. La planilla se genera solo para intenciones propias en estado aprobado (3) o verificado (8), con datos guardados de `ni_inscripciones` y datos derivados de la oferta académica. Se agregó un builder genérico HTML→PDF reutilizable y sus pruebas unitarias y de integración.

## Tareas realizadas

- [x] Fase A — `PdfOptions`, `PdfGenerationException` y `HtmlPdfBuilder`; registro de `Services::htmlPdfBuilder()` y pruebas unitarias de papel, orientación, opciones, acentos y errores.
- [x] Fase B — `NuevoIngresoPlanillaException`, `NuevoIngresoPlanillaService`, vista `paso3/planilla.php`, `Paso3::planilla()`, ruta GET con `nuevoIngresoAuth:4`, `Services::nuevoIngresoPlanilla()` y pruebas unitarias del servicio e integración del controlador.
- [x] Fase C — Bloque de éxito en `paso3/estado.php` con mensaje, monto, referencia, botón de recibo y botón de planilla; pruebas de la vista actualizadas.
- [x] Verificación de `php -l`, pruebas del área y `graphify update .`.
- [ ] Smoke test manual completo de la planilla y del recibo con una sesión real y un pago aprobado — Motivo: el entorno de ejecución no dispone de una base de sede ni de una sesión de nuevo ingreso real. Se ejecutó un smoke automatizado de la vista con Dompdf real, pero no el recorrido HTTP completo con sesión.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `HtmlPdfBuilder::generar()` devuelve un binario que comienza con `%PDF-` y no lanza errores con acentos ni con campos vacíos | `HtmlPdfBuilderTest::testGeneraUnPdfValidoConAcentosYCamposVacios` | ok |
| `HtmlPdfBuilder::generar()` respeta `PdfOptions` con papel Letter y orientación vertical por defecto | `HtmlPdfBuilderTest::testUsaCartaVerticalPorDefecto` | ok |
| `HtmlPdfBuilder::generar()` respeta un papel y una orientación distintos | `HtmlPdfBuilderTest::testRespetaPapelYOrientacionDistintos` | ok |
| `HtmlPdfBuilder` no referencia clases de nuevo ingreso ni consulta base de datos, sesión o rutas | `HtmlPdfBuilderTest::testNoConoceNuevoIngresoNiBaseDeDatos` | ok |
| `PdfOptions` valida papel y orientación; orientación inválida lanza `InvalidArgumentException` | `PdfOptionsTest` | ok |
| `PdfGenerationException` se lanza si Dompdf no está disponible o falla el render | `HtmlPdfBuilderTest::testLanzaExcepcionSiDompdfNoEstaDisponible` y `testLanzaExcepcionSiFallaElRender` | ok |
| La vista `planilla.php` muestra apellidos, nombres, identificación, correo, teléfono, país, provincia, ciudad, dirección, carrera, sede, turno y modalidad | `NuevoIngresoPlanillaServiceTest::testEstadoAprobadoGeneraLaPlanillaConDatosGuardados` | ok |
| La identificación se presenta con prefijo `V-` o `E-` según `identificacion_tipo` | `testEstadoAprobadoGeneraLaPlanillaConDatosGuardados` y `testIdentificacionTipoEUsaPrefijoE` | ok |
| El turno se resuelve en la base de la sede por `turno_id` y se muestra con `CoTurno` | `testEstadoAprobadoGeneraLaPlanillaConDatosGuardados` | ok |
| La modalidad se muestra como "Presencial" o "Virtual" | `testModalidadVirtualYDesconocida` | ok |
| La planilla no muestra periodo, número de postulación, monto, referencia, estado del pago, plan, recaudos, representante, salud, información académica ni información laboral | Revisión de `paso3/planilla.php` y de los datos construidos por el servicio | ok |
| Los campos derivados no resueltos se muestran como "No disponible" y registran advertencia; la planilla se genera igualmente | `testTurnoAusenteSeMuestraComoNoDisponible`, `testPaisYProvinciaAusentesSeMuestranComoNoDisponible`, `testCarreraYSedeNoResueltasSeMuestranComoNoDisponible` | ok |
| El servicio solo acepta intenciones propias en estado 3 u 8 | `testRechazaEstadoNoAprobado`, `testRechazaIntencionAjena`, `testEstadoVerificadoTambienGeneraLaPlanilla` | ok |
| El servicio usa `HtmlPdfBuilder` con `new PdfOptions('letter', 'portrait', true, true)` | `testEstadoAprobadoGeneraLaPlanillaConDatosGuardados` | ok |
| `Paso3::planilla` solo acepta GET y responde 405 con página de mensaje | `Paso4PlanillaTest::testPlanillaRechazaMetodosDistintosDeGet` | ok |
| `Paso3::planilla` valida sesión, paso, id positivo, propiedad y estado | `Paso4PlanillaTest` (422 por id, estado y ajena; redirección sin sesión) | ok |
| La ruta `GET /inscripciones/nuevo-ingreso/paso-4/planilla/(:num)` existe con `nuevoIngresoAuth:4` | `Paso4PlanillaTest::testRutaRegistradaConFiltroDePaso4` | ok |
| El controlador responde con `application/pdf`, `Content-Disposition: attachment; filename="PlanillaNI{niId}.pdf"`, `Cache-Control: private, no-store` y el cuerpo binario | `testPlanillaAprobadaDevuelvePdfConCabecerasDeDescarga` | ok |
| La planilla se genera sin escribir en base de datos y es idempotente | `testDescargaRepetidaNoEscribeEnBaseDeDatos` | ok |
| El bloque "Pago aprobado" se reemplaza por un bloque de éxito con mensaje, monto, referencia y ambos botones | `Paso4NuevoIngresoTest::testIndexEstadosAprobadosYPendienteNoOfrecenIniciarNiCancelar` | ok |
| Ambos botones aparecen solo en estado aprobado y se abren en pestaña nueva con `rel="noopener"` | Prueba de integración de la vista (estados 3/8 y 7) | ok |
| El botón "Descargar recibo" conserva la ruta y el comportamiento existentes | `Paso4ReciboTest` (7/7) y `ReportesReciboTest` (1/1) | ok |
| El bloque de éxito se muestra cada vez que se abre el Paso 4 en estado aprobado | Renderizado del bloque desde `estado.php` para los estados 3 y 8 | ok |
| No se modifican `Imprimir::planilla()`, `app/Views/imprimir/planilla.php`, `Reportes::Recibo`, `ReciboPdfBuilder` ni el recibo de nuevo ingreso | Revisión de archivos no modificados y pruebas de regresión del recibo | ok |
| Pruebas unitarias del servicio (3, 8, 7, ajena, postulación inexistente, turno ausente, país/provincia ausentes, modalidad) | `NuevoIngresoPlanillaServiceTest` (11/11) | ok |
| Pruebas unitarias del builder y de `PdfOptions` | `HtmlPdfBuilderTest` (6/6), `PdfOptionsTest` (5/5) | ok |
| Pruebas de integración del controlador (200, 405, 422 por id, 422 por estado 7, 422 por ajena, redirección sin sesión) | `Paso4PlanillaTest` (8/8) | ok |
| `Paso4NuevoIngresoTest`, `Paso4ReciboTest`, `Paso4PagoTest`, `ZelleNuevoIngresoTest` y el área de pagos siguen pasando | Ejecución por archivo | parcial: `Paso4NuevoIngresoTest` conserva 1 fallo previo (línea 358) y `NuevoIngresoPagoServiceTest` conserva 1 fallo previo (línea 233), ambos presentes antes de iniciar |
| Smoke test manual de la planilla y del recibo con sesión válida y pago aprobado | Smoke automatizado de la vista con Dompdf real (PDF `%PDF-` > 2 KB) | pendiente: no hay sesión real ni base de sede en el entorno |
| `php -l` sin errores en archivos nuevos o modificados | `php -l` sobre los 10 archivos PHP tocados | ok |
| `graphify update .` ejecutado después de los cambios | `graphify update .` | ok |
| No se agregaron dependencias, migraciones, seeds, CSRF ni cambios en `vendor/`, `system/` o `public/vendor/` | Revisión de `git status` y del diff | ok |

## Flujos cubiertos

- **Flujo normal:** el Paso 4 en estado aprobado muestra el bloque de éxito, el monto y la referencia, y los botones de recibo y planilla. La planilla responde 200 con PDF y cabeceras de descarga. Verificado con pruebas de integración y unitarias.
- **Flujos alternativos:** estado verificado (8), descarga repetida sin escritura, turno ausente, país/provincia ausentes, relación carrera/sede no resuelta y modalidad virtual o desconocida. Todos cubiertos por pruebas.
- **Control de errores:** 405 por método distinto de GET; 422 por id inválido, intención ajena, estado distinto de 3/8 y postulación inexistente; redirección sin sesión; 500 ante fallo de Dompdf. Los errores de dominio muestran un mensaje con enlace al Paso 4 y no revelan si la intención existe.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Pdf/PdfOptions.php` | Configuración reutilizable de papel, orientación y opciones de Dompdf. |
| `app/Libraries/Pdf/PdfGenerationException.php` | Errores genéricos de la conversión HTML→PDF. |
| `app/Libraries/Pdf/HtmlPdfBuilder.php` | Builder genérico HTML→PDF con Dompdf. |
| `app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaException.php` | Errores de dominio de la planilla. |
| `app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaService.php` | Composición, validación y datos de la planilla de nuevo ingreso. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` | Plantilla HTML de la planilla adaptada del diseño regular. |
| `tests/app/Libraries/Pdf/PdfOptionsTest.php` | Pruebas de `PdfOptions`. |
| `tests/app/Libraries/Pdf/HtmlPdfBuilderTest.php` | Pruebas del builder genérico con Dompdf real. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaServiceTest.php` | Pruebas del servicio con SQLite y builder falso. |
| `tests/app/Integration/Paso4PlanillaTest.php` | Pruebas de la ruta, el controlador, las cabeceras y los errores. |
| `docs/features/009-exito-pago-recibo-planilla-nuevo-ingreso/prototipo.md` | Este documento. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Config/Services.php` | Registro de `htmlPdfBuilder()` y `nuevoIngresoPlanilla()`, con sus instancias estáticas. |
| `app/Config/Routes.php` | Ruta `GET paso-4/planilla/(:num)` con `nuevoIngresoAuth:4`. |
| `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Método `planilla()`, import de la excepción y URL `planilla` en `urls()`. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Bloque de éxito con mensaje y botones de recibo y planilla. |
| `tests/app/Integration/Paso4NuevoIngresoTest.php` | Verificación del botón y la URL de la planilla, y de su ausencia en estado 7. |
| `docs/features/009-exito-pago-recibo-planilla-nuevo-ingreso/plan.md` | Estado actualizado a `en curso`. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** `GET /inscripciones/nuevo-ingreso/paso-4/planilla/(:num)` → `Paso3::planilla/$1`, filtro `nuevoIngresoAuth:4`. No se modificó la ruta del recibo.
- **Permisos y validaciones:** sesión `nuevo_ingreso` con `paso_actual >= 4` (filtro y `sesionValida()`), método GET, id entero positivo, resolución del contexto, propiedad de la intención vía `obtenerIntencion($id, $niId)` y estado 3 u 8 vía `estaAprobada()`. La sede y la identidad no se leen de la petición.
- **Migraciones/seeds:** no aplica; no se agregaron cambios de esquema ni datos.
- **Compatibilidad:** no cambia el contrato del recibo ni el de los reportes regulares. La nueva ruta es aditiva. La planilla responde `attachment`; el recibo conserva `inline`.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php -l` sobre los archivos PHP nuevos y modificados | Sin errores de sintaxis. |
| `php vendor\phpunit\phpunit\phpunit --no-coverage tests\app\Libraries\Pdf` | 11/11 pruebas, 23 aserciones (incluye `PdfOptionsTest` y `HtmlPdfBuilderTest`). |
| `... tests\app\Libraries\Inscripciones\NuevoIngreso\Planilla\NuevoIngresoPlanillaServiceTest.php` | 11/11 pruebas, 42 aserciones. |
| `... tests\app\Integration\Paso4PlanillaTest.php` | 8/8 pruebas, 19 aserciones. |
| `... tests\app\Libraries` | 143 pruebas, 1 fallo previo en `NuevoIngresoPagoServiceTest:233`. |
| `... tests\app\Integration` | 146 pruebas, 1 fallo previo en `Paso4NuevoIngresoTest:358`. |
| `graphify update .` | Grafo actualizado; advertencias por `tree_sitter_sql` y archivos de vistas con sintaxis no soportada. |

## Verificación

- **Línea base (antes):** `Paso4ReciboTest` 7/7; `Paso4PagoTest` 19/19; `ZelleNuevoIngresoTest` 9/9; `NuevoIngresoReciboServiceTest` 10/10; `ReportesReciboTest` 1/1; `Paso4NuevoIngresoTest` 27 pruebas con 1 fallo en la línea 354 (`testIniciarConIntencionCreadaIgnoraPlanDelFormulario`); `NuevoIngresoPagoServiceTest` 33 pruebas con 1 fallo en la línea 233 (`testPlanSeleccionadoYReutilizacionSinDuplicar`). Ambos fallos son previos a esta feature.
- **Prueba manual (flujo normal):** smoke automatizado que renderizó la vista real `paso3/planilla.php` con datos de ejemplo y la convirtió con el Dompdf de `public/dompdf`; el binario inició con `%PDF-` y superó 2 KB. No se ejecutó el recorrido HTTP con sesión y pago reales.
- **Flujos alternativos y errores:** cubiertos por las pruebas unitarias y de integración descritas; los estados 3 y 8 generan, el estado 7 y las intenciones ajenas responden 422, y los métodos distintos de GET responden 405.
- **Pruebas automatizadas:** `PdfOptionsTest` 5/5, `HtmlPdfBuilderTest` 6/6, `NuevoIngresoPlanillaServiceTest` 11/11, `Paso4PlanillaTest` 8/8, `Paso4ReciboTest` 7/7, `Paso4PagoTest` 19/19, `ZelleNuevoIngresoTest` 9/9, `NuevoIngresoReciboServiceTest` 10/10, `ReportesReciboTest` 1/1.
- **Criterios del plan:** todos los criterios funcionales y de pruebas quedaron cubiertos; queda pendiente el smoke manual con una sesión real y un pago aprobado, y se documentan los 2 fallos previos ajenos a la feature.

## Desviaciones del plan

- El servicio deja propagar `PdfGenerationException` en lugar de envolverla en `NuevoIngresoPlanillaException`, para que el controlador responda 500 (fallo del generador) y no 422 (error de dominio), tal como indica la tabla de errores del plan. La fábrica `porErrorGeneracion()` se usa para errores al renderizar la vista.
- El smoke manual con sesión real quedó pendiente porque el entorno no dispone de la base de la sede ni de una sesión de nuevo ingreso.

## Riesgos y pendientes

- **Dompdf no declarado en Composer:** `public/dompdf/` está ignorado por git. Si el despliegue no lo conserva, la planilla responde 500. El nuevo builder centraliza el acoplamiento, pero la dependencia sigue sin formalizarse.
- **Smoke pendiente:** falta validar el recorrido completo con una sesión de nuevo ingreso y una intención aprobada en un entorno con la base de la sede.
- **Fallos previos:** `Paso4NuevoIngresoTest::testIniciarConIntencionCreadaIgnoraPlanDelFormulario` y `NuevoIngresoPagoServiceTest::testPlanSeleccionadoYReutilizacionSinDuplicar` fallan antes y después de esta feature; no se corrigieron porque el plan no contempla un bugfix.
- **Logo remoto:** la plantilla usa `base_url()` y `remoteEnabled`. Si el servidor no resuelve la URL, el logo no se incrusta, pero el PDF se genera.
- **Auto-routing:** `Paso3::planilla` es público y podría invocarse por una URI no prevista; se mitiga con las validaciones internas de método, sesión, paso, id, propiedad y estado.
- **Refactor pendiente:** `Imprimir::planilla()` y `Servicio` siguen usando su inclusión manual de Dompdf; no se migraron al builder genérico.

## Consolidación

- **Estado:** consolidado
- **Fecha:** 2026-10-29
- **Rama destino:** `feature/desacoplar-contructor-pagos`
- **Estrategia:** `cherry-pick` de 4 commits
- **Commits:** `4514c5e`, `e95d4c5`, `da84c78`, `64d72ad`
- **Rama prototipo eliminada:** sí
- **Corrección:** la consolidación previa en `feature/inscripciones-nuevo-ingreso` era local y no se publicó; esa rama se devolvió a `origin` (`55e93bb`).
- **Pendiente aceptado:** smoke test manual con sesión real y pago aprobado; no ejecutado por falta de base de sede y sesión de nuevo ingreso en el entorno.
