backend/MEDIA_CLEANUP_GUIDE.md

# Comando de Limpieza de Archivos Media

Este documento explica cómo utilizar los comandos de limpieza de archivos media huérfanos en el proyecto Django.

## ¿Qué son los archivos huérfanos?

Los archivos huérfanos son archivos que existen físicamente en el directorio `/media/` pero que no están referenciados en ningún campo de archivo (`FileField` o `ImageField`) de la base de datos. Esto puede ocurrir por:

- Eliminación de registros sin eliminar sus archivos asociados
- Errores en procesos de carga de archivos
- Archivos temporales que nunca se limpiaron
- Migraciones de datos incorrectas

## Comandos Disponibles

### 1. cleanup_media (Comando Original)
```bash
python manage.py cleanup_media [opciones]
```

### 2. cleanup_media_fast (Comando Optimizado)
```bash
python manage.py cleanup_media_fast [opciones]
```

## Opciones Disponibles

### Opciones Comunes (ambos comandos):
- `--dry-run`: Muestra qué archivos se eliminarían sin eliminarlos realmente
- `--verbose`: Muestra información detallada del proceso
- `--help`: Muestra ayuda del comando

### Opciones del cleanup_media:
- `--batch-size N`: Tamaño del lote para procesar archivos (default: 10000)

### Opciones del cleanup_media_fast:
- `--limit N`: Limitar el número de archivos huérfanos a procesar
- `--sample-size N`: Tamaño de muestra para análisis rápido (default: 10000)
- `--quick-scan`: Hacer un escaneo rápido con muestra limitada

## Uso Recomendado

### 1. Análisis Inicial (Siempre hacer primero)
```bash
# Escaneo rápido para obtener una estimación
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run --verbose"

# O escaneo completo para números exactos (puede tomar tiempo)
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --dry-run --verbose"
```

### 2. Limpieza por Lotes (Recomendado para grandes volúmenes)
```bash
# Limpiar muestra de 10,000 archivos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --verbose"

# Limpiar hasta 5,000 archivos específicos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 5000 --verbose"
```

### 3. Limpieza Completa
```bash
# Eliminar todos los archivos huérfanos (CUIDADO: puede tomar mucho tiempo)
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --verbose"
```

## Ejemplos de Salida

### Dry Run (Modo Prueba):
```
Iniciando análisis en: /app/media
Modo escaneo rápido - muestra de 10000 archivos
Obteniendo muestra de archivos...
Muestra obtenida: 10000 archivos
Encontrados 5 modelos con campos de archivo
Procesando Document...
  Document: 2059405 registros procesados
Archivos huérfanos encontrados: 2763 (72.57 MB) - Tiempo: 7.81s

--- MODO PRUEBA: Los siguientes archivos se eliminarían ---
  - documents/vu_AC_0101_230_1703_3004804_4.pdf
  - documents/vu_AC_0101_300_3172_4001419_2.pdf
  ... y 2743 archivos más
```

### Eliminación Real:
```
¿Estás seguro de que quieres eliminar 2763 archivos? (s/N): s
Progreso: 36.2% (1000 eliminados)
Progreso: 72.4% (2000 eliminados)
Eliminados 2763 archivos huérfanos (51.32 MB)
```

## Casos de Uso

### Caso 1: Primera vez ejecutando el comando
```bash
# 1. Hacer análisis inicial
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run"

# 2. Si hay pocos archivos (<5000), eliminar todos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan"

# 3. Si hay muchos archivos, eliminar por lotes
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 10000"
```

### Caso 2: Mantenimiento regular
```bash
# Escaneo rápido y limpieza
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan"
```

### Caso 3: Limpieza masiva después de migración de datos
```bash
# 1. Análisis completo primero
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --dry-run"

# 2. Limpieza por lotes grandes
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 50000"
```

## Consideraciones de Seguridad

### ⚠️ IMPORTANTE - Hacer Backup
Siempre haz un backup de tu directorio `/media/` antes de ejecutar eliminaciones masivas:
```bash
# Backup del directorio media
docker exec backend tar -czf /tmp/media_backup.tar.gz /app/media/

# Copiar backup al host
docker cp backend:/tmp/media_backup.tar.gz ./media_backup_$(date +%Y%m%d_%H%M%S).tar.gz
```

### ✅ Buenas Prácticas
1. **Siempre usar `--dry-run` primero** para ver qué se va a eliminar
2. **Empezar con lotes pequeños** (`--limit`) en lugar de eliminar todo de una vez
3. **Verificar la aplicación** después de cada limpieza para asegurar que no se rompió nada
4. **Ejecutar en horarios de bajo tráfico** para grandes volúmenes
5. **Monitorear el espacio en disco** antes y después

### 🚨 Advertencias
- Los archivos eliminados **NO SE PUEDEN RECUPERAR** fácilmente
- El comando solo verifica referencias en la BD, no enlaces desde código o templates
- Archivos muy recientes podrían estar en proceso de ser referenciados

## Troubleshooting

### Error: "Too many open files"
```bash
# Aumentar límite de archivos abiertos
docker exec -it backend bash -c "ulimit -n 65536 && cd /app && python manage.py cleanup_media_fast --quick-scan"
```

### Proceso muy lento
```bash
# Usar modo quick-scan en lugar de escaneo completo
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run"
```

### Verificar que el comando existe
```bash
# Listar comandos disponibles
docker exec -it backend bash -c "cd /app && python manage.py help"
```

## Automatización

Para automatizar la limpieza regular, puedes crear un cron job:
```bash
# Ejecutar limpieza semanal los domingos a las 2 AM
0 2 * * 0 docker exec backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan" >> /var/log/media_cleanup.log 2>&1
```

## Monitoreo

Para monitorear el efecto de la limpieza:
```bash
# Antes de limpiar
docker exec backend du -sh /app/media/

# Después de limpiar (verificar el cambio)
docker exec backend du -sh /app/media/
```