hazard_odoo/resumen_proyecto.md

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: 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: 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: 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.