# Correo de inscripción culminada con recibo, planilla y documentos pendientes

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

## Objetivo

Enviar al aspirante un correo cuando su pago de nuevo ingreso quede aprobado o verificado, con el mismo feedback que muestra el Paso 4 al finalizar la inscripción: la planilla de inscripción en PDF, el recibo en PDF y la lista de documentos pendientes para entrega presencial, con su fecha límite. El correo se envía una sola vez por postulación y no se reenvía automáticamente, aunque el pago vuelva a consultarse o el aspirante recargue la pantalla. Si el envío falla, un comando `spark` permite reenviar únicamente los correos que quedaron en estado `fallido`.

## Alcance

- **Incluye:**
  - Agregar a `ni_inscripciones` los campos de control del correo: estado del envío, fecha del intento y mensaje de error resumido.
  - Crear una migración idempotente y registrarla en `init:principal`.
  - Crear un servicio de notificación que:
    - Valide que la intención sea propia de la postulación y esté en estado 3 u 8.
    - Reserve el intento de envío de forma atómica para garantizar "una sola vez por postulación".
    - Genere el recibo y la planilla con los servicios existentes de FEAT-007 y FEAT-009.
    - Resuelva los documentos presenciales aplicables con `NiDocumentoPresencialModel` y la fecha límite con `CalculadoraPlazoEntrega` (FEAT-010).
    - Renderice y envíe un correo HTML con ambos PDF adjuntos, la lista de documentos y un botón al Paso 4.
    - Registre el resultado (`enviado` o `fallido`) sin exponer datos personales en el log.
  - Crear el comando `ni:reenviar-correo-aprobacion` para reenviar manualmente los correos en estado `fallido` de postulaciones aprobadas.
  - Crear el contrato y la implementación del remitente basado en `Services::phpMailer()`.
  - Crear la plantilla `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php`.
  - Enganchar el envío en los dos puntos reales de aprobación:
    - Pago en línea no Zelle aprobado desde `Paso3::postPago()`.
    - Pago Zelle verificado desde `ZelleReportManager::verificar()`.
  - Mantener el correo Zelle actual de "Pago verificado" y enviar además el nuevo correo con adjuntos. Son dos correos distintos; la decisión es explícita.
  - Cubrir con pruebas la migración, el servicio, los estados de idempotencia, los adjuntos, la lista de documentos, la fecha límite, los fallos, los enganches de aprobación y el comando de reenvío.

- **No incluye:**
  - Crear rutas, controladores, endpoints o pantallas nuevas.
  - Crear una cola de correos, un worker o un cron. El envío es síncrono y best-effort; el reenvío de fallidos es manual con un comando `spark`.
  - Reintentar automáticamente cuando falle el SMTP, Dompdf o el correo del aspirante. El intento queda como `fallido` y solo se reenvía al ejecutar el comando manual.
  - Enviar correos a postulaciones que ya estaban aprobadas antes del despliegue. Solo se notifican las aprobaciones que ocurran después; el comando no procesa `pendiente`.
  - Modificar el correo Zelle actual, su plantilla, sus destinatarios o su auditoría. Se conserva tal cual.
  - Modificar el diseño, el contenido o las rutas del recibo y de la planilla existentes.
  - Incluir monto, referencia, tasa, plan, descuento, carrera o sede en el cuerpo del correo. Esos datos permanecen en los PDF adjuntos cuando correspondan.
  - Registrar qué documentos entregó el estudiante, marcar documentos recibidos o cambiar el catálogo de FEAT-010.
  - Agregar copias (CC/BCC), destinatarios administrativos, programación de envíos ni reintentos automáticos. El reenvío manual se limita al comando indicado.
  - Agregar dependencias, CSRF, migraciones de sucursal o cambios en `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.
  - Modificar `NuevoIngresoReciboService`, `NuevoIngresoPlanillaService`, `CalculadoraPlazoEntrega`, `NiDocumentoPresencialModel` ni sus pruebas, salvo consumirlos.

> **Evaluación de alcance:** la petición es una sola capacidad de negocio: notificar por correo la culminación de la inscripción con los documentos que ya existen y permitir recuperar manualmente los envíos fallidos. La migración, el servicio, la plantilla, el comando y los dos enganches de aprobación no aportan valor por separado; por eso se mantiene un único documento con cuatro fases internas. No se recomienda dividirla en features independientes.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`.
- FEAT-007 ya implementa `NuevoIngresoReciboService::generar($intencionId, $niInscripcionId)` y devuelve `['pdf' => ..., 'nombre_archivo' => 'ReciboNI{id}.pdf']`.
- FEAT-009 ya implementa `NuevoIngresoPlanillaService::generar($intencionId, $niInscripcionId)` y devuelve `['pdf' => ..., 'nombre_archivo' => 'PlanillaNI{niId}.pdf']`.
- FEAT-010 ya implementa `NiDocumentoPresencialModel::obtenerParaCarrera($carreraId)` y `CalculadoraPlazoEntrega::calcular($intencion)`. La tabla `ni_documentos_presenciales` y su relación con carreras existen en la rama.
- `Paso3::postPago()` procesa los pagos en línea no Zelle. Si la pasarela confirma, `PaymentOrchestrator` actualiza la intención al estado 3. Zelle deja la intención en 7 y se verifica después desde el panel administrativo.
- `ZelleReportManager::verificar()` actualiza la intención al estado 8, sincroniza GHL y envía el correo Zelle actual. El nuevo correo se envía después de ese aviso, sin reemplazarlo.
- `NuevoIngresoPagoService::procesarPago()` devuelve de forma idempotente si la intención ya está aprobada (3/8) o pendiente de verificación (7). Ese comportamiento permite evitar correos históricos.
- `NuevoIngresoPagoService::estaAprobada()` reconoce los estados 3 y 8. `estadoDeIntencion()` los presenta como `aprobado`.
- La identidad, el correo y la carrera del aspirante salen de `ni_inscripciones`; no se aceptan datos del cliente.
- El correo del aspirante es `ni_inscripciones.correo`. Se asume que es la dirección correcta y que ya fue validada en el Paso 0. Si se corrige en la postulación, el comando de reenvío puede volver a intentarlo.
- El comando de reenvío se ejecuta manualmente por un operador con acceso a CLI. No se programa en cron ni se expone por HTTP.
- La carrera para filtrar documentos sale de `ni_inscripciones.sucursal_carrera_id` → `es_sucursales_carreras.carrera_id`. No se usa la sesión `nuevo_ingreso`, porque el correo también se envía desde la verificación administrativa de Zelle.
- La fecha límite se calcula con la misma clase y la misma intención que usa el Paso 4, para que el correo y la pantalla coincidan.
- `Services::phpMailer(false)` crea una instancia nueva de PHPMailer y evita arrastrar destinatarios del correo Zelle anterior.
- `public/dompdf/` sigue siendo una dependencia de facto del proyecto, igual que para el recibo y la planilla. Si no está disponible, no se envía el correo y se registra el fallo.
- El proyecto usa el esquema `FEAT-NNN` y carpetas `NNN-slug`. El siguiente número libre es `FEAT-011`; no colisiona con FEAT-001 a FEAT-010.
- La zona horaria de la aplicación es `America/Chicago`; la calculadora de plazo usa `America/Caracas`, igual que FEAT-010.
- El correo se envía en español, con el diseño y el logo de las plantillas existentes.

## Fases internas de implementación

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

1. **Fase A - Datos e idempotencia:** crear la migración de los campos de control y registrarla en `InitPrincipalDb`. Al finalizar, una base inicializada tiene los campos y la migración se puede ejecutar dos veces sin error.
2. **Fase B - Servicio, remitente y plantilla:** crear el contrato del remitente, la implementación PHPMailer, el servicio de notificación, la plantilla HTML y el registro en `Services`. Cubrir con pruebas el envío, los adjuntos, los documentos, la fecha límite, la idempotencia y los fallos. Esta fase no engancha todavía la aprobación.
3. **Fase C - Enganches de aprobación:** invocar el servicio desde `Paso3::postPago()` cuando un pago no Zelle pase a estado 3, y desde `ZelleReportManager::verificar()` cuando un pago Zelle pase a estado 8. Cubrir con pruebas de integración que se envía una sola vez y que no se envía en rechazos, reintentos ni aprobaciones históricas.
4. **Fase D - Comando de reenvío:** crear `ni:reenviar-correo-aprobacion`, que selecciona postulaciones en `fallido`, resuelve su intención aprobada y llama a `reenviar()`. Cubrir con pruebas el filtrado, `--dry-run`, `--id`, `--limit`, el resumen y los casos sin intención aprobada.

## Flujo normal

1. Paso 1: El aspirante completa el pago de nuevo ingreso por una pasarela no Zelle.
2. Paso 2: `Paso3::postPago()` valida sesión, paso, id y contexto, y lee la intención propia antes de procesar para conocer su estado previo.
3. Paso 3: `NuevoIngresoPagoService::procesarPago()` valida que la intención esté en estado 2 (`pagando`), que la forma de pago siga permitida y que la sede coincida.
4. Paso 4: `PaymentOrchestrator::procesar()` despacha la pasarela y, si la pasarela confirma, `IntencionesPagoModel::actualizaStatus()` deja la intención en estado 3 y actualiza `actualizado_dt` por el timestamp del modelo.
5. Paso 5: `postPago()` recibe `estatus = success`. Si el estado previo era 2, vuelve a leer la intención y comprueba con `estaAprobada()` que el estado actual sea 3.
6. Paso 6: Si la intención quedó aprobada, `postPago()` llama a `Services::nuevoIngresoAprobacionNotificacion()->notificar($intencionId, $niId)` dentro de un `try/catch`. Un fallo del correo no cambia la respuesta del pago.
7. Paso 7: El servicio de notificación valida que la intención exista, pertenezca a la postulación y esté en estado 3 u 8. Si no cumple, no reserva el intento y devuelve `false`.
8. Paso 8: El servicio reserva el envío con una actualización atómica en `ni_inscripciones`: solo pasa de `correo_aprobacion_estado = 'pendiente'` a `'intentando'` si la fila sigue pendiente. Si otra ejecución ya lo reservó, no envía.
9. Paso 9: El servicio carga la postulación y valida que `correo` exista y tenga formato válido. Si no, marca `fallido`, registra el motivo y termina sin enviar.
10. Paso 10: El servicio resuelve `carrera_id` desde `es_sucursales_carreras` usando `sucursal_carrera_id`. Si no lo resuelve, usa un identificador inválido para obtener solo los documentos globales y registra una advertencia.
11. Paso 11: El servicio consulta `NiDocumentoPresencialModel::obtenerParaCarrera($carreraId)` y calcula el plazo con `CalculadoraPlazoEntrega::calcular($intencion)`.
12. Paso 12: El servicio genera el recibo con `NuevoIngresoReciboService::generar($intencionId, $niId)`.
13. Paso 13: El servicio genera la planilla con `NuevoIngresoPlanillaService::generar($intencionId, $niId)`.
14. Paso 14: Si cualquiera de los dos PDF no se genera, el servicio marca `fallido`, registra el error y no envía el correo. No se envía un correo incompleto.
15. Paso 15: El servicio renderiza `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php` con el nombre del aspirante, la lista de documentos, el plazo y la URL del Paso 4.
16. Paso 16: El servicio construye dos adjuntos: `ReciboNI{intencionId}.pdf` y `PlanillaNI{niId}.pdf`, ambos con MIME `application/pdf`.
17. Paso 17: El remitente crea una instancia nueva de PHPMailer con `Services::phpMailer(false)`, configura el destinatario, el asunto, el cuerpo HTML, el texto alternativo y los dos adjuntos.
18. Paso 18: El remitente envía el correo. Si `send()` devuelve verdadero, el servicio marca `correo_aprobacion_estado = 'enviado'` y guarda la fecha del intento.
19. Paso 19: Si el envío falla, el servicio marca `correo_aprobacion_estado = 'fallido'`, guarda un mensaje resumido y registra el detalle técnico en el log. No se reintenta automáticamente; queda disponible para el comando de reenvío.
20. Paso 20: El aspirante recibe un correo con el mensaje de inscripción culminada, los dos PDF adjuntos, la lista de documentos pendientes con su fecha límite y un botón para volver al Paso 4.
21. Paso 21: Si el aspirante recarga el Paso 4, no se envía otro correo: la pantalla solo lee datos y el intento ya quedó registrado como `enviado` o `fallido`.
22. Paso 22: Si el mismo pago se reenvía desde una pestaña vieja, `procesarPago()` responde de forma idempotente y el controlador no vuelve a llamar al notificador porque el estado previo ya no es 2.

### Flujo Zelle

1. Paso 1: El aspirante reporta un pago Zelle y la intención queda en estado 7 (`sin verificar`).
2. Paso 2: Un administrador abre el reporte y ejecuta la verificación con el monto recibido.
3. Paso 3: `ZelleReportManager::verificar()` valida el monto, los detalles de nuevo ingreso y el bloqueo optimista del reporte.
4. Paso 4: Dentro de la transacción, el reporte pasa a `Verificado` y la intención pasa al estado 8 con `actualizado_dt`.
5. Paso 5: Después del commit, `ZelleReportManager` actualiza GHL y envía el correo Zelle actual de "Pago verificado" con enlace al Paso 4.
6. Paso 6: Inmediatamente después, si la intención tiene `ni_inscripcion_id`, llama al nuevo servicio de notificación.
7. Paso 7: El nuevo servicio reserva el intento, genera el recibo y la planilla, consulta los documentos, calcula el plazo y envía el correo con adjuntos.
8. Paso 8: El aspirante recibe dos correos: el aviso Zelle existente y el nuevo correo de inscripción culminada. La decisión de mantener ambos es explícita.
9. Paso 9: Si la verificación se repite, el bloqueo optimista devuelve el resultado sin volver a ejecutar la notificación. El nuevo correo no se duplica.
10. Paso 10: Si el nuevo correo falla, el aviso Zelle ya se envió y el nuevo intento queda como `fallido`; puede reenviarse manualmente con el comando.

### Flujo de reenvío manual con comando

1. Paso 1: Un operador ejecuta `php spark ni:reenviar-correo-aprobacion`.
2. Paso 2: El comando lee las opciones `--dry-run`, `--limit` y `--id`. Sin opciones, procesa todas las postulaciones en estado `fallido`, ordenadas por id.
3. Paso 3: Si no hay postulaciones fallidas, muestra el mensaje "No hay correos fallidos por reenviar." y termina.
4. Paso 4: Para cada postulación candidata, resuelve su última intención con `NuevoIngresoPagoService::obtenerUltimaIntencion()`.
5. Paso 5: Si la intención no existe o no está en estado 3 u 8, omite la postulación, la reporta como "sin intención aprobada" y no cambia su estado.
6. Paso 6: Si se indicó `--dry-run`, reporta la postulación como candidata sin generar PDFs, sin enviar y sin escribir en base de datos.
7. Paso 7: En ejecución real, llama a `Services::nuevoIngresoAprobacionNotificacion()->reenviar($intencionId, $niId)`.
8. Paso 8: `reenviar()` valida la intención y reserva el intento con una actualización atómica de `fallido` a `intentando`. Si otra ejecución ya lo tomó, no envía.
9. Paso 9: El servicio reutiliza el mismo flujo de composición: recibo, planilla, documentos, plazo, plantilla y adjuntos.
10. Paso 10: Si el envío es exitoso, el estado queda `enviado` y el comando lo reporta como enviado.
11. Paso 11: Si el envío vuelve a fallar, el estado queda `fallido` y el comando lo reporta como fallido. Una nueva ejecución del comando puede volver a intentarlo.
12. Paso 12: Al finalizar, el comando muestra un resumen con total de candidatos, enviados, fallidos y omitidos.
13. Paso 13: El comando no procesa postulaciones en `pendiente`, `intentando` ni `enviado`; solo `fallido`.
14. Paso 14: El comando no se ejecuta automáticamente ni se programa en cron. Su ejecución es una decisión manual del operador.

## Flujos alternativos / variantes

### Aprobación por pasarela no Zelle

1. Paso 1: La pasarela confirma el pago y la intención pasa de 2 a 3.
2. Paso 2: El controlador detecta estado previo 2 y estado actual 3.
3. Paso 3: El notificador reserva el intento y envía el correo con adjuntos y documentos.
4. Paso 4: El estado queda `enviado` y no se vuelve a enviar en recargas, reenvíos idempotentes ni ejecuciones del comando.

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

1. Paso 1: El aspirante reporta un pago Zelle.
2. Paso 2: `procesarPago()` devuelve `success`, pero la intención queda en 7.
3. Paso 3: El controlador comprueba el estado actual y `estaAprobada()` devuelve falso.
4. Paso 4: No se llama al notificador. El correo se enviará cuando el administrador verifique el pago.

### Pago verificado por Zelle (estado 8)

1. Paso 1: El administrador verifica el reporte.
2. Paso 2: La intención queda en 8 y se envía el aviso Zelle actual.
3. Paso 3: El nuevo notificador se ejecuta después del aviso actual y envía el correo con planilla, recibo y documentos.
4. Paso 4: Ambos correos quedan registrados; el nuevo intento se controla con el flag de `ni_inscripciones`.

### Aprobación ya existente o reenvío idempotente

1. Paso 1: La intención ya está en estado 3 u 8.
2. Paso 2: `procesarPago()` devuelve un éxito idempotente sin llamar a la pasarela.
3. Paso 3: El controlador no llama al notificador porque el estado previo no era 2.
4. Paso 4: El correo no se reenvía automáticamente. Si estaba en `fallido`, solo el comando manual puede reintentarlo.

### Postulación aprobada antes del despliegue

1. Paso 1: La postulación ya estaba aprobada y tiene `correo_aprobacion_estado = 'pendiente'` por el valor por defecto de la migración.
2. Paso 2: Nadie ejecuta un proceso masivo de envío.
3. Paso 3: Si el aspirante reenvía un formulario viejo, el controlador detecta estado previo 3/8 y no llama al notificador.
4. Paso 4: No se envían correos históricos.

### Sin documentos presenciales aplicables

1. Paso 1: La carrera no tiene documentos exclusivos y no hay documentos globales activos.
2. Paso 2: `obtenerParaCarrera()` devuelve un arreglo vacío.
3. Paso 3: La plantilla omite la sección de documentos y la fecha límite.
4. Paso 4: El correo se envía igualmente con el recibo y la planilla adjuntos.

### Sin fecha límite resuelta

1. Paso 1: La intención no tiene `actualizado_dt` ni `fecha` válidos.
2. Paso 2: `CalculadoraPlazoEntrega::calcular()` devuelve `null` y registra una advertencia.
3. Paso 3: La plantilla muestra la lista de documentos sin la línea de fecha límite.
4. Paso 4: El correo se envía con los adjuntos y la lista.

### Carrera no resuelta

1. Paso 1: `sucursal_carrera_id` no tiene una relación válida en `es_sucursales_carreras`.
2. Paso 2: El servicio usa un identificador imposible y obtiene solo los documentos globales; registra una advertencia.
3. Paso 3: La planilla existente muestra "No disponible" en los campos derivados que no resuelva.
4. Paso 4: El correo se envía con la lista global y los adjuntos, sin inventar documentos de carrera.

### Fallo al generar el recibo o la planilla

1. Paso 1: Dompdf no está disponible, el HTML falla o el servicio lanza una excepción.
2. Paso 2: El notificador captura el error, marca `fallido` y registra el motivo.
3. Paso 3: No se envía ningún correo, ni siquiera uno parcial.
4. Paso 4: No se reintenta automáticamente; el correo queda `fallido` y puede reenviarse con el comando.

### Fallo de consulta de documentos

1. Paso 1: La tabla de documentos no está migrada o la base no responde.
2. Paso 2: El notificador captura el error, marca `fallido` y registra el motivo.
3. Paso 3: No se envía el correo porque faltaría una parte solicitada.
4. Paso 4: El pago y la pantalla del Paso 4 no se ven afectados.

### Fallo de SMTP

1. Paso 1: El servidor SMTP no responde, rechaza las credenciales o devuelve error.
2. Paso 2: El remitente devuelve `false`; el notificador marca `fallido`.
3. Paso 3: El detalle técnico se registra en el log sin incluir el correo del aspirante.
4. Paso 4: No se reintenta automáticamente. El intento queda `fallido` y puede reenviarse con el comando.

### Correo del aspirante inválido o ausente

1. Paso 1: `ni_inscripciones.correo` está vacío o no pasa la validación de correo.
2. Paso 2: El notificador marca `fallido` y registra el motivo.
3. Paso 3: No se generan PDFs ni se envía nada.
4. Paso 4: El intento queda `fallido`; si se corrige el correo en la postulación, el comando puede reintentarlo.

### Dos aprobaciones concurrentes

1. Paso 1: Dos peticiones intentan notificar la misma postulación al mismo tiempo.
2. Paso 2: Solo una actualización atómica consigue pasar de `pendiente` a `intentando`.
3. Paso 3: La otra obtiene cero filas afectadas y no envía.
4. Paso 4: El aspirante recibe como máximo un correo.

### Proceso interrumpido después de reservar el intento

1. Paso 1: El proceso cae después de marcar `intentando` y antes de enviar.
2. Paso 2: El estado queda `intentando`.
3. Paso 3: Ninguna ejecución posterior lo vuelve a tomar: `notificar()` solo reserva desde `pendiente` y `reenviar()` solo desde `fallido`.
4. Paso 4: No hay correo y no hay reintento automático. El comando solo procesa `fallido`, no `intentando`; el log y el estado permiten diagnosticarlo.

### Reenvío manual de un correo fallido

1. Paso 1: El operador ejecuta `php spark ni:reenviar-correo-aprobacion`.
2. Paso 2: El comando selecciona las postulaciones con `correo_aprobacion_estado = 'fallido'`.
3. Paso 3: Para cada una, resuelve la última intención y comprueba que esté en estado 3 u 8.
4. Paso 4: Llama a `reenviar()`, que reserva el paso de `fallido` a `intentando`.
5. Paso 5: Si el correo se envía, el estado queda `enviado` y no se vuelve a seleccionar.
6. Paso 6: Si vuelve a fallar, el estado queda `fallido` y una nueva ejecución del comando puede reintentarlo.

### Comando sin correos fallidos

1. Paso 1: El operador ejecuta el comando.
2. Paso 2: La consulta no devuelve filas.
3. Paso 3: El comando muestra "No hay correos fallidos por reenviar.".
4. Paso 4: No se escribe en base de datos ni se envía nada.

### Comando con postulación fallida sin intención aprobada

1. Paso 1: La postulación está en `fallido`, pero su última intención no existe, está cancelada o no está en estado 3 u 8.
2. Paso 2: El comando omite la postulación y la reporta como "sin intención aprobada".
3. Paso 3: No llama a `reenviar()` y no cambia el estado.
4. Paso 4: El resumen incluye la postulación como omitida.

### Ejecuciones concurrentes del comando

1. Paso 1: Dos operadores ejecutan el comando al mismo tiempo.
2. Paso 2: Ambos seleccionan la misma postulación en `fallido`.
3. Paso 3: Solo una actualización atómica consigue pasar de `fallido` a `intentando`.
4. Paso 4: La otra ejecución omite la fila y se envía como máximo un correo.

### Comando con `--dry-run`

1. Paso 1: El operador ejecuta `php spark ni:reenviar-correo-aprobacion --dry-run`.
2. Paso 2: El comando lista las postulaciones candidatas y la intención que usaría.
3. Paso 3: No genera PDFs, no envía y no cambia estados.
4. Paso 4: El resumen indica cuántos correos se habrían reenviado.

### Comando con `--id` o `--limit`

1. Paso 1: El operador limita la ejecución con `--id=123` o `--limit=10`.
2. Paso 2: El comando aplica el filtro sobre las postulaciones en `fallido`.
3. Paso 3: Si `--id` apunta a una postulación que no está en `fallido`, no hay candidatos y se informa.
4. Paso 4: El resto del flujo es igual al reenvío manual.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Intención inexistente o ajena | `NuevoIngresoPagoService::obtenerIntencion()` devuelve `null` | El notificador devuelve `false` sin reservar el intento | `pendiente`; sin correo |
| Intención en estado distinto de 3 u 8 | `estaAprobada()` devuelve `false` | No se reserva ni se envía | `pendiente`; sin correo |
| Intento ya reservado, enviado o fallido en el primer envío | Actualización atómica desde `pendiente` con 0 filas afectadas | No se envía; se registra un aviso informativo | Estado existente intacto |
| Reenvío de un correo que no está en `fallido` | Actualización atómica desde `fallido` con 0 filas afectadas | No se envía; el comando lo reporta como omitido | Estado existente intacto |
| Postulación no encontrada | Actualización atómica con 0 filas afectadas | No se envía; log técnico | `pendiente`; sin correo |
| Correo ausente o inválido | Validación con `valid_email()` | Marca `fallido`; log con motivo `sin_correo` | `fallido`; sin correo |
| Tabla o columnas no migradas | Excepción de base de datos en la reserva | Marca `fallido` si es posible; log técnico; no rompe el pago | `fallido` o `pendiente`; sin correo |
| Fallo al generar el recibo | Excepción de `NuevoIngresoReciboService` | Marca `fallido`; no envía; log técnico | `fallido`; sin correo |
| Fallo al generar la planilla | Excepción de `NuevoIngresoPlanillaService` | Marca `fallido`; no envía; log técnico | `fallido`; sin correo |
| Fallo al consultar documentos | Excepción de `NiDocumentoPresencialModel` o tabla ausente | Marca `fallido`; no envía; log técnico | `fallido`; sin correo |
| Carrera no resuelta | Consulta sin fila en `es_sucursales_carreras` | Usa solo documentos globales; advertencia en log; envía | `enviado` |
| Sin documentos aplicables | Arreglo vacío | Omite la sección de documentos; envía | `enviado` |
| Sin fecha base válida | `CalculadoraPlazoEntrega::calcular()` devuelve `null` | Omite la fecha límite; envía; advertencia en log | `enviado` |
| Fallo al renderizar la plantilla | Excepción de `view()` | Marca `fallido`; no envía; log técnico | `fallido`; sin correo |
| Fallo de PHPMailer o SMTP | `send()` devuelve `false` o lanza excepción | Marca `fallido`; log técnico sin datos personales; el comando permite reintentar | `fallido`; sin correo |
| Fallo al guardar el estado final | Excepción de base de datos después del envío | Log técnico; el correo ya salió | `intentando` o estado anterior; sin reenvío automático |
| Pago no Zelle aprobado | Estado previo 2 y estado actual 3 | Llama al notificador una vez | `enviado` o `fallido` |
| Pago Zelle pendiente (estado 7) | `estaAprobada()` devuelve `false` | No llama al notificador | `pendiente` |
| Pago Zelle verificado (estado 8) | `ZelleReportManager` después del commit | Envía el aviso Zelle actual y luego el nuevo correo | `enviado` o `fallido` |
| Verificación Zelle repetida | Bloqueo optimista del reporte | Devuelve el resultado sin notificar de nuevo | Sin cambio |
| Pago no Zelle con error | `estatus` distinto de `success` | No llama al notificador | Sin correo |
| Reenvío de un pago ya aprobado | `procesarPago()` responde idempotente; estado previo 3/8 | No llama al notificador | Sin correo |
| Aprobación histórica anterior al despliegue | No hay evento de aprobación nuevo | No se envía ningún correo masivo; el comando no procesa `pendiente` | `pendiente`; sin correo |
| Correo Zelle actual | Flujo existente | Se conserva y se envía antes del nuevo correo | Sin cambio |
| Comando sin correos fallidos | Consulta sin filas | Muestra "No hay correos fallidos por reenviar." | Sin cambio |
| Comando con postulación sin intención aprobada | `obtenerUltimaIntencion()` nula o no aprobada | Omite la postulación, la reporta y no cambia el estado | `fallido`; sin envío |
| Comando con `--id` inexistente o no fallido | Consulta sin filas | No hay candidatos; muestra el resumen | Sin cambio |
| Comando con `--dry-run` | Opción activa | Lista candidatos sin enviar ni escribir | Sin cambio |
| Error inesperado en una fila del comando | Excepción capturada por el comando | Reporta la fila como fallida u omitida y continúa con las demás | Estado de la fila intacto o `fallido` |

## Reglas de negocio y validaciones

- Solo se notifican intenciones en estado 3 (aprobado) u 8 (verificado). Cualquier otro estado no consume el intento ni envía correo.
- La notificación se dispara únicamente cuando la aprobación ocurre en la ejecución actual:
  - Pago no Zelle: estado previo 2 y estado actual 3.
  - Zelle: verificación exitosa que deja la intención en 8.
- El correo se envía una sola vez por postulación (`ni_inscripciones.id`), no por intención.
- El intento se reserva con una actualización atómica antes de generar PDFs o enviar. Si la reserva no afecta filas, no se envía.
- Un fallo de PDF, documentos, plantilla o SMTP consume el intento y queda como `fallido`. No se reintenta automáticamente; solo se reenvía manualmente con el comando `ni:reenviar-correo-aprobacion`.
- El comando de reenvío solo procesa postulaciones en `correo_aprobacion_estado = 'fallido'`. No procesa `pendiente`, `intentando` ni `enviado`.
- El comando solo reenvía cuando la última intención de la postulación existe y está en estado 3 u 8. Si no, omite la fila sin cambiar su estado.
- El comando no salta la reserva atómica: `reenviar()` pasa de `fallido` a `intentando` y solo envía si la transición afecta una fila.
- Si el reenvío falla de nuevo, el estado vuelve a `fallido` y una nueva ejecución del comando puede reintentarlo. No hay límite de intentos ni espera mínima.
- `--dry-run` lista los candidatos sin generar PDFs, sin enviar y sin escribir en base de datos.
- `--limit` por defecto es `0` (sin límite); un valor positivo acota el lote. `--id` filtra una sola postulación.
- El comando no se programa en cron ni se expone por HTTP. Se ejecuta manualmente por un operador con acceso a CLI.
- Un error en una fila no detiene el resto del lote: el comando captura la excepción, reporta la fila y continúa.
- El destinatario es únicamente `ni_inscripciones.correo`. No se agregan copias.
- El cuerpo del correo:
  - Saluda por el nombre del aspirante.
  - Indica que el pago fue aprobado y la inscripción culminó.
  - Menciona que se adjuntan el recibo y la planilla.
  - Muestra la lista de documentos pendientes para entrega presencial, si existe.
  - Muestra la fecha límite de entrega, si se pudo calcular, y la insignia "Plazo vencido" si corresponde.
  - Incluye un botón al Paso 4.
  - No muestra monto, referencia, tasa, plan, descuento, carrera ni sede.
- Los adjuntos son exactamente los PDF que generan los servicios existentes:
  - `ReciboNI{intencionId}.pdf`.
  - `PlanillaNI{niId}.pdf`.
- El correo es HTML, con texto alternativo en español y el logo institucional de las plantillas existentes.
- La lista de documentos usa la carrera de la postulación, nunca un parámetro del cliente, y respeta la regla global/exclusivo de FEAT-010.
- Si no hay documentos, se omite la sección completa y se envía el correo.
- Si no hay fecha límite, se muestra la lista sin la línea de fecha.
- Si la carrera no se resuelve, se muestran solo los documentos globales y se registra una advertencia; no se bloquea el envío.
- El correo se envía después de que la aprobación ya quedó persistida. Un fallo del correo nunca revierte el pago, el estado de la intención ni la sincronización GHL.
- El envío es síncrono y best-effort. El controlador y `ZelleReportManager` capturan cualquier excepción del notificador para no alterar la respuesta al usuario o al administrador.
- El notificador no lanza excepciones hacia sus consumidores; devuelve `true` o `false` y registra el resultado.
- Los campos de control se actualizan con query builder para evitar validaciones del modelo y para hacer la reserva atómica.
- `correo_aprobacion_error` guarda solo un código o mensaje corto y genérico. El detalle técnico va al log con el id de la intención y de la postulación, sin el correo del aspirante.
- No se almacenan los PDFs ni el HTML del correo. Cada envío se genera en memoria.
- No se agregan rutas, filtros, CSRF ni cambios de sesión. El envío no recibe datos del cliente.
- La migración es idempotente y no modifica datos existentes. Las postulaciones existentes quedan en `pendiente`.

## Contratos y diseño propuesto

### Campos nuevos en `ni_inscripciones`

| Columna | Tipo | Nulo | Valor por defecto | Regla |
| --- | --- | --- | --- | --- |
| `correo_aprobacion_estado` | ENUM(`pendiente`,`intentando`,`enviado`,`fallido`) | No | `pendiente` | La base rechaza cualquier valor fuera del enum. |
| `correo_aprobacion_dt` | DATETIME | Sí | NULL | Fecha del último intento (reserva, envío o fallo). |
| `correo_aprobacion_error` | VARCHAR(255) | Sí | NULL | Código o mensaje resumido del fallo; sin datos personales. |

- Migración: `app/Database/Migrations/2026-10-29-000104_AddCorreoAprobacionToNiInscripciones.php`.
- `correo_aprobacion_estado` se define como ENUM; en MySQL/MariaDB la base rechaza valores fuera de la lista. En SQLite (pruebas) CodeIgniter lo traduce a `TEXT` con `CHECK`.
- Usa `fieldExists()` por columna y `forge->addColumn()`; se puede ejecutar dos veces sin error.
- Se registra en `InitPrincipalDb::runPrincipalMigrations()` después de `2026-10-29-000103_CreateNiDocumentosPresencialesCarreras.php`.
- No se agregan índices: el acceso es por clave primaria y el volumen es bajo.
- Los tres campos no se agregan a `NiInscripcionModel::$allowedFields`: solo los escribe el servicio de notificación con query builder, para que un cliente no pueda asignarlos por error en un guardado masivo.

### Máquina de estados del correo

```text
pendiente --(notificar / reserva atómica)--> intentando --(envío OK)--> enviado
                                                      \--(fallo)------> fallido

fallido --(reenviar manual por comando)--> intentando --(envío OK)--> enviado
                                                     \--(fallo)------> fallido
```

- Solo se sale de `pendiente` una vez.
- `intentando` es terminal si el proceso se interrumpe; no se reintenta automáticamente y el comando no lo procesa.
- `enviado` es terminal.
- `fallido` solo sale por el comando de reenvío manual, que lo pasa a `intentando`.
- No existe transición de `fallido` ni de `intentando` a `pendiente`.

### `NuevoIngresoAprobacionNotificacionService`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionService.php`.

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `notificar(int $intencionId, int $niInscripcionId): bool` | Primer envío automático: validar, reservar desde `pendiente`, componer y enviar el correo. | Escribe los campos de control; genera PDFs en memoria; envía correo. No lanza excepciones. |
| `reenviar(int $intencionId, int $niInscripcionId): bool` | Reenvío manual: validar, reservar desde `fallido`, componer y enviar el correo. | Igual que `notificar`, pero solo acepta el estado de origen `fallido`. |

- Dependencias inyectables:
  - `NiInscripcionModel`.
  - `NuevoIngresoPagoService`.
  - `NuevoIngresoReciboService`.
  - `NuevoIngresoPlanillaService`.
  - `NiDocumentoPresencialModel`.
  - `CalculadoraPlazoEntrega`.
  - `BaseConnection` de la base principal.
  - `CorreoAprobacionSenderInterface`.
- Flujo interno compartido:
  1. Validar ids positivos.
  2. Obtener la intención con `obtenerIntencion($intencionId, $niInscripcionId)`.
  3. Si es nula o no está aprobada, devolver `false` sin reservar.
  4. Reservar con `UPDATE ... WHERE id = ? AND correo_aprobacion_estado = ?` usando `pendiente` para `notificar()` y `fallido` para `reenviar()`. Si `affectedRows() === 0`, devolver `false`.
  5. Cargar la postulación y validar el correo.
  6. Resolver `carrera_id` y consultar documentos.
  7. Calcular el plazo.
  8. Generar recibo y planilla.
  9. Renderizar la vista.
  10. Enviar con el remitente.
  11. Actualizar el estado final.
- Cualquier `\Throwable` se captura en el método público, se registra y se traduce a `fallido` cuando la reserva ya ocurrió.
- El método devuelve `true` solo si el correo se envió y el estado final se guardó como `enviado`.
- `notificar()` no acepta `fallido`; `reenviar()` no acepta `pendiente`, `intentando` ni `enviado`.
- No conoce sesión, rutas, controladores ni el flujo Zelle. Recibe ids ya validados y vuelve a validar propiedad y estado.

### Comando `ni:reenviar-correo-aprobacion`

Ubicación: `app/Commands/NiReenviarCorreoAprobacion.php`.

| Aspecto | Regla |
| --- | --- |
| Nombre | `ni:reenviar-correo-aprobacion` |
| Grupo | `Nuevo ingreso` |
| Descripción | Reenvía los correos de inscripción culminada que quedaron en estado `fallido`. |
| `--id=0` | Procesa solo la postulación indicada (`ni_inscripciones.id`). |
| `--limit=0` | Máximo de postulaciones a procesar; `0` (por defecto) significa sin límite. |
| `--dry-run` | Lista candidatos sin generar PDFs, enviar ni escribir. |
| Filtro base | `correo_aprobacion_estado = 'fallido'`, ordenado por `id` ascendente. |
| Intención | Usa `NuevoIngresoPagoService::obtenerUltimaIntencion($niId)` y `estaAprobada()`. |
| Envío | Llama a `NuevoIngresoAprobacionNotificacionService::reenviar($intencionId, $niId)`. |
| Sin intención aprobada | Omite la fila, la reporta y no cambia su estado. |
| Error por fila | Captura `\Throwable`, reporta la fila y continúa con el resto. |
| Salida | Una línea por postulación y un resumen con candidatos, enviados, fallidos y omitidos. |
| Automatización | Ninguna; no se registra en cron ni se expone por HTTP. |

- El comando no procesa `pendiente`, `intentando` ni `enviado`.
- El comando no modifica el correo del aspirante ni el estado de la intención; solo llama al servicio de notificación.
- Si el comando se ejecuta dos veces, las filas que quedaron `enviado` dejan de seleccionarse; las que volvieron a fallar siguen en `fallido` y pueden reintentarse.
- Si el comando se ejecuta con `--dry-run`, no se reserva el intento ni se altera `correo_aprobacion_estado`.

### `CorreoAprobacionSenderInterface`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/Contracts/CorreoAprobacionSenderInterface.php`.

```php
public function enviar(
    string $destinatario,
    string $nombre,
    string $asunto,
    string $html,
    string $altBody,
    array $adjuntos
): bool;
```

- `$adjuntos` es una lista de `['nombre' => string, 'contenido' => string]`.
- La interfaz permite inyectar un doble en pruebas sin tocar SMTP.

### `PhpMailerCorreoAprobacionSender`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/PhpMailerCorreoAprobacionSender.php`.

- Usa `Services::phpMailer(false)` para obtener una instancia nueva.
- Configura `Timeout = 10`.
- Agrega el destinatario con `addAddress()`.
- Configura `Subject`, `msgHTML($html)` y `AltBody`.
- Agrega cada adjunto con `addStringAttachment($contenido, $nombre, 'base64', 'application/pdf')`.
- Devuelve el resultado de `send()`.
- Captura `\Throwable`, registra el detalle técnico sin el correo del aspirante y devuelve `false`.

### Plantilla del correo

Ubicación: `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php`.

- Variables: `$nombre`, `$documentos`, `$plazo`, `$paso4_url`, `$logo_url`.
- Diseño basado en `app/Views/emails/zelle_recibo.php`: encabezado azul, logo, cuerpo blanco, pie institucional.
- Asunto propuesto: `Tu inscripción en UNIR ha culminado` (supuesto a validar).
- Texto alternativo: `Tu pago fue aprobado y tu inscripción ha culminado. Adjuntamos tu recibo y tu planilla. Revisa los documentos pendientes para entrega presencial.`
- Secciones:
  1. Saludo con el nombre.
  2. Mensaje breve de inscripción culminada y mención de los adjuntos.
  3. Lista de documentos, solo si `$documentos` no está vacío.
  4. Fecha límite, solo si `$plazo['fecha_limite_texto']` existe; insignia "Plazo vencido" si `$plazo['vencida']` es verdadero.
  5. Botón "Ir al Paso 4".
  6. Pie institucional.
- Toda salida se escapa con `esc()`.
- No muestra montos ni referencias.

### Enganches de aprobación

| Punto | Cambio | Regla |
| --- | --- | --- |
| `Paso3::postPago()` | Antes de `procesarPago()`, leer la intención y guardar su `estados_id`. Después de un `success`, si el estado previo era 2, releer la intención; si `estaAprobada()` es verdadero, llamar al notificador dentro de un `try/catch`. | No altera la redirección ni el flash de éxito si el correo falla. |
| `ZelleReportManager::verificar()` | Después del commit, de la actualización GHL y del aviso Zelle actual, si `$accion === 'verificar' && $niId !== null`, llamar al notificador dentro de un `try/catch`. | Conserva el aviso Zelle y agrega el nuevo correo. |

- El controlador no notifica si el estado previo no era 2, lo que evita correos históricos y reenvíos idempotentes.
- El controlador no notifica si la intención actual no está aprobada (por ejemplo, Zelle en 7).
- `ZelleReportManager` solo notifica en verificaciones que realmente ejecutaron la transacción; el bloqueo optimista evita duplicados.
- Ambas llamadas son best-effort: si el notificador devuelve `false` o lanza una excepción no controlada, se registra y la operación principal continúa.

### `Services`

- Agregar imports:
  - `App\Libraries\Inscripciones\NuevoIngreso\Notificacion\NuevoIngresoAprobacionNotificacionService`.
  - `App\Libraries\Inscripciones\NuevoIngreso\Notificacion\PhpMailerCorreoAprobacionSender`.
  - `App\Libraries\Inscripciones\NuevoIngreso\Documentos\CalculadoraPlazoEntrega`.
  - `App\Models\Inscripciones\NiDocumentoPresencialModel`.
- Agregar `public static $nuevoIngresoAprobacionNotificacionInstance = null;`.
- Agregar `nuevoIngresoAprobacionNotificacion($getShared = true)` que construye el servicio con `Database::connect()`, `new NiInscripcionModel($dbPrincipal)`, `self::nuevoIngresoPago()`, `self::nuevoIngresoRecibo()`, `self::nuevoIngresoPlanilla()`, `new NiDocumentoPresencialModel($dbPrincipal)`, `new CalculadoraPlazoEntrega()`, `$dbPrincipal` y `new PhpMailerCorreoAprobacionSender()`.
- Las pruebas deben reiniciar `$nuevoIngresoAprobacionNotificacionInstance` en `setUp`/`tearDown`, igual que los demás servicios.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Database/Migrations/2026-10-29-000104_AddCorreoAprobacionToNiInscripciones.php` | Campos de control e idempotencia. |
| Modificar | `app/Commands/InitPrincipalDb.php` | Registrar la migración en `init:principal`. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionService.php` | Composición, idempotencia y envío. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/Contracts/CorreoAprobacionSenderInterface.php` | Contrato del remitente. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Notificacion/PhpMailerCorreoAprobacionSender.php` | Implementación con PHPMailer. |
| Crear | `app/Views/emails/nuevo_ingreso_inscripcion_culminada.php` | Plantilla HTML del correo. |
| Modificar | `app/Config/Services.php` | Registrar el servicio de notificación. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Enganche para pagos no Zelle aprobados. |
| Modificar | `app/Libraries/ZelleReportManager.php` | Enganche para pagos Zelle verificados. |
| Crear | `app/Commands/NiReenviarCorreoAprobacion.php` | Comando manual para reenviar correos `fallido`. |
| Crear | `tests/app/Database/Migrations/CorreoAprobacionNiInscripcionesMigrationTest.php` | Columnas, valores por defecto e idempotencia. |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Notificacion/NuevoIngresoAprobacionNotificacionServiceTest.php` | Estados, adjuntos, documentos, plazo, fallos, concurrencia lógica y `reenviar()`. |
| Crear | `tests/app/Commands/NiReenviarCorreoAprobacionTest.php` | Filtro `fallido`, `--dry-run`, `--id`, `--limit`, resumen y omisiones. |
| Modificar | `tests/app/Integration/Paso4PagoTest.php` | Notificación única en aprobación no Zelle y no notificación en idempotentes/errores. |
| Modificar | `tests/app/Integration/ZelleNuevoIngresoTest.php` | Notificación única al verificar y no notificación en rechazo/duplicado. |
| Documentar | `docs/features/011-correo-aprobacion-inscripcion-recibo-planilla-documentos/plan.md` | Este plan. |

No se modifican `NiInscripcionModel`, `NuevoIngresoReciboService`, `NuevoIngresoPlanillaService`, `CalculadoraPlazoEntrega`, `NiDocumentoPresencialModel`, `NuevoIngresoPagoService`, `PaymentOrchestrator`, `IntencionesPagoModel`, las rutas, los filtros, la SPA ni la API. No se agregan dependencias ni migraciones de sucursal.

## Criterios de finalización

- [ ] La migración `000104` agrega `correo_aprobacion_estado`, `correo_aprobacion_dt` y `correo_aprobacion_error` a `ni_inscripciones` con los tipos y valores por defecto indicados.
- [ ] La migración es idempotente: se puede ejecutar dos veces sin error y no modifica filas existentes.
- [ ] La migración está registrada en `InitPrincipalDb::runPrincipalMigrations()`.
- [ ] Los tres campos de control no se agregan a `NiInscripcionModel::$allowedFields`; solo el servicio de notificación los escribe con query builder.
- [ ] `NuevoIngresoAprobacionNotificacionService::notificar()` devuelve `false` sin reservar cuando la intención no existe, es ajena o no está en estado 3 u 8.
- [ ] `notificar()` reserva el intento con una actualización atómica desde `pendiente`; dos llamadas simultáneas producen como máximo un envío.
- [ ] `reenviar()` reserva el intento con una actualización atómica desde `fallido`; no envía desde `pendiente`, `intentando` ni `enviado`.
- [ ] Una segunda llamada a `notificar()` después de `enviado`, `fallido` o `intentando` no envía ni cambia el estado.
- [ ] Una llamada a `reenviar()` después de `enviado` o `intentando` no envía ni cambia el estado; solo funciona desde `fallido`.
- [ ] El correo se envía solo al `correo` de `ni_inscripciones`; un correo ausente o inválido deja el estado en `fallido` y no envía.
- [ ] El correo adjunta `ReciboNI{intencionId}.pdf` y `PlanillaNI{niId}.pdf`, ambos con contenido PDF válido.
- [ ] Si falla la generación del recibo o de la planilla, no se envía ningún correo y el estado queda `fallido`.
- [ ] Si falla la consulta de documentos, no se envía el correo y el estado queda `fallido`.
- [ ] El cuerpo del correo incluye el nombre, el mensaje de inscripción culminada, la lista de documentos aplicables, la fecha límite cuando exista y el botón al Paso 4.
- [ ] El cuerpo del correo no incluye monto, referencia, tasa, plan, descuento, carrera ni sede.
- [ ] La lista de documentos respeta la regla global/exclusivo de FEAT-010 y se filtra por la carrera de la postulación.
- [ ] Si no hay documentos aplicables, el correo se envía sin la sección de documentos ni la fecha límite.
- [ ] Si no hay fecha base válida, el correo se envía con la lista pero sin la línea de fecha límite.
- [ ] Si la carrera no se resuelve, se usan solo los documentos globales, se registra una advertencia y el correo se envía.
- [ ] La plantilla escapa toda salida con `esc()` y usa el diseño y el logo de las plantillas existentes.
- [ ] Un pago no Zelle aprobado desde `Paso3::postPago()` dispara el notificador una sola vez.
- [ ] Un pago no Zelle con error, un pago ya aprobado o un pago pendiente de verificación no dispara el notificador.
- [ ] Un pago Zelle verificado dispara el aviso Zelle actual y además el nuevo correo con adjuntos.
- [ ] Un pago Zelle rechazado o una verificación repetida no dispara el nuevo correo.
- [ ] Las aprobaciones anteriores al despliegue no generan correos.
- [ ] El comando `ni:reenviar-correo-aprobacion` existe, procesa por defecto todas las postulaciones en `fallido` y permite acotar con `--limit` o `--id`.
- [ ] El comando resuelve la última intención y solo reenvía cuando está en estado 3 u 8; si no, omite la fila sin cambiar su estado.
- [ ] El comando soporta `--dry-run`, `--limit` y `--id`; `--dry-run` no genera PDFs, no envía y no escribe.
- [ ] Un reenvío exitoso deja el estado en `enviado` y la fila deja de ser candidata.
- [ ] Un reenvío fallido deja el estado en `fallido` y una nueva ejecución del comando puede reintentarlo.
- [ ] El comando no procesa `pendiente`, `intentando` ni `enviado`.
- [ ] El comando captura errores por fila y continúa con el resto del lote.
- [ ] El comando muestra un resumen con candidatos, enviados, fallidos y omitidos.
- [ ] Un fallo del notificador no altera la redirección, el flash de éxito, el estado del pago, la sincronización GHL ni la respuesta del panel administrativo.
- [ ] El detalle técnico del fallo se registra en el log sin incluir el correo del aspirante ni otros datos personales.
- [ ] `correo_aprobacion_error` contiene solo un código o mensaje resumido y no supera los 255 caracteres.
- [ ] No se agregaron rutas, endpoints, CSRF, dependencias ni cambios en `vendor/`, `system/` o `public/vendor/`.
- [ ] Las pruebas de la migración, del servicio, del comando, de `Paso4PagoTest` y de `ZelleNuevoIngresoTest` pasan.
- [ ] Las pruebas existentes de FEAT-007, FEAT-009 y FEAT-010 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 los dos adjuntos, la lista, la fecha, la ausencia de reenvío automático y el reenvío manual de un fallido simulado.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Formato de entrega | Adjuntar los dos PDF y listar los documentos en el cuerpo. |
| Correo Zelle existente | Mantener ambos correos: el aviso Zelle actual y el nuevo correo con adjuntos. |
| Momento del envío | Inmediatamente al aprobarse el pago, desde el flujo de aprobación. |
| Unidad de idempotencia | Una sola vez por postulación. |
| Fallo de envío | No reintentar automáticamente; marcar el intento como `fallido` y guardar el log. |
| Contenido del cuerpo | Mensaje breve de inscripción culminada, adjuntos y documentos; sin montos ni referencias. |
| Fallo al generar PDF | No enviar el correo y registrar el error. |
| Estado tras fallo | Queda `fallido`; no se reenvía automáticamente, pero puede reenviarse con un comando manual. |
| Reenvío manual | Sí, comando `ni:reenviar-correo-aprobacion`; sin interfaz web. |
| Alcance del reenvío | Solo correos en `fallido`; no `pendiente`, `intentando` ni `enviado`. |
| Aprobaciones históricas | No enviar correos históricos; el comando no procesa `pendiente`. |
| Fecha límite | Incluirla en la lista, con "Plazo vencido" si corresponde. |
| Botón al portal | Incluir un botón al Paso 4. |
| Destinatarios | Solo el correo del aspirante. |
| Trazabilidad | Campos de estado en `ni_inscripciones`. |
| Sin documentos | Enviar el correo sin la sección de documentos. |
| División del alcance | No se recomienda dividir; es una sola capacidad con cuatro fases internas. |

## Riesgos y deuda técnica

- **Envío síncrono:** la aprobación espera la generación de dos PDFs y el envío SMTP. Con Dompdf y un servidor lento, la respuesta puede tardar varios segundos. Una cola de correos es una feature posterior.
- **Sin reintentos automáticos:** un fallo transitorio de SMTP, de Dompdf o de la base deja el correo en `fallido`. Un operador debe ejecutar el comando para reintentarlo; no hay reintento programado.
- **Reenvío manual repetible:** mientras el correo siga en `fallido`, cada ejecución del comando puede reintentarlo. No hay límite de intentos ni espera mínima entre ejecuciones.
- **Lote sin límite por defecto:** si hay muchos correos fallidos, el comando puede tardar y saturar el SMTP. Para volúmenes altos conviene ejecutarlo con `--limit` en varios lotes.
- **Proceso interrumpido:** si el proceso cae después de reservar y antes de enviar, el estado queda `intentando`. El comando no procesa ese estado, por lo que requiere revisión manual; el log y el campo de estado permiten diagnosticarlo.
- **Comando solo para `fallido`:** una postulación aprobada que nunca llegó a intentar el envío (`pendiente`) no se recupera con el comando. Es intencional para no enviar correos históricos.
- **Dos correos en Zelle:** el aspirante recibe el aviso Zelle actual y el nuevo correo. Es intencional, pero puede generar confusión o quejas; debe validarse con negocio.
- **Dependencia de Dompdf:** `public/dompdf/` está ignorado por git. Si el despliegue no lo conserva, el recibo o la planilla fallan y el correo no se envía.
- **Logo remoto:** la planilla usa `base_url()` y Dompdf con recursos remotos. Si el servidor no puede resolver la URL, el logo puede faltar; el PDF y el correo pueden generarse igualmente.
- **Migración no aplicada:** si el código se despliega antes que la migración, la reserva falla y no se envía el correo; el pago no se rompe. La migración debe aplicarse antes o junto con el despliegue.
- **Enganches limitados:** solo se notifican `Paso3::postPago()` y `ZelleReportManager::verificar()`. Si en el futuro se agrega un webhook o un método nuevo que apruebe pagos, deberá invocar el notificador explícitamente.
- **Aprobaciones históricas:** las postulaciones ya aprobadas no reciben correo. Si negocio quiere notificarlas, se necesita una campaña o un comando aparte.
- **Sin auditoría dedicada:** los campos de estado no guardan un historial de intentos ni el cuerpo del correo. Para auditoría completa se necesitaría una tabla de notificaciones.
- **Datos personales en adjuntos:** el recibo y la planilla contienen datos del aspirante. El correo se envía solo a su dirección registrada; no se agregan copias.
- **Entregabilidad:** la autenticación SPF/DKIM, el rebote y la reputación del remitente quedan fuera de esta feature; dependen de la configuración SMTP existente.
- **Pruebas sin SMTP real:** las pruebas usan un remitente falso. No cubren tiempos de espera, rebotes ni respuestas reales del servidor.
- **Zelle actual sin cambios:** si el correo Zelle actual falla, su auditoría lo registra; el nuevo correo se intenta de todos modos. No se unifican ambos avisos.

## Preguntas abiertas y supuestos a validar

- Se asume que el asunto `Tu inscripción en UNIR ha culminado` es el texto deseado.
- Se asume que el cuerpo no debe mostrar monto, referencia, carrera ni sede, según la decisión de la entrevista.
- Se asume que un fallo de consulta de documentos debe abortar el correo, porque la lista es parte del contenido solicitado.
- Se asume que una carrera no resuelta debe enviar solo los documentos globales, sin bloquear el correo.
- Se asume que la fecha límite del correo debe ser la misma que muestra el Paso 4, calculada con `actualizado_dt` y respaldo `fecha`.
- Se asume que `ni_inscripciones.correo` es la dirección correcta y está validada desde el Paso 0.
- Se asume que los servicios de recibo y planilla pueden ejecutarse sin sesión, como ya lo hacen en sus rutas actuales.
- Se asume que `public/dompdf/` estará disponible en el entorno de despliegue.
- Se asume que las tablas de FEAT-010 estarán migradas antes de usar esta feature.
- Se asume que los únicos estados aprobados son 3 y 8.
- Se asume que no hay un webhook externo de aprobación fuera de los dos enganches identificados.
- Se asume que el correo se envía en español y con el logo institucional existente.
- Se asume que el nombre del archivo `PlanillaNI{niId}.pdf` y `ReciboNI{intencionId}.pdf` es aceptable para los adjuntos.
- Se asume que no se requiere copia a admisiones, pagos ni ningún otro destinatario.
- Se asume que el comando se ejecuta manualmente y que un operador revisa su salida.
- Se asume que el reenvío solo se aplica a `fallido`; `intentando` atascado no se recupera en esta iteración.
- Se asume que el comando procesa todas las postulaciones fallidas por defecto y que se puede acotar el lote con `--limit`.
- Se asume que el nombre `ni:reenviar-correo-aprobacion` es adecuado para el comando.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-29 | Creación del plan FEAT-011 tras revisar `Paso3`, `NuevoIngresoPagoService`, `ZelleReportManager`, `NuevoIngresoReciboService`, `NuevoIngresoPlanillaService`, `NiDocumentoPresencialModel`, `CalculadoraPlazoEntrega`, las plantillas de `app/Views/emails`, `Services::phpMailer()`, las migraciones de `ni_inscripciones` y las features FEAT-007 a FEAT-010. La entrevista definió: adjuntar ambos PDF, mantener el correo Zelle actual, enviar al aprobar, una vez por postulación, no reintentar tras fallo, cuerpo breve sin montos ni referencias, no enviar PDFs incompletos, sin reenvío manual, sin correos históricos, incluir fecha límite, botón al Paso 4, solo el correo del aspirante, estado en `ni_inscripciones` y enviar sin sección cuando no haya documentos. | opencode (agente) |
| 2026-10-29 | Corrección solicitada por el usuario: se agrega el comando manual `ni:reenviar-correo-aprobacion` para reenviar solo correos `fallido`. Se actualiza la máquina de estados (`fallido` → `intentando`), el método `reenviar()` del servicio, el flujo del comando, los criterios, las decisiones y los riesgos. | opencode (agente) |
| 2026-10-29 | Implementación ejecutada en la rama `p-feature/correo-aprobacion-inscripcion-recibo-planilla-documentos`. El comando se registra como `ni:reenviar_correo_aprobacion` porque CodeIgniter 4.0.3 trata los nombres con guiones como opciones y no los ejecuta. La migración no se aplicó a la base local; el smoke test real con SMTP y pasarela queda pendiente. Ver `prototipo.md`. | opencode (agente) |
| 2026-10-29 | Cambio solicitado por el usuario: `correo_aprobacion_estado` pasa de `VARCHAR(20)` a `ENUM('pendiente','intentando','enviado','fallido')`. Se actualiza la migración `000104` y la prueba de migración verifica el `CHECK` generado en SQLite. | opencode (agente) |
