Documentation officielle

Data Flow
Builder

Générez des fichiers de données de test structurées — CSV, positionnel, JSON, XML — avec des données françaises réalistes (NIR, SIRET, IBAN, communes).

FormatCSV · Positionnel · JSON · XML
DonnéesNIR · SIRET · IBAN · Adresses · Communes via API gouv.fr
InterfaceDesktop multiplateforme (Windows / macOS / Linux)
CohérenceLiaison automatique NIR ↔ Prénom ↔ Civilité ↔ Date naissance
OrganisationDossiers imbriqués · Drag & drop · Import/Export JSON
ConformitéVérification d'un fichier réel vs mapping : encodage, types, formats, SIRET, NIR, IBAN…
StackPython 3.11+ · Flet · Faker FR
🚀
Installation
Prérequis, pip, binaires autonomes, structure des données.
📐
Concepts fondamentaux
Flux, sections en-tête/données/pied de page, champs, dossiers.
📋
Types de champs
Référence complète alpha, num, date, bool, decimal.
🔗
Cohérence NIR
Synchronisation automatique NIR ↔ prénom ↔ civilité ↔ date.
🔢
Presets
Valeurs prédéfinies, distribution pondérée, format JSON.
📦
Import / Export
Format JSON complet, partage de templates, rétrocompatibilité.
Vérification de conformité
Contrôlez un fichier réel par rapport au mapping d'un flux : encodage, délimiteur, types, formats, SIRET, NIR…

🚀 Installation & Démarrage

Data Flow Builder fonctionne sur Windows, macOS et Linux. Choisissez l'option adaptée à votre usage.

Prérequis

ComposantVersion minimaleNote
Python3.11+Requis uniquement pour l'installation depuis les sources
pipDernière versionpip install --upgrade pip
OSWindows 10+, macOS 12+, Ubuntu 20.04+

Option 1 — Depuis les sources

Recommandée pour les développeurs souhaitant modifier ou contribuer au projet.

# 1. Cloner le dépôt
git clone https://github.com/votre-org/DataFlowBuilder.git
cd DataFlowBuilder

# 2. Créer un environnement virtuel (recommandé)
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate.bat     # Windows

# 3. Installer
pip install -e .

# 4. Lancer
python main.py

Option 2 — Binaire autonome

Aucune installation de Python requise. Téléchargez depuis la page Releases.

SystèmeFichier
Windows 64-bitDataFlowBuilder-windows
macOS Apple SiliconDataFlowBuilder-macos
Linux 64-bitDataFlowBuilder-linux
ℹ️
Sur macOS, au premier lancement, faire clic droit → Ouvrir pour contourner Gatekeeper.

Dépendances de développement

pip install -e ".[dev]"
pre-commit install

Installe : pytest, ruff, mypy, bandit, pre-commit, pyinstaller.

Structure des données persistées

{tempdir}/DataFlowBuilder/
├── flows/                   # Un fichier JSON par flux
│   └── flow_1234567890.json
├── data/
│   ├── folders.json         # Arborescence des dossiers
│   └── communes_cache.json  # Cache API géographique
├── generated/               # Données générées (un sous-dossier par flux)
│   └── nom_du_flux/
│       └── export_2024-01-15.csv
├── assets/                  # Ressources applicatives (favicon.ico)
└── logs/
    └── dataflow_builder.log
💡
Windows : %TEMP%\DataFlowBuilder\Linux/macOS : /tmp/DataFlowBuilder/

Premier lancement

  1. L'écran d'accueil Mes flux s'affiche — vide au premier démarrage
  2. Cliquez sur + dans la barre latérale pour créer un flux
  3. L'éditeur s'ouvre sur un flux vierge nommé "Nouveau flux"
  4. Configurez le format, ajoutez des champs, cliquez Aperçu
  5. Sauvegarder pour conserver le flux

📐 Concepts fondamentaux

Comprendre la hiérarchie Flux → Sections → Champs est essentiel pour tirer le meilleur parti de Data Flow Builder.

Vue d'ensemble

Application
└── Dossiers (arborescence illimitée)
    └── Flux (template de fichier)
        ├── Configuration  (format, encodage, nb lignes…)
        ├── En-tête        (0 ou 1 ligne fixe en début)
        ├── Données        (1-N structures × numRows répétitions)
        │   ├── Ligne A  [champ1, champ2, …]
        │   └── Ligne B  [champ1, champ2, …]
        └── Pied de page   (0 ou 1 ligne fixe en fin)

Le Flux

Un flux est le concept central — un template de fichier de données.

ParamètreValeurs possiblesDescription
Formatcsv · fixed · json · xmlFormat du fichier de sortie
Délimiteur, · ; · | · \tSéparateur de champs (CSV)
Saut de ligneCRLF · LFWindows ou Unix
EncodageUTF-8 · ISO-8859-1Encodage du fichier généré
Nombre de lignesEntier ≥ 1Répétitions des lignes de données
Délimiteur finaltrue · falseAjoute le délimiteur en fin de chaque ligne (CSV)

Les Sections

En-tête (headerFields)

Générée une seule fois en début de fichier. Typiquement : enregistrement de contrôle, date de création, compteur de lignes.

Données (fields)

Contient une ou plusieurs structures de lignes, chacune répétée numRows fois.

Exemple — 2 structures, numRows = 3 :
[En-tête]
[Ligne A] ← répétition 1
[Ligne B] ← répétition 1
[Ligne A] ← répétition 2
[Ligne B] ← répétition 2
[Ligne A] ← répétition 3
[Ligne B] ← répétition 3
[Pied de page]

Pied de page (footerFields)

Générée une seule fois en fin de fichier. Utile pour les enregistrements de clôture ou les totaux.

Le Champ

Un champ produit une valeur par ligne générée. Il a un type de base et un sous-type.

PropriétéDescription
NomLibellé affiché dans l'interface
Type de basealpha, num, date, bool, decimal
Sous-typeSpécialisation (email, NIR, SIRET, dateNaissance…)
LongueurTaille maximale (troncature automatique)
Inclure dans la sortieSi décoché : champ calculé mais non écrit dans le fichier

Priorité de génération

1. Compteur de lignes  (subType == "compteurLignes")
2. Concaténation       (subType == "concat")
3. Incrément           (num/none + increment == true)
4. Preset prédéfini    (si useRandom == false)
5. Génération aléatoire (Faker FR + logique métier)

Les 4 onglets de l'éditeur

OngletContenu
⚙️ ConfigurationFormat, délimiteur, encodage, nombre de lignes…
📋 En-têteChamps de la ligne d'en-tête
📊 DonnéesStructures de lignes (multi-lignes supporté)
📄 Pied de pageChamps du pied de page

📋 Référence des types de champs

5 types de base, 30+ sous-types spécialisés pour les données françaises.

🔤 Alpha — Champs textuels

alpha / none — Texte libre

Génère une chaîne aléatoire ou applique la valeur par défaut si elle est renseignée.

ParamètreValeursDéfaut
LongueurEntier10
Valeur par défautTexte libre""
Paddingnone · before · after · bothnone
Caractère de padding1 caractère" "

alpha / email

Adresse e-mail réaliste via Faker FR. Format : [email protected]. Longueur défaut : 50.

alpha / phone / phonePlus33

Numéro FR national (0X XX XX XX XX, long. 14) ou international (+33 X XX XX XX XX, long. 15).

alpha / nom / prenom

Nom de famille ou prénom français (Faker FR). Longueur défaut : 30.

alpha / prenomNir

Prénom cohérent avec le genre du NIR de la même ligne. NIR 1… → masculin, 2… → féminin. Le lien vers le champ NIR source est configurable (voir Cohérence NIR).

alpha / civilite

ParamètreValeurs
Catégorieclassiques · administratives · professionnelles
Format de sortiecode (M, Mme) · label (Monsieur, Madame)
CatégorieCivilités
classiquesM, Mme, Mlle
administrativesM, Mme, Dr, Pr, Me, Fr, Sr, Père, Abbé, Rabbin, Imam
professionnellesDr, Pr, Me, Ing, Dir, Pres, Chef

alpha / civiliteNir

Civilité cohérente avec le genre du NIR. Mêmes paramètres que civilite. Le lien vers le champ NIR source est configurable (voir Cohérence NIR).

alpha / adresse / adresseComplete

adresse : numéro + rue (long. 100). adresseComplete : adresse complète sur une ligne (long. 200). adresseComplete peut être liée à un champ codePostal pour inclure automatiquement la commune et le code postal correspondants.

alpha / ville

Commune française via API geo.api.gouv.fr. Filtrable par préfixe de code postal (31*, 75*… ou * pour toutes les communes). Peut être liée à un champ codePostal de la même ligne pour garantir la cohérence commune/code postal (voir API Géographique).

alpha / lieuNaissance

Commune de naissance cohérente avec le département extrait du NIR (positions 5-6). Le champ NIR source est configurable.

alpha / codeApe

Code APE/NAF français. Format : XXXXZ (ex : 6201Z). Longueur défaut : 5.

alpha / iban

IBAN français. Format : FR76 XXXX XXXX XXXX XXXX XXXX XXX. Longueur défaut : 27.

alpha / concat — Concaténation

Assemble champs existants et textes libres dans un ordre défini. L'éditeur dédié permet d'ajouter des champs ou des textes libres et de les réordonner via les boutons ↑ ↓.

"concatItems": [
  { "type": "field", "fieldId": "abc123" },
  { "type": "text",  "value": "_" },
  { "type": "field", "fieldId": "def456" }
]

🔢 Num — Champs numériques

num / none — Entier libre

Entier aléatoire ou incrémenté. Supporte padding (ex: 00001000).

ParamètreDéfaut
Longueur10
Incrément actiffalse
Valeur de départ1
Paddingnone

num / nir — NIR (Sécurité Sociale)

15 chiffres structurés selon les règles françaises. Voir Cohérence NIR pour les liaisons automatiques.

Position :  0   1-2  3-4  5-6   7-9   10-12  13-14
Contenu :  Sexe Année Mois Dept Commune Ordre   Clé
Exemple :   1    85   04   69   123     456     78

num / siret

SIRET français à 14 chiffres (SIREN 9 chiffres + NIC 5 chiffres).

num / codePostal / codeInsee

Code postal ou INSEE à 5 chiffres. Filtrable par département.

num / departement / departementNaissance

Département FR (01–95). departementNaissance extrait du NIR.

num / compteurLignes

Nombre total de lignes du fichier (en-tête + données × N + pied de page). Calculé avant la génération.

📅 Date

Formats disponibles

FormatExempleLongueur
DD/MM/YYYY15/04/198510
YYYY-MM-DD1985-04-1510
YYYYMMDD198504158
DDMMYYYY150419858
timestamp482457600~10
YYYYMMDDHHmmss1985041512000014
DD/MM/YYYY HH:mm:ss15/04/1985 12:00:0019

date / dateNaissance

Date cohérente avec l'année/mois du NIR. Tous les formats supportés. Le champ NIR source est configurable. Voir Cohérence NIR.

✅ Bool

Sous-typeValeur 1Valeur 2Long.Notes
noneAléatoire parmi les valeurs du preset3Valeur par défaut configurable
ONON1
OUINONOUINON3
OKKOOKKO2
BINAIRE011
💡
Pour une distribution pondérée (ex. 70% O / 30% N), utilisez les Presets.

💰 Decimal

ParamètreValeursDéfaut
Séparateur décimal. · ,.
Nombre de décimales0–102
Paddingnone · before · after · bothnone

⚙️ Configuration d'un champ

Référence complète de tous les paramètres JSON d'un champ, avec leurs valeurs par défaut.

Paramètres communs (tous types)

ParamètreClé JSONTypeDéfaut
Nomnamestring""
Catégoriecategorystring""
Type de basetypeenum"alpha"
Sous-typesubTypestring"none"
Longueurlengthint10
Inclure dans la sortieincludeInOutputbooltrue
Commentairecommentstring""
ID (auto-généré)idstring
Lien de cohérencelinkedFieldIdstring""

Exemple JSON complet

{
  "id": "abc123",
  "name": "Code client",
  "category": "Identification",
  "type": "num",
  "subType": "none",
  "length": 8,
  "includeInOutput": true,

  // Padding (alpha/none, num/none, decimal)
  "padding": "before",
  "paddingChar": "0",

  // Valeur fixe / valeur par défaut
  "defaultValue": "",

  // Incrément (num/none uniquement)
  "increment": true,
  "incrementStart": 1000,

  // Date
  "format": "DD/MM/YYYY",
  "todayDate": false,
  "dateMinEnabled": true,
  "dateMinToday": false,
  "dateMinExclusive": false,
  "dateMin": "01/01/2020",
  "dateMaxEnabled": true,
  "dateMaxToday": true,
  "dateMaxExclusive": false,
  "dateMax": "",

  // Concaténation (alpha/concat)
  "concatItems": [
    { "type": "field", "fieldId": "abc123" },
    { "type": "text",  "value": "_" }
  ],

  // Filtre géographique
  "codePostalFilter": "31",

  // Lien de cohérence (champs dépendants : ville, adresseComplete, civiliteNir, prenomNir,
  //                    lieuNaissance, dateNaissance, departementNaissance)
  // "" = auto (lie au premier champ source trouvé dans la ligne)
  // "__none__" = indépendant (génère sans tenir compte des autres champs de la ligne)
  // "" = lié au champ dont l'ID est 
  "linkedFieldId": "",

  // Civilité
  "civiliteCategorie": "classiques",
  "civiliteOutput": "code",

  // Décimal
  "decimalSeparator": ",",
  "decimalPlaces": 2,

  "comment": "Identifiant numérique unique"
}

Tableau — Paramètres par type

Paramètrealpha/nonealpha/concatalpha/civilitenum/nonenum/nirdatebooldecimal
Longueur
Padding
Valeur par défaut
Incrément
Format / Bornes date
Config civilité
Filtre départementvillepostal/insee
Concat items
Décimales

🔗 Cohérence NIR

Data Flow Builder gère automatiquement la cohérence entre un champ NIR et les champs qui en dépendent sur la même ligne.

Principe

num/nir ──► alpha/prenomNir          (prénom selon le sexe)
        ├── alpha/civiliteNir        (civilité selon le sexe)
        ├── date/dateNaissance       (date extraite de l'année/mois)
        ├── num/departementNaissance (département extrait)
        └── alpha/lieuNaissance      (commune du département)

Structure du NIR

185046912345678
│ ││ ││ ││ ││  │
│ ││ ││ ││ │└──┘── Clé  (positions 13-14)
│ ││ ││ ││ └─────── Ordre (positions 10-12)
│ ││ ││ │└───────── Commune (positions 7-9)
│ ││ ││ └─────────── Département (positions 5-6) → 69 = Rhône
│ ││ │└───────────── Mois de naissance (positions 3-4) → 04 = Avril
│ │└─────────────── Année (positions 1-2) → 85 → 1985
│ └───────────────── Sexe (position 0) → 1 = Masculin
└─────────────────── Exemple complet

Activation

Il suffit d'ajouter les deux types de champs dans la même ligne de données :

  1. Ajouter un champ num / nir
  2. Ajouter un ou plusieurs champs liés (prenomNir, civiliteNir, dateNaissance…)
  3. Le moteur de dépendances gère l'ordre automatiquement

Comportement par champ lié

ChampLogique
alpha/prenomNirNIR 1… → prénom masculin FR, NIR 2… → prénom féminin FR
alpha/civiliteNirNIR 1… → M/Monsieur, NIR 2… → Mme/Madame
date/dateNaissanceAnnée et mois extraits du NIR, jour aléatoire 1–28
num/departementNaissancePositions 5-6 du NIR directement
alpha/lieuNaissanceCommune aléatoire du département extrait

Exemple de ligne cohérente

NIR              : 185046912345678
Civilité NIR     : M
Prénom NIR       : Jean
Date naissance   : 15/04/1985  (mois=04, année=85→1985, jour aléatoire)
Département naiss: 69
Toutes ces valeurs sont mutuellement cohérentes : sexe masculin, né en avril 1985 dans le Rhône.

Cas particuliers

SituationComportement
Pas de champ nir dans la ligneValeurs aléatoires non cohérentes
Plusieurs champs nir dans la lignePar défaut, le premier dans l'ordre de génération est utilisé. Configurable via le lien de cohérence.
NIR invalideFallback sur génération aléatoire
API indisponible (lieuNaissance)Cache local ou 10 villes de fallback

Contrôle des liaisons

Les champs dépendants (prenomNir, civiliteNir, dateNaissance, departementNaissance, lieuNaissance) disposent d'un paramètre Lien de cohérence qui contrôle le comportement de liaison.

Valeur linkedFieldIdComportementCas d'usage
"" (auto)Se lie au premier champ nir trouvé dans la ligne (ordre de génération)Cas standard, un seul NIR dans la ligne
"__none__" (indépendant)Génère sans consulter aucun champ NIRChamp à générer indépendamment de tout NIR
"<id>" (lié)Se lie explicitement au champ dont l'ID est <id>Plusieurs NIR dans la ligne — chaque dépendant pointe son propre NIR
// Exemple : 2 NIR indépendants sur la même ligne
// Champ NIR 1 (id: "nir-titulaire")
{ "type": "num", "subType": "nir", "id": "nir-titulaire" }

// Prénom lié au NIR 1
{ "type": "alpha", "subType": "prenomNir", "linkedFieldId": "nir-titulaire" }

// Champ NIR 2 (id: "nir-conjoint")
{ "type": "num", "subType": "nir", "id": "nir-conjoint" }

// Prénom lié au NIR 2 — indépendant du premier
{ "type": "alpha", "subType": "prenomNir", "linkedFieldId": "nir-conjoint" }
ℹ️
La même logique s'applique aux champs géographiques : un champ ville peut être lié à un codePostal spécifique de la ligne via linkedFieldId.

🗓️ Champs Date

Les champs de type date offrent un contrôle fin sur les formats de sortie, les bornes et le comportement dynamique.

Formats de sortie

CléExempleLongueurPlaceholder saisie
DD/MM/YYYY15/04/198510JJ/MM/AAAA
YYYY-MM-DD1985-04-1510AAAA-MM-JJ
DD-MM-YYYY15-04-198510JJ-MM-AAAA
MM/DD/YYYY04/15/198510MM/JJ/AAAA
YYYYMMDD198504158AAAAMMJJ
DDMMYYYY150419858JJMMAAAA
timestamp482457600~10
YYYYMMDDHHmmss1985041512000014AAAAMMJJHHmmss
DD/MM/YYYY HH:mm:ss15/04/1985 12:00:0019JJ/MM/AAAA HH:mm:ss

Paramètres de bornes

ParamètreClé JSONDéfautDescription
Date du jourtodayDatefalseGénère toujours la date d'exécution (ignore les bornes)
Borne min activéedateMinEnabledfalseActive la contrainte minimale
Borne min = aujourd'huidateMinTodayfalseBorne dynamique = date du jour
Borne min exclusivedateMinExclusivefalse> au lieu de >=
Borne min (valeur)dateMin""Date fixe dans le format choisi
Borne max activéedateMaxEnabledfalseActive la contrainte maximale
Borne max = aujourd'huidateMaxTodayfalseBorne dynamique = date du jour
Borne max exclusivedateMaxExclusivefalse< au lieu de <=
Borne max (valeur)dateMax""Date fixe dans le format choisi

Exemples de configuration

Dates sur les 12 derniers mois

{
  "dateMinEnabled": true,
  "dateMin": "01/04/2024",   // il y a 12 mois
  "dateMaxEnabled": true,
  "dateMaxToday": true       // borne max = aujourd'hui
}

Dates dans le futur (strictement)

{
  "dateMinEnabled": true,
  "dateMinToday": true,
  "dateMinExclusive": true   // strictement > aujourd'hui
}

Date fixe (toujours identique)

{
  "todayDate": false,
  "defaultValue": "01/01/2024"
}

Date de naissance NIR

Le sous-type dateNaissance extrait l'année et le mois du NIR de la même ligne :

🔢 Presets de valeurs

Les presets permettent de définir une liste de valeurs prédéfinies pour un champ. Le générateur pioche aléatoirement dans cette liste.

Modes de fonctionnement

ModeComportement
Valeurs aléatoires (défaut)Le preset est ignoré, génération normale
Valeurs prédéfiniesTirage aléatoire uniforme dans la liste

Accès

Dans l'éditeur de champ, cliquez sur le bouton "Presets" (🎲). Une fenêtre de dialogue s'ouvre.

Distribution pondérée

Chaque entrée a une probabilité égale d'être tirée. Pour simuler une distribution pondérée, dupliquez les entrées :

Cible : 75% ACTIF, 25% INACTIF
→ Ajouter :
  ACTIF    (entrée 1)
  ACTIF    (entrée 2)
  ACTIF    (entrée 3)
  INACTIF  (entrée 4)

Cas d'usage typiques

ChampValeurs de preset utiles
Type d'enregistrement01, 02, 99
StatutACTIF, INACTIF, EN_ATTENTE
Code paysFR, BE, CH, LU
Code deviseEUR, USD, GBP
Centre de coûtCC001, CC002, CC003

Format JSON

"presets": {
  "field-id-abc123": {
    "useRandom": false,
    "values": [
      { "value": "ACTIF",    "comment": "Salarié actif",    "isDefault": true  },
      { "value": "INACTIF",  "comment": "Salarié inactif",  "isDefault": false },
      { "value": "SUSPENDU", "comment": "Compte suspendu",  "isDefault": false }
    ]
  }
}
ℹ️
Les presets sont sauvegardés avec le flux et inclus dans l'export JSON.

📁 Gestion des dossiers

Organisez vos flux en arborescence de dossiers (profondeur illimitée) depuis la barre latérale gauche.

Structure de l'arbre

📁 Tous les flux       ← Vue globale
📥 Sans dossier        ← Flux non classés
📁 RH
   📁 Paie
   📁 Formation
📁 Finance
📁 Clients

Actions disponibles

ActionDescription
Nouveau dossierCréé à la racine ou sous un dossier existant
RenommerModifier le nom du dossier courant
Sous-dossierCréer un enfant du dossier courant
SupprimerSupprime le dossier + sous-dossiers ; les flux vont à la racine

Déplacer un flux

Menu déroulant : sur la carte flux, ouvrez "Déplacer…" et sélectionnez le dossier cible.

Drag & drop : maintenez le clic sur l'icône ⠿ et déposez dans la barre latérale.

⚠️
La suppression d'un dossier est irréversible. Les flux contenus sont déplacés à la racine, pas supprimés.

Format de stockage JSON

[
  {
    "id": "1712345678.123",
    "name": "RH",
    "parentId": null,
    "created": "2024-04-05 10:00:00"
  },
  {
    "id": "1712345699.456",
    "name": "Paie",
    "parentId": "1712345678.123",
    "created": "2024-04-05 10:05:00"
  }
]

🌍 API Géographique

Les communes françaises sont chargées depuis l'API officielle du gouvernement, avec cache local et fallback offline.

Source

https://geo.api.gouv.fr/communes

API gratuite, sans authentification, maintenue par Etalab.

Stratégie de chargement

Premier lancement :  API gov ──► Cache JSON ──► Application
Lancements suivants: Cache JSON ──────────────► Application
API indisponible :   Fallback (10 villes) ─────► Application

Communes de fallback

CommuneDépartement
Paris75
Marseille13
Lyon69
Toulouse31
Nice06
Nantes44
Bordeaux33
Lille59
Rennes35
Strasbourg67

Filtrage par code postal

Le paramètre codePostalFilter filtre les codes postaux avec support des wildcards :

ValeurEffet
*Toutes les communes françaises (aucun filtre)
31*Codes commençant par 31 → Haute-Garonne
75*Codes commençant par 75 → Paris
97*Codes commençant par 97 → DOM-TOM
*10*Codes contenant 10
*25Codes se terminant par 25
33000Correspondance exacte (code postal précis)
ℹ️
Le filtre s'applique sur les codes postaux (ex : 31* pour la Haute-Garonne), pas sur les codes de département. La syntaxe supporte les wildcards * en préfixe, suffixe ou les deux.

Cohérence ville / code postal

Les champs ville et adresseComplete peuvent être liés à un champ codePostal de la même ligne pour garantir la cohérence entre les deux valeurs.

Valeur linkedFieldIdComportement
"" (auto)Se lie au premier codePostal de la ligne, puis utilise son filtre département propre
"__none__" (indépendant)Ignore les champs codePostal présents — utilise uniquement son propre filtre
"<id>" (lié)Se synchronise avec le code postal dont l'ID est <id>
⚠️
Sans linkedFieldId explicite, si plusieurs champs codePostal coexistent dans la ligne avec des filtres différents, le dernier trouvé peut prendre le dessus. Préférez un lien explicite dans ce cas.

Résolution de problèmes

ProblèmeSolution
Toujours les mêmes 10 villesAPI indisponible au premier lancement — vérifier la connexion et supprimer le cache
Supprimer le cacheEffacer {appdir}/data/communes_cache.json et redémarrer

📦 Import / Export JSON

Les flux peuvent être exportés en JSON et partagés entre utilisateurs ou machines. Le fichier contient la définition complète, pas les données générées.

Exporter

Depuis la vue d'accueil : icône sur la carte du flux → choisir l'emplacement.

ℹ️
Le bouton Exporter dans l'éditeur génère le fichier de données (CSV, etc.), pas la définition du flux.

Importer

Vue d'accueil → Importer → sélectionner un .json. Si vous êtes dans un dossier spécifique, le flux est automatiquement affecté à ce dossier.

Format JSON complet

{
  // Métadonnées
  "id": "1712345678.123",
  "name": "Flux salarié mensuel",
  "description": "Fichier RH recette Paie",
  "folderId": null,
  "format": "csv",
  "delimiter": ";",
  "lineEnding": "CRLF",
  "encoding": "UTF-8",
  "hasHeader": true,
  "numRows": 500,
  "trailingDelimiter": false,

  // En-tête
  "headerFields": [ /* tableau de champs */ ],

  // Lignes de données
  "fields": [
    {
      "id": "line-001",
      "name": "Ligne salarié",
      "fields": [
        {
          "id": "fld-nir",
          "name": "NIR",
          "type": "num",
          "subType": "nir",
          "length": 15,
          "includeInOutput": true,
          "category": "Identité"
        },
        {
          "id": "fld-prenom",
          "name": "Prénom",
          "type": "alpha",
          "subType": "prenomNir",
          "length": 30,
          "includeInOutput": true,
          "linkedFieldId": "fld-nir"  // lié explicitement au NIR ci-dessus
        },
        {
          "id": "fld-statut",
          "name": "Statut",
          "type": "alpha",
          "subType": "none",
          "length": 10,
          "defaultValue": "ACTIF",
          "includeInOutput": true
        }
      ]
    }
  ],

  // Pied de page
  "footerFields": [ /* tableau de champs */ ],

  // Presets
  "presets": {
    "fld-statut": {
      "useRandom": false,
      "values": [
        { "value": "ACTIF",   "comment": "", "isDefault": true  },
        { "value": "INACTIF", "comment": "", "isDefault": false }
      ]
    }
  }
}

🔧 CI/CD & Build

Le projet utilise GitHub Actions pour l'intégration continue, la compilation multi-plateforme et la publication des releases.

Workflows GitHub Actions

WorkflowDéclencheurDescription
ci.ymlPush / PRTests, lint, coverage
build.ymlReleaseCompilation Flet multi-OS
release.ymlTag v*Publication GitHub Release
dependabot.ymlHebdomadaireMises à jour de dépendances
dependency-review.ymlPRAudit CVE des dépendances

Build multi-plateforme

PlateformeRunnerArtefact
Windows 64-bitwindows-latestDataFlowBuilder-windows
macOS Apple Siliconmacos-latestDataFlowBuilder-macos
Linux 64-bitubuntu-latestDataFlowBuilder-linux

Outils qualité

Ruff (Linter + Formatter)

ruff check .          # Vérifier
ruff check --fix .    # Corriger auto
ruff format .         # Formater

Bandit (Sécurité)

bandit -r src/

Tests & Coverage

pytest --cov=src --cov-report=term-missing

Build local

pip install -e ".[dev]"
flet build windows/linux ou macos
./dist/DataFlowBuilder

Conventional Commits

feat: ajouter le type de champ SIRET
fix: corriger le padding "both" pour longueurs impaires
docs: mettre à jour la documentation NIR
chore: bumper Faker à 25.0.0

❓ FAQ

Réponses aux questions les plus fréquentes.

Installation & Démarrage

L'application ne démarre pas après python main.py

python --version   # Doit afficher 3.11+
pip install -e .   # Réinstaller les dépendances

Où sont stockées mes données ?

Windows : %TEMP%\DataFlowBuilder\Linux/macOS : /tmp/DataFlowBuilder/

Flux et dossiers

Comment dupliquer un flux ?

Exportez-le en JSON (⬇ sur la carte), puis ré-importez-le. Un nouvel ID lui est attribué automatiquement.

J'ai supprimé un flux par erreur. Récupérable ?

Non, la suppression est définitive. Exportez régulièrement vos flux importants en JSON.

Si je supprime un dossier, mes flux sont-ils supprimés ?

Non. Les flux sont déplacés à la racine. Seul le dossier est supprimé.

Champs et types

Différence entre civilite et civiliteNir ?

civilite : aléatoire dans la catégorie choisie. civiliteNir : cohérente avec le genre du NIR de la même ligne.

J'ai deux champs NIR (ou deux champs code postal) dans la même ligne — comment contrôler les liaisons ?

Les champs dépendants (prenomNir, civiliteNir, ville…) exposent un paramètre Lien de cohérence dans leur panneau d'édition. Trois modes sont disponibles :

Voir Cohérence NIR pour les détails.

Comment générer un entier auto-incrémenté démarrant à 1000 ?

  1. Type : num, sous-type : none
  2. Cochez "Incrément"
  3. Valeur de départ : 1000
  4. Longueur : 8, padding : before, char : 000001000

Comment forcer une valeur fixe ?

Type alpha/none, renseignez la valeur par défaut. Toujours retournée sauf preset actif.

Comment avoir 70% de "ACTIF" et 30% de "INACTIF" ?

Presets : activez "Valeurs prédéfinies", ajoutez ACTIF ×7 et INACTIF ×3.

Données géographiques

L'application génère toujours les mêmes 10 villes

L'API n'a pas été contactée au premier lancement. Vérifiez la connexion internet, supprimez communes_cache.json et redémarrez.

Génération et export

Différence entre "Aperçu" et "Exporter" ?

Aperçu : génère quelques lignes dans l'interface (sans créer de fichier). Exporter : génère le fichier complet sur disque.

Générer un fichier positionnel (largeur fixe)

  1. Format : fixed
  2. Chaque champ avec sa longueur exacte
  3. Champs texte : padding after, char espace
  4. Champs numériques : padding before, char 0

Développement

Comment ajouter un nouveau type de champ ?

  1. Ajouter l'entrée dans FIELD_SUBTYPES dans field_types.py
  2. Configurer SUBTYPE_CONFIG (extra_fields, defaults)
  3. Implémenter la logique dans data_generator.py
  4. Ajouter les tests dans tests/test_data_generator.py

✅ Vérification de conformité

Contrôlez qu'un fichier de données réel respecte exactement le mapping d'un flux — encodage, délimiteur, nombre de champs, longueurs, types, formats et cohérence des sous-types.

Principe

La vérification de conformité compare un fichier existant (CSV, positionnel, JSON ou XML) au flux actuellement ouvert dans l'éditeur. Elle produit un rapport détaillé listant chaque écart, classé par sévérité.

ℹ️
Pour les formats JSON et XML, seuls la lisibilité structurelle et l'encodage sont vérifiés. Les contrôles de délimiteur et de champs s'appliquent uniquement aux formats CSV et positionnel.

Accéder au vérificateur

  1. Ouvrez un flux dans l'éditeur.
  2. Cliquez sur le bouton Vérifier la conformité (icône ) dans la barre d'actions.
  3. Le dialogue de conformité s'ouvre par-dessus l'éditeur.

Utilisation du dialogue

  1. Cliquez Parcourir… pour sélectionner le fichier à analyser.
  2. Cliquez Lancer l'analyse — un indicateur de progression s'affiche pendant l'analyse.
  3. Les résultats apparaissent groupés par sévérité, repliables/dépliables.
  4. Utilisez les filtres (Erreurs / Avertissements / Infos) pour cibler un type d'écart.
  5. Cliquez Exporter le rapport pour sauvegarder un compte-rendu texte (.txt).

Niveaux de sévérité

NiveauIcôneSignification
errorÉcart bloquant — le fichier ne respecte pas le mapping (encodage incorrect, type invalide, format de date non conforme…)
warning⚠️Anomalie probable — le fichier est lisible mais un champ présente un format suspect (SIRET avec clé Luhn invalide, numéro de téléphone mal formé…)
infoℹ️Contrôle réussi — confirmation qu'un point structurel est conforme (encodage OK, fins de ligne OK…)

Le rapport est marqué CONFORME (✅) uniquement si aucune erreur n'est détectée. Les avertissements n'empêchent pas la conformité.

Contrôles effectués

1. Encodage

Le fichier est décodé selon l'encodage déclaré dans le flux. Si ce décodage échoue, l'outil tente automatiquement utf-8-sig, iso-8859-1, windows-1252 et utf-16, puis signale l'encodage détecté en erreur.

2. Structure (JSON / XML)

Pour les formats json et xml, le contenu est parsé — toute erreur de syntaxe est reportée en erreur.

3. Fins de ligne

Comparaison du saut de ligne observé (CRLF, LF, CR ou mixte) avec la valeur déclarée dans le flux. Un écart génère un avertissement.

4. Délimiteur

Présence du caractère délimiteur déclaré dans au moins une ligne du fichier. L'absence génère une erreur.

5. En-tête et pied de page

Vérification de la cohérence entre la présence d'en-tête / pied de page déclarée dans le flux et le contenu effectif du fichier (nombre de colonnes de la première / dernière ligne).

6. Nombre de champs par ligne

Chaque ligne de données est découpée selon le délimiteur et le nombre de colonnes est comparé au nombre de champs includeInOutput déclarés. Un écart génère une erreur.

7. Longueur des champs

La valeur de chaque colonne est comparée à la longueur maximale déclarée dans le mapping. Un dépassement génère une erreur.

8. Cohérence de type

Type déclaréContrôle
numLa valeur ne doit contenir que des chiffres (hors espaces).
decimalLa valeur doit être convertible en nombre flottant avec le séparateur décimal configuré (. ou ,).
boolLa valeur doit appartenir à l'ensemble attendu selon le sous-type (O/N, OUI/NON, OK/KO, 0/1).
dateLa valeur doit correspondre exactement au format de date déclaré (ex. DD/MM/YYYY).

9. Cohérence du sous-type

Sous-typeValidationSévérité
emailRegex x@y.zwarning
siret14 chiffres + clé de contrôle Luhnwarning
nir15 chiffres exactswarning
ibanFormat CC99… (pays 2 lettres + 2 chiffres + alphanumérique)warning
codeApe4 chiffres + 1 lettre majuscule (ex. 6201Z)warning
codePostalExactement 5 chiffreswarning
codeInseeExactement 5 chiffreswarning
phoneNuméro FR national (0X… ou +33…)warning
phonePlus33Numéro FR international (+33…)warning
💡
Les contrôles de sous-type génèrent des avertissements (et non des erreurs) car ils peuvent produire des faux positifs — par exemple, un SIRET d'entreprise fictif peut avoir une clé Luhn invalide par construction.

Limite d'analyse

Pour des raisons de performance, le détail des contrôles par champ (longueur, type, sous-type) est appliqué aux 1 000 premières lignes de données au maximum. Les contrôles globaux (encodage, délimiteur, fins de ligne) portent toujours sur la totalité du fichier.

Rapport exporté

Le bouton Exporter le rapport sauvegarde un fichier conformite_<nom_du_flux>.txt contenant :

════════════════════════════════════════════════════════════════════════
  RAPPORT DE CONFORMITÉ – DATA FLOW BUILDER
════════════════════════════════════════════════════════════════════════
  Flux      : Flux salarié
  Fichier   : /home/user/salaries_mars.csv
  Date      : 15/03/2026 à 14:32:07
────────────────────────────────────────────────────────────────────────
  Encodage       : UTF-8 ✓
  Fins de ligne  : CRLF ✓
  Délimiteur     : ; ✓
────────────────────────────────────────────────────────────────────────
  ✅ CONFORME   ❌ 0 erreur(s)   ⚠️  2 avert.   ℹ️  3 info(s)   ⏱ 0.12 s   📄 500 ligne(s)
════════════════════════════════════════════════════════════════════════

  ⚠️  AVERTISSEMENTS (2)
  ────────────────────────────────────────────────────────────────────────
  Ligne 47 | SIRET  [Sous-type (siret)]  'SIRET' : le SIRET '12345678900000' échoue à la clé Luhn.
      Attendu : clé Luhn valide  →  Observé : 12345678900000

Architecture

FichierRôle
core/compliance_checker.pyMoteur de vérification — classes ComplianceChecker, ComplianceReport, CheckResult
ui/compliance_ui.pyDialogue Flet — sélection de fichier, progression, affichage filtrable, export