Programación y cargas

Una vez implementado el adapter y los módulos sync, los jobs se ejecutan manualmente durante el onboarding y luego se automatizan. Podés usar el Programador de tareas de Windows, cron, systemd, Ansible Semaphore, CI o Docker según tu entorno.

Antes de programar nada, revisá Inicio rápido, los flags CLI y, si empaquetás ejecutables, CI / PyInstaller.

Los comandos exactos dependen de tu sync_registry.py. Las tablas siguientes cubren el template estándar y extensiones habituales en proyectos cliente.

Tres modos de carga

Importante: omitir fechas no significa automáticamente “todo el histórico”. Significa que tu adapter corre sin filtro de fechas y trae lo que devuelve la consulta o vista en ese momento. Acordá con Brightmarket la ventana de onboarding antes de la primera carga.

Podés acotar los datos de dos formas — elegí una por entidad y mantené consistencia:

• En el script: pasá -from y -to con el rango acordado.
• En la fuente: filtrá en vistas o SQL para que, aun sin fechas en el CLI, solo salga el período acordado.

Reglas de fechas:

• -from y -to son un par: si usás uno, el otro es obligatorio.
• Formato siempre YYYYMMDD.
• Ejecutá -test antes de cualquier carga productiva.

Entidades opcionales

Solo ejecutá y programá lo que tu cliente implementa. Si un comando no aplica, omitilo — evita confusiones en onboarding.

Entidades núcleo en la mayoría de clientes: -payment_methods o -accepted_payment_methods, -clients, -skus, -promotions, -tickets.

Onboarding histórico (ejemplo: 2 años de tickets)

Un requisito habitual es cargar ~2 años de tickets, con clientes, SKUs y promociones alineados a ese mismo período. En ese caso usá el modo B con un rango amplio — no hace falta una “carga completa sin fechas”.

python -m src.main -test

# Ejemplo: últimos 2 años (ajustá fechas a tu ventana de onboarding)
python -m src.main -clients -from 20240619 -to 20260619
python -m src.main -skus -from 20240619 -to 20260619
python -m src.main -promotions -from 20240619 -to 20260619
# Preferí -file para onboarding histórico (un JSONL + import async)
python -m src.main -tickets -file -from 20240619 -to 20260619

Las entidades relacionadas deben cubrir la misma ventana de negocio que los tickets: clientes, SKUs y promociones referenciados en esos tickets tienen que existir en Brightmarket antes o durante la carga de tickets.

Orden típico: medios de pago → clientes → SKUs → promociones → tickets. Cada paso puede usar el mismo rango de fechas en lugar de omitir fechas.

Para cargas históricas grandes de tickets, usá -tickets -file (escribe temp/tickets-….jsonl y lo sube a tickets/import/upload). Con -generate-only solo genera el archivo. El default -tickets (sin -file) sigue enviando un POST por ticket.

Si el rango es muy grande, partilo en trozos (por mes o trimestre) con el mismo patrón de -from/-to.

Carga inicial (onboarding)

Seguí este orden durante la puesta en marcha. Las filas extendido aplican solo si tu proyecto registra ese comando en sync_registry.py.

No programes jobs diarios hasta que la carga inicial de cada entidad (en la ventana acordada) haya terminado correctamente y los datos se vean bien en Brightmarket.

Carga diaria (programada)

Después del onboarding, usá el modo C: misma fecha en -from y -to.

python -m src.main -clients -from 20260619 -to 20260619

Qué fecha pasar (hoy vs ayer) es una decisión de negocio: alineala con cómo filtra tu adapter y cuándo la fuente cierra los datos del día.

Ejemplo de cronograma diario

Programá solo las entidades que usa tu cliente — omití filas opcionales si no aplican.

Horarios de referencia para repartir carga sobre la BD y la API:

Recomendaciones:

• Escaloná los jobs para reducir contención en BD y API.
• Una tarea por entidad facilita monitoreo y reintentos.
• No actives la programación diaria hasta completar y verificar la carga inicial de esa entidad.

Fechas dinámicas en el programador

En lugar de hardcodear la fecha en cada tarea, usá un script wrapper que calcule YYYYMMDD y llame a python -m src.main.

Bash (Linux / macOS / cron):

#!/usr/bin/env bash
set -euo pipefail
cd /ruta/a/tu/proyecto
source .venv/bin/activate
DATE=$(date +%Y%m%d)
python -m src.main -clients -from "$DATE" -to "$DATE"

Para sincronizar el día anterior:

DATE=$(date -d "yesterday" +%Y%m%d)   # GNU date
# macOS: DATE=$(date -v-1d +%Y%m%d)
python -m src.main -tickets -from "$DATE" -to "$DATE"

PowerShell (Windows Task Scheduler):

Set-Location C:\ruta\a\tu\proyecto
$date = Get-Date -Format "yyyyMMdd"
& .\.venv\Scripts\python.exe -m src.main -clients -from $date -to $date

En cualquier programador:

• Definí el directorio de trabajo del proyecto.
• Activá el entorno virtual o usá el ejecutable PyInstaller.
• Asegurate de que .env esté disponible (misma carpeta o variables del sistema).

Operación, backfill y reprocesos

El onboarding histórico (modo B) y el reproceso/backfill usan el mismo mecanismo: -from y -to con un rango amplio. La programación diaria (modo C) empieza solo cuando la ventana acordada está cargada y verificada en Brightmarket.

• Logs: el runner del SDK escribe en archivos de log; configurá el prefijo en main.py con configure_logging.
• Fallos: revisá el código de salida del proceso; configurá reintentos y alertas según tu plataforma.
• Rangos grandes: partí en meses o trimestres si una sola corrida es demasiado pesada.
• Orden de entidades: consultá la Guía de implementación para dependencias entre syncs.