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