# Mensaje de éxito con descargas de recibo y planilla de inscripción

- **Código:** FEAT-009
- **Tipo:** feature
- **Estado:** en curso
- **Fecha:** 2026-10-29
- **Autor:** opencode (agente)

## Objetivo

Mostrar en el Paso 4 de nuevo ingreso un mensaje de éxito cuando el pago esté aprobado o verificado, con dos acciones de descarga: el recibo que ya existe y una nueva planilla de inscripción en PDF. La planilla debe reflejar únicamente los datos básicos realmente guardados de la postulación y de la oferta académica, sin inventar información ni exponer datos de otras postulaciones.

## Alcance

- Incluye:
  - Reemplazar el bloque actual "Pago aprobado" de `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` por un bloque de éxito con:
    - Mensaje de éxito y confirmación de que el pago fue aprobado.
    - Botón "Descargar recibo" que reutiliza la ruta y el servicio existentes de FEAT-007.
    - Botón "Descargar planilla de inscripción" que apunta a una ruta nueva.
  - Crear `NuevoIngresoPlanillaService` y su excepción de dominio.
  - Crear `HtmlPdfBuilder` y `PdfOptions` genéricos en `app/Libraries/Pdf` para exportar HTML a PDF con papel, orientación, recursos remotos y opciones de Dompdf configurables.
  - Crear `PdfGenerationException` genérica para los errores del builder HTML→PDF.
  - Crear una plantilla HTML nueva adaptada del diseño de `app/Views/inscripciones/nuevo_ingreso/pdf/planilla.php`.
  - Crear la vista `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php`.
  - Exponer `Paso3::planilla($id)` solo por GET, con sesión `nuevo_ingreso`, `paso_actual >= 4`, intención propia y estado 3 u 8.
  - Agregar la ruta `GET inscripciones/nuevo-ingreso/paso-4/planilla/(:num)` con el filtro `nuevoIngresoAuth:4`.
  - Registrar `Services::htmlPdfBuilder()` y `Services::nuevoIngresoPlanilla()`.
  - Mostrar en la planilla los datos guardados de `ni_inscripciones`, la carrera, la sede, el turno y la modalidad.
  - Cubrir con pruebas unitarias el servicio, el builder genérico y `PdfOptions`, y con pruebas de integración el controlador, la ruta y la vista del bloque de éxito.

- No incluye:
  - Modificar `Imprimir::planilla()` ni `app/Views/imprimir/planilla.php`; la planilla regular conserva su comportamiento y su sesión de estudiante.
  - Migrar `Imprimir::planilla()` ni `Servicio` al builder genérico. Queda como refactor posterior.
  - Persistir los campos del formulario extendido de Paso 0 (representante, salud, información académica, información laboral). Hoy no se guardan en `ni_inscripciones` y esta feature no agrega columnas ni migraciones.
  - Mostrar periodo académico, número o código de postulación, estado del pago, monto, referencia o plan dentro de la planilla.
  - Mostrar el estado de los recaudos.
  - Modificar el recibo, su ruta, su servicio, su builder o su diseño.
  - Cambiar la máquina de estados, las pasarelas, Zelle, GHL, Orbis o la sincronización académica.
  - Generar PDFs para estados distintos de 3 u 8.
  - Almacenar el PDF, crear historial de descargas, auditar descargas o reenviar documentos por correo.
  - Agregar CSRF a rutas GET de solo lectura.
  - Modificar `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

> **Decisión de alcance:** la petición original terminaba en "y". En la entrevista el usuario confirmó que no faltaba ningún requisito adicional. También se propuso dividir el trabajo en dos features independientes, pero el usuario eligió un solo documento. Por eso se mantiene un único plan con tres fases internas secuenciales: builder genérico HTML→PDF, planilla de nuevo ingreso y bloque de éxito que la enlaza.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`. El Paso 4 ya tiene estado, plan e intención (FEAT-004), métodos y pago en línea (FEAT-005), verificación de Zelle (FEAT-006), recibo PDF (FEAT-007) y sincronización GHL (FEAT-008).
- El recibo ya existe: `Paso3::recibo($id)` (`app/Controllers/Inscripciones/NuevoIngreso/Paso3.php:207`), la ruta `GET inscripciones/nuevo-ingreso/paso-4/recibo/(:num)` y el servicio `NuevoIngresoReciboService`. Esta feature no lo modifica; solo conserva su botón en el nuevo bloque de éxito.
- `Paso3::index()` ya deriva el estado `aprobado` para las intenciones 3 y 8 y pasa `$estado`, `$intencion`, `$monto` y `$urls` a la vista `estado.php`.
- `NuevoIngresoPagoService::obtenerIntencion($id, $niId)` filtra por `ni_inscripcion_id` y `borrado_dt IS NULL`; una intención ajena se comporta como inexistente. `estaAprobada()` reconoce los estados 3 y 8.
- `ni_inscripciones` guarda: `id`, `sucursal_carrera_id`, `turno_id`, `modalidad`, `pais_provincia_id`, `identificacion_tipo`, `identificacion_valor`, `nombre`, `apellido`, `correo`, `telefono`, `ciudad`, `direccion`, `paso_actual`, `ghl_contact_id`, `ghl_sincronizado`, `orbis_sincronizado`, `created_at` y `updated_at`.
- `es_sucursales_carreras` relaciona `id` con `sucursal_id` y `carrera_id`. Los nombres visibles salen de `es_carreras.nombre` y `aasucurs.sucursal_nombre` en la base principal, igual que en el Paso 0.
- `turno_id` corresponde a `ceturno.CeTurnoID` en la base de la sede. El nombre visible es `CoTurno`, según `OfertaAcademicaService::listarTurnosActivos()`.
- `modalidad` se interpreta con `OfertaAcademicaPresenter::MODALIDADES`: `0` = Presencial, `1` = Virtual.
- `pais_provincia_id` se resuelve en `gb_paises_provincias.nombre` y `gb_paises.nombre`, igual que en la sincronización GHL del Paso 0.
- `identificacion_tipo = 0` es `V` y `1` es `E`, según el formulario de Paso 0 y FEAT-007.
- Dompdf ya se usa en el proyecto mediante `include_once 'dompdf/autoload.inc.php'` (`app/Controllers/Imprimir.php` y `app/Controllers/Servicio.php`). La carpeta `public/dompdf/` existe en este checkout pero está ignorada por git; se asume que el entorno de despliegue la conserva.
- El nuevo `HtmlPdfBuilder` centraliza el uso de Dompdf para los reportes nuevos. No conoce nuevo ingreso, sesión, base de datos, ruta ni nombre de archivo.
- `PdfOptions` es un objeto de configuración del PDF: papel, orientación, recursos remotos, parser HTML5 y opciones adicionales de Dompdf. Sus valores por defecto son Letter, vertical, recursos remotos habilitados y parser HTML5 habilitado.
- El logo de la planilla regular está en `public/imagenes/logo.jpg`. La nueva plantilla reutiliza ese recurso con `base_url()` y `HtmlPdfBuilder` con `remoteEnabled = true`.
- La planilla no muestra el periodo porque no está persistido en `ni_inscripciones`; el usuario decidió no obtenerlo del contexto de pago.
- La planilla no muestra número de postulación porque el usuario decidió no incluir identificador.
- La planilla no muestra datos de pago porque el usuario decidió que solo contenga datos de inscripción.
- `docs/features` contiene `FEAT-001` a `FEAT-008`; `FEAT-009` no colisiona. Se respeta el esquema del repositorio en lugar de `feature-000`.
- Las pruebas de integración usan SQLite en archivo y dobles, como `Paso4ReciboTest`, `Paso4PagoTest` y `ZelleNuevoIngresoTest`, porque el controlador resuelve la conexión de la sede.

## Fases internas de implementación

La feature se implementa en tres fases secuenciales. Cada fase cierra con `php -l`, pruebas del área y revisión antes de continuar.

1. **Fase A - Builder genérico HTML→PDF:** crear `PdfOptions`, `PdfGenerationException` y `HtmlPdfBuilder`; registrar `Services::htmlPdfBuilder()`; cubrir con pruebas unitarias papel, orientación, opciones y HTML con acentos. Esta fase es un habilitador reutilizable y no conoce nuevo ingreso.
2. **Fase B - Planilla de inscripción:** crear la excepción, el servicio, la vista de planilla, el método `Paso3::planilla`, la ruta, el servicio de contenedor y sus pruebas. El servicio usa `HtmlPdfBuilder` con `PdfOptions`. Al final de esta fase la planilla ya se puede solicitar por URL con una sesión válida, aunque todavía no exista el botón visible.
3. **Fase C - Bloque de éxito:** reemplazar el bloque "Pago aprobado" por el mensaje de éxito con los dos botones y actualizar las pruebas de integración de la vista. Esta fase depende de la ruta creada en la Fase B.

## Flujo normal

1. Paso 1: El aspirante completa el pago y `Paso3::postPago()` redirige al Paso 4 con `exito_pago`.
2. Paso 2: El aspirante abre `GET /inscripciones/nuevo-ingreso/paso-4`. El filtro `nuevoIngresoAuth:4` valida sesión y `paso_actual >= 4`.
3. Paso 3: `Paso3::index()` resuelve la intención vigente o la última, deriva el estado `aprobado` para los estados 3 u 8 y renderiza `paso3/index.php`.
4. Paso 4: `paso3/index.php` incluye `paso3/estado.php`. Al recibir `estado = 'aprobado'`, la vista muestra el bloque de éxito con el mensaje, el monto y la referencia actuales, el botón "Descargar recibo", el botón "Descargar planilla de inscripción" y el enlace "Ver intentos de pago".
5. Paso 5: El botón "Descargar recibo" abre en una pestaña nueva la ruta existente `GET /inscripciones/nuevo-ingreso/paso-4/recibo/{intencionId}`. El flujo del recibo no cambia.
6. Paso 6: El botón "Descargar planilla de inscripción" abre en una pestaña nueva `GET /inscripciones/nuevo-ingreso/paso-4/planilla/{intencionId}`.
7. Paso 7: La petición entra por la ruta explícita `paso-4/planilla/(:num)` con `nuevoIngresoAuth:4`.
8. Paso 8: `Paso3::planilla($id)` comprueba que el método sea GET. Si no lo es, responde 405 con la página de mensaje y un enlace al Paso 4.
9. Paso 9: `Paso3::planilla()` ejecuta `sesionValida()` como defensa adicional al filtro y al auto-routing.
10. Paso 10: Valida que `$id` sea un entero positivo. Si no, responde 422 con el mensaje "La intención de pago es obligatoria." y enlace al Paso 4.
11. Paso 11: Resuelve el contexto con `Services::nuevoIngresoContext()->resolver()` y obtiene `ni_inscripcion_id` de la postulación. La identidad y la sede no se leen de la petición.
12. Paso 12: Llama a `Services::nuevoIngresoPlanilla()->generar($id, $niId)`.
13. Paso 13: `NuevoIngresoPlanillaService` obtiene la intención con `NuevoIngresoPagoService::obtenerIntencion($id, $niId)`. Si es nula, ajena o está borrada, lanza `NuevoIngresoPlanillaException::porIntencionNoEncontrada()`.
14. Paso 14: El servicio comprueba `estaAprobada($intencion)`. Si el estado no es 3 u 8, lanza `porPagoNoAprobado()`.
15. Paso 15: Carga la postulación con `NiInscripcionModel`. Si no existe, lanza `porPostulacionNoEncontrada()`.
16. Paso 16: Resuelve la carrera y la sede desde `es_sucursales_carreras`, `es_carreras` y `aasucurs` en la base principal, usando `sucursal_carrera_id`. No acepta una carrera o sede enviadas por el cliente.
17. Paso 17: Resuelve la conexión de la sede con `ConexionSedeResolverInterface` y consulta `ceturno` por `CeTurnoID = ni_inscripciones.turno_id` para obtener `CoTurno`.
18. Paso 18: Resuelve país y provincia desde `gb_paises_provincias` y `gb_paises` por `pais_provincia_id`.
19. Paso 19: Normaliza la identificación con prefijo `V-` o `E-` según `identificacion_tipo`, y la modalidad con `OfertaAcademicaPresenter::MODALIDADES`.
20. Paso 20: Construye un arreglo de datos con nombre, apellido, identificación, correo, teléfono, país, provincia, ciudad, dirección, carrera, sede, turno y modalidad. Los campos derivados que no se puedan resolver se muestran como "No disponible" y se registra una advertencia.
21. Paso 21: Renderiza `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` con los datos normalizados. La vista no consulta base de datos ni sesión.
22. Paso 22: El servicio crea `new PdfOptions('letter', 'portrait', true, true)` y llama a `HtmlPdfBuilder::generar($html, $opciones)`.
23. Paso 23: `HtmlPdfBuilder` incluye el autoload de Dompdf, aplica las opciones, configura el papel, carga el HTML, renderiza y devuelve el binario.
24. Paso 24: El servicio devuelve `['pdf' => $binario, 'nombre_archivo' => 'PlanillaNI' . $niId . '.pdf']`.
25. Paso 25: `Paso3::planilla()` responde con `Content-Type: application/pdf`, `Content-Disposition: attachment; filename="PlanillaNI{niId}.pdf"`, `Cache-Control: private, no-store` y el cuerpo binario.
26. Paso 26: El navegador descarga el PDF. La operación es idempotente y no escribe en base de datos.
27. Paso 27: Si el aspirante recarga el Paso 4, el bloque de éxito y ambos botones vuelven a mostrarse mientras el estado siga siendo 3 u 8.

## Flujos alternativos / variantes

### Descarga del recibo desde el bloque de éxito

1. Paso 1: El bloque de éxito muestra el botón "Descargar recibo" con la URL `urls.recibo . intencionId`.
2. Paso 2: El enlace se abre en una pestaña nueva con `target="_blank"` y `rel="noopener"`.
3. Paso 3: La petición llega a la ruta y al método existentes de FEAT-007, que vuelven a validar sesión, paso, propiedad y estado.
4. Paso 4: El PDF se genera y se muestra en línea como hasta ahora; esta feature no altera su contenido ni su nombre.

### Planilla con datos derivados incompletos

1. Paso 1: La postulación existe y el pago está aprobado, pero `turno_id` es nulo, el turno ya no existe en `ceturno` o la relación carrera/sede no devuelve nombre.
2. Paso 2: El servicio deja el campo correspondiente en "No disponible" y registra una advertencia en el log.
3. Paso 3: La planilla se genera igualmente con los datos que sí existen.
4. Paso 4: No se bloquea la descarga por un catálogo incompleto.

### Planilla sin país o provincia resueltos

1. Paso 1: `pais_provincia_id` apunta a un registro inexistente o inactivo.
2. Paso 2: El servicio muestra país y provincia como "No disponible" y registra una advertencia.
3. Paso 3: Ciudad y dirección se muestran tal como están guardadas.
4. Paso 4: La planilla se genera sin inventar valores geográficos.

### Pago verificado por Zelle (estado 8)

1. Paso 1: La intención está en estado 8.
2. Paso 2: `estaAprobada()` devuelve verdadero y la planilla se genera igual que para el estado 3.
3. Paso 3: La planilla no muestra monto, referencia, tasa, descuento ni ningún dato de pago.
4. Paso 4: El bloque de éxito conserva el monto y la referencia que ya muestra el Paso 4.

### Pago no Zelle aprobado (estado 3)

1. Paso 1: La intención está en estado 3.
2. Paso 2: La planilla se genera con los mismos datos de inscripción.
3. Paso 3: No se consultan reportes Zelle, tasas ni descuentos.
4. Paso 4: El comportamiento es equivalente al de Zelle para la planilla.

### Descarga repetida

1. Paso 1: El aspirante vuelve a solicitar la misma planilla.
2. Paso 2: El servicio vuelve a leer la postulación y los catálogos, sin escribir ni consumir nada.
3. Paso 3: El PDF se regenera con los mismos datos persistidos.
4. Paso 4: No se crea auditoría, historial ni archivo temporal persistente.

### Acceso por auto-routing

1. Paso 1: Un cliente invoca `Paso3::planilla` por una URI no prevista en `Routes.php`.
2. Paso 2: El método ejecuta la comprobación de GET, `sesionValida()`, la validación del id y la resolución del contexto antes de generar.
3. Paso 3: Sin sesión o sin paso 4 redirige; con sesión válida aplica las mismas reglas de propiedad y estado.
4. Paso 4: No se expone ninguna planilla de una postulación ajena.

### Recibo regular (regresión)

1. Paso 1: Un estudiante del portal regular abre `GET /Reportes/Recibo/{id}`.
2. Paso 2: `Reportes::Recibo` conserva su validación de sesión, propiedad, estado 3/8 y rechazo de intenciones de nuevo ingreso.
3. Paso 3: Genera el PDF con `ReciboPdfBuilder` y el mismo nombre `Recibo{id}.pdf`.
4. Paso 4: No hay cambios en su contenido ni en su respuesta.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Sesión de nuevo ingreso ausente o inválida | Filtro `nuevoIngresoAuth:4`; `sesionValida()` | Redirección a `/inscripciones/nuevo-ingreso`; en AJAX 401 | Sin PDF; no se escribe |
| `paso_actual` menor a 4 | Filtro; `sesionValida()` | Redirección a `/inscripciones/nuevo-ingreso/materias`; en AJAX 403 | Sin PDF |
| Método distinto de GET en `planilla` | `$this->request->getMethod()` | Página de mensaje 405 con enlace al Paso 4 | Sin PDF |
| `$id` ausente, cero, negativo o no numérico | Validación del controlador | Página de mensaje 422 "La intención de pago es obligatoria." | Sin PDF |
| Contexto de postulación inválido | `NuevoIngresoContextException` | Página de mensaje 422 con enlace al Paso 4 | Sin PDF |
| `ni_inscripcion_id` no resuelto | Validación del controlador | Página de mensaje 422 o 500 según el origen; log técnico | Sin PDF |
| Intención inexistente, ajena o con `borrado_dt` | `obtenerIntencion()` devuelve `null` | Página de mensaje 422 "No tienes permisos para ver esta planilla."; no se revela si el id existe | Sin PDF; sin datos ajenos |
| Intención en estado distinto de 3 u 8 | `estaAprobada()` devuelve `false` | Página de mensaje 422 "La planilla no está disponible. El pago aún no ha sido aprobado o verificado." con enlace al Paso 4 | Estado intacto |
| Postulación no encontrada | `NiInscripcionModel` devuelve `null` | Página de mensaje 422 "No fue posible generar la planilla."; log técnico | Sin PDF |
| Carrera o sede no resueltas | Consulta sin fila | Campo "No disponible"; log warning; la planilla se genera | PDF generado |
| Turno nulo, inexistente o fuera de la sede | Consulta `ceturno` sin fila | Campo "No disponible"; log warning; la planilla se genera | PDF generado |
| Provincia o país no resueltos | Consulta `gb_paises_provincias` sin fila | Campos "No disponible"; log warning; la planilla se genera | PDF generado |
| Opciones de PDF inválidas | Validación de `PdfOptions` | Excepción `InvalidArgumentException`; el controlador responde 500 y registra el detalle técnico | Sin PDF; sin escritura |
| Dompdf no disponible en `public/dompdf` | `HtmlPdfBuilder` no encuentra el autoload o la clase | `PdfGenerationException::porDompdfNoDisponible()`; página 500 "No fue posible generar la planilla. Intenta nuevamente."; log técnico | Sin PDF; sin escritura |
| Error de Dompdf al renderizar | `HtmlPdfBuilder` captura `\Throwable` | `PdfGenerationException::porErrorAlGenerar()`; página 500; log técnico sin datos personales | Sin PDF |
| Auto-routing sin filtro | `sesionValida()` y validaciones internas | Misma respuesta que la ruta explícita | Sin PDF |
| Error inesperado de base de datos | Excepción del modelo o del servicio | Página de mensaje 500; log técnico sin datos personales | Sin PDF; sin escritura |
| Recibo regular con intención NI | Guarda existente en `Reportes::Recibo` | Página de mensaje "No tienes permisos para ver este recibo." | Sin PDF |
| Regresión del recibo regular | Prueba/smoke test | El PDF regular conserva filas, diseño y nombre | Sin cambio funcional |

## Reglas de negocio y validaciones

- El bloque de éxito se muestra solo cuando `estado === 'aprobado'` (estados 3 u 8) y `intencionId > 0`. En cualquier otro estado se conserva el bloque actual correspondiente.
- El bloque de éxito reemplaza al bloque "Pago aprobado"; no se duplica. Conserva el monto y la referencia que ya muestra el Paso 4.
- El mensaje de éxito se muestra cada vez que se abre el Paso 4 en estado aprobado, no solo una vez después del pago.
- El botón "Descargar recibo" conserva la ruta, el método y el comportamiento existentes de FEAT-007. No se modifica el recibo.
- El botón "Descargar planilla de inscripción" solo aparece en el bloque de éxito y apunta a `paso-4/planilla/{intencionId}`.
- La planilla solo se genera para intenciones propias de la postulación: `obtenerIntencion($id, $niId)` con `ni_inscripcion_id` y `borrado_dt IS NULL`. La identidad y la sede salen de la sesión `nuevo_ingreso` y del contexto, nunca de un `AASUCURSID` o de una cédula enviados por el cliente.
- Solo se permite el estado 3 (aprobado) u 8 (verificado). Cualquier otro estado, incluido 7 (en verificación), responde 422 y no genera PDF.
- `Paso3::planilla` es una operación de solo lectura: no actualiza la intención, no crea reportes, no marca GHL, no sincroniza Orbis y no modifica `paso_actual`.
- La planilla contiene solo datos básicos guardados y datos derivados de la oferta académica:
  - Apellidos y nombres.
  - Identificación con prefijo `V-` o `E-`.
  - Correo electrónico.
  - Teléfono.
  - País y estado/provincia.
  - Ciudad.
  - Dirección.
  - Carrera.
  - Sede.
  - Turno.
  - Modalidad.
- La planilla no muestra periodo, número de postulación, monto, referencia, estado del pago, plan, tasa, descuento, recaudos, representante, salud, información académica ni información laboral.
- Los campos derivados que no se puedan resolver se muestran como "No disponible"; no se inventan valores ni se bloquea la descarga.
- El nombre y el apellido salen de `ni_inscripciones`, no de la sesión ni de un parámetro del cliente.
- La identificación sale de `identificacion_tipo` y `identificacion_valor` de `ni_inscripciones`. `0` se presenta como `V-` y `1` como `E-`.
- El turno se resuelve con `turno_id` en la base de la sede (`ceturno.CeTurnoID`) y se presenta con `CoTurno`. No se consulta el turno en la base principal.
- La modalidad se presenta con `OfertaAcademicaPresenter::MODALIDADES`; un valor distinto de 0 o 1 se muestra como "No disponible".
- La carrera y la sede se resuelven desde `sucursal_carrera_id` y no desde la petición.
- El país y la provincia se resuelven desde `pais_provincia_id` en la base principal.
- La planilla reutiliza el diseño, el logo, el encabezado, el código de formato y la disposición de `app/Views/imprimir/planilla.php`, adaptado a los datos de nuevo ingreso. No se modifica la plantilla regular.
- El nombre del archivo es `PlanillaNI{niId}.pdf`, donde `niId` es el id de la postulación y no se muestra dentro del documento.
- La respuesta de la planilla usa `Content-Disposition: attachment` para forzar la descarga. El recibo conserva `inline` como hasta ahora.
- No se almacena el PDF ni se crea historial de descargas. Cada solicitud regenera el documento con los datos persistidos.
- `NuevoIngresoPlanillaService` no conoce la sesión, la ruta, la vista ni Dompdf. Recibe `niInscripcionId` e `intencionId` ya validados por el controlador, vuelve a validar propiedad y estado, renderiza el HTML y delega la generación del PDF en `HtmlPdfBuilder`.
- `HtmlPdfBuilder` no consulta base de datos ni conoce sesión, ruta, reporte o nombre de archivo: recibe el HTML y `PdfOptions` y devuelve el binario. Es reutilizable por futuros reportes.
- `PdfOptions` define papel, orientación, recursos remotos, parser HTML5 y opciones adicionales de Dompdf. Por defecto usa Letter, vertical, recursos remotos habilitados y parser HTML5 habilitado.
- `PdfGenerationException` es genérica y no menciona nuevo ingreso ni datos personales. El detalle técnico se registra en el log.
- La planilla usa `new PdfOptions('letter', 'portrait', true, true)`.
- Todos los métodos públicos nuevos validan sesión, paso, id, propiedad y estado, aunque exista una ruta con filtro, para cubrir el auto-routing.
- La vista de la planilla escapa la salida con `esc()`; el HTML se construye con datos ya normalizados.
- No se agregan dependencias, migraciones, seeds, CSRF ni cambios de esquema. Dompdf ya es una dependencia de facto del proyecto, aunque no esté declarada en `composer.json`.
- El bloque de éxito usa clases Tailwind existentes. No se edita `public/css/tailwind-v4.css`.

## Contratos y diseño propuesto

### `PdfOptions`

| Propiedad | Tipo | Valor por defecto | Regla |
| --- | --- | --- | --- |
| `paper` | string o array | `'letter'` | Cadena no vacía o arreglo `[ancho, alto]` con valores positivos. |
| `orientation` | string | `'portrait'` | Solo `portrait` o `landscape`; otro valor lanza `InvalidArgumentException`. |
| `remoteEnabled` | bool | `true` | Habilita recursos remotos en Dompdf. |
| `html5ParserEnabled` | bool | `true` | Habilita el parser HTML5 de Dompdf. |
| `dompdfOptions` | array | `[]` | Opciones adicionales que se pasan a `set_option`. |

- Constructor propuesto: `__construct($paper = 'letter', string $orientation = 'portrait', bool $remoteEnabled = true, bool $html5ParserEnabled = true, array $dompdfOptions = [])`.
- Valida papel y orientación en el constructor. No conoce reporte, sesión, base de datos ni nombre de archivo.
- Es un objeto de configuración, no un builder: no genera PDF.

### `HtmlPdfBuilder`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `generar(string $html, ?PdfOptions $opciones = null): string` | Convertir HTML en un PDF con Dompdf y devolver el binario. | Sin escritura; sin base de datos. |

- Si `$opciones` es nulo, usa `new PdfOptions()`.
- Incluye el autoload de Dompdf con `include_once FCPATH . 'dompdf/autoload.inc.php'` o el patrón existente del proyecto.
- Aplica `remoteEnabled`, `html5ParserEnabled`, `dompdfOptions`, papel y orientación.
- Ejecuta `loadHtml`, `render` y devuelve `$dompdf->output()`.
- Si el autoload o la clase no existen, lanza `PdfGenerationException::porDompdfNoDisponible()`.
- Si Dompdf falla al renderizar, lanza `PdfGenerationException::porErrorAlGenerar()`.
- No conoce el origen de los datos, la sesión, la ruta, el nombre del archivo ni las clases de nuevo ingreso.

### `PdfGenerationException`

- Extiende `\RuntimeException`.
- Fábricas: `porDompdfNoDisponible(?\Throwable $previo = null)` y `porErrorAlGenerar(?\Throwable $previo = null)`.
- Mensajes genéricos en español, sin detalles técnicos ni datos personales.
- El controlador la traduce a una página de mensaje con código 500; el detalle técnico se registra en el log.

### `NuevoIngresoPlanillaService`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `generar(int $intencionId, int $niInscripcionId): array` | Validar propiedad y estado, construir los datos de la planilla, renderizar el HTML y generar el PDF. | Solo lectura; no escribe. Lanza `NuevoIngresoPlanillaException`. |

- Dependencias inyectables: `NiInscripcionModel`, `NuevoIngresoPagoService`, `BaseConnection` de la base principal, `ConexionSedeResolverInterface` y `HtmlPdfBuilder`.
- Reutiliza `obtenerIntencion()` y `estaAprobada()` del servicio de pago. No duplica la validación de propiedad.
- Construye `PdfOptions` con `paper = 'letter'`, `orientation = 'portrait'`, `remoteEnabled = true` y `html5ParserEnabled = true`.
- Devuelve:
  ```php
  [
      'pdf'            => $binario,
      'nombre_archivo' => 'PlanillaNI' . $niInscripcionId . '.pdf',
  ]
  ```
- Construye un arreglo interno `$datos` con las claves:
  ```php
  [
      'apellido',
      'nombre',
      'identificacion',
      'correo',
      'telefono',
      'pais',
      'provincia',
      'ciudad',
      'direccion',
      'carrera',
      'sede',
      'turno',
      'modalidad',
  ]
  ```
- Renderiza la vista y llama a `HtmlPdfBuilder::generar($html, $opciones)`.
- No conoce sesión, ruta, vista ni la sesión del portal regular.

### `NuevoIngresoPlanillaException`

- Extiende `\RuntimeException`.
- Fábricas: `porIntencionNoEncontrada()`, `porPagoNoAprobado()`, `porPostulacionNoEncontrada()` y `porErrorGeneracion(?\Throwable $previo = null)`.
- Mensajes en español, sin detalles técnicos ni datos personales.
- El controlador la traduce a una página de mensaje con código 422; los errores inesperados se traducen a 500.

### `Paso3::planilla`

| Aspecto | Regla |
| --- | --- |
| Firma | `public function planilla($id = 0)` |
| Método HTTP | Solo GET; otro método responde 405. |
| Sesión | `sesionValida()` exige `nuevo_ingreso` y `paso_actual >= 4`. |
| Id | Entero positivo; otro valor responde 422. |
| Contexto | `Services::nuevoIngresoContext()->resolver()`; `niId` sale de `inscripcion.id`. |
| Servicio | `Services::nuevoIngresoPlanilla()->generar($id, $niId)`. |
| Respuesta | `application/pdf`, `Content-Disposition: attachment`, `Cache-Control: private, no-store`, cuerpo binario. |
| Errores | Página de mensaje del layout de nuevo ingreso con enlace al Paso 4; 422 de dominio, 500 inesperado. |
| Escritura | Ninguna. |

### `Services`

- Agregar `use App\Libraries\Pdf\HtmlPdfBuilder;`, `use App\Libraries\Pdf\PdfGenerationException;` y `use App\Libraries\Inscripciones\NuevoIngreso\Planilla\NuevoIngresoPlanillaService;`.
- Agregar `public static $htmlPdfBuilderInstance = null;` y `public static $nuevoIngresoPlanillaInstance = null;`.
- `htmlPdfBuilder($getShared = true)` devuelve una instancia compartida de `HtmlPdfBuilder`.
- `nuevoIngresoPlanilla($getShared = true)` construye el servicio con `Database::connect()`, `new NiInscripcionModel($dbPrincipal)`, `self::nuevoIngresoPago()`, `new ConexionSedeResolver()`, `$dbPrincipal` y `self::htmlPdfBuilder()`.
- Las pruebas deben reiniciar ambas instancias en `setUp`/`tearDown`.

### Rutas y vistas

| Método | URI | Acción | Filtro |
| --- | --- | --- | --- |
| GET | `inscripciones/nuevo-ingreso/paso-4/planilla/(:num)` | `Paso3::planilla/$1` | `nuevoIngresoAuth:4` |

- `Paso3::urls()` agrega `'planilla' => $base . '/paso-4/planilla/'`.
- `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` reemplaza el bloque `aprobado` por el bloque de éxito y agrega el botón "Descargar planilla de inscripción" con `target="_blank"` y `rel="noopener"`.
- El botón del recibo se conserva dentro del mismo bloque y usa `$urls['recibo']`.
- `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` es una plantilla HTML autónoma para el builder. Adapta el encabezado, los estilos y las tablas de `app/Views/imprimir/planilla.php`, pero recibe el arreglo `$planilla` de nuevo ingreso.
- No se modifica `app/Views/imprimir/planilla.php` ni `app/Controllers/Imprimir.php`.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Libraries/Pdf/PdfOptions.php` | Configuración reutilizable del PDF. |
| Crear | `app/Libraries/Pdf/HtmlPdfBuilder.php` | Exportación genérica HTML→PDF. |
| Crear | `app/Libraries/Pdf/PdfGenerationException.php` | Errores genéricos del builder. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaService.php` | Dominio y composición de la planilla NI. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaException.php` | Errores de dominio de la planilla. |
| Crear | `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` | Plantilla HTML adaptada del diseño existente. |
| Modificar | `app/Config/Services.php` | Registrar `htmlPdfBuilder` y `nuevoIngresoPlanilla`. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | `planilla()`, `urls()` y manejo de errores. |
| Modificar | `app/Config/Routes.php` | Ruta GET de la planilla con `nuevoIngresoAuth:4`. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Bloque de éxito y botón de planilla. |
| Crear | `tests/app/Libraries/Pdf/HtmlPdfBuilderTest.php` | PDF válido, papel, orientación, opciones y HTML con acentos. |
| Crear | `tests/app/Libraries/Pdf/PdfOptionsTest.php` | Valores por defecto y validación de papel y orientación. |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaServiceTest.php` | Propiedad, estados, datos, campos ausentes y no escritura. |
| Crear | `tests/app/Integration/Paso4PlanillaTest.php` | Ruta, filtro, PDF, 405, 422 e aislamiento. |
| Modificar | `tests/app/Integration/Paso4NuevoIngresoTest.php` | Bloque de éxito y presencia de ambos botones. |
| Documentar | `docs/features/009-exito-pago-recibo-planilla-nuevo-ingreso/plan.md` | Este plan. |

No se modifican migraciones, seeds, `gb_config`, `ni_inscripciones`, `NuevoIngresoPagoService`, `NuevoIngresoReciboService`, `Reportes::Recibo`, `Imprimir::planilla()`, las pasarelas, la SPA ni la API. No se agregan dependencias.

## Criterios de finalización

- [ ] `HtmlPdfBuilder::generar()` devuelve un binario que comienza con `%PDF-` y no lanza errores con acentos ni con campos vacíos.
- [ ] `HtmlPdfBuilder::generar()` respeta `PdfOptions` con papel Letter y orientación vertical por defecto.
- [ ] `HtmlPdfBuilder::generar()` respeta un papel y una orientación distintos cuando se le pasan en `PdfOptions`.
- [ ] `HtmlPdfBuilder` no referencia clases de nuevo ingreso ni consulta base de datos, sesión o rutas.
- [ ] `PdfOptions` valida el papel y la orientación; una orientación inválida lanza `InvalidArgumentException`.
- [ ] `PdfGenerationException` se lanza si Dompdf no está disponible o si falla el render.
- [ ] La vista `planilla.php` muestra apellidos, nombres, identificación, correo, teléfono, país, provincia, ciudad, dirección, carrera, sede, turno y modalidad.
- [ ] La identificación se presenta con prefijo `V-` o `E-` según `identificacion_tipo`.
- [ ] El turno se resuelve en la base de la sede por `turno_id` y se muestra con `CoTurno`.
- [ ] La modalidad se muestra como "Presencial" o "Virtual" según `OfertaAcademicaPresenter::MODALIDADES`.
- [ ] 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.
- [ ] Los campos derivados no resueltos se muestran como "No disponible" y registran una advertencia; la planilla se genera igualmente.
- [ ] `NuevoIngresoPlanillaService::generar()` solo acepta intenciones propias en estado 3 u 8; una intención ajena, inexistente o en otro estado lanza la excepción de dominio.
- [ ] `NuevoIngresoPlanillaService` usa `HtmlPdfBuilder` con `new PdfOptions('letter', 'portrait', true, true)`.
- [ ] `Paso3::planilla` solo acepta GET y responde 405 con página de mensaje para otros métodos.
- [ ] `Paso3::planilla` valida sesión, paso, id positivo, propiedad y estado; una intención ajena o inexistente responde 422 sin revelar su existencia.
- [ ] La ruta `GET /inscripciones/nuevo-ingreso/paso-4/planilla/(:num)` existe con el filtro `nuevoIngresoAuth:4`.
- [ ] El controlador responde con `Content-Type: application/pdf`, `Content-Disposition: attachment; filename="PlanillaNI{niId}.pdf"`, `Cache-Control: private, no-store` y el cuerpo binario.
- [ ] La planilla se genera sin escribir en base de datos y es idempotente ante descargas repetidas.
- [ ] El bloque "Pago aprobado" se reemplaza por un bloque de éxito con mensaje, monto, referencia, botón "Descargar recibo" y botón "Descargar planilla de inscripción".
- [ ] Ambos botones aparecen solo en el estado aprobado y se abren en una pestaña nueva con `rel="noopener"`.
- [ ] El botón "Descargar recibo" conserva la ruta y el comportamiento existentes de FEAT-007.
- [ ] El bloque de éxito se muestra cada vez que se abre el Paso 4 en estado aprobado.
- [ ] No se modifican `Imprimir::planilla()`, `app/Views/imprimir/planilla.php`, `Reportes::Recibo`, `ReciboPdfBuilder` ni el recibo de nuevo ingreso.
- [ ] Las pruebas unitarias del servicio cubren estado 3, estado 8, estado 7, intención ajena, postulación inexistente, turno ausente, país/provincia ausentes y mapeo de modalidad.
- [ ] Las pruebas unitarias del builder cubren PDF válido, papel, orientación, opciones y HTML con acentos.
- [ ] Las pruebas unitarias de `PdfOptions` cubren valores por defecto y validación.
- [ ] Las pruebas de integración cubren PDF 200, 405, 422 por id inválido, 422 por estado 7, 422 por intención ajena y redirección sin sesión.
- [ ] Las pruebas de `Paso4NuevoIngresoTest`, `Paso4ReciboTest`, `Paso4PagoTest`, `ZelleNuevoIngresoTest` y el área de pagos siguen pasando.
- [ ] Se ejecuta un smoke test manual de la planilla y del recibo en un entorno con sesión válida y pago aprobado.
- [ ] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [ ] `graphify update .` se ejecuta después de los cambios de código.
- [ ] No se agregaron dependencias, migraciones, seeds, CSRF ni cambios en `vendor/`, `system/` o `public/vendor/`.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Momento del mensaje | Al aprobarse el pago, en el Paso 4. |
| Persistencia del mensaje | Se muestra siempre que el Paso 4 esté en estado aprobado. |
| Bloque actual | El nuevo mensaje reemplaza el bloque "Pago aprobado"; no se duplica. |
| Alcance documental | Un solo documento con tres fases internas, aunque se recomendó dividirlo. |
| Builder PDF | Genérico `HtmlPdfBuilder` con `PdfOptions`; recibe HTML y especificaciones, no está atado a nuevo ingreso. |
| Contenido de la planilla | Solo datos guardados en base de datos y datos derivados de la oferta académica. |
| Datos personales | Todos los de `ni_inscripciones`: nombre, apellido, identificación, correo, teléfono, ciudad, dirección y país/provincia. |
| Datos de pago | No se incluyen en la planilla. |
| Periodo | No se muestra. |
| Número de postulación | No se muestra. |
| Secciones no guardadas | Se omiten representante, salud, información académica e información laboral. |
| Formato | PDF con el diseño existente adaptado, mediante una plantilla nueva para nuevo ingreso. |
| Disponibilidad | Recibo y planilla solo con pago aprobado o verificado (estados 3 u 8). |
| Frase truncada | El usuario confirmó que no faltaba ningún requisito adicional después de "y". |

## Riesgos y deuda técnica

- **Dompdf no declarado en Composer:** `public/dompdf/` está ignorado por git y el proyecto lo usa con `include_once`. Si el entorno de despliegue no lo conserva, la planilla responde 500. El nuevo `HtmlPdfBuilder` centraliza ese acoplamiento y facilita formalizar la dependencia en una tarea aparte.
- **Builder genérico sin migración de reportes existentes:** `Imprimir::planilla()` y `Servicio` siguen usando su inclusión manual de Dompdf. No se unifican en esta feature; debe hacerse como refactor posterior.
- **Refactor pendiente del formulario extendido:** representante, salud, académica y laboral se capturan en la variante `extra_fields` pero no se persisten. La planilla no los muestra y el usuario aceptó explícitamente esa limitación.
- **Datos derivados de catálogos:** un turno eliminado, una relación carrera/sede desactivada o una provincia borrada producen "No disponible". Es preferible a bloquear la descarga, pero debe revisarse en el smoke test.
- **Logo remoto:** la plantilla usa `base_url()` y `RemoteEnabled` en `PdfOptions`. Si el servidor no puede resolver la URL, el logo no se incrusta; la planilla debe seguir generándose.
- **Auto-routing:** `Paso3::planilla` es público y podría invocarse por una URI no prevista. Se mitiga con las validaciones internas y el filtro de la ruta explícita.
- **Contenido del bloque de éxito:** el Paso 4 muestra monto y referencia, pero la planilla no. Si negocio exige que la planilla incluya el pago, debe especificarse una feature posterior.
- **Sin almacenamiento ni auditoría:** cada descarga regenera el documento. No hay historial ni cache; es intencional para no agregar almacenamiento ni datos personales.
- **Sin CSRF:** las rutas son GET y de solo lectura. Cualquier cambio futuro que convierta la planilla en una acción con escritura debe revisar esta decisión.

## Preguntas abiertas y supuestos a validar

- Se asume que `public/dompdf/` estará disponible en el entorno de despliegue, igual que para `Imprimir::planilla()` y `Servicio::printDocument()`.
- Se asume que `HtmlPdfBuilder` es el único punto nuevo de acoplamiento con Dompdf y que no requiere declarar la dependencia en `composer.json` en esta feature.
- Se asume que `PdfOptions` usa Letter y vertical por defecto, con recursos remotos y parser HTML5 habilitados.
- Se asume que `HtmlPdfBuilder` devuelve el binario y no conoce el nombre del archivo ni las cabeceras HTTP.
- Se asume que `turno_id` guardado en `ni_inscripciones` corresponde a `ceturno.CeTurnoID` de la base de la sede.
- Se asume que `CoTurno` es el nombre visible aceptable para el turno en la planilla.
- Se asume que `es_carreras.nombre` y `aasucurs.sucursal_nombre` son los nombres oficiales que deben mostrarse.
- Se asume que `identificacion_tipo = 0` es `V` y `1` es `E`, según el formulario de Paso 0.
- Se asume que el logo `public/imagenes/logo.jpg` sigue disponible y es el adecuado para la planilla de nuevo ingreso.
- Se asume que el nombre `PlanillaNI{niId}.pdf` es aceptable.
- Se asume que la planilla debe descargarse con `Content-Disposition: attachment`; el recibo conserva `inline`.
- Se asume que omitir periodo y número de postulación es aceptable para el formato solicitado.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-29 | Creación del plan FEAT-009 tras revisar `Paso3`, `estado.php`, `NuevoIngresoReciboService`, `NuevoIngresoPagoService`, `OfertaAcademicaService`, `OfertaAcademicaPresenter`, `Imprimir::planilla()`, `app/Views/imprimir/planilla.php`, las migraciones de `ni_inscripciones` y las features FEAT-004 a FEAT-008. La entrevista definió: mensaje en el Paso 4 al aprobarse el pago, reemplazo del bloque actual, planilla solo con datos guardados, sin datos de pago, sin periodo, sin número de postulación, sin secciones no persistidas y un solo documento. | opencode (agente) |
| 2026-10-29 | Ajuste de diseño: se reemplaza el builder específico de planilla por `HtmlPdfBuilder` genérico con `PdfOptions`, reutilizable por futuros reportes. El plan pasa a tres fases: builder genérico, planilla de nuevo ingreso y bloque de éxito. | opencode (agente) |
