# Centralizar el despacho de formas de pago en `PaymentService`

- **Código:** REF-001
- **Tipo:** refactor
- **Estado:** en curso (código y pruebas automatizadas completos; smoke test manual pendiente)
- **Fecha:** 2026-10-27
- **Autor:** opencode (agente)

## Objetivo

Sustituir la cadena de `if/else` de `PaymentService::getPaymentService()` por un mapa único `FORMAS_SOPORTADAS` (código → clase), exponer `soporta()` y reemplazar el `echo` + `exit` del servicio por `InvalidArgumentException`. El controlador `Pagos` conservará exactamente la salida visible actual para un código no soportado.

## Motivación

La lista de pasarelas está codificada como una cadena de comparaciones y el conocimiento de las formas de pago válidas queda disperso entre `PaymentService`, `Pagos` y `pg_formas_pago`. No hay una consulta única de soporte (`soporta()`), el camino de error no es testeable porque termina el proceso, y una librería de dominio no debería emitir HTML ni terminar la petición.

## Estado actual

- `PaymentService::getPaymentService()` (`app/Libraries/Payments/PaymentService.php:64-118`) resuelve siete códigos mediante `if/else`: `bnscboton`, `c2pmercant`, `bncvpos`, `bncc2p`, `saldofavor`, `pagomovilb` y `zelle`.
- Un código desconocido imprime `Tipo de pago '<código>' no soportado.` y ejecuta `exit` (`app/Libraries/Payments/PaymentService.php:109-114`). No hay `soporta()` ni mapa central.
- `prePayment()` y `postPayment()` (`app/Libraries/Payments/PaymentService.php:15-56`) validan `is_string`/`is_array` y devuelven `false` si el tipo es inválido.
- La guarda de tipo de `getPaymentService()` (`app/Libraries/Payments/PaymentService.php:66`) es contradictoria y no protege el despacho de forma fiable; el único consumidor encontrado es `Pagos`.
- `Pagos::prePago()` (`app/Controllers/Pagos.php:948-1022`) y `Pagos::postPago()` (`app/Controllers/Pagos.php:1030-1116`) llaman a `Services::paymentService()` y no capturan la terminación del servicio.
- El seed `PgFormasPagoSeeder` declara siete formas activas soportadas y `pgvenez` inactiva (`app/Database/Seeds/PgFormasPagoSeeder.php:14-95`). Los títulos de `Pagos` incluyen códigos no soportados (`bncboton`, `mercboton`, `pgvenez`) en `app/Controllers/Pagos.php:997-1007`, por lo que una URL construida a mano puede alcanzar el camino no soportado.
- No existen pruebas de pagos en `tests/app`; la suite completa no inicia por un fallo preexistente ajeno a este cambio (`tests/app/Models/BotChatSystemTest.php`).

## Qué mejora este refactor

- **Legibilidad:** una sola tabla declarativa reemplaza siete ramas y sus comentarios repetidos.
- **Mantenibilidad:** agregar o retirar una pasarela del despacho se hace en un único lugar.
- **Testabilidad:** `soporta()` y el mapa pueden probarse sin ejecutar el proceso; el error deja de ser un `exit`.
- **Duplicación / acoplamiento:** se elimina el conocimiento repetido de códigos y se desacopla la librería de la salida HTML y de la terminación de la petición.
- **Rendimiento:** equivalente; una búsqueda en arreglo reemplaza comparaciones encadenadas, sin consultas adicionales.

## Invariantes (qué NO debe cambiar)

- Las siete formas soportadas siguen apuntando a las mismas clases y devuelven la misma instancia por código.
- Las firmas públicas `prePayment($t_payment, $data)`, `postPayment($t_payment, $data)`, `getPaymentService(string $t_payment)` y el registro `Services::paymentService()` se conservan.
- `prePayment()`/`postPayment()` siguen devolviendo `false` cuando reciben tipos inválidos, antes de resolver la pasarela.
- Para un código no soportado, la respuesta HTTP visible sigue siendo el texto exacto `Tipo de pago '<código>' no soportado.` seguido de la terminación actual, sin cargar vista. El `echo`/`exit` se reproduce en el controlador, en el mismo punto del flujo.
- Los flujos de las siete pasarelas, sus vistas, montos, mensajes y efectos secundarios no cambian.
- No cambian rutas, filtros, esquema, seeds, datos ni configuración.
- No se agregan formas de pago ni se activa `pgvenez`.

## Alcance

- **Incluye:** mapa `FORMAS_SOPORTADAS`, `soporta()`, despacho por mapa, `InvalidArgumentException` en `PaymentService`, captura en `Pagos::prePago()`/`postPago()` para conservar la salida actual, limpieza de imports/variables muertas y pruebas unitarias del despacho.
- **No incluye:** `PaymentOrchestrator` (ver REF-002), cambios en pasarelas, nuevas interfaces, cambios de rutas, corrección de defectos preexistentes (por ejemplo, la guarda de tipo, el flujo de estado distinto de `2` o el `id` nulo) ni cambios de experiencia de usuario.

## Contexto y supuestos

- El repositorio está en la rama `feature/desacoplar-contructor-pagos`; este plan no cambia de rama.
- PHP objetivo 8.0; no hay `strict_types`, por lo que se mantiene la coerción actual.
- `Pagos` es el único consumidor de `PaymentService` (búsqueda en `app/`, `tests/` y `public/`). Si existiera un consumidor externo no versionado, el cambio de `echo/exit` a excepción en el servicio sería visible para él.
- El camino no soportado solo es alcanzable con una URL construida a mano o si se activa una forma sin clase asociada; con los datos del seed actual no se llega desde la UI normal.
- `FORMAS_SOPORTADAS` será `public const` para permitir inspección y pruebas. Si se prefiere no exponerlo, puede ser `private` sin afectar el resto del plan.
- El mensaje de la excepción será exactamente el texto legado, sin salto de línea, para que el controlador pueda reutilizarlo.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Modificar | `app/Libraries/Payments/PaymentService.php` | Agregar `FORMAS_SOPORTADAS`, `soporta()`, despachar por mapa y lanzar `InvalidArgumentException`; retirar imports y variables sin uso. |
| Modificar | `app/Controllers/Pagos.php` | Capturar `InvalidArgumentException` en el mismo punto donde hoy se llama a `prePayment()`/`postPayment()` y reproducir el `echo` + `exit` actual. |
| Agregar | `tests/app/Libraries/Payments/PaymentServiceTest.php` (propuesta) | Cubrir mapa, `soporta()`, instancias, entradas inválidas, mensaje de excepción y delegación con dobles. |
| Modificar | `MEMORY.md` | Registrar el cierre del bloque de despacho y el estado de REF-002. |

No se modifica `app/Config/Services.php`, las pasarelas, las rutas ni la base de datos.

## Plan de pasos

1. **Caracterización previa:** agregar pruebas que fijen el comportamiento actual de las siete formas (clase devuelta) y de las entradas inválidas (`false`). Registrar en la bitácora el texto exacto y el efecto del camino no soportado mediante una sonda manual en un entorno autorizado.
2. **Mapa único:** declarar `FORMAS_SOPORTADAS` con los siete códigos y las clases actuales, en el mismo namespace.
3. **Soporte:** agregar `soporta($t_payment): bool`; debe devolver `false` para valores no string, cadena vacía o código desconocido, sin lanzar excepción.
4. **Despacho:** reescribir `getPaymentService()` para validar con `soporta()` y, si no hay soporte, lanzar `InvalidArgumentException` con el mensaje legado. Conservar la firma y el retorno de la instancia.
5. **Controlador:** envolver la llamada a `prePayment()` en `prePago()` y a `postPayment()` en `postPago()` con `try/catch (\InvalidArgumentException $e)`, en el mismo lugar donde hoy ocurre el despacho; en el `catch`, hacer `echo $e->getMessage(); exit;`. No mover la validación de sesión, propiedad, estado, vistas ni `die()` existentes.
6. **Limpieza:** retirar `use App\Controllers\Pagos`, `use Config\Services` y la variable `$response = null` si quedan sin uso; actualizar docblocks con `@throws` en español.
7. **Verificación:** ejecutar las pruebas del área, `php -l` sobre los archivos modificados y el smoke test manual.
8. **Cierre:** actualizar `MEMORY.md` y ejecutar `graphify update .` si se modificó código.

## Estrategia de verificación

### Pruebas existentes que cubren el comportamiento

- No hay pruebas de pagos en `tests/app`. Este plan debe crear la red de seguridad antes de cambiar el despacho.
- La suite completa no inicia por `BotChatSystemTest`; ejecutar solo el directorio nuevo.

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

- `PaymentServiceCharacterizationTest` (puede vivir en el mismo archivo final):
  - Para cada uno de los siete códigos, `getPaymentService($codigo)` devuelve una instancia de la clase esperada.
  - `prePayment($t_payment, $data)` y `postPayment($t_payment, $data)` devuelven `false` con `t_payment` no string o `data` no array.
  - `prePayment('saldofavor', ['monto_total' => 100, 'id' => 1, 'forma_pago' => 'saldofavor'])` devuelve `['vista' => 'pagos/pagar_int_saldofavor']`, que es el comportamiento actual de una pasarela sin efectos secundarios.
- Sonda manual del camino no soportado: invocar `Pagos/prePago/no_soportado/{id}` y `Pagos/postPago/no_soportado/{id}` en un entorno autorizado y anotar texto exacto, ausencia de vista y terminación. No usar datos reales.

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

- `testMapaContieneExactamenteLasSieteFormasSoportadas`.
- `testSoportaDevuelveTrueParaCadaCodigoYFalseParaDesconocidoOVacio`.
- `testGetPaymentServiceDevuelveLaClaseEsperadaParaCadaCodigo`.
- `testGetPaymentServiceLanzaInvalidArgumentExceptionConElMensajeLegado`.
- `testPrePaymentYPostPaymentDevuelvenFalseConTiposInvalidos`.
- `testPrePaymentDelegaEnLaPasarela` usando `saldofavor`.
- `testPostPaymentDelegaEnLaPasarela` con una subclase anónima de `PaymentService` que sobrescriba `getPaymentService()` y devuelva un doble; así se evita ejecutar una pasarela real.

### Prueba manual (smoke test)

1. En una base de desarrollo o pruebas autorizada, iniciar sesión con un estudiante que tenga una intención de pago en estado `2`.
2. Abrir `/Pagos/prePago/saldofavor/{id}`. Resultado esperado: la misma vista, monto, bancos, saldo a favor y `post_pago_url` que antes del cambio.
3. Enviar `/Pagos/postPago/saldofavor/{id}`. Resultado esperado: el mismo mensaje, ticket y actualización de estado que antes.
4. Repetir al menos con `zelle` si el entorno permite cargar un comprobante de prueba; verificar que el archivo y los mensajes no cambian.
5. Solicitar `/Pagos/prePago/no_soportado/{id}` y `/Pagos/postPago/no_soportado/{id}`. Resultado esperado: exactamente `Tipo de pago 'no_soportado' no soportado.`, sin vista, con la misma terminación que antes del refactor.
6. Ejecutar `vendor\bin\phpunit.bat tests\app\Libraries\Payments` y `php -l` sobre los archivos tocados.

## Riesgos y efectos secundarios

- **Cambio de contrato interno:** `getPaymentService()` deja de terminar el proceso y lanza excepción. No se encontraron otros consumidores, pero un consumidor externo no versionado vería la excepción. El controlador conserva la salida HTTP.
- **Mensaje distinto:** si la excepción no usa el texto exacto, el usuario vería otro mensaje. Se fija el texto legado en una prueba.
- **Mapa incompleto o clase incorrecta:** rompería una pasarela. Las pruebas recorren los siete códigos.
- **Pruebas con `exit`:** no se puede probar el `exit` en el mismo proceso; el camino legado se verifica con sonda manual y la excepción se prueba por separado.
- **Auto-routing:** `prePago()` y `postPago()` son métodos públicos alcanzables por URI; no se cambia su firma ni visibilidad.
- **`pgvenez`:** sigue inactiva; si se activa sin clase asociada, el camino no soportado se vuelve alcanzable y debe conservar el mensaje.

## Rollback

- Revertir el commit o commits de REF-001 con `git revert`. No hay migraciones, seeds ni cambios de datos que deshacer.
- Si REF-002 ya estuviera en curso, revertir primero REF-002 y luego REF-001, porque el orquestador consume el nuevo despacho.
- Las pruebas nuevas pueden conservarse o retirarse junto con el commit; no afectan producción.

## Criterios de finalización

- [ ] `FORMAS_SOPORTADAS` contiene exactamente las siete formas actuales y cada una apunta a la misma clase.
- [ ] `soporta()` responde correctamente para códigos válidos, desconocidos, vacíos y valores no string.
- [ ] Un código desconocido lanza `InvalidArgumentException` con el mensaje legado exacto.
- [ ] `Pagos::prePago()` y `Pagos::postPago()` conservan el `echo` + `exit` y el mismo punto de salida para códigos no soportados.
- [ ] Las siete pasarelas y sus flujos no cambian.
- [ ] Las pruebas nuevas pasan y el smoke test manual confirma paridad antes/después.
- [ ] No se modificaron rutas, filtros, esquema, seeds, datos ni configuración.
- [ ] `MEMORY.md` refleja el estado y `graphify update .` se ejecutó si hubo cambios de código.

## Preguntas abiertas

- ¿Existe algún consumidor de `PaymentService::getPaymentService()` fuera de este repositorio? La búsqueda local solo encontró `Pagos`.
- ¿Se confirma que el camino no soportado responde HTTP 200 (sin status explícito) y termina con código 0? Se asume por el `echo` + `exit` actual.
- ¿`FORMAS_SOPORTADAS` debe ser público o basta con `soporta()`? El plan asume `public const`.
- ¿Se quiere conservar literalmente el mensaje sin salto de línea? El plan asume que sí.
- ¿Se debe mantener `pgvenez` inactiva durante este refactor? El plan asume que sí.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-27 | Creación del plan REF-001 a partir de la entrevista de alcance. | opencode (agente) |
| 2026-10-27 | Ejecución del plan: mapa, `soporta()`, excepción, captura en `Pagos` y pruebas. Smoke test manual pendiente por falta de sede autorizada. | opencode (agente) |
