# Plan de slices — Panel administrativo de consulta de inscripciones de nuevo ingreso

- **Fecha:** 2026-10-30
- **Estado:** pendiente
- **Objetivo general:** Crear un panel administrativo de solo lectura que reutilice el login, layout, filtros y tablas del panel Zelle para consultar las postulaciones de nuevo ingreso. Debe listar todas las postulaciones con filtros y mostrar, en el detalle, información mínima del prospecto, su paso actual y los recaudos digitales adjuntos, con opción de verlos en línea o descargarlos.
- **Total de slices:** 9
- **Tipos:** 8 feature · 0 bugfix · 1 refactor · 0 hotfix
- **Regla:** cada slice cubre una única tarea
- **Supuestos:**
  - “Validar” significa **solo consultar**; no se aprueban, rechazan ni modifican postulaciones ni pagos.
  - Los documentos mostrados son únicamente los recaudos digitales de `ni_inscripciones_recaudos`; quedan fuera el comprobante Zelle y los documentos presenciales de FEAT-010.
  - El acceso se controla con un nuevo módulo `inscripciones_ni`, asignado inicialmente al perfil Administrador; otros perfiles se definen con negocio.
  - El filtro “estado” corresponde al estado de la intención de pago más reciente (`pg_estados`), no a un estado administrativo nuevo.
  - La información mínima del listado es: identificación, nombre, correo, teléfono, carrera, sede, paso actual, estado de pago y cantidad de recaudos disponibles. El detalle agrega la identificación completa y la tabla de recaudos.
  - Los archivos ya viven en `public/inscripciones-archivos/nuevo-ingreso`; no se migra su almacenamiento.
  - No se modifica el flujo de validación de pagos Zelle ni se agregan escrituras administrativas.

**Fuera de alcance:** aprobar/rechazar postulaciones, marcar documentos recibidos, validar pagos, sincronizar Orbis/GHL, modificar el Paso 1 o el panel Zelle existente.

## Mapa de dependencias

```text
1 → 5, 7, 8
2 → 5, 7
3 → 5, 7
4 → 5, 6
6 → 7, 8
8 → 9
```

## Slices

### Slice 1 — Registrar el módulo de acceso `inscripciones_ni`

- **Tipo:** feature
- **Objetivo:** que exista el permiso administrativo `inscripciones_ni` y esté asignado solo a los perfiles autorizados.
- **Depende de:** —
- **Áreas / archivos:** `app/Database/Seeds/AcAccesosSeeder.php`, `app/Database/Seeds/AcPerfilesAccesosSeeder.php`, pruebas de seeders.
- **Acciones:** 1) Agregar el acceso con `codigo_acceso = 'inscripciones_ni'` usando upsert por código, no por ID fijo. 2) Asignarlo al perfil Administrador y revocar otros perfiles para ese acceso. 3) Cubrir la ejecución doble del seeder y la ausencia de duplicados.
- **Verificación:** ejecutar ambos seeders dos veces; debe existir una sola fila en `ac_accesos` y una sola asignación activa; un perfil sin acceso recibe la denegación de `AdminPanel`.
- **Riesgo:** medio — controla acceso a datos personales de aspirantes.
- **Prompt sugerido:** `implementar feature: registrar el módulo administrativo inscripciones_ni y asignarlo a los perfiles autorizados`

### Slice 2 — Centralizar las etiquetas del paso actual

- **Tipo:** feature
- **Objetivo:** que el listado y el detalle muestren el mismo nombre legible para cada valor de `paso_actual`.
- **Depende de:** —
- **Áreas / archivos:** nueva clase en `app/Libraries/Inscripciones/NuevoIngreso/` y su prueba unitaria.
- **Acciones:** 1) Crear un resolvedor con el mapa de valores reales que escriben Paso0-Paso3. 2) Exponer `etiqueta()`, `descripcion()` y un valor de respaldo para pasos desconocidos o nulos. 3) Cubrir todos los valores conocidos, nulos y valores fuera de rango.
- **Verificación:** pruebas unitarias que confirmen etiqueta y descripción para cada paso, sin consultar base de datos.
- **Riesgo:** bajo — solo transforma valores existentes.
- **Prompt sugerido:** `implementar feature: centralizar el mapa de etiquetas del paso actual de nuevo ingreso`

### Slice 3 — Extraer la paginación del listado Zelle a un partial reutilizable

- **Tipo:** refactor
- **Objetivo:** reutilizar la paginación existente del panel Zelle sin duplicar marcado ni alterar su comportamiento.
- **Depende de:** —
- **Áreas / archivos:** `app/Views/admin/zelle/reportes.php`, nuevo partial en `app/Views/admin/templates/`.
- **Acciones:** 1) Extraer el bloque de paginación a un partial parametrizado por URL base, página, total de páginas y query string. 2) Reemplazar el bloque original del listado Zelle por el partial. 3) Conservar los filtros activos en los enlaces.
- **Verificación:** comparar los enlaces generados con una muestra de filtros; el listado Zelle sigue paginando igual y no cambia su contenido.
- **Riesgo:** medio — puede romper la navegación del panel existente.
- **Prompt sugerido:** `implementar refactor: extraer la paginación del listado Zelle a un partial reutilizable`

### Slice 4 — Crear la consulta paginada de postulaciones con filtros

- **Tipo:** feature
- **Objetivo:** obtener una página de postulaciones con los datos mínimos, el estado de pago y el conteo de recaudos disponibles, aplicando filtros del servidor.
- **Depende de:** —
- **Áreas / archivos:** nuevo servicio en `app/Libraries/Inscripciones/NuevoIngreso/Admin/`, tablas `ni_inscripciones`, `es_sucursales_carreras`, `es_carreras`, `aasucurs`, `ni_inscripciones_recaudos`, `pg_intenciones_pago`, `pg_estados`; pruebas de integración.
- **Acciones:** 1) Implementar `listar($filtros, $page, $perPage)` con filtros por paso, sede, carrera, estado de pago y búsqueda por cédula, nombre, apellido o correo. 2) Resolver la intención de pago más reciente por postulación y contar recaudos con `archivo_path` no vacío. 3) Usar bindings, límite máximo de página y orden por fecha de creación descendente. 4) Exponer los catálogos necesarios para los filtros.
- **Verificación:** pruebas con y sin filtros, filtros combinados, búsqueda, paginación, valores inválidos y verificación de que no hay escrituras ni concatenación de valores del cliente.
- **Riesgo:** medio — varias uniones y posible impacto de rendimiento.
- **Prompt sugerido:** `implementar feature: crear la consulta paginada de postulaciones de nuevo ingreso con filtros`

### Slice 5 — Exponer el listado administrativo con filtros y navegación

- **Tipo:** feature
- **Objetivo:** que un administrador autorizado abra el listado, filtre, pagine y navegue al detalle desde el panel.
- **Depende de:** Slice 1, Slice 2, Slice 3, Slice 4
- **Áreas / archivos:** `app/Config/Routes.php`, nuevo controlador `app/Controllers/Admin/InscripcionesNuevoIngreso.php`, vista `app/Views/admin/nuevo_ingreso/index.php`, `app/Views/admin/templates/header.php`.
- **Acciones:** 1) Agregar la ruta `GET admin/panel/inscripciones-nuevo-ingreso` con `adminPanel:module=inscripciones_ni`. 2) Crear el método de listado que lea filtros, consulte el servicio y renderice la vista. 3) Mostrar tabla con identificación enmascarada, nombre, correo, teléfono, carrera, sede, paso, estado de pago y recaudos disponibles. 4) Integrar filtros, paginación y el enlace “Ver”. 5) Agregar “Inscripciones NI” al menú de escritorio y móvil.
- **Verificación:** acceso permitido con el módulo, redirección sin sesión o sin permiso, filtros y paginación funcionales, salida escapada y navegación al detalle.
- **Riesgo:** bajo — no hay escrituras ni archivos involucrados.
- **Prompt sugerido:** `implementar feature: exponer el listado administrativo de inscripciones de nuevo ingreso con filtros`

### Slice 6 — Crear la consulta de detalle con recaudos digitales

- **Tipo:** feature
- **Objetivo:** obtener la información mínima de una postulación y todos sus recaudos activos con su disponibilidad.
- **Depende de:** Slice 4
- **Áreas / archivos:** servicio administrativo, `NiInscripcionRecaudoModel`, pruebas de integración.
- **Acciones:** 1) Implementar `obtenerDetalle($id)` con carrera, sede, paso y estado de pago. 2) Obtener los recaudos activos ordenados por catálogo, con nombre, obligatoriedad, estado y bandera `disponible` según `archivo_path`. 3) Devolver `null` cuando la postulación no exista. 4) No exponer rutas físicas ni ejecutar lecturas de archivo.
- **Verificación:** pruebas con postulación existente, inexistente, sin recaudos, con recaudos disponibles y no disponibles, y verificación de orden y ausencia de escrituras.
- **Riesgo:** medio — relación entre postulación y documentos.
- **Prompt sugerido:** `implementar feature: crear la consulta de detalle de una postulación con sus recaudos digitales`

### Slice 7 — Exponer el detalle administrativo con documentos

- **Tipo:** feature
- **Objetivo:** que el administrador vea el resumen del prospecto y la tabla de recaudos, con acciones solo para documentos disponibles.
- **Depende de:** Slice 1, Slice 2, Slice 3, Slice 6
- **Áreas / archivos:** `app/Config/Routes.php`, controlador administrativo, vista `app/Views/admin/nuevo_ingreso/detalle.php`.
- **Acciones:** 1) Agregar la ruta `GET admin/panel/inscripciones-nuevo-ingreso/(:num)` con `adminPanel:module=inscripciones_ni`. 2) Redirigir con mensaje si la postulación no existe. 3) Mostrar identificación completa, nombre, correo, teléfono, carrera, sede, paso y estado de pago. 4) Listar recaudos con estado “Disponible” o “No adjuntado”. 5) Mostrar botones “Ver” y “Descargar” únicamente cuando el archivo esté disponible.
- **Verificación:** acceso autorizado, caso no encontrado, documentos disponibles y ausentes, botones ocultos cuando corresponde y salida escapada.
- **Riesgo:** bajo — solo lectura de datos y enlaces.
- **Prompt sugerido:** `implementar feature: exponer el detalle administrativo de una postulación con sus recaudos`

### Slice 8 — Servir un recaudo en línea de forma segura

- **Tipo:** feature
- **Objetivo:** que un administrador autorizado abra un PDF o imagen de un recaudo directamente en el navegador, sin exponer archivos ajenos.
- **Depende de:** Slice 1, Slice 6
- **Áreas / archivos:** `app/Config/Routes.php`, controlador administrativo, resolvedor de archivos, pruebas de seguridad.
- **Acciones:** 1) Agregar la ruta `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)` con `adminPanel:module=inscripciones_ni`. 2) Validar que el recaudo pertenezca a la postulación. 3) Resolver la ruta real dentro de `FCPATH . 'inscripciones-archivos/nuevo-ingreso'` y rechazar rutas fuera de esa base. 4) Verificar existencia y MIME real permitido: PDF, JPEG, PNG o WEBP. 5) Responder `inline` con `Content-Type`, longitud, `nosniff` y caché privada; devolver 404 genérico si algo falla.
- **Verificación:** visualización correcta por tipo, 404 para recaudo ajeno, inexistente o ruta manipulada, redirección sin sesión y ausencia de rutas internas en la respuesta.
- **Riesgo:** alto — exposición de archivos y path traversal.
- **Prompt sugerido:** `implementar feature: servir recaudos digitales en línea de forma segura desde el panel administrativo`

### Slice 9 — Forzar la descarga segura de un recaudo

- **Tipo:** feature
- **Objetivo:** que el administrador descargue el recaudo con un nombre de archivo seguro y como adjunto.
- **Depende de:** Slice 8
- **Áreas / archivos:** misma ruta y resolvedor del Slice 8, vista de detalle y pruebas de cabeceras.
- **Acciones:** 1) Interpretar `?descargar=1` sobre el endpoint existente. 2) Enviar `Content-Disposition: attachment` con un nombre derivado del recaudo y la extensión validada. 3) Eliminar saltos de línea, comillas y caracteres de control del nombre. 4) Mantener las mismas validaciones de propiedad, ruta y MIME.
- **Verificación:** cabeceras de descarga correctas, nombre saneado, descarga de un archivo propio y 404 para archivo ajeno o inexistente; la vista en línea sigue funcionando.
- **Riesgo:** alto — inyección de cabeceras o entrega de archivos no autorizados.
- **Prompt sugerido:** `implementar feature: forzar la descarga segura de recaudos desde el panel administrativo`

## Tabla resumen

| # | Slice | Tipo | Depende de | Verificación |
| --- | --- | --- | --- | --- |
| 1 | Registrar módulo `inscripciones_ni` | feature | — | Seeder doble sin duplicados y acceso denegado a perfiles no autorizados |
| 2 | Centralizar etiquetas de paso | feature | — | Pruebas unitarias de todos los valores y casos nulos |
| 3 | Extraer paginación de Zelle | refactor | — | El listado Zelle conserva enlaces y filtros |
| 4 | Consulta paginada con filtros | feature | — | Pruebas de filtros, búsqueda, paginación y sin escrituras |
| 5 | Listado administrativo y navegación | feature | 1, 2, 3, 4 | Acceso, filtros, paginación y enlace al detalle |
| 6 | Consulta de detalle y recaudos | feature | 4 | Casos existente, inexistente, con y sin documentos |
| 7 | Detalle administrativo con documentos | feature | 1, 2, 3, 6 | Datos, estados de documentos y botones condicionados |
| 8 | Ver recaudo en línea | feature | 1, 6 | Inline correcto, 404 para ajenos o rutas manipuladas |
| 9 | Descargar recaudo | feature | 8 | Cabeceras de adjunto, nombre saneado y 404 seguro |
