Ingestion des flux¶

Status: CURRENT

Objet¶

L'ingestion constitue le point d'entrée technique du Pipeline CMonChoix.

Elle récupère une source marchande, enregistre le contexte de lecture, vérifie que la donnée obtenue est exploitable techniquement et transmet un artefact traçable au Stage.

Elle ne produit aucune vérité métier.

Source marchande
      ↓
Acquisition
      ↓
Validation technique
      ↓
Artefact importé + métadonnées
      ↓
Stage

Responsabilités¶

L'ingestion est responsable de :

résoudre la source configurée pour un feed ;
télécharger ou localiser l'artefact d'entrée ;
identifier son format, son encodage, sa compression et ses paramètres de lecture ;
enregistrer le feed, le marchand, le run et les métadonnées techniques ;
détecter les erreurs d'accès, les fichiers vides ou manifestement invalides ;
fournir au Stage une entrée stable et rejouable.

Frontière stricte¶

L'ingestion ne doit jamais :

classifier un produit ;
normaliser une marque, un modèle, une catégorie ou un attribut ;
corriger une donnée marchande ;
déduire une identité produit ;
calculer un score de qualité ;
choisir une image ;
construire une projection ;
appliquer une règle de verticale.

Ces responsabilités appartiennent aux étapes aval du Pipeline.

Sources supportées¶

Le mécanisme d'ingestion peut accueillir différents transports ou formats :

fichier CSV ;
XML ;
JSON ;
archive compressée ;
API partenaire ;
fichier déjà présent sur un stockage contrôlé.

Le format ne change pas le contrat : la source doit être associée à un identifiant stable et produire un artefact traçable.

Métadonnées minimales¶

Chaque acquisition doit permettre de retrouver au minimum :

feed_id ou identifiant équivalent ;
marchand ou source logique ;
run_id ;
URI ou emplacement d'origine ;
horodatage de récupération ;
format et paramètres de lecture ;
taille connue de l'artefact ;
empreinte lorsque disponible ;
statut final de l'acquisition ;
erreur technique éventuelle.

Ces métadonnées sont nécessaires pour relier les lignes du Stage à l'artefact réellement traité.

Fidélité et intégrité¶

L'artefact acquis doit rester fidèle à ce qui a été reçu.

Les opérations techniques autorisées sont limitées à ce qui est nécessaire pour rendre la source lisible, par exemple :

décompression ;
détection ou validation d'encodage ;
ouverture du flux ;
validation de présence des en-têtes ;
calcul d'une empreinte.

Elles ne doivent pas devenir une normalisation métier implicite.

Une transformation technique doit rester explicable et reproductible.

Runs, lots et reprise¶

L'ingestion s'exécute dans le contexte d'un run identifié.

Le découpage en batches intervient ensuite lors de la lecture et du Stage. L'acquisition doit néanmoins fournir suffisamment d'informations pour :

reprendre un run sans télécharger arbitrairement une nouvelle version de la source ;
distinguer deux imports successifs du même feed ;
éviter qu'un run historique soit mélangé avec un artefact plus récent ;
diagnostiquer précisément l'artefact utilisé par chaque lot.

Lorsque la source distante est instable, l'artefact local du run devient la référence opérationnelle du traitement.

Gestion des erreurs¶

Les erreurs d'ingestion sont techniques et doivent être isolées.

Exemples :

source inaccessible ;
authentification refusée ;
délai dépassé ;
fichier vide ;
compression invalide ;
format non reconnu ;
en-têtes indispensables absents ;
lecture interrompue.

Une erreur doit produire un état explicite et ne doit pas être convertie silencieusement en run réussi avec zéro ligne.

L'échec d'un feed ne doit pas corrompre les autres runs ou les données déjà projetées.

Observabilité¶

Les métriques minimales attendues sont :

acquisition démarrée ;
acquisition réussie ou échouée ;
durée ;
taille de l'artefact ;
empreinte ou version lorsque disponible ;
nombre de tentatives ;
code d'erreur technique ;
identifiants du feed et du run.

Les compteurs d'acquisition, de Stage et de projection représentent des périmètres différents. Ils ne doivent pas être confondus dans les rapports.

Sécurité opérationnelle¶

Avant de rejouer une analyse ou une projection à partir d'un run historique, il faut vérifier que l'artefact et le Stage correspondant sont encore cohérents.

Une projection précédemment altérée par un ancien comportement destructif ne doit pas être utilisée comme base neutre pour mesurer une nouvelle règle. La chaîne doit être régénérée depuis une source fiable avant comparaison.

L'ingestion ne déclenche pas Media Quality. Elle fournit seulement les données et les images marchandes qui pourront être analysées plus tard.

Tests attendus¶

Les tests d'ingestion doivent couvrir au minimum :

succès sur un artefact valide ;
refus d'une source indisponible ou vide ;
traçabilité du feed et du run ;
stabilité de l'empreinte pour un même artefact ;
absence de normalisation métier ;
isolation entre deux runs ;
reprise utilisant le bon artefact ;
production d'un état d'erreur exploitable.

Invariants¶

Neutralité métier¶

L'ingestion transporte et décrit la source. Elle ne l'interprète pas.

Traçabilité¶

Toute ligne traitée en aval doit pouvoir être reliée à un feed, un run et un artefact d'origine.

Rejouabilité¶

Un même artefact et la même configuration de lecture doivent produire la même entrée de Stage.

Isolation¶

Un échec d'acquisition ne doit pas endommager un autre run ni une projection existante.

Erreur explicite¶

Un artefact absent, vide ou illisible ne doit jamais être présenté comme une ingestion réussie.