dimanche, 17 mai, 2026
Schéma de base de données
IsoFind utilise une base SQLite locale (isofind.db) composée de 33 tables réparties en 8 domaines fonctionnels. Cette page documente les colonnes clés, clés primaires, clés étrangères et champs métier principaux. Le schéma est vérifié et migré automatiquement au démarrage de l'application via db_migration.py, sans aucune perte de données existantes.
IsoFind : La migration est non destructive. Les colonnes manquantes sont ajoutées
(ALTER TABLE ADD COLUMN), les tables absentes sont recréées intégralement,
et les colonnes supplémentaires sont ignorées pour assurer la rétrocompatibilité descendante.
Echantillons & données isotopiques
samples est la table pivot du modèle (toutes les mesures, rendements et traitements y sont rattachés par clé étrangère). isotope_data stocke les rapports mesurés par élément et ratio. purification_yields enregistre le rendement de purification en mémoire par élément, évitant la modification manuelle des rapports isotopiques bruts. sample_methods et sample_pipelines instancient les protocoles analytiques sur un échantillon donné.
isofind.db - domaine : échantillons
. +-- samples -- table pivot principale | +-- id PK | +-- name, material_type, sector | +-- project, classification | +-- collection_date, collection_location | +-- latitude, longitude | `-- owner_id | +-- isotope_data -- mesures isotopiques brutes | +-- id PK | +-- sample_id FK -> samples | +-- element, isotope_ratio | +-- ratio_value, uncertainty | +-- normalized_value, standard_used | `-- sample_type, collection_date | +-- purification_yields -- rendements en mémoire par élément | +-- id PK | +-- sample_id FK -> samples [UNIQUE (sample_id, element)] | +-- element, yield_percent | `-- operator, method_key, measured_at | +-- sample_methods -- protocoles appliqués à un échantillon | +-- id PK | +-- sample_id FK -> samples | +-- method_id FK -> method_library | +-- method_type, element, laboratory | `-- yield_percent, performed_date | `-- sample_pipelines -- pipelines analytiques appliqués +-- id PK +-- sample_id FK -> samples +-- pipeline_id FK -> method_pipelines +-- current_stage, status `-- started_at, completed_at
Mesures par famille
Trois tables dédiées stockent les mesures analytiques non isotopiques, chacune rattachée à un échantillon via sample_id. sample_geochem stocke les concentrations élémentaires avec normalisation automatique en unité interne. sample_molecules stocke les concentrations moléculaires (PFAS, pesticides, HAP, solvants, BTEX) avec flag de détection et seuil réglementaire. sample_physicochemistry stocke les conditions physico-chimiques (pH, Eh, DO, T, conductivité). sample_audit_trail journalise toutes les modifications ligne par ligne (INSERT / UPDATE / DELETE).
isofind.db - domaine : mesures par famille
. +-- sample_geochem -- concentrations élémentaires (inorganiques) | +-- id PK | +-- sample_id FK -> samples [CASCADE] | +-- element ex: 'Sb', 'Ca', 'Li', 'Cr' | +-- value_normalized, uncertainty unité interne mg/kg | +-- display_value, display_unit valeur et unité d'origine | +-- method ICP-MS, XRF, ICP-OES... | `-- depth_m convention forage, positif vers le bas | +-- sample_molecules -- concentrations moléculaires organiques | +-- id PK | +-- sample_id FK -> samples [CASCADE] | +-- molecule_id FK -> user_molecules [SET NULL] | +-- nom, cas, famille | +-- valeur, unite, valeur_ug_l conversion canonique en µg/L | +-- incertitude, lod, loq, detecte | +-- mz_mesure, methode, laboratoire | +-- conforme, seuil_ref diagnostic réglementaire | `-- matrice, date_analyse | +-- sample_physicochemistry -- conditions physico-chimiques | +-- id PK | +-- sample_id FK -> samples [CASCADE] | +-- parameter pH, Eh_mV, do_mg_l, temperature_c, etc. | +-- value, uncertainty, method | +-- measured_at, notes | `-- depth_m convention forage, positif vers le bas | `-- sample_audit_trail -- journal des modifications ligne par ligne +-- id PK +-- sample_id FK -> samples [CASCADE] +-- action [INSERT | UPDATE | DELETE] +-- column_name, old_value, new_value `-- changed_by, changed_at
IsoFind : Les paramètres de sample_physicochemistry
suivent une nomenclature normalisée documentée dans db_migration.py :
pH, Eh_mV,
pe (calculé Eh_mV / 59.16 à 25 °C),
temperature_c, conductivity_us_cm,
do_mg_l, ionic_strength_M,
alkalinity_mg_l, toc_mg_l,
turbidity_ntu, salinity_ppt.
Le champ depth_m présent dans les trois tables alimente directement
la vue Profils verticaux.
MRC & corrections
analyzed_crm représente une session de mesure d'un matériau de référence certifié (instrument, laboratoire, score qualité). analyzed_crm_values stocke les valeurs mesurées et certifiées avec leurs écarts en sigma. crm_derived_shifts dérive les corrections à appliquer aux rapports bruts. sample_crm_association relie explicitement un MRC à l'échantillon qu'il contrôle.
isofind.db - domaine : MRC & corrections
. +-- analyzed_crm -- session de mesure d'un MRC | +-- id PK | +-- crm_id, crm_name | +-- instrument, laboratory, operator | `-- quality_score, session_name, analysis_date | +-- analyzed_crm_values -- valeurs mesurées vs certifiées | +-- id PK | +-- analyzed_crm_id FK -> analyzed_crm [CASCADE] | +-- element, isotope_ratio | +-- measured_value, certified_value | `-- deviation, deviation_sigma, status | +-- crm_derived_shifts -- corrections dérivées du MRC | +-- id PK | +-- analyzed_crm_id FK -> analyzed_crm [CASCADE] | +-- element, isotope_ratio | +-- shift_value, uncertainty | `-- is_active, source | `-- sample_crm_association -- lien échantillon <-> MRC +-- id PK +-- sample_id FK -> samples [CASCADE] +-- analyzed_crm_id FK -> analyzed_crm [CASCADE] `-- association_type [UNIQUE (sample_id, analyzed_crm_id)]
Méthodes & pipelines
method_library est une bibliothèque de protocoles réutilisables (digestion, purification, séparation, analyse), référençables par local_key. method_pipelines enchaîne des méthodes en séquences ordonnées via un champ stages_json. Les deux tables d'instanciation (sample_methods, sample_pipelines) relient ces protocoles à un échantillon concret.
isofind.db - domaine : méthodes & pipelines
. +-- method_library -- bibliothèque de protocoles | +-- id PK | +-- name, type [digestion | purification | séparation | analyse] | +-- element_target, equipment, laboratory | +-- doi, reference_text, author | `-- local_key [UNIQUE] identifiant de référence | +-- method_pipelines -- séquences ordonnées de méthodes | +-- id PK | +-- name, element | +-- stages_json séquence des étapes | +-- total_duration_hours, is_template | `-- local_key [UNIQUE] | +-- sample_methods -- instanciation d'un protocole sur échantillon | +-- id PK | +-- sample_id FK -> samples [CASCADE] | +-- method_id FK -> method_library [SET NULL] | +-- method_type, element, laboratory | `-- yield_percent, performed_date, performed_by | `-- sample_pipelines -- instanciation d'un pipeline sur échantillon +-- id PK +-- sample_id FK -> samples [CASCADE] +-- pipeline_id FK -> method_pipelines [CASCADE] +-- current_stage, status [pending | in_progress | completed | failed] `-- started_at, completed_at
Standards isotopiques & références géographiques
isotope_standards centralise les standards de référence (NIST, IAEA, etc.) et les standards personnalisés. isotopic_shifts encode les décalages entre paires de standards pour la normalisation inter-laboratoires. reference_standards désigne le standard actif par élément. geographic_zones et reference_data fournissent les données de fond géochimique régional utilisées dans la correspondance isotopique.
isofind.db - domaine : standards & références
. +-- isotope_standards -- standards analytiques (NIST, IAEA, custom) | +-- id PK | +-- name, element, isotope_ratio | +-- reference_value, uncertainty | +-- is_reference, is_custom | +-- batch_number, is_default_batch | `-- reference_standard_id auto-ref (standard parent) | +-- isotopic_shifts -- décalages entre paires de standards | +-- id PK | +-- source_standard_id FK -> isotope_standards | +-- target_standard_id FK -> isotope_standards | +-- element, isotope_ratio | `-- shift_value, uncertainty, source | +-- reference_standards -- standard actif par élément | +-- id PK | +-- element [UNIQUE] | `-- standard_id FK -> isotope_standards | +-- geographic_zones -- zones géochimiques de référence | +-- id PK | +-- name, country, region | +-- latitude, longitude, radius_km | `-- geological_context | `-- reference_data -- données de fond géochimique régional +-- id PK +-- geographic_zone_id FK -> geographic_zones +-- element, isotope_ratio +-- mean_value, std_deviation `-- sample_count, confidence_level, source
Catalogue moléculaire
user_molecules est le catalogue de molécules éditable par l'utilisateur (CAS unique, SMILES, formule, masse molaire, famille, seuils réglementaires, LOD, LOQ). Il étend le catalogue de référence livré avec IsoFind et permet d'ajouter des molécules spécifiques à un contexte d'usage. ref_molecules_isotopes porte le référentiel isotopique moléculaire : pour chaque paire molécule × élément isotopique, il enregistre la notation, le mécanisme, les gammes de valeurs par source, et le score de discrimination forensique.
isofind.db - domaine : catalogue moléculaire
. +-- user_molecules -- catalogue de molécules extensible | +-- id PK | +-- nom, nom_iupac | +-- cas [UNIQUE] | +-- smiles, formule, masse_molaire | +-- mz_principal, mz_secondaires | +-- famille, sous_famille, type_polluant | +-- seuil_eau, seuil_sol, seuil_unit réglementaires | +-- reglementation, lod, loq | `-- methode_ref, unite_defaut | `-- ref_molecules_isotopes -- référentiel isotopique par molécule +-- id PK +-- molecule_id lien optionnel vers user_molecules +-- molecule_nom, molecule_cas, famille +-- element, isotope_type, notation ex: C, d13C, delta13C +-- mecanisme, application_forensique +-- label_source_1, gamme_source_1_min/max +-- label_source_2, gamme_source_2_min/max +-- discrimination_score, precision_requise_permil +-- methode_analytique, matrice_optimale `-- faisabilite, licence, actif [pro | lite | gratuit]
IsoFind : Le champ licence de
ref_molecules_isotopes permet le filtrage par édition :
les entrées 'pro' ne sont visibles qu'en IsoFind Pro,
les entrées 'gratuit' sont accessibles dans toutes les éditions.
C'est le mécanisme de cloisonnement du catalogue entre éditions, défini au niveau base sans duplication du code.
Publications & archive
publications centralise les références bibliographiques (DOI, auteurs, journal). Deux tables de liaison la connectent aux méthodes (method_publication_link) et aux échantillons (sample_publications). archive_samples et archive_isotope_data conservent un instantané figé des données à la date d'archivage, isolé du graphe principal - original_id préserve la traçabilité vers l'enregistrement source.
isofind.db - domaine : publications & archive
. +-- publications -- bibliographie centrale | +-- id PK | +-- doi [UNIQUE] | +-- title, authors, journal, year | `-- category, keywords, url, pdf_path | +-- method_publication_link -- méthode <-> publication | +-- id PK | +-- method_id FK -> method_library [CASCADE] | +-- publication_id FK -> publications [CASCADE] | `-- link_type [source | modification | validation] | +-- sample_publications -- échantillon <-> publication | +-- id PK | +-- sample_id FK -> samples [CASCADE] | +-- publication_id FK -> publications [CASCADE] | `-- relation_type [source | published_in | reference | cited] | +-- archive_samples -- instantané figé des échantillons | +-- id PK | +-- name, material_type, sector, project | +-- original_id traçabilité vers samples.id d'origine | `-- archived_at horodatage d'archivage | +-- archive_isotope_data -- instantané figé des mesures isotopiques | +-- id PK | +-- sample_id FK -> archive_samples | +-- element, isotope_ratio, ratio_value | `-- archived_at, standard_used | +-- archive_geochem -- instantané figé des concentrations élémentaires | +-- id PK | +-- sample_id FK -> archive_samples | +-- element, valeur, unite, methode | +-- incertitude, lod, loq, depth_m | `-- archived_at | +-- archive_molecules -- instantané figé des concentrations moléculaires | +-- id PK | +-- sample_id FK -> archive_samples | +-- nom, cas, famille, valeur, unite | +-- incertitude, lod, loq, detecte | `-- archived_at | `-- archive_physicochemistry -- instantané figé des conditions physico-chimiques +-- id PK +-- sample_id FK -> archive_samples +-- parameter, value, uncertainty, method +-- measured_at, depth_m `-- archived_at
Analyses & configuration
Tables autonomes sans clés étrangères vers le reste du modèle. analysis_history journalise chaque analyse lancée (type, statut, durée, nombre d'échantillons impliqués), avec soft-delete via deleted_at. custom_elements étend la configuration des éléments isotopiques disponibles au-delà des valeurs par défaut.
isofind.db - domaine : analyses & configuration
. +-- analysis_history -- journal des analyses lancées | +-- id PK | +-- name, analysis_type | +-- samples_count, duration | +-- status [completed | ...] | +-- created_at, updated_at | `-- deleted_at soft-delete | +-- custom_elements -- éléments isotopiques personnalisés | +-- id PK | +-- symbol [UNIQUE] | +-- name, ratios ratios disponibles pour cet élément | `-- is_default inclus dans la config de base | `-- prospection_sessions -- sessions du module Prospection E&M +-- id PK +-- name, project, status +-- inputs_json, results_json entrées et sortie d'analyse +-- score_global, best_match, maturity_stage `-- sample_id, created_at, updated_at
Légende & conventions
| Notation | Signification |
|---|---|
| PK | Clé primaire, identifiant unique de la ligne |
| FK | Clé étrangère, référence vers une autre table |
| [CASCADE] | Suppression en cascade, les lignes enfants sont supprimées avec le parent |
| [SET NULL] | La clé étrangère est mise à NULL si le parent est supprimé |
| [UNIQUE] | Contrainte d'unicité sur la colonne ou la combinaison de colonnes |
| a | b | c | Valeurs acceptées, contrainte CHECK dans le DDL |
IsoFind : Le moteur est SQLite 3. Les types déclarés
(TEXT, REAL,
INTEGER, TIMESTAMP)
sont indicatifs; SQLite applique un typage dynamique par affinité de colonne.
Les champs horodatés sont stockés en TEXT au format ISO 8601
via datetime('now'), sauf mention explicite de
TIMESTAMP.
Dictionnaire des types de données
SQLite applique un typage dynamique par affinité de colonne. IsoFind impose néanmoins des conventions strictes pour garantir la précision des calculs isotopiques et l'interopérabilité avec les outils tiers. Le tableau suivant documente les conventions utilisées dans l'ensemble du schéma.
| Type déclaré | Affinité SQLite | Usage dans IsoFind | Exemples de champs |
|---|---|---|---|
| TEXT | TEXT | Chaînes, identifiants, ratios isotopiques, dates ISO 8601 | name, isotope_ratio, created_at |
| REAL | REAL | Valeurs isotopiques, incertitudes, coordonnées géographiques | ratio_value, uncertainty, latitude |
| FLOAT | REAL | Alias de REAL, héritage du schéma initial, comportement identique | mean_value, std_deviation |
| INTEGER | INTEGER | Clés primaires, compteurs, flags booléens (0/1) | id, samples_count, is_active |
| BOOLEAN | NUMERIC | Stocké comme INTEGER 0/1, jamais de valeur littérale true/false | is_default, is_reference, is_custom |
| TIMESTAMP | NUMERIC | Horodatages système, stockés en TEXT ISO 8601 malgré l'affectation NUMERIC | archived_at, created_at (tables archive) |
| VARCHAR(n) | TEXT | Héritage ORM, la longueur n n'est pas contrainte par SQLite mais documente l'intention | name, sector, standard_used |
IsoFind : Les valeurs de ratios isotopiques sont toujours stockées en
REAL (flottant 64 bits IEEE 754), ce qui garantit une précision
suffisante pour les mesures en spectrométrie de masse. Ne pas substituer par
TEXT pour ces champs, la normalisation et les calculs de
déviation en sigma seraient silencieusement faux.
Audit trail & traçabilité
La traçabilité est un critère central pour les applications forensiques et de défense. IsoFind enregistre l'historique des modifications à plusieurs niveaux (horodatage des opérations, conservation des données archivées, et journalisation des analyses), sans jamais supprimer de données de façon irréversible.
| Mécanisme | Tables concernées | Fonctionnement |
|---|---|---|
| Horodatage double | samples, analyzed_crm, method_library | Chaque enregistrement porte created_at et updated_at, mis à jour automatiquement via datetime('now') à chaque écriture. |
| Soft-delete | analysis_history | Les analyses supprimées ne sont pas effacées, le champ deleted_at est renseigné, l'enregistrement reste interrogeable pour audit. |
| Archivage figé | archive_samples, archive_isotope_data | Instantané complet des données à la date d'archivage. Le champ original_id maintient le lien vers l'enregistrement source dans samples, même si celui-ci est modifié ultérieurement. |
| Journal des analyses | analysis_history | Chaque analyse lancée est enregistrée avec son type, son statut, sa durée et le nombre d'échantillons impliqués. Constitue un log d'activité complet de la session analytique. |
| Contrôle qualité MRC | analyzed_crm, analyzed_crm_values | Chaque session de mesure d'un matériau de référence certifié est conservée intégralement, avec les écarts en sigma par rapport aux valeurs certifiées. Permet de reconstituer l'état de l'instrument à une date donnée. |
IsoFind : Les suppressions en cascade (ON DELETE CASCADE)
sont limitées aux tables de liaison et aux valeurs enfants directement dépendantes d'un enregistrement parent.
Les données primaires (samples, isotope_data)
ne sont jamais supprimées automatiquement par effet de bord.
Sécurité & chiffrement
IsoFind distingue deux périmètres de protection : l'intégrité des données à l'export, et la confidentialité des données au repos. Ces deux mécanismes sont indépendants et complémentaires.
IsoFind : Le fichier isofind.db lui-même
n'est pas chiffré au repos, il est protégé par les permissions système du répertoire d'installation.
Le chiffrement s'applique aux exports .isof et aux sauvegardes,
pas à la base SQLite active, sauf option activée (plan IsoFind Pro).
| Mécanisme | Périmètre | Détail technique |
|---|---|---|
| Intégrité SHA-256 | Exports .isof | Chaque fichier export embarque un hash SHA-256 de son contenu. À l'import, IsoFind recalcule le hash et rejette les fichiers altérés. Garantit que les données n'ont pas été modifiées en transit. |
| Chiffrement AES | Exports chiffrés .isof | Les exports peuvent être chiffrés avec une clé gérée via le trousseau système (isofKeyringManage). Le destinataire doit disposer de la clé correspondante pour déchiffrer l'import. |
| Signature numérique | Fichiers .isof certifiés | Les fichiers issus d'un laboratoire certifié portent une signature cryptographique vérifiable via le standard ISOF. La signature atteste de l'origine et de l'intégrité de la chaîne analytique complète. |
| Permissions système | Base isofind.db | L'accès à la base active est contrôlé par les permissions du système de fichiers. Sur les déploiements multi-utilisateurs, le répertoire de données doit être restreint à l'utilisateur exécutant IsoFind. |