MangaReader/ios-app/Sources/QUICK_START.md

# Quick Start - Sistema de Descarga

## Integración Rápida (5 minutos)

### Paso 1: Verificar Archivos

Los siguientes archivos ya están creados en tu proyecto:

```
ios-app/Sources/
├── Services/
│   ├── DownloadManager.swift          ✅ 13KB
│   └── DOWNLOAD_SYSTEM_README.md      ✅ Documentación completa
├── Views/
│   ├── DownloadsView.swift            ✅ 13KB
│   └── MangaDetailView.swift          ✅ Actualizado
├── Extensions/
│   └── DownloadExtensions.swift       ✅ 4.7KB
├── Examples/
│   └── IntegrationExample.swift       ✅ Ejemplos de integración
└── Tests/
    └── DownloadManagerTests.swift     ✅ Tests unitarios
```

### Paso 2: Agregar DownloadsView a Tu App

Si tienes un TabView, simplemente agrega:

```swift
// En tu ContentView o App principal
TabView {
    ContentView()              // Tu vista actual
        .tabItem {
            Label("Biblioteca", systemImage: "books.vertical")
        }

    DownloadsView()            // ✅ NUEVA VISTA
        .tabItem {
            Label("Descargas", systemImage: "arrow.down.circle")
        }
        .badge(downloadManager.activeDownloads.count)  // Opcional: badge

    SettingsView()
        .tabItem {
            Label("Ajustes", systemImage: "gear")
        }
}
```

### Paso 3: Probar la Descarga

1. Abre `MangaDetailView` (ya está actualizado)
2. Toca el botón de descarga (icono de flecha hacia abajo) en la toolbar
3. Selecciona "Descargar últimos 10" o "Descargar todos"
4. Observa el progreso en cada fila de capítulo
5. Ve a la tab "Descargas" para ver el progreso detallado

¡Eso es todo! El sistema está completamente integrado.

## Características Incluidas

### ✅ Ya Funciona
- Descarga de capítulos individuales
- Descarga masiva (todos o últimos N)
- Progreso en tiempo real
- Cancelación de descargas
- Historial de descargas
- Notificaciones de estado
- Gestión de almacenamiento
- Manejo de errores

### 📱 UI Components
- `DownloadsView` - Vista completa con tabs
- `ActiveDownloadCard` - Card con progreso
- `CompletedDownloadCard` - Card de completados
- `FailedDownloadCard` - Card con reintentar
- Toast notifications
- Progress bars

### 🔧 Services
- `DownloadManager` - Singleton gerente de descargas
- `DownloadTask` - Modelo de tarea individual
- `DownloadState` - Estados de descarga
- `DownloadError` - Tipos de error

## Uso Básico

### Desde MangaDetailView

```swift
// Ya está implementado en MangaDetailView
// El usuario solo necesita tocar el botón de descarga
```

### Programáticamente

```swift
let downloadManager = DownloadManager.shared

// Descargar un capítulo
try await downloadManager.downloadChapter(
    mangaSlug: manga.slug,
    mangaTitle: manga.title,
    chapter: chapter
)

// Descargar múltiples
await downloadManager.downloadChapters(
    mangaSlug: manga.slug,
    mangaTitle: manga.title,
    chapters: chapters
)

// Cancelar descarga
downloadManager.cancelDownload(taskId: taskId)

// Cancelar todas
downloadManager.cancelAllDownloads()
```

### Verificar Descargas

```swift
let storage = StorageService.shared

// ¿Está descargado?
if storage.isChapterDownloaded(
    mangaSlug: manga.slug,
    chapterNumber: 1
) {
    // Usar imagen local
    let imageURL = storage.getImageURL(
        mangaSlug: manga.slug,
        chapterNumber: 1,
        pageIndex: 0
    )
}
```

## Personalización Opcional

### Ajustar Concurrencia

En `DownloadManager.swift`:

```swift
private let maxConcurrentDownloads = 3        // Capítulos simultáneos
private let maxConcurrentImagesPerChapter = 5 // Imágenes simultáneas
```

### Ajustar Calidad de Imagen

En `StorageService.swift`:

```swift
image.jpegData(compressionQuality: 0.8)  // 80% de calidad
```

En `DownloadExtensions.swift`:

```swift
let maxDimension: CGFloat = 2048  // Redimensionar si es mayor
return resized.compressedData(quality: 0.75)  // 75% de calidad
```

## Solución de Problemas

### Las descargas no inician
1. Verificar conexión a internet
2. Verificar que ManhwaWebScraper funciona
3. Verificar logs en consola

### El progreso no se actualiza
1. Asegurar que estás en @MainActor
2. Verificar que las propiedades son @Published
3. Verificar que observas DownloadManager

### Error "Already downloaded"
1. Es normal - el capítulo ya existe
2. Usa `storage.deleteDownloadedChapter()` para eliminar
3. O permite sobrescribir

### Las imágenes no se guardan
1. Verificar permisos de la app
2. Verificar espacio disponible
3. Verificar que directorios existen

## Próximos Pasos

### Opcional: Badge en TabView

```swift
struct MainTabView: View {
    @StateObject private var downloadManager = DownloadManager.shared

    var body: some View {
        TabView {
            // ...
            DownloadsView()
                .tabItem {
                    Label("Descargas", systemImage: "arrow.down.circle")
                }
                .badge(downloadManager.activeDownloads.count)  // ✅ Badge
        }
    }
}
```

### Opcional: Widget en Home

```swift
struct ContentView: View {
    @ObservedObject var downloadManager = DownloadManager.shared

    var body: some View {
        ScrollView {
            // Tu contenido actual

            if downloadManager.hasActiveDownloads {
                ActiveDownloadsWidget()
            }
        }
    }
}
```

### Opcional: Banner de Descargas

```swift
struct ContentView: View {
    var body: some View {
        MangaDetailView(manga: manga)
            .activeDownloadsBanner()  // ✅ Modificador personalizado
    }
}
```

## Testing

### Manual
1. Descargar un capítulo
2. Cancelar una descarga
3. Descargar múltiples capítulos
4. Probar sin internet
5. Limpiar almacenamiento

### Automatizado
Los tests están en `/Sources/Tests/DownloadManagerTests.swift`

Para ejecutar en Xcode:
1. Cmd + U
2. O Product → Test

## Archivos de Referencia

### Documentación
- `DOWNLOAD_SYSTEM_README.md` - Guía completa (400 líneas)
- `IMPLEMENTATION_SUMMARY.md` - Resumen ejecutivo
- `DIAGRAMS.md` - Diagramas de flujo
- `CHECKLIST.md` - Checklist de implementación

### Código
- `DownloadManager.swift` - Core del sistema
- `DownloadsView.swift` - Vista principal
- `DownloadExtensions.swift` - Extensiones útiles
- `IntegrationExample.swift` - Ejemplos de integración

## Soporte

### Problemas Comunes

**"No se compila"**
- Asegúrate de tener iOS 15+
- Verificar que todos los archivos están en el target
- Limpiar carpeta de builds (Cmd + Shift + K)

**"Las descargas fallan"**
- Verificar que ManhwaWebScraper funciona correctamente
- Probar con diferentes capítulos
- Verificar logs en consola

**"No se guardan las imágenes"**
- Verificar permisos en Info.plist
- Probar en dispositivo real (no simulador)
- Verificar espacio disponible

### Contacto

Para más ayuda, consulta:
1. `DOWNLOAD_SYSTEM_README.md` - Documentación completa
2. `DIAGRAMS.md` - Diagramas de flujo
3. `IntegrationExample.swift` - Ejemplos de código

---

**Tiempo de integración**: 5 minutos
**Dificultad**: Fácil
**Estado**: ✅ COMPLETO

¡Happy coding! 🚀