# Acta de compromiso en PDF en el Paso 4 y en el correo de inscripción culminada

- **Código:** FEAT-022
- **Tipo:** feature
- **Estado:** en curso
- **Fecha:** 2026-11-04
- **Autor:** opencode (agente)

## Objetivo

Generar un reporte PDF del Acta de Compromiso (términos y condiciones que el aspirante acepta en el Paso 0) y entregarlo en los dos puntos donde el estudiante cierra su inscripción: como descarga en la pantalla final (Paso 4) y como tercer adjunto del correo de inscripción culminada de FEAT-011. El acta debe servir para imprimirse, firmarse manuscritamente y conservarse en el expediente.

## Alcance

- **Incluye:**
  - Crear un servicio de dominio que genere el PDF del acta para una intención propia y aprobada.
  - Crear la excepción de dominio del acta con los mismos códigos de error que el recibo y la planilla.
  - Crear la vista HTML del PDF con el mismo texto del modal de Acta de Compromiso del Paso 0.
  - Incluir en el PDF el nombre completo, la cédula, la fecha de aceptación y un espacio para firma manuscrita.
  - Registrar el servicio en `Services`.
  - Crear el endpoint `GET /inscripciones/nuevo-ingreso/paso-4/acta/(:num)` con el filtro `nuevoIngresoAuth:3`.
  - Agregar el método de descarga en `Paso3`, con el mismo patrón de seguridad y cabeceras que la planilla.
  - Agregar el botón "Descargar acta de compromiso" junto al botón de planilla en la vista final (Paso 4), visible solo con pago aprobado.
  - Agregar el PDF del acta como tercer adjunto del correo de inscripción culminada y mencionarlo en el cuerpo y en el texto alternativo.
  - Cubrir con pruebas el servicio, el endpoint, la vista final, los adjuntos del correo y la regla de "todo o nada".

- **No incluye:**
  - Persistir la aceptación del acta en base de datos (fecha, IP, user agent, versión o hash).
  - Agregar columnas, migraciones o seeds.
  - Modificar el modal del Paso 0, su texto, su comportamiento de scroll, su checkbox o el flujo OTP.
  - Extraer el texto del acta a una vista parcial o a configuración compartida; se duplica de forma consciente.
  - Modificar el aviso Zelle existente de "Pago verificado" ni agregarle el acta.
  - Crear una firma electrónica, sello de tiempo, certificado digital o validación criptográfica.
  - Almacenar los PDFs generados, crear una cola de correos, un cron o una interfaz administrativa.
  - Agregar rutas, endpoints o pantallas para consultar el acta fuera del Paso 4 y del correo.
  - Cambiar las reglas de aprobación del pago, los estados de la intención, el recibo o la planilla.
  - Agregar dependencias, CSRF nuevo o cambios en `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

> **Evaluación de alcance:** la petición es una sola capacidad de negocio: emitir el Acta de Compromiso como reporte PDF y entregarla en los dos canales de cierre de la inscripción. La generación del PDF es prerrequisito del botón y del adjunto; no son funcionalidades independientes. Por eso se mantiene un único documento con tres fases internas y no se recomienda dividirla.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`.
- El texto vigente del Acta de Compromiso está en el modal del Paso 0: `app/Views/inscripciones/nuevo_ingreso/paso0/formulario.php:478-556`, con el contenido en las líneas `502-523`.
- El texto contiene tres bloques: párrafo introductorio, lista "Me comprometo a:" con dos viñetas y párrafo "Por lo cual acepto:" con la aceptación de sanciones.
- La decisión de la entrevista es reutilizar exactamente ese texto, sin redacción nueva ni cambios legales. El PDF lo duplica en su propia vista; no se modifica el Paso 0.
- La aceptación no se persiste. Por decisión de la entrevista, la "Fecha de aceptación" del PDF será la fecha de generación/emisión del documento.
- Consecuencia asumida: si el acta se descarga dos veces en fechas distintas, cada PDF mostrará la fecha de esa descarga. La fecha impresa no demuestra por sí sola el momento histórico de aceptación; la evidencia prevista es la firma manuscrita del aspirante.
- No hay una fecha de aceptación previa que migrar. Las postulaciones ya existentes pueden generar el acta sin columnas nuevas ni respaldos.
- El PDF solo se emite para una intención propia de la postulación y en estado aprobado (3) o verificado (8), igual que el recibo y la planilla.
- La identidad, el nombre, la cédula y la carrera salen de `ni_inscripciones`; la intención se valida con `NuevoIngresoPagoService::obtenerIntencion()` usando el `niId` del contexto. Nunca se aceptan datos del cliente.
- El `niId` del contexto se obtiene con `Services::nuevoIngresoContext()->resolver()`, igual que en `Paso3::recibo()` y `Paso3::planilla()`.
- El correo de inscripción culminada es el de FEAT-011 (`NuevoIngresoAprobacionNotificacionService` y `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php`). El acta se agrega allí; el aviso Zelle actual queda intacto.
- El correo se envía en los dos caminos de aprobación ya existentes: pago no Zelle aprobado (estado 3) y Zelle verificado (estado 8).
- Se mantiene la regla "todo o nada" del correo: si falla el recibo, la planilla o el acta, no se envía el correo y el intento queda `fallido`.
- El proyecto usa el esquema `FEAT-NNN` y carpetas `NNN-slug`. El siguiente número libre es `FEAT-022`; no colisiona con FEAT-001 a FEAT-021.
- La zona horaria de la aplicación es `America/Chicago` (`app/Config/App.php`). La fecha del acta se toma con `date('d/m/Y')` en esa zona. Si el negocio exige hora de Venezuela, se ajusta a `America/Caracas` antes de implementar; queda como supuesto.
- `public/dompdf/` sigue siendo una dependencia de facto del proyecto, igual que para el recibo y la planilla. Si no está disponible, el acta no se genera.
- El PDF se genera en memoria y no se almacena. El nombre del archivo es `ActaCompromisoNI{niId}.pdf`, consistente con `PlanillaNI{niId}.pdf`.

## 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 - Servicio, excepción y vista PDF:** crear `NuevoIngresoActaCompromisoService`, `NuevoIngresoActaCompromisoException` y la vista `app/Views/inscripciones/nuevo_ingreso/pdf/acta_compromiso.php`; registrarlo en `Services`; cubrir con pruebas la generación, los datos, el texto y los rechazos. Esta fase no expone ruta ni correo.
2. **Fase B - Endpoint y botón en Paso 4:** agregar la ruta `paso-4/acta/(:num)`, el método `Paso3::acta()` y el botón en la vista final; pasar `$estaAprobada` desde `Paso4::index()`. Cubrir con pruebas las cabeceras, la descarga, los errores y la visibilidad del botón.
3. **Fase C - Adjunto en el correo:** inyectar el servicio del acta en `NuevoIngresoAprobacionNotificacionService`, generar el PDF, adjuntarlo y actualizar la plantilla y el texto alternativo. Cubrir con pruebas el tercer adjunto y la regla de "todo o nada".

## Flujo normal

### Generación y descarga desde el Paso 4

1. Paso 1: El aspirante completa el pago y la intención queda aprobada en estado 3 o verificada en estado 8.
2. Paso 2: `Paso4::index()` confirma que el pago está aprobado y renderiza la pantalla final con `$estaAprobada = true`.
3. Paso 3: La vista final arma la URL del acta con el id de la intención: `base_url('inscripciones/nuevo-ingreso/paso-4/acta/' . (int) $intencion['id'])`.
4. Paso 4: La vista muestra el botón "Descargar acta de compromiso" junto al botón "Descargar planilla de inscripción", solo si `$estaAprobada` y el id de la intención son válidos.
5. Paso 5: El aspirante hace clic. La petición GET llega a `Paso3::acta($id)` con el filtro `nuevoIngresoAuth:3`.
6. Paso 6: El método comprueba que el método HTTP sea GET; si no, responde 405 con un mensaje en español.
7. Paso 7: El método ejecuta `sesionValida()` como defensa adicional al filtro. Si la sesión no es válida, devuelve la respuesta de error correspondiente.
8. Paso 8: El método valida que `$id` sea numérico y positivo; si no, responde 422.
9. Paso 9: El método resuelve el contexto con `Services::nuevoIngresoContext()->resolver()` y obtiene el `niId` de la postulación; si no hay postulación, responde 422.
10. Paso 10: El método llama a `Services::nuevoIngresoActaCompromiso()->generar((int) $id, $niId)`.
11. Paso 11: El servicio valida que la intención exista y pertenezca a la postulación con `NuevoIngresoPagoService::obtenerIntencion($intencionId, $niInscripcionId)`. Si es nula o ajena, lanza `porIntencionNoEncontrada()`.
12. Paso 12: El servicio valida con `estaAprobada()` que la intención esté en estado 3 u 8. Si no, lanza `porPagoNoAprobado()`.
13. Paso 13: El servicio carga la postulación con `NiInscripcionModel::find($niInscripcionId)`. Si no existe, lanza `porPostulacionNoEncontrada()`.
14. Paso 14: El servicio arma los datos del acta: nombre completo, cédula con prefijo `V-` o `E-`, fecha de aceptación con formato `dd/mm/aaaa` y el texto del acta.
15. Paso 15: El servicio renderiza `app/Views/inscripciones/nuevo_ingreso/pdf/acta_compromiso.php` con esos datos.
16. Paso 16: El servicio genera el PDF con `Services::htmlPdfBuilder()->generar($html, new PdfOptions('letter', 'portrait', true, true))`.
17. Paso 17: El servicio devuelve `['pdf' => $binario, 'nombre_archivo' => 'ActaCompromisoNI' . $niInscripcionId . '.pdf']`.
18. Paso 18: El controlador responde con `Content-Type: application/pdf`, `Content-Disposition: attachment; filename="ActaCompromisoNI{niId}.pdf"` y `Cache-Control: private, no-store`, y escribe el binario en el cuerpo.
19. Paso 19: El navegador descarga el archivo. No se escribe en base de datos, no se modifica la postulación y no se consume ningún intento de correo.

### Envío en el correo de inscripción culminada

1. Paso 1: El pago se aprueba por pasarela no Zelle (estado 3) o se verifica por Zelle (estado 8).
2. Paso 2: El flujo de aprobación llama a `NuevoIngresoAprobacionNotificacionService::notificar($intencionId, $niId)`, como ya ocurre en FEAT-011.
3. Paso 3: El servicio valida la intención, el estado aprobado y reserva el intento de forma atómica en `ni_inscripciones`.
4. Paso 4: El servicio carga la postulación y valida el correo del aspirante.
5. Paso 5: El servicio genera el recibo con `NuevoIngresoReciboService::generar()`.
6. Paso 6: El servicio genera la planilla con `NuevoIngresoPlanillaService::generar()`.
7. Paso 7: El servicio genera el acta con `NuevoIngresoActaCompromisoService::generar()` usando la misma intención y postulación.
8. Paso 8: Si cualquiera de los tres PDF queda vacío, el servicio marca el intento como `fallido` con el motivo `pdf_vacio`, registra el error y no envía el correo.
9. Paso 9: El servicio renderiza la plantilla del correo con el nombre, los documentos presenciales, el plazo y la URL del Paso 4. La plantilla menciona el acta como adjunto.
10. Paso 10: El servicio arma tres adjuntos: `ReciboNI{intencionId}.pdf`, `PlanillaNI{niId}.pdf` y `ActaCompromisoNI{niId}.pdf`.
11. Paso 11: El remitente envía el correo con los tres adjuntos y el texto alternativo actualizado.
12. Paso 12: Si el envío es exitoso, el estado queda `enviado`. Si falla, queda `fallido` y puede reenviarse con el comando `ni:reenviar-correo-aprobacion` de FEAT-011.
13. Paso 13: El acta adjunta muestra la fecha de generación del correo; una descarga posterior desde el Paso 4 puede mostrar una fecha distinta. Es el comportamiento aceptado al no persistir la aceptación.

## Flujos alternativos / variantes

### Pago Zelle verificado (estado 8)

1. Paso 1: El administrador verifica el reporte Zelle y la intención pasa a estado 8.
2. Paso 2: `ZelleReportManager` envía el aviso Zelle actual, sin cambios.
3. Paso 3: Después del aviso, el notificador de FEAT-011 genera recibo, planilla y acta.
4. Paso 4: El correo de inscripción culminada sale con los tres adjuntos.
5. Paso 5: El botón del Paso 4 también permite descargar el acta, porque el estado 8 se considera aprobado.

### Pago pendiente de verificación (estado 7)

1. Paso 1: El aspirante reporta un pago Zelle y la intención queda en estado 7.
2. Paso 2: `estaAprobada()` devuelve falso.
3. Paso 3: No se genera el acta para el correo. El botón del Paso 4 no se muestra porque la pantalla final aún no corresponde.
4. Paso 4: El acta se generará cuando el pago se verifique.

### Intención ajena, inexistente o no aprobada

1. Paso 1: Se solicita el acta con un id de intención de otra postulación o con un estado no aprobado.
2. Paso 2: El servicio no encuentra la intención en la postulación o `estaAprobada()` devuelve falso.
3. Paso 3: Lanza `porIntencionNoEncontrada()` o `porPagoNoAprobado()`.
4. Paso 4: El controlador responde 422 con un mensaje en español y no genera el PDF.

### Postulación existente sin fecha de aceptación

1. Paso 1: La postulación fue aprobada antes de este cambio y no tiene ningún registro de aceptación.
2. Paso 2: El servicio no consulta columnas de aceptación.
3. Paso 3: Usa la fecha de generación como "Fecha de aceptación" y genera el acta normalmente.
4. Paso 4: No se bloquea la descarga ni el correo.

### Descargas repetidas en fechas distintas

1. Paso 1: El aspirante descarga el acta el 4 de noviembre.
2. Paso 2: El PDF muestra "Fecha de aceptación: 04/11/2026".
3. Paso 3: El aspirante descarga el acta el 10 de noviembre.
4. Paso 4: El nuevo PDF muestra "Fecha de aceptación: 10/11/2026". No hay caché ni almacenamiento del PDF anterior.
5. Paso 5: Es el comportamiento aceptado; la firma manuscrita es la evidencia física.

### Sesión ausente o paso insuficiente

1. Paso 1: Se solicita la ruta del acta sin sesión `nuevo_ingreso` o con `paso_actual` menor que 3.
2. Paso 2: El filtro `nuevoIngresoAuth:3` redirige al paso correspondiente o responde 401/403 si la petición es AJAX/JSON.
3. Paso 3: El método no se ejecuta.
4. Paso 4: No se genera ningún PDF.

### Acta impresa y firmada

1. Paso 1: El aspirante descarga el PDF.
2. Paso 2: El documento muestra el texto del acta, sus datos, la fecha de aceptación y un espacio de firma.
3. Paso 3: El aspirante imprime, firma manuscritamente y entrega el acta en la sede.
4. Paso 4: El sistema no registra la firma ni la entrega; eso queda fuera del alcance.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Método HTTP distinto de GET | `strtoupper($this->request->getMethod()) !== 'GET'` | Responde 405 con mensaje en español | Sin PDF |
| Sesión ausente | Filtro `nuevoIngresoAuth:3` o `sesionValida()` | Redirección, 401 o 403 según el tipo de petición | Sin PDF |
| `paso_actual` menor que 3 | Filtro `nuevoIngresoAuth:3` | Redirige al paso correspondiente | Sin PDF |
| Id no numérico o menor o igual a cero | Validación local | Responde 422 con mensaje en español | Sin PDF |
| Postulación no resuelta | `niId <= 0` | Responde 422 con mensaje en español | Sin PDF |
| Intención inexistente o ajena | `obtenerIntencion()` devuelve `null` | Lanza `porIntencionNoEncontrada()`; el controlador responde 422 | Sin PDF |
| Pago no aprobado (estado distinto de 3 u 8) | `estaAprobada()` devuelve falso | Lanza `porPagoNoAprobado()`; el controlador responde 422 | Sin PDF |
| Postulación no encontrada | `find()` no devuelve arreglo | Lanza `porPostulacionNoEncontrada()`; el controlador responde 422 | Sin PDF |
| Error al renderizar la vista del acta | Excepción de `view()` | Lanza `porErrorGeneracion()`; el controlador responde 500 y registra el detalle | Sin PDF |
| Dompdf no disponible o error de generación | `HtmlPdfBuilder` lanza `PdfGenerationException` | El controlador responde 500, registra el detalle y no expone información interna | Sin PDF |
| Fallo del acta durante el correo | Excepción o PDF vacío en `componerYEnviar()` | Marca el intento como `fallido`; no envía un correo incompleto | `fallido`; sin correo |
| Fallo del recibo o la planilla durante el correo | Excepción o PDF vacío | Igual que FEAT-011: marca `fallido` y no envía | `fallido`; sin correo |
| Reenvío de un correo fallido | Comando manual de FEAT-011 | Vuelve a generar los tres PDFs y reenvía solo si la intención sigue aprobada | `enviado` o `fallido` |
| Acta solicitada con pago en estado 7 | `estaAprobada()` devuelve falso | Responde 422; no genera el acta | Sin PDF |
| Pago ya aprobado antes del despliegue | No hay fecha de aceptación persistida | Genera el acta con la fecha de generación | PDF válido |
| Descarga repetida | Nueva petición GET | Genera un PDF nuevo con la fecha actual; no usa caché | PDF válido |

## Reglas de negocio y validaciones

- El acta solo se genera para una intención propia de la postulación y en estado 3 (aprobado) u 8 (verificado). Cualquier otro estado se rechaza con 422.
- La identidad del aspirante sale de `ni_inscripciones` vinculada a la sesión `nuevo_ingreso`; no se aceptan nombre, cédula, carrera ni sede enviados por el cliente.
- El PDF debe reproducir el texto del modal del Paso 0 sin cambios de redacción:
  - Párrafo introductorio sobre el deber de la comunidad UNIR.
  - Título "Me comprometo a:" con las dos viñetas de prohibiciones.
  - Título "Por lo cual acepto:" con el párrafo de aceptación de sanciones.
- El PDF debe incluir:
  - Encabezado institucional con el logo y el título "Acta de Compromiso".
  - Nombre completo del aspirante.
  - Cédula con prefijo `V-` o `E-`, según `identificacion_tipo`.
  - "Fecha de aceptación" con la fecha de generación en formato `dd/mm/aaaa`.
  - Un espacio de firma manuscrita para el aspirante, con su nombre y cédula.
- El PDF no debe incluir montos, referencias de pago, tasas, planes, descuentos, carrera, sede, turno ni modalidad, salvo que se decida agregarlos en una iteración futura. La entrevista solo pidió nombre, cédula y fechas.
- La fecha impresa es la fecha de generación; no se persiste ni se recupera del Paso 0. No se debe presentar como un sello de tiempo ni como evidencia de aceptación histórica.
- El nombre del archivo es `ActaCompromisoNI{niId}.pdf`. No se almacena en `writable/` ni en `public/`.
- El endpoint es GET, de solo lectura, y no requiere CSRF. No escribe en base de datos ni consume el intento de correo.
- La descarga usa `Content-Disposition: attachment` para forzar la descarga, igual que la planilla. No se usa `inline`.
- La respuesta lleva `Cache-Control: private, no-store` para evitar que un PDF con datos personales quede en caché compartida.
- El botón del Paso 4 se muestra solo si `$estaAprobada` es verdadero y existe un id de intención válido. No se muestra para pagos pendientes, cancelados o sin intención.
- El botón se coloca junto al de planilla, con el mismo estilo y comportamiento de descarga; en pantallas pequeñas ambos botones deben envolverse sin romper el diseño.
- El correo de inscripción culminada adjunta exactamente tres PDFs: recibo, planilla y acta. No se adjunta el acta al aviso Zelle existente.
- Si el acta no se genera o queda vacía, el correo no se envía y el intento queda `fallido`. Se mantiene la regla de "todo o nada" de FEAT-011.
- El texto del correo debe mencionar el acta como adjunto, además del recibo y la planilla. El texto alternativo debe incluir la misma mención.
- El asunto del correo no cambia: `Tu inscripción en UNIR ha culminado`.
- El cuerpo del correo sigue sin mostrar montos, referencias, tasas, planes, descuentos, carrera ni sede.
- El acta se genera en español, con el mismo diseño institucional y el logo de las plantillas existentes.
- La duplicación del texto es una decisión explícita. Si en el futuro cambia el modal del Paso 0, la vista del PDF debe actualizarse en el mismo cambio; se registra como riesgo de mantenimiento.
- No se agregan columnas a `ni_inscripciones` ni se modifica `NiInscripcionModel::$allowedFields`.
- No se modifican las rutas, filtros o flujos existentes de recibo, planilla, pago, Zelle o correo, salvo los enganches descritos.
- La fecha se toma con `date('d/m/Y')` en la zona horaria configurada de la aplicación (`America/Chicago`). Queda como supuesto; si el negocio exige `America/Caracas`, se ajusta antes de implementar.

## Contratos y diseño propuesto

### `NuevoIngresoActaCompromisoService`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoService.php`.

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `generar(int $intencionId, int $niInscripcionId): array` | Validar intención propia y aprobada, cargar la postulación, armar los datos, renderizar la vista y generar el PDF. | Solo lectura; devuelve `['pdf' => string, 'nombre_archivo' => string]`. |

- Dependencias inyectables:
  - `NiInscripcionModel`.
  - `NuevoIngresoPagoService`.
  - `HtmlPdfBuilder`.
- Flujo interno:
  1. Obtener la intención con `obtenerIntencion($intencionId, $niInscripcionId)`.
  2. Rechazar si es nula.
  3. Rechazar si `estaAprobada()` es falso.
  4. Cargar la postulación.
  5. Armar los datos del acta.
  6. Renderizar la vista.
  7. Generar el PDF con `PdfOptions('letter', 'portrait', true, true)`.
  8. Devolver el binario y el nombre del archivo.
- No conoce sesión, rutas, controladores, correo ni correo Zelle.
- No escribe en base de datos.

### `NuevoIngresoActaCompromisoException`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoException.php`.

- Métodos estáticos propuestos:
  - `porIntencionNoEncontrada(): self`.
  - `porPagoNoAprobado(): self`.
  - `porPostulacionNoEncontrada(): self`.
  - `porErrorGeneracion(\Throwable $anterior): self`.
- Mensajes en español, sin detalles internos.
- Sigue el patrón de `NuevoIngresoReciboException` y `NuevoIngresoPlanillaException`.

### Vista del PDF

Ubicación: `app/Views/inscripciones/nuevo_ingreso/pdf/acta_compromiso.php`.

- Variables: `$nombre`, `$cedula`, `$fecha_aceptacion`.
- Estructura propuesta:
  1. Encabezado con logo institucional (`base_url('imagenes/logo.jpg')`) y título "ACTA DE COMPROMISO".
  2. Bloque de datos: nombre, cédula y "Fecha de aceptación".
  3. Párrafo introductorio idéntico al del modal.
  4. Título "Me comprometo a:" con las dos viñetas idénticas.
  5. Título "Por lo cual acepto:" con el párrafo idéntico.
  6. Leyenda "He leído atentamente y acepto los términos de esta Acta de Compromiso."
  7. Espacio de firma manuscrita con línea, nombre y cédula.
  8. Pie institucional.
- Todo el HTML debe estar preparado para Dompdf; evitar recursos remotos si no son necesarios.
- Toda salida dinámica se escapa con `esc()`.

### `Paso3::acta()`

Ubicación: `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php`, junto a `planilla()`.

- Firma: `public function acta($id = 0)`.
- Reglas:
  - Solo GET; otro método responde 405.
  - `sesionValida()` como defensa adicional al filtro.
  - `$id` numérico y positivo; si no, 422.
  - Resolver el contexto y obtener `niId`; si no hay postulación, 422.
  - Llamar a `Services::nuevoIngresoActaCompromiso()->generar((int) $id, $niId)`.
  - Responder `application/pdf`, `attachment`, `Cache-Control: private, no-store`.
  - Capturar `NuevoIngresoContextException | NuevoIngresoActaCompromisoException` y responder 422 con el mensaje de dominio.
  - Capturar `\Throwable` y responder 500 con un mensaje genérico, registrando el detalle en el log.

### Ruta

Ubicación: `app/Config/Routes.php`, dentro del grupo `inscripciones/nuevo-ingreso`.

```php
$routes->get('paso-4/acta/(:num)', 'Paso3::acta/$1', ['filter' => 'nuevoIngresoAuth:3']);
```

- Se coloca junto a `paso-4/recibo/(:num)` y `paso-4/planilla/(:num)`.
- Se usa el mismo filtro `nuevoIngresoAuth:3` que la planilla; el filtro permite el paso 4 porque valida `paso_actual >= 3`.
- El endpoint queda disponible para un aspirante con `paso_actual >= 3`, pero el servicio solo genera el acta si la intención está en estado 3 u 8. El botón solo se muestra en la pantalla final (Paso 4).
- No se crea una ruta en el grupo de API ni una ruta administrativa.

### Vista final (Paso 4)

Ubicación: `app/Views/inscripciones/nuevo_ingreso/paso4/index.php`.

- `Paso4::index()` debe pasar `'pagoAprobado' => $estaAprobada` a la vista.
- La vista debe calcular:
  - `$planillaUrl` como hoy.
  - `$actaUrl = base_url('inscripciones/nuevo-ingreso/paso-4/acta/' . (int) $intencion['id'])` cuando `$pagoAprobado` y el id sean válidos.
- El bloque de botones debe mostrar el botón de planilla y el de acta en el mismo contenedor flexible, con `target="_blank"` y `rel="noopener"` para el acta, igual que la planilla.
- El botón del acta usa el texto "Descargar acta de compromiso" y un icono institucional coherente (por ejemplo, `verified_user`).
- Si `$pagoAprobado` es falso o no hay intención, no se muestra el botón del acta.

### Correo de inscripción culminada

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionService.php` y `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php`.

- El constructor del servicio agrega `NuevoIngresoActaCompromisoService $actaService` como dependencia.
- En `componerYEnviar()`, después de generar recibo y planilla:
  - `$acta = $this->actaService->generar($intencionId, $niInscripcionId);`
  - `$pdfActa = (string) ($acta['pdf'] ?? '');`
- La validación de PDFs vacíos incluye `$pdfActa === ''` y mantiene el motivo `pdf_vacio`.
- El arreglo `$adjuntos` agrega:
  - `['nombre' => (string) ($acta['nombre_archivo'] ?? 'ActaCompromisoNI' . $niInscripcionId . '.pdf'), 'contenido' => $pdfActa]`.
- El texto alternativo (`ALT_BODY`) cambia a una frase que mencione recibo, planilla y acta.
- La plantilla cambia la frase "Adjuntamos tu recibo y tu planilla en formato PDF" por una que incluya el acta de compromiso.
- No se agrega un enlace de descarga del acta en el correo; la decisión es adjuntarla.
- No se modifica el asunto ni el diseño general de la plantilla.

### `Services`

Ubicación: `app/Config/Services.php`.

- Agregar imports de `NuevoIngresoActaCompromisoService` y `NuevoIngresoActaCompromisoException` si aplica.
- Agregar `public static $nuevoIngresoActaCompromisoInstance = null;`.
- Agregar `nuevoIngresoActaCompromiso($getShared = true)` que construya el servicio con:
  - `new NiInscripcionModel(Database::connect())`.
  - `self::nuevoIngresoPago()`.
  - `self::htmlPdfBuilder()`.
- Actualizar `nuevoIngresoAprobacionNotificacion()` para inyectar `self::nuevoIngresoActaCompromiso()`.
- Las pruebas deben reiniciar `$nuevoIngresoActaCompromisoInstance` y `$nuevoIngresoAprobacionNotificacionInstance` en `setUp`/`tearDown`.

### Pruebas previstas

- `tests/app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoServiceTest.php`:
  - Genera el PDF para pago no Zelle aprobado (estado 3).
  - Genera el PDF para Zelle verificado (estado 8).
  - Rechaza intención ajena, inexistente y no aprobada.
  - Rechaza postulación inexistente.
  - Verifica el nombre del archivo y el contenido PDF no vacío.
  - Verifica que el HTML renderizado contiene el párrafo introductorio, las dos viñetas y el párrafo de sanciones.
  - Verifica que el HTML incluye nombre, cédula y fecha con formato `dd/mm/aaaa`.
  - Verifica que no escribe en base de datos.
- `tests/app/Integration/Paso4ActaCompromisoTest.php`:
  - Descarga correcta con cabeceras `application/pdf`, `attachment` y `private, no-store`.
  - 405 para POST.
  - 422 para id inválido, intención ajena y pago no aprobado.
  - 500 cuando el builder falla.
  - El botón aparece solo con pago aprobado.
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionServiceTest.php`:
  - El correo incluye tres adjuntos.
  - El nombre del tercer adjunto es `ActaCompromisoNI{niId}.pdf`.
  - Si el acta falla o queda vacía, no se envía el correo y el estado queda `fallido`.
  - El texto alternativo menciona el acta.
- `tests/app/Integration/Paso4FinalizadoDocumentosTest.php` o `Paso4NuevoIngresoTest.php`:
  - La vista final muestra el botón del acta cuando el pago está aprobado.
  - No lo muestra cuando no hay pago aprobado.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoService.php` | Generación del PDF del acta. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoException.php` | Errores de dominio del acta. |
| Crear | `app/Views/inscripciones/nuevo_ingreso/pdf/acta_compromiso.php` | Vista HTML del PDF con el texto duplicado del Paso 0. |
| Modificar | `app/Config/Services.php` | Registro del servicio y dependencia del notificador. |
| Modificar | `app/Config/Routes.php` | Ruta GET de descarga del acta. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Método `acta()` de descarga. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso4.php` | Pasar `$estaAprobada` a la vista final. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso4/index.php` | Botón de descarga junto al de planilla. |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionService.php` | Generar y adjuntar el acta; texto alternativo. |
| Modificar | `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php` | Mencionar el acta adjunta. |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Acta/NuevoIngresoActaCompromisoServiceTest.php` | Pruebas del servicio. |
| Crear | `tests/app/Integration/Paso4ActaCompromisoTest.php` | Pruebas del endpoint y del botón. |
| Modificar | `tests/app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionServiceTest.php` | Tercer adjunto y "todo o nada". |
| Modificar | `tests/app/Integration/Paso4FinalizadoDocumentosTest.php` o `Paso4NuevoIngresoTest.php` | Visibilidad del botón. |
| Documentar | `docs/features/022-acta-compromiso-pdf-paso4-correo/plan.md` | Este plan. |

No se modifican `Paso0`, el modal del acta, `NiInscripcionModel`, las migraciones, `NuevoIngresoReciboService`, `NuevoIngresoPlanillaService`, `NuevoIngresoPagoService`, `PaymentOrchestrator`, `ZelleReportManager`, la SPA ni la API. No se agregan dependencias ni cambios en `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

## Criterios de finalización

- [ ] Existe `NuevoIngresoActaCompromisoService::generar()` y devuelve `['pdf' => string, 'nombre_archivo' => 'ActaCompromisoNI{niId}.pdf']`.
- [ ] El servicio rechaza intenciones inexistentes, ajenas o no aprobadas con las excepciones de dominio correspondientes.
- [ ] El servicio acepta estados 3 y 8 y rechaza cualquier otro estado.
- [ ] El PDF contiene el párrafo introductorio, las dos viñetas de "Me comprometo a:" y el párrafo de "Por lo cual acepto:" con el mismo texto del modal del Paso 0.
- [ ] El PDF muestra el nombre completo y la cédula con prefijo `V-` o `E-`.
- [ ] El PDF muestra "Fecha de aceptación" con formato `dd/mm/aaaa` y el valor de la fecha de generación.
- [ ] El PDF incluye un espacio de firma manuscrita con nombre y cédula.
- [ ] El PDF no incluye montos, referencias, tasas, planes, descuentos, carrera, sede, turno ni modalidad.
- [ ] El PDF se genera con `PdfOptions('letter', 'portrait', true, true)` y no se almacena en disco.
- [ ] La ruta `GET /inscripciones/nuevo-ingreso/paso-4/acta/(:num)` existe con el filtro `nuevoIngresoAuth:3`.
- [ ] `Paso3::acta()` responde 405 a métodos distintos de GET.
- [ ] `Paso3::acta()` responde 422 a id inválido, postulación no resuelta, intención ajena o pago no aprobado.
- [ ] `Paso3::acta()` responde 500 ante un fallo de Dompdf o de renderizado, sin exponer detalles internos.
- [ ] La respuesta de descarga usa `Content-Type: application/pdf`, `Content-Disposition: attachment` y `Cache-Control: private, no-store`.
- [ ] La vista final muestra el botón "Descargar acta de compromiso" junto al de planilla cuando el pago está aprobado.
- [ ] La vista final no muestra el botón del acta cuando el pago no está aprobado o no hay intención.
- [ ] El correo de inscripción culminada adjunta `ReciboNI{intencionId}.pdf`, `PlanillaNI{niId}.pdf` y `ActaCompromisoNI{niId}.pdf`.
- [ ] El cuerpo del correo y el texto alternativo mencionan el acta como adjunta.
- [ ] Si el acta no se genera o queda vacía, el correo no se envía y el intento queda `fallido` con el motivo `pdf_vacio`.
- [ ] El aviso Zelle existente de "Pago verificado" no se modifica ni recibe el acta.
- [ ] El asunto del correo sigue siendo `Tu inscripción en UNIR ha culminado`.
- [ ] No se agregaron columnas, migraciones, seeds ni cambios en `NiInscripcionModel::$allowedFields`.
- [ ] No se modificó el modal del Paso 0, su texto, su checkbox ni el flujo OTP.
- [ ] No se agregaron dependencias ni cambios en `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.
- [ ] Las pruebas del servicio, del endpoint, del botón y del notificador pasan.
- [ ] Las pruebas existentes de FEAT-007, FEAT-009, FEAT-010 y FEAT-011 siguen pasando.
- [ ] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [ ] `graphify update .` se ejecuta después de los cambios de código.
- [ ] Se ejecuta un smoke test manual con un pago aprobado no Zelle y otro con Zelle, verificando el botón, la descarga, los tres adjuntos y la regla de "todo o nada".

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Contenido del acta | Reutilizar exactamente el texto del modal del Paso 0. |
| Datos del aspirante | Nombre y cédula; fecha de aceptación con el valor de la fecha de emisión/generación. |
| Firma | Espacio para firma manuscrita del aspirante. |
| Entrega en Paso 4 | Botón junto al de planilla, solo con pago aprobado. |
| Entrega en el correo | Adjuntar el PDF como tercer adjunto y mencionarlo en el cuerpo. |
| Fecha de aceptación | Usar la fecha de emisión/generación porque no se persiste la aceptación. |
| Persistencia de la aceptación | No persistir fecha, IP, user agent, versión ni hash. |
| Postulaciones antiguas | No bloquear: generar el acta con la fecha de generación. |
| Sincronización del texto | Duplicar el texto en la vista del PDF, sin extraer parcial compartida. |
| Condición de descarga | Solo intención propia en estado 3 u 8. |
| Rotulación de fechas | Mostrar solo "Fecha de aceptación" con la fecha de generación. |
| Fallo del acta en el correo | Todo o nada: no enviar el correo y marcarlo `fallido`. |
| Aviso Zelle | No modificarlo; el acta solo se agrega al correo de inscripción culminada. |
| Comportamiento del botón | Descargar el archivo (`attachment`), igual que la planilla. |
| División del alcance | No se recomienda dividir; es una sola capacidad con tres fases internas. |

## Riesgos y deuda técnica

- **Fecha de aceptación no verificable:** al no persistir la aceptación, la fecha impresa es la de generación. No sirve como evidencia histórica ni como sello de tiempo. La evidencia prevista es la firma manuscrita.
- **Fechas distintas entre descargas:** el acta del correo y una descarga posterior pueden mostrar fechas diferentes. Es una consecuencia directa de la decisión de no persistir.
- **Texto duplicado:** el modal del Paso 0 y la vista del PDF pueden divergir si se edita uno sin el otro. Se acepta el riesgo; una mejora futura sería extraer una vista parcial o configuración compartida.
- **Dependencia de Dompdf:** si `public/dompdf/` no está disponible, el acta no se genera y el correo queda `fallido` por la regla de "todo o nada".
- **Sin auditoría de descargas:** no se registra quién descargó el acta ni cuándo. No está en el alcance.
- **Sin firma electrónica:** el documento no tiene validez criptográfica; se apoya en la impresión y firma manuscrita.
- **Zona horaria:** la fecha se toma en `America/Chicago` por configuración de la app. Si el negocio requiere `America/Caracas`, debe ajustarse antes de implementar; no se debe cambiar a ciegas.
- **Compatibilidad con FEAT-011:** el cambio de constructor del notificador obliga a actualizar sus pruebas y cualquier doble de prueba que lo instancie. Debe hacerse en la misma fase.
- **Botón en Paso 4:** actualmente la vista muestra la planilla con solo validar `$intencion['id']`; el acta debe usar explícitamente `$estaAprobada` para no ofrecer una descarga que el servicio rechazará.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-11-04 | Creación del plan FEAT-022 a partir de la entrevista. Sin implementación. | opencode (agente) |
| 2026-11-04 | Implementación de las fases A, B y C con pruebas automatizadas en verde. Pendiente el smoke test manual con pagos reales. | opencode (agente) |
