# Forzar la descarga segura de un recaudo desde el panel administrativo

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

## Objetivo

Que un administrador autorizado con el módulo `inscripciones_ni` descargue como archivo adjunto el PDF o la imagen de un recaudo digital de una postulación de nuevo ingreso, con un nombre derivado del recaudo y saneado, manteniendo intactas las validaciones de propiedad, ruta y MIME del endpoint existente y sin alterar la visualización en línea.

## Alcance

- **Incluye:**
  - Interpretar `?descargar=1` en el endpoint existente `GET admin/panel/inscripciones-nuevo-ingreso/(:num)/recaudo/(:num)`.
  - Enviar `Content-Disposition: attachment` cuando el parámetro valga exactamente `1`.
  - Construir el nombre de descarga a partir del nombre ya resuelto por `RecaudoArchivoService` (`recaudo-{recaudoId}.{ext}`), con la extensión derivada del MIME real.
  - Saneamiento del nombre de descarga: eliminar CR, LF, comillas dobles, barra invertida, barra inclinada, punto y coma, caracteres de control y caracteres no ASCII del valor de `filename`.
  - Emitir `filename*=UTF-8''...` con codificación porcentual RFC 5987 únicamente cuando el nombre saneado requiera caracteres no ASCII.
  - Fallback al nombre `recaudo-{recaudoId}.{ext}` si el saneamiento dejara el nombre vacío o inválido.
  - Mantener `Content-Type` del MIME real, `Content-Length`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
  - Mantener sin cambios las validaciones de sesión, módulo, propiedad del recaudo, ruta canónica, existencia y MIME real.
  - Ajustar el enlace "Descargar" de la vista de detalle para que la descarga ocurra en la misma pestaña; el enlace "Ver" conserva `target="_blank"`.
  - Actualizar las pruebas del controlador y de la vista, y agregar pruebas del saneamiento del nombre.
  - Ejecutar como regresión las pruebas del servicio de recaudos, `AdminPanelTest`, `PostulacionesAdminServiceTest` y `DetallePostulacionViewTest`.
- **No incluye:**
  - Cambiar la ruta, el resolvedor `RecaudoArchivoService`, la validación de propiedad, la base canónica de archivos ni la lista de MIME permitidos. Permanecen igual que en FEAT-018.
  - Modificar la respuesta `inline` existente ni su cabecera `Content-Disposition`.
  - Descargar cualquier archivo distinto de los recaudos de `ni_inscripciones_recaudos` (comprobantes Zelle, documentos del flujo del estudiante, etc.).
  - Auditar descargas exitosas o visualizaciones exitosas. Solo se mantiene el registro de rechazos de FEAT-018.
  - Agregar límite de peticiones, cuotas, throttling o bloqueo por sesión.
  - Verificar la integridad del archivo contra `archivo_hash`.
  - Convertir, comprimir, redimensionar o generar miniaturas.
  - Cambiar el almacenamiento, migraciones, seeds, API JWT, SPA, panel Zelle, pagos o el flujo del estudiante.
  - Agregar dependencias, helpers globales, variables de entorno ni cambios de esquema.
  - Endurecer `Paso1::verArchivo()` del flujo del estudiante.

> **Evaluación de alcance:** el cambio cubre una sola capacidad de negocio: "entregar el mismo recaudo ya autorizado como archivo adjunto cuando el administrador lo solicite". Extiende el contrato del endpoint de FEAT-018, reutiliza su resolvedor y agrega saneamiento de cabecera y un ajuste de enlace. No mezcla módulos ni actores independientes. **No se detectó necesidad de dividir este cambio.**

## Contexto y supuestos

- El cambio corresponde al **Slice 9** de `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md` y depende de FEAT-018 (Slice 8), ya consolidado en la rama `feature/panel-administrativo-documentos-ni`.
- FEAT-018 ya expone la ruta, el controlador `App\Controllers\Admin\InscripcionesNuevoIngreso::recaudo()` y el servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\RecaudoArchivoService::resolver()`.
- El servicio devuelve `ruta`, `mime`, `nombre` y `bytes`; el nombre ya es `recaudo-{recaudoId}.{ext}` y la extensión se deriva del MIME real. Este cambio consume ese contrato y no lo modifica.
- La vista de detalle ya genera `$urlDescargar = $urlVer . '?descargar=1'` y hoy la abre con `target="_blank"`. En este cambio se quita `target` y `rel` del enlace "Descargar"; "Ver" no cambia.
- El parámetro se interpreta con comparación estricta contra la cadena `'1'`. Un valor ausente, vacío, `0`, `true`, `yes` o un arreglo mantiene la respuesta `inline` para un recurso válido.
- El saneamiento es defensa en profundidad: el nombre real proviene de datos controlados (id entero y extensión derivada del MIME), nunca de la URL, del nombre físico del disco ni de datos del aspirante.
- El nombre derivado actual es siempre ASCII, por lo que `filename*=UTF-8''...` no se emitirá en la operación normal; queda implementado para nombres futuros con caracteres no ASCII.
- Las respuestas de error conservan el `404` genérico y el `500` genérico de FEAT-018, sin `Content-Disposition: attachment`.
- El esquema documental del proyecto es `FEAT-NNN`. El siguiente número libre es `FEAT-019`, verificado contra `docs/features/`. El directorio usa el patrón `019-<slug-en-kebab-case>`.
- No se requieren dependencias nuevas ni cambios de esquema.
- La suite completa tiene un fallo preexistente ajeno a este cambio; se ejecutan las pruebas del área afectada y un smoke test manual.
- El smoke test manual en navegador puede quedar pendiente por falta de una sesión administrativa real y de recaudos de prueba en la base principal, igual que en FEAT-018.

## Flujo normal

### Descarga adjunta

1. Paso 1: Un administrador autorizado con el módulo `inscripciones_ni` abre el detalle de una postulación con al menos un recaudo disponible.
2. Paso 2: La tabla de recaudos muestra los enlaces "Ver" y "Descargar" solo para los recaudos con `disponible === true`.
3. Paso 3: El administrador pulsa "Descargar"; el navegador solicita `GET admin/panel/inscripciones-nuevo-ingreso/{id}/recaudo/{recaudoId}?descargar=1` en la misma pestaña.
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 identificadores y aplica la verificación de sesión y módulo como defensa en profundidad.
6. Paso 6: El controlador delega la resolución en `RecaudoArchivoService::resolver($id, $recaudoId, $adminId)`.
7. Paso 7: El servicio valida postulación, propiedad del recaudo, `activo`, ruta relativa, base canónica, existencia, MIME real permitido y tamaño, exactamente como en FEAT-018.
8. Paso 8: El controlador comprueba que `?descargar` sea exactamente la cadena `'1'`.
9. Paso 9: El controlador toma el nombre resuelto `recaudo-{recaudoId}.{ext}`, le aplica el saneamiento y arma `Content-Disposition: attachment; filename="..."`, agregando `filename*=UTF-8''...` solo si el nombre saneado contiene caracteres no ASCII.
10. Paso 10: El controlador responde `200` con `Content-Type` del MIME real, `Content-Length`, `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
11. Paso 11: El navegador descarga el archivo con el nombre `recaudo-{recaudoId}.{ext}` sin navegar fuera del panel y sin mostrar rutas internas.
12. Paso 12: La operación no escribe en base de datos, no modifica el archivo ni altera la sesión administrativa.

### Visualización en línea (sin regresión)

1. Paso 1: El administrador pulsa "Ver" y el navegador solicita la misma ruta sin `?descargar=1`, en una pestaña nueva.
2. Paso 2: Se ejecutan el filtro, la verificación de sesión/módulo y la resolución del servicio con las mismas validaciones.
3. Paso 3: Al no existir `descargar=1`, el controlador responde exactamente como en FEAT-018: `200` con `Content-Disposition: inline; filename="recaudo-{recaudoId}.{ext}"`.
4. Paso 4: El navegador muestra el PDF o la imagen en línea.

## Flujos alternativos / variantes

### Descarga de PDF

1. Paso 1: El archivo real es `application/pdf`.
2. Paso 2: El servicio devuelve `nombre = recaudo-{recaudoId}.pdf`.
3. Paso 3: El controlador responde `Content-Type: application/pdf` y `Content-Disposition: attachment; filename="recaudo-{recaudoId}.pdf"`.
4. Paso 4: El navegador descarga el PDF con el nombre indicado.

### Descarga de JPEG, PNG o WEBP

1. Paso 1: El archivo real es `image/jpeg`, `image/png` o `image/webp`.
2. Paso 2: El servicio devuelve la extensión `jpg`, `png` o `webp`.
3. Paso 3: El controlador responde con el MIME real y `attachment` con el nombre correspondiente.
4. Paso 4: El navegador descarga la imagen.

### 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 deriva el nombre del MIME real.
3. Paso 3: La descarga usa la extensión derivada del MIME real.
4. Paso 4: No se expone la extensión original ni el nombre físico.

### Valores distintos de `descargar=1`

1. Paso 1: La URL incluye `?descargar=0`, `?descargar=true`, `?descargar=yes`, `?descargar=` o `?descargar[]=1`.
2. Paso 2: El controlador no reconoce el valor como descarga porque la comparación es estricta contra `'1'`.
3. Paso 3: El recurso válido se sirve como `inline`, igual que en FEAT-018.
4. Paso 4: No se produce error por un valor inesperado.

### Nombre con caracteres no ASCII

1. Paso 1: En una evolución futura, el nombre resuelto contiene caracteres no ASCII.
2. Paso 2: El saneamiento elimina controles, comillas, barras y punto y coma, y separa el valor ASCII del valor UTF-8.
3. Paso 3: El controlador emite `filename="..."` solo con ASCII y `filename*=UTF-8''...` con el nombre UTF-8 codificado según RFC 5987.
4. Paso 4: El navegador elige la representación que soporte; si no soporta `filename*`, usa el `filename` ASCII.

### Saneamiento deja un nombre vacío

1. Paso 1: El nombre recibido está compuesto solo por caracteres prohibidos o queda vacío tras el saneamiento.
2. Paso 2: El controlador usa el fallback `recaudo-{recaudoId}.{ext}` con la extensión del MIME resuelto.
3. Paso 3: La descarga continúa con un nombre seguro y trazable.
4. Paso 4: No se responde `404` por un problema de nombre.

### Aperturas repetidas

1. Paso 1: El administrador descarga 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 descargas 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 entrega |
| `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 |
| `?descargar=1` con recurso ajeno, inexistente o inválido | La resolución devuelve `null` | `404` genérico en `text/plain`, sin `attachment` | Sin entrega |
| `?descargar=1` con `DatabaseException` | Captura en el controlador | `500` con texto genérico, sin `attachment` ni detalles internos | Error visible sin datos internos |
| `?descargar=1` con error inesperado | Captura defensiva en el controlador | `500` con texto genérico, sin `attachment` | Error visible sin datos internos |
| `?descargar` con valor distinto de `'1'` | Comparación estricta | Sirve `inline` si el recurso es válido | Comportamiento de FEAT-018 |
| Nombre saneado vacío o inválido | Validación posterior al saneamiento | Usa `recaudo-{recaudoId}.{ext}` | Descarga con nombre de respaldo |
| Intento de inyectar CR, LF, comillas, barras o punto y coma en el nombre | Saneamiento del nombre | Los caracteres se eliminan antes de construir la cabecera | Cabecera válida sin inyección |
| Datos con HTML en la ruta o en el nombre | No se interpolan en la respuesta; el nombre se deriva del id y del MIME | Solo se devuelven cabeceras controladas | Sin ejecución de HTML ni inyección de cabeceras |

## Reglas de negocio y validaciones

1. **Activador exacto:** la descarga se fuerza únicamente cuando `$this->request->getGet('descargar')` es la cadena `'1'`. Cualquier otro valor, un arreglo o la ausencia del parámetro mantiene la respuesta `inline`.
2. **Respuesta inline sin cambios:** la cabecera de la visualización en línea sigue siendo `inline; filename="recaudo-{recaudoId}.{ext}"`, sin `filename*` y con las mismas cabeceras de FEAT-018.
3. **Nombre de descarga:** se toma el `nombre` devuelto por `RecaudoArchivoService`, que ya se deriva del MIME real (`recaudo-{recaudoId}.{ext}`). No se usa el nombre original, el nombre aleatorio del disco, datos del aspirante ni valores de la petición.
4. **Saneamiento:** antes de construir la cabecera se eliminan del nombre CR (`\r`), LF (`\n`), comillas dobles (`"`), barra invertida (`\`), barra inclinada (`/`), punto y coma (`;`), caracteres de control (`U+0000`–`U+001F` y `U+007F`) y caracteres no ASCII del valor de `filename`.
5. **Codificación RFC 5987:** si el nombre saneado contiene caracteres no ASCII, se agrega `filename*=UTF-8''<nombre-codificado>` con codificación porcentual. Si el nombre es ASCII, solo se emite `filename="..."`.
6. **Fallback:** si el nombre saneado queda vacío, sin extensión válida o no coincide con el patrón seguro esperado, se usa `recaudo-{recaudoId}.{ext}` con la extensión del MIME resuelto.
7. **Formato de cabecera:** la descarga usa `Content-Disposition: attachment` con el nombre entre comillas dobles. No se permite interpolar texto libre en la cabecera.
8. **Autorización y propiedad intactas:** se mantienen el filtro `adminPanel:module=inscripciones_ni`, la verificación de sesión/módulo del controlador, la validación de que el recaudo pertenece a la postulación, `activo = 1`, la postulación existente, la ruta relativa al prefijo, la base canónica, la existencia del archivo y el MIME real permitido.
9. **Identidad desde la sesión:** el `admin_id` para logs y resolución sale de `admin_user['id']`. Los únicos datos de la petición usados para resolver el recurso son los dos enteros de la ruta; el parámetro `descargar` solo elige el modo de entrega.
10. **Sin confianza en el cliente:** no se aceptan rutas, nombres de archivo, MIME, `archivo_path`, `archivo_hash` ni identificadores de catálogo por query string o cuerpo.
11. **Cabeceras de éxito:** la respuesta `200` incluye `Content-Type` del MIME real, `Content-Length` en bytes, `Content-Disposition` (`inline` o `attachment` según el caso), `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
12. **Errores sin attachment:** las respuestas `404` y `500` conservan sus cabeceras y cuerpos genéricos de FEAT-018 y no incluyen `Content-Disposition: attachment`.
13. **Auditoría:** solo se registran los rechazos, con `inscripcion_id`, `recaudo_id`, `admin_id` y un código de motivo; nunca ruta, nombre, hash, contenido ni datos personales. Las descargas y visualizaciones exitosas no se registran.
14. **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.
15. **Sin caché reutilizable:** la respuesta `200` usa `private, max-age=0, must-revalidate`; las respuestas de error usan `no-store`. No se usa caché pública ni se comparte el archivo entre sesiones.
16. **Vista de detalle:** el enlace "Descargar" deja de abrir una pestaña nueva (se quitan `target="_blank"` y `rel="noopener noreferrer"`); el enlace "Ver" conserva `target="_blank"` y `rel="noopener noreferrer"`. Los enlaces se siguen mostrando solo para recaudos disponibles.
17. **Compatibilidad:** no se modifica la firma de `recaudo(int $id, int $recaudoId)`, la ruta, el servicio, `PostulacionesAdminService`, `NiInscripcionRecaudoModel`, el listado, el filtro `AdminPanel`, el header, el login, el panel Zelle, la API JWT, la SPA ni el flujo del estudiante. El contrato del endpoint gana la variante de descarga.
18. **Auto-routing:** se mantiene la defensa en profundidad del controlador; una petición por auto-routing sin sesión o sin módulo sigue respondiendo `404` genérico antes de resolver o descargar.
19. **Idioma y estilo:** comentarios, docblocks y mensajes nuevos en español, siguiendo las convenciones de `AGENTS.md`.
20. **Sin dependencias nuevas:** no se agregan librerías, paquetes, helpers globales ni variables de entorno.

## Áreas afectadas

- `app/Controllers/Admin/InscripcionesNuevoIngreso.php`: modificar `recaudo()` para detectar `descargar=1` y elegir `inline` o `attachment`; agregar métodos privados para sanear el nombre y construir la cabecera `Content-Disposition` (incluido el `filename*` RFC 5987 cuando aplique). Sin SQL propio.
- `app/Views/Admin/nuevo_ingreso/detalle.php`: quitar `target="_blank"` y `rel="noopener noreferrer"` del enlace "Descargar"; mantener el enlace "Ver" y la condición `disponible`.
- `tests/app/Controllers/Admin/InscripcionesNuevoIngresoRecaudoTest.php`: reemplazar la prueba que hoy verifica que `?descargar=1` se ignora por pruebas de `attachment`, nombre, `filename*`, cabeceras de seguridad, `404` con `descargar=1` y regresión de `inline`; agregar pruebas del saneamiento y del fallback.
- `tests/app/Views/Admin/DetallePostulacionViewTest.php`: actualizar o agregar la verificación de que "Descargar" conserva `?descargar=1` sin `target="_blank"` y que "Ver" conserva `target="_blank"`.
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/RecaudoArchivoServiceTest.php`: ejecutar como regresión; no se requieren cambios porque el servicio no se modifica.
- `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.
- `docs/features/019-forzar-descarga-segura-recaudo-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 `app/Config/Routes.php`, `RecaudoArchivoService.php`, `PostulacionesAdminService.php`, `NiInscripcionRecaudoModel.php`, `Paso1.php`, `PagosZelleServices.php`, `Panel.php`, `PanelAuth.php`, el 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

- [x] Una petición `GET .../recaudo/{recaudoId}?descargar=1` sobre un recaudo propio y válido responde `200` con `Content-Disposition: attachment`.
- [x] La cabecera de descarga contiene `filename="recaudo-{recaudoId}.{ext}"` con la extensión derivada del MIME real.
- [x] El nombre de descarga se sanea eliminando CR, LF, comillas dobles, barra invertida, barra inclinada, punto y coma y caracteres de control.
- [x] Si el nombre saneado contiene caracteres no ASCII, se emite `filename*=UTF-8''...` con codificación porcentual RFC 5987.
- [x] Si el nombre saneado queda vacío o inválido, se usa el fallback `recaudo-{recaudoId}.{ext}`.
- [x] La respuesta de descarga incluye `Content-Type` del MIME real, `Content-Length`, `X-Content-Type-Options: nosniff` y `Cache-Control: private, max-age=0, must-revalidate`.
- [x] Sin `descargar` o con un valor distinto de `'1'`, el recurso válido se sirve `inline; filename="recaudo-{recaudoId}.{ext}"` sin `filename*`, igual que en FEAT-018.
- [x] Un recaudo ajeno, inexistente, inactivo, sin archivo, con ruta inválida, con archivo ausente o con MIME no permitido responde `404` genérico también cuando se envía `?descargar=1`, sin cabecera `attachment`.
- [x] Un `DatabaseException` o un error inesperado con `?descargar=1` responde `500` genérico sin `attachment`, sin trazas ni SQL.
- [x] El saneamiento no permite inyectar CR, LF, comillas ni caracteres de control en `Content-Disposition`.
- [x] La descarga solo se fuerza con la cadena exacta `'1'`; `0`, `true`, `yes`, vacío o un arreglo mantienen `inline`.
- [x] Las validaciones de sesión, módulo, propiedad, ruta canónica, existencia y MIME real no cambian respecto de FEAT-018.
- [x] `RecaudoArchivoService` no se modifica.
- [x] No se registran descargas ni visualizaciones exitosas; solo se mantienen los logs de rechazo.
- [x] El enlace "Descargar" del detalle apunta a la misma ruta con `?descargar=1` y ya no usa `target="_blank"`.
- [x] El enlace "Ver" del detalle conserva `target="_blank"` y `rel="noopener noreferrer"`.
- [x] Los enlaces "Ver" y "Descargar" siguen apareciendo solo para recaudos con `disponible === true`.
- [x] Las pruebas nuevas y actualizadas del controlador y de la vista pasan.
- [x] Las pruebas de `RecaudoArchivoServiceTest`, `AdminPanelTest`, `PostulacionesAdminServiceTest` y `DetallePostulacionViewTest` pasan como regresión.
- [x] Se ejecuta `php -l` sobre el controlador y la vista sin errores de sintaxis.
- [ ] Se completa el smoke test manual: descarga de PDF, descarga de imagen, vista en línea, valor `descargar` distinto de `1`, recaudo ajeno, recaudo inexistente, recaudo inactivo, archivo ausente, ruta manipulada, MIME no permitido y sesión cerrada.
- [x] No se ejecutan escrituras en base de datos ni se modifica, borra o mueve el archivo.
- [x] No se modificaron la ruta, el servicio, `Paso1::verArchivo()`, la librería de pagos, el filtro `AdminPanel`, la SPA, la API JWT ni el panel Zelle.
- [x] Se ejecuta `graphify update .` después de los cambios de código.

## Riesgos

- **Alto:** inyección de cabeceras HTTP mediante el nombre de archivo. Se mitiga usando un nombre derivado de datos controlados, saneando CR/LF, comillas, barras, punto y coma y controles, y no interpolando datos de la petición en `Content-Disposition`. Cualquier fallo de esta validación debe considerarse bloqueante.
- **Alto:** entrega de archivos no autorizados por habilitar una variante de descarga. Se mitiga conservando íntegras las validaciones de propiedad, ruta, existencia y MIME de FEAT-018; el modo de entrega no relaja ninguna de ellas.
- **Medio:** la prueba existente `testIgnoraElParametroDescargarYRespondeInline` afirma el comportamiento contrario. Debe actualizarse de forma explícita para evitar una falsa sensación de regresión.
- **Medio:** `filename*` tiene soporte variable en navegadores antiguos. Se emite junto con `filename` ASCII como respaldo; el nombre actual es ASCII y no depende de él.
- **Bajo:** algunos navegadores o visores pueden ignorar `Content-Disposition: attachment` y abrir el archivo en línea. El servidor cumple el contrato; el smoke test debe confirmarlo en los navegadores objetivo.
- **Bajo:** el enlace "Descargar" en la misma pestaña depende de que el navegador respete `attachment`. Si no lo hace, el usuario vería el archivo en lugar de descargarlo; el comportamiento del servidor seguiría siendo correcto.
- **Bajo:** diferencias de mayúsculas y separadores entre Windows y Linux. El saneamiento y la resolución del servicio ya normalizan separadores y se prueban en 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.
- **Bajo:** el smoke test manual puede quedar pendiente por falta de sesión administrativa real y datos de prueba, como ocurrió en FEAT-018; se documentará en el prototipo de ejecución.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial de la descarga adjunta de recaudos desde el panel administrativo. Se define el activador exacto `descargar=1`, el nombre `recaudo-{recaudoId}.{ext}` derivado del MIME, el saneamiento de la cabecera, `filename*` RFC 5987 condicional, el fallback del nombre, la conservación de las validaciones de FEAT-018 y el ajuste del enlace "Descargar" en la vista de detalle. Se excluyen cambios en la ruta, el servicio, la auditoría de éxitos, el rate limiting y el endpoint del estudiante. | opencode (agente) |
| 2026-10-30 | Ejecución de la feature en la rama `p-feature/forzar-descarga-segura-recaudo-panel-administrativo`: implementación de la entrega adjunta con saneamiento y fallback, ajuste del enlace "Descargar" y actualización de pruebas. Smoke test manual pendiente de sesión administrativa real. Ver `prototipo.md`. | opencode (agente) |
