# Resumen de Proyecto: Integración Odoo-Shopify (Hazard) Este documento detalla el estado actual del módulo de integración **`hazard_shopify`**, resumiendo todas las características robustas, mejoras de seguridad, lógica de sincronización y herramientas avanzadas de exportación implementadas para la gestión eficiente del catálogo, inventario y códigos de barras EAN-13 entre Odoo y Shopify. --- ## 📊 Estado General de Funcionalidades | Funcionalidad / Módulo | Estado | Descripción Técnica | | :--- | :---: | :--- | | **Autenticación OAuth y Conexión Segura** | ✅ **Completado** | Generación de token temporal de 24h, renovación automática con margen de 5 minutos, encriptación en base de datos. | | **Prevención de Duplicados (Paso 0)** | ✅ **Completado** | Agrupación en memoria de variantes duplicadas en Shopify antes del proceso de importación/sync para prevenir errores de integridad. | | **Generador de Barcodes EAN-13** | ✅ **Completado** | Generación secuencial automática basada en prefijo GS1 con cálculo de dígito verificador estándar y prevención de colisiones. | | **Sincronizador Background de Barcodes** | ✅ **Completado** | Proceso en segundo plano por lotes (*batches* de 50) con control de rate limit y commits por registro para evitar pérdida de progreso. | | **Importación de Catálogo (Shopify → Odoo)** | ✅ **Completado** | Creación inteligente de productos en Odoo (nombre, precios, imágenes base64 y mapeo de IDs de variantes e inventario). | | **Control de Inventario Multi-Sucursal** | ✅ **Completado** | Mapeo interactivo de almacenes Odoo ↔ Sucursales Shopify. Actualizaciones individuales y masivas basadas en diferencias (*discrepancias*). | | **Sincronización de Ventas (Pedidos)** | ✅ **Completado** | Importación automática mediante Odoo Cron cada 30 minutos o manual de pedidos recientes, asignando listas de precios y diarios. | | **Reportes Avanzados y Herramientas** | ✅ **Completado** | Exportación de CSV para impresoras de etiquetas y Excel dinámico multi-hoja con inventario detallado y códigos reservados. | --- ## 🛠️ Detalles de Arquitectura y Funcionalidades ### 1. Autenticación y Conexión Segura - **Mecanismo**: Implementa la autenticación mediante *OAuth Client Credentials*. - **Renovación Inteligente**: En lugar de depender de tokens estáticos vulnerables o expiraciones manuales abruptas, el sistema almacena las credenciales del Dev Dashboard y verifica el token antes de cada llamada API (`_ensure_access_token`). Si el token está a 5 minutos o menos de expirar, se solicita y actualiza automáticamente. - **Acciones Disponibles**: - `⚡ Generar Token`: Genera y almacena el primer token. - `Probar Conexión`: Envía una solicitud de ping rápida a la tienda para validar la integridad del canal. ### 2. Gestión de Duplicados en Web (Paso 0) - **El Problema**: Los SKUs duplicados en Shopify corrompen el inventario y las ventas al intentar mapearse en Odoo. - **La Solución**: Una pestaña inteligente dedicada ("Paso 0: Duplicados en Shopify") que agrupa en memoria todos los registros utilizando `NewId` de Odoo de forma optimizada. - **Acciones**: - Resalta en rojo los duplicados y advierte al usuario. - Permite proponer un **SKU Sugerido (Corrección)** directamente en una grilla editable. - Exporta un CSV de discrepancias para su revisión por parte del cliente antes de forzar la sincronización. ### 3. Generador e Inyector de Códigos de Barras EAN-13 - **Generación Idempotente**: Calcula dinámicamente códigos EAN-13 utilizando el prefijo de la empresa (por defecto `200001` para uso interno GS1). - **Control de Secuencias**: Obtiene el máximo número de secuencia actual de la base de datos para continuar de forma consecutiva sin repetir códigos generados anteriormente. - **Algoritmo EAN-13**: Cálculo matemático estricto del dígito verificador estándar GS1: $$\text{CheckDigit} = (10 - (\text{Suma de dígitos impares} + 3 \times \text{Suma de dígitos pares}) \pmod{10}) \pmod{10}$$ - **Sincronización Background Multihilo**: - Para evitar bloqueos HTTP (*Timeouts* de Odoo/Nginx), el botón `2. Subir a Shopify` ejecuta un hilo background (`threading.Thread`) que procesa variantes en lotes de 50. - **Rate Limit**: Implementa una espera controlada de `0.6` segundos entre variantes, respetando los límites de la API de Shopify (2 peticiones/segundo). - **Resiliencia Extrema**: Realiza un `cr.commit()` individual por cada variante subida con éxito. Si la red cae o el servidor se detiene, el progreso realizado queda guardado en la base de datos; al reactivar el proceso, simplemente continúa con las líneas en estado `pending` y `error`. - **Manual Overrides**: Botón `✓ Marcar como Subidos` para corregir estados de forma masiva en Odoo si se sincronizaron por otra vía, y botón `Reintentar errores` para volver a meter en cola los fallos capturados. ### 4. Sincronización Multi-Sucursal de Inventario (Shopify → Odoo) - **Mapeo Flexible**: Permite asociar N ubicaciones físicas de Shopify con N almacenes o ubicaciones de Odoo mediante la sub-tabla `shopify.location.mapping`. - **Sincronización Inteligente**: - Consulta en tiempo real (`requests.get`) los inventarios en las ubicaciones de Shopify asociadas. - Permite auditar el catálogo detectando diferencias de stock Odoo vs Shopify. - Ofrece el botón `Actualizar Stock Seleccionado (Shopify → Odoo)` para forzar a Odoo a igualar los niveles de stock de Shopify de forma masiva mediante *Inventory Adjustments* rápidos. ### 5. Reportes de Exportación Avanzados - **CSV de Etiquetas**: Genera un archivo optimizado para software de impresión de etiquetas (Dymo, Zebra, etc.) con columnas estructuradas de variantes y códigos de barras. - **Excel Multi-Hoja (openpyxl)**: - **Hoja 1 ("Inventario")**: Tabla con diseño estilizado, cabeceras en azul premium, auto-ajuste de columnas y colores dinámicos según el estado de Shopify (verde para subido, amarillo para pendiente, rojo para error). - **Hoja 2 ("Próximos Disponibles")**: Pre-calcula los siguientes **500 códigos EAN-13** consecutivos basados en el contador secuencial activo. Tiene diseño en color verde GS1 y tipografía de tipo Courier New para fácil lectura por el personal de almacén, previniendo que asignen códigos manualmente de manera incorrecta. --- ## 📂 Archivos del Módulo en el Repositorio El código fuente principal y las vistas XML están estructurados de la siguiente manera: 1. **Modelos de Base de Datos**: - [`shopify_config.py`](file:///var/www/vhosts/tesscorp.com.mx/hazard.tesscorp.com.mx/Addons/custom/hazard_shopify/models/shopify_config.py): Lógica principal del token, generación secuencial de EAN-13, hilo background resiliente, importación de stock multi-sucursal y formateo de hojas Excel de alta estética. - [`sku_simulation_line.py`](file:///var/www/vhosts/tesscorp.com.mx/hazard.tesscorp.com.mx/Addons/custom/hazard_shopify/models/sku_simulation_line.py): Estructura de datos por variante, campos computados para la detección de duplicados en memoria, y lógica de creación de variantes e imágenes base64 en Odoo. 2. **Interfaz de Usuario (Vistas XML)**: - [`shopify_config_views.xml`](file:///var/www/vhosts/tesscorp.com.mx/hazard.tesscorp.com.mx/Addons/custom/hazard_shopify/views/shopify_config_views.xml): Vistas de formulario Odoo enriquecidas estéticamente con paneles de estadísticas en vivo (Dashboards con badges CSS para estados), menús personalizados e instrucciones interactivas. --- ## 🚀 Plan de Despliegue y Pruebas Para garantizar una transición segura a producción, se recomienda seguir este flujo de verificación: ### Fase 1: Pruebas de Generación Local 1. Ingresar a Odoo y abrir el registro de **Configuración de Shopify**. 2. Modificar el campo **Prefijo empresa (6 dígitos)** si es necesario (ej: `200002`). 3. Presionar el botón `1. Generar EAN-13` en la pestaña **🔖 Barcodes EAN-13**. 4. Validar en la tabla que los códigos se asignen secuencialmente de forma correcta y que el último dígito corresponda al algoritmo verificador EAN-13. 5. Exportar el **Excel (Inventario + Próximos)** y verificar que la hoja 2 muestre 500 códigos subsiguientes listos. ### Fase 2: Sincronización en Staging (Lote Pequeño) 1. Filtrar variantes utilizando el campo de búsqueda o categorías. 2. Sincronizar un lote controlado de 5 a 10 productos a Shopify. 3. Presionar `2. Subir a Shopify` y monitorear el log en vivo o recargar el formulario para ver cómo el progreso incrementa y el contador de "Pendientes" baja. 4. Validar directamente en el panel de Shopify que la variante haya recibido su código de barras correspondiente. ### Fase 3: Ejecución Masiva 1. Una vez validada la Fase 2, ejecutar la sincronización para las más de 1,100 variantes pendientes. 2. El hilo background continuará procesando a un ritmo seguro de ~2 variantes por segundo sin congelar la pantalla de Odoo, completando todo el catálogo de forma autónoma.