# Proyecto: Temporizador de finalización y auditoría de confirmación de pago en Paso 3 de Nuevo Ingreso

## Descripcion:

Optimizar la experiencia del estudiante y la trazabilidad operativa en el Paso 3 (Paso 4 visual: Selección de Plan y Pago) del flujo de inscripciones de nuevo ingreso tras la confirmación exitosa de su pago.

El proyecto aborda dos necesidades fundamentales:
1. **Experiencia y Flujo de Usuario:** Orientar claramente al estudiante para que descargue su recibo de pago, informándole que dispone de 30 segundos antes de ser redirigido automáticamente a la pantalla final para imprimir su planilla de inscripción (pudiendo avanzar inmediatamente con un clic). Al ingresar al Paso 3 con un pago ya aprobado, el temporizador de 30 segundos se activa de inmediato y se otorga foco visual y de interacción al botón de finalizar.
2. **Auditoría y Monitoreo de Datos:** Asegurar la persistencia de la fecha de confirmación de pago en la tabla de postulaciones (`ni_inscripciones.fecha_pago_completado`), permitiendo auditar y filtrar con precisión qué estudiantes completaron su pago satisfactoriamente pero quedaron estancados en el Paso 3 sin avanzar a la vista final.

## Alcance del Proyecto

- **Esquema de Base de Datos y Modelo:**
  - Migración idempotente para incorporar el campo `fecha_pago_completado` (`DATETIME NULL`) en la tabla `ni_inscripciones`.
  - Actualización de `$allowedFields` y métodos de persistencia en `NiInscripcionModel`.
- **Persistencia y Lógica de Aprobación en Backend:**
  - Garantizar que al momento de marcarse o detectarse un pago aprobado (en `Paso3::procesarPago()`, validación síncrona o callbacks), se registre la marca temporal exacta en `fecha_pago_completado` si aún no ha sido fijada.
  - Exponer soporte para auditar estudiantes que pagaron (`fecha_pago_completado IS NOT NULL`) pero cuyo `paso_actual = '3'`.
- **Presentación y Notificaciones en Frontend (Paso 3):**
  - Mostrar bloque informativo prominente indicando al estudiante:
    1. Descarga disponible de su recibo de pago.
    2. Aviso claro de que será redirigido en 30 segundos al paso final para generar e imprimir su planilla oficial.
    3. Opción de avanzar de forma inmediata haciendo clic en el botón "Finalizar".
  - Componente de temporizador regresivo de 30 segundos en la UI con sincronización en tiempo real.
  - Foco programático (scroll suave y realce visual/pulse) dirigido al botón `btnFinalizarPaso` ("Finalizar") al cargar la vista con estado aprobado.
- **Transición Controlada:**
  - Auto-envío seguro del formulario de finalización hacia `paso-4/continuar` al llegar a 0 segundos si el aspirante no hizo clic previamente.

## Reglas de Negocio

- **Persistencia Inmutable de Confirmación:** `fecha_pago_completado` se registra una única vez cuando el pago alcanza el estado de aprobación. Si el estudiante recarga la pantalla o interactúa nuevamente, no se debe sobrescribir la fecha original.
- **Trazabilidad de Estancamiento:** La combinación `fecha_pago_completado IS NOT NULL AND paso_actual = '3'` representa legítimamente a los aspirantes con cobro en firme que no han concluido formalmente la visualización de la planilla; esta métrica debe ser auditable por los coordinadores y administradores.
- **Disponibilidad Inmediata del Recibo:** El botón o enlace de descarga del recibo debe permanecer plenamente accesible durante la vigencia del temporizador, abriéndose en pestaña nueva (`target="_blank"`) para no interrumpir el flujo de redirección.
- **Autonomía del Estudiante vs. Automatización:** El temporizador de 30 segundos es una ayuda guiada, no un bloqueo. El usuario puede hacer clic en "Finalizar" en el segundo 1 o en cualquier momento. Si transcurren los 30 segundos sin acción, el sistema asume la confirmación y avanza automáticamente.
- **Activación al Recargar o Reingresar:** Si el aspirante abandona la pestaña y regresa al Paso 3 con su pago ya aprobado, la vista vuelve a activar el temporizador de 30 segundos con foco en el botón de finalizar para garantizar que culmine el circuito hacia la planilla.
- **Aislamiento Multi-sede y Seguridad:** La verificación del estado de pago y la actualización de `ni_inscripciones` se rigen estrictamente por el contexto resuelto de la sesión (`nuevo_ingreso.id`), respetando las políticas de no confiar en identificadores enviados por el cliente.

## Modelo

Definición conceptual de las entidades y modificaciones al esquema:

### 1. Tabla `ni_inscripciones`
- **Campo nuevo:** `fecha_pago_completado` (`DATETIME NULL`, DEFAULT NULL).
- **Propósito:** Almacena la estampa de tiempo en la cual la postulación tuvo su primer pago efectivamente confirmado/aprobado.
- **Índice sugerido:** `idx_ni_inscripciones_pago_completado` (`fecha_pago_completado`, `paso_actual`) para acelerar reportes de auditoría y detección de casos estancados.

### 2. Modelo `App\Models\Inscripciones\NiInscripcionModel`
- Incorporación de `fecha_pago_completado` a `$allowedFields`.
- Método de apoyo `registrarFechaPagoCompletado(int $inscripcionId, ?string $fecha = null): bool` que garantice idempotencia (`WHERE fecha_pago_completado IS NULL`).
- Método de consulta/auditoría `obtenerEstancadosEnPaso3(): array` o soporte para filtrado en reportes.

## Presentación

### Vista Paso 3 (`app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` e `index.php`):
- **Caja de Notificación de Aprobación y Recibo:**
  - Mensaje principal: *"¡Tu pago ha sido aprobado con éxito!"*
  - Llamado explícito a la acción: *"Te recomendamos descargar tu recibo de pago ahora. En 30 segundos serás redirigido automáticamente al paso final para descargar tu planilla de inscripción."*
  - Botón prominente de color verde: `[ Descargar recibo ]` (con icono de descarga, abriendo en pestaña nueva).
- **Componente de Cuenta Regresiva (Temporizador 30s):**
  - Barra o chip visual animado: *"Redirigiendo automáticamente en: 30s"* (cuenta descendente dinámica 30... 29... 0).
  - Indicador de progreso visual o badge temporal.
- **Botón de Acción Principal (`btnFinalizarPaso`):**
  - Botón con texto *"Finalizar inscripción"* o *"Finalizar"*.
  - Efecto de foco automático (`element.focus()`, `scrollIntoView({ behavior: 'smooth' })`) al renderizar la vista cuando el pago está aprobado.
  - Efecto visual sutil (anillo o pulso) para captar la atención del usuario hacia la acción requerida.
  - Al hacer clic o al agotarse el contador a 0, se realiza el submit del formulario hacia la ruta de avance al paso final.

## Lista de Tareas (Checklist de Implementación)

> Orden de ejecución sugerido. Cada tarea indica el entregable técnico esperado y su identificador unívoco. No marcar como completada sin su respectiva verificación.

### Fase 0 — Base de Datos y Modelo de Inscripción

- [x] **T-01** Crear migración idempotente `AddFechaPagoCompletadoToNiInscripciones` para añadir la columna `fecha_pago_completado` (`DATETIME NULL`) e índice en `ni_inscripciones`.
- [x] **T-02** Actualizar `app/Models/Inscripciones/NiInscripcionModel.php` incorporando `fecha_pago_completado` en `$allowedFields` y agregando el método auxiliar idempotente `registrarFechaPagoCompletado()`.

### Fase 1 — Registro y Persistencia en Backend

- [x] **T-10** Registrar `fecha_pago_completado` en `Paso3::procesarPago()` en el momento en que se confirma la aprobación del pago.
- [x] **T-11** Asegurar en `Paso3::index()` y `Paso3::continuar()` que si el pago está aprobado pero la inscripción no tiene `fecha_pago_completado`, se persista retrospectivamente la fecha actual o la fecha de la intención de pago.
- [x] **T-12** Verificar que la consulta de auditoría para estudiantes con pago aprobado y `paso_actual = '3'` funcione correctamente sobre la base de datos principal.

### Fase 2 — Vistas e Interfaz de Usuario (Descarga de Recibo y Redirección)

- [x] **T-20** Modificar la vista de estado aprobado (`app/Views/inscripciones/nuevo_ingreso/paso3/estado.php`) agregando la instrucción clara de descarga de recibo y la notificación de redirección hacia la planilla.
- [x] **T-21** Implementar en `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` el contenedor visual del temporizador de 30 segundos visible exclusivamente cuando `$estado === 'aprobado'`.

### Fase 3 — Script del Temporizador y Foco en Botón Finalizar

- [x] **T-30** Implementar script en el cliente (`paso3.js` o script inline controlado en la vista) que inicialice la cuenta regresiva de 30 segundos tras cargar el documento con pago aprobado.
- [x] **T-31** Programar el foco visual y de interacción (`focus()` y scroll) hacia el botón `btnFinalizarPaso`.
- [x] **T-32** Vincular el fin del temporizador (0 segundos) al disparo automático del formulario hacia `paso-4/continuar`, permitiendo en paralelo el clic voluntario del usuario sin bloqueos.

### Fase 4 — Verificación y Pruebas

- [x] **T-40** Ejecutar migración idempotente mediante comando spark (`php spark migrate` o `init:principal`) y verificar estructura de tabla.
- [x] **T-41** Probar escenario con pago aprobado: verificar que el temporizador inicia en 30s, da foco a `btnFinalizarPaso`, el recibo se puede descargar en nueva pestaña y al llegar a 0 redirige a la vista final.
- [x] **T-42** Probar clic manual antes de los 30s y validar que redirige inmediatamente a la vista final persistiendo `paso_actual = 4`.
- [x] **T-43** Verificar en base de datos que `fecha_pago_completado` queda almacenada con la fecha correcta y no se altera en reintentos.
