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/platforms/README.md
+++ b/platforms/README.md
@@ -0,0 +1,162 @@
+# Plataformas de Monitoreo
+
+Este directorio contiene las implementaciones de las diferentes plataformas de marketplace que el monitor puede usar.
+
+## Estructura
+
+- `base_platform.py`: Clase abstracta que define la interfaz común para todas las plataformas
+- `platform_factory.py`: Factory para crear instancias de plataformas dinámicamente
+- `wallapop_platform.py`: Implementación para Wallapop
+- `vinted_platform_template.py`: Plantilla de ejemplo para añadir nuevas plataformas
+
+## Cómo añadir una nueva plataforma
+
+### 1. Crear la clase de la plataforma
+
+Crea un nuevo archivo `<platform_name>_platform.py` que herede de `BasePlatform`:
+
+```python
+from platforms.base_platform import BasePlatform
+from models.article import Article
+import requests
+import logging
+
+class MiPlataformaPlatform(BasePlatform):
+    def __init__(self, item_monitor):
+        super().__init__(item_monitor)
+        self.logger = logging.getLogger(__name__)
+    
+    def get_platform_name(self):
+        return "mi_plataforma"
+    
+    def create_url(self):
+        # Construye la URL de búsqueda usando self._item_monitor
+        url = f"https://api.miplataforma.com/search?q={self._item_monitor.get_search_query()}"
+        
+        # Añade parámetros opcionales según la configuración
+        if self._item_monitor.get_min_price() != 0:
+            url += f"&min_price={self._item_monitor.get_min_price()}"
+        
+        return url
+    
+    def fetch_articles(self):
+        # Obtiene artículos desde la API
+        url = self.create_url()
+        headers = self.get_request_headers()
+        
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        
+        data = response.json()
+        return self.parse_response(data)
+    
+    def parse_response(self, response_data):
+        # Parsea la respuesta y crea objetos Article
+        articles = []
+        for item in response_data['items']:
+            article = Article(
+                id=item['id'],
+                title=item['title'],
+                description=item['description'],
+                price=item['price'],
+                currency=item['currency'],
+                location=item['location'],
+                allows_shipping=item['shipping'],
+                url=item['url'],
+                images=item['images'][:3],
+                modified_at=item['date'],
+                platform=self.get_platform_name()
+            )
+            articles.append(article)
+        
+        return articles
+```
+
+### 2. Registrar la plataforma en el Factory
+
+Edita `platform_factory.py` y añade tu plataforma al diccionario `_platforms`:
+
+```python
+from platforms.mi_plataforma_platform import MiPlataformaPlatform
+
+class PlatformFactory:
+    _platforms = {
+        'wallapop': WallapopPlatform,
+        'mi_plataforma': MiPlataformaPlatform,  # <-- Añade aquí
+    }
+```
+
+### 3. Configurar workers.json
+
+Añade el campo `platform` a tus items en `workers.json`:
+
+```json
+{
+  "items": [
+    {
+      "name": "Mi búsqueda",
+      "platform": "mi_plataforma",
+      "search_query": "gameboy",
+      "min_price": 10,
+      "max_price": 100,
+      ...
+    }
+  ]
+}
+```
+
+## Parámetros disponibles en ItemMonitor
+
+Tu plataforma puede usar los siguientes parámetros de configuración:
+
+- `get_name()`: Nombre del monitor
+- `get_search_query()`: Términos de búsqueda
+- `get_latitude()` / `get_longitude()`: Coordenadas geográficas
+- `get_max_distance()`: Distancia máxima en km
+- `get_condition()`: Estado del artículo
+- `get_min_price()` / `get_max_price()`: Rango de precios
+- `get_title_exclude()`: Palabras a excluir del título
+- `get_description_exclude()`: Palabras a excluir de la descripción
+- `get_title_must_include()`: Palabras requeridas en el título
+- `get_description_must_include()`: Palabras requeridas en la descripción
+- `get_title_first_word_exclude()`: Primera palabra del título a excluir
+- `get_check_every()`: Intervalo de verificación en segundos
+- `get_thread_id()`: ID del hilo de Telegram
+
+**Nota:** Los filtros de título y descripción son aplicados automáticamente por el Worker, 
+no necesitas implementarlos en tu plataforma.
+
+## Modelo Article
+
+Todas las plataformas deben devolver objetos `Article` con los siguientes campos:
+
+- `id`: Identificador único del artículo en la plataforma
+- `title`: Título del artículo
+- `description`: Descripción (se trunca a 500 caracteres)
+- `price`: Precio numérico
+- `currency`: Código de moneda (EUR, USD, etc.)
+- `location`: Ubicación del vendedor
+- `allows_shipping`: Boolean indicando si permite envíos
+- `url`: URL del artículo
+- `images`: Lista de URLs de imágenes (máximo 3)
+- `modified_at`: Fecha de modificación (string "YYYY-MM-DD HH:MM:SS")
+- `platform`: Nombre de la plataforma
+
+## Lógica común del Worker
+
+El Worker maneja automáticamente:
+
+- ✅ Filtrado por palabras excluidas en título/descripción
+- ✅ Filtrado por palabras requeridas en título/descripción
+- ✅ Filtrado por primera palabra del título
+- ✅ Deduplicación de artículos
+- ✅ Envío de notificaciones a Telegram
+- ✅ Gestión de errores y reintentos
+- ✅ Logging y estadísticas
+
+Tu plataforma solo debe encargarse de:
+
+- 🔧 Construir la URL de búsqueda específica de la plataforma
+- 🔧 Hacer la petición HTTP con los headers apropiados
+- 🔧 Parsear la respuesta y convertirla a objetos Article
+