add abstraction ob platform and article + vinted

" Signed-off-by: Omar Sánchez Pizarro <omar.sanchez@pistacero.net>
2025-10-10 14:58:27 +02:00
parent b5178f415b
commit 4111f57564
16 changed files with 1890 additions and 102 deletions
--- a/REFACTORING.md
+++ b/REFACTORING.md
@@ -0,0 +1,207 @@
+# Refactorización: Arquitectura Multi-Plataforma
+
+## Resumen de Cambios
+
+Se ha refactorizado completamente la arquitectura del proyecto para soportar múltiples plataformas de marketplace (Wallapop, Vinted, Buyee, etc.) mediante un diseño desacoplado y extensible.
+
+## Cambios Principales
+
+### 1. Nueva Estructura de Directorios
+
+```
+├── platforms/                      # NUEVO
+│   ├── __init__.py
+│   ├── base_platform.py           # Clase abstracta para plataformas
+│   ├── platform_factory.py        # Factory para crear plataformas
+│   ├── wallapop_platform.py       # Implementación de Wallapop
+│   ├── vinted_platform_template.py # Template para nuevas plataformas
+│   └── README.md                  # Documentación de plataformas
+│
+├── models/                         # NUEVO
+│   ├── __init__.py
+│   └── article.py                 # Modelo genérico de artículo
+│
+└── datalayer/
+    └── wallapop_article.py        # DEPRECADO (mantener por compatibilidad)
+```
+
+### 2. Clases Nuevas
+
+#### `models/article.py` - Modelo Genérico
+- **Propósito**: Representa un artículo de cualquier plataforma
+- **Cambios respecto a WallapopArticle**:
+  - Añadido campo `platform` para identificar el origen
+  - Método `get_images()` devuelve lista directa (no requiere procesamiento)
+  - Método `get_modified_at()` devuelve string ya formateado
+  - Igualdad considera plataforma (`id` + `platform`)
+
+#### `platforms/base_platform.py` - Clase Abstracta
+- **Propósito**: Define la interfaz común para todas las plataformas
+- **Métodos abstractos**:
+  - `get_platform_name()`: Retorna identificador de la plataforma
+  - `create_url()`: Construye URL de búsqueda
+  - `fetch_articles()`: Obtiene artículos de la plataforma
+  - `parse_response()`: Parsea respuesta a objetos Article
+- **Métodos concretos**:
+  - `get_request_headers()`: Headers por defecto (puede sobreescribirse)
+
+#### `platforms/wallapop_platform.py` - Implementación Wallapop
+- **Propósito**: Lógica específica de Wallapop
+- **Migración desde Worker**:
+  - `_create_url()` → `create_url()`
+  - `_request_articles()` → `fetch_articles()`
+  - `_parse_json_response()` → `parse_response()`
+- **Nuevas funcionalidades**:
+  - Manejo de errores en parseo de artículos individuales
+  - Logging específico de errores de Wallapop
+  - Headers específicos de Wallapop (`X-DeviceOS`)
+
+#### `platforms/platform_factory.py` - Factory Pattern
+- **Propósito**: Crear instancias de plataformas dinámicamente
+- **Funcionalidades**:
+  - `create_platform(name, item_monitor)`: Instancia la plataforma
+  - `get_available_platforms()`: Lista plataformas disponibles
+  - `register_platform(name, class)`: Registra nuevas plataformas
+- **Ventajas**:
+  - Añadir plataformas sin modificar código existente
+  - Validación de plataformas soportadas
+  - Mensajes de error descriptivos
+
+### 3. Clases Modificadas
+
+#### `managers/worker.py` - Refactorización Mayor
+**Eliminado** (lógica específica de Wallapop):
+- `_create_url()` - Movido a `WallapopPlatform.create_url()`
+- `_request_articles()` implementación completa - Movido a plataforma
+- `_parse_json_response()` - Movido a `WallapopPlatform.parse_response()`
+- Imports: `requests`, `WallapopArticle`
+- Constantes: `REQUEST_SLEEP_TIME`, `REQUEST_RETRY_TIME`, `USER_AGENT`
+
+**Añadido** (lógica desacoplada):
+- `self._platform`: Instancia de la plataforma configurada
+- Inicialización de plataforma mediante `PlatformFactory`
+- Manejo de errores de inicialización de plataforma
+- Log de plataforma inicializada
+- `_request_articles()` ahora delega a `self._platform.fetch_articles()`
+
+**Mantenido** (lógica común a todas las plataformas):
+- `_has_words()`: Búsqueda de palabras en texto
+- `_title_has_excluded_words()`: Filtrado de títulos
+- `_description_has_excluded_words()`: Filtrado de descripciones
+- `_title_has_required_words()`: Palabras requeridas en título
+- `_description_has_required_words()`: Palabras requeridas en descripción
+- `_title_first_word_is_excluded()`: Filtrado de primera palabra
+- `_meets_item_conditions()`: Validación completa de condiciones
+- `work()`: Loop principal de trabajo
+- `run()`: Manejo de errores y reinicios
+
+#### `datalayer/item_monitor.py` - Campo de Plataforma
+**Añadido**:
+- Parámetro `platform` en `__init__()`
+- Campo `self._platform`
+- Método `get_platform()`
+- Default `'wallapop'` en `load_from_json()` para compatibilidad hacia atrás
+
+### 4. Archivos de Configuración
+
+#### `workers.json` - Campo Opcional de Plataforma
+**Añadido**:
+- Campo `"platform": "wallapop"` en primer item como ejemplo
+- Otros items usan el default (wallapop) por compatibilidad
+
+**Ejemplo**:
+```json
+{
+  "name": "Playstation 1",
+  "platform": "wallapop",
+  "search_query": "playstation",
+  ...
+}
+```
+
+### 5. Documentación
+
+#### `platforms/README.md` - Guía Completa
+- Introducción a la arquitectura de plataformas
+- Cómo añadir una nueva plataforma (paso a paso)
+- Parámetros disponibles en ItemMonitor
+- Estructura del modelo Article
+- Lógica común del Worker vs lógica de plataforma
+
+#### `platforms/vinted_platform_template.py` - Plantilla
+- Implementación esqueleto para Vinted
+- TODOs marcados claramente
+- Comentarios explicativos
+- Estructura JSON de ejemplo
+- Pasos de activación
+
+#### `README.md` - Actualización Principal
+- Nueva sección "Arquitectura Multi-Plataforma"
+- Nueva sección "Añadir Nuevas Plataformas"
+- Actualización de descripción del proyecto
+- Tabla de parámetros con campo `platform`
+- Diagrama de estructura del proyecto
+- Lista de plataformas soportadas
+
+## Ventajas de la Nueva Arquitectura
+
+### ✅ Desacoplamiento
+- Lógica de plataforma separada de lógica de filtrado
+- Cada componente tiene una responsabilidad única
+- Fácil de mantener y testear
+
+### ✅ Extensibilidad
+- Añadir plataformas sin tocar código existente
+- Factory pattern permite registro dinámico
+- Plantillas y documentación para nuevas plataformas
+
+### ✅ Reutilización
+- Filtros comunes para todas las plataformas
+- Modelo Article unificado
+- Worker genérico
+
+### ✅ Mantenibilidad
+- Código más limpio y organizado
+- Responsabilidades claras
+- Fácil de entender y modificar
+
+## Compatibilidad Hacia Atrás
+
+✅ **100% Compatible**: El código existente funciona sin cambios
+- Items sin campo `platform` usan "wallapop" por defecto
+- `WallapopArticle` aún existe (aunque ya no se usa)
+- Mismos filtros y funcionalidad
+
+## Próximos Pasos
+
+Para añadir nuevas plataformas:
+
+1. **Vinted**: Completar el template existente
+2. **Buyee**: Crear nueva implementación
+3. **Amazon**: Posible integración futura
+4. **eBay**: Posible integración futura
+
+## Migración
+
+No se requiere migración. El sistema funciona con configuraciones existentes.
+
+Para aprovechar las nuevas funcionalidades:
+1. Añade `"platform": "wallapop"` a tus items en `workers.json` (opcional)
+2. Implementa nuevas plataformas según `platforms/README.md`
+
+## Testing
+
+Recomendaciones para testing:
+1. Verificar que Wallapop sigue funcionando igual
+2. Probar con configuraciones sin campo `platform`
+3. Validar que los filtros funcionan con el nuevo modelo Article
+4. Probar manejo de errores en inicialización de plataformas
+
+## Archivos a Mantener (Deprecados)
+
+- `datalayer/wallapop_article.py`: Mantener por si hay dependencias externas
+
+## Cambios en Dependencias
+
+Ninguno. Las mismas dependencias funcionan con la nueva arquitectura.
+