Initial commit: MangaReader iOS App
✨ Features: - App iOS completa para leer manga sin publicidad - Scraper con WKWebView para manhwaweb.com - Sistema de descargas offline - Lector con zoom y navegación - Favoritos y progreso de lectura - Compatible con iOS 15+ y Sideloadly/3uTools 📦 Contenido: - Backend Node.js con Puppeteer (opcional) - App iOS con SwiftUI - Scraper de capítulos e imágenes - Sistema de almacenamiento local - Testing completo - Documentación exhaustiva 🧪 Prueba: Capítulo 789 de One Piece descargado exitosamente - 21 páginas descargadas - 4.68 MB total - URLs verificadas y funcionales 🎉 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
277
docs/README.md
Normal file
277
docs/README.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# MangaReader - Documentación Técnica
|
||||
|
||||
Bienvenido a la documentación técnica de MangaReader. Este directorio contiene toda la información necesaria para entender, desarrollar y contribuir al proyecto.
|
||||
|
||||
## Documentos Disponibles
|
||||
|
||||
### [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||||
Documentación completa de la arquitectura del sistema.
|
||||
|
||||
**Contenido:**
|
||||
- Visión general del sistema (Backend + iOS App)
|
||||
- Arquitectura MVVM de la app iOS
|
||||
- Diagramas de flujo de datos (scraping, lectura, guardado)
|
||||
- Patrones de diseño implementados (Singleton, MVVM, Repository, etc.)
|
||||
- Diagramas de secuencia en ASCII
|
||||
- Decisiones arquitectónicas y su justificación
|
||||
|
||||
**Para quién es:**
|
||||
- Desarrolladores que necesitan entender la estructura general
|
||||
- Arquitectos que evalúan el diseño del sistema
|
||||
- Nuevos contribuyentes que necesitan orientación
|
||||
|
||||
---
|
||||
|
||||
### [API.md](./API.md)
|
||||
Documentación de la API y modelos de datos.
|
||||
|
||||
**Contenido:**
|
||||
- Modelos de datos (Manga, Chapter, MangaPage, ReadingProgress, etc.)
|
||||
- Documentación completa de servicios (ManhwaWebScraper, StorageService)
|
||||
- Descripción de ViewModels y sus responsabilidades
|
||||
- Errores y manejo de excepciones
|
||||
- Ejemplos de uso para cada método público
|
||||
|
||||
**Para quién es:**
|
||||
- Desarrolladores que integran funcionalidades
|
||||
- Equipo QA que necesita entender comportamientos esperados
|
||||
- Contribuyentes que agregan nuevas features
|
||||
|
||||
---
|
||||
|
||||
### [CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||
Guía para contribuir al proyecto.
|
||||
|
||||
**Contenido:**
|
||||
- Configuración del entorno de desarrollo
|
||||
- Cómo agregar nuevas fuentes de manga
|
||||
- Cómo modificar el scraper existente
|
||||
- Estándares de código (Swift style guide)
|
||||
- Testing (unit tests, integración)
|
||||
- Pull request guidelines
|
||||
- Troubleshooting común
|
||||
|
||||
**Para quién es:**
|
||||
- Nuevos contribuyentes
|
||||
- Desarrolladores que agregan features
|
||||
- Maintainers que revisan PRs
|
||||
|
||||
---
|
||||
|
||||
## Estructura del Proyecto
|
||||
|
||||
```
|
||||
MangaReader/
|
||||
├── docs/ # Documentación técnica
|
||||
│ ├── README.md # Este archivo (índice)
|
||||
│ ├── ARCHITECTURE.md # Arquitectura y diagramas
|
||||
│ ├── API.md # API y modelos de datos
|
||||
│ └── CONTRIBUTING.md # Guía para contribuyentes
|
||||
│
|
||||
├── ios-app/ # Aplicación iOS
|
||||
│ ├── MangaReaderApp.swift # Entry point de la app
|
||||
│ ├── Sources/
|
||||
│ │ ├── Models/ # Modelos de datos
|
||||
│ │ │ └── Manga.swift # Models documentados
|
||||
│ │ ├── Services/ # Lógica de negocio
|
||||
│ │ │ ├── ManhwaWebScraper.swift # Scraper documentado
|
||||
│ │ │ └── StorageService.swift # Storage documentado
|
||||
│ │ └── Views/ # UI SwiftUI
|
||||
│ │ ├── ContentView.swift
|
||||
│ │ ├── MangaDetailView.swift
|
||||
│ │ └── ReaderView.swift
|
||||
│ └── MangaReader.xcodeproj
|
||||
│
|
||||
└── backend/ # Backend opcional (Node.js)
|
||||
├── scraper.js
|
||||
├── server.js
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resumen Rápido de Componentes
|
||||
|
||||
### Modelos de Datos
|
||||
- **Manga**: Información completa de un manga
|
||||
- **Chapter**: Capítulo individual con estado de lectura
|
||||
- **MangaPage**: Página individual (imagen)
|
||||
- **ReadingProgress**: Progreso de lectura del usuario
|
||||
- **DownloadedChapter**: Capítulo descargado localmente
|
||||
|
||||
### Servicios
|
||||
- **ManhwaWebScraper**: Scraper usando WKWebView para manhwaweb.com
|
||||
- **StorageService**: Gestión de almacenamiento local (UserDefaults + FileManager)
|
||||
|
||||
### ViewModels
|
||||
- **MangaListViewModel**: Lista principal de mangas
|
||||
- **MangaDetailViewModel**: Detalle de un manga
|
||||
- **ReaderViewModel**: Lector de capítulos
|
||||
|
||||
### Views
|
||||
- **ContentView**: Vista principal con lista de mangas
|
||||
- **MangaDetailView**: Detalle y capítulos de un manga
|
||||
- **ReaderView**: Lector de imágenes con zoom/pan
|
||||
|
||||
---
|
||||
|
||||
## Comenzar Rápidamente
|
||||
|
||||
### Para Entender la Arquitectura
|
||||
1. Lee [ARCHITECTURE.md](./ARCHITECTURE.md) - Sección "Visión General"
|
||||
2. Revisa los diagramas de flujo de datos
|
||||
3. Estudia los patrones de diseño usados
|
||||
|
||||
### Para Usar la API
|
||||
1. Consulta [API.md](./API.md) - Sección "Modelos de Datos"
|
||||
2. Revisa los servicios disponibles
|
||||
3. Mira los ejemplos de uso
|
||||
|
||||
### Para Contribuir
|
||||
1. Lee [CONTRIBUTING.md](./CONTRIBUTING.md) - "Configuración del Entorno"
|
||||
2. Configura tu entorno de desarrollo
|
||||
3. Revisa los estándares de código
|
||||
4. Sigue el workflow de Pull Requests
|
||||
|
||||
---
|
||||
|
||||
## Tecnologías Utilizadas
|
||||
|
||||
### iOS App
|
||||
- **SwiftUI**: Framework de UI declarativo
|
||||
- **Combine**: Programación reactiva
|
||||
- **WKWebView**: Rendering de JavaScript
|
||||
- **UserDefaults**: Almacenamiento de preferencias
|
||||
- **FileManager**: Almacenamiento de archivos
|
||||
|
||||
### Backend (Opcional)
|
||||
- **Node.js**: Runtime de JavaScript
|
||||
- **Express**: Framework web
|
||||
- **Puppeteer**: Headless Chrome automation
|
||||
|
||||
---
|
||||
|
||||
## Patrones de Diseño Principales
|
||||
|
||||
| Patrón | Implementación | Propósito |
|
||||
|--------|---------------|-----------|
|
||||
| **MVVM** | ViewModels separados de Views | Separar UI de lógica |
|
||||
| **Singleton** | `StorageService.shared`, `ManhwaWebScraper.shared` | Instancia única compartida |
|
||||
| **Repository** | `StorageService` abstrae UserDefaults/FileManager | Interfaz unificada de datos |
|
||||
| **Async/Await** | Métodos `async throws` en scraper | Código asíncrono legible |
|
||||
| **Observable** | `@Published`, `ObservableObject` | Reactividad en SwiftUI |
|
||||
|
||||
---
|
||||
|
||||
## Flujos Principales
|
||||
|
||||
### 1. Agregar Manga
|
||||
```
|
||||
Usuario → ContentView → MangaListViewModel
|
||||
↓
|
||||
ManhwaWebScraper.scrapeMangaInfo()
|
||||
↓
|
||||
WKWebView + JavaScript
|
||||
↓
|
||||
Manga actualizado en UI
|
||||
```
|
||||
|
||||
### 2. Leer Capítulo
|
||||
```
|
||||
Usuario → MangaDetailView → ReaderView
|
||||
↓
|
||||
ReaderViewModel.loadPages()
|
||||
↓
|
||||
¿Descargado? ─NO→ ManhwaWebScraper.scrapeChapterImages()
|
||||
│S ↓
|
||||
└─→ StorageService.getDownloadedChapter()
|
||||
↓
|
||||
Mostrar páginas en ReaderView
|
||||
```
|
||||
|
||||
### 3. Guardar Progreso
|
||||
```
|
||||
Usuario navega a página X
|
||||
↓
|
||||
ReaderViewModel.currentPage = X
|
||||
↓
|
||||
ReaderViewModel.saveProgress()
|
||||
↓
|
||||
StorageService.saveReadingProgress()
|
||||
↓
|
||||
UserDefaults (JSON codificado)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Preguntas Frecuentes
|
||||
|
||||
**¿Puedo agregar nuevas fuentes de manga?**
|
||||
Sí. Lee [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Cómo Agregar Nuevas Fuentes de Manga".
|
||||
|
||||
**¿El backend es obligatorio?**
|
||||
No. La app iOS funciona completamente de manera autónoma. El backend es opcional y puede servir como cache/API intermedia.
|
||||
|
||||
**¿Cómo cambio el scraper si manhwaweb.com cambia su estructura?**
|
||||
Consulta [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Cómo Modificar el Scraper".
|
||||
|
||||
**¿Cómo ejecuto los tests?**
|
||||
Ve a [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Testing".
|
||||
|
||||
---
|
||||
|
||||
## Convenciones de Documentación
|
||||
|
||||
### En Código Swift
|
||||
- **///**: Comentarios de documentación públicos (soportan Markdown)
|
||||
- **//:**: Comentarios de sección (MARK)
|
||||
- **//**: Comentarios de implementación
|
||||
|
||||
### Ejemplo de Documentación de Método
|
||||
```swift
|
||||
/// Obtiene la lista de capítulos de un manga.
|
||||
///
|
||||
/// Este método carga la página del manga, espera a que JavaScript renderice
|
||||
/// el contenido, y extrae todos los links de capítulos disponibles.
|
||||
///
|
||||
/// - Parameter mangaSlug: Slug único del manga
|
||||
/// - Returns: Array de `Chapter` ordenados por número (descendente)
|
||||
/// - Throws: `ScrapingError` si el WebView no está inicializado
|
||||
///
|
||||
/// # Example
|
||||
/// ```swift
|
||||
/// let chapters = try await scraper.scrapeChapters(mangaSlug: "one-piece")
|
||||
/// ```
|
||||
func scrapeChapters(mangaSlug: String) async throws -> [Chapter]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recursos Adicionales
|
||||
|
||||
### Documentación Oficial
|
||||
- [Swift Language Guide](https://docs.swift.org/swift-book/)
|
||||
- [SwiftUI Documentation](https://developer.apple.com/documentation/swiftui)
|
||||
- [WKWebView Reference](https://developer.apple.com/documentation/webkit/wkwebview)
|
||||
|
||||
### Herramientas
|
||||
- **SwiftLint**: Linter para código Swift
|
||||
- **SwiftFormat**: Formateador automático
|
||||
- **Jazzy**: Generador de documentación (Objective-C/Swift)
|
||||
|
||||
---
|
||||
|
||||
## Soporte y Contribución
|
||||
|
||||
¿Encontraste un error en la documentación? ¿Falta algo?
|
||||
|
||||
1. Abre un issue en el repositorio
|
||||
2. O envía un Pull Request con las mejoras
|
||||
|
||||
Para más detalles sobre cómo contribuir, revisa [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
**Última actualización**: Febrero 2026
|
||||
**Versión**: 1.0.0
|
||||
**Mantenedor**: MangaReader Team
|
||||
Reference in New Issue
Block a user