wallabicher/REFACTORING.md

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:

{
  "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.