# Zelle de nuevo ingreso: conversión, verificación administrativa y notificaciones

- **Código:** FEAT-006
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-28
- **Autor:** opencode (agente)

## Objetivo

Completar el flujo de Zelle para nuevo ingreso: que el reporte use la tasa de la sede y el descuento propio de nuevo ingreso, que el panel administrativo distinga y verifique estos pagos hasta el estado 8 sin marcar deudas, y que el aspirante reciba un correo con enlace al Paso 4. El resultado debe ser verificable para verificación, rechazo y aislamiento entre pagos regulares y de nuevo ingreso.

## Alcance

- Incluye:
  - Aplicar `desc_pg_dolar_ni` como descuento exclusivo de las intenciones de nuevo ingreso, en la vista previa y en el monto que se guarda en el reporte Zelle.
  - Persistir el desglose completo de la conversión: tasa, porcentaje de descuento, total sin descuento, monto del descuento, total final y monto en bolívares equivalente.
  - Mantener el reporte en `Sin confirmar` y la intención en estado 7 al registrar el pago.
  - Mostrar en el panel administrativo el origen del reporte (regular o nuevo ingreso), los datos del aspirante y un filtro por origen.
  - Verificar un reporte Zelle de nuevo ingreso: reporte `Verificado`, intención en estado 8, historial, auditoría y `data_respuesta` con el desglose.
  - Rechazar un reporte Zelle de nuevo ingreso: reporte `Rechazado`, intención en estado 4 y detalle `_ni` conservado.
  - Garantizar que `ProceNi()` solo valide el vínculo con la postulación y no marque deudas ni inscripciones.
  - Actualizar en GHL el campo de ciclo de vida del contacto a `Inscrito` al verificar, sin mover oportunidades ni cambiar `ghl_sincronizado`.
  - Enviar el aviso de verificación o rechazo al correo de `ni_inscripciones.correo`, con enlace al Paso 4.
  - Cubrir con pruebas unitarias y de integración la verificación, el rechazo y el aislamiento.
- No incluye:
  - Sincronización con Orbis, cambios en `paso_actual`, `orbis_sincronizado` o `ghl_sincronizado`.
  - Movimiento de oportunidades, pipelines o etapas en GHL.
  - Recibo PDF de nuevo ingreso ni reutilización del recibo regular para el aspirante.
  - Reintento automático o cola para correos o GHL fallidos.
  - Backfill de reportes Zelle de nuevo ingreso creados antes de este cambio.
  - Nuevas pasarelas, rutas, filtros o cambios de CSRF.
  - Cambios funcionales en el flujo regular de Zelle; solo se conserva su comportamiento con valores por defecto.

> **Decisión de alcance:** el usuario eligió un solo documento con fases internas. Para reducir el riesgo, la implementación se ordena en tres fases y cada una debe cerrar con `php -l`, pruebas del área y revisión antes de continuar.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`. El Paso 4 ya tiene métodos, formas de pago y procesamiento (FEAT-005), y Zelle ya deja la intención en 7 con el reporte en `Sin confirmar`.
- `pg_intenciones_pago.ni_inscripcion_id` es el discriminador de origen: nulo para pagos regulares y no nulo para nuevo ingreso. No se debe inferir el origen por la cédula ni por la descripción.
- `ni_inscripciones` (base principal) guarda `nombre`, `apellido`, `correo`, `ghl_contact_id` y `paso_actual` de la postulación. Es la fuente del correo y del contacto GHL para este flujo.
- `desc_pg_dolar_ni` ya existe en `gb_config` (migración `2026-10-27-000098`) y se crea en `0`. Un valor `0`, ausente o no numérico significa “sin descuento”; no debe impedir el pago.
- La tasa se obtiene de `pg_tasa_dia` en la base de la sede de la intención. Sin tasa válida no se puede convertir ni registrar el reporte.
- `monto_total` de la intención está en bolívares. El monto del reporte `pg_zelle_reportes.monto` está en dólares y es el total final después del descuento aplicable.
- El descuento de nuevo ingreso reemplaza al descuento global `desc_pg_dolar`; no se suman ni se aplican ambos.
- El estado 8 corresponde a `Verificado`; el estado 4 corresponde a `Rechazado` en `pg_estados`. El reporte usa los literales `Sin confirmar`, `Verificado` y `Rechazado`, no ids.
- El panel administrativo ya está protegido por `adminPanel:module=zelle` y CSRF. No se agregan controles nuevos.
- GHL expone `GoHighLevelClient::updateContact()` y el campo `CF_ESTADO_CICLO_VIDA`. Se asume que el valor `Inscrito` es aceptado por la configuración del campo; si no lo es, el fallo se audita y no bloquea la verificación.
- Las pruebas usan SQLite en archivo y dobles de correo/GHL, como `Paso4PagoTest` e `IntencionesPagoModelNiTest`.
- `MEMORY.md` y `docs/constitution.md` no existen en este checkout; no se crean en esta feature.
- El código `FEAT-006` no colisiona: `docs/features` contiene `FEAT-001` a `FEAT-005`. Se respeta el esquema del repositorio en lugar de `feature-000`.

## Fases internas de implementación

1. **Fase A - Conversión y reporte:** `PagosZelleServices`, migración del desglose, registro en `InitPrincipalDb` y pruebas de conversión. Al cerrar, el reporte NI debe guardar el monto con `desc_pg_dolar_ni` y la intención debe quedar en 7.
2. **Fase B - Verificación y rechazo:** `ZelleReportManager`, validación de detalles NI, preservación del detalle al rechazar, `Panel` y vistas del panel con origen, datos del aspirante y filtro. Al cerrar, verificar debe dejar 8/`Verificado` y rechazar 4/`Rechazado` sin tocar deudas.
3. **Fase C - GHL y correos:** actualización best-effort de GHL, correo del aspirante con enlace al Paso 4, plantillas condicionales y pruebas de aislamiento e idempotencia. Al cerrar, los fallos de GHL o correo deben quedar auditados sin revertir el pago.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso`, `paso_actual >= 4` y una intención en estado 2 (`pagando`) elige Zelle dentro de la familia `rp` y abre `GET /inscripciones/nuevo-ingreso/paso-4/prepago/zelle/{id}`.
2. Paso 2: `Paso3::prePago()` valida sesión, paso, propiedad, estado, sede y forma; `NuevoIngresoPagoService::prepararPago()` agrega `descuento_dolar` con `descuentoDolarNuevoIngreso()` y resuelve la conexión de la sede.
3. Paso 3: `PaymentOrchestrator::preparar()` despacha a `PagosZelleServices::prePayment()`. La pasarela convierte `monto_total` (Bs) a USD usando la tasa de la sede y `desc_pg_dolar_ni`, y devuelve `total_sin_descuento`, `monto_descuento`, `total_final`, `tasa` y `descuento`.
4. Paso 4: La vista de Zelle de nuevo ingreso muestra el total final en USD con el descuento NI y el detalle del pago. No recalcula montos en el navegador.
5. Paso 5: El aspirante envía por POST remitente, número de confirmación, fecha y comprobante a `/paso-4/postpago/zelle/{id}`.
6. Paso 6: `Paso3::postPago()` valida sesión, paso, propiedad, estado, sede y forma; normaliza los archivos y llama a `procesarPago()`.
7. Paso 7: `NuevoIngresoPagoService::procesarPago()` agrega `descuento_dolar`, resuelve la conexión de la sede y el pagador de la postulación, y llama a `PaymentOrchestrator::procesar()`.
8. Paso 8: El orquestador pasa a `PagosZelleServices::postPayment()` el `monto_total` en Bs, el `descuento` NI, la conexión de la sede y los datos del pagador.
9. Paso 9: `postPayment()` valida campos obligatorios, comprobante (PDF/JPG/PNG, máximo 5 MB, MIME real), referencia no duplicada y límite de pendientes; guarda el comprobante con nombre seguro.
10. Paso 10: `postPayment()` convierte Bs a USD con la tasa de la sede y el descuento NI. El descuento global `desc_pg_dolar` no se aplica a una intención de nuevo ingreso.
11. Paso 11: `postPayment()` calcula `monto_pagado` (total final en USD) y `monto_bs` (equivalente en bolívares del monto con descuento). Ambos se derivan de datos del servidor; no se acepta un monto del cliente.
12. Paso 12: En una transacción se inserta `pg_zelle_reportes` con estado `Sin confirmar`, el desglose completo, la referencia, el comprobante y la tasa; se registra `pg_zelle_auditoria` y `pg_pagos_realizados`; y se actualiza `pg_intenciones_pago` a estado 7 con `formas_pago_id` de Zelle.
13. Paso 13: Si la transacción falla, se revierte y se elimina el comprobante guardado; la intención permanece en 2. Si tiene éxito, se notifica al correo de pagos el reporte pendiente y la pasarela devuelve `gestionado = true`.
14. Paso 14: El controlador redirige a `/paso-4` con el mensaje de reporte registrado. La pantalla muestra “Pago en verificación” y no permite elegir otra forma sobre la misma intención.
15. Paso 15: El administrador con acceso al módulo Zelle abre `/admin/panel/zelle/reportes`. El listado muestra el badge de origen y, para nuevo ingreso, el nombre del aspirante. El filtro por origen permite ver todos, solo regulares o solo nuevo ingreso.
16. Paso 16: El administrador abre el reporte. La vista muestra el origen, los datos del aspirante (nombre, correo, postulación), el desglose de la conversión, el comprobante y las acciones de verificar o rechazar.
17. Paso 17: Para verificar, el administrador ingresa el monto recibido en USD, que debe ser mayor o igual al `monto` del reporte (total con descuento NI); el formulario permite un excedente.
18. Paso 18: `Panel::verificar()` llama a `ZelleReportManager::cambiarEstado($id, 'verificar', 'Verificado', $usuario, $montoRecibido)`. El manager carga el reporte y su intención, y determina el origen por `pg_intenciones_pago.ni_inscripcion_id`.
19. Paso 19: Para un reporte NI, el manager valida que la intención tenga `ni_inscripcion_id` y que todos sus detalles activos contengan el mismo `NiInscripcionID`. Si falta el vínculo, hay un detalle ajeno o el detalle no corresponde, la verificación falla y no cambia el estado.
20. Paso 20: La validación reutiliza `IntencionesPagoModel::validarDetallesPago()` y `ProceNi()`. `ProceNi()` solo comprueba que la postulación exista y que la cabecera pertenezca a ella; no ejecuta `ProceDeuda()` ni `ProceInscr()` y no modifica deudas, inscripciones ni datos académicos.
21. Paso 21: En una transacción se actualiza el reporte a `Verificado` con `monto_pagado` y `excedente`; la intención a estado 8 con `monto_pagado`, `referencia` y `data_respuesta` (desglose completo); se registra auditoría e historial en `pg_pagos_realizados`.
22. Paso 22: Después del commit, y solo para un reporte NI verificado, el manager actualiza GHL de forma best-effort: si `ni_inscripciones.ghl_contact_id` existe, llama a `updateContact()` con `CF_ESTADO_CICLO_VIDA = 'Inscrito'`. No modifica `ghl_sincronizado`, no mueve oportunidades y no revierte la verificación si falla.
23. Paso 23: Después del commit, el manager envía el correo de verificación de forma best-effort al `correo` de `ni_inscripciones`, con el botón “Ir al Paso 4” hacia `/inscripciones/nuevo-ingreso/paso-4`. Si no hay correo válido o el envío falla, la verificación se completa y el fallo se audita.
24. Paso 24: El administrador vuelve al detalle con el mensaje de éxito. La intención queda en 8 y el reporte en `Verificado`; el aspirante ve el estado actualizado en el Paso 4 y puede consultar sus intentos.
25. Paso 25: Si el administrador rechaza, registra el motivo y `cambiarEstado($id, 'rechazar', 'Rechazado', $usuario, null, $motivo)`. El reporte pasa a `Rechazado`, la intención a 4 y el detalle `_ni` se conserva. No se envía cambio a GHL.
26. Paso 26: El correo de rechazo se envía al correo del aspirante con el motivo y el botón “Volver al Paso 4”. El aspirante puede iniciar un nuevo intento desde el Paso 4, sin reutilizar la intención rechazada.
27. Paso 27: Todas las acciones del panel son POST con CSRF; las pantallas de listado y detalle son GET y de solo lectura. La verificación y el rechazo son idempotentes para un reporte ya cerrado en el mismo estado.

## Flujos alternativos / variantes

### Reporte regular de Zelle

1. Paso 1: La intención tiene `ni_inscripcion_id` nulo y el reporte se crea con el flujo regular.
2. Paso 2: La conversión usa el descuento global `desc_pg_dolar` y el correo se resuelve en `aaentidad`, como hoy.
3. Paso 3: La verificación procesa deudas e inscripciones con `validarDetallesPago()`; no ejecuta `ProceNi()`, no envía GHL de nuevo ingreso y no usa el correo del aspirante.
4. Paso 4: El correo de verificación enlaza al recibo regular (`/Reportes/Recibo/{id}`) y el rechazo conserva su comportamiento actual.
5. Paso 5: Las columnas nuevas del desglose pueden quedar nulas; la vista y el correo regular no las requieren.

### Verificación con excedente

1. Paso 1: El administrador ingresa un monto recibido mayor al total con descuento.
2. Paso 2: El manager calcula `excedente = monto_recibido - monto_requerido` y lo persiste en el reporte y en el historial.
3. Paso 3: El correo muestra el monto pagado y el monto acreditado; la intención queda en 8.
4. Paso 4: No se ajusta la deuda ni se generan movimientos académicos por el excedente.

### Reporte NI sin contacto GHL

1. Paso 1: La postulación no tiene `ghl_contact_id` o el contacto no existe.
2. Paso 2: La verificación se completa y el reporte queda `Verificado`.
3. Paso 3: Se registra en auditoría `ghl_omitido` con el motivo; no se modifica `ghl_sincronizado`.
4. Paso 4: El correo al aspirante se intenta de forma independiente.

### Reporte NI sin correo válido

1. Paso 1: `ni_inscripciones.correo` está vacío o no pasa `FILTER_VALIDATE_EMAIL`.
2. Paso 2: La verificación o el rechazo se completan.
3. Paso 3: No se envía correo; se registra en auditoría `notificacion_fallida` con el motivo.
4. Paso 4: No se usa el correo de pagos ni `aaentidad` como respaldo para este aviso.

### Rechazo de un reporte NI

1. Paso 1: El administrador indica un motivo no vacío y confirma el rechazo.
2. Paso 2: El reporte pasa a `Rechazado` y la intención a estado 4.
3. Paso 3: El detalle `_ni` se conserva; no se elimina ni se marca `borrado_dt`, a diferencia del flujo regular.
4. Paso 4: No se envía cambio a GHL.
5. Paso 5: Se envía el correo de rechazo con el motivo y el enlace al Paso 4.
6. Paso 6: El aspirante ve el estado `reintento` y puede crear una intención nueva; la rechazada no se reutiliza.

### Reporte ya verificado o rechazado

1. Paso 1: El reporte ya está en `Verificado` o `Rechazado`.
2. Paso 2: Si la acción solicita el mismo estado, el manager devuelve el resultado actual con un mensaje idempotente.
3. Paso 3: No se vuelve a enviar GHL ni correo y no se duplica el historial.
4. Paso 4: Si la acción solicita el estado opuesto, responde 409 y no modifica nada.

### Reporte NI con vínculo inválido

1. Paso 1: La intención tiene `ni_inscripcion_id` nulo, el detalle no contiene `NiInscripcionID` o el valor no coincide con la cabecera.
2. Paso 2: La validación NI falla antes de la transacción.
3. Paso 3: Se registra `verificacion_fallida` en auditoría y se devuelve un error 422/500.
4. Paso 4: El reporte permanece `Sin confirmar` y la intención en 7; no se envía GHL ni correo.

### Reporte NI con detalle de deuda o inscripción

1. Paso 1: La intención NI contiene un detalle con `AdMovID` o `CeEstudiInscrID`, o un detalle sin `NiInscripcionID`.
2. Paso 2: La validación NI lo rechaza por considerarlo inconsistente.
3. Paso 3: No se ejecutan `ProceDeuda()` ni `ProceInscr()`.
4. Paso 4: El reporte queda pendiente y se audita el error.

### Reporte NI anterior a esta feature

1. Paso 1: El reporte existe pero sus columnas de desglose son nulas.
2. Paso 2: La verificación usa el `monto`, `monto_bs` y `tasa` persistidos; los campos de desglose no disponibles se conservan nulos.
3. Paso 3: No se recalcula el monto verificado ni se modifica el reporte histórico.
4. Paso 4: El correo y GHL se comportan como en un reporte NI nuevo.

### Tasa no disponible

1. Paso 1: `pg_tasa_dia` no tiene una tasa válida para la sede.
2. Paso 2: `convertirBsAdolar()` devuelve error.
3. Paso 3: El reporte no se registra, se elimina el comprobante si ya se guardó y la intención permanece en 2.
4. Paso 4: El aspirante recibe el mensaje de error y puede reintentar.

### Envío duplicado o carrera entre administradores

1. Paso 1: Dos administradores procesan el mismo reporte o el mismo formulario se reenvía.
2. Paso 2: El bloqueo optimista del reporte exige que siga en `Sin confirmar`; solo una transición gana.
3. Paso 3: La segunda operación devuelve el estado actual si coincide o 409 si es el estado opuesto.
4. Paso 4: No se duplican GHL, correo, auditoría ni historial.

### Filtro por origen en el panel

1. Paso 1: El administrador elige “Todos”, “Regulares” o “Nuevo ingreso” en el listado.
2. Paso 2: El manager aplica `ni_inscripcion_id IS NULL` o `IS NOT NULL` según corresponda.
3. Paso 3: El filtro se conserva al exportar PDF o Excel.
4. Paso 4: Los reportes regulares conservan sus columnas y totales; los NI muestran su badge y datos de aspirante.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Sesión de nuevo ingreso ausente o inválida al reportar | Filtro `nuevoIngresoAuth:4` y comprobación defensiva | Redirección a `/inscripciones/nuevo-ingreso`; en AJAX 401 | Sin reporte; no se escribe |
| Intención ajena, inexistente o de otra postulación | `obtenerIntencion($id, $niId)` devuelve null | Redirección a `/paso-4` con mensaje genérico | Sin escritura; no se revela el id |
| Intención en estado distinto de `pagando` | `estados_id` distinto de 2 | Redirección a `/paso-4` con mensaje según el estado | Estado intacto |
| Forma Zelle no permitida o inactiva | `esFormaPagoPermitida()` o catálogo | Redirección a `/paso-4` con mensaje | Sin escritura |
| Tasa de la sede ausente o menor o igual a 0 | `convertirBsAdolar()` devuelve error | Mensaje de error; no se registra el reporte | Intención en 2; comprobante eliminado |
| Descuento NI ausente, cero o inválido | Normalización en el servicio | Se aplica 0% de descuento; no se bloquea | Reporte con descuento 0 |
| Comprobante faltante, inválido, sobredimensionado o con MIME no permitido | `validarObligatorios()`/`validarComprobante()` | Mensaje de error de la pasarela | Intención en 2 |
| Referencia de Zelle duplicada | `referenciaExiste()` | Mensaje de referencia ya registrada | Intención en 2 |
| Límite de pendientes alcanzado | `contarPendientes()` | Mensaje con el límite configurado | Intención en 2 |
| Fallo de base de datos al registrar el reporte | Transacción de `postPayment()` | Rollback y eliminación del comprobante | Intención en 2 |
| Reporte inexistente en el panel | `getReporte()`/`cambiarEstado()` | Redirección con “Reporte de pago no encontrado” | Sin escritura |
| Reporte ya verificado o rechazado, misma acción | Comparación de estado terminal | Respuesta idempotente con el estado actual; sin reenvíos | Estado terminal intacto |
| Reporte ya cerrado, acción opuesta | Comparación de estado terminal | Error 409 “no admite más acciones” | Estado terminal intacto |
| Monto recibido ausente al verificar | `$montoRecibido === null` | Error 422 “Debe indicar el monto recibido” | Reporte `Sin confirmar`; intención 7 |
| Monto recibido menor al total con descuento | Comparación con `reporte.monto` | Error 422 con el monto requerido | Reporte `Sin confirmar`; intención 7 |
| Motivo de rechazo vacío | `trim($motivo) === ''` | Error 422 “Debe indicar el motivo” | Reporte `Sin confirmar`; intención 7 |
| Intención NI sin `ni_inscripcion_id` | Consulta de la intención | Error de validación NI; auditoría `verificacion_fallida` | Reporte `Sin confirmar`; intención 7 |
| Detalle NI ausente, sin `NiInscripcionID` o con valor distinto | Validación de detalles NI | Error de validación NI; no se procesan deudas | Reporte `Sin confirmar`; intención 7 |
| Detalle de deuda o inscripción en una intención NI | Validación de detalles NI | Se rechaza por inconsistencia; no se ejecuta `ProceDeuda()`/`ProceInscr()` | Reporte `Sin confirmar`; intención 7 |
| Postulación del detalle NI inexistente | `ProceNi()` devuelve false | Error de validación NI | Reporte `Sin confirmar`; intención 7 |
| Sede sin grupo de conexión | `getBaseDatosBySucursal()` devuelve vacío | Error controlado; auditoría | Reporte `Sin confirmar`; intención 7 |
| GHL sin `ghl_contact_id`, contacto inexistente o API con error | Respuesta de GHL | La verificación continúa; auditoría `ghl_omitido` o `ghl_fallido` | Reporte `Verificado`; intención 8 |
| Correo NI vacío, inválido o fallo de envío | Validación de correo o excepción de PHPMailer | La operación continúa; auditoría `notificacion_fallida` | Reporte `Verificado`/`Rechazado` |
| Fallo de correo en un reporte regular | Excepción de PHPMailer | Se conserva el comportamiento actual: best-effort y auditoría | Estado regular intacto |
| Fallo al consultar `pg_pagos_realizados` o auditoría | Excepción de base | La transacción principal se revierte si ocurre dentro de ella | Sin cambio parcial |
| Error inesperado en el panel | `catch (\RuntimeException)` en `Panel::cambiarEstado()` | Flash de error; log técnico | Sin escritura parcial |
| Filtro de origen con valor no permitido | Whitelist `todos`/`ni`/`regular` | Se ignora el filtro o se usa `todos` | Listado sin error |
| Reporte NI histórico sin columnas de desglose | Campos nulos | Se muestran solo los datos disponibles; no se recalcula | Verificación con datos persistidos |

## Reglas de negocio y validaciones

- El origen de un pago se determina exclusivamente por `pg_intenciones_pago.ni_inscripcion_id`. No se usa la cédula, el nombre, la descripción ni un parámetro del cliente.
- Para nuevo ingreso, `desc_pg_dolar_ni` reemplaza al descuento global. La conversión se hace con la tasa de `pg_tasa_dia` de la sede de la intención.
- Un descuento NI `0`, ausente o no numérico se normaliza a `0.0`; no se rechaza el pago por esa causa. Una tasa ausente o menor o igual a cero sí impide el registro.
- El monto del reporte es el total final en USD con el descuento aplicable. `monto_bs` es el equivalente en bolívares del monto con descuento. Ambos se calculan y persisten en el servidor; no se aceptan montos del cliente.
- El desglose persistido incluye `tasa`, `descuento` (porcentaje), `total_sin_descuento`, `monto_descuento`, `total_final` (en `monto`) y `monto_bs`; se replica en `pg_zelle_reportes`, en el `payload` de auditoría y en `data_respuesta` de la intención al verificar.
- Al registrar el reporte, la intención queda en 7 y el reporte en `Sin confirmar`. No se marca como aprobado ni se envía GHL en ese momento.
- La verificación exige `monto_recibido >= reporte.monto`; el excedente se calcula y persiste. No se acepta un monto menor.
- En un reporte NI, todos los detalles activos deben contener `NiInscripcionID` igual a `ni_inscripcion_id` de la cabecera. Si un detalle no cumple, la verificación falla de forma cerrada.
- `ProceNi()` solo valida que la postulación exista y que la cabecera pertenezca a ella. No marca deudas, no marca inscripciones, no actualiza Orbis y no escribe en la base de la sede.
- En un reporte NI, la verificación no ejecuta `ProceDeuda()` ni `ProceInscr()`, aunque existan detalles con esas claves; la validación previa lo impide.
- Verificar un reporte NI deja el reporte en `Verificado` y la intención en 8. Rechazarlo deja el reporte en `Rechazado` y la intención en 4.
- El rechazo NI conserva el detalle `_ni` y no lo borra ni lo marca como eliminado. El rechazo regular conserva su liberación actual de detalles.
- La verificación NI actualiza GHL solo después del commit y solo si la acción es verificar. Actualiza `CF_ESTADO_CICLO_VIDA` a `Inscrito` en el contacto de `ni_inscripciones.ghl_contact_id`. No modifica `ghl_sincronizado`, no mueve oportunidades y no se ejecuta al rechazar.
- Los fallos de GHL y correo son best-effort: no revierten el pago ni cambian el estado. Se registran en `pg_zelle_auditoria` con el motivo y el destinatario/contacto cuando aplique.
- El correo NI se envía solo a `ni_inscripciones.correo`. No se usa `aaentidad`, no se usa el correo de pagos como respaldo y no se envía si el correo está vacío o es inválido.
- Los correos NI enlazan a `/inscripciones/nuevo-ingreso/paso-4` tanto en verificación como en rechazo. Los correos regulares conservan el enlace al recibo.
- El panel muestra un badge de origen y los datos del aspirante (nombre, correo y `ni_inscripcion_id`) solo para reportes NI. El filtro por origen se aplica al listado, al resumen y a las exportaciones.
- Las vistas escapan toda salida con `esc()`; los atributos usan `esc(..., 'attr')`. No se insertan datos de usuario sin escapar.
- La verificación y el rechazo son idempotentes por estado: la misma acción no reenvía GHL ni correo; la acción opuesta devuelve 409.
- No se agregan rutas, filtros, CSRF, dependencias ni cambios en `vendor/`, `system/` o `public/vendor/`.
- La migración del desglose es idempotente (`fieldExists`) y no reescribe datos existentes. No se hace backfill de reportes históricos.
- No se modifica el comportamiento del flujo regular de Zelle: descuento global, deudas/inscripciones, recibo y correo regular se conservan.

## Contratos y diseño propuesto

### `PagosZelleServices`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `prePayment(array $data): array` | Preparar la vista de Zelle con la conversión correcta. | Solo lectura; usa `monto_total`, `descuento` y `db`. |
| `postPayment(array $data): string` | Validar el reporte, convertir, guardar comprobante y registrar reporte/intención. | Escritura transaccional; deja intención en 7. |
| `calcularConversionPago(float $montoBs, ?float $descuento, ?string $db): array` | Método interno reutilizable para convertir con la tasa de la sede y el descuento indicado. | Sin escritura; facilita pruebas unitarias. |

- `prePayment()` usa `convertirBsAdolar($data['monto_total'], null, $data['descuento'] ?? null, $data['db'] ?? null)`. Si no llegan `descuento` o `db`, conserva el comportamiento actual (global/sesión).
- `postPayment()` usa el descuento recibido en `$data['descuento']` cuando es numérico; si es nulo, usa el descuento global como respaldo del flujo regular. No usa `desc_pg_dolar` para una intención NI.
- `postPayment()` persiste en `pg_zelle_reportes`: `monto` (total final USD), `tasa`, `monto_bs`, `descuento`, `total_sin_descuento` y `monto_descuento`.
- El `payload` de auditoría y `pg_pagos_realizados` incluyen el mismo desglose y la referencia.
- La respuesta exitosa conserva `estatus = success`, `gestionado = true`, `referencia`, `monto` y `response`.

### `IntencionesPagoModel`

- No se modifica `ProceNi()`. Ya valida la postulación y la cabecera, y no marca deudas.
- `validarDetallesPago()` se reutiliza para reportes NI después de la validación de vínculo del manager. No se cambia su contrato.
- No se modifica `actualizaStatus()` en este cambio.

### `ZelleReportManager`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `baseReportesQuery()` | Incluir `ni_inscripcion_id` y datos del aspirante. | Solo lectura; join izquierdo con `ni_inscripciones`. |
| `aplicarFiltros()` | Aplicar el filtro de origen `ni`/`regular`. | Solo lectura. |
| `validarDetallesNuevoIngreso(int $intencionId, int $niId): array` | Validar que todos los detalles activos pertenezcan a la postulación y reutilizar `validarDetallesPago()`. | Solo lectura; no marca deudas. |
| `actualizarGhlVerificacion(array $reporte, int $niId): bool` | Actualizar el ciclo de vida del contacto a `Inscrito`. | Best-effort; auditoría; no revierte. |
| `emailAspirante(int $niId): ?array` | Resolver nombre y correo desde `ni_inscripciones`. | Solo lectura. |
| `construirAvisoVerificacion()` | Elegir destinatario y CTA según origen. | Sin envío; prepara HTML. |
| `construirAvisoRechazo()` | Elegir destinatario y CTA según origen. | Sin envío; prepara HTML. |
| `cambiarEstado()` | Orquestar validación, transición, auditoría, historial, GHL y correo. | Escritura transaccional y efectos best-effort posteriores. |

- `baseReportesQuery()` agrega `LEFT JOIN ni_inscripciones ni ON ni.id = pg_intenciones_pago.ni_inscripcion_id` y selecciona `pg_intenciones_pago.ni_inscripcion_id AS ni_inscripcion_id`, `ni.nombre AS ni_nombre`, `ni.apellido AS ni_apellido` y `ni.correo AS ni_correo`.
- `aplicarFiltros()` acepta `origen` con valores `todos` (predeterminado), `ni` (`IS NOT NULL`) y `regular` (`IS NULL`). Un valor inválido se trata como `todos`.
- `cambiarEstado()` consulta la intención para obtener `ni_inscripcion_id` y `AASUCURSID`. Si es NI y la acción es verificar, llama a `validarDetallesNuevoIngreso()` antes de la transacción. Si es NI y la acción es rechazar, omite el borrado de detalles.
- La transacción actualiza reporte, intención, auditoría e historial. GHL y correo se ejecutan después del commit.
- `actualizarGhlVerificacion()` no se ejecuta si el reporte es regular, si la acción es rechazar, si falta `ghl_contact_id` o si la postulación no existe. Registra `ghl_actualizado`, `ghl_omitido` o `ghl_fallido`.
- `notificarResultado()` conserva su firma y su carácter best-effort. Para NI usa `emailAspirante()` y el CTA al Paso 4; para regular usa `emailEstudiante()` y el recibo.
- La auditoría de correo conserva `notificacion_enviada`/`notificacion_fallida` y agrega el destinatario y el tipo de enlace en el `payload`.

### `Admin\Panel`

- `filtrosReportes()` agrega `'origen' => (string) $this->request->getGet('origen')`.
- `reportes()`, `exportarPdf()` y `exportarExcel()` conservan el filtro y lo propagan al manager y a los enlaces de exportación.
- No se agregan rutas ni filtros. Las acciones siguen siendo POST con CSRF.

### Migración

- Nueva migración idempotente `2026-10-28-000101_AddDesgloseDescuentoToPgZelleReportes.php`.
- Agrega a `pg_zelle_reportes`, si no existen:
  - `descuento` `DOUBLE(5,2)` nulo, después de `tasa`.
  - `total_sin_descuento` `DOUBLE(10,2)` nulo, después de `descuento`.
  - `monto_descuento` `DOUBLE(10,2)` nulo, después de `total_sin_descuento`.
- Se registra en `app/Commands/InitPrincipalDb.php` después de `2026-10-27-000100_AlterIdentificacionPgIntencionesPago.php`.
- No se hace backfill. Las columnas son nulas para reportes históricos y la vista debe tolerarlo.

### Vistas y correos

| Archivo | Responsabilidad |
| --- | --- |
| `app/Views/admin/zelle/reportes.php` | Filtro por origen, columna/badge de origen y nombre del aspirante en reportes NI. |
| `app/Views/admin/zelle/reporte.php` | Badge y bloque de aspirante, desglose de conversión y formulario de verificación con el monto requerido. |
| `app/Views/admin/zelle/reportes_pdf.php` | Columna de origen cuando aplique; conserva el diseño actual. |
| `app/Views/emails/zelle_recibo.php` | CTA configurable (`cta_url`/`cta_texto`) y texto condicional para NI; por defecto conserva “Ver recibo”. |
| `app/Views/emails/zelle_rechazo.php` | Bloque CTA opcional para NI; si no se pasa, conserva el correo regular sin botón. |

- Las plantillas usan `$cta_url ?? $recibo_url` y `$cta_texto ?? 'Ver recibo'` para no romper el correo regular.
- Para NI, el CTA es `base_url('inscripciones/nuevo-ingreso/paso-4')` y el texto “Ir al Paso 4” (verificación) o “Volver al Paso 4” (rechazo).
- Los datos del aspirante se muestran solo en el panel protegido; no se exponen en el portal público.
- No se modifica `public/css/tailwind-v4.css`; se usan clases Tailwind existentes.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Modificar | `app/Libraries/Payments/PagosZelleServices.php` | Aplicar descuento NI, convertir con la sede y persistir el desglose. |
| Crear | `app/Database/Migrations/2026-10-28-000101_AddDesgloseDescuentoToPgZelleReportes.php` | Columnas de desglose en `pg_zelle_reportes`. |
| Modificar | `app/Commands/InitPrincipalDb.php` | Registrar la migración idempotente. |
| Modificar | `app/Libraries/ZelleReportManager.php` | Origen NI, validación, rechazo con detalle, GHL, correo y filtro. |
| Modificar | `app/Controllers/Admin/Panel.php` | Filtro de origen y propagación a exportaciones. |
| Modificar | `app/Views/admin/zelle/reportes.php` | Badge, datos del aspirante y filtro. |
| Modificar | `app/Views/admin/zelle/reporte.php` | Origen, desglose y monto a verificar. |
| Modificar | `app/Views/admin/zelle/reportes_pdf.php` | Columna de origen en exportación. |
| Modificar | `app/Views/emails/zelle_recibo.php` | CTA condicional al Paso 4. |
| Modificar | `app/Views/emails/zelle_rechazo.php` | CTA opcional al Paso 4. |
| Crear | `tests/app/Libraries/Payments/PagosZelleServicesTest.php` | Conversión con descuento NI y respaldo regular. |
| Crear | `tests/app/Integration/ZelleNuevoIngresoTest.php` | Verificación, rechazo, aislamiento, idempotencia, GHL y correo con SQLite y dobles. |
| Crear | `tests/app/Database/Migrations/DesgloseZelleMigrationTest.php` | Idempotencia de la migración y conservación de datos existentes. |
| Documentar | `docs/features/006-zelle-verificacion-nuevo-ingreso/plan.md` | Este plan. |

No se modifican rutas, filtros, `PaymentService`, `PaymentOrchestrator` (salvo que la implementación detecte que no reenvía `descuento`, en cuyo caso se corrige y se documenta), `NuevoIngresoPagoService`, `ProceNi()`, `ni_inscripciones`, la SPA ni la API.

## Criterios de finalización

- [x] `PagosZelleServices::prePayment()` y `postPayment()` usan `desc_pg_dolar_ni` para una intención NI y no aplican `desc_pg_dolar` en ese caso.
- [x] Un `desc_pg_dolar_ni` ausente, cero o inválido se normaliza a 0% sin bloquear el pago; una tasa ausente o menor o igual a cero sí bloquea y deja la intención en 2.
- [x] El reporte NI guarda `monto` final con descuento, `tasa`, `monto_bs` equivalente y el desglose `descuento`, `total_sin_descuento` y `monto_descuento`.
- [x] El desglose se replica en el `payload` de auditoría y en `data_respuesta` de la intención al verificar.
- [x] Registrar un reporte NI deja la intención en 7 y el reporte en `Sin confirmar`, con auditoría e historial.
- [x] El listado y el detalle del panel muestran badge de origen, nombre/correo del aspirante y el filtro por origen; el filtro se conserva en PDF y Excel.
- [x] Verificar un reporte NI deja el reporte en `Verificado` y la intención en 8, con `monto_pagado`, `excedente`, `referencia`, auditoría e historial.
- [x] La verificación NI exige que todos los detalles activos contengan el mismo `NiInscripcionID` de la cabecera; un detalle ausente, ajeno o de deuda/inscripción falla de forma cerrada.
- [x] `ProceNi()` no marca deudas ni inscripciones y no se ejecutan `ProceDeuda()`/`ProceInscr()` en un reporte NI.
- [x] Rechazar un reporte NI deja el reporte en `Rechazado`, la intención en 4 y conserva el detalle `_ni` sin borrarlo ni marcarlo como eliminado.
- [x] Al verificar un reporte NI se actualiza GHL `CF_ESTADO_CICLO_VIDA = 'Inscrito'` si existe `ghl_contact_id`; no se modifica `ghl_sincronizado` ni se mueven oportunidades.
- [x] Al rechazar un reporte NI no se envía cambio a GHL.
- [x] Los fallos o la ausencia de GHL no bloquean la verificación y se auditan como `ghl_omitido` o `ghl_fallido`.
- [x] El correo NI se envía solo a `ni_inscripciones.correo`; si falta o es inválido, la operación se completa y se audita `notificacion_fallida`.
- [x] Los correos NI de verificación y rechazo enlazan a `/inscripciones/nuevo-ingreso/paso-4`; los regulares conservan el enlace al recibo y su comportamiento.
- [x] Un reporte regular conserva la conversión global, el procesamiento de deudas/inscripciones, el recibo y el correo actual; no ejecuta `ProceNi()` ni la lógica GHL/correo NI.
- [x] Un reporte NI solo modifica su propia intención y sus detalles; una intención regular con la misma cédula no cambia.
- [x] La verificación y el rechazo son idempotentes para el mismo estado y devuelven 409 para la acción opuesta, sin duplicar GHL, correo, auditoría ni historial.
- [x] La migración es idempotente, está registrada en `InitPrincipalDb` y no reescribe datos existentes.
- [x] Las pruebas de conversión, verificación, rechazo, aislamiento, idempotencia, GHL y correo pasan con SQLite y dobles.
- [x] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [x] `graphify update .` se ejecuta después de los cambios de código.
- [x] No se agregaron rutas, filtros, CSRF, dependencias ni cambios en `vendor/`, `system/` o `public/vendor/`.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Alcance | Un solo plan con fases internas A, B y C. |
| Descuento NI | `desc_pg_dolar_ni` reemplaza al descuento global en Zelle NI, tanto en la vista previa como en el monto reportado. |
| Rechazo NI | Intención en estado 4 y detalle `_ni` conservado; no se borra ni se marca deudas. |
| Enlaces de correo | Verificación y rechazo enlazan a `/inscripciones/nuevo-ingreso/paso-4`. |
| Destinatario | Solo `ni_inscripciones.correo`; sin respaldo en `aaentidad` ni en el correo de pagos. |
| Panel | Badge de origen, datos del aspirante y filtro por origen en listado, detalle y exportaciones. |
| Efectos de verificar | Pago, historial y auditoría; además, actualización de GHL a `Inscrito`. Sin Orbis ni cambios en `paso_actual`. |
| Monto a verificar | La misma regla que el flujo regular, aplicada al total NI con su propio porcentaje de descuento; se permite excedente. |
| Auditoría | Desglose completo en reporte, auditoría y `data_respuesta`. |
| Pruebas | Unitarias de conversión e integración con SQLite para verificación, rechazo y aislamiento. |
| GHL al rechazar | No se envía cambio. |
| Fallo de GHL | Best-effort y auditoría; no revierte el pago. |
| Plantillas | Reutilizar las existentes con CTA condicional; no duplicar HTML. |
| “Estado 7” | Intención en 7 y reporte en `Sin confirmar`; no se agrega un estado nuevo. |
| Correo ausente | La operación se completa y se audita el fallo. |
| `ghl_sincronizado` | No se modifica al actualizar el ciclo de vida. |
| Aislamiento | NI solo afecta su intención; regular no ejecuta `ProceNi`; rechazo NI conserva detalle; el vínculo NI debe ser válido. |

## Riesgos y deuda técnica

- **Valor `Inscrito` en GHL:** si el campo de ciclo de vida no tiene esa opción o la API la rechaza, la verificación se completa pero la actualización queda auditada como fallida. Confirmar la configuración del campo antes de desplegar.
- **Sin reintento automático:** un fallo de GHL o correo después del commit no se reintenta. Queda auditado y requiere una acción manual o una feature futura de cola/reintento.
- **Reportes históricos:** la migración no hace backfill. Los reportes NI anteriores tendrán columnas nulas y el detalle del desglose no estará completo.
- **Migración en producción:** las columnas son nuevas y nullable; aun así, debe aplicarse con respaldo y sin ejecutar `down()` sobre datos reales.
- **Descuento configurado en cero:** `desc_pg_dolar_ni` se crea en `0`. Si operaciones no lo configura, el aspirante pagará el total sin descuento; es una decisión operativa, no un error del flujo.
- **PII en el panel:** el nombre y correo del aspirante se muestran a usuarios con acceso al módulo Zelle. No se agrega una nueva exposición pública, pero debe revisarse la política de acceso.
- **Dependencia de `ni_inscripciones`:** el correo y el contacto GHL se leen de la base principal. Si la postulación no existe o está incompleta, el pago se verifica pero las notificaciones se omiten y se auditan.
- **Compatibilidad del flujo regular:** las plantillas y el manager se comparten. La implementación debe usar valores por defecto y pruebas de regresión para no cambiar el correo, el recibo ni el procesamiento de deudas regular.
- **Pruebas de archivo:** `postPayment()` depende de `is_uploaded_file()` y del guardado en disco; la conversión se prueba extrayendo `calcularConversionPago()` y el flujo completo de archivo se valida en integración manual o con un doble específico.
- **Idempotencia de notificaciones:** si el reporte ya está cerrado, no se reenvían GHL ni correo. Esto evita duplicados, pero no reintenta fallos.
- **Concurrencia:** se conserva el bloqueo optimista del reporte. No se rediseña la creación de reportes ni la unicidad de referencias.
- **CSRF:** el panel ya lo aplica; el flujo de nuevo ingreso conserva su deuda técnica de CSRF documentada en FEAT-005.
- **Sin MEMORY.md:** este checkout no tiene `MEMORY.md`; no se actualiza. Si aparece, debe registrarse la nueva feature y su estado.

## Preguntas abiertas

No quedan preguntas bloqueantes. Los siguientes puntos se registran como supuestos a validar antes del despliegue:

- Confirmar que el campo GHL de ciclo de vida acepta el valor `Inscrito`.
- Confirmar que operaciones configurará `desc_pg_dolar_ni` con el porcentaje vigente.
- Confirmar que el correo de `ni_inscripciones` es el canal oficial para los avisos de pago.
- Confirmar que el negocio acepta que un fallo de GHL o correo no bloquee la verificación y quede solo auditado.

Si alguno de estos supuestos cambia, se debe actualizar este plan antes de implementar la fase correspondiente.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-006 tras revisar `PagosZelleServices`, `PaymentOrchestrator`, `NuevoIngresoPagoService`, `ZelleReportManager`, `IntencionesPagoModel::ProceNi()`, `Admin\Panel`, las vistas de Zelle, las plantillas de correo y las migraciones de `pg_zelle_reportes`. Se acordó un solo plan con tres fases, descuento NI exclusivo, verificación a 8, rechazo a 4 con detalle conservado, GHL a `Inscrito`, correo desde `ni_inscripciones` y enlace al Paso 4. | opencode (agente) |
