Skip to content

Commit 761e689

Browse files
savoisnsavoisn
committed
adding seeds documentation
1 parent 0db7d61 commit 761e689

2 files changed

Lines changed: 165 additions & 0 deletions

File tree

‎docs/en/seeds.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Seeds
2+
3+
## Overview
4+
5+
Seeds populate the database with realistic development data.
6+
They are good examples for understanding the data models and implementing your own framework.
7+
They are driven by `api/db/seeds/seed.js` and use the same `DatabaseBuilder` factory as the test suite.
8+
9+
## Learning Content Hierarchy
10+
11+
Data is built top-down in a tree structure, with each level attached to its parent:
12+
13+
```
14+
Framework → Area → Competence → Thematic → Tube → Skill → Challenge
15+
```
16+
17+
Each builder receives the running `learningContentData` tree so it can link items to their parents. IDs are deterministic (e.g. `areaF0A1`, `skillF0A1C0T0S2Act`, `challengeF0A1C0T0S2Ch0`).
18+
19+
## Skill Generation Pattern
20+
21+
Skills are generated in pairs per level index within each tube:
22+
23+
| Index parity | Skill 1 | Skill 2 |
24+
|---|---|---|
25+
| Even | `actif` v1 | `en construction` v2 |
26+
| Odd | `périmé` v1 | `archivé` v2 |
27+
28+
Tubes whose name contains `workbench` receive a single workbench skill (`en construction`) instead.
29+
30+
## Challenge Generation Pattern
31+
32+
The number and statuses of challenges generated per skill depend on the skill's status:
33+
34+
| Skill status | Challenges created |
35+
|---|---|
36+
| `en construction` | 1 `proposée` proto + 1 `proposée` décli + 1 `périmée` décli |
37+
| `actif` | 1 `validée` proto + 1 `validée` décli + 1 `périmée` décli + 1 `archivée` décli |
38+
| `archivé` | 1 `archivée` proto + 1 `archivée` décli + 1 `périmée` décli |
39+
| `périmé` | 2 `périmées` |
40+
41+
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.
42+
43+
Translations are created for every locale in `SEEDS_LOCALES` for each challenge.
44+
45+
## Other Builders
46+
47+
| File | Description |
48+
|---|---|
49+
| `data/tags.js` | Fixed list of tags |
50+
| `data/tutorials.js` | Fixed list of tutorials, distributed across skills |
51+
| `data/pix-1d.js` | Pix 1D framework, built independently of `seedsConfig` |
52+
| `data/modules.js` | Reads JSON files from `data/modules/*.json` and inserts them as-is |
53+
| `data/static-courses.js` | Fixed set of static courses |
54+
| `data/whitelisted-urls.js` | Fixed set of whitelisted URLs |
55+
56+
## Seed Users
57+
58+
Four users are always created:
59+
60+
| Trigram | Role | API key source |
61+
|---|---|---|
62+
| `DEV` | admin | `REVIEW_APP_ADMIN_USER_API_KEY` or hardcoded default |
63+
| `EDI` | editor | `REVIEW_APP_EDITOR_USER_API_KEY` or hardcoded default |
64+
| `RPO` | readpixonly | `REVIEW_APP_READ_PIX_ONLY_USER_API_KEY` or hardcoded default |
65+
| `LOL` | readonly | `REVIEW_APP_READ_ONLY_USER_API_KEY` or hardcoded default |
66+
67+
Hardcoded API keys are only active when `REVIEW_APP` is not set.
68+
69+
## Configuration
70+
71+
All record counts are controlled by environment variables (defined in `lib/config.js` as `seedsConfig`):
72+
73+
| Env var | Default | Meaning |
74+
|---|---|---|
75+
| `SEEDS_CNT_FRAMEWORKS` | 2 | Number of frameworks |
76+
| `SEEDS_CNT_AREAS` | 2 | Areas per framework |
77+
| `SEEDS_CNT_COMPETENCES` | 2 | Competences per area |
78+
| `SEEDS_CNT_THEMATICS` | 2 | Thematics per competence |
79+
| `SEEDS_CNT_TUBES` | 2 | Tubes per thematic |
80+
| `SEEDS_SKILL_LEVEL` | 3 | Max skill levels per tube |
81+
| `SEEDS_LOCALES` | `['fr','en']` | Locales for translations |
82+
83+

‎docs/fr/seeds.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Seeds
2+
3+
## Vue d'ensemble
4+
5+
Les seeds peuplent la base de données avec des données de développement réalistes.
6+
Ces seeds sont de bons exemples pour s'approprier les modèles de données et implémenter son propre référentiel.
7+
Ils sont pilotés par `api/db/seeds/seed.js` et utilisent la même factory `DatabaseBuilder` que la suite de tests.
8+
9+
## Hiérarchie du contenu pédagogique
10+
11+
Les données sont construites de haut en bas dans une structure arborescente, chaque niveau étant rattaché à son parent :
12+
13+
```
14+
Référentiel → Domaine → Compétence → Thématique → Sujet → Acquis → Épreuve
15+
```
16+
17+
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`).
18+
19+
## Génération des acquis
20+
21+
Les acquis sont générés par paires pour chaque niveau dans un sujet :
22+
23+
| Parité de l'index | Acquis 1 | Acquis 2 |
24+
|---|---|---|
25+
| Pair | `actif` v1 | `en construction` v2 |
26+
| Impair | `périmé` v1 | `archivé` v2 |
27+
28+
Les sujets dont le nom contient `workbench` reçoivent un unique acquis workbench (`en construction`) à la place.
29+
30+
## Génération des épreuves
31+
32+
Le nombre et les statuts des épreuves générées par acquis dépendent du statut de l'acquis :
33+
34+
| Statut de l'acquis | Épreuves créées |
35+
|---|---|
36+
| `en construction` | 1 proto `proposée` + 1 décli `proposée` + 1 décli `périmée` |
37+
| `actif` | 1 proto `validée` + 1 décli `validée` + 1 décli `périmée` + 1 décli `archivée` |
38+
| `archivé` | 1 proto `archivée` + 1 décli `archivée` + 1 décli `périmée` |
39+
| `périmé` | 2 `périmées` |
40+
41+
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.
42+
43+
Des traductions sont créées pour chaque langue de `SEEDS_LOCALES` pour chaque épreuve.
44+
45+
## Autres constructeurs
46+
47+
| Fichier | Description |
48+
|---|---|
49+
| `data/tags.js` | Liste fixe de tags |
50+
| `data/tutorials.js` | Liste fixe de tutoriels, répartis sur les acquis |
51+
| `data/pix-1d.js` | Référentiel Pix 1D, construit indépendamment de `seedsConfig` |
52+
| `data/modules.js` | Lit les fichiers JSON de `data/modules/*.json` et les insère tels quels |
53+
| `data/static-courses.js` | Ensemble fixe de parcours statiques |
54+
| `data/whitelisted-urls.js` | Ensemble fixe d'URLs autorisées |
55+
56+
## Utilisateurs seeds
57+
58+
Quatre utilisateurs sont toujours créés :
59+
60+
| Trigramme | Rôle | Source de la clé API |
61+
|---|---|---|
62+
| `DEV` | admin | `REVIEW_APP_ADMIN_USER_API_KEY` ou valeur par défaut codée en dur |
63+
| `EDI` | editor | `REVIEW_APP_EDITOR_USER_API_KEY` ou valeur par défaut codée en dur |
64+
| `RPO` | readpixonly | `REVIEW_APP_READ_PIX_ONLY_USER_API_KEY` ou valeur par défaut codée en dur |
65+
| `LOL` | readonly | `REVIEW_APP_READ_ONLY_USER_API_KEY` ou valeur par défaut codée en dur |
66+
67+
Les clés API codées en dur ne sont actives que lorsque la variable `REVIEW_APP` n'est pas définie.
68+
69+
## Configuration
70+
71+
Le nombre d'enregistrements est contrôlé par des variables d'environnement (définies dans `lib/config.js` via `seedsConfig`) :
72+
73+
| Variable d'environnement | Défaut | Signification |
74+
|---|---|---|
75+
| `SEEDS_CNT_FRAMEWORKS` | 2 | Nombre de référentiels |
76+
| `SEEDS_CNT_AREAS` | 2 | Domaines par référentiel |
77+
| `SEEDS_CNT_COMPETENCES` | 2 | Compétences par domaine |
78+
| `SEEDS_CNT_THEMATICS` | 2 | Thématiques par compétence |
79+
| `SEEDS_CNT_TUBES` | 2 | Sujets par thématique |
80+
| `SEEDS_SKILL_LEVEL` | 3 | Niveau maximum des acquis par sujet |
81+
| `SEEDS_LOCALES` | `['fr','en']` | Langues pour les traductions |
82+

0 commit comments

Comments
 (0)