# Extraer la orquestación de pagos a `PaymentOrchestrator`

- **Código:** REF-002
- **Tipo:** refactor
- **Estado:** en curso
- **Fecha:** 2026-10-27
- **Autor:** opencode (agente)
- **Depende de:** REF-001

## Objetivo

Crear `App\Libraries\Payments\PaymentOrchestrator` para coordinar la intención de pago, la invocación de `PaymentService` y la normalización/actualización de la respuesta. Registrar `Services::paymentOrchestrator()` y hacer que `Pagos::prePago()` y `Pagos::postPago()` deleguen en él, conservando en el controlador la sesión, la propiedad del movimiento, las vistas, las redirecciones y el contrato HTTP.

## Motivación

`Pagos::prePago()` y `Pagos::postPago()` mezclan validación de sesión, consulta de modelos, cálculo de datos para la vista, despacho de la pasarela, decodificación de JSON, actualización de estado y carga de vistas. Esa concentración impide probar la coordinación sin levantar HTTP y sesión, y obliga a que el controlador conozca el formato interno de cada pasarela. `PaymentService` solo despacha; falta una capa de coordinación de dominio.

## Estado actual

- `Pagos::prePago()` (`app/Controllers/Pagos.php:948-1022`):
  - valida sesión y propiedad (`:951-955`);
  - consulta saldo a favor, bancos e intención (`:958-977`);
  - llama a `Services::paymentService()->prePayment()` (`:979-987`);
  - agrega `detalles_intencion_p`, `detalles_intencion`, `bancos`, `saldo_favor` y `post_pago_url` (`:989-994`);
  - arma migajas, carga la vista y termina con `die()` (`:996-1021`).
- `Pagos::postPago()` (`app/Controllers/Pagos.php:1030-1116`):
  - valida sesión y propiedad (`:1033-1037`);
  - si `$id` es nulo carga una vista de mensaje y continúa (`:1039-1049`);
  - consulta la intención con `find($id)` y obtiene `monto_total` (`:1054-1061`);
  - si el estado no es `2`, imprime un script de redirección y **continúa** (`:1063-1071`);
  - llama a `Services::paymentService()->postPayment()` con `id`, `data`, `files`, `monto`, `db` y `estudiante` (`:1073-1084`);
  - decodifica JSON, agrega `forma_pago` y actualiza estado si no fue gestionado (`:1086-1096`);
  - arma el mensaje, el ticket y carga la vista (`:1098-1115`).
- `PaymentService` es una fachada de despacho; `Services::paymentService()` devuelve una instancia compartida (`app/Config/Services.php:151-165`).
- No existen pruebas de pagos en `tests/app` ni un orquestador de este flujo.

## Qué mejora este refactor

- **Legibilidad:** `prePago()` y `postPago()` conservan solo sesión, propiedad, decisiones HTTP y vistas; la coordinación queda en una clase con métodos acotados.
- **Mantenibilidad:** el flujo “intención → pasarela → respuesta → estado” vive en un único lugar y no se repite entre métodos.
- **Testabilidad:** el orquestador recibe `PaymentService` por constructor y expone puntos protegidos para intención, bancos y actualización de estado; se puede probar con dobles sin base real ni sesión.
- **Duplicación / acoplamiento:** el controlador deja de conocer el `json_decode`, la inyección de `forma_pago` y la condición de `gestionado`; el orquestador deja de conocer `base_url`, vistas, `die()` y sesión.
- **Rendimiento:** equivalente; se mantiene una sola consulta de intención por flujo y no se agregan round trips. En `postPago` se reutiliza la intención ya consultada por el controlador.

## Invariantes (qué NO debe cambiar)

- Las firmas públicas `Pagos::prePago($forma_pago_det, $id)` y `Pagos::postPago($forma_pago_det = 'none', $id = null)` se conservan, incluyendo su visibilidad pública y el auto-routing.
- `validarSesion()` y `validarPropietario()` siguen en el controlador, en el mismo orden y antes de cualquier coordinación.
- Se conservan las vistas, los nombres de archivo, las llaves del arreglo de datos (`vista`, `detalles_intencion_p`, `detalles_intencion`, `bancos`, `saldo_favor`, `post_pago_url`, `forma_pago`, `mensaje`, `retorno`, `siguiente`) y los textos visibles.
- Se conserva el `die()` de `prePago()` y la ausencia de `die()` en `postPago()`.
- Se conserva el comportamiento actual de los casos borde, aunque sea defectuoso: `$id` nulo carga la vista y continúa; estado distinto de `2` imprime la redirección y continúa procesando. Este refactor no los corrige.
- Se conserva `json_decode($response, true)`, la asignación de `forma_pago` y la condición `empty($response['gestionado'])` para actualizar estado.
- No cambian las consultas ni su número: `getPagosPorCedulaConDetalle`, `getBancosActivos`, `find($id)` y `actualizaStatus` se ejecutan una vez por flujo, como hoy.
- No cambian rutas, filtros, pasarelas, esquema, seeds, datos ni configuración.
- El código no soportado sigue produciendo la salida legada definida en REF-001.

## Alcance

- **Incluye:** nueva clase `PaymentOrchestrator`, su registro en `Config\Services`, delegación desde `Pagos::prePago()`/`postPago()`, puntos de extensión protegidos para pruebas, pruebas unitarias con dobles y actualización de documentación.
- **No incluye:** cambios en `PaymentService` (los cubre REF-001), cambios en pasarelas, corrección de los defectos de `$id` nulo o estado distinto de `2`, nuevas formas de pago, cambios de vistas, rutas, filtros, esquema o datos, ni mejoras de rendimiento distintas de mantener las consultas actuales.

## Contexto y supuestos

- Este plan se ejecuta después de REF-001. Si REF-001 no está aplicado, el orquestador debe convivir con el `echo`/`exit` actual o esperar a que se complete.
- `PaymentOrchestrator` será una clase de dominio sin estado propio, en `app/Libraries/Payments/PaymentOrchestrator.php`.
- Métodos propuestos, en inglés para consistencia con `PaymentService`:
  - `prePayment(string $formaPago, array $estudiante, $saldoFavor): array`
  - `postPayment(string $formaPago, array $intencion, array $contexto): array`
- `prePayment()` consulta bancos e intención con los modelos actuales y devuelve la respuesta de la pasarela más `detalles_intencion_p`, `detalles_intencion` y `bancos`. El controlador agrega `saldo_favor`, `post_pago_url` y carga la vista.
- `postPayment()` recibe la intención ya consultada por el controlador (`$it`) para que la validación de estado actual ocurra en el mismo punto y no se duplique la consulta. El orquestador usa `id` y `monto_total` de esa intención.
- El controlador conserva el `try/catch (\InvalidArgumentException)` de REF-001 alrededor de la llamada al orquestador, para que la excepción del despacho no cambie la salida HTTP.
- `PaymentOrchestrator` recibe `PaymentService` por constructor; por defecto usa `Config\Services::paymentService()`. Las consultas de modelos se encapsulan en métodos protegidos para poder sustituirlas en pruebas.
- `Services::paymentOrchestrator()` devuelve una instancia compartida, análoga a `paymentService()`.
- Las pruebas usan datos anonimizados y no tocan una base real.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `app/Libraries/Payments/PaymentOrchestrator.php` (propuesta) | Coordinar intención, pasarela, respuesta y actualización de estado sin sesión, vistas ni HTTP. |
| Modificar | `app/Config/Services.php` | Agregar propiedad estática y `paymentOrchestrator($getShared = true)` con el mismo patrón de `paymentService()`. |
| Modificar | `app/Controllers/Pagos.php` | Delegar en el orquestador y retirar del controlador las consultas y la composición que se mueven; conservar sesión, propiedad, estado, vistas, URLs y `die()`. |
| Agregar | `tests/app/Libraries/Payments/PaymentOrchestratorTest.php` (propuesta) | Fijar la composición de respuestas, las llamadas a la pasarela y la actualización de estado con dobles. |
| Modificar | `MEMORY.md` | Registrar que la orquestación ya no vive en `Pagos` y que REF-002 quedó cerrado. |

No se modifican las clases de pasarela, `PaymentService` (salvo lo de REF-001), las vistas, las rutas ni la base de datos.

## Plan de pasos

1. **Fase 0, caracterización:** en un entorno autorizado, capturar con datos anonimizados:
   - la respuesta completa de `prePago('saldofavor', $id)` para una intención en estado `2`;
   - la respuesta de `postPago('saldofavor', $id)` con un POST válido;
   - el efecto sobre el estado cuando la pasarela no gestiona el pago;
   - el caso de estado distinto de `2` y el caso `$id` nulo.
   Registrar llaves, valores representativos, orden de consultas y efectos. No usar datos personales reales en el plan ni en las pruebas.
2. **Crear el orquestador:** clase sin estado, constructor con `?PaymentService`, y métodos `prePayment()`/`postPayment()`. Encapsular consultas en `obtenerIntencionPrePago()`, `obtenerBancosActivos()` y `actualizarEstadoIntencion()` protegidos.
3. **Implementar `prePayment()`:** replicar exactamente las consultas, la llamada a la pasarela y la composición actual; no agregar validaciones nuevas ni manejar la intención vacía de forma distinta.
4. **Implementar `postPayment()`:** replicar la llamada a la pasarela, `json_decode`, `forma_pago` y la actualización condicional de estado; no mover ni corregir la validación de estado del controlador.
5. **Registrar el servicio:** agregar `paymentOrchestrator()` en `Config\Services` y usarlo desde `Pagos`.
6. **Delegar en el controlador:** reemplazar las líneas de consulta/despacho/composición por la llamada al orquestador; conservar `validarSesion`, `validarPropietario`, la vista de `$id` nulo, el script de estado distinto de `2`, `CargarVistas`, `base_url`, `die()` y el `try/catch` de REF-001.
7. **Pruebas:** agregar las pruebas con dobles descritas abajo y ejecutarlas.
8. **Cierre:** smoke test manual, `php -l`, actualización de `MEMORY.md` y `graphify update .`.

## Estrategia de verificación

### Pruebas existentes que cubren el comportamiento

- No hay pruebas de pagos en `tests/app`. La caracterización se obtiene de la captura manual de la fase 0 y se fija en las pruebas nuevas del orquestador.
- No se debe intentar ejecutar la suite completa por el fallo preexistente de `BotChatSystemTest`.

### Pruebas de caracterización (antes de modificar)

- Capturar y documentar en la bitácora las respuestas actuales de `prePago()` y `postPago()` para `saldofavor` y, si es posible, `zelle`.
- Guardar fixtures anonimizados con las llaves y valores esperados; las pruebas del orquestador deben reproducir esas llaves exactamente.
- Verificar el número de consultas actuales por flujo (una intención, una bancos, una actualización condicional) para detectar duplicados después.

### Pruebas nuevas (después de implementar)

Con un `PaymentService` falso (subclase anónima) y una subclase de prueba de `PaymentOrchestrator` que sobrescriba los métodos protegidos:

- `testPrePaymentComponeLaRespuestaConLasLlavesActuales`: la respuesta contiene las llaves de la pasarela, `detalles_intencion_p`, `detalles_intencion` y `bancos` con los mismos valores del fixture.
- `testPrePaymentUsaElMontoYLaFormaDeLaIntencion`: el doble recibe `monto_total`, `id` y `forma_pago` correctos.
- `testPrePaymentNoDuplicaLaConsultaDeIntencion`: el método protegido se invoca una vez.
- `testPostPaymentDecodificaJsonYAgregaFormaPago`.
- `testPostPaymentActualizaEstadoCuandoNoEstaGestionado`: se llama una vez con el `id` y la respuesta esperada.
- `testPostPaymentNoActualizaEstadoCuandoEstaGestionado`: no se llama a la actualización.
- `testPostPaymentPropagaInvalidArgumentException`: el controlador puede conservar la salida legada de REF-001.
- `testPaymentOrchestratorSeRegistraComoCompartido`: dos llamadas a `Services::paymentOrchestrator()` devuelven la misma instancia.

### Prueba manual (smoke test)

1. En una base de desarrollo o pruebas autorizada, iniciar sesión con un estudiante con intención en estado `2`.
2. Abrir `/Pagos/prePago/saldofavor/{id}`. Resultado esperado: misma vista, monto, bancos, saldo, migajas y `post_pago_url` que antes.
3. Enviar `/Pagos/postPago/saldofavor/{id}`. Resultado esperado: mismo mensaje, ticket y actualización de estado que antes; una sola actualización.
4. Repetir con `zelle` si el entorno permite un comprobante de prueba; verificar carga de archivo y mensajes.
5. Probar un código no soportado y confirmar que se conserva la salida de REF-001.
6. Probar una intención con estado distinto de `2` y confirmar que el script de redirección sigue apareciendo y que el procesamiento continúa como hoy.
7. Ejecutar `vendor\bin\phpunit.bat tests\app\Libraries\Payments` y `php -l` sobre los archivos tocados.

## Riesgos y efectos secundarios

- **Deriva de comportamiento:** mover código puede cambiar el orden de consultas, las llaves de la vista o el momento del `die()`. Mitigación: diff línea por línea, fixtures de la fase 0 y smoke test.
- **Consultas duplicadas:** si el orquestador vuelve a consultar la intención en `postPago`, se duplica `find($id)`. Mitigación: recibir `$it` desde el controlador.
- **Corregir sin querer los casos borde:** el `$id` nulo y el estado distinto de `2` tienen un comportamiento defectuoso que debe conservarse. Mitigación: dejarlos en el controlador y probarlos en el smoke.
- **Acoplamiento con el framework:** si el orquestador usa `base_url`, sesión, vistas o `die()`, se pierde la mejora. Mitigación: revisar que no importe helpers HTTP ni `BaseController`.
- **Estado compartido:** `Services::paymentOrchestrator()` es compartido; la clase debe ser sin estado mutable para no filtrar datos entre peticiones.
- **`json_decode` nulo:** si una pasarela devuelve algo no JSON, el comportamiento actual falla al asignar `forma_pago`. No se corrige en este refactor; el orquestador debe replicar la misma secuencia.
- **Cobertura de pasarelas:** las pruebas usan dobles y no cubren las siete pasarelas reales; el smoke debe incluir al menos una pasarela sin efectos externos y, si es posible, Zelle.
- **Dependencia de REF-001:** si REF-001 no está aplicado, el `try/catch` y el mensaje legado pueden no coincidir. Ejecutar en orden.

## Rollback

- Revertir los commits de REF-002 con `git revert`; REF-001 puede permanecer porque es independiente y ya está verificado.
- No hay migraciones, seeds ni cambios de esquema. Las actualizaciones de estado ocurridas durante el smoke se hacen en una base de pruebas autorizada y deben restaurarse o descartarse.
- Si el rollback de REF-002 deja código sin usar, retirar también `Services::paymentOrchestrator()` y las pruebas nuevas en el mismo revert.

## Criterios de finalización

- [ ] `PaymentOrchestrator` existe, no tiene estado mutable y no conoce sesión, vistas, `base_url` ni `die()`.
- [ ] `Services::paymentOrchestrator()` está registrado y `Pagos::prePago()`/`postPago()` lo usan.
- [ ] El controlador conserva sesión, propiedad, estado, vistas, URLs, `die()` y el `try/catch` de REF-001.
- [ ] Las respuestas de `prePago()`/`postPago()` tienen las mismas llaves, valores y textos que antes.
- [ ] No se duplican consultas: una intención, una bancos y una actualización condicional por flujo.
- [ ] La actualización de estado ocurre exactamente cuando `empty($response['gestionado'])`.
- [ ] Los casos borde actuales (`$id` nulo y estado distinto de `2`) se conservan sin corregir.
- [ ] Las pruebas nuevas pasan y el smoke test confirma paridad antes/después.
- [ ] No se modificaron pasarelas, rutas, filtros, vistas, esquema, seeds, datos ni configuración.
- [ ] `MEMORY.md` refleja el cierre y `graphify update .` se ejecutó si hubo cambios de código.

## Preguntas abiertas

- ¿Se confirma que `postPago` puede recibir la intención ya consultada en lugar de volver a consultarla? Es la opción que evita duplicar `find($id)` y conserva la validación de estado en el controlador.
- ¿Existe algún consumidor de `Pagos::prePago()`/`postPago()` distinto de las vistas y el auto-routing? La búsqueda local solo encontró enlaces en `app/Views/pagos`.
- ¿Los métodos del orquestador deben llamarse `prePayment()`/`postPayment()` (consistencia con `PaymentService`) o `prePago()`/`postPago()` (consistencia con el controlador)? El plan asume los primeros.
- ¿Se acepta que el orquestador use los modelos actuales mediante métodos protegidos, sin introducir interfaces de repositorio? El plan asume que sí.
- ¿Se confirma que el comportamiento defectuoso de estado distinto de `2` y `$id` nulo se conserva y se corrige en otra tarea? El plan asume que sí.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-27 | Creación del plan REF-002 a partir de la entrevista de alcance; depende de REF-001. | opencode (agente) |
| 2026-10-27 | Ejecución en `p-refactor/payment-orchestrator-pagos`: orquestador, servicio compartido, delegación del controlador y pruebas. Smoke test pendiente por falta de base autorizada. Ver `prototipo.md`. | opencode (agente) |
