# Prototipo de ejecución — FEAT-017 Detalle administrativo de una postulación con sus recaudos digitales

- **Rama:** p-feature/detalle-administrativo-postulacion-recaudos
- **Rama base:** feature/panel-administrativo-documentos-ni
- **Plan:** docs/features/017-detalle-administrativo-postulacion-recaudos/plan.md
- **Fecha:** 2026-10-30
- **Estado:** consolidado
- **Fecha de consolidación:** 2026-10-30
- **Rama destino:** feature/panel-administrativo-documentos-ni

## Resumen

Se habilitó el detalle de solo lectura de una postulación de nuevo ingreso desde el panel administrativo. Un administrador con el módulo `inscripciones_ni` puede abrir el detalle desde el listado, consultar el resumen del prospecto y ver los recaudos digitales con acciones “Ver” y “Descargar” solo cuando el archivo está disponible. Los endpoints de ver y descargar permanecen pendientes (Slices 8 y 9), por lo que los enlaces aún no responden.

## Tareas realizadas

- [x] Ruta `GET admin/panel/inscripciones-nuevo-ingreso/(:num)` agregada dentro del grupo `admin/panel` con filtro `adminPanel:module=inscripciones_ni`.
- [x] Método público `InscripcionesNuevoIngreso::detalle(int $id)` agregado; delega la consulta en `PostulacionesAdminService::obtenerDetalle()`.
- [x] Manejo de `id = 0` y de `null` del servicio con redirección al listado y flash `admin_error`.
- [x] Manejo de `DatabaseException` con log del `id` y vista con mensaje genérico y código 500.
- [x] Vista `app/Views/admin/nuevo_ingreso/detalle.php` creada con header administrativo, botón “Volver al listado”, resumen del prospecto y tabla de recaudos.
- [x] Valores de respaldo “No registrado”, “No disponible” y “Pendiente” implementados.
- [x] Estado de recaudo “Disponible” / “No adjuntado” y acciones condicionadas a `disponible === true`.
- [x] Enlaces “Ver” y “Descargar” con `target="_blank"` y `rel="noopener noreferrer"` hacia las rutas previstas.
- [x] Columna “Acciones” con enlace “Ver” agregada al listado y `colspan` del estado vacío ajustado a 10.
- [x] Pruebas de vista del detalle y del listado creadas.
- [x] Pruebas de `PostulacionesAdminServiceTest` y `AdminPanelTest` ejecutadas como regresión.
- [ ] Smoke test manual completo en un entorno con base de datos y sesión administrativa — Motivo: esta ejecución no dispone de un entorno levantado con datos reales ni credenciales de administrador; el flujo queda cubierto por pruebas de vista y regresión del filtro.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| Ruta de detalle existe en el grupo `admin/panel` con filtro `adminPanel:module=inscripciones_ni` | Revisión de `app/Config/Routes.php` y `php spark routes` | ok |
| `detalle(int $id)` es público y delega en `obtenerDetalle()` | Revisión del controlador | ok |
| El controlador no contiene SQL propio | Revisión del controlador (solo usa el servicio) | ok |
| `id = 0` redirige con `admin_error` sin consultar el servicio | Revisión del controlador | ok |
| Postulación inexistente redirige con `admin_error` | Revisión del controlador | ok |
| Ruta sin sesión redirige al login con `admin_error` | Regresión `AdminPanelTest` (9 pruebas) | ok |
| Perfil sin `inscripciones_ni` no accede | Regresión `AdminPanelTest` | ok |
| Ruta con módulo activo responde 200 | No ejecutado con petición real; cubierto parcialmente por `AdminPanelTest` | pendiente |
| Vista de detalle renderiza el header con `menu_activo = 'inscripciones_ni'` | Pruebas de vista y revisión | ok |
| Botón “Volver al listado” apunta al listado | `testIncluyeElBotonVolverAlListado` | ok |
| Identificación completa sin enmascarar | `testMuestraLaIdentificacionCompletaSinEnmascarar` | ok |
| Se muestran nombre, correo, teléfono, carrera, sede, paso y pago | `testRenderizaElResumenCompletoDelProspecto` | ok |
| Correo o teléfono vacíos muestran “No registrado” | `testMuestraNoRegistradoCuandoCorreoYTelefonoEstanVacios` | ok |
| Estado de pago como badge | Revisión de la vista y `testRenderizaElResumenCompletoDelProspecto` | ok |
| Tabla con columnas “Recaudo”, “Estado” y “Acciones” | `testRenderizaLasColumnasDeLaTablaDeRecaudos` | ok |
| Recaudo disponible muestra “Disponible” y dos enlaces | `testRecaudoDisponibleMuestraEstadoYDosAcciones` | ok |
| Recaudo no disponible muestra “No adjuntado” y sin enlaces | `testRecaudoNoDisponibleNoGeneraAcciones` | ok |
| Enlace “Ver” apunta a la ruta prevista | `testRecaudoDisponibleMuestraEstadoYDosAcciones` | ok |
| Enlace “Descargar” agrega `?descargar=1` | `testRecaudoDisponibleMuestraEstadoYDosAcciones` | ok |
| Ambos enlaces usan `target="_blank"` y `rel="noopener noreferrer"` | `testLasAccionesSeAbrenEnPestanaNuevaConRelSeguro` | ok |
| URLs solo con identificadores enteros | `testLasUrlsSoloUsanIdentificadoresEnteros` | ok |
| Postulación sin recaudos muestra “Sin recaudos registrados” | `testPostulacionSinRecaudosMuestraEstadoVacio` | ok |
| La vista no lee archivos ni verifica MIME | `testLaVistaNoLeeArchivosNiVerificaMime` | ok |
| Datos dinámicos escapados con `esc()` | `testLosDatosDinamicosSeEscapan` | ok |
| Listado incluye columna “Acciones” y enlace “Ver” | `ListadoNuevoIngresoViewTest` | ok |
| Estado vacío del listado usa `colspan="10"` | `testElEstadoVacioUsaColspanDiez` | ok |
| Listado conserva identificación enmascarada | `testConservaLaIdentificacionEnmascarada` | ok |
| `DatabaseException` registra el `id` y responde 500 sin trazas | Revisión del controlador | ok |
| No hay escrituras en base de datos en el detalle | Revisión del controlador y la vista (solo lectura) | ok |
| Pruebas nuevas de detalle y listado pasan | 18 pruebas ejecutadas | ok |
| Regresión de servicio y filtro pasa | 33 pruebas ejecutadas | ok |
| `php -l` sin errores en controlador y vistas | Comando ejecutado | ok |
| Smoke test manual completo | No ejecutado por falta de entorno con datos y sesión admin | pendiente |
| Sin cambios en dependencias, SPA, API JWT, Zelle ni flujo de estudiantes | Revisión de `git status` | ok |
| `graphify update .` ejecutado | Comando ejecutado | ok |

## Flujos cubiertos

- **Flujo normal:** listado con enlace “Ver”, carga del detalle autorizado, resumen del prospecto, tabla de recaudos y acciones para los disponibles.
- **Flujos alternativos:** postulación sin recaudos, mezcla de recaudos disponibles y ausentes, datos de contacto vacíos, oferta no encontrada, paso desconocido y acciones hacia endpoints aún no implementados.
- **Control de errores:** `id = 0`, postulación inexistente, excepción de base de datos al consultar el detalle, excepción al resolver los módulos del header y acceso denegado por el filtro `AdminPanel`.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Views/admin/nuevo_ingreso/detalle.php` | Vista del detalle con resumen del prospecto y tabla de recaudos. |
| `tests/app/Views/Admin/DetallePostulacionViewTest.php` | Pruebas de renderizado, respaldos, acciones, URLs y escapado. |
| `tests/app/Views/Admin/ListadoNuevoIngresoViewTest.php` | Pruebas de la columna “Acciones”, enlace “Ver” y `colspan`. |
| `docs/features/017-detalle-administrativo-postulacion-recaudos/prototipo.md` | Documentación de la ejecución. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Config/Routes.php` | Ruta de detalle con filtro `adminPanel:module=inscripciones_ni`. |
| `app/Controllers/Admin/InscripcionesNuevoIngreso.php` | Método `detalle()` con delegación al servicio, redirecciones y manejo de errores. |
| `app/Views/admin/nuevo_ingreso/index.php` | Columna “Acciones” con enlace “Ver” y `colspan="10"`. |
| `docs/features/017-detalle-administrativo-postulacion-recaudos/plan.md` | Estado actualizado a “en curso”. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** `GET admin/panel/inscripciones-nuevo-ingreso/{id}` con filtro `adminPanel:module=inscripciones_ni`. Los enlaces a `.../{id}/recaudo/{recaudoId}` y `...?descargar=1` quedan previstos para los Slices 8 y 9.
- **Permisos y validaciones:** sesión `admin_user`, usuario activo, módulo `inscripciones_ni` y asignación activa del perfil mediante `AdminPanel`; el `id` se normaliza a entero no negativo.
- **Migraciones/seeds:** no aplica.
- **Compatibilidad:** no se modifica el contrato de `PostulacionesAdminService`, el filtro `AdminPanel`, el login ni el listado existente; solo se agrega una columna y una ruta.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | 24 pruebas, 354 aserciones, ok |
| `php vendor/phpunit/phpunit/phpunit tests/app/Filters/AdminPanelTest.php` | 9 pruebas, 23 aserciones, ok |
| `php vendor/phpunit/phpunit/phpunit tests/app/Helpers/AdminAccessHelperTest.php` | 5 pruebas, 12 aserciones, ok |
| `php vendor/phpunit/phpunit/phpunit tests/app/Views/Admin/DetallePostulacionViewTest.php` | 14 pruebas, 41 aserciones, ok |
| `php vendor/phpunit/phpunit/phpunit tests/app/Views/Admin/ListadoNuevoIngresoViewTest.php` | 4 pruebas, 6 aserciones, ok |
| `php -l` sobre rutas, controlador, vistas y pruebas nuevas | Sin errores de sintaxis |
| `php spark routes` | Ruta de detalle registrada |
| `graphify update .` | Grafo actualizado; advertencias por extensión SQL ausente y archivos ajenos con errores de sintaxis |

## Verificación

- **Línea base (antes):** `PostulacionesAdminServiceTest` y `AdminPanelTest` en 24 pruebas y 354 aserciones, ok.
- **Prueba manual (flujo normal):** no ejecutada con petición HTTP real por falta de entorno con base de datos y sesión administrativa. El renderizado se verificó con pruebas de vista.
- **Flujos alternativos y errores:** cubiertos por las pruebas de vista y por la regresión de `AdminPanelTest`.
- **Pruebas automatizadas:** 18 pruebas nuevas y 38 pruebas de regresión ejecutadas, todas ok.
- **Criterios del plan:** cumplidos los verificables en código y pruebas; queda pendiente el smoke test manual y la comprobación de respuesta 200 con una petición real.

## Desviaciones del plan

- No se agregó una prueba de controlador o de petición HTTP porque el plan solo contempla pruebas de vista y regresión del filtro. La verificación de respuesta 200 con petición real queda dentro del smoke test manual pendiente.

## Riesgos y pendientes

- El detalle expone identificación completa y datos personales; la única protección es el filtro `adminPanel:module=inscripciones_ni`.
- Los enlaces “Ver” y “Descargar” responden 404 hasta implementar los Slices 8 y 9. No deben presentarse como operativos.
- Pendiente ejecutar el smoke test manual en un entorno con base de datos y sesión administrativa, incluido el cierre de sesión y la comprobación de respuesta 200.
- No se realizó `commit` ni se publicó la rama.
