# Prototipo de ejecución — FEAT-007 Recibo PDF de nuevo ingreso

- **Rama:** p-feature/recibo-pdf-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/007-recibo-pdf-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado
- **Consolidado en:** feature/desacoplar-contructor-pagos (2026-10-28, merge --no-ff)

## Resumen

Se implementó el recibo PDF de nuevo ingreso para intenciones propias en estado 3 u 8, accesible desde el bloque de pago aprobado del Paso 4. La generación se extrajo a `ReciboPdfBuilder`, compartido con el recibo regular, y se orquestó con `NuevoIngresoReciboService`. El flujo es de solo lectura, valida sesión, paso, propiedad y estado, y muestra el desglose de Zelle con los valores persistidos.

## Tareas realizadas

- [x] Crear `ReciboPdfBuilder` con el renderizado del recibo regular y salida binaria `Output('S')`.
- [x] Refactorizar `Reportes::Recibo` para usar el builder compartido, conservando filas, validaciones y nombre `Recibo{id}.pdf`.
- [x] Crear `NuevoIngresoReciboException` con fábricas de dominio.
- [x] Crear `NuevoIngresoReciboService` con validación de propiedad/estado y armado de filas NI y Zelle.
- [x] Registrar `Services::reciboPdfBuilder()` y `Services::nuevoIngresoRecibo()` con instancias reiniciables en pruebas.
- [x] Agregar `Paso3::recibo()`, `urls()['recibo']`, la ruta GET con `nuevoIngresoAuth:4` y el botón del estado aprobado.
- [x] Cubrir builder, servicio, controlador y regresión del recibo regular con pruebas automatizadas.
- [x] Ejecutar `php -l`, pruebas del área y `graphify update .`.
- [ ] Smoke test manual en un entorno con sesión válida — Motivo: no hay una sesión real de estudiante/aspirante ni base de despliegue disponible en este checkout. Se sustituyó por pruebas de integración y de regresión.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| Builder devuelve binario `%PDF-` con acentos y filas vacías | `ReciboPdfBuilderTest` (3 casos) | ok |
| `Reportes::Recibo` usa el builder y conserva filas, nombre y respuesta | `ReportesReciboTest` + revisión del diff | ok |
| `Reportes::Recibo` sigue rechazando intenciones NI | Revisión de la condición `ni_inscripcion_id !== null` conservada | ok |
| El servicio solo acepta intenciones propias en estado 3 u 8 | `NuevoIngresoReciboServiceTest` (estado 7, ajena, estados 3 y 8) | ok |
| El recibo no muestra el plan | Filas esperadas en pruebas; no hay consulta ni fila de plan | ok |
| Filas base: referencia, nombre, identificación, transacción, total Bs y descripción | `NuevoIngresoReciboServiceTest` y `ReportesReciboTest` | ok |
| Nombre e identificación salen de `ni_inscripciones` con prefijo V/E | Pruebas con tipo `0` (V) y tipo `1` (E) | ok |
| Pago no Zelle sin descuento, tasa ni total en divisa | `testPagoNoZelleAprobadoMuestraSoloElTotalEnBs` | ok |
| Zelle con subtotal, total Bs y total USD | `testZelleConDescuentoTasaYTotalEnDivisa` | ok |
| Descuento y tasa solo se muestran si son mayores que cero | Pruebas Zelle con y sin desglose | ok |
| Descuento persistido o derivado, sin usar descuento global | Revisión del servicio + prueba con descuento persistido | ok |
| Tasa persistida, sin usar tasa vigente | Revisión del servicio + prueba con tasa persistida | ok |
| Monto verificado con respaldo `monto_pagado` → `data_respuesta` → `monto` | Revisión del servicio + prueba histórica | ok |
| Excedente mayor que cero muestra tres filas y omite `Total $` | `testZelleConExcedenteMuestraElDesgloseSinTotalDuplicado` | ok |
| Reporte histórico sin columnas se completa con `data_respuesta` | `testZelleSinReporteUsaDataRespuestaComoRespaldo` | ok |
| `Paso3::recibo` solo acepta GET y responde 405 | `Paso4ReciboTest::testReciboRechazaMetodosDistintosDeGet` | ok |
| Valida sesión, paso, id, propiedad y estado; ajena responde 422 | `Paso4ReciboTest` (id inválido, ajena, estado 7, sin sesión) | ok |
| Ruta GET con filtro `nuevoIngresoAuth:4` | `testRutaRegistradaConFiltroDePaso4` + revisión de `Routes.php` | ok |
| Botón solo en estado aprobado y apunta a la ruta correcta | `Paso4NuevoIngresoTest` (aprobado y pendiente) | ok |
| Cabeceras `application/pdf`, `inline`, `private, no-store` | `testReciboAprobadoDevuelvePdfConCabeceras` | ok |
| Generación sin escritura e idempotente | `testDescargaRepetidaNoEscribeEnBaseDeDatos` | ok |
| Pruebas unitarias de estados, Zelle, descuento, excedente, ajena y no aprobada | `NuevoIngresoReciboServiceTest` (10 casos) | ok |
| Pruebas de integración de PDF 200, 405, 422 y redirección | `Paso4ReciboTest` (7 casos) | ok |
| Pruebas existentes de Paso 4 y pagos siguen pasando | `tests/app/Integration`, `tests/app/Libraries`, `tests/app/Database` | ok |
| Smoke test manual del recibo regular y NI | No ejecutado por falta de sesión/base real | pendiente |
| `php -l` sin errores | Ejecutado sobre los 13 archivos PHP nuevos/modificados | ok |
| `graphify update .` ejecutado | Ejecutado tras los cambios de código y pruebas | ok |
| Sin dependencias, migraciones, seeds, CSRF ni cambios en `vendor/`/`system/` | Revisión del diff y del estado de Git | ok |

## Flujos cubiertos

- **Flujo normal:** intención propia en estado 3 u 8, sesión `nuevo_ingreso` con paso 4; el controlador devuelve el PDF en línea con su nombre y cabeceras.
- **Flujos alternativos:** pago no Zelle, Zelle con descuento y tasa, Zelle con excedente, Zelle sin reporte usando `data_respuesta`, Zelle sin datos de divisa, identificación V y E, y descarga repetida.
- **Control de errores:** 405 por método distinto de GET, 422 por id inválido, intención ajena, estado no aprobado, postulación inexistente y contexto inválido, 500 por error inesperado del builder, y redirección sin sesión o con paso menor a 4.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Recibos/ReciboPdfBuilder.php` | Builder compartido del PDF extraído del recibo regular. |
| `app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboService.php` | Dominio y armado de filas del recibo NI. |
| `app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboException.php` | Errores de dominio del recibo NI. |
| `tests/app/Libraries/Recibos/ReciboPdfBuilderTest.php` | PDF válido, filas vacías y acentos. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboServiceTest.php` | Filas NI, Zelle, respaldos, propiedad, estados e idempotencia. |
| `tests/app/Integration/Paso4ReciboTest.php` | Controlador, cabeceras, 405, 422, redirección y ruta. |
| `tests/app/Integration/ReportesReciboTest.php` | Regresión del recibo regular con el builder compartido. |
| `docs/features/007-recibo-pdf-nuevo-ingreso/prototipo.md` | Este documento. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Controllers/Reportes.php` | Usa `Services::reciboPdfBuilder()` y fija `Content-Disposition` del recibo regular. |
| `app/Config/Services.php` | Registra `reciboPdfBuilder` y `nuevoIngresoRecibo` con instancias estáticas. |
| `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Agrega `recibo()`, el manejo de errores y `urls()['recibo']`. |
| `app/Config/Routes.php` | Agrega la ruta GET `paso-4/recibo/(:num)` con `nuevoIngresoAuth:4`. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Agrega `$puedeVerRecibo` y el botón "Descargar recibo" en estado aprobado. |
| `tests/app/Integration/Paso4NuevoIngresoTest.php` | Verifica el botón en estado aprobado y su ausencia en pendiente. |
| `docs/features/007-recibo-pdf-nuevo-ingreso/plan.md` | Estado actualizado a `en curso` por el smoke test pendiente. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** `GET inscripciones/nuevo-ingreso/paso-4/recibo/(:num)` → `Paso3::recibo/$1`, filtro `nuevoIngresoAuth:4`. Es de solo lectura.
- **Permisos y validaciones:** sesión `nuevo_ingreso` con `paso_actual >= 4`, id entero positivo, `ni_inscripcion_id` resuelto desde el contexto, propiedad vía `obtenerIntencion($id, $niId)` y estado 3 u 8 vía `estaAprobada()`. El método repite las validaciones para cubrir el auto-routing.
- **Migraciones/seeds:** no aplica; no se agregaron ni modificaron migraciones, seeds ni esquemas.
- **Compatibilidad:** el recibo regular conserva filas, nombre `Recibo{id}.pdf` y respuesta en línea. `Reportes::Recibo` sigue rechazando intenciones NI. El recibo NI usa `ReciboNI{id}.pdf`. Sin cambios de contrato para clientes existentes.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `vendor\bin\phpunit.bat tests/app/Integration` (línea base) | OK: 124 pruebas, 431 aserciones |
| `vendor\bin\phpunit.bat tests/app/Integration` (final) | OK: 132 pruebas, 458 aserciones |
| `vendor\bin\phpunit.bat tests/app/Libraries` | OK: 121 pruebas, 345 aserciones |
| `vendor\bin\phpunit.bat tests/app/Database` | OK: 49 pruebas, 129 aserciones |
| `php -l` sobre los archivos PHP nuevos y modificados | Sin errores de sintaxis |
| `graphify update .` | Grafo actualizado (13868 nodos, 28646 aristas) |

## Verificación

- **Línea base (antes):** `tests/app/Integration` con 124 pruebas y 431 aserciones, todas en verde.
- **Prueba manual (flujo normal):** no ejecutada en navegador por falta de sesión/base real; el flujo se verificó con `Paso4ReciboTest` y un builder falso.
- **Flujos alternativos y errores:** cubiertos por las pruebas unitarias del servicio y las pruebas de integración del controlador.
- **Pruebas automatizadas:** builder (3), servicio (10), controlador/ruta (7), regresión del recibo regular (1) y suite existente de integración, librerías y base de datos.
- **Criterios del plan:** todos los criterios automatizables quedaron en verde. El smoke test manual queda pendiente por el entorno.

## Desviaciones del plan

- Se agregó `tests/app/Integration/ReportesReciboTest.php`, no listado en "Áreas afectadas", para cubrir la regresión del recibo regular exigida por el alcance y los criterios.
- El recibo regular ahora fija explícitamente `Content-Disposition: inline; filename="Recibo{id}.pdf"` desde el controlador, equivalente al comportamiento previo de FPDF `Output('I')`.
- No se modificó ninguna migración, seed, dependencia, CSRF ni archivo fuera del alcance.

## Riesgos y pendientes

- **Pendiente:** ejecutar el smoke test manual del recibo regular y del recibo NI en un entorno con sesión y base reales antes de desplegar.
- **Reportes Zelle históricos:** los pagos anteriores a las columnas de desglose dependen de `data_respuesta`; si falta, el recibo omite las filas no resolubles.
- **Auto-routing:** `Paso3::recibo()` es público y podría invocarse por una URI no prevista; las validaciones internas y el filtro de la ruta mitigan el riesgo.
- **FPDF y `utf8_decode()`:** se conserva el comportamiento del recibo regular; una futura migración a PHP 8.2+ debe revisar la deprecación.
- **Logo por URL:** igual que el recibo regular, depende de que el servidor pueda acceder a `base_url('/assets/reportes/logo1.png')`; debe probarse en despliegue.
