﻿# Estado, plan e intención del Paso 4 de nuevo ingreso

- **Código:** FEAT-004
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-28
- **Autor:** opencode (agente)

## Objetivo

Entregar el primer corte visible del Paso 4 de nuevo ingreso: mostrar el resumen de carrera, sede, periodo, plan y monto; permitir elegir plan cuando corresponda; crear o reutilizar la intención de pago; y presentar el estado con sus acciones de iniciar, cancelar y consultar intentos. No se integran pasarelas ni se cobra todavía. El resultado es plan seleccionado, intención creada o reutilizada y estado visible.

## Alcance

- Incluye:
  - Reemplazo del placeholder de `Paso3` por los métodos `index()`, `iniciar()`, `cancelar($id)` e `intentos($id)`.
  - Rutas GET/POST con el filtro `nuevoIngresoAuth:4`.
  - Lectura del contexto de pago en el dominio: periodo de nuevo ingreso, nombre del periodo, planes configurados, plan seleccionado, tasa, seguro y monto.
  - Estado de presentación derivado de `estados_id`.
  - Vista de resumen con carrera, sede, periodo, plan y monto; tasa, seguro y referencia como datos secundarios.
  - Selector de plan con las reglas de esta especificación.
  - Vistas de estado y acciones, con mensajes para todos los estados del dominio.
  - Confirmación de cancelación en JavaScript con respaldo a `window.confirm`.
  - Actualización del total mostrado al cambiar de plan.
  - Reutilización de la vista existente `pagos/intenciones_pagos.php` para el historial de intentos, con estado vacío.
  - Pruebas automatizadas del controlador y del nuevo contrato de lectura del servicio.
- No incluye:
  - Pasarelas, métodos de pago, `metodos`, `reportar`, `enLinea`, `prePago`, `postPago`, Zelle, recibos PDF, GHL, Orbis ni sincronización académica.
  - Endpoint de recibo o botón de impresión.
  - Cambios en la máquina de estados del servicio (`iniciarPago`, `cancelar`, transiciones).
  - Cambio de plan sobre una intención creada, vigente o aprobada.
  - Pagos parciales, abonos, cuotas o aplicación de `PoDetPlan`.
  - CSRF, migraciones, seeds, esquema, `gb_config`, `ni_inscripciones`, `PaymentService` o `PaymentOrchestrator`.
  - Cambios en la SPA administrativa.
  - Autenticación nueva: se reutiliza la sesión `nuevo_ingreso` y el filtro existente.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`; el repositorio ya contiene `NuevoIngresoContextService`, `NuevoIngresoPagoService`, su interfaz, la migración `ni_inscripcion_id` y las pruebas del dominio de pago.
- `Paso3` es hoy un placeholder que solo redirige según sesión y `paso_actual`; la vista `paso3/index.php` muestra "Por definir". Este plan sustituye ese contenido por el primer corte funcional.
- El respaldo `PORTAL-ESTUDIANTIL-V2 - copia` contiene una implementación de referencia del Paso 4 con pasarelas. Se reutilizan contratos y estructura de pantalla, pero no se copia código de pasarelas, recibos ni métodos de pago.
- `NuevoIngresoPagoService` ya expone `listarPlanes()`, `crearIntencion()`, `iniciarPago()`, `cancelar()`, `obtenerIntencion()`, `obtenerIntencionVigente()` y `obtenerUltimaIntencion()`. No expone el nombre del periodo ni un estado de presentación; este plan agrega ambos como lectura sin efectos secundarios.
- `contextoPago()` reutiliza el resolvedor interno del servicio y, por tanto, hereda la exigencia de `identificacion_valor` de la postulación. Si esa identificación faltara, la lectura del contexto falla y `index` se degrada a los datos persistidos de la intención, según el flujo de error acordado. No se agrega una validación nueva ni se modifica `crearIntencion()`.
- `NuevoIngresoContextService::resolver()` devuelve `inscripcion`, `sucursal_id`, `sucursal_nombre`, `carrera_id`, `carrera_nombre`, `sucursal_carrera_id`, `orbis_codigo` y `db`. La identidad y la sede salen de ahí, nunca de un parámetro del cliente.
- El periodo se lee de `gb_config.periodo_ni` en la sede y su nombre de `ceperiolect.DePerLec`, con `CoPerLec` como respaldo y cadena vacía si no existe la fila.
- `pg_tasa_dia` y `ceplanpagoperio` viven en la sede; `costo_seguro` y el catálogo de estados viven en la base principal. El servicio ya resuelve esas conexiones.
- La vista `pagos/intenciones_pagos.php` y `IntencionesPagoModel::getIntencionesPagos($id)` existen y muestran `pg_pagos_realizados` de una intención, con el nombre de la forma de pago. Se reutilizan.
- No se aplica CSRF en el grupo de nuevo ingreso actualmente. Este cambio no lo agrega; se registra como riesgo y deuda técnica.
- `MEMORY.md` no existe en este checkout. No se crea en esta feature.
- El nuevo JS se llama `nuevo-ingreso-paso4.js` para no confundirlo con `nuevo-ingreso-paso3.js`, que pertenece al Paso 2 (turno/modalidad).
- Las pruebas de integración usan SQLite en archivo, como `Paso3NuevoIngresoTest`, porque el controlador abre la conexión de la sede con una segunda conexión.
- El código `FEAT-004` no colisiona: `docs/features` contiene `001`, `002` y `003`.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso` y `paso_actual >= 4` abre `GET /inscripciones/nuevo-ingreso/paso-4`. El filtro `nuevoIngresoAuth:4` valida la sesión y el paso antes de llegar al controlador.
2. Paso 2: `Paso3::index()` obtiene el contexto con `Services::nuevoIngresoContext()->resolver()` y extrae `ni_inscripcion_id`, carrera, sede y conexión de la sede.
3. Paso 3: Consulta la intención vigente (`estados_id` 1, 2 o 7) con `obtenerIntencionVigente()`. Si no existe, obtiene la última intención con `obtenerUltimaIntencion()`.
4. Paso 4: Deriva el estado de presentación con `estadoDeIntencion($intencion)` o `sin_intencion` si no hay ninguna.
5. Paso 5: Si la intención tiene un detalle `_ni`, extrae `PlanPagoPerioID` del JSON para conocer el plan persistido.
6. Paso 6: Resuelve el contexto de pago con `contextoPago($niInscripcionId, $planIdPersistido)`: periodo, nombre del periodo, planes válidos con su monto, tasa, seguro y monto del plan seleccionado.
7. Paso 7: Si hay un solo plan válido, el servicio lo selecciona automáticamente. Si hay varios y no existe intención previa, el plan queda sin seleccionar y la vista muestra la opción vacía "Selecciona un plan".
8. Paso 8: El controlador determina si el selector es visible: solo para `sin_intencion`, `reintento` o `cancelado`, y solo si hay más de un plan válido.
9. Paso 9: El controlador calcula el monto a mostrar: el persistido en la intención para estados `creado`, `pagando`, `pendiente` y `aprobado`; el recalculado por el contexto para `sin_intencion`, `reintento` y `cancelado`.
10. Paso 10: Renderiza el layout de nuevo ingreso, el resumen, el selector si aplica y el bloque de estado/acciones. La pantalla no escribe en base de datos.
11. Paso 11: Si el estado permite iniciar, el aspirante elige un plan cuando hay varios y envía `POST /inscripciones/nuevo-ingreso/paso-4/iniciar` con el campo `plan_id`.
12. Paso 12: `Paso3::iniciar()` exige método POST, valida sesión y paso, resuelve el contexto y lee `plan_id` con `$this->request->getPost('plan_id')`. Solo acepta un entero positivo; cualquier otro valor se trata como ausente.
13. Paso 13: Si la última intención está aprobada (3 u 8), redirige a `/paso-4` sin crear ni modificar nada.
14. Paso 14: Si la última intención está en estado `creado` (1), usa el plan persistido del detalle e ignora el `plan_id` del formulario. En cualquier otro caso, si hay más de un plan válido y no llegó `plan_id`, redirige a `/paso-4` con `error_pago = 'Selecciona un plan de pago para continuar.'`. Si hay un solo plan, continúa sin selección explícita.
15. Paso 15: Llama a `crearIntencion($niInscripcionId, $planId)`. El servicio devuelve la intención aprobada si existe; reutiliza la vigente; pasa de `creado` a `pagando`; o crea una nueva en estado `pagando` con su detalle `_ni`.
16. Paso 16: Si la intención quedó aprobada o pendiente de verificación, redirige a `/paso-4`. En caso contrario llama a `iniciarPago($intencionId, $niInscripcionId)` para asegurar el estado `pagando` (operación idempotente) y redirige a `/paso-4`.
17. Paso 17: La pantalla muestra el estado `pagando`, el plan y monto persistidos, un aviso de que la selección de método de pago estará disponible en una etapa posterior y la acción de cancelar. No hay botón de pasarela.
18. Paso 18: Si el aspirante cancela, el JS pide confirmación y envía `POST /inscripciones/nuevo-ingreso/paso-4/cancelar/{id}`.
19. Paso 19: `Paso3::cancelar()` exige POST, valida sesión y paso, y llama a `cancelar($intencionId, $niInscripcionId)`. El servicio solo acepta estados 1 o 2, pasa la cabecera a `5 Cancelado` y hace borrado lógico de los detalles.
20. Paso 20: El controlador redirige a `/paso-4` con un flash de éxito o de error. La pantalla muestra el estado `cancelado` o `reintento` y permite iniciar un nuevo intento.
21. Paso 21: Desde cualquier estado con intención, el aspirante puede abrir `GET /inscripciones/nuevo-ingreso/paso-4/intentos/{id}`.
22. Paso 22: `Paso3::intentos()` valida sesión y paso, verifica con `obtenerIntencion($id, $niInscripcionId)` que la intención existe y pertenece a la postulación, y consulta `getIntencionesPagos($id)`.
23. Paso 23: Renderiza el layout de nuevo ingreso con la vista `pagos/intenciones_pagos` y breadcrumbs de nuevo ingreso. Si no hay pagos intentados, muestra el estado vacío.

## Flujos alternativos / variantes

### Un solo plan configurado

1. Paso 1: `contextoPago()` encuentra exactamente un plan válido para `periodo_ni`.
2. Paso 2: Lo selecciona automáticamente y devuelve su `plan_id` y `monto_total`.
3. Paso 3: La vista no muestra selector; muestra el nombre y el monto del plan.
4. Paso 4: `iniciar()` puede enviar `plan_id` o no; el servicio usa el único plan válido.

### Varios planes sin intención previa

1. Paso 1: `contextoPago()` recibe `planId = null` y encuentra más de un plan válido.
2. Paso 2: Devuelve `plan_id = 0`, `plan = []` y `monto_total = 0.0`, pero incluye la lista completa de planes con sus montos.
3. Paso 3: La vista muestra una opción vacía "Selecciona un plan" y el total como "Selecciona un plan".
4. Paso 4: Al cambiar de plan, el JS actualiza el total con `data-monto` de la opción elegida.
5. Paso 5: Si se envía `iniciar` sin `plan_id`, el controlador redirige con el flash de selección obligatoria y no crea intención.

### Intención en estado creado (1)

1. Paso 1: `obtenerIntencionVigente()` devuelve la intención en estado `1`.
2. Paso 2: `estadoDeIntencion()` devuelve `creado`.
3. Paso 3: La vista muestra "Pago creado, pendiente de iniciar", el plan persistido en solo lectura y el botón "Comenzar pago".
4. Paso 4: El formulario envía el `plan_id` persistido en un campo oculto; el controlador lo ignora y usa el plan del detalle para no cambiar el plan de una intención vigente.
5. Paso 5: `crearIntencion()` reutiliza la intención, la pasa a `pagando` y `iniciarPago()` confirma el estado.

### Intención aprobada o verificada (3 u 8)

1. Paso 1: `estadoDeIntencion()` devuelve `aprobado`.
2. Paso 2: La vista muestra monto, referencia y mensaje de pago aprobado.
3. Paso 3: Solo se ofrece "Ver intentos". No se muestra iniciar, cancelar ni recibo.
4. Paso 4: Si se intenta `iniciar` desde un formulario viejo, el controlador detecta la intención aprobada y redirige sin escribir.

### Intención pendiente de verificación (7)

1. Paso 1: `estadoDeIntencion()` devuelve `pendiente`.
2. Paso 2: La vista muestra "Pago en verificación" y el enlace a intentos.
3. Paso 3: No se muestra cancelar porque el servicio solo cancela estados 1 y 2.
4. Paso 4: Un `POST /iniciar` reutiliza la intención pendiente y redirige sin cambiar el estado.

### Intención cancelada (5) o rechazada (4)

1. Paso 1: No hay intención vigente; `obtenerUltimaIntencion()` devuelve la última.
2. Paso 2: `estadoDeIntencion()` devuelve `cancelado` para 5 y `reintento` para 4.
3. Paso 3: La vista muestra el mensaje correspondiente y permite iniciar un nuevo intento.
4. Paso 4: Si hay varios planes, se muestra el selector con el plan anterior preseleccionado si sigue siendo válido; si no, con la opción vacía.
5. Paso 5: `crearIntencion()` no reutiliza la cancelada ni la rechazada; crea una nueva intención.

### Fallo de contexto con intención previa

1. Paso 1: `contextoPago()` lanza una excepción de dominio porque faltan planes, periodo o tasa.
2. Paso 2: El controlador registra un warning sin datos personales.
3. Paso 3: Si hay intención guardada, muestra el plan y monto persistidos, una advertencia visible y solo las acciones seguras: cancelar si el estado es 1 o 2, y ver intentos.
4. Paso 4: No muestra el botón de iniciar porque no se puede recalcular ni validar un plan.
5. Paso 5: Si no hay intención, o el estado es `reintento`, muestra el error bloqueante y no ofrece acciones de pago.

### Historial de intentos vacío

1. Paso 1: La intención existe y pertenece a la postulación.
2. Paso 2: `getIntencionesPagos()` devuelve una lista vacía.
3. Paso 3: La vista compartida muestra una fila de estado vacío con el texto "No hay intentos de pago registrados para esta intención.".
4. Paso 4: El enlace de retorno a `/paso-4` sigue disponible.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Sesión de nuevo ingreso ausente o inválida | Filtro `nuevoIngresoAuth:4`; comprobación defensiva en el controlador | Redirección a `/inscripciones/nuevo-ingreso`; en AJAX/JSON el filtro responde 401 | Sin pantalla de pago; no se escribe |
| `paso_actual` menor a 4 | Filtro; comprobación defensiva | Redirección a `/inscripciones/nuevo-ingreso/materias`; en AJAX 403 | Sin pantalla de pago |
| Postulación, relación carrera/sede o carrera no disponible | `NuevoIngresoContextException` | `index`: mensaje HTML con 422; `iniciar`/`cancelar`: redirect + `error_pago` | Sin escritura |
| `ni_plan_pago_id` vacío o inválido | `porPlanNoConfigurado()` | `index`: 422 con mensaje; acciones: redirect + flash | Sin intención nueva |
| `periodo_ni` ausente o inválido | `porConfiguracionInvalida()` | `index`: 422; acciones: redirect + flash | Sin intención nueva |
| Ningún plan válido para el periodo | `porPlanNoEncontrado()` | `index`: 422; acciones: redirect + flash | Sin intención nueva |
| Plan enviado que no pertenece a la sede o al periodo | `seleccionarPlan()` lanza `porPlanNoEncontrado()` | `iniciar`: redirect + flash; `index` no recibe plan del cliente | Sin intención nueva |
| Última tasa ausente o menor o igual a 0 | `porTasaNoDisponible()` | `index`: 422; acciones: redirect + flash; con intención previa se degrada a datos persistidos | Sin intención nueva |
| Varios planes y `iniciar` sin `plan_id` | Conteo de planes en el controlador | Redirect a `/paso-4` con "Selecciona un plan de pago para continuar." | Sin intención nueva |
| Intención aprobada al intentar iniciar | `estadoDeIntencion()` = `aprobado` | Redirect a `/paso-4` sin escribir | Intención aprobada intacta |
| Intención pendiente de verificación al iniciar | `estadoDeIntencion()` = `pendiente` | Redirect a `/paso-4` sin escribir | Estado 7 intacto |
| Cancelación de una intención en estado distinto de 1 o 2 | `cancelar()` lanza `porTransicionInvalida()` | Redirect + `error_pago` | Estado anterior intacto |
| Intención inexistente o de otra postulación en `cancelar` o `intentos` | `obtenerIntencion()` devuelve `null` | `cancelar`: redirect + flash; `intentos`: mensaje HTML 422 | Sin datos de la intención ajena |
| Método distinto de POST en `iniciar` o `cancelar` | `$this->request->getMethod()` | Mensaje HTML 405 con enlace de retorno | Sin escritura |
| Fallo de base de datos al crear cabecera o detalle | Excepción del servicio o `porErrorPersistencia()` | `iniciar`: redirect + flash genérico | Sin intención parcial por transacción |
| Fallo al consultar `pg_pagos_realizados` | Excepción del modelo | `intentos`: mensaje HTML 500; log técnico | Sin datos mostrados |
| Error inesperado en `index` | `catch (\Throwable)` | Mensaje HTML 500 con enlace a materias; log técnico | Sin escritura |
| Error inesperado en `iniciar` o `cancelar` | `catch (\Throwable)` | Redirect a `/paso-4` con mensaje genérico; log técnico | Sin escritura parcial |

## Reglas de negocio y validaciones

- La identidad de la postulación es `ni_inscripcion_id` de la sesión/contexto, nunca un `AASUCURSID` ni un id enviado libremente por el cliente.
- La sede y la conexión se resuelven con `NuevoIngresoContextService`; no se consultan datos académicos en la base principal.
- `index()` es de solo lectura: no crea ni modifica intenciones, no cambia `paso_actual` y no escribe en `gb_config`.
- La intención visible es la vigente (`1`, `2`, `7`); si no existe, la última no borrada. Una intención cancelada o rechazada no se considera vigente.
- `estadoDeIntencion()` se define así:
  - `1` → `creado`.
  - `2` → `pagando`.
  - `3` y `8` → `aprobado`.
  - `4` → `reintento`.
  - `5` → `cancelado`.
  - `7` → `pendiente`.
  - Sin intención → `sin_intencion`.
  - Cualquier otro valor → `reintento`.
- El selector de plan se muestra solo si el estado es `sin_intencion`, `reintento` o `cancelado`, y existen más de un plan válido. En `creado`, `pagando`, `pendiente` y `aprobado` el plan es de solo lectura.
- Con un solo plan válido se selecciona automáticamente. Con varios y sin intención previa, el plan queda en `0`, el monto en `0.0` y la vista exige una elección explícita.
- En `iniciar`, el `plan_id` se lee con `$this->request->getPost('plan_id')`; solo se acepta un entero positivo. Un valor no numérico, cero o negativo se trata como ausente. El servicio valida que el plan pertenezca a `ni_plan_pago_id` y al `periodo_ni`.
- Si la última intención está en estado `creado` (1), el plan persistido manda y se ignora cualquier `plan_id` del formulario. No se permite cambiar el plan de una intención vigente.
- Si hay más de un plan y no se envió `plan_id`, no se crea intención; se informa al usuario.
- Si hay un solo plan, `crearIntencion()` puede invocarse con `planId = null` y el servicio usa el único plan válido.
- El monto de la intención se calcula y persiste en el servidor. La pantalla no acepta montos del cliente.
- Para `creado`, `pagando`, `pendiente` y `aprobado` se muestra el `monto_total` persistido. Para `sin_intencion`, `reintento` y `cancelado` se muestra el monto recalculado por `contextoPago()` para el plan seleccionado.
- La tasa, el seguro y la referencia se muestran como datos secundarios cuando existen o son mayores que cero; no se usan para recalcular en el navegador.
- `cancelar()` solo procede para estados 1 y 2. La cancelación es lógica: cabecera a estado 5 y `borrado_dt` en los detalles; no se elimina físicamente.
- `intentos()` solo muestra datos de una intención que pertenece a la postulación. Si no existe o es ajena, devuelve 422 sin revelar si el identificador existe.
- `intentos()` es de solo lectura y reutiliza `IntencionesPagoModel::getIntencionesPagos($id)`.
- Todas las salidas de las vistas se escapan con `esc()`; los atributos usan `esc(..., 'attr')`. No se insertan datos de usuario directamente en JavaScript.
- El JS de cancelación usa `Swal.fire` si está disponible y `window.confirm` como respaldo. Bloquea el botón mientras envía para evitar doble cancelación. El JS del selector actualiza el total con `data-monto` y no confía en montos calculados en el cliente.
- No se agregan dependencias. No se modifica `vendor/`, `system/` ni `public/vendor/`.
- CSRF no se modifica en este cambio. Se registra como riesgo: los POST del Paso 4 quedan protegidos solo por sesión y filtro hasta que se aborde el endurecimiento general del módulo.

## Contratos y diseño propuesto

### `NuevoIngresoPagoService`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `contextoPago(int $niInscripcionId, ?int $planId = null): array` | Resolver periodo, nombre del periodo, planes válidos con monto, plan seleccionado, tasa, seguro y monto total. | Solo lectura. Lanza excepciones de dominio. |
| `estadoDeIntencion(array $intencion): string` | Derivar `creado`, `pagando`, `pendiente`, `aprobado`, `reintento`, `cancelado` desde `estados_id`. | Sin efectos. |
| `obtenerIntencionVigente(int $niInscripcionId): ?array` | Devolver la intención vigente (1, 2 o 7). | Solo lectura. Ya existe; se declara en la interfaz. |
| `obtenerUltimaIntencion(int $niInscripcionId): ?array` | Devolver la última intención no borrada, sin importar estado. | Solo lectura. Ya existe; se declara en la interfaz. |

`contextoPago()` devolverá, como mínimo:

```php
[
    'periodo_id'     => 900001,
    'periodo_nombre' => '2026-2N',
    'plan_id'        => 900002, // 0 si hay varios y no se eligió
    'plan'           => ['id' => 900002, 'nombre' => 'PLAN NI CONTADO', 'codigo' => 'CONTADO', 'ref_dolar' => 50.0, 'monto' => 1234.56],
    'planes'         => [
        ['id' => 900002, 'nombre' => 'PLAN NI CONTADO', 'codigo' => 'CONTADO', 'ref_dolar' => 50.0, 'monto' => 1234.56],
    ],
    'tasa'           => 40.00,
    'seguro'         => 0.00,
    'monto_total'    => 1234.56, // 0.0 si no hay plan seleccionado
    'sucursal_id'    => 1,
]
```

- `contextoPago()` reutiliza los métodos privados existentes (`resolverContexto()`, `idsConfiguracionLocal()`, `periodoNi()`, `resolverPlanesPago()`, `seleccionarPlan()`, `ultimaTasa()`, `seguroGlobal()`, `calcularMonto()`).
- Si `$planId` es `null` y hay un solo plan válido, selecciona ese plan. Si hay varios, no selecciona ninguno.
- Si `$planId` no es `null` y no está entre los planes válidos, lanza `porPlanNoEncontrado()`.
- El nombre del periodo se busca en `ceperiolect` (`DePerLec`, luego `CoPerLec`). Si no existe la fila, devuelve cadena vacía sin lanzar excepción.
- No escribe en base de datos ni modifica la intención.

### `Paso3`

| Método | Responsabilidad |
| --- | --- |
| `index()` | Renderizar resumen, selector y estado/acciones. |
| `iniciar()` | Validar POST, seleccionar plan, crear/reutilizar intención, asegurar estado `pagando` y redirigir. |
| `cancelar($id = 0)` | Validar POST, cancelar la intención propia en estado 1 o 2 y redirigir. |
| `intentos($id = 0)` | Validar propiedad y renderizar el historial de `pg_pagos_realizados`. |
| `sesionValida()` | Privado. Comprobar sesión y `paso_actual >= 4`; redirigir si no. |
| `planIdDeIntencion(array $intencion)` | Privado. Leer `PlanPagoPerioID` del primer detalle `_ni`. |
| `urls()` | Privado. Devolver `paso4`, `iniciar`, `cancelar`, `intentos` y `salir`. |
| `respuestaMensaje()` | Privado. Renderizar layout + mensaje + retorno con el código HTTP indicado. |

- Los métodos auxiliares deben ser `private` para que el auto-routing no los exponga como endpoints.
- Todas las acciones usan `$this->request` de CI4: `getMethod()`, `getPost()` y `getFiles()` no son necesarios en este corte.
- `index`, `intentos` y las respuestas de mensaje usan `view()` con el layout de nuevo ingreso; `iniciar` y `cancelar` devuelven `redirect()`.

### Vistas y JavaScript

| Archivo | Responsabilidad |
| --- | --- |
| `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` | Contenedor, encabezado, steps popover, error flash, inclusión de `_resumen`, `estado` y botón Salir. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/_resumen.php` | Carrera, sede, periodo, selector o plan, total, tasa, seguro y referencia. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Mensaje y acciones por estado. |
| `public/js/inscripciones/nuevo-ingreso-paso4.js` | Confirmación de cancelación, bloqueo de envío y actualización del total al cambiar de plan. |
| `app/Views/pagos/intenciones_pagos.php` | Reutilizada; se agrega una fila de estado vacío sin alterar el comportamiento con datos. |

- El encabezado usa el título "Pago de inscripción" y el componente `steps_popover` con `pasoActual => 4`.
- El resumen formatea montos con `number_format($monto, 2, ',', '.')` y la etiqueta `VES`.
- El selector usa `id="plan-pago"`, `name="plan_id"`, `data-plan-selector` y `form="form-iniciar-pago"`. Cada opción lleva `data-monto`.
- El formulario de inicio usa `id="form-iniciar-pago"`, `method="POST"`, `data-confirm="¿Deseas iniciar el pago de tu inscripción?"`.
- El formulario de cancelación usa `method="POST"`, `data-confirm="¿Seguro que deseas cancelar esta intención de pago?"` y la URL con el id de la intención.
- El JS se carga con cache-busting mediante `filemtime()`.
- No se modifica `public/css/tailwind-v4.css`; se usan clases Tailwind existentes.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Reemplazar el placeholder por `index`, `iniciar`, `cancelar`, `intentos` y auxiliares privados |
| Modificar | `app/Config/Routes.php` | Agregar POST `paso-4/iniciar`, POST `paso-4/cancelar/(:num)` y GET `paso-4/intentos/(:num)` con `nuevoIngresoAuth:4`; conservar GET `paso-4` |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | Agregar `contextoPago()` y `estadoDeIntencion()`; conservar la máquina de estados |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php` | Declarar `contextoPago`, `estadoDeIntencion`, `obtenerIntencionVigente` y `obtenerUltimaIntencion` |
| Reemplazar | `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` | Pantalla del primer corte visible |
| Crear | `app/Views/inscripciones/nuevo_ingreso/paso3/_resumen.php` | Resumen reutilizable de plan, periodo y monto |
| Crear | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Mensajes y acciones por estado |
| Crear | `public/js/inscripciones/nuevo-ingreso-paso4.js` | Confirmación de cancelación y total dinámico |
| Modificar | `app/Views/pagos/intenciones_pagos.php` | Fila de estado vacío para el historial de nuevo ingreso |
| Crear | `tests/app/Integration/Paso4NuevoIngresoTest.php` | Cubrir index, iniciar, cancelar e intentos con SQLite |
| Modificar | `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Cubrir `contextoPago()` y `estadoDeIntencion()` |
| Documentar | `docs/features/004-estado-plan-intencion-paso-4/plan.md` | Este plan |

No se modifican migraciones, seeds, `gb_config`, `ni_inscripciones`, `PaymentService`, `PaymentOrchestrator`, `NuevoIngresoContextService`, `Filters.php`, la SPA ni las pasarelas.

## Criterios de finalización

- [x] `contextoPago()` devuelve periodo, nombre del periodo, planes válidos, plan seleccionado, tasa, seguro y monto total; no escribe en base de datos.
- [x] `contextoPago()` selecciona automáticamente el único plan válido; con varios y sin `planId` devuelve `plan_id = 0` y `monto_total = 0.0`; con un `planId` inválido lanza `porPlanNoEncontrado()`.
- [x] `estadoDeIntencion()` aplica el mapeo `1=creado`, `2=pagando`, `3/8=aprobado`, `4=reintento`, `5=cancelado`, `7=pendiente`, desconocido=`reintento`.
- [x] La interfaz `NuevoIngresoPagoServiceInterface` declara `contextoPago`, `estadoDeIntencion`, `obtenerIntencionVigente` y `obtenerUltimaIntencion`.
- [x] `GET /paso-4` exige `nuevoIngresoAuth:4` y renderiza resumen de carrera, sede, periodo, plan y monto sin crear intención.
- [x] La vista muestra el selector solo en `sin_intencion`, `reintento` o `cancelado` con más de un plan; en `creado`, `pagando`, `pendiente` y `aprobado` el plan es de solo lectura.
- [x] Con varios planes y sin intención previa, el selector tiene una opción vacía, el total no muestra un monto y `iniciar` sin plan redirige con el mensaje de selección.
- [x] Con un solo plan, no hay selector y el plan se selecciona automáticamente.
- [x] `POST /paso-4/iniciar` rechaza métodos distintos de POST con 405, exige plan cuando hay varios, reutiliza o crea la intención y termina en `/paso-4` con estado `pagando`, sin pasarela.
- [x] Una intención en estado 1 muestra "Pago creado" con plan de solo lectura y "Comenzar pago"; el `iniciar` no cambia su plan.
- [x] Una intención aprobada o pendiente no se modifica al reenviar `iniciar`; se redirige a `/paso-4`.
- [x] `POST /paso-4/cancelar/{id}` rechaza métodos distintos de POST con 405, solo cancela estados 1 y 2, usa el servicio y redirige con flash.
- [x] El JS de cancelación confirma con Swal y usa `window.confirm` como respaldo; bloquea el envío mientras se procesa.
- [x] `GET /paso-4/intentos/{id}` valida que la intención pertenezca a la postulación; devuelve 422 si no existe o es ajena; lista `pg_pagos_realizados` con la vista compartida.
- [x] La vista de intentos muestra el estado vacío cuando no hay pagos intentados y conserva el enlace de retorno a `/paso-4`.
- [x] El desglose de errores HTTP es consistente: 200 en pantallas correctas, 302 en acciones exitosas, 405 en método incorrecto, 422 en errores de dominio o intención ajena, 500 en errores inesperados.
- [x] Las vistas escapan toda salida con `esc()` y no insertan datos de usuario sin escapar.
- [x] No se agregaron CSRF, migraciones, seeds, dependencias, pasarelas, recibos ni cambios de esquema.
- [x] `tests/app/Integration/Paso4NuevoIngresoTest.php` cubre index (sin intención, un plan, varios planes, estado 1, 2, 3/8, 7, 4, 5 y fallo de contexto), iniciar (un plan, varios con y sin plan, aprobada, pendiente), cancelar (éxito, estado no cancelable, ajena) e intentos (éxito, vacío, ajena, inexistente).
- [x] Las pruebas nuevas del servicio cubren `contextoPago()` y `estadoDeIntencion()`, y las pruebas existentes del área siguen pasando.
- [x] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [x] `graphify update .` se ejecuta después de los cambios de código.

## Preguntas abiertas

- Se asume que la intención en estado 1 se presenta como `creado` (no como `reintento`) para no ofrecer un cambio de plan que el servicio ignoraría. ¿Se confirma ese estado adicional?
- Se asume que una intención cancelada (5) preselecciona su plan anterior si sigue siendo válido, en lugar de mostrar la opción vacía. ¿Se prefiere la opción vacía también en ese caso?
- Se asume que el estado vacío de intentos se agrega a la vista compartida `pagos/intenciones_pagos.php` en lugar de duplicar la tabla en una vista nueva. ¿Se acepta tocar esa vista compartida?
- Se asume que `ceperiolect.DePerLec` es el nombre visible del periodo y `CoPerLec` solo el respaldo. ¿El negocio usa otro campo?
- Se asume que el fallo de contexto en estado `cancelado` no habilita iniciar (solo aviso, datos persistidos e intentos), porque sin planes o tasa no se puede crear una intención válida. ¿Se confirma?
- Se asume que el 405 se devuelve como página HTML del portal, no como JSON, porque las acciones son formularios server-side. ¿Se confirma?

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-004 tras revisar `Paso3`, `NuevoIngresoPagoService`, `NuevoIngresoContextService`, rutas, vistas y el respaldo del Paso 4. Se acordó un solo cambio, sin pasarelas, con extensión de lectura del servicio y contrato HTTP tipo respaldo. | opencode (agente) |
| 2026-10-28 | Ejecución de FEAT-004 en `p-feature/estado-plan-intencion-paso-4`. Se implementaron servicio, controlador, rutas, vistas, JS y pruebas. El usuario decidió que una intención cancelada no preselecciona su plan anterior. | opencode (agente) |
