# Mensaje amigable ante formas de pago no soportadas

- **Código:** BUG-003
- **Tipo:** bugfix
- **Estado:** en curso

## Objetivo

Corregir la experiencia del estudiante cuando llega a `Pagos::prePago()` o `Pagos::postPago()` con una forma de pago que no tiene pasarela registrada (por ejemplo `pgvenez` o `bncboton`). En lugar de exponer el mensaje técnico de la excepción, un `exit` sin contexto o un error 500, el portal debe mostrar la vista de mensaje existente con un texto claro y un botón para volver a elegir la forma de pago, registrando el detalle técnico solo en los logs.

## Problema

`PaymentService::FORMAS_SOPORTADAS` solo registra siete códigos (`bnscboton`, `c2pmercant`, `bncvpos`, `bncc2p`, `saldofavor`, `pagomovilb` y `zelle`). `pgvenez` y `bncboton` no forman parte del mapa, aunque aparecen en los títulos de migaja de `Pagos::prePago()` y pueden existir como filas activas en `pg_formas_pago`. Cuando el estudiante abre una URL construida con uno de esos códigos, `PaymentService::getPaymentService()` lanza `InvalidArgumentException`.

En la rama actual el controlador ya captura esa excepción, pero responde con `echo $e->getMessage(); exit;` (`app/Controllers/Pagos.php:966-972` y `:1056-1067`). El estudiante ve un texto técnico y la petición termina sin la vista del portal. Antes de la incorporación de ese `try/catch` (REF-001), la excepción no se capturaba y el resultado era un 500. El reporte confirma que el fallo se observó en desarrollo/pruebas al no encontrarse la forma de pago, no en producción.

## Impacto

- **Usuarios:** un estudiante con una intención de pago activa que llegue a una forma no soportada no puede continuar y recibe una salida técnica. No hay pérdida de datos ni cobros incorrectos.
- **Operación:** no afecta procesos internos ni datos; solo la experiencia de pago en un caso de borde.
- **Gravedad:** baja. Es un defecto de manejo de error, no una regla de negocio ni una pasarela faltante.
- **Producción:** el usuario confirmó que no hay evidencia de afectación a usuarios reales. Si se confirmara lo contrario, el caso debe reclasificarse como **hotfix**.
- **Alcance:** `pgvenez` y `bncboton` siguen **no soportadas**. No se habilitan pasarelas nuevas en este bugfix.

## Reproducción

> Ejecutar solo en una base de desarrollo o pruebas autorizada. No usar producción.

1. Iniciar sesión como estudiante con una intención de pago en estado `2` (pendiente), en una sede autorizada.
2. Abrir manualmente `GET /Pagos/prePago/pgvenez/{id_intencion}` o `GET /Pagos/prePago/bncboton/{id_intencion}`.
3. Resultado actual: el controlador captura `InvalidArgumentException` y muestra el texto `Tipo de pago 'pgvenez' no soportado.` (o el código correspondiente) y termina con `exit`; en versiones sin el `try/catch` la respuesta es un 500.
4. Repetir con `GET|POST /Pagos/postPago/pgvenez/{id_intencion}` y `GET|POST /Pagos/postPago/bncboton/{id_intencion}`.
5. Resultado actual: mismo comportamiento de salida técnica, sin vista del portal ni botón de retorno.
6. Verificar que existe una fila activa con esos códigos en `pg_formas_pago` y que la vista `pagos/elegir_tp_forma_pago.php` genera el enlace `Pagos/prePago/{codigo}/{id}`; eso explica cómo un estudiante puede llegar al caso.

## Comportamiento esperado

- Ante `pgvenez`, `bncboton` o cualquier código ausente de `PaymentService::FORMAS_SOPORTADAS`, el portal muestra `app/Views/templates/mensaje.php` con el texto: **“La forma de pago seleccionada no está disponible. Por favor, elige otra.”**
- El botón **Volver** lleva a `Pagos/PagarEnLinea`, donde el estudiante puede elegir otra forma de pago.
- La respuesta ya no es un 500 ni un `echo` de la excepción; se sirve la vista normal del portal con HTTP 200.
- El detalle técnico (código de forma de pago y mensaje de la excepción) se registra en `writable/logs` como advertencia, sin datos personales ni secretos.
- Las formas soportadas (`bnscboton`, `c2pmercant`, `bncvpos`, `bncc2p`, `saldofavor`, `pagomovilb`, `zelle`) conservan su comportamiento actual.
- Se mantienen `validarSesion()` y `validarPropietario()` antes de cualquier respuesta, y no cambian las rutas ni el contrato HTTP de `prePago()`/`postPago()`.
- No se modifica `PaymentService::FORMAS_SOPORTADAS` ni se agregan clases de pasarela.

## Causa raíz (hipótesis)

Hipótesis sustentada en el código actual:

- `PaymentService::getPaymentService()` valida el código contra `FORMAS_SOPORTADAS` y lanza `InvalidArgumentException` cuando no existe (`app/Libraries/Payments/PaymentService.php:79-83`).
- `pgvenez` y `bncboton` no están en ese mapa (`app/Libraries/Payments/PaymentService.php:12-20`), por lo que cualquier intento de usarlos termina en esa excepción.
- `Pagos::prePago()` y `Pagos::postPago()` capturan la excepción, pero la traducen a `echo $e->getMessage(); exit;` en lugar de cargar una vista (`app/Controllers/Pagos.php:966-972` y `:1056-1067`). Antes de REF-001 no existía el `try/catch`, de ahí el 500.
- Los títulos de migaja incluyen `pgvenez` y `bncboton` (`app/Controllers/Pagos.php:982` y `:988`), y la vista de elección arma el enlace con el código de la base (`app/Views/pagos/elegir_tp_forma_pago.php:62`), lo que permite llegar al caso aunque la pasarela no esté soportada.

La causa queda confirmada por lectura de código. La reproducción HTTP exacta y el mensaje del 500 original no se pudieron verificar en este entorno por falta de base/sede autorizada y porque la rama actual ya incorpora el `try/catch`.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `docs/bugfix/003-formas-pago-no-soportadas/plan.md` | Documento de este plan. |
| Modificar | `app/Controllers/Pagos.php` | Reemplazar el `echo`/`exit` de ambos `catch` por un método privado que registre el detalle y cargue `templates/mensaje` con el texto y el retorno acordados. Detener el flujo tras renderizar, sin ejecutar el resto de `prePago()`/`postPago()`. |
| Modificar | `tests/app/Libraries/Payments/PaymentServiceTest.php` | Incluir `bncboton` entre los códigos no soportados y fijar que `pgvenez` y `bncboton` lanzan la excepción legada. `pgvenez` ya aparece en la lista de `soporta()`; falta cubrir ambos en `getPaymentService()`. |
| Modificar | `tests/app/Libraries/Payments/PaymentOrchestratorTest.php` | Agregar pruebas de regresión que demuestren que `prePayment()` y `postPayment()` propagan `InvalidArgumentException` para `pgvenez` y `bncboton`, usando el orquestador de prueba ya existente. |

No se modifica `app/Views/templates/mensaje.php`: se reutiliza con las llaves `mensaje` y `retorno` que ya admite (`app/Views/templates/mensaje.php:22-28`). No se modifica `PaymentService` ni se agregan pasarelas.

## Plan de verificación

### Prueba manual (flujo normal)

> Requiere una base/sede de desarrollo o pruebas autorizada, un estudiante con sesión y una intención en estado `2`. No ejecutar en producción.

1. Iniciar sesión como estudiante y confirmar que existe una intención de pago pendiente.
2. Abrir `GET /Pagos/prePago/pgvenez/{id_intencion}`.
3. Resultado esperado: se muestra la vista de mensaje con el texto “La forma de pago seleccionada no está disponible. Por favor, elige otra.”, botón **Volver** hacia `Pagos/PagarEnLinea`, sin el mensaje `Tipo de pago '...' no soportado.` y sin 500.
4. Repetir con `bncboton` en `prePago` y con ambos códigos en `postPago`; el resultado debe ser el mismo y no debe continuar hacia ninguna pasarela.
5. Revisar `writable/logs` y confirmar una advertencia con el código no soportado y el mensaje técnico, sin datos personales.
6. Probar una forma soportada (por ejemplo `saldofavor`) y confirmar que su flujo no cambió.
7. Probar con un usuario sin sesión y con un usuario que no es propietario de la intención; deben conservarse las validaciones actuales (`validarSesion()` y `validarPropietario()`).
8. Revisar que el código no soportado no se muestre en la interfaz (solo el texto amigable).

### Prueba automatizada / código de verificación

No se crea código de prueba nuevo en este paso de planificación. La verificación automatizada se implementará junto con la corrección y se ejecutará con:

```sh
vendor\bin\phpunit.bat tests\app\Libraries\Payments --no-coverage
```

Cobertura propuesta:

- `PaymentServiceTest`: `soporta()` devuelve `false` para `pgvenez` y `bncboton`; `getPaymentService()` lanza `InvalidArgumentException` con el mensaje legado para ambos.
- `PaymentOrchestratorTest`: `prePayment()` y `postPayment()` propagan la excepción para `pgvenez` y `bncboton` sin intentar normalizar una respuesta inexistente. Se reutiliza `orquestadorDePrueba()` con datos fijos para evitar base real.
- La renderización de la vista se valida manualmente en el flujo normal, porque `Pagos` requiere sesión, base y `CargarVistas()`; no se propone una prueba HTTP completa para este bugfix pequeño.

Resultado esperado: la suite de `tests/app/Libraries/Payments` sigue en verde, con los nuevos casos agregados (actualmente 15 tests, 60 assertions).

## Riesgos y efectos secundarios

- **Captura demasiado amplia:** el `catch` de `InvalidArgumentException` también atraparía una excepción lanzada dentro de una pasarela soportada. El mensaje “no disponible” podría ser impreciso en ese caso; se mitiga registrando el mensaje exacto en el log y manteniendo el texto genérico. Si se detecta ese escenario, se puede condicionar el texto con `PaymentService::soporta($forma_pago_det)`.
- **Pérdida de diagnóstico visible:** al dejar de mostrar el mensaje técnico, el soporte debe revisar logs. Es el comportamiento deseado; se documenta la ubicación de `writable/logs`.
- **Comportamiento de `exit`:** al reemplazarlo por un retorno tras cargar la vista, hay que asegurar que `prePago()` no continúe hacia el `CargarVistas()` normal ni hacia el `die()` final, y que `postPago()` no siga construyendo el mensaje de ticket.
- **Casos borde preexistentes:** `postPago()` con `$id` nulo o con una intención inexistente sigue teniendo avisos y accesos a `null`; este bugfix no los corrige para no ampliar el alcance. Si se reproducen como 500, deben tratarse en un bugfix separado.
- **Dependencia de datos:** si `pg_formas_pago` tiene activas formas sin pasarela, el enlace seguirá apareciendo; este bugfix solo mejora la respuesta al hacer clic. Ocultar esas formas o desactivarlas en datos es una decisión operativa separada.
- **Smoke test:** requiere base/sede autorizada; si no está disponible, se documentará como pendiente y no se afirmará que el flujo HTTP quedó verificado.

## Criterios de finalización

- [ ] `GET /Pagos/prePago/pgvenez/{id}` y `/Pagos/prePago/bncboton/{id}` muestran la vista de mensaje con el texto acordado, HTTP 200, sin `echo` técnico ni 500.
- [ ] `GET|POST /Pagos/postPago/pgvenez/{id}` y `/Pagos/postPago/bncboton/{id}` muestran la misma vista y no continúan el flujo de pago.
- [ ] El botón **Volver** apunta a `Pagos/PagarEnLinea`.
- [ ] El código y el mensaje técnico quedan en `writable/logs` sin datos personales.
- [ ] Las siete formas soportadas conservan su comportamiento y sus pruebas pasan.
- [ ] `PaymentServiceTest` y `PaymentOrchestratorTest` cubren `pgvenez` y `bncboton` como no soportados.
- [ ] `vendor\bin\phpunit.bat tests\app\Libraries\Payments --no-coverage` termina en verde.
- [ ] `validarSesion()` y `validarPropietario()` siguen ejecutándose antes de la respuesta amigable.
- [ ] No se modificaron rutas, filtros, pasarelas, `FORMAS_SOPORTADAS`, esquema ni datos.

## Notas del programador

- La referencia “Debe ir junto con 003-03” se descarta por indicación del usuario: es un asunto externo y no forma parte de este plan.
- Este plan no implementa la corrección; solo define el alcance, la causa probable y la verificación.
- `pgvenez` y `bncboton` permanecen no soportados. Habilitarlos requeriría un plan de feature o integración de pasarela, no un bugfix.
- La vista `templates/mensaje` ya escapa el mensaje con `<?= $mensaje ?>` sin `esc()`; el texto es una constante controlada por el servidor, no un dato de entrada, por lo que no se agrega interpolación de datos del usuario. No pasar el nombre del código ni la excepción a esa vista.
- Si se decide usar un método privado, mantenerlo en `Pagos` y que reciba solo el código de forma de pago; no debe devolver HTML ni exponer la excepción.
- Documentación relacionada: `docs/refactor/001-payment-service-mapa-formas-pago/` y `docs/refactor/002-payment-orchestrator-pagos/`.
