# Prototipo de ejecución — FEAT-005 Métodos y pago en línea del Paso 4 de nuevo ingreso

- **Rama:** p-feature/metodos-pago-en-linea-paso-4
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/005-metodos-pago-en-linea-paso-4/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado
- **Consolidado en:** feature/desacoplar-contructor-pagos
- **Fecha de consolidación:** 2026-10-28

## Resumen

Se completó el Paso 4 de nuevo ingreso con la selección de métodos (reportar o pagar en línea), la lista de formas por familia y el ciclo preparar/procesar contra las pasarelas existentes. La identidad, la sede, el monto y la forma se validan desde la sesión `nuevo_ingreso`, la postulación y `pg_intenciones_pago`; `saldofavor` queda excluido. Se conservaron sin cambios los métodos del portal regular en `PaymentOrchestrator` y se parametrizaron las seis vistas de pasarela para renderizarse embebidas.

## Tareas realizadas

- [x] Fase A — Catálogo robusto y selección de métodos: `FormasPagoModel`, parciales, vistas `metodos`/`formas_pago`, rutas GET y enlace desde `estado.php`.
- [x] Fase B — Preparación de pasarela: `prepararPago()`, contrato, `prePago()`, ruta GET, `PaymentOrchestrator::preparar()` y parametrización de las seis vistas.
- [x] Fase C — Procesamiento: `procesarPago()`, `postPago()`, ruta POST, idempotencia, Zelle/pagomovilb y manejo de respuestas.
- [x] Pruebas del modelo, servicio, orquestador e integración del controlador.
- [x] `php -l`, suites del área, `graphify update .` y documentación.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `getFormasPagoPorTipo()` acepta solo `po`/`rp` y devuelve `[]` con otro valor | `FormasPagoModelTest::testRechazaTipoInvalidoSinConsultar` | ok |
| Ordena por `orden` si existe y por `id` si no | `testOrdenaPorIdCuandoNoExisteLaColumnaOrden`, `testOrdenaPorOrdenCuandoLaColumnaExiste` | ok |
| Exige forma activa, banco activo y `borrado_dt IS NULL`, y devuelve `banco_nombre`/`logo` | `testFiltraInactivosBorradosYDevuelveDatosDelBanco` | ok |
| `formasPagoDisponibles()` excluye `saldofavor` y no soportadas | Pruebas existentes y `Paso4PagoTest` | ok |
| `GET /paso-4/metodos` exige filtro y estado `pagando`; oculta familias vacías | `Paso4PagoTest` (métodos, familia vacía, sin formas, aprobada) | ok |
| `GET /paso-4/reportar` y `en-linea` renderizan su familia y redirigen si está vacía | `Paso4PagoTest` (rp, po, familia vacía) | ok |
| La pantalla de métodos muestra cancelar, intentos y volver | `Paso4PagoTest::testMetodosRenderizaSoloLasFamiliasConFormas` | ok |
| La pantalla de formas muestra descripción, logo, volver y cancelar | `Paso4PagoTest` y parcial `_formas_pago.php` | ok |
| `GET /prepago/{codigo}/{id}` valida sesión, paso, propiedad, estado, sede y forma; no escribe | `Paso4PagoTest`, `NuevoIngresoPagoServiceTest` | ok |
| `prePago` pasa intención, detalles, bancos, `post_pago_url`, breadcrumbs, `embebida` y `urls` | Revisión de `Paso3::prePago()` y render de Zelle embebida | ok |
| `POST /postpago/{codigo}/{id}` rechaza métodos distintos de POST con 405 | `Paso4PagoTest::testPostPagoRechazaMetodoGetCon405` | ok |
| `postPago` valida propiedad, estado, sede y forma; aprobadas/pendientes son idempotentes | `Paso4PagoTest` y `NuevoIngresoPagoServiceTest` | ok |
| `postPago` despacha monto persistido, POST, archivos, conexión de sede y pagador | `testProcesarPagoDespachaMontoPagadorYConexion`, `testPostPagoPagomovilbDespachaLaFormaElegida` | ok |
| Pasarelas no Zelle confirmadas dejan 3; Zelle deja 7 y no recibe segunda actualización | Pruebas de `PaymentOrchestrator::procesar()` (`gestionado`) | ok, con doble del orquestador |
| `pagomovilb` aprueba en 3 si el banco confirma y conserva 2 si falla | Respuestas simuladas success/error en `Paso4PagoTest` | ok, sin banco real |
| `postPago` redirige a `/paso-4` con `exito_pago`/`error_pago`; sin recibo ni GHL | `Paso4PagoTest` | ok |
| Las seis vistas soportan `$embebida` y usan `$post_pago_url`; el portal regular conserva su comportamiento | `php -l`, revisión y fallback de acciones | ok |
| Todos los formularios usan POST; `bnscboton` ya no es enlace GET | Revisión de vistas y `Paso4PagoTest` | ok |
| `estado.php` muestra "Elegir método de pago" en `pagando` | `Paso4NuevoIngresoTest::testIndexEstadoPagandoMuestraAvisoYCancelar` | ok |
| `PaymentOrchestrator::preparar()` lanza excepción capturable si la pasarela no devuelve arreglo | `testPrepararLanzaExcepcionCapturableCuandoLaPasarelaNoDevuelveArreglo` | ok |
| Métodos públicos nuevos ejecutan `sesionValida()` y validación de estado | Revisión de `Paso3` y pruebas de acceso directo | ok |
| Vistas escapan salida con `esc()` | Revisión de vistas nuevas y modificadas | ok |
| Pruebas cubren modelo, servicio, orquestador e integración (Zelle, pagomovilb, ajena, estado, forma, error) | Suites ejecutadas | ok |
| Pruebas existentes del Paso 4 y pagos siguen pasando | Suites ejecutadas | ok |
| `php -l` sin errores en PHP nuevo o modificado | Comando ejecutado sobre 16 archivos de aplicación y 5 de prueba | ok |
| `graphify update .` ejecutado | Comando ejecutado | ok |
| Sin migraciones, seeds, CSRF, dependencias ni cambios en `vendor/`/`system/` | `git status` y revisión | ok |
| No se persiste `formas_pago_id` en `prePago` | `testPrepararPagoDespachaLaIntencionConDescuentoYConexion` | ok |

## Flujos cubiertos

- **Flujo normal:** resumen en `pagando` → métodos → familia → `prePago` → formulario → `postPago` → redirección a `/paso-4` con flash.
- **Flujos alternativos:** solo una familia con formas, ninguna familia, intención aprobada, pendiente, creada/cancelada, Zelle y `pagomovilb`.
- **Control de errores:** sesión/paso inválidos, intención ajena o inexistente, sede distinta, forma no permitida, pasarela sin vista, método HTTP incorrecto, intención no pagable, respuesta de pasarela con error y fallo inesperado con log técnico.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Views/inscripciones/nuevo_ingreso/paso3/metodos.php` | Pantalla de selección de familia. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/formas_pago.php` | Pantalla de formas por familia. |
| `app/Views/pagos/partials/_metodos_pago.php` | Parcial de tarjetas de familia con render condicional. |
| `app/Views/pagos/partials/_formas_pago.php` | Parcial de formas con logo, descripción y enlace a `prepago`. |
| `tests/app/Models/PagosOnline/FormasPagoModelTest.php` | Cobertura del catálogo robusto. |
| `tests/app/Integration/Paso4PagoTest.php` | Cobertura de métodos, familias, `prePago` y `postPago`. |
| `docs/features/005-metodos-pago-en-linea-paso-4/prototipo.md` | Este documento. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Models/PagosOnline/FormasPagoModel.php` | Whitelist `po`/`rp`, filtros de activos y borrado, fallback de orden y datos de banco. |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | `prepararPago()`, `procesarPago()`, `estaAprobada()`/`estaPendienteVerificacion()` públicas y auxiliares de sede/pagador. |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php` | Declaración de los nuevos métodos del contrato. |
| `app/Libraries/Payments/PaymentOrchestrator.php` | Nuevos `preparar()`/`procesar()` con intención explícita y conexión de sede. |
| `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | `metodos()`, `reportar()`, `enLinea()`, `prePago()`, `postPago()` y auxiliares privados. |
| `app/Config/Routes.php` | Rutas GET/POST del flujo con `nuevoIngresoAuth:4`. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Enlace "Elegir método de pago" en `pagando`. |
| `app/Views/pagos/pagar_int_bnscboton.php` | `$embebida`, acción POST y fallback de URL. |
| `app/Views/pagos/pagar_int_bncc2p.php` | `$embebida`, acción POST y fallback de URL. |
| `app/Views/pagos/pagar_int_bncvpos.php` | `$embebida`, acción POST y fallback de URL. |
| `app/Views/pagos/pagar_int_c2pmercant.php` | `$embebida`, acción POST y fallback de URL. |
| `app/Views/pagos/pagar_int_pagomovilb.php` | `$embebida`, acción POST y fallback de URL. |
| `app/Views/pagos/pagar_int_zelle.php` | `$embebida` y fallback de `post_pago_url`. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Cobertura de `prepararPago()`/`procesarPago()` y soporte de `bases_datos`. |
| `tests/app/Libraries/Payments/PaymentOrchestratorTest.php` | Cobertura de `preparar()`/`procesar()` y excepción capturable. |
| `tests/app/Integration/Paso4NuevoIngresoTest.php` | Ajuste de la expectativa del aviso `pagando` al nuevo enlace. |
| `docs/features/005-metodos-pago-en-linea-paso-4/plan.md` | Estado completado, decisión del orquestador y bitácora. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:**
  - `GET inscripciones/nuevo-ingreso/paso-4/metodos` → `Paso3::metodos` (`nuevoIngresoAuth:4`).
  - `GET inscripciones/nuevo-ingreso/paso-4/reportar` → `Paso3::reportar` (`nuevoIngresoAuth:4`).
  - `GET inscripciones/nuevo-ingreso/paso-4/en-linea` → `Paso3::enLinea` (`nuevoIngresoAuth:4`).
  - `GET inscripciones/nuevo-ingreso/paso-4/prepago/(:segment)/(:num)` → `Paso3::prePago` (`nuevoIngresoAuth:4`).
  - `POST inscripciones/nuevo-ingreso/paso-4/postpago/(:segment)/(:num)` → `Paso3::postPago` (`nuevoIngresoAuth:4`).
- **Permisos y validaciones:** sesión `nuevo_ingreso` y `paso_actual >= 4`; propiedad por `ni_inscripcion_id`; estado `pagando`; coincidencia de sede `AASUCURSID`; forma dentro de `formasPagoDisponibles()`; solo GET en preparación y solo POST en procesamiento/cancelación.
- **Migraciones/seeds:** no aplica; no se crearon ni modificaron.
- **Compatibilidad:** `PaymentOrchestrator::prePayment()`/`postPayment()` y el portal regular se conservan. Las vistas de pasarela mantienen su header y URLs legadas cuando `$embebida` no se define y `$post_pago_url` no se pasa. `FormasPagoModel` ahora también filtra bancos inactivos y borrado lógico para el portal regular.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `phpunit tests/app/Libraries/Payments/PaymentOrchestratorTest.php` (línea base) | 10 pruebas, 23 aserciones, OK |
| `phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` (línea base) | 22 pruebas, 86 aserciones, OK |
| `phpunit tests/app/Integration/Paso4NuevoIngresoTest.php` (línea base) | 27 pruebas, 123 aserciones, OK |
| `phpunit tests/app/Integration/Paso3NuevoIngresoTest.php` (línea base) | 37 pruebas, 96 aserciones, OK |
| `php -l` sobre archivos PHP de aplicación y pruebas | Sin errores de sintaxis |
| `phpunit tests/app/Models/PagosOnline/FormasPagoModelTest.php` | 4 pruebas, 9 aserciones, OK |
| `phpunit tests/app/Libraries/Payments/PaymentOrchestratorTest.php` | 14 pruebas, 34 aserciones, OK |
| `phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | 33 pruebas, 125 aserciones, OK |
| `phpunit tests/app/Integration/Paso4PagoTest.php` | 19 pruebas, 67 aserciones, OK |
| `phpunit tests/app/Integration` | 115 pruebas, 365 aserciones, OK |
| `phpunit tests/app/Libraries` | 101 pruebas, 284 aserciones, OK |
| `phpunit tests/app/Models/PagosOnline` | 18 pruebas, 52 aserciones, OK |
| `phpunit tests/app/Database` | 46 pruebas, 118 aserciones, OK |
| `graphify update .` | Grafo actualizado (13 634 nodos, 27 995 aristas, 872 comunidades) |

## Verificación

- **Línea base (antes):** 96 pruebas del área (orquestador, servicio, Paso 3 y Paso 4) en verde.
- **Prueba manual (flujo normal):** no se ejecutó contra un navegador ni pasarelas reales; se verificó por integración con SQLite y doble del orquestador. Se agregó un smoke test con `PaymentService` real para `prePago` de `bncc2p`, que renderiza el formulario sin llamar al banco.
- **Flujos alternativos y errores:** cubiertos por `Paso4PagoTest` (familias vacías, estados aprobado/pendiente/no pagable, intención ajena, forma no permitida, 405, error de pasarela).
- **Pruebas automatizadas:** ver tabla de comandos.
- **Criterios del plan:** todos verificados; los relacionados con pasarelas reales se validaron con dobles, no contra sandbox.

## Desviaciones del plan

- **Orquestador:** el plan suponía que `preparar()`/`procesar()` ya existían y pedía no agregar métodos. En la rama solo existían `prePayment()`/`postPayment()`, y `prePayment()` busca por cédula excluyendo nuevo ingreso. Con autorización del usuario se agregaron `preparar()` y `procesar()` conservando los métodos existentes. El plan se actualizó en su sección de diseño y bitácora.
- **Excepción no importada:** no se "corrigió" una referencia inexistente; el nuevo `preparar()` lanza `\RuntimeException` correctamente.
- **Prueba existente:** `Paso4NuevoIngresoTest` esperaba el texto "etapa posterior" en estado `pagando`; se actualizó a "Elegir método de pago" porque el plan reemplaza ese aviso.
- **Descuento en Zelle:** el `preparar()` del orquestador recalcula el desglose con `desc_pg_dolar_ni` y la conexión de la sede. El `postPayment()` interno de `PagosZelleServices` sigue usando el descuento global `desc_pg_dolar`; no se modificó la pasarela por estar fuera del alcance.

## Riesgos y pendientes

- **Zelle:** si `desc_pg_dolar_ni` y `desc_pg_dolar` difieren, el total mostrado en `prePago` puede no coincidir con el monto registrado por la pasarela al procesar. Requiere decisión de negocio o una futura feature que parametrice el descuento dentro de Zelle.
- **CSRF:** el módulo sigue sin CSRF; los POST dependen de sesión, filtro y validaciones de dominio. Es deuda técnica acordada.
- **Pasarelas reales:** no se probó contra sandbox ni producción; las pruebas usan SQLite y un doble del orquestador. Faltan pruebas de tiempos de espera y respuestas reales.
- **Auto-routing:** los métodos públicos nuevos validan sesión y estado, pero cualquier método público futuro debe seguir la misma regla.
- **`getBaseDatosBySucursal()`:** devuelve el valor de `bases_datos.base_datos`; si en producción ese valor no coincide con un grupo de conexión válido, la preparación falla con configuración inválida. Es el comportamiento del helper existente y del contexto de nuevo ingreso.
- **Portal regular:** `FormasPagoModel` ahora excluye bancos inactivos y registros con borrado lógico; si el portal mostraba formas de bancos inactivos, dejará de hacerlo (comportamiento deseado por el plan).
- **Siguiente paso sugerido:** validar el flujo en un entorno con pasarelas de prueba, revisar la decisión del descuento de Zelle y planificar el endurecimiento CSRF del módulo.
