# Listado administrativo de inscripciones de nuevo ingreso con filtros y paginación

- **Código:** FEAT-015
- **Tipo:** feature
- **Estado:** en curso
- **Fecha:** 2026-10-30
- **Autor:** opencode (agente)

## Objetivo

Que un administrador autorizado con el módulo `inscripciones_ni` pueda iniciar sesión, llegar desde el panel al listado de postulaciones de nuevo ingreso, filtrar y paginar los resultados, y ver los datos mínimos de cada postulación con la identificación enmascarada. El acceso debe resolverse siempre desde la sesión administrativa y el permiso del perfil, nunca desde parámetros del cliente.

## Alcance

- **Incluye:**
  - Registrar `GET admin/panel/inscripciones-nuevo-ingreso` dentro del grupo `admin/panel`, con el filtro `adminPanel:module=inscripciones_ni`.
  - Crear el controlador `App\Controllers\Admin\InscripcionesNuevoIngreso` con un método de listado que lea los filtros del query string, normalice la página, fije 15 registros por página, consulte `PostulacionesAdminService` y renderice la vista.
  - Crear la vista `app/Views/admin/nuevo_ingreso/index.php` con formulario de filtros, tabla de resultados, estado vacío, mensaje de error y paginación.
  - Mostrar las columnas: identificación enmascarada, nombre completo, correo, teléfono, carrera, sede, paso actual legible, estado de pago y cantidad de recaudos disponibles.
  - Exponer los filtros `paso`, `sucursal_id`, `carrera_id`, `estado_pago` y `search`, alimentados por `obtenerCatalogosFiltros()`.
  - Reutilizar el partial `app/Views/admin/templates/_paginacion.php` conservando los filtros activos.
  - Agregar al header la entrada “Inscripciones NI” en escritorio y móvil, visible solo cuando el perfil tiene el módulo activo.
  - Hacer dinámico el enlace “Inicio” para que apunte a la primera pantalla permitida del usuario y no provoque una denegación de sesión.
  - Ajustar `PanelAuth` para redirigir después del login a la primera pantalla permitida: dashboard Zelle si el perfil tiene `zelle`, listado NI si solo tiene `inscripciones_ni`.
  - Crear un helper compartido para resolver los módulos administrativos activos de un perfil y la URL de inicio, reutilizado por `PanelAuth`, `Panel` y el nuevo controlador.
  - Agregar pruebas automatizadas del helper de navegación y ejecutar las pruebas existentes del filtro `AdminPanel` y del servicio de consulta.
  - Documentar el smoke test manual del flujo completo.

- **No incluye:**
  - La ruta, el controlador y la vista de detalle de una postulación, el enlace “Ver” y la tabla de recaudos. Corresponden al Slice 7 del plan `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md` y se especifican en un cambio posterior.
  - La consulta de detalle con recaudos (Slice 6) y la visualización o descarga segura de archivos (Slices 8 y 9).
  - Aprobar, rechazar o modificar postulaciones, pagos o documentos. El listado es estrictamente de solo lectura.
  - Crear o modificar el módulo `inscripciones_ni`, sus seeders, migraciones o asignaciones de perfil. Ya existen en FEAT-012.
  - Cambiar la lógica del dashboard Zelle, sus rutas, sus consultas o su exportación.
  - Cambiar el comportamiento del filtro `AdminPanel` para rutas distintas de la nueva.
  - Agregar un selector de tamaño de página o columnas ordenables.
  - Enmascarar nombre, correo o teléfono en el listado.
  - Modificar la SPA, la API JWT, el CORS o el flujo de estudiantes.

> **Evaluación de alcance:** el cambio cubre una sola capacidad de negocio: “acceder al listado administrativo de postulaciones de nuevo ingreso”. La ruta, el controlador, la vista, los filtros y la paginación son una unidad; el menú y la redirección post-login son necesarios para que esa capacidad sea alcanzable sin romper la sesión del usuario. El detalle es una capacidad independiente y se difiere. No se detectó necesidad de dividir este cambio.

## Contexto y supuestos

- La rama de trabajo detectada es `feature/panel-administrativo-documentos-ni`.
- El servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService` (FEAT-014) ya existe y expone `listar($filtros, $page, $perPage)` y `obtenerCatalogosFiltros()`.
- `listar()` acepta los filtros `paso`, `sucursal_id` (o `sede`), `carrera_id` (o `carrera`), `estado_pago` y `search` (o `q`). La vista enviará los nombres canónicos `paso`, `sucursal_id`, `carrera_id`, `estado_pago` y `search`.
- `listar()` ya normaliza la página y el tamaño, aplica bindings, ordena por `created_at DESC, id DESC`, resuelve el último estado de pago y cuenta recaudos. El controlador no duplica esas reglas.
- El tamaño de página será fijo en 15, que es el valor por defecto del servicio.
- El módulo autorizado es `inscripciones_ni` y, según FEAT-012, solo el perfil `Auditor NI` tiene una asignación activa. El control de acceso real lo sigue aplicando `AdminPanel`.
- El login del panel reutiliza las credenciales de `ac_usuarios` y ya exige que el perfil tenga al menos un acceso activo. No se cambia la autenticación ni el hash de claves.
- La prioridad de destino post-login es `zelle` y luego `inscripciones_ni`. Un usuario con ambos módulos conserva el dashboard Zelle actual.
- `admin/panel` sigue siendo el dashboard de Zelle. Un usuario solo con `inscripciones_ni` no debe navegar allí; su “Inicio” será el listado NI.
- La identificación se enmascara con `mask_identificacion()` sobre `identificacion_completa`. El resto de los datos personales se muestra completo en el listado, según el plan de slices.
- El enlace “Ver” no se implementa en este cambio porque la ruta de detalle no existe todavía. No se deja un enlace roto.
- El header es compartido por todas las vistas del panel. Las nuevas variables tendrán valores por defecto seguros para no romper vistas existentes.
- El grupo `admin/panel` ya aplica el filtro `csrf`; la nueva ruta es GET y no procesa formularios POST. No se agrega una ruta de escritura.
- Las tablas de acceso (`ac_usuarios`, `ac_accesos`, `ac_perfiles_accesos`) viven en la conexión `default`.
- Si falla la base de datos, se registra el detalle en el log y se muestra un mensaje genérico en la vista. No se exponen trazas al usuario.
- El código documental del proyecto usa el esquema `FEAT-NNN`. El siguiente número libre es `015`, verificado contra `docs/features/`.
- La suite completa del proyecto tiene un fallo preexistente ajeno a este cambio; se ejecutan las pruebas del área afectada.

## Flujo normal

1. Paso 1: Un administrador con perfil `Auditor NI` abre `admin/panel/login` e ingresa usuario, contraseña y sede.
2. Paso 2: `PanelAuth::autenticar()` valida credenciales, reCAPTCHA si aplica y que el perfil tenga al menos un acceso activo.
3. Paso 3: `PanelAuth` guarda `admin_user` en la sesión CI4 y resuelve los módulos activos del perfil.
4. Paso 4: Si el perfil solo tiene `inscripciones_ni`, el login redirige a `admin/panel/inscripciones-nuevo-ingreso`; si tiene `zelle`, redirige a `admin/panel`.
5. Paso 5: El filtro `AdminPanel` valida la sesión, que el usuario siga activo, que el módulo `inscripciones_ni` exista y que el perfil tenga una asignación activa y no borrada.
6. Paso 6: `InscripcionesNuevoIngreso::index()` lee `page`, `paso`, `sucursal_id`, `carrera_id`, `estado_pago` y `search` del query string.
7. Paso 7: El controlador normaliza `page` a un entero mayor o igual a 1 y fija `perPage = 15`; no acepta tamaños de página del cliente.
8. Paso 8: El controlador llama a `listar($filtros, $page, 15)` y a `obtenerCatalogosFiltros()`.
9. Paso 9: El servicio devuelve `data`, `total`, `page`, `per_page` y `total_pages`, con los datos normalizados de cada postulación.
10. Paso 10: El controlador pasa a la vista los resultados, la metadata de paginación, los catálogos, los filtros activos y las variables de navegación del header.
11. Paso 11: La vista renderiza el header con el menú autorizado, el formulario de filtros, la tabla de resultados y el partial de paginación.
12. Paso 12: La tabla muestra la identificación enmascarada, el nombre completo, el correo, el teléfono, la carrera, la sede, la etiqueta del paso, el estado de pago y el número de recaudos disponibles.
13. Paso 13: El administrador envía el formulario de filtros por GET; el flujo vuelve al Paso 6 y la paginación conserva los filtros activos.

## Flujos alternativos / variantes

### Filtros combinados

1. Paso 1: El administrador selecciona paso, sede, carrera y estado de pago, y escribe un término de búsqueda.
2. Paso 2: El formulario envía todos los parámetros por GET.
3. Paso 3: El controlador los entrega al servicio sin construir SQL.
4. Paso 4: El servicio aplica las condiciones con AND y bindings.
5. Paso 5: La vista muestra solo las postulaciones que cumplen todos los criterios y la paginación conserva cada filtro.

### Búsqueda textual

1. Paso 1: El administrador escribe una cédula, nombre, apellido o correo en `search`.
2. Paso 2: El controlador recorta el valor y lo envía al servicio.
3. Paso 3: El servicio aplica la búsqueda parametrizada sobre los cuatro campos.
4. Paso 4: La vista muestra los resultados coincidentes y conserva el término en el formulario y en los enlaces de paginación.

### Navegación entre páginas

1. Paso 1: El administrador pulsa “Anterior” o “Siguiente” en el partial de paginación.
2. Paso 2: El enlace incluye los filtros activos y el nuevo `page`, sin duplicar el parámetro.
3. Paso 3: El controlador normaliza la página y consulta el servicio.
4. Paso 4: La vista muestra la página solicitada y mantiene los filtros visibles.

### Página fuera del rango total

1. Paso 1: El administrador solicita una página mayor que `total_pages`.
2. Paso 2: El servicio devuelve `data = []` conservando `total`, `page`, `per_page` y `total_pages`.
3. Paso 3: La vista muestra el estado vacío y la paginación con la página solicitada.
4. Paso 4: No se produce una excepción ni se pierde la sesión.

### Listado sin resultados

1. Paso 1: Los filtros no coinciden con ninguna postulación.
2. Paso 2: El servicio devuelve `data = []` y `total = 0`.
3. Paso 3: La vista muestra “No se encontraron postulaciones” y mantiene el formulario con los filtros aplicados.
4. Paso 4: La paginación no se muestra si solo hay una página.

### Login de un usuario con ambos módulos

1. Paso 1: El perfil tiene asignaciones activas de `zelle` e `inscripciones_ni`.
2. Paso 2: El resolvedor devuelve ambos módulos con prioridad `zelle`.
3. Paso 3: El login redirige a `admin/panel`.
4. Paso 4: El header muestra “Inicio”, “Reportes Zelle” e “Inscripciones NI”.

### Login de un usuario solo con `inscripciones_ni`

1. Paso 1: El perfil solo tiene la asignación activa de `inscripciones_ni`.
2. Paso 2: El resolvedor devuelve solo ese módulo.
3. Paso 3: El login redirige al listado NI.
4. Paso 4: El header muestra “Inicio” apuntando al listado NI y “Inscripciones NI”; no muestra “Reportes Zelle”.

### Sesión ya iniciada que vuelve al login

1. Paso 1: El usuario con sesión `admin_user` abre `admin/panel/login`.
2. Paso 2: `PanelAuth::login()` resuelve sus módulos activos.
3. Paso 3: Lo redirige a su primera pantalla permitida sin mostrar el formulario.
4. Paso 4: Si ya no tiene módulos activos, limpia `admin_user` y muestra el login con un mensaje de error.

### Acceso directo sin sesión

1. Paso 1: Un visitante abre la URL del listado sin `admin_user`.
2. Paso 2: `AdminPanel` detecta la ausencia de sesión.
3. Paso 3: Redirige a `admin/panel/login` con `admin_error`.
4. Paso 4: No se consulta el servicio ni se muestran datos.

### Acceso directo con un perfil sin el módulo

1. Paso 1: Un usuario con sesión de Zelle abre la URL del listado.
2. Paso 2: `AdminPanel` no encuentra una asignación activa de `inscripciones_ni`.
3. Paso 3: Redirige al login con `admin_error` y elimina `admin_user`, según el comportamiento actual del filtro.
4. Paso 4: No se muestran datos de postulaciones.

### Permiso revocado durante la sesión

1. Paso 1: El usuario tenía acceso al módulo al iniciar sesión, pero la asignación se desactiva o borra.
2. Paso 2: La siguiente petición al listado es evaluada por `AdminPanel`.
3. Paso 3: El filtro deniega el acceso y limpia la sesión.
4. Paso 4: El usuario debe volver a autenticarse.

### Usuario eliminado o módulo inexistente

1. Paso 1: El filtro consulta `ac_usuarios` o `ac_accesos`.
2. Paso 2: El usuario está borrado o el módulo no existe o está borrado.
3. Paso 3: Redirige al login con un mensaje y, si corresponde, limpia la sesión.
4. Paso 4: No se ejecuta la consulta del listado.

### Error de base de datos durante el listado

1. Paso 1: El servicio lanza `DatabaseException` al contar o consultar.
2. Paso 2: El controlador captura la excepción y registra el detalle en el log.
3. Paso 3: Responde con código 500 y renderiza la misma vista con un mensaje genérico.
4. Paso 4: No se muestran trazas, SQL ni datos personales.

### Catálogos vacíos

1. Paso 1: No hay sedes, carreras, pasos o estados de pago disponibles.
2. Paso 2: El servicio devuelve listas vacías.
3. Paso 3: El formulario muestra solo la opción “Todos” en cada filtro.
4. Paso 4: La tabla puede seguir mostrando resultados si los filtros no dependen de esos catálogos.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Petición sin sesión administrativa | `admin_user` ausente o inválido en `AdminPanel` | Redirige a `admin/panel/login` con `admin_error` | Acceso denegado; sin consulta |
| Usuario de sesión eliminado o inactivo | Consulta a `ac_usuarios` sin resultado o con `borrado_dt` | Redirige al login y limpia `admin_user` | Acceso denegado |
| Módulo `inscripciones_ni` inexistente o borrado | Consulta a `ac_accesos` sin resultado o con `borrado_dt` | Redirige al login con `admin_error` | Acceso denegado |
| Perfil sin asignación activa del módulo | Consulta a `ac_perfiles_accesos` sin resultado, inactiva o borrada | Redirige al login y limpia `admin_user` | Acceso denegado |
| Perfil sin ningún módulo activo al iniciar sesión | Resolvedor de módulos devuelve lista vacía | `PanelAuth` rechaza el login con mensaje y no crea sesión | Sin sesión administrativa |
| Sesión con `perfil_id` ausente o inválido | Resolvedor no puede consultar el perfil | Limpia `admin_user` y redirige al login | Acceso denegado |
| `page` no numérico, cero o negativo | Normalización en el controlador | Se usa `1` | Primera página |
| `page` mayor que `total_pages` | Servicio devuelve `data = []` | La vista muestra estado vacío y conserva los filtros | Sin excepción |
| Filtro de paso con valor no permitido | Validación del servicio | El servicio no devuelve coincidencias | Tabla vacía |
| Filtro de sede o carrera con valor no positivo | Validación del servicio | El servicio no devuelve coincidencias | Tabla vacía |
| Término de búsqueda con comillas o intento de inyección | Bindings del servicio | Se trata como texto literal | Consulta segura |
| Falla de base de datos al listar o cargar catálogos | `DatabaseException` capturada en el controlador | Log del detalle; vista con mensaje genérico y código 500 | Sin datos; error visible |
| Catálogos sin datos | Listas vacías del servicio | Selects con “Todos”; sin errores | Listado operativo |
| Sin resultados | `total = 0` | Tabla con mensaje “No se encontraron postulaciones” | Estado vacío |
| Enlace “Inicio” sin módulos resueltos | Helper devuelve URL nula | El header no renderiza el enlace | Sin navegación inválida |

## Reglas de negocio y validaciones

- La identidad y el permiso del administrador salen de la sesión `admin_user` y de la base `default`; nunca de un parámetro de la petición.
- El módulo se identifica por `codigo_acceso = 'inscripciones_ni'`, no por un `id` fijo.
- Solo se consideran asignaciones con `activo = '1'`, `borrado_dt IS NULL` y un acceso con `borrado_dt IS NULL`.
- La nueva ruta debe declararse dentro del grupo `admin/panel` y llevar el filtro `adminPanel:module=inscripciones_ni`. No se permite una ruta sin filtro.
- El controlador no ejecuta SQL propio para el listado ni para los catálogos; delega en `PostulacionesAdminService`.
- El tamaño de página es fijo en 15. El cliente no puede imponer otro valor.
- La página se normaliza a un entero mínimo de 1. Los filtros se envían como cadenas y el servicio decide su validez.
- Los filtros se conservan en la paginación, excluyendo `page` del arreglo de parámetros para evitar duplicados.
- La identificación se enmascara con `mask_identificacion()` sobre `identificacion_completa`; no se muestra la cédula completa en el listado.
- Nombre, correo y teléfono se muestran completos en el listado, según la decisión funcional registrada.
- Toda salida dinámica se escapa con `esc()`. No se interpolan datos de usuario en HTML o JavaScript sin escapar.
- La tabla no incluye el enlace “Ver” en este cambio. Se agregará cuando exista la ruta de detalle.
- La entrada “Inscripciones NI” del menú se muestra solo si `inscripciones_ni` está entre los módulos activos del perfil.
- La entrada “Reportes Zelle” se muestra solo si `zelle` está entre los módulos activos.
- El enlace “Inicio” apunta a la primera pantalla permitida: `admin/panel` si existe `zelle`; listado NI si solo existe `inscripciones_ni`; no se renderiza si no hay módulos.
- La prioridad de módulos es `zelle` y luego `inscripciones_ni`, para conservar el comportamiento actual de los usuarios que ya usan Zelle.
- El estado activo del menú se determina con una variable explícita (`menu_activo`), no por el texto del título.
- El header debe funcionar con valores por defecto si una vista antigua no envía las nuevas variables.
- Los errores de base de datos se registran con `log_message('error', ...)` y se muestra un mensaje genérico al usuario.
- No se realizan escrituras, migraciones, seeds ni cambios de esquema.
- Los comentarios y mensajes nuevos se escriben en español, según las convenciones del repositorio.

## Áreas afectadas

- `app/Config/Routes.php` (nueva ruta dentro del grupo `admin/panel`).
- `app/Controllers/Admin/InscripcionesNuevoIngreso.php` (nuevo controlador).
- `app/Views/admin/nuevo_ingreso/index.php` (nueva vista).
- `app/Views/admin/templates/header.php` (menú condicionado, Inicio dinámico y estado activo).
- `app/Views/admin/templates/_paginacion.php` (reutilizado; sin cambios previstos).
- `app/Controllers/Admin/PanelAuth.php` (redirección post-login y reutilización del resolvedor).
- `app/Controllers/Admin/Panel.php` (pasar variables de navegación al header).
- `app/Helpers/admin_access_helper.php` (nuevo helper de módulos activos y URL de inicio).
- `tests/app/Helpers/AdminAccessHelperTest.php` (nuevo).
- `tests/app/Filters/AdminPanelTest.php` (ejecutar la cobertura existente del módulo; ampliar solo si falta un caso).
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` (ejecutar como regresión).
- `docs/features/015-listado-administrativo-inscripciones-nuevo-ingreso/plan.md` (este documento).
- `MEMORY.md` (solo si el cambio altera el estado o las decisiones documentadas del proyecto).

No se modifican `vendor/`, `public/vendor/`, `system/`, `app/ThirdParty/`, la SPA, la API JWT ni el flujo de estudiantes.

## Criterios de finalización

- [ ] La ruta `GET admin/panel/inscripciones-nuevo-ingreso` existe dentro del grupo `admin/panel` y usa el filtro `adminPanel:module=inscripciones_ni`.
- [ ] El controlador `App\Controllers\Admin\InscripcionesNuevoIngreso` existe, lee los filtros del query string, normaliza `page` y usa 15 registros por página.
- [ ] El controlador delega el listado y los catálogos en `PostulacionesAdminService`; no contiene SQL propio para esas consultas.
- [ ] La vista `app/Views/admin/nuevo_ingreso/index.php` existe y muestra las columnas: identificación enmascarada, nombre completo, correo, teléfono, carrera, sede, paso, estado de pago y recaudos disponibles.
- [ ] La identificación se muestra enmascarada con `mask_identificacion()` sobre `identificacion_completa`; no aparece la cédula completa.
- [ ] Todos los datos dinámicos de la vista se escapan con `esc()`.
- [ ] El formulario expone los filtros `paso`, `sucursal_id`, `carrera_id`, `estado_pago` y `search`, poblados desde `obtenerCatalogosFiltros()`.
- [ ] Los filtros se pueden combinar y el servicio recibe los nombres canónicos.
- [ ] La paginación reutiliza `_paginacion.php`, conserva los filtros activos y no duplica `page`.
- [ ] Una página fuera de rango muestra el estado vacío sin excepción y conserva la metadata.
- [ ] Un listado sin resultados muestra “No se encontraron postulaciones” y mantiene los filtros.
- [ ] Un `DatabaseException` se registra en el log y la vista muestra un mensaje genérico con código 500.
- [ ] El login redirige a `admin/panel` si el perfil tiene `zelle`, y al listado NI si solo tiene `inscripciones_ni`.
- [ ] Un usuario con ambos módulos conserva el dashboard Zelle como destino post-login.
- [ ] El header muestra “Inscripciones NI” en escritorio y móvil solo si el perfil tiene el módulo activo.
- [ ] El header muestra “Reportes Zelle” solo si el perfil tiene `zelle`.
- [ ] El enlace “Inicio” apunta a la primera pantalla permitida y no provoca una denegación de sesión para usuarios solo NI.
- [ ] El estado activo del menú se resuelve con `menu_activo` y funciona en escritorio y móvil.
- [ ] Sin sesión, la ruta redirige a `admin/panel/login` con `admin_error`.
- [ ] Con sesión de un perfil sin `inscripciones_ni`, la ruta redirige al login y no muestra datos.
- [ ] Con el módulo activo, la ruta responde 200 y muestra el listado.
- [ ] No se realizan escrituras en base de datos durante el listado.
- [ ] Las pruebas del helper de navegación pasan.
- [ ] Las pruebas existentes de `AdminPanel` y `PostulacionesAdminService` pasan.
- [ ] Se ejecuta `php -l` sobre el controlador, la vista y el helper nuevos sin errores de sintaxis.
- [ ] Se completa el smoke test manual: login NI, listado, filtros, paginación, estado vacío, menú, Inicio y cierre de sesión.
- [ ] No se modificaron archivos de dependencias, la SPA, la API JWT ni el flujo de estudiantes.

## Riesgos

- **Medio:** el cambio toca `PanelAuth` y el header compartido; una regresión podría afectar el acceso actual al panel Zelle. Se mitiga con pruebas del helper, regresión de `AdminPanel` y smoke test de ambos perfiles.
- **Bajo:** un usuario solo NI que escriba manualmente `admin/panel` seguirá siendo rechazado y perderá la sesión, porque el dashboard sigue protegido por `zelle`. El menú dinámico evita la navegación normal; corregir el filtro queda fuera de alcance.
- **Bajo:** los catálogos pueden ser grandes; se renderizan selects simples sin paginación. Si el volumen crece, se evaluará un selector con búsqueda en otro cambio.
- **Bajo:** el listado muestra correo y teléfono completos. Es una decisión funcional; si cambia la política de privacidad, se ajusta el enmascarado en un cambio posterior.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial del listado administrativo, acceso post-login por módulo y menú condicionado. Se difiere el detalle al Slice 7. | opencode (agente) |
| 2026-10-30 | Implementación consolidada en `feature/panel-administrativo-documentos-ni` con merge --no-ff. Pruebas automatizadas y `php -l` aprobados; queda pendiente el smoke test manual con base de datos y navegador. | opencode (agente) |
