Concetti chiave

Company

L'azienda cliente. Top-level di tenancy: ogni risorsa appartiene a una company. I dati dinamici sono isolati in schemi PostgreSQL derivati dall'ID: company_<id> per il Feed Manager e oms_<id> per il dominio OMS (vedi Multi-tenant).

Project

Un dataset prodotti. Configurato con una lista di database fields custom (es. id, title, price, ean, stock, category). Una company può avere più progetti (es. "Catalogo IT", "Outlet", "B2B").

Source / Import

Una fonte di dati che alimenta un progetto. Configurata con:

• connettore (sftp, ftp, https, amazon_sp, …);
• credenziali;
• formato del file (csv, json, xml, …);
• mapping colonna sorgente → field progetto;
• scheduling opzionale (cron).

Un progetto può avere N import attive contemporaneamente.

Export

Una destinazione che riceve i dati del progetto. Due tipologie:

• File: produce un artefatto scaricabile (CSV/JSON/XML/Amazon TXT) accessibile via link firmato.
• Connessione: push diretto verso un marketplace o un endpoint esterno (Amazon SP-API, FTP push, ecc.).

Ogni export può avere regole proprie che filtrano/trasformano i dati senza alterare gli altri export.

Regola

Una condizione + un'azione applicata in step RULES. Il query builder UI (react-querybuilder) genera JSONLogic, valutato dal worker tramite json-logic-engine. Le regole sono raggruppabili e ordinabili (drag-and-drop); l'ordine importa.

Tipi di azione:

• Filter: esclude righe che non matchano la condizione.
• Transform: sostituisce un valore in un campo.
• Exclude: rimuove un campo dall'export per certe righe.

Pipeline Run

Un'esecuzione end-to-end. Conserva: status (pending, running, completed, failed), started_at, completed_at, log strutturati (pipeline_logs table), riferimenti agli import/export coinvolti.

Connessione

Configurazione cifrata di accesso a un provider esterno. Può essere riutilizzata da import, export e canali OMS compatibili. Il registro Italia comprende marketplace, negozi commerce e corrieri con stato ready, controlled, beta o blocked: la presenza nel registro non equivale a disponibilità generale per ogni tenant.

Canale OMS

Configurazione operativa che collega un marketplace o negozio all'OMS. Conserva health della connessione, stato di attivazione, collegamento al progetto Feed Manager e, quando supportato, webhook inbound e policy di pubblicazione stock.

Inventory ledger e reservation

Il ledger registra i movimenti che modificano la giacenza. Una reservation impegna temporaneamente stock per una riga d'ordine senza modificare la quantità fisica. La disponibilità è sempre giacenza - riservato.

Outbox e blocker

L'outbox conserva un effetto asincrono da consegnare al worker o a un provider. Un blocker segnala invece un caso che richiede attenzione o riconciliazione e non può essere risolto con un retry cieco. Vedi Architettura OMS.

Scheduler

Cron-based, orchestrato dal worker. Trigger una pipeline run automaticamente.