Spécifications d'ingestion — anatomie

Une spécification d’ingestion est le contrat complet qui transforme un fichier entrant en lignes dans le modèle analytique de Solya. Cette référence en documente chaque partie. Pour l’introduction orientée utilisateur, voir le guide de couche données.

Comment un fichier circule dans une spécification

Détection

Solya décide quelle spécification s’applique à un fichier entrant, en utilisant les règles de détection de la spécification.

Analyse

Le fichier est lu sous forme tabulaire et ses colonnes sont mappées à des champs typés, en utilisant la configuration d’analyse.

Promotion

Un ou plusieurs pipelines de promotion transforment les données analysées et les écrivent dans les tables silver/gold.

Forme de premier niveau

Une spécification est rédigée en JSON (clés en snake_case). Ses champs :

Champ	Requis	Description
`spec_id`	✓	Identifiant canonique, stable entre les versions (ex. `polaris_sav`, `ginkoia_tickets`).
`spec_version`	✓	Numéro de version monotone. Unique par `(spec_id, spec_version)`.
`name`	–	Nom d’affichage.
`description`	–	À quoi sert la spécification.
`pos_system`	–	Identifiant du système source (ex. `polaris`, `ginkoia`).
`status`	✓	`DRAFT` · `ACTIVE` · `DEPRECATED` · `ARCHIVED`.
`scope`	✓	`GLOBAL` (seeds de la plateforme, partagée) ou `ORG` (possédée par l’organisation).
`organization_id`	conditionnel	Requis pour la portée `ORG` ; null pour `GLOBAL`.
`is_default`	✓	Indique si c’est la spécification par défaut pour son `pos_system` + `scope`.
`priority`	✓	Brise-égalité quand plusieurs spécifications correspondent (plus haut gagne). Par défaut `0`.
`detection`	✓	La configuration de détection.
`parsing`	✓	La configuration d’analyse.
`promotions`	–	Un tableau de pipelines de promotion, un par dataset de sortie.
`promotion`	–	Forme de promotion unique dépréciée ; utiliser `promotions`.
`tags`	✓	`{ "systems": [...], "formats": [...] }` pour le filtrage UI.

{
  "spec_id": "ginkoia_tickets",
  "spec_version": 2,
  "name": "Ginkoia — Tickets",
  "pos_system": "ginkoia",
  "status": "ACTIVE",
  "scope": "GLOBAL",
  "is_default": true,
  "priority": 0,
  "detection": { "match_mode": "composite", "rules": [ /* … */ ] },
  "parsing":   { "parser": { /* … */ }, "mapping": { /* … */ } },
  "promotions": [ { /* … */ } ],
  "tags": { "systems": ["ginkoia"], "formats": ["excel"] }
}

Portée : GLOBAL vs ORG

Les spécifications GLOBAL sont fournies par la plateforme et disponibles pour chaque organisation. Elles couvrent les formats POS standards (Polaris, Ginkoia, Kezia, …).
Les spécifications ORG appartiennent à une seule organisation (organization_id défini) et ne sont visibles que pour elle.

Déploiement

L’existence n’est pas la même que l’activation pour une organisation. Une spécification est déployée vers une organisation via un enregistrement d’activation (flag enabled) — ainsi une organisation peut activer/désactiver les spécifications sans que personne n’édite la spécification elle-même. Dans l’API/DTO cela apparaît comme isDeployed sur chaque spécification.

Priorité et résolution de conflits

Quand plus d’une spécification correspond à un fichier :

Les spécifications sont classées par priority (décroissant).
La spec_version plus récente prend préséance.
La première spécification correspondante est appliquée.

Cycle de vie et versioning

DRAFT → ACTIVE ⇄ DEPRECATED → ARCHIVED

Un spec_id peut avoir plusieurs versions ; (spec_id, spec_version) est unique.
Le seeding est idempotent (upsert sur cette paire) ; les spécifications GLOBAL supprimées de l’ensemble de seeds sont archivées, non supprimées, pour préserver l’historique.

Continuez vers les trois éléments constitutifs : Détection, Analyse, et le catalogue Étapes de promotion — puis voir les exemples complets.

Intégration API

Recettes API

Plateforme & modèle de données

Couche décision (référence)

Exploitation & infrastructure

Specs d'ingestion (référence)

Workflows (référence)

Règles de tagging (référence)

Alertes (référence)

Spécifications d'ingestion — anatomie

Comment un fichier circule dans une spécification

Forme de premier niveau

Portée : GLOBAL vs ORG

Déploiement

Priorité et résolution de conflits

Cycle de vie et versioning

​Comment un fichier circule dans une spécification

​Forme de premier niveau

​Portée : GLOBAL vs ORG

​Déploiement

​Priorité et résolution de conflits

​Cycle de vie et versioning

Comment un fichier circule dans une spécification

Forme de premier niveau

Portée : GLOBAL vs ORG

Déploiement

Priorité et résolution de conflits

Cycle de vie et versioning