DEV Community

Mi Rak
Mi Rak

Posted on Edited on

test

# Modèle de données (sys_data_model) : guide d'utilisation

Ce module remplace le stockage des référentiels de Standards. Chaque entité d'un référentiel (GOVERNANCE, CONTROLS…) a ses propres tables physiques. Chaque version importée est historisée, et les liens entre tables sont physiques.

Page : **Paramètres → Modèle de données** (`/settings/sys-data-model`).

---

## 1. Installation

Enter fullscreen mode Exit fullscreen mode


bash
git checkout sys-data-model
npm run db:migrate


**Ajouter la variable d'environnement** dans le fichier `.env` :

Enter fullscreen mode Exit fullscreen mode


shell
SDM_JOUER_MIGRATIONS=1


Elle affiche le bouton **« Jouer les migrations »** dans l'onglet Migrations. Sans elle, il faut jouer chaque migration à la main.

**Lancer le projet avec `npm start`**, et **pas** avec `npm run start:local`.

> **Pourquoi ?** Le mode *watch* redémarre le serveur dès qu'un fichier change. Or l'écran écrit des fichiers de migration : le serveur redémarre en pleine création et l'opération échoue.

Ouvrez ensuite la page.

> **À retenir :** chaque fois que l'écran **engendre** une migration (tables d'une entité, table d'un lien, vue), il faut la **jouer** avec le bouton **« Jouer les migrations »**. Tant qu'elle n'est pas jouée, la table n'existe pas. Une migration en attente bloque aussi l'import des entités qu'elle concerne.

---

## 2. Le parcours, dans l'ordre

| Étape | Onglet | Action |
|---|---|---|
| 1 | Entités | **Reprendre depuis Standards** |
| 2 | Entités | **Engendrer toutes les migrations** |
| 3 | Migrations | **Jouer les migrations** |
| 4 | Migrations | **Engendrer la vue**, puis **Jouer les migrations** |
| 5 | Migrations | **Importer les déclarations** avec le fichier `X`, pour obtenir la définition des liens |
| 6 | Liens | **Engendrer la table** des liens qui en demandent une, puis **Jouer les migrations** |
| 7 | Imports | Déposer les fichiers, **Analyser**, puis **Valider et intégrer** |
| 8 | Données | Vérifier le contenu importé |
| 9 | Test API | Tester les fonctions de l'API |

Le détail de chaque onglet suit.

---

## 3. Les onglets

### Entités

Cet onglet sert à déclarer les entités (une entité = un type de ligne, par exemple `gov_requirement`) et leurs attributs (les colonnes).

- **Reprendre depuis Standards** crée automatiquement les entités à partir des référentiels existants. Les découpages connus sont faits d'office : GOVERNANCE par TYPE, et CONTROLS.
- **Nouvelle entité** sert à en créer une à la main. Cliquer sur une entité ouvre sa fiche (attributs, parent, ordre). Modifier les attributs ne demande pas de migration.
- **Sources** (colonne de la fiche) : sert quand le nom d'une colonne change d'une version à l'autre. Voir la section 4 plus bas.
- **Découper** répartit un référentiel en plusieurs entités, selon la valeur d'une colonne.
- **Engendrer la migration** (sur une entité) ou **Engendrer toutes les migrations** écrit le fichier qui créera les tables.

### Migrations

Cet onglet liste les fichiers engendrés et leur état : à jouer, ou jouée.

- **Jouer les migrations :** joue toutes les migrations en attente. Le bouton n'apparaît que si `SDM_JOUER_MIGRATIONS=1` est défini.
- **Engendrer la vue :** crée la *vue de compatibilité* d'un référentiel. Elle présente les nouvelles tables sous la même forme que l'ancien Standards. Il faut ensuite la jouer. **Elle est indispensable pour le Test API** (voir plus bas).
- **Importer les déclarations :** charge un fichier de déclarations (référentiels, entités, attributs, liens). C'est ce bouton qu'on utilise avec le fichier `X` pour récupérer la définition des liens. L'import crée ce qui manque et n'écrase rien. Les différences sont seulement signalées.
- **Exporter les déclarations :** produit ce même fichier, pour passer à un autre environnement.
- **Comparer à la base :** compare les déclarations aux tables réellement présentes.

### Imports

Cet onglet sert à charger une version d'un référentiel.

1. Choisissez le référentiel dans le menu de gauche.
2. Déposez les fichiers (FR et EN, ou le fichier source selon le référentiel) et saisissez le numéro de version.
3. **Analyser :** rien n'est écrit. Un rapport s'affiche. Il indique les nouveaux codes, les textes modifiés, les codes retirés et les liens.
4. **Valider et intégrer** pour enregistrer la version, ou **Refuser**.

Pour reprendre les versions déjà présentes dans Standards, utilisez **Reprendre les versions Standards**. Elle rejoue chaque version, de la plus ancienne à la plus récente.

Un code déjà connu n'est jamais dupliqué : seules ses modifications sont historisées. Un lien vers un code introuvable est **signalé dans le rapport, sans bloquer l'import**.

### Données

Cet onglet sert à consulter les données importées, en lecture seule.

Vous pouvez filtrer par référentiel, langue et version, et chercher par code ou par libellé. Il est possible de déplier la hiérarchie et d'ouvrir le détail FR/EN d'une ligne.

### Liens

Cet onglet montre l'arbre des entités et leurs liens.

Il existe deux sortes de liens :

- **Native :** le lien est porté par une colonne du fichier. Il est recalculé à chaque import.
- **À rapprocher :** le fichier ne contient pas l'information. Le lien est établi à la main, puis reconduit automatiquement à chaque nouvelle version tant que les deux codes existent.

Les actions :

- **Reprendre les liens existants** récupère les liens déjà déclarés dans Standards.
- **Nouveau lien** demande la table source, la colonne source, la table cible, la colonne cible et la cardinalité. Une phrase explique la cardinalité choisie. La migration de la table de liaison est engendrée tout de suite : il faut ensuite la jouer.
- **Engendrer la table** (sur un lien) : pour les liens qui viennent d'un import de déclarations, il faut engendrer leur table puis la jouer.
- **Instances** (sur un lien « à rapprocher ») permet d'établir les paires de codes une à une, ou d'**importer un classeur Excel à 2 colonnes** (code source, code cible).

Les liens ne sont jamais bloquants. Un code absent est signalé. L'ordre d'import des référentiels n'a pas d'importance : les liens se complètent quand la table cible arrive.

### Test API

Cet onglet sert à tester les fonctions de l'API Standards, servies cette fois par le nouveau module : mêmes noms, mêmes paramètres, même réponse.

> **Prérequis :** la **vue** du référentiel doit exister. Pour cela, allez dans **Migrations**, faites **Engendrer la vue**, puis **Jouer les migrations**. Sans vue, l'API ne trouve rien.

Choisissez une fonction, remplissez les paramètres, puis cliquez sur **Exécuter**. La version utilisée est la plus récente intégrée.

---

## 4. Quand une colonne change d'une version à l'autre : le champ « Sources »

Chaque attribut lit, dans le fichier importé, la colonne qui porte **son nom**. Si une nouvelle version renomme cette colonne, ajoute une colonne ou en supprime une, on le déclare dans le champ **Sources** de l'attribut. Une seule définition couvre alors toutes les versions.

**La marche à suivre :**

1. **Imports :** déposez la nouvelle version, puis cliquez sur **Analyser**. Rien n'est encore enregistré.
2. Dans le rapport, regardez deux blocs :
   - **« Colonnes déclarées absentes du fichier »** : l'attribut qui ne trouve plus sa colonne ;
   - **« Colonnes du fichier non déclarées — valeurs ignorées »** : la colonne que personne ne lit. **C'est son nom qu'il faut reporter.**
3. Cliquez sur **Refuser**.
4. **Entités :** ouvrez l'entité. Dans l'attribut concerné, remplissez **Sources** avec le nom relevé et la version, puis cliquez sur **Enregistrer**.
5. **Imports :** relancez **Analyser**. Les deux alertes ont disparu. Faites alors **Valider et intégrer**.

**La notation** (rappelée aussi au-dessus du tableau des attributs) :

| Saisie dans « Sources » | Signification |
|---|---|
| *(vide)* | la colonne de même nom, toutes versions |
| `LIBELLE ; TITRE [6.6-]` | `LIBELLE` dans toutes les versions, `TITRE` à partir de 6.6 |
| `LIBELLE [-6.5]` | jusqu'à 6.5 : l'attribut n'existe plus ensuite |
| `LIBELLE [5.0-6.5]` | de 5.0 à 6.5 seulement |

Plusieurs sources se séparent par « ; ». Pour une version donnée, la source valable la plus récente l'emporte.

Le nom à saisir est le **nom technique** de la colonne, le même pour les fichiers FR et EN. Ce n'est pas le titre français ou anglais du fichier officiel.

Le reste de l'application (données, vue, API) ne voit que l'attribut : un simple changement de nom de colonne ne crée pas de fausse modification.

---

## 5. Règles utiles

- **Lancez avec `npm start`**, jamais en mode *watch* (`npm run start:local`).
- **Analyser n'écrit jamais rien.** Seul « Valider et intégrer » enregistre.
- **Une migration engendrée doit être jouée** (bouton « Jouer les migrations ») avant d'importer ou de tester.
- **Pour supprimer une entité ou un lien**, il faut d'abord retirer sa migration ou sa table.
- **Deux droits existent :** `system.sysDataModel.access` donne la lecture, `system.sysDataModel.manage` donne toutes les actions.

---

## Mail d'envoi

> **Objet :** sys_data_model : guide d'utilisation et fichier de déclarations
>
> Hello,
>
> Voici le guide d'utilisation de sys_data_model, ainsi que le fichier d'import des déclarations (définition des entités et des liens).
>
> Le guide reprend l'installation, le parcours étape par étape et le rôle de chaque onglet. Le fichier de déclarations s'importe dans l'onglet Migrations → « Importer les déclarations », une fois les migrations jouées et la vue créée (étape 5 du guide).
>
> N'hésite pas si tu as des questions.
>
> 

Enter fullscreen mode Exit fullscreen mode

Top comments (0)