# Consulta paginada de postulaciones de nuevo ingreso con filtros y catálogos

- **Código:** FEAT-014
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-30
- **Autor:** Antigravity (agente)

## Objetivo

Implementar el servicio de consulta administrativa `PostulacionesAdminService` en `App\Libraries\Inscripciones\NuevoIngreso\Admin\` para obtener de forma paginada y optimizada las postulaciones de nuevo ingreso, incluyendo sus datos básicos de identificación, carrera, sede, paso actual legible, estado de la intención de pago más reciente y la cantidad de recaudos digitales consignados, soportando filtros en servidor y proveyendo los catálogos necesarios para alimentar la interfaz administrativa.

## Alcance

- **Incluye:**
  - Crear la clase de servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService`.
  - Implementar el método principal de consulta:
    `listar(array $filtros = [], int $page = 1, int $perPage = 15): array`
  - Soportar paginación segura en servidor:
    - Página por defecto `1`, con coerción a entero positivo si se envían valores menores a `1`.
    - Cantidad de registros por página por defecto `15`, con un límite máximo estricto de `100` registros para evitar saturación de memoria.
    - Estructura de retorno estandarizada:
      ```php
      [
          'data'        => array, // Arreglo asociativo de postulaciones normalizadas
          'total'       => int,   // Total de registros que cumplen los filtros
          'page'        => int,   // Página actual consultada
          'per_page'    => int,   // Registros por página aplicados
          'total_pages' => int,   // Total de páginas calculadas
      ]
      ```
  - Soportar los siguientes filtros en servidor aplicados de forma combinable (AND):
    - `paso`: filtrado por valor de `ni_inscripciones.paso_actual` ('0', '1', '2', '3', '4').
    - `sucursal_id`: filtrado por la sede asignada a través de `es_sucursales_carreras.sucursal_id`.
    - `carrera_id`: filtrado por la carrera asignada a través de `es_sucursales_carreras.carrera_id`.
    - `estado_pago`: filtrado por el identificador de estado de la intención de pago más reciente (`pg_estados.id`), o el valor especial `'pendiente'` / `0` para postulaciones sin intención registrada.
    - `search` / `q`: búsqueda textual con comodines sobre cédula (`ni_inscripciones.identificacion_valor`), nombre (`ni_inscripciones.nombre`), apellido (`ni_inscripciones.apellido`) o correo (`ni_inscripciones.correo`).
  - Resolución de datos asociados por postulación:
    - Información de sede (`aasucurs.NBSUC`) y carrera (`es_carreras.nombre`) vía JOIN con `es_sucursales_carreras`.
    - Traducción del paso actual a etiqueta legible utilizando `App\Libraries\Inscripciones\NuevoIngreso\PasoActualResolver` (FEAT-013).
    - Estado de la intención de pago más reciente asociada a la postulación (`pg_intenciones_pago.ni_inscripcion_id`), extrayendo el nombre del estado (`pg_estados.nombre`); en caso de no poseer ninguna intención de pago registrada, retornar por defecto `estado_pago_nombre = 'Pendiente'`.
    - Conteo en base de datos de recaudos digitales disponibles: total de filas en `ni_inscripciones_recaudos` asociadas a la postulación que cumplan `archivo_path IS NOT NULL`, `archivo_path != ''` y `activo = 1`.
  - Implementar el método de catálogos para filtros:
    `obtenerCatalogosFiltros(): array`
    Retornando un arreglo asociativo con:
    - `sedes`: lista de sucursales activas en oferta (`aasucurs.AASUCURSID`, `aasucurs.NBSUC`).
    - `carreras`: lista de carreras activas (`es_carreras.id`, `es_carreras.nombre`).
    - `pasos`: lista de pasos disponibles con su valor numérico y etiqueta legible obtenida desde `PasoActualResolver`.
    - `estados_pago`: lista de estados de pago activos desde `pg_estados` (`id`, `nombre`), incluyendo la opción representativa para postulaciones pendientes/sin intención.
  - Aplicar ordenamiento descendente por fecha de registro (`ni_inscripciones.created_at DESC, ni_inscripciones.id DESC`).
  - Garantizar uso estricto de Query Builder y parameter bindings para evitar vulnerabilidades de inyección SQL.
  - Crear la suite de pruebas de integración en `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php`.
  - Registrar este plan en `docs/features/014-consulta-paginada-postulaciones-nuevo-ingreso/plan.md`.

- **No incluye:**
  - Crear o modificar rutas web, endpoints API o controladores administrativos (asignado a Slice 5 / FEAT-015).
  - Vistas HTML, componentes Blade/PHP o assets de JavaScript/CSS (Slice 5 / FEAT-015).
  - La consulta detallada de una postulación individual con la lista completa de sus recaudos (Slice 6 / FEAT-016).
  - La descarga, lectura o visualización inline de archivos físicos de recaudos (Slice 8 / FEAT-018).
  - Operaciones de escritura, actualización, aprobación o rechazo de postulaciones (el servicio es estrictamente de solo lectura).
  - Validación I/O de existencia física en el disco de los archivos de recaudos.
  - Modificación del esquema de base de datos o creación de nuevas migraciones.

> **Evaluación de alcance:** Este cambio corresponde estrictamente al **Slice 4** del roadmap definido en `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`. Concentra únicamente la capa de servicio de consulta paginada y catálogos en base de datos. Está perfectamente delimitado, no mezcla presentación visual ni escrituras, por lo que no requiere subdivisión adicional.

## Contexto y supuestos

- Todas las tablas consultadas (`ni_inscripciones`, `es_sucursales_carreras`, `es_carreras`, `aasucurs`, `ni_inscripciones_recaudos`, `pg_intenciones_pago`, `pg_estados`) residen en la base de datos principal (`default`).
- La vinculación entre una postulación y su oferta académica se realiza mediante la llave foránea `ni_inscripciones.sucursal_carrera_id = es_sucursales_carreras.id`. A su vez, `es_sucursales_carreras.sucursal_id` se vincula con `aasucurs.AASUCURSID` y `es_sucursales_carreras.carrera_id` con `es_carreras.id`.
- La relación entre pagos y nuevo ingreso se efectúa mediante la columna `pg_intenciones_pago.ni_inscripcion_id`, agregada en la migración `2026-10-27-000099_AddNiInscripcionIdToPgIntencionesPago`.
- Una postulación puede no tener intenciones de pago asociadas (por ejemplo, si aún se encuentra en los Pasos 0, 1 o 2). En tales casos, el estado de pago devuelto para el listado será `Pendiente`.
- Si existen múltiples intenciones de pago para una misma postulación, se debe considerar únicamente la más reciente (ordenada por `pg_intenciones_pago.created_at DESC, pg_intenciones_pago.id DESC`).
- El cálculo de recaudos disponibles se realiza a nivel de consulta SQL mediante conteo condicional de registros activos con `archivo_path` no vacío, evitando lecturas directas del sistema de archivos durante la paginación.
- Para las etiquetas del paso actual se utiliza `App\Libraries\Inscripciones\NuevoIngreso\PasoActualResolver` (implementado en FEAT-013) asegurando coherencia terminológica con el resto del sistema.
- Las consultas deben operar eficientemente mediante dos pasos o subconsultas indexadas para no producir productos cartesianos al combinar postulaciones, recaudos y pagos.
- La numeración sigue el historial documental de features: el último código fue `FEAT-013` en `docs/features/013-etiquetas-paso-actual-nuevo-ingreso/plan.md`, por lo que este cambio toma el código libre `FEAT-014` y la carpeta `014-consulta-paginada-postulaciones-nuevo-ingreso`.

## Flujo normal

1. Paso 1: Un consumidor administrativo (ej. controlador `InscripcionesNuevoIngreso`) instancia `PostulacionesAdminService`.
2. Paso 2: El consumidor invoca `listar($filtros, $page, $perPage)` pasando los filtros recibidos de la petición GET y los parámetros de paginación.
3. Paso 3: El servicio sanea y valida los parámetros de paginación (`$page` mínimo 1, `$perPage` entre 1 y 100).
4. Paso 4: El servicio construye la consulta base sobre `ni_inscripciones` aplicando los JOINs con `es_sucursales_carreras`, `es_carreras` y `aasucurs`.
5. Paso 5: El servicio aplica los filtros activos (paso, sede, carrera, estado de pago y búsqueda textual) utilizando bindings seguros.
6. Paso 6: El servicio calcula el conteo total de registros que cumplen los filtros para determinar `total` y `total_pages`.
7. Paso 7: El servicio ejecuta la consulta paginada aplicando `LIMIT` y `OFFSET`, ordenando por `created_at DESC, id DESC`.
8. Paso 8: El servicio resuelve eficientemente la intención de pago más reciente y el conteo de recaudos disponibles para las postulaciones de la página actual, enriqueciendo cada fila con la etiqueta provista por `PasoActualResolver`.
9. Paso 9: El servicio retorna el arreglo con la estructura estandarizada de paginación (`data`, `total`, `page`, `per_page`, `total_pages`).

## Flujos alternativos / variantes

### Consulta con filtros combinados

1. Paso 1: El consumidor invoca `listar()` con `['sede' => 1, 'carrera' => 3, 'paso' => '2', 'estado_pago' => 1]`.
2. Paso 2: El servicio incorpora todas las condiciones mediante cláusulas `AND` con sus respectivos parámetros parametrizados.
3. Paso 3: Solo se retornan las postulaciones que satisfacen simultáneamente todos los criterios.
4. Paso 4: El conteo total de la paginación refleja con precisión el conjunto filtrado.

### Búsqueda textual por cédula, nombre o correo

1. Paso 1: El consumidor envía `['search' => '12345678']` o `['search' => 'pedro.perez@example.com']`.
2. Paso 2: El servicio limpia el término y aplica una condición agrupada `(identificacion_valor LIKE :search: OR nombre LIKE :search: OR apellido LIKE :search: OR correo LIKE :search:)`.
3. Paso 3: Se devuelven las postulaciones cuyos datos personales coincidan con el término, sin importar mayúsculas/minúsculas.

### Postulación sin intención de pago registrada

1. Paso 1: Una postulación se encuentra en Paso 0 o Paso 1 y aún no registra filas en `pg_intenciones_pago`.
2. Paso 2: La resolución del pago identifica la ausencia de intención.
3. Paso 3: El servicio asigna `estado_pago_id = null` y `estado_pago_nombre = 'Pendiente'`.
4. Paso 4: Si el consumidor filtró por el estado especial `pendiente`, esta postulación es incluida en los resultados.

### Página solicitada superior al total de páginas

1. Paso 1: El consumidor solicita la página `10` cuando el total de registros solo produce `3` páginas.
2. Paso 2: El servicio procesa la consulta con el `OFFSET` correspondiente.
3. Paso 3: La consulta devuelve `data = []`.
4. Paso 4: La respuesta mantiene `total = N`, `total_pages = 3` y `page = 10`, permitiendo al consumidor manejar el estado vacío sin generar errores de ejecución.

### Obtención de catálogos para filtros

1. Paso 1: El consumidor invoca `obtenerCatalogosFiltros()`.
2. Paso 2: El servicio consulta las sedes activas desde `aasucurs` y carreras activas desde `es_carreras` que cuenten con oferta académica.
3. Paso 3: El servicio consulta los estados de pago activos desde `pg_estados`.
4. Paso 4: El servicio genera las opciones de paso actual utilizando `PasoActualResolver`.
5. Paso 5: Retorna el mapa completo estructurado para inicializar los combos de filtro en la interfaz.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Parámetro `$page` menor a 1 o no numérico | Validación inicial en `listar()` | Se normaliza automáticamente a `1` | Consulta ejecutada en la primera página |
| Parámetro `$perPage` menor a 1 | Validación inicial en `listar()` | Se normaliza al valor por defecto `15` | Consulta ejecutada con tamaño por defecto |
| Parámetro `$perPage` mayor a 100 | Validación de límite superior en `listar()` | Se trunca al valor máximo permitido de `100` | Consulta protegida contra desbordamiento de memoria |
| Caracteres maliciosos o intentos de SQLi en búsqueda | Uso de Query Builder y parameter binding | Los caracteres se tratan como literales de búsqueda | Consulta parametrizada segura; sin inyección |
| Filtro de paso con valor desconocido o no válido | Validación contra los valores admitidos de paso | El filtro se descarta o no produce coincidencias | Sin excepción; resultados consistentes |
| Error de conexión o fallo de base de datos | Captura de `DatabaseException` | Registro en log de errores con contexto | Excepción controlada propagada al llamador |

## Reglas de negocio y validaciones

1. **Aislamiento y solo lectura:** El servicio `PostulacionesAdminService` opera exclusivamente como lector de datos; no debe ejecutar sentencias `INSERT`, `UPDATE` ni `DELETE` bajo ninguna circunstancia.
2. **Normalización de paginación:**
   - `$page`: entero positivo $\ge 1$.
   - `$perPage`: entero positivo entre $1$ y $100$ (valor predeterminado: $15$).
   - `total_pages`: cálculo $\lceil \text{total} / \text{per\_page} \rceil$, con un mínimo de $1$ si $\text{total} = 0$.
3. **Resolución del estado de pago:**
   - La intención de pago válida es aquella asociada con `pg_intenciones_pago.ni_inscripcion_id = ni_inscripciones.id`.
   - Si existen múltiples registros para la misma postulación, prevalece el que tenga mayor fecha de creación / ID más alto.
   - Si no existe intención de pago asociada, el campo `estado_pago_nombre` debe ser siempre `'Pendiente'` y `estado_pago_id` debe ser `null`.
4. **Criterio de recaudos disponibles:**
   - Se contabilizan únicamente los registros de `ni_inscripciones_recaudos` vinculados a la inscripción donde `archivo_path IS NOT NULL`, `archivo_path != ''` y `activo = 1`.
   - No se realiza verificación I/O de existencia de archivos en el sistema de archivos local para asegurar un rendimiento de consulta óptimo.
5. **Enriquecimiento del paso actual:**
   - El valor almacenado en `ni_inscripciones.paso_actual` ('0' a '4') se traduce a su nombre legible utilizando `PasoActualResolver::etiqueta()`.
   - En caso de valor nulo o no mapeado, se adopta el texto de respaldo `'Paso no disponible'`.
6. **Seguridad y bindings:**
   - Todo término de búsqueda o valor de filtro debe enlazarse mediante bindings (`named parameters` o `question marks`).
   - Queda expresamente prohibida la concatenación de variables en las sentencias SQL.
7. **Orden de resultados:**
   - El orden predeterminado e inmutable es cronológico inverso: `ni_inscripciones.created_at DESC, ni_inscripciones.id DESC`.

## Áreas afectadas

- **Nuevo servicio:**
  - `app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php`
- **Integraciones internas:**
  - `App\Libraries\Inscripciones\NuevoIngreso\PasoActualResolver`
- **Tablas involucradas (solo lectura en conexión principal):**
  - `ni_inscripciones`
  - `es_sucursales_carreras`
  - `es_carreras`
  - `aasucurs`
  - `ni_inscripciones_recaudos`
  - `pg_intenciones_pago`
  - `pg_estados`
- **Pruebas:**
  - `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php`
- **Documentación:**
  - `docs/features/014-consulta-paginada-postulaciones-nuevo-ingreso/plan.md`

## Criterios de finalización

- [x] La clase `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService` está creada e implementada.
- [x] El método `listar()` pagina correctamente respetando `$page`, `$perPage` (por defecto 15, máximo 100) y devuelve la estructura con `data`, `total`, `page`, `per_page` y `total_pages`.
- [x] Se aplican correctamente los filtros individuales y combinados por sede (`sucursal_id`), carrera (`carrera_id`), paso actual (`paso`) y estado de pago (`estado_pago`).
- [x] La búsqueda textual (`search` / `q`) filtra adecuadamente por coincidencia parcial en cédula, nombre, apellido o correo mediante bindings seguros.
- [x] La intención de pago más reciente por postulación se resuelve con precisión, asignando `'Pendiente'` a aquellas que no posean intenciones registradas.
- [x] El conteo de recaudos disponibles refleja exactamente la cantidad de recaudos activos con `archivo_path` no vacío sin realizar I/O en disco.
- [x] Cada registro retornado incluye la etiqueta legible del paso actual provista por `PasoActualResolver`.
- [x] El método `obtenerCatalogosFiltros()` entrega los listados de sedes, carreras, pasos legibles y estados de pago.
- [x] El orden de resultados es estrictamente descendente por fecha de creación e ID.
- [x] La suite de pruebas de integración en `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` cubre todos los escenarios (filtros, paginación, límites, búsqueda, casos sin pago, bindings) y se ejecuta con éxito.
- [x] No se realizan escrituras ni modificaciones de datos en ninguna tabla.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial de la funcionalidad para el Slice 4 del panel administrativo de nuevo ingreso | Antigravity (agente) |
| 2026-10-30 | Implementación de `PostulacionesAdminService` con paginación, filtros seguros, resolución de pago/recaudos y suite de pruebas de integración (15 pruebas, 110 aserciones) | Antigravity (agente) |
