# Prototipo de ejecución — FEAT-006 Zelle de nuevo ingreso: conversión, verificación administrativa y notificaciones

- **Rama:** p-feature/zelle-verificacion-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/006-zelle-verificacion-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado
- **Consolidado en:** feature/desacoplar-contructor-pagos
- **Fecha de consolidación:** 2026-10-28

## Resumen

Se completó el flujo de Zelle para nuevo ingreso: la conversión usa la tasa de la sede y `desc_pg_dolar_ni`, el reporte persiste el desglose completo y queda pendiente mientras la intención pasa al estado 7. El panel administrativo identifica el origen, muestra los datos del aspirante y permite verificar (estado 8) o rechazar (estado 4) sin marcar deudas. Al verificar se actualiza GHL de forma best-effort y se notifica al correo de la postulación con enlace al Paso 4; el rechazo conserva el detalle `_ni` y también notifica al aspirante.

## Tareas realizadas

- [x] Fase A — Conversión y reporte: `PagosZelleServices` aplica descuento NI, usa la conexión de la sede y persiste `descuento`, `total_sin_descuento` y `monto_descuento`; migración idempotente registrada en `InitPrincipalDb`.
- [x] Fase A — Pruebas unitarias de conversión con descuento NI, cero, negativo, nulo (global) y tasa ausente.
- [x] Fase B — `ZelleReportManager` determina el origen por `ni_inscripcion_id`, valida el vínculo de todos los detalles `_ni` y conserva el detalle al rechazar.
- [x] Fase B — Verificación NI deja reporte `Verificado` e intención 8 con monto pagado, excedente, referencia, `data_respuesta`, auditoría e historial.
- [x] Fase B — Panel: filtro por origen, badges de origen, datos del aspirante, desglose de conversión y monto requerido en PDF/Excel.
- [x] Fase C — GHL best-effort con `CF_ESTADO_CICLO_VIDA = 'Inscrito'` solo al verificar NI; no toca `ghl_sincronizado` ni oportunidades.
- [x] Fase C — Correo al `correo` de `ni_inscripciones` con CTA al Paso 4 en verificación y rechazo; fallos auditados sin revertir el pago.
- [x] Pruebas de integración de verificación, rechazo, aislamiento, idempotencia, GHL y correo con SQLite y dobles.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `prePayment()` y `postPayment()` usan `desc_pg_dolar_ni` en NI y no aplican `desc_pg_dolar` | `PagosZelleServicesTest` (conversión NI/global) | ok |
| Descuento NI ausente/cero/inválido se normaliza a 0; tasa inválida bloquea | Pruebas de descuento cero, negativo, nulo y tasa ausente | ok |
| Reporte NI guarda monto final, tasa, monto Bs y desglose | Revisión de `postPayment()` y payload/reporte | ok |
| Desglose replicado en auditoría y `data_respuesta` | `ZelleNuevoIngresoTest::testVerificarNiActualizaPagoGhlYCorreo` | ok |
| Registrar reporte deja intención 7 y reporte `Sin confirmar` | Flujo existente conservado; prueba de verificación parte de ese estado | ok |
| Panel muestra origen, aspirante y filtro; filtro en PDF/Excel | Revisión de vistas, `Panel::filtrosReportes()` y exportaciones | ok |
| Verificar NI deja reporte `Verificado` e intención 8 | `testVerificarNiActualizaPagoGhlYCorreo` | ok |
| Todos los detalles activos deben tener el mismo `NiInscripcionID` | `testVerificarNiConDetalleAjenoFallaDeFormaCerrada` | ok |
| `ProceNi()` no marca deudas ni se ejecuta `ProceDeuda()`/`ProceInscr()` | `testVerificarNiConDetalleDeDeudaFallaSinProcesarla`; `ProceNi()` sin cambios | ok |
| Rechazar NI deja reporte `Rechazado`, intención 4 y conserva detalle | `testRechazarNiConservaElDetalleYEnviaCorreo` | ok |
| Verificar NI actualiza GHL a `Inscrito` sin tocar `ghl_sincronizado` | `testVerificarNiActualizaPagoGhlYCorreo` | ok |
| Rechazar NI no envía cambio a GHL | `testRechazarNiConservaElDetalleYEnviaCorreo` | ok |
| Fallos/ausencia de GHL no bloquean y se auditan | `testVerificarNiSinContactoGhlSeAuditaSinRevertir` | ok |
| Correo NI solo a `ni_inscripciones.correo`; ausencia se audita | `testVerificarNiSinCorreoAuditaElFallo` | ok |
| Correos NI enlazan al Paso 4; regulares conservan el recibo | Pruebas de contenido de aviso y revisión de plantillas | ok |
| Reporte regular conserva comportamiento | Validación regular sin cambios; pruebas base de `Paso4PagoTest` y `PaymentOrchestratorTest` | ok |
| NI solo modifica su intención; regular con misma cédula no cambia | `testAislamientoYFiltroPorOrigen` | ok |
| Idempotencia por estado y 409 para acción opuesta | `testIdempotenciaNoReenviaGhlNiCorreo`, `testAccionOpuestaDevuelve409` | ok |
| Migración idempotente y registrada, sin reescribir datos | `DesgloseZelleMigrationTest` y revisión de `InitPrincipalDb` | ok |
| Pruebas de conversión, verificación, rechazo, aislamiento, idempotencia, GHL y correo | Suites `PagosZelleServicesTest` y `ZelleNuevoIngresoTest` | ok |
| `php -l` sin errores en archivos nuevos/modificados | Ejecutado sobre 12 archivos PHP | ok |
| `graphify update .` ejecutado | Ejecutado al cierre | ok |
| Sin rutas, filtros, CSRF, dependencias ni cambios en `vendor/`, `system/`, `public/vendor/` | Revisión de `git status` | ok |

## Flujos cubiertos

- **Flujo normal:** reporte NI con descuento de la sede, verificación a estado 8, GHL, correo al aspirante y CTA al Paso 4.
- **Flujos alternativos:** excedente al verificar, reporte NI sin contacto GHL, reporte NI sin correo válido, rechazo NI con detalle conservado, reporte ya cerrado en el mismo estado y filtro por origen.
- **Control de errores:** detalle ausente/ajeno, detalle de deuda o inscripción en una intención NI, monto recibido menor, motivo vacío, tasa ausente, fallo de GHL y fallo de correo. Todos dejan estado consistente y auditoría cuando aplica.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Database/Migrations/2026-10-28-000101_AddDesgloseDescuentoToPgZelleReportes.php` | Agregar columnas nullable del desglose de forma idempotente. |
| `tests/app/Libraries/Payments/PagosZelleServicesTest.php` | Pruebas de conversión con descuento NI y respaldo regular. |
| `tests/app/Integration/ZelleNuevoIngresoTest.php` | Pruebas de verificación, rechazo, aislamiento, idempotencia, GHL y correo. |
| `tests/app/Database/Migrations/DesgloseZelleMigrationTest.php` | Pruebas de idempotencia y conservación de datos de la migración. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Commands/InitPrincipalDb.php` | Registrar la migración `2026-10-28-000101`. |
| `app/Libraries/Payments/PagosZelleServices.php` | Descuento NI, conexión de sede, desglose persistido y `calcularConversionPago()`. |
| `app/Libraries/ZelleReportManager.php` | Origen NI, validación cerrada, rechazo con detalle conservado, GHL, correos y filtro por origen. |
| `app/Controllers/Admin/Panel.php` | Filtro `origen` y columna de origen en Excel. |
| `app/Views/admin/zelle/reportes.php` | Filtro, badge de origen y datos del aspirante. |
| `app/Views/admin/zelle/reporte.php` | Origen, bloque del aspirante, desglose y monto requerido. |
| `app/Views/admin/zelle/reportes_pdf.php` | Filtro y columna de origen. |
| `app/Views/emails/zelle_recibo.php` | CTA configurable y texto condicional para NI. |
| `app/Views/emails/zelle_rechazo.php` | CTA opcional al Paso 4 para NI. |
| `docs/features/006-zelle-verificacion-nuevo-ingreso/plan.md` | Estado y criterios actualizados. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** ninguno. Se conservan `GET /admin/panel/zelle/reportes`, `GET /admin/panel/zelle/reporte/{id}`, `POST .../verificar` y `POST .../rechazar` con `adminPanel:module=zelle`.
- **Permisos y validaciones:** el panel sigue exigiendo sesión administrativa y módulo Zelle; las acciones siguen siendo POST con CSRF. La identidad del aspirante y su sede salen de `ni_inscripciones`/`pg_intenciones_pago`, no del cliente.
- **Migraciones/seeds:** migración idempotente `2026-10-28-000101` registrada en `InitPrincipalDb`; no hay backfill. Verificada con SQLite y con `fieldExists`/caché de columnas.
- **Compatibilidad:** los reportes regulares conservan descuento global, procesamiento de deudas/inscripciones, recibo y correo. Los reportes históricos NI sin desglose se muestran con `-` y no se recalculan.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php vendor\bin\phpunit tests/app/Models/PagosOnline/IntencionesPagoModelNiTest.php` | OK, 14 pruebas (línea base y cierre) |
| `php vendor\bin\phpunit tests/app/Integration/Paso4PagoTest.php` | OK, 19 pruebas (línea base y cierre) |
| `php vendor\bin\phpunit tests/app/Libraries/Payments/PaymentOrchestratorTest.php` | OK, 14 pruebas (línea base y cierre) |
| `php vendor\bin\phpunit tests/app/Libraries/Payments/PagosZelleServicesTest.php` | OK, 7 pruebas |
| `php vendor\bin\phpunit tests/app/Integration/ZelleNuevoIngresoTest.php` | OK, 9 pruebas |
| `php vendor\bin\phpunit tests/app/Database/Migrations/DesgloseZelleMigrationTest.php` | OK, 3 pruebas |
| `php vendor\bin\phpunit tests/app/Integration` | OK, 124 pruebas |
| `php vendor\bin\phpunit tests/app/Libraries/Payments` | OK, 29 pruebas |
| `php vendor\bin\phpunit tests/app/Database/Migrations` | OK, 18 pruebas |
| `php -l` sobre 12 archivos PHP nuevos/modificados | Sin errores |
| `graphify update .` | Grafo actualizado |

## Verificación

- **Línea base (antes):** `IntencionesPagoModelNiTest` 14/14, `Paso4PagoTest` 19/19 y `PaymentOrchestratorTest` 14/14 en verde antes de implementar.
- **Prueba manual (flujo normal):** no se ejecutó navegación real; el flujo se cubrió con integración SQLite y dobles de GHL/correo. Vistas revisadas y validadas con `php -l`.
- **Flujos alternativos y errores:** cubiertos por `ZelleNuevoIngresoTest` (sin GHL, sin correo, detalle ajeno, detalle de deuda, idempotencia, 409, aislamiento y filtro).
- **Pruebas automatizadas:** suites nuevas y de regresión indicadas arriba, todas en verde.
- **Criterios del plan:** los 23 criterios de finalización quedaron marcados y verificados.

## Desviaciones del plan

- Las fases A, B y C se implementaron en un solo lote y se cerraron con `php -l`, pruebas del área y revisión al final, en lugar de una pausa formal entre fases.
- Se agregó una prueba de migración (`DesgloseZelleMigrationTest`) no listada en el plan para verificar idempotencia y conservación de datos.
- La columna de origen también se agregó al Excel, además del PDF, para conservar coherencia con el filtro exportado.

## Riesgos y pendientes

- El valor `Inscrito` debe existir en el campo de ciclo de vida de GHL; si la API lo rechaza, la verificación se completa y queda auditada como `ghl_fallido`.
- No hay cola ni reintento para fallos de GHL o correo; requieren revisión manual de la auditoría.
- La migración debe aplicarse en producción con respaldo; no se ejecutó contra una base MySQL real en esta sesión.
- Los reportes NI anteriores a la feature no tienen desglose y se muestran con los datos persistidos disponibles.
- No se hizo `commit` ni se publicó la rama; queda local para revisión.
