# Sincronización GHL a Inscrito al aprobar pagos no Zelle de nuevo ingreso

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

## Objetivo

Que todo pago de nuevo ingreso aprobado por una pasarela no Zelle actualice en GoHighLevel el campo de ciclo de vida del contacto a `Inscrito`, de forma best-effort y con trazabilidad en el log de la aplicación. El cambio cierra el hueco que FEAT-006 dejó para Zelle verificado: Zelle ya actualiza GHL al verificar, pero las pasarelas no Zelle aprobadas en estado 3 no lo hacen.

## Alcance

- Incluye:
  - Agregar a `GoHighLevelClient` un método reutilizable para actualizar el campo de ciclo de vida de un contacto.
  - Integrar la sincronización en `IntencionesPagoModel::actualizaStatus()`, punto común de las pasarelas no Zelle.
  - Sincronizar solo cuando la intención de nuevo ingreso pasa de estado 2 (`pagando`) a estado 3 (`aprobado`), la actualización fue exitosa y la validación de detalles es correcta.
  - Exigir que la intención tenga `ni_inscripcion_id` y que `ni_inscripciones.ghl_contact_id` no esté vacío.
  - Actualizar el campo `CF_ESTADO_CICLO_VIDA` con el valor `Inscrito`.
  - Registrar el resultado en el log de la aplicación: éxito en nivel `info`; omisión o fallo en nivel `warning`.
  - Cubrir con pruebas unitarias el éxito, las omisiones y el fallo de GHL usando SQLite y un doble del cliente.
  - Documentar el cambio en este plan.
- No incluye:
  - Zelle de nuevo ingreso: ya está cubierto por FEAT-006 al verificar el reporte (estado 8).
  - Zelle regular ni pagos no Zelle del portal regular.
  - Búsqueda de contactos por cédula, creación de contactos o actualización de oportunidades, pipelines o etiquetas.
  - Modificar `ghl_sincronizado`, `paso_actual`, `orbis_sincronizado` o datos académicos.
  - Aprobaciones del flujo legacy de Banco de Venezuela en `PagosVenezuelaTraits::post_pago_pgvenez`, que actualiza el estado 3 sin pasar por `PaymentOrchestrator`.
  - Aprobaciones manuales inexistentes para pagos no Zelle de nuevo ingreso.
  - Nueva tabla de auditoría, migración de base de datos, cola de reintentos o backfill de pagos históricos.
  - Cambios en rutas, filtros, CSRF, vistas, JavaScript, SPA, API o dependencias.

> **Decisión de alcance:** no se recomienda dividir el cambio. Zelle ya está resuelto; el trabajo pendiente es una única integración acotada al punto común de aprobación de las pasarelas no Zelle de nuevo ingreso.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`.
- `pg_intenciones_pago.ni_inscripcion_id` es el discriminador de origen: nulo para pagos regulares y no nulo para nuevo ingreso. Se agregó en la migración `2026-10-27-000099`.
- `ni_inscripciones.ghl_contact_id` guarda el contacto creado o encontrado en GHL durante el Paso 0. Se agregó en la migración `2026-10-20-000095`.
- El ciclo de vida del contacto ya se usa en el flujo de nuevo ingreso: Paso 1 escribe `Necesidad`, Paso 2 escribe `Iniciado` y FEAT-006 escribe `Inscrito` al verificar Zelle. Este cambio completa la transición al aprobar pagos no Zelle.
- Las formas no Zelle disponibles para nuevo ingreso son las soportadas por `PaymentService::FORMAS_SOPORTADAS` y no excluidas por `NuevoIngresoPagoService`: `bnscboton`, `c2pmercant`, `bncvpos`, `bncc2p` y `pagomovilb`. `saldofavor` está excluida para nuevo ingreso y `zelle` no pasa por `actualizaStatus()` porque la pasarela devuelve `gestionado = true`.
- `PaymentOrchestrator` llama a `IntencionesPagoModel::actualizaStatus()` cuando la pasarela no marca el pago como gestionado. Por eso el modelo es el punto común de las cinco formas no Zelle.
- `actualizaStatus()` valida la forma de pago, la referencia y el monto; si todo es correcto, ejecuta `validarDetallesPago()` y actualiza la intención a estado 3. Hoy el resultado de `validarDetallesPago()` no se usa para decidir la aprobación; este cambio solo lo usará para decidir la sincronización con GHL.
- `validarDetallesPago()` devuelve `['ok' => bool, 'errores' => array]`. Para nuevo ingreso, `ProceNi()` solo comprueba el vínculo con la postulación y no marca deudas ni inscripciones.
- El cliente GHL ya expone `updateContact()` y la constante `CF_ESTADO_CICLO_VIDA = 'uTfDymMiwkt4My1rd3JX'`. Se asume que el campo acepta el valor `Inscrito`, igual que en FEAT-006.
- Un fallo de GHL no debe bloquear, revertir ni demorar de forma indefinida la aprobación. Se usará un timeout de 5 segundos.
- No existe `MEMORY.md` ni `docs/constitution.md` en este checkout; no se crean ni se actualizan en esta feature.
- El código `FEAT-008` no colisiona: `docs/features` contiene `FEAT-001` a `FEAT-007`. Se respeta el esquema del repositorio en lugar de `feature-000`.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso` y una intención en estado 2 (`pagando`) elige una forma no Zelle en el Paso 4: `bnscboton`, `c2pmercant`, `bncvpos`, `bncc2p` o `pagomovilb`.
2. Paso 2: `Paso3::postPago()` valida sesión, paso, propiedad, estado, sede y forma; llama a `NuevoIngresoPagoService::procesarPago()`.
3. Paso 3: `NuevoIngresoPagoService` valida la intención, la forma permitida y la sede; llama a `PaymentOrchestrator::procesar()`.
4. Paso 4: `PaymentOrchestrator::procesar()` despacha a la pasarela correspondiente y obtiene una respuesta con `estatus = success`, referencia y monto.
5. Paso 5: Como la pasarela no devuelve `gestionado = true`, el orquestador llama a `IntencionesPagoModel::actualizaStatus($id, $response)`.
6. Paso 6: `actualizaStatus()` resuelve la forma de pago en `pg_formas_pago`; si no existe, no hay aprobación.
7. Paso 7: `actualizaStatus()` comprueba que la referencia no exista para esa forma y que `monto_pagado` esté presente; si falla, no hay aprobación.
8. Paso 8: Antes de actualizar, `actualizaStatus()` consulta la intención y guarda su `estados_id` anterior y su `ni_inscripcion_id`.
9. Paso 9: `actualizaStatus()` ejecuta `validarDetallesPago($id)` y conserva su resultado `ok` y sus errores.
10. Paso 10: `actualizaStatus()` actualiza la intención a estado 3 con referencia, monto pagado, `data_respuesta` y `formas_pago_id`; guarda el resultado booleano de la actualización.
11. Paso 11: `actualizaStatus()` inserta la traza en `pg_pagos_realizados`.
12. Paso 12: Después de las escrituras, `actualizaStatus()` evalúa la sincronización con GHL. Solo continúa si se cumplen todas las condiciones:
    - el estado anterior era exactamente `2`;
    - la actualización a estado 3 fue exitosa;
    - `validarDetallesPago()['ok']` es `true`;
    - `ni_inscripcion_id` no es nulo ni cero.
13. Paso 13: Con las condiciones cumplidas, consulta `ni_inscripciones.ghl_contact_id`. Si el valor está vacío o la postulación no existe, no llama a GHL y registra un `warning`.
14. Paso 14: Si hay contacto, llama a `GoHighLevelClient::updateLifecycleStatus($contactId, 'Inscrito')` con timeout de 5 segundos.
15. Paso 15: Si GHL responde con `status = true`, registra un `info` con `intencion_id`, `ni_inscripcion_id` y el resultado. Si responde con error, registra un `warning` con el código y el mensaje.
16. Paso 16: `actualizaStatus()` devuelve `$datos` sin modificarlo. La aprobación del pago continúa su curso normal y el aspirante ve el pago aprobado.
17. Paso 17: Si GHL falla, lanza una excepción o supera el timeout, la excepción se captura, se registra un `warning` y la aprobación permanece en estado 3.

## Flujos alternativos / variantes

### Pago de nuevo ingreso sin contacto GHL

1. Paso 1: La intención pasa de 2 a 3 y la validación de detalles es correcta.
2. Paso 2: `ni_inscripciones.ghl_contact_id` está vacío o la postulación no existe.
3. Paso 3: No se llama a GHL.
4. Paso 4: Se registra un `warning` con el motivo `sin_ghl_contact_id` o `postulacion_no_encontrada`.
5. Paso 5: El pago queda aprobado en estado 3.

### Pago de nuevo ingreso con validación de detalles fallida

1. Paso 1: La pasarela responde `success` y la intención se actualiza a estado 3.
2. Paso 2: `validarDetallesPago()` devuelve `ok = false` porque un detalle no pertenece a la postulación o la postulación no existe.
3. Paso 3: No se llama a GHL.
4. Paso 4: Se registra un `warning` con el motivo `validacion_fallida` y la cantidad de errores.
5. Paso 5: El pago conserva el estado 3, igual que antes de este cambio.

### Pago regular no Zelle

1. Paso 1: La intención tiene `ni_inscripcion_id` nulo.
2. Paso 2: La pasarela responde `success` y la intención pasa a estado 3.
3. Paso 3: La condición de nuevo ingreso no se cumple.
4. Paso 4: No se llama a GHL y no se registra un aviso específico para evitar ruido.
5. Paso 5: El pago regular conserva su comportamiento actual.

### Callback repetido o aprobación duplicada

1. Paso 1: Llega un nuevo callback para una intención que ya está en estado 3.
2. Paso 2: La lectura previa devuelve `estados_id = 3`.
3. Paso 3: No se cumple la condición de transición 2→3.
4. Paso 4: No se vuelve a llamar a GHL ni se duplica el registro de aprobación en el log.
5. Paso 5: La intención permanece en estado 3.

### Pago Zelle de nuevo ingreso

1. Paso 1: El aspirante elige Zelle y registra el reporte.
2. Paso 2: `PagosZelleServices` deja la intención en estado 7 y devuelve `gestionado = true`.
3. Paso 3: El orquestador no llama a `actualizaStatus()`.
4. Paso 4: La verificación administrativa sigue usando `ZelleReportManager::actualizarGhlVerificacion()` y deja la intención en 8.
5. Paso 5: Esta feature no modifica ni duplica ese comportamiento.

### Pago legacy de Banco de Venezuela

1. Paso 1: El flujo legacy `PagosVenezuelaTraits::post_pago_pgvenez` actualiza el estado 3 directamente, sin pasar por el orquestador.
2. Paso 2: La intención pertenece al portal regular y no tiene `ni_inscripcion_id`.
3. Paso 3: No se ejecuta la sincronización de esta feature.
4. Paso 4: El flujo legacy conserva su comportamiento actual.

### GHL no disponible o con error

1. Paso 1: Se cumplen todas las condiciones y se llama a `updateLifecycleStatus()`.
2. Paso 2: GHL responde con un código distinto de 2xx, lanza una excepción o supera los 5 segundos.
3. Paso 3: La excepción se captura y se registra un `warning` con el código o el mensaje.
4. Paso 4: No se modifica `$datos`, no se revierte la intención y no se bloquea al aspirante.
5. Paso 5: La intención permanece en estado 3.

### Forma de pago desconocida, referencia duplicada o monto ausente

1. Paso 1: `actualizaStatus()` no encuentra la forma, detecta una referencia duplicada o no recibe `monto_pagado`.
2. Paso 2: No se actualiza la intención a estado 3.
3. Paso 3: No se llama a GHL.
4. Paso 4: Se conserva la respuesta de error existente de la pasarela.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Forma de pago no encontrada en `pg_formas_pago` | Consulta de `actualizaStatus()` | Devuelve `estatus = Error` con el mensaje actual; no actualiza la intención | Intención en 2; sin GHL |
| Referencia duplicada para la misma forma | Consulta de `actualizaStatus()` | Devuelve `estatus = Error` con el mensaje actual; no actualiza la intención | Intención en 2; sin GHL |
| `monto_pagado` ausente | Validación de `actualizaStatus()` | Devuelve `estatus = Error` con el mensaje actual; no actualiza la intención | Intención en 2; sin GHL |
| Intención no encontrada antes de actualizar | Consulta previa por id | No se actualiza ni se sincroniza; se registra `warning` | Sin escritura; sin GHL |
| Fallo de la actualización a estado 3 | Resultado booleano de `update()` | No se sincroniza; se registra `warning` | Intención sin cambio; sin GHL |
| Validación de detalles fallida en nuevo ingreso | `validarDetallesPago()['ok'] === false` | No se sincroniza; se registra `warning` con la cantidad de errores | Intención en 3; sin GHL |
| Postulación de nuevo ingreso inexistente | Consulta a `ni_inscripciones` sin fila | No se sincroniza; se registra `warning` | Intención en 3; sin GHL |
| Postulación sin `ghl_contact_id` | Valor vacío o solo espacios | No se sincroniza; se registra `warning` | Intención en 3; sin GHL |
| GHL responde con error HTTP | `status = false` en la respuesta del cliente | Se registra `warning` con código y mensaje; la aprobación continúa | Intención en 3; sin cambio en GHL |
| GHL lanza una excepción | `catch (\Throwable)` | Se registra `warning` con el mensaje; la aprobación continúa | Intención en 3; sin cambio en GHL |
| GHL supera el timeout de 5 segundos | Timeout del cliente HTTP | Se captura como fallo; se registra `warning`; la aprobación continúa | Intención en 3; sin cambio en GHL |
| Callback repetido con intención ya aprobada | Estado anterior distinto de 2 | No se sincroniza ni se duplica el log de aprobación | Intención en 3; sin GHL |
| Pago regular no Zelle | `ni_inscripcion_id` nulo | No se sincroniza; sin log específico | Intención en 3; sin GHL |
| Pago Zelle de nuevo ingreso | `gestionado = true`; no pasa por `actualizaStatus()` | Se conserva el flujo y la actualización de FEAT-006 | Intención en 8; GHL actualizado por FEAT-006 |
| Pago legacy de Banco de Venezuela | Ruta directa en `PagosVenezuelaTraits` | No se ejecuta esta sincronización | Estado legacy sin cambio |
| Error inesperado en el log | `catch (\Throwable)` interno de la sincronización | Se intenta registrar el fallo; nunca se propaga a la aprobación | Intención en 3; sin bloqueo |
| Intención de nuevo ingreso con `ghl_contact_id` inválido | Respuesta de GHL | Se registra `warning`; no se busca ni se crea otro contacto | Intención en 3; sin cambio en GHL |

## Reglas de negocio y validaciones

- La sincronización aplica únicamente a intenciones con `ni_inscripcion_id` no nulo. Los pagos regulares no se sincronizan.
- La sincronización se dispara solo en la primera transición de estado 2 (`pagando`) a estado 3 (`aprobado`) dentro de `actualizaStatus()`. No se dispara en callbacks repetidos, estados 3 ya alcanzados, estados 7 u 8, ni en rechazos.
- La sincronización exige `validarDetallesPago()['ok'] === true`. Si la validación falla, el pago conserva su aprobación actual, pero GHL no se actualiza.
- La sincronización exige que `ni_inscripciones.ghl_contact_id` tenga un valor no vacío después de aplicar `trim()`. No se busca el contacto por cédula, no se crea un contacto nuevo y no se usa `ghl_sincronizado` como condición.
- El valor que se escribe es `Inscrito` en el campo personalizado `CF_ESTADO_CICLO_VIDA`. No se mueven oportunidades, pipelines ni etapas; no se agregan etiquetas.
- La actualización de GHL es best-effort: nunca lanza una excepción hacia la pasarela, nunca cambia `$datos`, nunca revierte la intención y nunca impide que el pago quede en estado 3.
- El timeout de la llamada a GHL es de 5 segundos. Un timeout se trata como fallo y se registra.
- No se modifica `ghl_sincronizado`, `paso_actual`, `orbis_sincronizado`, `ni_inscripciones` ni datos académicos.
- No se agrega una tabla de auditoría ni una migración. La trazabilidad se limita al log de la aplicación, con nivel `info` para éxito y `warning` para omisión o fallo.
- Los logs no incluyen cédula, correo, nombre ni otros datos personales. Solo incluyen `intencion_id`, `ni_inscripcion_id`, motivo, código y mensaje técnico.
- El modelo conserva su contrato actual: `actualizaStatus()` sigue devolviendo el arreglo `$datos` de la pasarela y sigue insertando la traza en `pg_pagos_realizados`.
- La lectura previa de la intención agrega una consulta por aprobación. Es una lectura indexada por `id` y no cambia el comportamiento de escritura.
- `validarDetallesPago()` se sigue ejecutando y conservando sus efectos actuales. Este cambio solo captura su resultado; no altera la lógica de aprobación ni introduce bloqueos nuevos.
- Cualquier pasarela futura que no marque `gestionado = true` y use el orquestador quedará cubierta automáticamente. Una pasarela que marque `gestionado = true` deberá implementar su propia sincronización.
- Zelle de nuevo ingreso conserva su implementación en `ZelleReportManager`. Esta feature no modifica `PagosZelleServices`, `ZelleReportManager` ni sus pruebas.
- El flujo legacy de Banco de Venezuela queda fuera de alcance y conserva su comportamiento.

## Contratos y diseño propuesto

### `GoHighLevelClient`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `updateLifecycleStatus(string $contactId, string $status, int $timeoutSeconds = 5): array` | Actualizar el campo `CF_ESTADO_CICLO_VIDA` de un contacto. | Una llamada HTTP `PUT /contacts/{contactId}`; devuelve el contrato estándar del cliente (`status`, `code`, `data`, `raw`). |

- El método construye el payload `customFields` con `[['id' => self::CF_ESTADO_CICLO_VIDA, 'value' => $status]]`.
- No valida la existencia del contacto ni busca alternativas; si el contacto no existe, GHL responde con error y el llamador lo registra.
- No modifica los métodos existentes `updateContact()`, `syncContact()` ni `searchContactByCedula()`.
- El timeout predeterminado es 5 segundos para no demorar la respuesta de la pasarela.

### `IntencionesPagoModel`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `actualizaStatus($it, $datos)` | Conservar la aprobación actual y agregar la sincronización best-effort. | Lectura previa, actualización, historial y llamada a GHL condicional. |
| `sincronizarGhlInscrito(int $intencionId, int $niInscripcionId): void` | Resolver el contacto y actualizar el ciclo de vida a `Inscrito`. | Lectura de `ni_inscripciones` y llamada HTTP; no escribe en base de datos. |
| `crearGhlClient(): GoHighLevelClient` | Fábrica protegida para permitir un doble en pruebas. | Sin efectos en producción. |

- `actualizaStatus()` conserva la lectura de la forma, la validación de referencia, la validación del monto y la ejecución de `validarDetallesPago()`.
- Antes de la actualización, lee `estados_id` y `ni_inscripcion_id` de la intención. Si no hay fila, no sincroniza.
- Captura el resultado de `validarDetallesPago()` en una variable y lo usa solo para decidir la sincronización.
- Captura el resultado booleano de `update()`. Solo sincroniza si fue exitoso.
- Llama a `sincronizarGhlInscrito()` después de insertar en `pg_pagos_realizados` y solo si el estado anterior era `2`, la actualización fue exitosa, la validación fue correcta y `ni_inscripcion_id` es mayor que cero.
- `sincronizarGhlInscrito()` consulta `ni_inscripciones` por id y selecciona `ghl_contact_id`. Si no hay fila o el valor está vacío, registra `warning` y termina.
- `sincronizarGhlInscrito()` llama a `crearGhlClient()->updateLifecycleStatus($contactId, 'Inscrito')` dentro de `try/catch`.
- El método no lanza excepciones hacia `actualizaStatus()` y no altera `$datos`.
- La fábrica `crearGhlClient()` se marca `protected` para que las pruebas puedan sustituir el cliente sin modificar el modelo en producción.

### Integración con el flujo existente

- `PaymentOrchestrator` no se modifica. La integración ocurre en el modelo que ya usa para actualizar el estado.
- `NuevoIngresoPagoService` no se modifica. La validación de sede y forma sigue en el servicio.
- `Paso3` no se modifica. La respuesta al aspirante conserva su contrato.
- `PagosZelleServices` y `ZelleReportManager` no se modifican.
- `PagosVenezuelaTraits` no se modifica.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Modificar | `app/Libraries/GoHighLevel/GoHighLevelClient.php` | Agregar `updateLifecycleStatus()` reutilizable. |
| Modificar | `app/Models/PagosOnline/IntencionesPagoModel.php` | Lectura previa, captura de validación, sincronización condicional y fábrica del cliente. |
| Crear | `tests/app/Models/PagosOnline/IntencionesPagoModelGhlTest.php` | Pruebas de éxito, omisiones, idempotencia y fallo de GHL con SQLite y doble del cliente. |
| Documentar | `docs/features/008-sincronizacion-ghl-aprobacion-pago-nuevo-ingreso/plan.md` | Este plan. |

No se modifican rutas, filtros, CSRF, controladores, vistas, JavaScript, SPA, API, migraciones, seeders, `vendor/`, `system/` ni `public/vendor/`.

## Criterios de finalización

- [x] `GoHighLevelClient` expone un método que actualiza `CF_ESTADO_CICLO_VIDA` con el valor recibido y devuelve el contrato estándar del cliente.
- [x] El método nuevo no cambia la firma ni el comportamiento de `updateContact()`, `syncContact()` o `searchContactByCedula()`.
- [x] `actualizaStatus()` lee el `estados_id` anterior y el `ni_inscripcion_id` antes de actualizar la intención.
- [x] `actualizaStatus()` captura el resultado de `validarDetallesPago()` y el resultado booleano de `update()` sin cambiar la lógica de aprobación existente.
- [x] La sincronización con GHL se ejecuta solo si el estado anterior es `2`, la actualización a `3` fue exitosa, la validación fue correcta y `ni_inscripcion_id` es mayor que cero.
- [x] La sincronización no se ejecuta para pagos regulares, callbacks repetidos, estados ya aprobados, rechazos, Zelle ni el flujo legacy de Banco de Venezuela.
- [x] La sincronización exige `ghl_contact_id` no vacío y no busca ni crea contactos.
- [x] La llamada a GHL escribe el valor `Inscrito` en `CF_ESTADO_CICLO_VIDA` y usa un timeout de 5 segundos.
- [x] Un éxito de GHL deja un registro `info` con `intencion_id` y `ni_inscripcion_id`, sin datos personales.
- [x] Un fallo, timeout, contacto ausente, postulación ausente o validación fallida deja un registro `warning` con el motivo y no altera la aprobación.
- [x] Un fallo de GHL no lanza excepciones hacia la pasarela, no modifica `$datos`, no revierte la intención y no cambia el estado 3.
- [x] `ghl_sincronizado` no se consulta ni se modifica.
- [x] No se agregan tablas, migraciones, seeders, rutas, filtros, dependencias ni cambios en `vendor/`, `system/` o `public/vendor/`.
- [x] Las pruebas cubren éxito, pago regular, contacto ausente, postulación ausente, validación fallida, callback repetido, fallo de GHL y forma/referencia/monto inválidos.
- [x] Las pruebas del área pasan con SQLite y un doble de `GoHighLevelClient`; se documenta que la suite completa tiene un fallo preexistente en `tests/app/Models/BotChatSystemTest.php`.
- [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] Este plan se mantiene actualizado si cambia alguna decisión de alcance o validación.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Alcance de pagos | Todos los pagos de nuevo ingreso. Zelle ya está cubierto por FEAT-006; esta feature cubre las pasarelas no Zelle. |
| Estado de GHL | Campo de ciclo de vida del contacto (`CF_ESTADO_CICLO_VIDA`) con el valor `Inscrito`. No se mueven oportunidades ni pipelines. |
| Resolución del contacto | Solo actualizar si existe `ghl_contact_id` guardado. No buscar por cédula ni crear contactos. |
| Fallo de GHL | Aprobar igual y auditar el fallo. Comportamiento best-effort; nunca bloquear ni revertir el pago. |
| Auditoría | Solo log de la aplicación: `info` para éxito y `warning` para omisión o fallo. Sin tabla nueva. |
| Punto de integración | `IntencionesPagoModel::actualizaStatus()`, punto común de las pasarelas no Zelle. |
| Estados que disparan | Solo la transición 2→3 de pasarelas. Zelle estado 8 conserva FEAT-006. |
| Flujo legacy BDV | Fuera de alcance; no se modifica `PagosVenezuelaTraits`. |
| Idempotencia | Solo la primera transición 2→3. Un callback repetido no vuelve a llamar a GHL. |
| Condición habilitante | `ni_inscripcion_id` no nulo y `ghl_contact_id` no vacío. No se exige `ghl_sincronizado = 1`. |
| Validación de detalles | Solo sincronizar si `validarDetallesPago()` devuelve `ok`. La aprobación existente no se bloquea si falla. |
| Diseño de la llamada | Método reutilizable en `GoHighLevelClient`; no se refactoriza Zelle en esta feature. |
| División del cambio | No se recomienda dividir: es una integración acotada a un solo punto de aprobación. |

## Riesgos y deuda técnica

- **Latencia en la aprobación:** la llamada a GHL es síncrona y puede añadir hasta 5 segundos a la respuesta de la pasarela. Si el tiempo de respuesta es crítico, se debe evaluar una cola o un proceso posterior.
- **Valor `Inscrito` no disponible:** si el campo de GHL no acepta ese valor, la aprobación se completa pero GHL queda sin actualizar y solo se registra un `warning`. Confirmar la configuración del campo antes de desplegar.
- **Validación fallida con pago aprobado:** si `validarDetallesPago()` falla, el pago sigue en estado 3 por el comportamiento heredado, pero no se marca `Inscrito`. Esto puede dejar una inconsistencia entre el pago y GHL; se documenta y no se corrige en esta feature para no alterar la aprobación.
- **Sin reintento:** un fallo de GHL no se reintenta. Queda en el log y requiere seguimiento manual o una feature futura de cola.
- **Sin auditoría en base de datos:** el log puede rotar o perderse. Si se requiere trazabilidad permanente, se debe crear una tabla de auditoría en otra feature.
- **Contacto obsoleto:** si `ghl_contact_id` apunta a un contacto eliminado o de otra ubicación, GHL responderá con error y solo se registrará el `warning`.
- **Acoplamiento del modelo a GHL:** `IntencionesPagoModel` gana una dependencia de infraestructura. Se mitiga con una fábrica protegida y con la llamada best-effort, pero una refactorización futura podría extraer la sincronización a una librería.
- **Pasarelas con `gestionado = true`:** si una pasarela futura marca el pago como gestionado, no pasará por `actualizaStatus()` y deberá implementar su propia sincronización. Debe quedar documentado en el contrato del orquestador.
- **Timeout de 5 segundos:** puede ser insuficiente en una red lenta; el fallo se registra y no bloquea. Ajustar solo con evidencia operativa.
- **Suite completa:** no inicia por el fallo preexistente de `BotChatSystemTest` con `DatabaseTestTrait`; se ejecutan las pruebas del área y un smoke test.
- **Sin `MEMORY.md`:** este checkout no lo tiene; no se actualiza. Si aparece, debe registrarse esta 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` en el entorno de producción.
- Confirmar que las cinco pasarelas no Zelle de nuevo ingreso siguen usando `PaymentOrchestrator` y no marcan `gestionado = true`.
- Confirmar que un timeout de 5 segundos es aceptable para la respuesta de la pasarela.
- Confirmar que el negocio acepta que un fallo de GHL no bloquee la aprobación y quede solo en el log.

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

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-008 tras revisar `GoHighLevelClient`, `IntencionesPagoModel::actualizaStatus()`, `PaymentOrchestrator`, `PaymentService`, `NuevoIngresoPagoService`, `PagosVenezuelaTraits`, `ZelleReportManager`, las pruebas de nuevo ingreso y las migraciones de `ni_inscripcion_id` y `ghl_contact_id`. Se acordó cubrir solo pagos no Zelle de nuevo ingreso, actualizar el ciclo de vida a `Inscrito`, exigir `ghl_contact_id` y validación correcta, y usar solo el log como auditoría. | opencode (agente) |
| 2026-10-28 | Implementación completada: `updateLifecycleStatus()` en `GoHighLevelClient`, integración best-effort en `actualizaStatus()`, pruebas en `IntencionesPagoModelGhlTest` y verificación del área. | opencode (agente) |
