# Servir un recaudo digital en línea desde el panel administrativo

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

## Objetivo

Que un administrador autorizado con el módulo `inscripciones_ni` abra en el navegador el PDF o la imagen de un recaudo digital de una postulación de nuevo ingreso, sin exponer archivos de otras postulaciones, sin revelar rutas internas y sin ejecutar escrituras sobre la postulación, el recaudo o el archivo.

## Alcance

- **Incluye:**
  - Registrar `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)` dentro del grupo `admin/panel`, con el filtro `adminPanel:module=inscripciones_ni`.
  - Agregar el método público `recaudo(int $id, int $recaudoId)` al controlador existente `App\Controllers\Admin\InscripcionesNuevoIngreso`.
  - Crear el servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\RecaudoArchivoService` con el método `resolver(int $postulacionId, int $recaudoId, ?int $usuarioAdminId = null): ?array`.
  - Validar la propiedad del recaudo contra la base principal: la fila de `ni_inscripciones_recaudos` debe existir con `id = recaudoId`, `inscripcion_id = postulacionId` y `activo = 1`; además, la postulación debe existir en `ni_inscripciones`.
  - Rechazar `archivo_path` vacío, nulo, con byte nulo, con `..`, con ruta absoluta o con prefijo de unidad Windows.
  - Resolver la ruta física con `realpath()` y comprobar que permanezca dentro de `FCPATH . 'inscripciones-archivos/nuevo-ingreso'`, incluyendo el rechazo de enlaces simbólicos que apunten fuera de esa base.
  - Verificar que sea un archivo regular con `is_file()` y detectar el MIME real con `finfo` (`FILEINFO_MIME_TYPE`).
  - Permitir únicamente `application/pdf`, `image/jpeg`, `image/png` e `image/webp`.
  - Derivar la extensión del MIME real y construir el nombre de entrega `recaudo-{recaudoId}.{ext}`.
  - Responder `200` con `Content-Type`, `Content-Length`, `Content-Disposition: inline`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
  - Responder `404` con `Content-Type: text/plain; charset=UTF-8`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` y el cuerpo fijo `Recurso no encontrado.` ante cualquier fallo de resolución.
  - Agregar una verificación de sesión y módulo en el controlador como defensa en profundidad ante el auto-routing, sin sustituir el filtro `AdminPanel`.
  - Registrar únicamente los intentos rechazados, con los identificadores de postulación, recaudo y usuario administrativo y un código de motivo; nunca la ruta, el nombre del archivo, el hash ni datos personales.
  - Agregar pruebas unitarias del servicio con archivos temporales y pruebas de integración de la ruta y sus cabeceras.
  - Ejecutar como regresión `AdminPanelTest`, `PostulacionesAdminServiceTest` y las pruebas de vista del detalle.

- **No incluye:**
  - Implementar la descarga como archivo adjunto, el parámetro `?descargar=1`, el saneamiento de nombres de descarga o la cabecera `attachment`. Corresponden al Slice 9.
  - Endurecer ni modificar `Paso1::verArchivo()` del flujo del estudiante. Es un cambio separado.
  - Verificar la integridad del archivo contra `archivo_hash`. Se registra como deuda técnica.
  - Agregar límite de peticiones, cuotas, throttling o bloqueo por sesión. Se registra como deuda técnica.
  - Modificar `PostulacionesAdminService`, `NiInscripcionRecaudoModel`, el listado, la vista de detalle, el header, el helper `admin_access`, el login o el filtro `AdminPanel`.
  - Cambiar el almacenamiento de archivos, migraciones, seeds, rutas del estudiante, API JWT, SPA, panel Zelle o el flujo de pagos.
  - Convertir, comprimir, redimensionar o generar miniaturas de PDF o imágenes.
  - Aprobar, rechazar, marcar recibidos o modificar recaudos, postulaciones o pagos.
  - Agregar dependencias, helpers globales o variables de entorno nuevas.
  - Servir el comprobante Zelle u otros documentos fuera de `ni_inscripciones_recaudos`.

> **Evaluación de alcance:** el cambio cubre una sola capacidad de negocio: “entregar de forma segura el archivo de un recaudo de una postulación a un administrador autorizado”. La ruta, el controlador, el resolvedor y sus pruebas forman una unidad indivisible. La descarga adjunta (Slice 9) y el endurecimiento del endpoint del estudiante son cambios independientes y quedan documentados fuera de este alcance. No se detectó necesidad de dividir este cambio.

## Contexto y supuestos

- El cambio corresponde al **Slice 8** de `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`.
- El segundo parámetro de la ruta es `ni_inscripciones_recaudos.id`, no `ni_recaudos.id`. El `recaudo_id` del catálogo no se usa para resolver el archivo.
- `ni_inscripciones`, `ni_inscripciones_recaudos` y `ni_recaudos` viven en la conexión principal `default`.
- `archivo_path` se guarda como ruta relativa a `FCPATH`, por ejemplo `inscripciones-archivos/nuevo-ingreso/26/10/abc123.pdf`. La base de entrega es `FCPATH . 'inscripciones-archivos/nuevo-ingreso'`.
- La carga de recaudos en `Paso1` ya limita el tamaño a 10 MB y acepta PDF, JPG, JPEG, PNG y WEBP. Este cambio no altera esa validación.
- El detalle de FEAT-017 ya genera el enlace “Ver” hacia esta ruta y el enlace “Descargar” con `?descargar=1`. En este cambio el parámetro se ignora y la respuesta siempre es `inline`; el botón “Descargar” seguirá mostrando el archivo en el navegador hasta implementar el Slice 9.
- La visualización exitosa **no** se registra; solo se registran los rechazos. Es una decisión de la entrevista y reduce la trazabilidad de accesos exitosos; se anota como deuda.
- Un fallo de resolución del recaudo (no existe, ajeno, inactivo, sin archivo, ruta inválida, archivo ausente o MIME no permitido) responde `404` genérico. Un `DatabaseException` responde `500` con texto genérico y se registra, para no ocultar una caída de infraestructura; se interpreta así la regla “404 si algo falla” referida a la resolución del recurso.
- `finfo` es requisito del entorno. Si no está disponible, la entrega se rechaza de forma cerrada con `404`.
- El proyecto usa `setAutoRoute(true)` y el método será público para que el router pueda invocarlo. Por eso el controlador valida sesión y módulo antes de resolver el archivo; esta verificación es defensa en profundidad y el filtro `adminPanel:module=inscripciones_ni` sigue siendo la autorización principal.
- La sesión `admin_user` guarda el perfil en `perfil_id` (singular), según `PanelAuth`. La verificación del controlador usa esa clave.
- Se replica el patrón seguro de `Panel::comprobante()` y `PagosZelleServices::resolverComprobanteParaEntrega()` sin acoplar el nuevo servicio a la librería de pagos.
- El esquema documental del proyecto es `FEAT-NNN`. El siguiente número libre es `FEAT-018`, verificado contra `docs/features/`. El directorio usa el patrón `018-<slug-en-kebab-case>`.
- La rama de trabajo es `feature/panel-administrativo-documentos-ni`.
- La suite completa tiene un fallo preexistente ajeno a este cambio; se ejecutan las pruebas del área afectada y un smoke test manual.
- No se requieren dependencias nuevas ni cambios de esquema.

## Flujo normal

1. Paso 1: Un administrador autorizado con el módulo `inscripciones_ni` abre el detalle de una postulación.
2. Paso 2: La tabla de recaudos muestra el enlace “Ver” solo para los recaudos con `disponible === true`.
3. Paso 3: El administrador pulsa “Ver”; el navegador solicita `GET admin/panel/inscripciones-nuevo-ingreso/{id}/recaudo/{recaudoId}` en una pestaña nueva.
4. Paso 4: El filtro `adminPanel:module=inscripciones_ni` valida la sesión `admin_user`, el usuario activo, el módulo y la asignación del perfil.
5. Paso 5: `InscripcionesNuevoIngreso::recaudo($id, $recaudoId)` normaliza ambos valores a enteros mayores o iguales a `0`.
6. Paso 6: El controlador verifica que exista `admin_user` y que su perfil tenga el módulo `inscripciones_ni`; si falla, responde `404` genérico y registra el intento.
7. Paso 7: El controlador llama a `RecaudoArchivoService::resolver($id, $recaudoId, $adminId)`.
8. Paso 8: El servicio valida que la postulación exista y que el recaudo pertenezca a ella, esté activo y tenga `archivo_path` informado; si no, registra el motivo y devuelve `null`.
9. Paso 9: El servicio rechaza rutas vacías, con byte nulo, con `..`, absolutas o con prefijo de unidad Windows; registra el motivo y devuelve `null`.
10. Paso 10: El servicio construye la ruta física, aplica `realpath()` y comprueba que esté dentro de la base de recaudos; rechaza enlaces simbólicos o rutas fuera de la base.
11. Paso 11: El servicio comprueba `is_file()` y detecta el MIME real con `finfo`.
12. Paso 12: Si el MIME no está en la lista permitida, registra el motivo y devuelve `null`.
13. Paso 13: El servicio deriva la extensión del MIME, calcula el tamaño y devuelve `ruta`, `mime`, `nombre` y `bytes`.
14. Paso 14: El controlador lee el contenido del archivo resuelto y construye la respuesta `200` con las cabeceras de entrega segura.
15. Paso 15: El navegador renderiza el PDF o la imagen en línea en la pestaña nueva, sin descargar automáticamente y sin mostrar rutas internas.
16. Paso 16: La operación no modifica la base de datos, no borra el archivo y no altera la sesión administrativa.

## Flujos alternativos / variantes

### Recaudo PDF

1. Paso 1: El archivo real es `application/pdf`.
2. Paso 2: El servicio deriva la extensión `pdf` y el nombre `recaudo-{recaudoId}.pdf`.
3. Paso 3: El controlador responde `Content-Type: application/pdf` e `inline`.
4. Paso 4: El visor de PDF del navegador muestra el documento.

### Recaudo JPEG, PNG o WEBP

1. Paso 1: El archivo real es `image/jpeg`, `image/png` o `image/webp`.
2. Paso 2: El servicio deriva `jpg`, `png` o `webp` y el nombre correspondiente.
3. Paso 3: El controlador responde con el MIME real e `inline`.
4. Paso 4: El navegador muestra la imagen en la pestaña nueva.

### Extensión almacenada distinta del MIME real

1. Paso 1: El archivo se guardó con extensión `.txt` o `.bin`, pero su contenido real es un PDF o una imagen permitida.
2. Paso 2: El servicio ignora la extensión almacenada y usa el MIME real.
3. Paso 3: La extensión y el nombre de entrega se derivan del MIME real.
4. Paso 4: La respuesta es válida si el MIME está permitido.

### Parámetro `?descargar=1` presente

1. Paso 1: El administrador pulsa “Descargar” y el navegador solicita la misma ruta con `?descargar=1`.
2. Paso 2: El controlador ignora el parámetro en este cambio.
3. Paso 3: La respuesta sigue siendo `inline` con el mismo contenido.
4. Paso 4: El navegador muestra el archivo; la descarga adjunta queda pendiente para el Slice 9.

### Recaudo de otra postulación

1. Paso 1: El administrador manipula la URL y usa el `id` de una postulación con el `recaudoId` de otra.
2. Paso 2: La consulta de propiedad no encuentra una fila con ambos identificadores.
3. Paso 3: El servicio registra `recaudo_no_disponible` y devuelve `null`.
4. Paso 4: El controlador responde `404` genérico sin revelar si el recaudo existe en otra postulación.

### Recaudo inactivo o sin archivo

1. Paso 1: La fila existe pero `activo <> 1` o `archivo_path` está vacío o es nulo.
2. Paso 2: La consulta de propiedad no devuelve una fila válida o el servicio detecta la ruta vacía.
3. Paso 3: El servicio registra el motivo y devuelve `null`.
4. Paso 4: El controlador responde `404` genérico.

### Archivo ausente en disco

1. Paso 1: La fila y la ruta son válidas, pero `realpath()` no resuelve el archivo o `is_file()` es falso.
2. Paso 2: El servicio registra `archivo_ausente` y devuelve `null`.
3. Paso 3: El controlador responde `404` genérico.
4. Paso 4: No se intenta leer ni se devuelve contenido parcial.

### Ruta manipulada en la base

1. Paso 1: `archivo_path` contiene `..`, un byte nulo, una ruta absoluta o un prefijo de unidad Windows.
2. Paso 2: El servicio rechaza el valor antes de construir la ruta física.
3. Paso 3: Registra `ruta_invalida` y devuelve `null`.
4. Paso 4: El controlador responde `404` genérico sin incluir el valor recibido.

### Ruta fuera de la base o enlace simbólico

1. Paso 1: `realpath()` resuelve a un archivo que no está dentro de `FCPATH . 'inscripciones-archivos/nuevo-ingreso'`.
2. Paso 2: El servicio compara la ruta canónica con la base canónica, con separadores normalizados.
3. Paso 3: Registra `fuera_de_base` y devuelve `null`.
4. Paso 4: El controlador responde `404` genérico.

### MIME no permitido

1. Paso 1: El archivo existe y está dentro de la base, pero su contenido real es HTML, SVG, un ejecutable u otro tipo no permitido.
2. Paso 2: `finfo` devuelve un MIME fuera de la lista permitida.
3. Paso 3: El servicio registra `mime_no_permitido` y devuelve `null`.
4. Paso 4: El controlador responde `404` genérico con `nosniff`, sin ejecutar ni mostrar el contenido.

### Acceso directo por auto-routing

1. Paso 1: Una petición intenta llegar al método público sin el prefijo `admin/panel`, por la URI de auto-routing.
2. Paso 2: El controlador ejecuta su verificación de sesión y módulo.
3. Paso 3: Si no hay `admin_user` o el perfil no tiene `inscripciones_ni`, responde `404` genérico y registra el intento.
4. Paso 4: No se resuelve, lee ni entrega ningún archivo.

### Sesión expirada o permiso revocado

1. Paso 1: El administrador tenía el detalle abierto y su sesión expira o pierde el módulo.
2. Paso 2: Al pulsar “Ver”, el filtro `AdminPanel` deniega y redirige a `admin/panel/login`.
3. Paso 3: No se ejecuta el controlador ni se sirve el archivo.
4. Paso 4: La pestaña nueva muestra el formulario de acceso.

### Identificadores inválidos

1. Paso 1: La URL contiene un `id` o un `recaudoId` igual a `0`, negativo o no numérico.
2. Paso 2: La ruta `(:num)` no coincide con negativos ni con texto; CodeIgniter responde `404` antes del controlador.
3. Paso 3: Si el método recibe `0`, el controlador responde `404` genérico sin consultar la base.
4. Paso 4: No se registra información sensible.

### Varias pestañas o aperturas repetidas

1. Paso 1: El administrador abre el mismo recaudo varias veces.
2. Paso 2: Cada petición vuelve a validar sesión, módulo, propiedad, ruta y MIME.
3. Paso 3: No se crea estado ni se escribe en base de datos.
4. Paso 4: Todas las respuestas válidas son equivalentes.

## 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 eliminado o inactivo | Consulta de `AdminPanel` sin resultado o con `borrado_dt` | Redirige al login y limpia `admin_user` | Acceso denegado |
| Módulo `inscripciones_ni` inexistente o borrado | Consulta de `AdminPanel` sin resultado | Redirige al login con `admin_error` | Acceso denegado |
| Perfil sin asignación activa del módulo | Consulta de `AdminPanel` sin asignación activa | Redirige al login y limpia `admin_user` | Acceso denegado |
| Permiso revocado durante la sesión | La siguiente petición es evaluada por `AdminPanel` | Deniega el acceso y limpia la sesión | El usuario debe volver a autenticarse |
| Acceso por auto-routing sin sesión o sin módulo | Verificación del controlador | `404` genérico y registro del intento | Sin resolución ni lectura |
| `id` o `recaudoId` igual a `0` | Validación del controlador | `404` genérico sin consultar la base | Sin detalle |
| `id` o `recaudoId` no numérico o negativo | La ruta `(:num)` no coincide | CodeIgniter responde `404` antes del controlador | Recurso no encontrado |
| Postulación inexistente | Consulta de existencia sin resultado | `404` genérico y log | Sin entrega |
| Recaudo inexistente, ajeno o inactivo | Consulta de propiedad sin fila válida | `404` genérico y log `recaudo_no_disponible` | Sin entrega |
| `archivo_path` vacío o nulo | Validación del servicio tras la consulta | `404` genérico y log `recaudo_sin_archivo` | Sin entrega |
| Ruta con byte nulo, `..`, absoluta o prefijo de unidad | Validación del servicio | `404` genérico y log `ruta_invalida` | Sin entrega |
| `realpath()` de la base o del archivo falla | `realpath()` devuelve `false` | `404` genérico y log `archivo_ausente` o `base_invalida` | Sin entrega |
| Ruta canónica fuera de la base | Comparación de prefijos normalizados | `404` genérico y log `fuera_de_base` | Sin entrega |
| Archivo ausente o no regular | `is_file()` falso | `404` genérico y log `archivo_ausente` | Sin entrega |
| `finfo` no disponible o falla | `finfo_open()` falso o `finfo_file()` no devuelve cadena | `404` genérico y log `mime_no_detectado` | Sin entrega |
| MIME real no permitido | Lista de MIME permitidos | `404` genérico con `nosniff` y log `mime_no_permitido` | Sin entrega |
| `filesize()` o `file_get_contents()` falla | Retorno falso | `404` genérico y log `lectura_fallida` | Sin entrega |
| `DatabaseException` al consultar | Captura en el controlador | `500` con texto genérico y log del error | Error visible sin datos internos |
| Error inesperado del resolvedor | Captura defensiva en el controlador | `500` con texto genérico y log | Error visible sin datos internos |
| Petición con `?descargar=1` | Parámetro presente | Se ignora; la respuesta sigue siendo `inline` | Comportamiento temporal hasta Slice 9 |
| Datos con HTML en la ruta o en el nombre | No se interpolan en la respuesta; el nombre se deriva del MIME y del `id` | Solo se devuelven cabeceras controladas | Sin ejecución de HTML ni inyección de cabeceras |

## Reglas de negocio y validaciones

1. **Autorización primaria:** la ruta debe declararse dentro del grupo `admin/panel` con el filtro `adminPanel:module=inscripciones_ni`. No se permite una ruta de entrega sin filtro.
2. **Defensa en profundidad:** el controlador verifica que exista `admin_user` y que su perfil tenga el módulo `inscripciones_ni` antes de resolver el archivo. Si la verificación falla, responde `404` genérico y registra el intento. Esta comprobación no reemplaza al filtro.
3. **Identidad desde la sesión:** el `usuarioAdminId` para el log sale de `admin_user['id']`. El único dato de la petición que se usa para resolver el recurso son los dos identificadores de la ruta.
4. **Propiedad del recaudo:** la fila debe existir en `ni_inscripciones_recaudos` con `id = recaudoId`, `inscripcion_id = postulacionId` y `activo = 1`. Además, la postulación debe existir en `ni_inscripciones`.
5. **Sin confianza en el cliente:** no se aceptan rutas, nombres de archivo, MIME, `archivo_path`, `archivo_hash` ni identificadores de catálogo enviados por query string o por el cuerpo. Solo se usan los dos enteros de la ruta.
6. **Base fija:** la base de entrega es `FCPATH . 'inscripciones-archivos/nuevo-ingreso'`. No se lee de variables de entorno ni de configuración de la petición. El servicio permite inyectar la base solo para pruebas.
7. **Rutas prohibidas:** se rechaza cualquier `archivo_path` vacío, nulo, con byte nulo, con `..`, con barra inicial o con prefijo de unidad Windows.
8. **Ruta canónica:** se aplica `realpath()` a la base y al archivo. La ruta canónica del archivo debe comenzar por la ruta canónica de la base más un separador. Los separadores se normalizan a `/` antes de comparar.
9. **Enlaces simbólicos:** al usar `realpath()`, un enlace que resuelva fuera de la base se rechaza. No se sirve el destino del enlace si está fuera.
10. **MIME real:** se usa `finfo` con `FILEINFO_MIME_TYPE`. La extensión almacenada no decide el tipo. Los únicos MIME permitidos son `application/pdf`, `image/jpeg`, `image/png` e `image/webp`.
11. **Nombre de entrega:** se construye como `recaudo-{recaudoId}.{ext}`, con la extensión derivada del MIME (`pdf`, `jpg`, `png`, `webp`). No se usa el nombre original, el nombre aleatorio del disco ni datos del aspirante.
12. **Respuesta exitosa:** `200` con `Content-Type` del MIME real, `Content-Length` en bytes, `Content-Disposition: inline; filename="recaudo-{id}.{ext}"`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
13. **Respuesta fallida:** `404` con `Content-Type: text/plain; charset=UTF-8`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` y el cuerpo exacto `Recurso no encontrado.`. No se incluye HTML, ruta, nombre de archivo, identificadores ni detalle del motivo.
14. **Descarga:** `?descargar=1` se ignora en este cambio. No se envía `Content-Disposition: attachment` ni se sanea un nombre de descarga. Esa responsabilidad pertenece al Slice 9.
15. **Sin escrituras:** no se ejecutan `INSERT`, `UPDATE`, `DELETE` ni DDL. No se borra, mueve, renombra ni modifica el archivo. No se actualiza ningún contador de accesos.
16. **Auditoría:** solo se registran los rechazos, con `inscripcion_id`, `recaudo_id`, `admin_id` y un código de motivo (`recaudo_no_disponible`, `recaudo_sin_archivo`, `ruta_invalida`, `fuera_de_base`, `archivo_ausente`, `mime_no_detectado`, `mime_no_permitido`, `lectura_fallida`, `base_invalida`). Nunca se registra la ruta, el nombre, el hash, el contenido ni datos personales. Los accesos exitosos no se registran.
17. **Errores de infraestructura:** un `DatabaseException` o un error inesperado se registra y se responde `500` con un texto genérico. No se devuelven trazas, SQL, rutas ni detalles internos.
18. **Lectura del archivo:** se usa `file_get_contents()` y `filesize()` después de resolver la ruta. Si cualquiera devuelve `false`, se trata como `lectura_fallida` y se responde `404`. Los archivos de recaudos están limitados a 10 MB en la carga; no se agrega un límite adicional en la entrega.
19. **Sin caché reutilizable:** la respuesta `200` usa `private, max-age=0, must-revalidate`; la respuesta `404` usa `no-store`. No se usa caché pública ni se comparte el archivo entre sesiones.
20. **Auto-routing:** el método debe ser público para que el router lo invoque. La verificación de sesión y módulo del controlador evita que una URI de auto-routing entregue archivos. No se desactiva `setAutoRoute` en este cambio.
21. **Compatibilidad:** no se modifica la firma ni el comportamiento de `PostulacionesAdminService`, `NiInscripcionRecaudoModel`, el listado, el detalle, el filtro `AdminPanel`, el header, el login, el panel Zelle, la API JWT ni el flujo del estudiante.
22. **Idioma y estilo:** comentarios, docblocks y mensajes nuevos en español, siguiendo las convenciones de `AGENTS.md`.
23. **Sin dependencias nuevas:** no se agregan librerías, paquetes, helpers globales ni variables de entorno.

## Áreas afectadas

- `app/Config/Routes.php`: nueva ruta `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)`, después de la ruta de detalle, con el filtro `adminPanel:module=inscripciones_ni`.
- `app/Controllers/Admin/InscripcionesNuevoIngreso.php`: nuevo método público `recaudo(int $id, int $recaudoId)` y utilidades privadas para la verificación de sesión/módulo, la respuesta `404` genérica y el manejo de errores. Sin SQL propio.
- `app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoService.php`: nuevo servicio con `resolver()`, validación de propiedad, resolución segura de ruta, detección de MIME, lista permitida y registro de rechazos. Constructor con inyección opcional de `BaseConnection`, `NiInscripcionRecaudoModel` y ruta base para pruebas.
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoServiceTest.php`: nuevo. Cubre propiedad, postulación inexistente, recaudo inactivo, ruta vacía, `..`, ruta absoluta, prefijo Windows, archivo ausente, ruta fuera de base, PDF/JPEG/PNG/WEBP válidos, MIME no permitido, extensión distinta del MIME, nombre derivado, tamaño y ausencia de escrituras.
- `tests/app/Controllers/Admin/InscripcionesNuevoIngresoRecaudoTest.php`: nuevo. Cubre la respuesta `200` y sus cabeceras, el `404` genérico, el `404` para recaudo ajeno o inexistente, la redirección sin sesión, la denegación sin módulo, la ignorancia de `?descargar=1` y el acceso por auto-routing sin sesión o sin módulo.
- `tests/app/Filters/AdminPanelTest.php`: ejecutar como regresión; no se requieren cambios.
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php`: ejecutar como regresión; no se requieren cambios.
- `tests/app/Views/Admin/DetallePostulacionViewTest.php`: ejecutar como regresión del enlace “Ver”; no se requieren cambios.
- `docs/features/018-servir-recaudo-en-linea-panel-administrativo/plan.md`: este documento.
- `MEMORY.md`: solo si al cerrar el cambio se altera el estado o una decisión documentada del proyecto.

No se modifican `PostulacionesAdminService.php`, `NiInscripcionRecaudoModel.php`, `Paso1.php`, `PagosZelleServices.php`, `Panel.php`, `PanelAuth.php`, las vistas del detalle o del listado, el header, el helper `admin_access`, migraciones, seeds, la SPA, la API JWT, `vendor/`, `public/vendor/`, `system/` ni `app/ThirdParty/`.

## Criterios de finalización

- [ ] La ruta `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)` existe dentro del grupo `admin/panel` y usa el filtro `adminPanel:module=inscripciones_ni`.
- [ ] El método `InscripcionesNuevoIngreso::recaudo(int $id, int $recaudoId)` existe, es público y delega la resolución en `RecaudoArchivoService::resolver()`.
- [ ] El controlador no contiene SQL propio para postulaciones ni recaudos.
- [ ] El controlador verifica `admin_user` y el módulo `inscripciones_ni` antes de resolver el archivo.
- [ ] Una petición sin sesión a la ruta filtrada redirige a `admin/panel/login` con `admin_error` y no ejecuta el controlador.
- [ ] Una petición con un perfil sin `inscripciones_ni` redirige al login y no sirve el archivo.
- [ ] Una petición por auto-routing sin sesión o sin módulo responde `404` genérico y no sirve el archivo.
- [ ] Un `id` o un `recaudoId` igual a `0` responde `404` genérico sin consultar la base.
- [ ] Un recaudo de otra postulación responde `404` genérico y registra `recaudo_no_disponible`.
- [ ] Un recaudo inexistente o inactivo responde `404` genérico y no revela si existe.
- [ ] Un recaudo con `archivo_path` vacío o nulo responde `404` genérico y registra `recaudo_sin_archivo`.
- [ ] Un `archivo_path` con byte nulo, `..`, ruta absoluta o prefijo de unidad Windows responde `404` genérico y registra `ruta_invalida`.
- [ ] Un archivo que resuelve fuera de `FCPATH . 'inscripciones-archivos/nuevo-ingreso'` responde `404` genérico y registra `fuera_de_base`.
- [ ] Un enlace simbólico que apunta fuera de la base no se sirve.
- [ ] Un archivo ausente o no regular responde `404` genérico y registra `archivo_ausente`.
- [ ] Un archivo con MIME no permitido responde `404` genérico con `nosniff` y registra `mime_no_permitido`.
- [ ] Un PDF real se sirve con `application/pdf`, `inline` y el nombre `recaudo-{recaudoId}.pdf`.
- [ ] Un JPEG, PNG o WEBP real se sirve con su MIME correspondiente y la extensión derivada correcta.
- [ ] La extensión y el nombre de entrega se derivan del MIME real, no de la extensión almacenada ni del nombre en disco.
- [ ] La respuesta `200` incluye `Content-Type`, `Content-Length`, `Content-Disposition: inline`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
- [ ] La respuesta de error es `404` con `Content-Type: text/plain; charset=UTF-8`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` y el cuerpo exacto `Recurso no encontrado.`.
- [ ] La respuesta de error no contiene rutas internas, nombres de archivo, identificadores, HTML ni el motivo del rechazo.
- [ ] Una petición con `?descargar=1` sigue respondiendo `inline` y no envía `Content-Disposition: attachment`.
- [ ] Los rechazos se registran con `inscripcion_id`, `recaudo_id`, `admin_id` y un código de motivo, sin rutas ni datos personales.
- [ ] Los accesos exitosos no se registran.
- [ ] Un `DatabaseException` se registra y responde `500` con texto genérico, sin trazas ni SQL.
- [ ] No se ejecutan escrituras en base de datos ni se modifica, borra o mueve el archivo.
- [ ] Las pruebas nuevas del servicio y de la ruta pasan.
- [ ] Las pruebas de `AdminPanelTest`, `PostulacionesAdminServiceTest` y `DetallePostulacionViewTest` pasan como regresión.
- [ ] Se ejecuta `php -l` sobre el controlador, el servicio y la ruta sin errores de sintaxis.
- [ ] Se completa el smoke test manual: “Ver” de un PDF, “Ver” de una imagen, recaudo ajeno, recaudo inexistente, recaudo inactivo, archivo ausente, ruta manipulada, recaudo con MIME no permitido, `?descargar=1`, sesión cerrada y acceso directo por auto-routing.
- [ ] No se modificaron `Paso1::verArchivo()`, la librería de pagos, las vistas, el filtro `AdminPanel`, la SPA, la API JWT ni el panel Zelle.
- [ ] Se ejecuta `graphify update .` después de los cambios de código.

## Riesgos

- **Alto:** exposición de archivos y path traversal. Se mitiga con la validación de propiedad en base, el rechazo de rutas sospechosas, `realpath()` contra una base canónica, `nosniff`, MIME real permitido y una respuesta `404` genérica sin detalles. Cualquier fallo de estas validaciones debe considerarse bloqueante.
- **Alto:** auto-routing activo sobre un método público. Se mitiga con la verificación de sesión y módulo en el controlador, además del filtro de ruta. El smoke test debe incluir el acceso directo sin el prefijo `admin/panel`. Si se detecta una entrega sin autorización, el cambio no se cierra y se propone un ajuste separado de auto-routing.
- **Medio:** la decisión de no auditar los accesos exitosos reduce la trazabilidad. Se registra como deuda técnica para una revisión de seguridad posterior.
- **Medio:** no se verifica `archivo_hash`. Un archivo alterado en disco con un MIME permitido podría servirse. Se registra como deuda técnica.
- **Medio:** `file_get_contents()` carga el archivo completo en memoria. Los recaudos se limitan a 10 MB en la carga, pero archivos heredados podrían ser mayores. Se acepta por ahora y se evaluará un streaming o un límite explícito en un cambio posterior.
- **Bajo:** el botón “Descargar” del detalle seguirá mostrando el archivo en línea hasta implementar el Slice 9. Es una condición funcional conocida y documentada.
- **Bajo:** el parámetro `?descargar=1` se ignora silenciosamente. Se documenta para no presentar la descarga como operativa.
- **Bajo:** `finfo` podría no estar disponible en un entorno mal configurado. La entrega falla de forma cerrada con `404`; el smoke test debe confirmar que la extensión está disponible.
- **Bajo:** diferencias de mayúsculas y separadores entre Windows y Linux. Se normalizan los separadores y se prueban ambos escenarios en la medida de lo posible.
- **Bajo:** la suite completa tiene un fallo preexistente; se ejecutan las pruebas del área y un smoke test manual.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial del endpoint administrativo para servir recaudos en línea de forma segura. Se define el resolvedor, la validación de propiedad y ruta, la lista de MIME permitidos, las cabeceras, la respuesta `404` genérica, la defensa ante auto-routing, la auditoría solo de rechazos y las pruebas. Se excluyen la descarga adjunta (Slice 9), el endurecimiento del endpoint del estudiante, la verificación de hash y el rate limiting. | opencode (agente) |
| 2026-10-30 | Consolidado en `feature/panel-administrativo-documentos-ni` mediante merge `--no-ff` (`b95ea0f`, `8c4f709`). El usuario aceptó los pendientes de smoke test manual y prueba de enlace simbólico en Windows, cubiertos por pruebas automatizadas. | opencode (agente) |
