# Prototipo de ejecución — FEAT-014 Consulta paginada de postulaciones de nuevo ingreso con filtros y catálogos

- **Rama:** p-feature/consulta-paginada-postulaciones-nuevo-ingreso
- **Rama base:** feature/panel-administrativo-documentos-ni
- **Plan:** docs/features/014-consulta-paginada-postulaciones-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-30
- **Estado:** consolidado
- **Fecha de consolidación:** 2026-10-30
- **Rama destino:** feature/panel-administrativo-documentos-ni

## Resumen
Se implementó el servicio de consulta administrativa `PostulacionesAdminService` en `App\Libraries\Inscripciones\NuevoIngreso\Admin\` para obtener de forma paginada las postulaciones de nuevo ingreso con datos normalizados (identificación completa, carrera, sede, paso actual legible con `PasoActualResolver`, estado de la intención de pago más reciente y conteo de recaudos disponibles en base de datos sin I/O en disco). Incluye filtros de servidor (paso, sede, carrera, estado de pago, búsqueda textual parametrizada) y catálogos para filtros.

## Tareas realizadas
- [x] Crear el servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService` con inyección opcional de `BaseConnection` y `PasoActualResolver`.
- [x] Implementar el método `listar($filtros, $page, $perPage)` con normalización de paginación (mínimo 1, por defecto 15, máximo 100), orden cronológico descendente (`created_at DESC, id DESC`) y retorno de estructura estandarizada (`data`, `total`, `page`, `per_page`, `total_pages`).
- [x] Implementar filtros combinados seguros: paso actual (validado contra valores permitidos '0'-'4'), sede (`sucursal_id`), carrera (`carrera_id`), estado de pago (con resolución de 'pendiente' para postulaciones sin intención o estado pendiente, e IDs específicos de `pg_estados`) y búsqueda textual con bindings (`identificacion_valor`, `nombre`, `apellido`, `correo`).
- [x] Resolver datos derivados por postulación: identificación completa con prefijo V-/E-, nombre completo, sede y carrera desde oferta académica (`es_sucursales_carreras`), etiqueta y descripción legible del paso vía `PasoActualResolver`, estado de pago más reciente (o 'Pendiente' si no tiene intención) y conteo de recaudos activos con `archivo_path` no vacío.
- [x] Implementar el método `obtenerCatalogosFiltros()` retornando sedes activas en oferta, carreras activas en oferta, pasos normalizados del stepper y estados de pago disponibles.
- [x] Diseñar e implementar la suite de pruebas de integración con SQLite en `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` cubriendo 15 escenarios de prueba y 110 aserciones.

## Criterios de aceptación
| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| La clase `PostulacionesAdminService` está creada e implementada | Revisión de código y prueba unitaria/integración | ok |
| El método `listar()` pagina correctamente respetando límites y estructura | `testPaginacionControlaTamanoYOffset` y `testPaginacionLimitesMinimosYMaximos` | ok |
| Se aplican filtros por sede, carrera, paso actual y estado de pago | `testFiltroPorPasoActual`, `testFiltroPorSede`, `testFiltroPorCarrera`, `testFiltroPorEstadoPagoPendienteOConIntencion` | ok |
| Búsqueda textual por cédula, nombre, apellido o correo mediante bindings seguros | `testFiltroBusquedaTextual` y `testBusquedaConIntentosDeInyeccionSqlEsSegura` | ok |
| Intención de pago más reciente resuelta con precisión y 'Pendiente' por defecto | `testFiltroPorEstadoPagoPendienteOConIntencion` y `testListarSinFiltrosRetornaTodosOrdenadosCronologicamente` | ok |
| Conteo de recaudos disponibles refleja archivos activos no vacíos sin I/O en disco | `testListarSinFiltrosRetornaTodosOrdenadosCronologicamente` (verificación de recaudo inactivo/vacío) | ok |
| Enriquecimiento de paso actual con etiqueta y descripción de `PasoActualResolver` | `testListarSinFiltrosRetornaTodosOrdenadosCronologicamente` y `testPostulacionConOfertaNoEncontradaUsaNoDisponible` | ok |
| Método `obtenerCatalogosFiltros()` entrega sedes, carreras, pasos y estados de pago | `testObtenerCatalogosFiltros` | ok |
| Orden de resultados descendente por fecha de registro e ID | `testListarSinFiltrosRetornaTodosOrdenadosCronologicamente` | ok |
| Suite de pruebas de integración ejecutada con éxito | `php vendor/phpunit/phpunit/phpunit tests/.../PostulacionesAdminServiceTest.php` (15 tests, 110 assertions) | ok |
| No se realizan escrituras ni modificaciones de datos en ninguna tabla | `testSoloLecturaNoModificaLaBaseDeDatos` | ok |

## Flujos cubiertos
- **Flujo normal:** Consulta paginada predeterminada de postulaciones con orden cronológico inverso, datos personales formateados, resolución de carrera/sede, paso actual y estado de pago.
- **Flujos alternativos:**
  - Paginación personalizada con tamaño y offset variables.
  - Filtros individuales y combinados por paso, sede, carrera y estado de pago.
  - Búsqueda textual parcial insensible a mayúsculas/minúsculas.
  - Consulta de páginas más allá del total existente (retorna data vacía sin excepción).
  - Consulta de catálogos para inicializar filtros en la interfaz.
- **Control de errores:**
  - Límites de paginación inválidos (normalización a mínimos y máximos seguros).
  - Pasos inválidos o fuera de rango (retorno vacío sin romper la consulta).
  - Postulaciones sin oferta académica vinculada (valores de respaldo 'No disponible').
  - Caracteres especiales y payloads de inyección SQL (parametrización estricta).
  - Captura y logging de `DatabaseException`.

## Archivos creados
| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php` | Servicio principal de consulta y catálogos administrativos de nuevo ingreso |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | Suite de pruebas de integración con base de datos SQLite aislada |
| `docs/features/014-consulta-paginada-postulaciones-nuevo-ingreso/prototipo.md` | Documento de prototipo y constancia de ejecución de la feature |

## Archivos modificados
| Archivo | Cambio realizado |
| --- | --- |
| `docs/features/014-consulta-paginada-postulaciones-nuevo-ingreso/plan.md` | Actualización de estado a `completado`, checklist de criterios verificados y registro en bitácora |

## Rutas, permisos y datos
- **Rutas/endpoints nuevos o modificados:** No aplica (la exposición HTTP administrativa corresponde a Slice 5 / FEAT-015).
- **Permisos y validaciones:** No aplica a nivel de servicio (se consumirá bajo el filtro `adminPanel:module=inscripciones_ni` en Slice 5).
- **Migraciones/seeds:** No aplica (opera sobre tablas y esquemas preexistentes).
- **Compatibilidad:** Totalmente compatible. No altera modelos existentes ni modifica registros en base de datos.

## Comandos ejecutados
| Comando | Resultado |
| --- | --- |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | 15 tests, 110 assertions, OK (1.97s) |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/PasoActualResolverTest.php` | 21 tests, 54 assertions, OK (631ms) |
| `php -l app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php` | Sin errores de sintaxis detectados |
| `php -l tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | Sin errores de sintaxis detectados |

## Verificación
- **Línea base (antes):** Ejecución de `PasoActualResolverTest.php`: 21 tests, 54 assertions OK.
- **Prueba manual (flujo normal):** Verificado mediante prueba automatizada `testListarSinFiltrosRetornaTodosOrdenadosCronologicamente`.
- **Flujos alternativos y errores:** Verificados mediante 14 pruebas específicas que cubren combinaciones de filtros, ordenamiento, inyecciones, límites de paginación y catálogos.
- **Pruebas automatizadas:** 15 pruebas en `PostulacionesAdminServiceTest.php`, 100% aprobadas.
- **Criterios del plan:** Todos los 11 criterios de finalización cumplidos y marcados.

## Desviaciones del plan
- Ninguna. Se respetaron todas las especificaciones y contratos definidos en `plan.md`.

## Riesgos y pendientes
- **Riesgos:** Ninguno en esta capa de solo lectura.
- **Siguiente paso sugerido:** Proceder con la implementación de **Slice 5** (`exponer el listado administrativo de inscripciones de nuevo ingreso con filtros`) para conectar este servicio con el controlador `InscripcionesNuevoIngreso`, la ruta administrativa protegida y la vista del panel.

## Consolidación

| Fecha | Estado | Rama destino | Estrategia |
| --- | --- | --- | --- |
| 2026-10-30 | consolidado | feature/panel-administrativo-documentos-ni | merge --no-ff |

- La rama prototipo `p-feature/consulta-paginada-postulaciones-nuevo-ingreso` fue eliminada con borrado seguro tras verificar que todos sus commits y archivos quedaron contenidos en la rama destino.
