# Prototipo de ejecución — FEAT-008 Sincronización GHL a Inscrito al aprobar pagos no Zelle de nuevo ingreso

- **Rama:** p-feature/sincronizacion-ghl-aprobacion-pago-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/008-sincronizacion-ghl-aprobacion-pago-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado
- **Consolidado en:** feature/desacoplar-contructor-pagos (2026-10-28)

## Resumen

Se agregó la actualización del ciclo de vida del contacto en GoHighLevel a `Inscrito` cuando una pasarela no Zelle aprueba un pago de nuevo ingreso. La integración vive en `IntencionesPagoModel::actualizaStatus()`, es best-effort, no bloquea ni revierte la aprobación y deja trazabilidad solo en el log de la aplicación.

## Tareas realizadas

- [x] Agregar `GoHighLevelClient::updateLifecycleStatus()` con payload `customFields` y timeout por defecto de 5 segundos.
- [x] Leer `estados_id` y `ni_inscripcion_id` antes de actualizar la intención en `actualizaStatus()`.
- [x] Capturar el resultado de `validarDetallesPago()` y el resultado booleano de `update()` sin cambiar la aprobación existente.
- [x] Sincronizar GHL solo en la transición 2 → 3, con actualización exitosa, validación correcta y `ni_inscripcion_id > 0`.
- [x] Exigir `ni_inscripciones.ghl_contact_id` no vacío; no buscar ni crear contactos.
- [x] Registrar `info` en éxito y `warning` en omisión o fallo, sin datos personales.
- [x] Capturar excepciones y fallos de GHL sin alterar `$datos` ni el estado 3.
- [x] Crear la fábrica protegida `crearGhlClient()` para sustituir el cliente en pruebas.
- [x] Cubrir éxito, pago regular, contacto ausente, postulación ausente, validación fallida, callback repetido, fallo de GHL, excepción y forma/referencia/monto inválidos.
- [x] Ejecutar `php -l` y las pruebas del área.
- [x] Ejecutar `graphify update .`.
- [x] Documentar el resultado en este prototipo y marcar el plan como completado.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `GoHighLevelClient` expone un método que actualiza `CF_ESTADO_CICLO_VIDA` y devuelve el contrato estándar | `testActualizaElCicloDeVidaConElPayloadEsperado` inspecciona método, endpoint, timeout y `customFields` | ok |
| El método nuevo no cambia `updateContact()`, `syncContact()` ni `searchContactByCedula()` | Revisión del diff: solo se agregó un método, sin tocar los existentes | ok |
| `actualizaStatus()` lee `estados_id` anterior y `ni_inscripcion_id` antes de actualizar | Revisión del código y pruebas de transición 2 → 3 y callback repetido | ok |
| `actualizaStatus()` captura la validación y el resultado de `update()` sin cambiar la aprobación | Revisión del código y pruebas de éxito, validación fallida y omisiones | ok |
| La sincronización solo ocurre con estado previo 2, actualización exitosa, validación correcta y `ni_inscripcion_id > 0` | `testSincronizaGhlAlAprobarPagoNuevoIngreso`, `testNoSincronizaPagoRegular`, `testNoRepiteLaSincronizacionEnUnCallbackRepetido` | ok |
| No sincroniza pagos regulares, callbacks repetidos, estados ya aprobados, rechazos, Zelle ni legado BDV | Prueba de pago regular y callback repetido; Zelle y BDV no pasan por este cambio | ok |
| Exige `ghl_contact_id` no vacío y no busca ni crea contactos | `testOmiteLaSincronizacionSiNoHayContactoGhl` | ok |
| Escribe `Inscrito` en `CF_ESTADO_CICLO_VIDA` con timeout de 5 segundos | `testActualizaElCicloDeVidaConElPayloadEsperado` y `testSincronizaGhlAlAprobarPagoNuevoIngreso` | ok |
| Un éxito deja un registro `info` con `intencion_id` y `ni_inscripcion_id` | `assertLogged('info', ...)` en la prueba de éxito | ok |
| Un fallo, timeout, contacto ausente, postulación ausente o validación fallida deja `warning` sin alterar la aprobación | Pruebas de contacto ausente, postulación ausente, validación fallida, fallo HTTP y excepción | ok |
| Un fallo de GHL no lanza excepciones, no modifica `$datos`, no revierte la intención y mantiene estado 3 | Pruebas de fallo HTTP y excepción comprueban estado 3 y retorno `success` | ok |
| `ghl_sincronizado` no se consulta ni se modifica | Revisión del código; no hay referencias en el cambio | ok |
| No se agregan tablas, migraciones, seeders, rutas, filtros, dependencias ni cambios en `vendor/`, `system/` o `public/vendor/` | Revisión del diff y `git status` | ok |
| Las pruebas cubren los escenarios requeridos | 13 pruebas en `IntencionesPagoModelGhlTest` | ok |
| Las pruebas del área pasan con SQLite y doble de `GoHighLevelClient` | Ejecuciones de PHPUnit del área | ok |
| `php -l` no reporta errores en los archivos PHP nuevos o modificados | `php -l` sobre los tres archivos PHP | ok |
| `graphify update .` se ejecuta después de los cambios | Ejecutado y grafo reconstruido | ok |
| El plan se mantiene actualizado | Estado `completado` y bitácora actualizada | ok |

## Flujos cubiertos

- **Flujo normal:** pago no Zelle de nuevo ingreso en estado 2, validación correcta, actualización a 3 y contacto GHL existente. Se llama a GHL con `Inscrito`, timeout 5 y se registra `info`.
- **Flujos alternativos:** pago regular sin `ni_inscripcion_id`; intención sin contacto GHL; postulación inexistente; validación de detalles fallida; callback repetido sobre una intención ya en estado 3.
- **Control de errores:** forma de pago inexistente, referencia duplicada, monto ausente, intención inexistente, GHL con respuesta no exitosa y GHL con excepción. En todos los casos la aprobación existente se conserva y la sincronización no propaga errores.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `tests/app/Models/PagosOnline/IntencionesPagoModelGhlTest.php` | Pruebas de la sincronización GHL con SQLite y dobles del cliente. |
| `docs/features/008-sincronizacion-ghl-aprobacion-pago-nuevo-ingreso/prototipo.md` | Registro de ejecución de esta feature. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Libraries/GoHighLevel/GoHighLevelClient.php` | Se agregó `updateLifecycleStatus()` con payload de `CF_ESTADO_CICLO_VIDA` y timeout configurable. |
| `app/Models/PagosOnline/IntencionesPagoModel.php` | Lectura previa de estado/origen, captura de validación y resultado de actualización, sincronización condicional, fábrica del cliente y logging best-effort. |
| `docs/features/008-sincronizacion-ghl-aprobacion-pago-nuevo-ingreso/plan.md` | Estado actualizado a `completado`, criterios marcados y bitácora ampliada. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** no aplica. No se tocaron rutas, filtros, CSRF, controladores, vistas, SPA ni API.
- **Permisos y validaciones:** la condición de sincronización exige estado previo 2, actualización exitosa, `validarDetallesPago()['ok']`, `ni_inscripcion_id > 0` y `ghl_contact_id` no vacío. La identidad y la sede no se reciben del cliente.
- **Migraciones/seeds:** no aplica.
- **Compatibilidad:** `actualizaStatus()` conserva su firma y su retorno `$datos`; `GoHighLevelClient::updateContact()`, `syncContact()` y `searchContactByCedula()` no cambian. La única diferencia observable es la llamada adicional a GHL y los registros de log en la transición 2 → 3 de nuevo ingreso.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `vendor\bin\phpunit.bat tests/app/Models/PagosOnline` (línea base) | OK, 18 pruebas, 52 aserciones |
| `vendor\bin\phpunit.bat tests/app/Libraries/Payments/PaymentOrchestratorTest.php tests/app/Integration/Paso4PagoTest.php` (línea base) | OK, 14 pruebas, 34 aserciones |
| `php -l app\Libraries\GoHighLevel\GoHighLevelClient.php` | Sin errores de sintaxis |
| `php -l app\Models\PagosOnline\IntencionesPagoModel.php` | Sin errores de sintaxis |
| `php -l tests\app\Models\PagosOnline\IntencionesPagoModelGhlTest.php` | Sin errores de sintaxis |
| `vendor\bin\phpunit.bat tests/app/Models/PagosOnline/IntencionesPagoModelGhlTest.php` | OK, 13 pruebas, 44 aserciones |
| `vendor\bin\phpunit.bat tests/app/Models/PagosOnline` | OK, 31 pruebas, 96 aserciones |
| `vendor\bin\phpunit.bat tests/app/Libraries/Payments` | OK, 29 pruebas, 99 aserciones |
| `vendor\bin\phpunit.bat tests/app/Integration/ZelleNuevoIngresoTest.php` | OK, 9 pruebas, 66 aserciones |
| `vendor\bin\phpunit.bat tests/app/Integration/Paso4PagoTest.php` | OK, 19 pruebas, 67 aserciones |
| `vendor\bin\phpunit.bat tests/app/Integration/Paso4NuevoIngresoTest.php` | OK, 27 pruebas, 129 aserciones |
| `vendor\bin\phpunit.bat tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | OK, 33 pruebas, 125 aserciones |
| `graphify update .` | Grafo reconstruido correctamente (13944 nodos, 28870 aristas, 865 comunidades) |
| `git diff --check` | Sin errores de espacios |

## Verificación

- **Línea base (antes):** `tests/app/Models/PagosOnline` pasó con 18 pruebas y 52 aserciones; `PaymentOrchestratorTest` + `Paso4PagoTest` pasaron con 14 pruebas y 34 aserciones.
- **Prueba manual (flujo normal):** no se ejecutó contra una pasarela real ni GHL real. El flujo se validó con el doble del cliente: intención en estado 2, detalles vinculados, contacto presente y respuesta exitosa; la intención quedó en 3 y se registró la llamada con `Inscrito`.
- **Flujos alternativos y errores:** cubiertos por pruebas automatizadas con SQLite; las omisiones no llaman a GHL y los fallos no alteran el estado 3.
- **Pruebas automatizadas:** `IntencionesPagoModelGhlTest` (13 pruebas) y las suites del área listadas arriba, todas exitosas.
- **Criterios del plan:** todos verificados. La suite completa no se ejecutó por el fallo preexistente de `tests/app/Models/BotChatSystemTest.php` con `DatabaseTestTrait`, documentado en `AGENTS.md`.

## Desviaciones del plan

- Ninguna desviación de alcance. Se agregaron dos pruebas adicionales a las exigidas: verificación directa del payload de `updateLifecycleStatus()` y captura de excepción lanzada por el cliente GHL.

## Riesgos y pendientes

- La llamada a GHL es síncrona y puede añadir hasta 5 segundos a la aprobación de la pasarela.
- Si el campo GHL no acepta el valor `Inscrito`, la aprobación se completa pero solo queda un `warning` en el log.
- Un fallo de GHL no se reintenta ni se audita en base de datos; queda sujeto a la rotación del log.
- No se creó ni actualizó `MEMORY.md` porque no existe en este checkout.
- La rama es local y no se publicó; no se realizaron commits.

## Consolidación

- **Fecha:** 2026-10-28
- **Rama destino:** feature/desacoplar-contructor-pagos
- **Commit de merge:** f5ebb3b
- **Estado:** consolidado
- **Rama prototipo:** eliminada con `git branch -d` tras verificar ancestro, ausencia de diferencias y pruebas del área.
