Archivos y medios

---
name: archivos-y-medios
description: subir, guardar y servir archivos pesados sin tumbar el servidor.
---

# Archivos y medios

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques subida de archivos, imágenes, audio, video o cualquier adjunto.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El usuario sube imágenes, audio, video, PDF o adjuntos.
- La app genera archivos: exportaciones, reportes, capturas, recortes.
- Vas a mostrar medios que deben cargar rápido en móvil.
- Hay contenido privado que no puede quedar en una URL pública adivinable.

Si ninguna aplica, no agregues almacenamiento de objetos: guardar un archivo pequeño en
base de datos como bytes puede bastar para un demo.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: almacenamiento de objetos
S3-compatible (**Vercel Blob**, **Cloudflare R2** o **Backblaze B2**) con subida directa
firmada.

1. El navegador sube directo al almacenamiento con una URL firmada. Nunca hagas pasar
   200 MB por tu servidor.
2. Guarda en base de datos solo metadatos: clave, tamaño, tipo, dueño, estado. El archivo
   vive en el bucket, no en tu tabla.
3. Valida tipo y tamaño del lado del servidor al pedir la firma, no confíes en la
   extensión que manda el cliente.
4. Procesa en segundo plano: miniaturas con **sharp**, video con **ffmpeg**. La respuesta
   al usuario no espera al transcodificador.
5. Sirve lo público por CDN y lo privado por URL firmada de corta vida.
6. Limpia lo huérfano: subidas que nunca se confirmaron, archivos de cuentas borradas.

## En qué te vas a trabar

- **El egreso es la factura sorpresa.** R2 y B2 existen justo por eso: revisa el precio
  de salida antes de comprometerte con un proveedor.
- **Video es otro deporte.** Transcodificar, generar HLS y servirlo bien es
  infraestructura, no una tarde; no lo prometas a la ligera.
- **Un bucket público mal configurado expone todo lo que subieron tus usuarios**,
  incluidos sus documentos. Revisa los permisos del bucket antes de dar esto por
  terminado.

## Criterio de terminado

No declares esto listo hasta que hayas subido un archivo grande desde móvil con conexión
lenta, confirmado que el archivo privado no es accesible sin firma, y verificado que un
archivo huérfano se limpia solo.