# Prototipo de ejecución — FEAT-004 Estado, plan e intención del Paso 4 de nuevo ingreso

- **Rama:** p-feature/estado-plan-intencion-paso-4
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/004-estado-plan-intencion-paso-4/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado

## Resumen

Se entregó el primer corte visible del Paso 4 de nuevo ingreso: resumen de carrera, sede, periodo, plan y monto; selector de plan cuando corresponde; creación o reutilización de la intención de pago; y estado con acciones de iniciar, cancelar y consultar intentos. No se integraron pasarelas, métodos de pago, recibos ni cobros. El resultado queda cubierto por pruebas de integración del controlador y pruebas del dominio de lectura del servicio.

## Tareas realizadas

- [x] Extender `NuevoIngresoPagoService` con `contextoPago()` y `estadoDeIntencion()`, reutilizando la resolución existente de sede, periodo, planes, tasa y seguro.
- [x] Declarar `contextoPago`, `estadoDeIntencion`, `obtenerIntencionVigente` y `obtenerUltimaIntencion` en `NuevoIngresoPagoServiceInterface`.
- [x] Reemplazar el placeholder de `Paso3` por `index`, `iniciar`, `cancelar` e `intentos`, con validación defensiva de sesión y paso.
- [x] Agregar las rutas POST de inicio/cancelación y GET de intentos con `nuevoIngresoAuth:4`.
- [x] Crear la vista de resumen, la vista de estado y la pantalla contenedora del Paso 4.
- [x] Crear el JS de confirmación, bloqueo de envío y actualización del total al cambiar de plan.
- [x] Reutilizar `pagos/intenciones_pagos.php` y agregar su estado vacío sin duplicar la tabla.
- [x] Cubrir el controlador con pruebas de integración SQLite y ampliar las pruebas del servicio.
- [x] Ejecutar `php -l`, las pruebas del área, `php spark routes` y `graphify update .`.
- [x] Actualizar el estado del plan a `completado`.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `contextoPago()` devuelve periodo, nombre, planes, plan, tasa, seguro y monto sin escribir | Pruebas `testContextoPagoConUnSoloPlanSeleccionaAutomaticamente`, `testContextoPagoConVariosPlanesSinSeleccionNoEligePlan` y conteo de intenciones | ok |
| `contextoPago()` autoselecciona el único plan; con varios sin `planId` devuelve 0; con plan inválido lanza excepción | Pruebas del servicio y `testContextoPagoRechazaPlanFueraDelPeriodo` | ok |
| `estadoDeIntencion()` aplica el mapeo 1/2/3/8/4/5/7 y desconocido | `testEstadoDeIntencionAplicaElMapeo` | ok |
| La interfaz declara los cuatro métodos nuevos/existentes | Revisión de `NuevoIngresoPagoServiceInterface` y `php -l` | ok |
| `GET /paso-4` exige filtro y renderiza resumen sin crear intención | `testIndexSinIntencionConVariosPlanesMuestraSelectorYNoCreaIntencion` y verificación de rutas | ok |
| Selector solo en `sin_intencion`, `reintento` y `cancelado` con más de un plan | Pruebas de index para estados 1, 2, 3, 8, 7, 4 y 5 | ok |
| Varios planes sin intención: opción vacía, total sin monto e `iniciar` sin plan informa | `testIndexSinIntencion...`, `testIniciarConVariosPlanesSinPlanRedirigeConErrorYNoCrea` | ok |
| Un solo plan: sin selector y autoseleccionado | `testIndexConUnSoloPlanLoSeleccionaSinSelector`, `testIniciarConUnSoloPlanCreaIntencionPagando` | ok |
| `POST /paso-4/iniciar` rechaza no-POST, exige plan, crea/reutiliza y termina en `pagando` | Pruebas de `iniciar` (405, un plan, varios con/sin plan) | ok |
| Estado 1 muestra plan de solo lectura y "Comenzar pago"; no cambia el plan | `testIndexEstadoCreado...`, `testIniciarConIntencionCreadaIgnoraPlanDelFormulario` | ok |
| Intención aprobada o pendiente no se modifica al reenviar `iniciar` | `testIniciarConIntencionAprobadaNoModificaNada`, `testIniciarConIntencionPendienteNoModificaNada` | ok |
| `POST /paso-4/cancelar/{id}` rechaza no-POST, solo cancela 1/2, usa servicio y redirige con flash | Pruebas de cancelación (éxito, estado no cancelable, GET 405) | ok |
| El JS confirma con Swal, usa `window.confirm` y bloquea el envío | Revisión de `public/js/inscripciones/nuevo-ingreso-paso4.js` | ok |
| `GET /paso-4/intentos/{id}` valida propiedad; 422 si ajena o inexistente; lista pagos | Pruebas de intentos (vacío, con datos, ajena, inexistente) | ok |
| El estado vacío de intentos aparece y conserva el retorno a `/paso-4` | `testIntentosMuestraEstadoVacioYRetorno` y breadcrumbs | ok |
| Códigos HTTP consistentes (200/302/405/422/500) | Pruebas del controlador y revisión de `respuestaMensaje` | ok |
| Todas las salidas de vistas se escapan con `esc()` | Revisión de las vistas modificadas y creadas | ok |
| No se agregaron CSRF, migraciones, seeds, dependencias, pasarelas ni cambios de esquema | Revisión de `git status` y diff | ok |
| Pruebas del controlador cubren los escenarios del plan | `Paso4NuevoIngresoTest` (27 pruebas) | ok |
| Pruebas nuevas del servicio y existentes del área siguen pasando | `NuevoIngresoPagoServiceTest` (22) y `Paso3NuevoIngresoTest` (37) | ok |
| `php -l` sin errores en PHP nuevo/modificado | Ejecución sobre los archivos tocados | ok |
| `graphify update .` ejecutado | Ejecución completada; grafo actualizado | ok |

## Flujos cubiertos

- **Flujo normal:** sesión válida de nuevo ingreso, resumen de carrera/sede/periodo/plan/monto, creación o reutilización de intención, estado `pagando` y bloqueo de pasarela hasta una etapa posterior.
- **Flujos alternativos:** un solo plan autoseleccionado; varios planes con selector y opción vacía; intención en estado 1 con plan persistido; aprobada/verificada; pendiente de verificación; cancelada y reintento; historial vacío.
- **Control de errores:** sesión o paso inválido con redirección; contexto de pago fallido con degradación a datos persistidos y acciones seguras; sin intención previa responde 422; método incorrecto responde 405 HTML; intención ajena/inexistente responde 422; errores inesperados responden 500 con log técnico.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| app/Views/inscripciones/nuevo_ingreso/paso3/_resumen.php | Resumen de carrera, sede, periodo, selector/plan, monto, tasa, seguro y referencia |
| app/Views/inscripciones/nuevo_ingreso/paso3/estado.php | Mensajes y acciones por estado de la intención |
| public/js/inscripciones/nuevo-ingreso-paso4.js | Confirmación con Swal/`window.confirm`, bloqueo de envío y total dinámico |
| tests/app/Integration/Paso4NuevoIngresoTest.php | Cobertura de index, iniciar, cancelar e intentos con SQLite |
| docs/features/004-estado-plan-intencion-paso-4/prototipo.md | Registro de ejecución de la feature |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php | Nuevos métodos de lectura `contextoPago()` y `estadoDeIntencion()`; nombre del periodo |
| app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php | Contrato de los métodos de lectura y de obtención de intenciones |
| app/Controllers/Inscripciones/NuevoIngreso/Paso3.php | Reemplazo del placeholder por `index`, `iniciar`, `cancelar`, `intentos` y auxiliares privados |
| app/Config/Routes.php | Rutas POST de inicio/cancelación y GET de intentos con `nuevoIngresoAuth:4` |
| app/Views/inscripciones/nuevo_ingreso/paso3/index.php | Pantalla del Paso 4 con resumen, estado, acciones y botón de salida |
| app/Views/pagos/intenciones_pagos.php | Estado vacío y escape de las filas del historial |
| tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php | Pruebas de `contextoPago()`, `estadoDeIntencion()` y soporte de `ceperiolect` |
| docs/features/004-estado-plan-intencion-paso-4/plan.md | Estado a `completado`, criterios marcados y bitácora de ejecución |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:**
  - `GET /inscripciones/nuevo-ingreso/paso-4` — `Paso3::index`, filtro `nuevoIngresoAuth:4`.
  - `POST /inscripciones/nuevo-ingreso/paso-4/iniciar` — `Paso3::iniciar`, filtro `nuevoIngresoAuth:4`.
  - `POST /inscripciones/nuevo-ingreso/paso-4/cancelar/(:num)` — `Paso3::cancelar/$1`, filtro `nuevoIngresoAuth:4`.
  - `GET /inscripciones/nuevo-ingreso/paso-4/intentos/(:num)` — `Paso3::intentos/$1`, filtro `nuevoIngresoAuth:4`.
- **Permisos y validaciones:** sesión `nuevo_ingreso` con `paso_actual >= 4`; identidad y sede desde `NuevoIngresoContextService`; propiedad de la intención validada con `ni_inscripcion_id`; solo POST para iniciar/cancelar; plan entero positivo validado por el servicio contra sede y periodo.
- **Migraciones/seeds:** no aplica. No se modificó esquema, `gb_config`, `ni_inscripciones` ni catálogos.
- **Compatibilidad:** la interfaz del servicio solo tiene una implementación; se conservaron los métodos existentes. La vista compartida `pagos/intenciones_pagos.php` mantiene su contrato y solo agrega estado vacío y escape. No se modificaron clientes externos, SPA ni pasarelas.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php vendor\phpunit\phpunit\phpunit tests/app/Integration/Paso4NuevoIngresoTest.php --no-coverage --testdox` | Éxito: 27 pruebas, 123 aserciones |
| `php vendor\phpunit\phpunit\phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php --no-coverage` | Éxito: 22 pruebas, 86 aserciones |
| `php vendor\phpunit\phpunit\phpunit tests/app/Integration/Paso3NuevoIngresoTest.php --no-coverage` | Éxito: 37 pruebas, 96 aserciones |
| `php -l` sobre controlador, servicio, interfaz, rutas, vistas y pruebas | Sin errores de sintaxis |
| `php spark routes` filtrado por `paso-4` | Las cuatro rutas se listan con el método esperado |
| `graphify update .` | Grafo actualizado; advertencias preexistentes de extracción SQL y archivos de error |

## Verificación

- **Línea base (antes):** `NuevoIngresoPagoServiceTest` con 16 pruebas y 57 aserciones; `Paso3NuevoIngresoTest` con 37 pruebas y 96 aserciones. Ambos en verde antes de implementar.
- **Prueba manual (flujo normal):** no se ejecutó contra una base MySQL real por no disponer de datos/sesión locales. Se sustituyó por la prueba de integración `Paso4NuevoIngresoTest` con SQLite en archivo, que recorre el flujo completo del controlador.
- **Flujos alternativos y errores:** cubiertos por `Paso4NuevoIngresoTest` (un plan, varios planes, estados 1/2/3/7/8/4/5, fallo de contexto con y sin intención, métodos incorrectos, intención ajena o inexistente).
- **Pruebas automatizadas:** ver tabla de comandos. La suite completa no se ejecutó porque `AGENTS.md` documenta un fallo preexistente en `tests/app/Models/BotChatSystemTest.php`.
- **Criterios del plan:** todos los criterios de finalización quedaron verificados y marcados en `plan.md`.

## Desviaciones del plan

- El usuario decidió que una intención **cancelada (5)** muestre la **opción vacía** en lugar de preseleccionar su plan anterior. El resto de estados mantiene la preselección cuando el plan sigue vigente.
- Cuando el contexto de pago falla y solo existen datos persistidos, el nombre del plan se muestra como `Plan #<id>` porque el detalle `_ni` guarda el identificador, no el nombre. Es un fallback de presentación, no una regla nueva de negocio.
- `respuestaMensaje()` escapa el mensaje antes de pasarlo a `templates/mensaje.php`, que imprime HTML sin escape. No cambia el contrato, solo refuerza la salida segura.

## Riesgos y pendientes

- **CSRF:** el grupo de nuevo ingreso sigue sin CSRF, tal como establece el plan. Los POST quedan protegidos por sesión y filtro, pero el endurecimiento general sigue pendiente.
- **Auto-routing:** los métodos públicos de `Paso3` validan sesión y paso de forma defensiva, pero el proyecto mantiene `setAutoRoute(true)`; conviene revisar el endurecimiento global de rutas en otra tarea.
- **Prueba en entorno real:** falta un smoke test contra una base de sede real con planes, tasa y periodo configurados.
- **Suite completa:** no se ejecutó por el fallo preexistente documentado en `BotChatSystemTest`.
- **Fuera de alcance por diseño:** pasarelas, métodos de pago, recibos, Zelle, GHL, Orbis y sincronización académica permanecen pendientes para etapas posteriores.

## Consolidación

- **Estado:** consolidado
- **Fecha:** 2026-10-28
- **Rama destino:** feature/desacoplar-contructor-pagos
- **Estrategia:** merge --no-ff
- **Commit de integración:** 24f78d8
- **Rama prototipo eliminada:** p-feature/estado-plan-intencion-paso-4
