# Prototipo de ejecución — FEAT-018 Servir un recaudo digital en línea desde el panel administrativo

- **Rama:** p-feature/servir-recaudo-en-linea-panel-administrativo
- **Rama base:** feature/panel-administrativo-documentos-ni
- **Plan:** docs/features/018-servir-recaudo-en-linea-panel-administrativo/plan.md
- **Fecha:** 2026-10-30
- **Estado:** consolidado (2026-10-30) en `feature/panel-administrativo-documentos-ni`

## Resumen

Se implementó el endpoint administrativo que entrega en línea el PDF o la imagen de un recaudo de una postulación de nuevo ingreso. El acceso exige sesión administrativa y el módulo `inscripciones_ni`, valida la propiedad del recaudo contra la base principal, rechaza rutas manipuladas o fuera de la base, detecta el MIME real y responde con cabeceras seguras o con un `404` genérico. La operación es de solo lectura y no modifica la postulación, el recaudo ni el archivo.

## Tareas realizadas

- [x] Registrar `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)` dentro del grupo `admin/panel` con el filtro `adminPanel:module=inscripciones_ni`.
- [x] Agregar `InscripcionesNuevoIngreso::recaudo(int $id, int $recaudoId)` público y sin SQL propio.
- [x] Crear `RecaudoArchivoService::resolver()` con validación de propiedad, ruta, base canónica, MIME y tamaño.
- [x] Añadir la verificación de `admin_user` y del módulo como defensa en profundidad ante auto-routing.
- [x] Responder `200` con `Content-Type`, `Content-Length`, `Content-Disposition: inline`, `nosniff` y caché privada.
- [x] Responder `404` genérico con `text/plain`, `no-store`, `nosniff` y el cuerpo exacto `Recurso no encontrado.`
- [x] Responder `500` genérico ante `DatabaseException` y errores inesperados.
- [x] Registrar solo los rechazos con `inscripcion_id`, `recaudo_id`, `admin_id` y motivo, sin rutas ni datos personales.
- [x] Agregar pruebas del servicio con archivos temporales y MIME real.
- [x] Agregar pruebas de integración del controlador, cabeceras, 404, 500, sesión/módulo y auto-routing.
- [x] Ejecutar las regresiones de `AdminPanelTest`, `PostulacionesAdminServiceTest` y `DetallePostulacionViewTest`.
- [x] Ejecutar `php -l` sobre ruta, controlador y servicio.
- [x] Ejecutar `graphify update .`.
- [ ] Smoke test manual en navegador — Motivo: el entorno local no dispone de una sesión administrativa real ni de postulaciones/recaudos de prueba en la base principal. Los escenarios se cubrieron con pruebas automatizadas equivalentes.
- [ ] Verificación de enlace simbólico fuera de la base — Motivo: la prueba se marcó como omitida porque el entorno Windows no permitió crear el enlace simbólico con `symlink()`. La comparación canónica se cubrió con una prueba unitaria por reflexión.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| Ruta dentro de `admin/panel` con filtro `adminPanel:module=inscripciones_ni` | Prueba que inspecciona la definición de la ruta y regresión de `AdminPanelTest` | ok |
| Método público `recaudo(int $id, int $recaudoId)` que delega en el servicio | Pruebas del controlador con servicio espía | ok |
| El controlador no contiene SQL propio | Revisión del controlador | ok |
| Verificación de `admin_user` y módulo antes de resolver | Pruebas sin sesión y sin módulo; el servicio espía no se invoca | ok |
| Sin sesión, la ruta filtrada redirige a `admin/panel/login` | Regresión `AdminPanelTest` y filtro declarado en la ruta | ok |
| Perfil sin `inscripciones_ni` no sirve el archivo | Regresión `AdminPanelTest` y prueba de defensa del controlador | ok |
| Auto-routing sin sesión o sin módulo responde `404` genérico | Pruebas del controlador | ok |
| `id` o `recaudoId` igual a `0` responde `404` sin consultar | Prueba con servicio espía y aserción de no invocación | ok |
| Recaudo de otra postulación responde `404` y registra `recaudo_no_disponible` | Pruebas del servicio y del controlador | ok |
| Recaudo inexistente o inactivo responde `404` | Pruebas del servicio y del controlador | ok |
| `archivo_path` vacío o nulo responde `404` y registra `recaudo_sin_archivo` | Pruebas del servicio | ok |
| Ruta con byte nulo, `..`, absoluta o unidad Windows responde `404` y registra `ruta_invalida` | Pruebas del servicio con cinco variantes | ok |
| Ruta canónica fuera de la base responde `404` y registra `fuera_de_base` | Prueba unitaria de `dentroDeBase` por reflexión; caso con enlace omitido en Windows | parcial |
| Enlace simbólico fuera de la base no se sirve | Prueba omitida por limitación del entorno Windows | pendiente |
| Archivo ausente o no regular responde `404` y registra `archivo_ausente` | Pruebas del servicio | ok |
| MIME no permitido responde `404` con `nosniff` | Pruebas del servicio y cabeceras del controlador | ok |
| PDF real se sirve con `application/pdf`, `inline` y `recaudo-{id}.pdf` | Prueba de integración del controlador | ok |
| JPEG, PNG y WEBP se sirven con su MIME y extensión correctos | Pruebas del servicio con imágenes reales generadas con GD | ok |
| Extensión y nombre se derivan del MIME real | Prueba con PNG almacenado como `.txt` | ok |
| Respuesta `200` con todas las cabeceras exigidas | Prueba de integración del controlador | ok |
| Respuesta de error con cabeceras y cuerpo exacto | Prueba de integración del controlador | ok |
| Respuesta de error sin rutas, nombres, identificadores ni HTML | Prueba de integración del controlador | ok |
| `?descargar=1` sigue respondiendo `inline` | Prueba de integración con query string | ok |
| Rechazos registrados con identificadores y motivo | Revisión del servicio y del controlador; prueba de log de rechazo | ok |
| Accesos exitosos no se registran | Prueba que verifica el historial del `TestLogger` vacío | ok |
| `DatabaseException` responde `500` genérico sin trazas | Prueba con servicio espía que lanza la excepción | ok |
| Sin escrituras en base ni cambios en el archivo | Prueba de conteo de filas y hash del archivo | ok |
| Pruebas nuevas pasan | Servicio: 14 pruebas, 84 aserciones, 1 omitida. Controlador: 14 pruebas, 53 aserciones | ok |
| Regresiones pasan | `AdminPanelTest`, `PostulacionesAdminServiceTest`, `DetallePostulacionViewTest` | ok |
| `php -l` sin errores | Ruta, controlador y servicio | ok |
| Smoke test manual completo | No ejecutado en navegador por falta de datos reales; cubierto por pruebas automatizadas equivalentes | pendiente |
| Sin cambios en `Paso1`, pagos, vistas, filtro, SPA, API JWT ni Zelle | Revisión de archivos modificados | ok |
| `graphify update .` ejecutado | Comando ejecutado con advertencias preexistentes ajenas al cambio | ok |

## Flujos cubiertos

- **Flujo normal:** un administrador con `inscripciones_ni` solicita el recaudo; el controlador valida sesión, módulo y propiedad, el servicio detecta el MIME real y responde `200` con el archivo en línea. Verificado con PDF y con imágenes JPEG/PNG/WEBP.
- **Flujos alternativos:** PDF, JPEG, PNG, WEBP; extensión almacenada distinta del MIME real; `?descargar=1` ignorado; aperturas repetidas sin estado; auto-routing sin sesión o sin módulo.
- **Control de errores:** recaudo ajeno, inexistente o inactivo; `archivo_path` vacío o nulo; ruta con byte nulo, `..`, absoluta o unidad Windows; archivo ausente; MIME no permitido; fallo de lectura; error de base de datos; error inesperado. Todos responden sin revelar datos internos.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoService.php` | Resolvedor seguro de propiedad, ruta y MIME del recaudo. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoServiceTest.php` | Pruebas del servicio con base SQLite temporal y archivos reales. |
| `tests/app/Controllers/Admin/InscripcionesNuevoIngresoRecaudoTest.php` | Pruebas de integración del controlador, cabeceras, errores y auto-routing. |
| `docs/features/018-servir-recaudo-en-linea-panel-administrativo/prototipo.md` | Este documento. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Config/Routes.php` | Nueva ruta `GET` del recaudo dentro del grupo `admin/panel` con filtro de módulo. |
| `app/Controllers/Admin/InscripcionesNuevoIngreso.php` | Método `recaudo()`, verificación de sesión/módulo, respuestas `404`/`500`, registro de rechazos y punto de extensión del servicio. |
| `docs/features/018-servir-recaudo-en-linea-panel-administrativo/plan.md` | Estado actualizado a `en curso`. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)` con filtro `adminPanel:module=inscripciones_ni` dentro del grupo que aplica `csrf`.
- **Permisos y validaciones:** sesión `admin_user`; perfil con el módulo activo `inscripciones_ni`; validación de que el recaudo pertenece a la postulación y está activo; verificación canónica de la ruta y MIME real permitido.
- **Migraciones/seeds:** no aplica.
- **Compatibilidad:** no cambia contratos existentes. El enlace “Descargar” del detalle sigue mostrando el archivo en línea porque `?descargar=1` se ignora hasta el Slice 9.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php -l app/Config/Routes.php` | Sin errores de sintaxis. |
| `php -l app/Controllers/Admin/InscripcionesNuevoIngreso.php` | Sin errores de sintaxis. |
| `php -l app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoService.php` | Sin errores de sintaxis. |
| `vendor\bin\phpunit.bat tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoServiceTest.php --no-coverage` | 14 pruebas, 84 aserciones, 1 omitida. |
| `vendor\bin\phpunit.bat tests/app/Controllers/Admin/InscripcionesNuevoIngresoRecaudoTest.php --no-coverage` | 14 pruebas, 53 aserciones, todas correctas. |
| `vendor\bin\phpunit.bat tests/app/Filters/AdminPanelTest.php --no-coverage` | 9 pruebas, 23 aserciones, todas correctas. |
| `vendor\bin\phpunit.bat tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php --no-coverage` | 24 pruebas, 354 aserciones, todas correctas. |
| `vendor\bin\phpunit.bat tests/app/Views/Admin/DetallePostulacionViewTest.php --no-coverage` | 14 pruebas, 41 aserciones, todas correctas. |
| `graphify update .` | Grafo actualizado; advertencias preexistentes sobre SQL y vistas de error. |

## Verificación

- **Línea base (antes):** `AdminPanelTest` 9/9, `PostulacionesAdminServiceTest` 24/24 y `DetallePostulacionViewTest` 14/14, todos correctos.
- **Prueba manual (flujo normal):** no ejecutada en navegador por falta de datos reales; el flujo se reproduce en la prueba de integración que entrega un PDF y verifica cuerpo y cabeceras.
- **Flujos alternativos y errores:** cubiertos por las pruebas de servicio y controlador (tipos de archivo, rutas manipuladas, recaudo ajeno/inactivo/inexistente, archivo ausente, MIME no permitido, lectura fallida, errores de infraestructura y `?descargar=1`).
- **Pruebas automatizadas:** `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoServiceTest.php` y `tests/app/Controllers/Admin/InscripcionesNuevoIngresoRecaudoTest.php`.
- **Criterios del plan:** todos los funcionales y de seguridad quedaron verificados o cubiertos por pruebas, salvo el caso de enlace simbólico en Windows y el smoke test manual en navegador.

## Desviaciones del plan

- Se añadió el motivo de auditoría `acceso_denegado` para registrar los rechazos por sesión o módulo, porque la regla de defensa en profundidad exige registrar el intento y la lista de motivos del plan no incluía ese caso.
- Se añadió el método protegido `crearServicioRecaudoArchivo()` como punto de extensión para las pruebas; en producción usa el servicio por defecto.
- Se añadió una comprobación estricta de que `archivo_path` comience por `inscripciones-archivos/nuevo-ingreso/`, coherente con el formato real de `Paso1` y como defensa adicional.
- La prueba de la ruta se hace inspeccionando `app/Config/Routes.php` porque recargar el archivo de rutas durante PHPUnit intenta enviar cabeceras después de que el runner ya escribió. La denegación por sesión/módulo se respalda con `AdminPanelTest`.

## Riesgos y pendientes

- El caso de enlace simbólico fuera de la base no se ejecutó en este entorno Windows; conviene validarlo en Linux o en un entorno con permisos de enlace simbólico.
- No se auditan los accesos exitosos, tal como define el plan; queda como deuda de trazabilidad.
- No se verifica `archivo_hash`; un archivo alterado en disco con MIME permitido podría servirse. Queda como deuda técnica.
- `file_get_contents()` carga el archivo completo en memoria; se acepta por el límite de 10 MB de la carga, pero archivos heredados mayores podrían consumir memoria.
- `?descargar=1` se ignora hasta implementar la descarga adjunta del Slice 9.
- El smoke test manual en navegador queda pendiente por falta de datos reales y sesión administrativa en el entorno local.
