hazard_odoo/.agents/AGENTS.md

Reglas del Proyecto — Hazard (Odoo 16)

Información General

• Empresa: Hazard (marca de ropa urbana / streetwear)
• Plataforma ERP: Odoo 16 Community con módulos Enterprise
• Ecommerce: Shopify (sincronizado con Odoo vía módulo custom hazard_shopify)
• Servidor: VPS en Plesk bajo el dominio tesscorp.com.mx
• Idioma de comunicación: Siempre responder en español

Arquitectura Docker

Contenedores

Contenedor	Imagen	Puerto Externo	Puerto Interno
odoo-16-hazard-new	hazard-odoo-odoo (custom, basada en odoo:16)	16001	8069
odoo-16-db-hazard-new	postgres:17	No expuesto	5432

Volúmenes y Rutas

• Módulos Enterprise: ./Addons/enterprise → /mnt/enterprise (dentro del contenedor)
• Módulos Custom: ./Addons/custom → /mnt/extra-addons (dentro del contenedor)
• Configuración Odoo: ./Conf/odoo.conf → /etc/odoo/odoo.conf
• Docker Compose: /var/www/vhosts/tesscorp.com.mx/hazard.tesscorp.com.mx/docker-compose.yml
• IP interna del contenedor DB: 172.18.0.2 (usada por MCP Server PostgreSQL)

Base de Datos

• Base de datos principal (producción): hazard_new
• Usuario DB: odoo
• Contraseña DB: odoo

Credenciales Odoo (XML-RPC)

• URL: http://localhost:16001
• Base de datos: hazard_new
• Usuario admin: admin
• Contraseña admin: admin

Módulos Custom Instalados

Módulo	Estado	Ubicación
hazard_shopify	✅ Instalado	Addons/custom/hazard_shopify
hazard_inventory_report	✅ Instalado	Addons/custom/hazard_inventory_report
hazard_website	❌ No instalado	Addons/custom/hazard_website

Otros Módulos de Terceros

• bi_sql_editor — Editor SQL en interfaz Odoo
• query_deluxe — Consultas avanzadas desde Odoo
• sql_request_abstract — Abstracción para consultas SQL
• l10n_mx_sat_sync_itadmin_ee — Sincronización SAT México

Reglas de Desarrollo Obligatorias

Python

• NUNCA usar print(). Siempre usar logging con _logger = logging.getLogger(__name__).
• Usar prefijos descriptivos en logs: _logger.info("[Módulo] Mensaje").
• Siempre agregar docstrings a funciones y clases.

Despliegue de Cambios

1. Cambios en archivos .py (modelos/lógica): Requiere restart del contenedor.

   docker restart odoo-16-hazard-new
   

2. Cambios en estructura de tablas (fields nuevos): Requiere restart + actualización del módulo.

   docker restart odoo-16-hazard-new
   # Luego ejecutar el script de actualización:
   python3 update_module.py
   

3. Cambios solo en XML/vistas/reportes: Solo requiere actualización del módulo (sin restart).

Seguridad y Respaldos

• NUNCA ejecutar UPDATE o DELETE masivos sin respaldo previo.
• Script de respaldo: backup_hazard.sh (respalda DB + código, retención 15 días).
• Los backups se suben a Google Drive automáticamente vía Plesk.

Código de Barras

• Formato EAN13 estandarizado con estructura 20000... (ej. 2000010012749).
• NUNCA crear scripts que alteren la secuencia de códigos de barras.

Archivos que NO se deben modificar

• Módulos en /mnt/enterprise (módulos oficiales de Odoo Enterprise).
• Solo modificar código en /mnt/extra-addons (módulos custom).

Scripts Útiles del Proyecto

Script	Propósito	Comando
backup_hazard.sh	Respaldo completo (DB + código)	bash backup_hazard.sh
update_module.py	Actualizar módulo hazard_shopify via XML-RPC	python3 update_module.py

Conexión MCP Server PostgreSQL

El agente tiene acceso directo de solo lectura a la base de datos hazard_new a través del MCP Server configurado en mcp_config.json. Usar la herramienta query del servidor odoo-postgres para consultas SQL cuando sea necesario inspeccionar datos.

Flujo Custom y Maquila (B2B)

• Regla Crítica: Los productos de las categorías Insumos / Materia Prima y Producto Final Custom pertenecen al flujo B2B/Maquila.
• Estos productos NUNCA deben enviarse ni sincronizarse con Shopify. Están tecnológicamente aislados de la plataforma de Retail.
• Cualquier script, sincronización o lógica de Odoo que interactúe con Shopify debe excluir explícitamente estas categorías.

---

Arquitectura del Módulo hazard_shopify

Modelos Custom (13 modelos)

Modelo Técnico	Archivo	Descripción
shopify.config	models/shopify_config.py	Configuración central de la tienda Shopify. Contiene TODA la lógica de sincronización (~4500 líneas).
shopify.sku.simulation.line	models/sku_simulation_line.py	Líneas de simulación de SKU para mapeo Shopify ↔ Odoo.
shopify.stock.queue	models/shopify_stock_queue.py	Cola asíncrona para sincronización reactiva de inventario.
shopify.cost.line	models/shopify_cost_line.py	Líneas de sincronización de costos desde Shopify.
shopify.publication	models/shopify_publication.py	Canales de venta de Shopify (Online Store, POS, etc.).
shopify.product.publication	models/shopify_product_publication.py	Tabla pivote: estado de publicación de un producto por canal.
shopify.location.mapping	models/shopify_config.py (final)	Mapeo Sucursal Shopify ↔ Almacén/Ubicación Odoo.
shopify.location.wizard	models/shopify_location_wizard.py	Wizard para seleccionar sucursal de Shopify.
shopify.refund.wizard	wizard/shopify_refund_wizard.py	Asistente para reembolsos manuales hacia Shopify.

Modelos Heredados (overrides)

Modelo	Archivo	Qué agrega
product.template	models/product_template.py	Campos shopify_id, shopify_published, shopify_sync_status, lógica de push a Shopify, canales de venta GraphQL, generación de barcodes.
product.product	models/product_template.py (L960+)	Campos CRÍTICOS: shopify_variant_id (llave de variante), shopify_inventory_item_id (llave de inventario). Auto-generación de EAN-13 al crear producto.
sale.order	models/sale_order.py	Campos shopify_order_id, shopify_fulfillment_status, shopify_refund_status, shopify_shipping_title. Lógica BOPIS, fulfillment, cancelación de pickings.
stock.quant	models/stock_quant.py	Override de _update_available_quantity() para encolar sincronización reactiva al cambiar stock.
res.users	models/res_users.py	Override de _search() para ocultar usuarios de soporte (admin, @tesscorp.com.mx).

Campos Shopify Críticos (NUNCA eliminar)

En product.product:

• shopify_variant_id — ID numérico de la variante en Shopify. Es la llave para push de SKU, barcodes y fulfillment.
• shopify_inventory_item_id — ID del ítem de inventario en Shopify. Es la llave para TODA la sincronización de stock.

En product.template:

• shopify_id — ID del producto (template) en Shopify.
• shopify_published — Flag booleano que indica si el producto existe en Shopify.

En sale.order:

• shopify_order_id — ID numérico del pedido en Shopify. Llave para duplicados y fulfillment.
• shopify_shipping_title — Título del método de envío. Se usa para detectar pedidos BOPIS (retiro en tienda).

---

Flujos de Negocio del Conector

Flujo 1: Importación de Pedidos (Shopify → Odoo)

Cron cada N min → cron_import_orders()
  → API REST: GET /orders.json?status=any&updated_at_min=...
  → Por cada pedido: _import_single_shopify_order(s_order)
    → Si ya existe: actualiza estado financiero, fulfillment, refunds, detecta ediciones
    → Si es nuevo: crea res.partner → crea sale.order → auto-confirma
      → Si POS o Fulfilled: auto-valida albarán de salida
      → Si tiene envío: agrega línea de producto ENVIO
      → Si pagado y auto_workflow_payment: publica factura + registra pago
      → Si fecha < cutoff: cancela albaranes (protección histórica)
    → Ejecuta _process_shopify_refunds_automation_logic()

Reglas importantes:

• El producto se busca por: 1° SKU (default_code), 2° shopify_variant_id, 3° nombre (ilike), 4° genérico SHOPIFY-GENERIC.
• Los impuestos se omiten (tax_id: []) porque Shopify ya los incluye en el precio.
• Los descuentos se calculan como porcentaje desde discount_allocations.

Flujo 2: Sincronización de Inventario (Odoo → Shopify)

Odoo es la FUENTE DE VERDAD del stock.

Modo Reactivo (por evento):
  stock.quant._update_available_quantity() → detecta cambio
    → Si producto tiene shopify_inventory_item_id → encola en shopify.stock.queue
    → Cron cada 5 min: process_queue_batch() → procesa 15 productos por lote
    → Llama a _sync_variants_stock_to_shopify()

Modo Cron (masivo periódico):
  cron_sync_inventory_to_shopify() → todas las variantes con shopify_inventory_item_id
    → _sync_variants_stock_to_shopify(variants)
    → API REST: POST /inventory_levels/set.json por cada variante × ubicación

Regla CRÍTICA: Jamás invertir la dirección. El cron cron_sync_inventory_from_shopify está redirigido a cron_sync_inventory_to_shopify por seguridad operativa.

Flujo 3: Fulfillment (Odoo → Shopify)

Desde el pedido en Odoo → botón "Enviar a Shopify"
  → action_notify_shopify_fulfillment()
  → Doble fallback:
    1° Intento: Endpoint legacy POST /orders/{id}/fulfillments.json
    2° Intento: Nuevo endpoint POST /fulfillments.json via fulfillment_orders
  → Escribe shopify_fulfillment_id y shopify_fulfillment_status en sale.order

Flujo 4: BOPIS (Buy Online, Pickup In Store)

Detección automática por shopify_shipping_title:
  Si contiene: OFICINA, RETIRO, PICKUP, SUCURSAL, TIENDA
    → Al confirmar pedido: _create_pickup_internal_transfer()
      → Crea traslado interno: Bodega ALMA → Oficina HRSGOLF
      → Reserva stock y alerta si hay faltantes
    → Al editar pedido en Shopify: _update_pickup_internal_transfer_qty()
      → Ajusta cantidades en traslados existentes o crea complementarios

Flujo 5: Reembolsos y Devoluciones Automáticas

_process_shopify_refunds_automation_logic(sale_order, s_order)
  → Candado Sandbox: Si shopify_sandbox_mode=True, solo procesa SKUs con "PRUEBA"
  → Por cada refund no procesado:
    A. Devolución de Stock: Crea stock.picking de entrada + auto-valida
    B. Nota de Crédito: Crea account.move tipo out_refund en borrador
  → Registra refund_id en shopify_refund_ids_processed para idempotencia

ADVERTENCIA: Este flujo ya opera en producción. Cambios aquí impactan contabilidad real y stock físico.

Flujo 6: Publicación de Productos (Odoo → Shopify)

Desde ficha de producto → botón "Publicar en Shopify"
  → action_push_to_shopify()
    → Si shopify_id existe: PUT /products/{id}.json (actualización)
    → Si no existe: POST /products.json (creación)
  → Sincroniza canales de venta vía API GraphQL (publishablePublish mutation)
  → Sube imagen si tiene (POST /products/{id}/images.json)

---

Sistema de Crons (7 Acciones Planificadas)

#	XML ID	Propósito	Frecuencia Default	Activo	Método
1	ir_cron_shopify_import_orders	Importar pedidos Shopify → Odoo	5 min	✅	cron_import_orders()
2	ir_cron_shopify_sync_inventory	Stock Odoo → Shopify (masivo)	12 horas	❌	cron_sync_inventory_to_shopify()
3	ir_cron_shopify_refresh_tokens	Renovar tokens OAuth (24h Shopify)	20 horas	✅	cron_refresh_tokens()
4	ir_cron_shopify_download_images	Descargar imágenes (manual/batch)	1 min	❌	_cron_download_images_batch()
5	ir_cron_shopify_auto_image_sync	Auto-descargar imágenes nuevas	2 horas	✅	cron_auto_download_images()
6	ir_cron_shopify_process_stock_queue	Procesar cola de stock reactiva	5 min	✅	process_queue_batch()
7	ir_cron_shopify_clean_stock_queue	Limpiar cola completada (+7 días)	1 día	✅	clean_done_queue()

Reglas sobre Crons:

• Los crons 1, 2 y 5 se actualizan dinámicamente desde el write() de shopify.config cuando el usuario cambia la frecuencia en la interfaz.
• NUNCA desactivar manualmente los crons 3 (tokens) o 6 (cola de stock) — rompe la operación.
• El cron 4 se activa/desactiva automáticamente (botón → se activa, termina → se desactiva).

---

API de Shopify

Configuración Técnica

• Versión API REST: 2024-01
• Versión API GraphQL: 2024-01
• Autenticación: Token de acceso (shpat_...) en header X-Shopify-Access-Token
• Renovación de Token: OAuth con client_id y client_secret, renovación automática cada 20h vía cron.
• Rate Limiting: time.sleep(0.5) entre requests (2 req/s). Reintentos automáticos en HTTP 429 (espera 5s, 3 intentos).

Endpoints Usados

Método	Endpoint	Propósito
GET	/orders.json	Importar pedidos
GET	/products.json	Importar catálogo
POST/PUT	/products/{id}.json	Crear/actualizar productos
POST	/products/{id}/images.json	Subir imágenes
POST	/inventory_levels/set.json	Sincronizar stock
GET	/locations.json	Obtener sucursales
POST	/orders/{id}/fulfillments.json	Fulfillment legacy
GET	/orders/{id}/fulfillment_orders.json	Fulfillment orders (nuevo)
POST	/fulfillments.json	Fulfillment nuevo API
POST	/orders/{id}/refunds/calculate.json	Calcular reembolso
POST	/orders/{id}/refunds.json	Ejecutar reembolso
PUT	/variants/{id}.json	Actualizar variante (SKU, barcode)
GET	/inventory_levels.json	Consultar niveles de stock
POST (GraphQL)	/graphql.json	Costos, canales de venta, publicaciones

---

Grupos de Seguridad del Módulo

Definidos en security/hazard_security.xml. Categoría: Hazard / HRSGOLF.

XML ID	Nombre	Permisos	Hereda de
group_hazard_designer	Diseño	Crea productos, sube fotos. Sin precios ni Shopify.	base.group_user
group_hazard_warehouse	Bodega	Stock y tracking. Sin precios.	stock.group_stock_user
group_hazard_sales	Ventas B2B	Cotizaciones/pedidos. Precios solo lectura.	sales_team.group_sale_salesman
group_hazard_finance	Admin/Finanzas	Control total: precios, catálogo, Shopify.	sales_team.group_sale_salesman_all_leads

Regla: Solo group_hazard_finance tiene acceso de escritura a shopify.config. Los demás tienen solo lectura o sin acceso.

---

Cola Asíncrona de Stock (shopify.stock.queue)

Mecanismo reactivo para sincronizar inventario en tiempo semi-real:

1. Trigger: stock.quant._update_available_quantity() detecta cualquier cambio de stock en Odoo.
2. Filtro: Solo encola productos con shopify_inventory_item_id (vinculados a Shopify).
3. Encolado: Crea registro en shopify.stock.queue con estado pending (evita duplicados).
4. Procesamiento: Cron cada 5 min → process_queue_batch() → procesa 15 productos por lote.
5. Limpieza: Cron diario → clean_done_queue() → elimina registros done con más de 7 días.

Condición: Solo procesa si auto_sync_products = True en la configuración de Shopify.

---

Lógica de SKU (sku_logic.py)

Formato estándar: HRS-{TIPO}-{MODELO}-{GENERO}-{COLOR}-{TALLA}

Ejemplo: HRS-POL-CLUB-M-BLK-L = Polo Club, Hombre, Negro, Talla L

Diccionarios de Mapeo (hardcoded)

• CATEGORIES: hat→HAT, polo→POL, hoodie→HOD, bag→BAG, glove→GLV, towel→TWL, etc.
• GENDERS: men→M, women→W, kids→K. Default U (unisex) para accesorios.
• COLORS: black→BLK, white→WHT, green→GRN, blue→BLU, red→RED, etc.

Regla: NUNCA modificar estos diccionarios sin aprobación explícita del cliente. Un cambio rompe la consistencia de los SKUs existentes.

---

Reglas de Seguridad Adicionales

Override de Usuarios (res_users.py)

• El modelo res.users oculta los usuarios de soporte (admin y @tesscorp.com.mx) de los usuarios del cliente.
• NUNCA eliminar este override. Los usuarios del cliente no deben ver las cuentas de desarrollo.

Sandbox de Reembolsos

• El campo shopify_sandbox_mode en shopify.config protege la base de datos de producción.
• Cuando está activo (por defecto), la automatización de reembolsos solo procesa pedidos con SKUs que contienen la palabra PRUEBA.
• NUNCA desactivar este modo sin autorización explícita y pruebas exhaustivas.

Producto Genérico de Envío

• El producto con SKU ENVIO (tipo servicio) se usa para las líneas de costo de envío importadas de Shopify.
• Se crea automáticamente si no existe. No eliminar.

Cliente Genérico POS

• El contacto Cliente POS Shopify se reutiliza para ventas POS sin datos de cliente.
• No eliminar ni renombrar. Evita crear contactos basura por cada venta POS.

Log Persistente de Crons

• Ruta dentro del contenedor: /var/lib/odoo/shopify_cron.log
• Volumen Docker: odoo-web-data-hazard-new
• Máximo 5 MB con rotación automática.
• Para consultar: docker exec odoo-16-hazard-new cat /var/lib/odoo/shopify_cron.log

Fecha de Corte de Importación

• El campo shopify_import_cutoff_date en shopify.config protege el inventario de pedidos históricos.
• Pedidos creados ANTES de esta fecha se importan pero sus albaranes de salida se cancelan automáticamente.
• No modificar esta fecha sin entender el impacto en el stock.

---

Autorización de Borrado

• NUNCA elimines archivos, directorios o recursos proactivamente sin la autorización explícita y directa del usuario.
• Si el usuario pregunta "¿Puedo borrar esto?", "¿Es seguro borrar esto?" o similar, limítate EXCLUSIVAMENTE a responder a su pregunta proporcionando la información.
• NO asumas que el usuario quiere que tú ejecutes el comando de borrado. Espera a que el usuario diga explícitamente "Bórralo", "Por favor elimínalo tú", o que ejecute la acción él mismo.

Limpieza y Scripts Temporales

• NUNCA crees scripts temporales de Python (o bash) directamente en la carpeta raíz del proyecto.
• Si necesitas crear un script (.py, .sh, etc.) para una tarea, colócalo SIEMPRE dentro del directorio scripts/. Crea este directorio si no existe.

Ejecución y Cambios de Código

• NUNCA apliques cambios en el código ni ejecutes comandos que modifiquen el entorno sin antes consultar y recibir la autorización explícita ("Adelante", "Ok", "Dale", etc.) del usuario. Debes plantear la solución primero y esperar aprobación.