From cd37303f1c5496815dd5cd7d82b36b610d1e8107 Mon Sep 17 00:00:00 2001 From: Nicolas Savois Date: Wed, 3 Jun 2026 12:48:12 +0200 Subject: [PATCH] adding seeds documentation --- docs/en/seeds.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/fr/seeds.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 docs/en/seeds.md create mode 100644 docs/fr/seeds.md diff --git a/docs/en/seeds.md b/docs/en/seeds.md new file mode 100644 index 000000000..771cc95f4 --- /dev/null +++ b/docs/en/seeds.md @@ -0,0 +1,83 @@ +# Seeds + +## Overview + +Seeds populate the database with realistic development data. +They are good examples for understanding the data models and implementing your own framework. +They are driven by `api/db/seeds/seed.js` and use the same `DatabaseBuilder` factory as the test suite. + +## Learning Content Hierarchy + +Data is built top-down in a tree structure, with each level attached to its parent: + +``` +Framework → Area → Competence → Thematic → Tube → Skill → Challenge +``` + +Each builder receives the running `learningContentData` tree so it can link items to their parents. IDs are deterministic (e.g. `areaF0A1`, `skillF0A1C0T0S2Act`, `challengeF0A1C0T0S2Ch0`). + +## Skill Generation Pattern + +Skills are generated in pairs per level index within each tube: + +| Index parity | Skill 1 | Skill 2 | +|---|---|---| +| Even | `actif` v1 | `en construction` v2 | +| Odd | `périmé` v1 | `archivé` v2 | + +Tubes whose name contains `workbench` receive a single workbench skill (`en construction`) instead. + +## Challenge Generation Pattern + +The number and statuses of challenges generated per skill depend on the skill's status: + +| Skill status | Challenges created | +|---|---| +| `en construction` | 1 `proposée` proto + 1 `proposée` décli + 1 `périmée` décli | +| `actif` | 1 `validée` proto + 1 `validée` décli + 1 `périmée` décli + 1 `archivée` décli | +| `archivé` | 1 `archivée` proto + 1 `archivée` décli + 1 `périmée` décli | +| `périmé` | 2 `périmées` | + +Challenge attributes (type, format, accessibility, etc.) are cycled through all enum values using the `cycle()` generator from `data/utils.js`, ensuring broad coverage without manual specification. + +Translations are created for every locale in `SEEDS_LOCALES` for each challenge. + +## Other Builders + +| File | Description | +|---|---| +| `data/tags.js` | Fixed list of tags | +| `data/tutorials.js` | Fixed list of tutorials, distributed across skills | +| `data/pix-1d.js` | Pix 1D framework, built independently of `seedsConfig` | +| `data/modules.js` | Reads JSON files from `data/modules/*.json` and inserts them as-is | +| `data/static-courses.js` | Fixed set of static courses | +| `data/whitelisted-urls.js` | Fixed set of whitelisted URLs | + +## Seed Users + +Four users are always created: + +| Trigram | Role | API key source | +|---|---|---| +| `DEV` | admin | `REVIEW_APP_ADMIN_USER_API_KEY` or hardcoded default | +| `EDI` | editor | `REVIEW_APP_EDITOR_USER_API_KEY` or hardcoded default | +| `RPO` | readpixonly | `REVIEW_APP_READ_PIX_ONLY_USER_API_KEY` or hardcoded default | +| `LOL` | readonly | `REVIEW_APP_READ_ONLY_USER_API_KEY` or hardcoded default | + +Hardcoded API keys are only active when `REVIEW_APP` is not set. + +## Configuration + +All record counts are controlled by environment variables (defined in `lib/config.js` as `seedsConfig`): + +| Env var | Default | Meaning | +|---|---|---| +| `SEEDS_CNT_FRAMEWORKS` | 2 | Number of frameworks | +| `SEEDS_CNT_AREAS` | 2 | Areas per framework | +| `SEEDS_CNT_COMPETENCES` | 2 | Competences per area | +| `SEEDS_CNT_THEMATICS` | 2 | Thematics per competence | +| `SEEDS_CNT_TUBES` | 2 | Tubes per thematic | +| `SEEDS_SKILL_LEVEL` | 3 | Max skill levels per tube | +| `SEEDS_LOCALES` | `['fr','en']` | Locales for translations | + + diff --git a/docs/fr/seeds.md b/docs/fr/seeds.md new file mode 100644 index 000000000..abd0b7662 --- /dev/null +++ b/docs/fr/seeds.md @@ -0,0 +1,82 @@ +# Seeds + +## Vue d'ensemble + +Les seeds peuplent la base de données avec des données de développement réalistes. +Ces seeds sont de bons exemples pour s'approprier les modèles de données et implémenter son propre référentiel. +Ils sont pilotés par `api/db/seeds/seed.js` et utilisent la même factory `DatabaseBuilder` que la suite de tests. + +## Hiérarchie du contenu pédagogique + +Les données sont construites de haut en bas dans une structure arborescente, chaque niveau étant rattaché à son parent : + +``` +Référentiel → Domaine → Compétence → Thématique → Sujet → Acquis → Épreuve +``` + +Chaque constructeur reçoit l'arbre `learningContentData` en cours de construction afin de lier les éléments à leurs parents. Les identifiants sont déterministes (ex. `areaF0A1`, `skillF0A1C0T0S2Act`, `challengeF0A1C0T0S2Ch0`). + +## Génération des acquis + +Les acquis sont générés par paires pour chaque niveau dans un sujet : + +| Parité de l'index | Acquis 1 | Acquis 2 | +|---|---|---| +| Pair | `actif` v1 | `en construction` v2 | +| Impair | `périmé` v1 | `archivé` v2 | + +Les sujets dont le nom contient `workbench` reçoivent un unique acquis workbench (`en construction`) à la place. + +## Génération des épreuves + +Le nombre et les statuts des épreuves générées par acquis dépendent du statut de l'acquis : + +| Statut de l'acquis | Épreuves créées | +|---|---| +| `en construction` | 1 proto `proposée` + 1 décli `proposée` + 1 décli `périmée` | +| `actif` | 1 proto `validée` + 1 décli `validée` + 1 décli `périmée` + 1 décli `archivée` | +| `archivé` | 1 proto `archivée` + 1 décli `archivée` + 1 décli `périmée` | +| `périmé` | 2 `périmées` | + +Les attributs des épreuves (type, format, accessibilité, etc.) sont cyclés sur l'ensemble des valeurs d'énumération à l'aide du générateur `cycle()` de `data/utils.js`, garantissant une couverture large sans spécification manuelle. + +Des traductions sont créées pour chaque langue de `SEEDS_LOCALES` pour chaque épreuve. + +## Autres constructeurs + +| Fichier | Description | +|---|---| +| `data/tags.js` | Liste fixe de tags | +| `data/tutorials.js` | Liste fixe de tutoriels, répartis sur les acquis | +| `data/pix-1d.js` | Référentiel Pix 1D, construit indépendamment de `seedsConfig` | +| `data/modules.js` | Lit les fichiers JSON de `data/modules/*.json` et les insère tels quels | +| `data/static-courses.js` | Ensemble fixe de parcours statiques | +| `data/whitelisted-urls.js` | Ensemble fixe d'URLs autorisées | + +## Utilisateurs seeds + +Quatre utilisateurs sont toujours créés : + +| Trigramme | Rôle | Source de la clé API | +|---|---|---| +| `DEV` | admin | `REVIEW_APP_ADMIN_USER_API_KEY` ou valeur par défaut codée en dur | +| `EDI` | editor | `REVIEW_APP_EDITOR_USER_API_KEY` ou valeur par défaut codée en dur | +| `RPO` | readpixonly | `REVIEW_APP_READ_PIX_ONLY_USER_API_KEY` ou valeur par défaut codée en dur | +| `LOL` | readonly | `REVIEW_APP_READ_ONLY_USER_API_KEY` ou valeur par défaut codée en dur | + +Les clés API codées en dur ne sont actives que lorsque la variable `REVIEW_APP` n'est pas définie. + +## Configuration + +Le nombre d'enregistrements est contrôlé par des variables d'environnement (définies dans `lib/config.js` via `seedsConfig`) : + +| Variable d'environnement | Défaut | Signification | +|---|---|---| +| `SEEDS_CNT_FRAMEWORKS` | 2 | Nombre de référentiels | +| `SEEDS_CNT_AREAS` | 2 | Domaines par référentiel | +| `SEEDS_CNT_COMPETENCES` | 2 | Compétences par domaine | +| `SEEDS_CNT_THEMATICS` | 2 | Thématiques par compétence | +| `SEEDS_CNT_TUBES` | 2 | Sujets par thématique | +| `SEEDS_SKILL_LEVEL` | 3 | Niveau maximum des acquis par sujet | +| `SEEDS_LOCALES` | `['fr','en']` | Langues pour les traductions | +