ungdev · AlbanSdl · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025 · Oct 17, 2025
diff --git a/.env.dist b/.env.dist
@@ -18,6 +18,9 @@ LDAP_USER=
 LDAP_PWD=
 
 ANNAL_UPLOAD_DIR=uploads/exams/
+MEDIA_UPLOAD_DIR=uploads/media
+MEDIA_DETACHED_LIFESPAN=1
+
 CAS_URL=https://cas.utt.fr/cas
 CAS_SERVICE=http://localhost:8080
 

diff --git a/.env.test.dist b/.env.test.dist
@@ -14,6 +14,9 @@ PAGINATION_PAGE_SIZE=20
 FAKER_SEED=42
 
 ANNAL_UPLOAD_DIR=uploads/exams/
+MEDIA_UPLOAD_DIR=uploads/media
+MEDIA_DETACHED_LIFESPAN=1
+
 CAS_URL=https://cas.utt.fr/cas
 CAS_SERVICE=https://etu.utt.fr/login
 LDAP_URL=ldap://localhost:3002

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -50,11 +50,36 @@
       - run: pnpm prisma generate
       - run: pnpm build
 
+  docs:
+    runs-on: self-hosted
+    strategy:
+      matrix:
+        node-version: [22]
+        pnpm-version: [10]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ matrix.pnpm-version }}
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          package-manager-cache: false
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+      - name: Use Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+      - run: pnpm build:docs:configure
+      - run: pnpm build:docs
+
   test:
     runs-on: self-hosted
     strategy:
      matrix:
        node-version: [22]
        pnpm-version: [10]
    env:
      DATABASE_URL: mysql://dev:dev@localhost:3306/etuutt_test

diff --git a/docs/conf.py b/docs/conf.py
@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'EtuUTT'
-copyright = '2024, UTT Net Group'
+copyright = '2025, UTT Net Group'
 author = 'UTT Net Group'
 
 
@@ -52,7 +52,14 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'shibuya'
+html_theme_options = {
+    "accent_color": "blue",
+    "github_url": "https://github.com/ungdev/etu-utt-api",
+    "announcement": "<center>Le site étu est toujours en cours de développement : la documentation est en cours d'écriture et peux être incomplète/incorrecte.</center>",
+}
+html_favicon = "logo.svg"
+html_logo = "logo.svg"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -64,4 +71,5 @@
     '.md': 'markdown',
 }
 
-myst_enable_extensions = ["attrs_inline"]
+myst_enable_extensions = ["attrs_inline"]
+myst_heading_anchors = 4
diff --git a/docs/doc_developers/api/index.md b/docs/doc_developers/api/index.md
@@ -1,4 +1,4 @@
-# Documentation développeurs - API
+# API
 
 Cette documentation s'adresse aux développeurs de l'API de EtuUTT. Elle traite des aspects techniques la concernant :
 outils utilisés, outils développés, choix faits, ...
@@ -10,6 +10,11 @@ setup.md
 nestjs.md
 conventions.md
 test.md
+documentation.md
+errors.md
+permissions.md
+lexical.md
 ues.md
 timetables.md
+scripts.md
 ```
diff --git a/docs/doc_developers/api/lexical.md b/docs/doc_developers/api/lexical.md
@@ -0,0 +1,88 @@
+# Texte formatable
+
+```{danger}
+*Le texte formatable est un **sujet de travail actuel**. Son implémentation est susceptible de changer.* \
+Par ailleurs, il est possible que cette fonctionnalité soit séparée dans un package nodejs indépendant.
+```
+
+A certains endroits du site étu, les utilisateurs pourront formatter du texte. Nous avons décidé de nous baser sur une bibliothèque, [lexical](https://lexical.dev) ([github](https://github.com/facebook/lexical)). Bien que l'utilisateur puisse envoyer du contenu formatté sur à peu près n'importe quel champ texte de l'api (à condition de respecter la limite de caractères), il n'y a que quelques champs qui supportent réellement le texte formatté.
+
+```{warning}
+Les champs qui ne supportent pas le texte formatté acceptent **pour le moment** des inputs formattés. Cependant, ces champs ne seront pas traités comme telles par les applications front-end (comme le front du site étu). Cela peut donner lieu à un affichage considéré comme buggé si la feature est mal utilisée par certaines implémentations front-end !
+```
+
+## Abbréviations dans ce document
+
+Nous utiliserons dans ce documents les abbréviations/anglicismes suivantes :
+
+- RTE: Rich Text Editor, l'éditeur de texte dans lequel l'utilisateur peut formater du texte
+- Renderer: côté serveur, la fonction qui transforme du contenu lexical en html
+- Document Object Model (DOM): la structure d'un document, généralement HTML. On l'utilisera ici pour parler de tout ce qui est relatif à l'affichage du texte formatable.
+
+## Les bundles
+
+Un bundle est la définition de l'ensemble des contenus supportés par une zone de texte formatable. Il contient des [nodes](#node) et, pour le front, des [plugins](#plugin) et des [composants de toolbar](#composant-de-toolbar).
+La définition d'un bundle permet de configurer plusieurs RTE ou Renderers de manière identique.
+
+Détaillons maintenant les différents éléments contenu dans un bundle :
+
+### Node
+
+Une node est une partie du texte ou un élément visuel que l'utilisateur peut ajouter à son texte. Il peut s'agir par exemple d'images, d'émojis customs, ou de texte avec un fond coloré.
+Pour créer de nouvelles capacités/de nouveaux éléments dans le texte formatté, la première étape est de créer une `class` qui hérite de `ElementNode`, `TextNode` ou `DecoratorNode`. Pour voir les méthodes à implémenter, regarde [la doc de lexical](https://lexical.dev/docs/concepts/nodes#creating-custom-nodes). Comme indiqué plus bas dans la doc, tu peux utiliser [`$config` et ne pas implémenter les 3 fonctions statiques](https://lexical.dev/docs/concepts/nodes#extending-elementnode-with-config).
+
+```{tip}
+Seule les `DecoratorNode` pourront être rendues avec une ReactNode côté front (cf. `DecoratorNode#decorate`). Si tu n'as pas envie d'écrire des opérations DOM, cela peut être une bonne solution 😉
+```
+
+Lorsque tu appliques des classes à des éléments, fais bien attention à prendre celles du thème de l'éditeur, `editor.theme[className]`. Tu pourrais sinon oublier de les implémenter de l'autre côté (serveur/client) et le rendu serait alors différent !
+
+Si tu souhaites remplacer une node déjà définie, tu peux enregistrer des [remplacements](https://lexical.dev/docs/concepts/node-replacement). Cela t'évitera de devoir copier-coller tout son code, et à chaque fois qu'une node remplacée sera créée, elle sera transformée en ta nouvelle node à l'aide de la fonction que tu auras définie !
+
+### Plugin
+
+Les plugins n'existent que côté front-end. Ce sont eux qui vont ajouter de la logique, tu vas pouvoir:
+
+- écouter des [évènements](https://lexical.dev/docs/concepts/commands), à l'aide de `editor.registerCommand()`
+- enregistrer des [transformers](https://lexical.dev/docs/concepts/transforms) avec `editor.registerNodeTransform()`
+- en react, utiliser `useEffect`
+- rendre un élément supplémentaire, un overlay par exemple
+
+```{admonition} TLDR
+:class: tip
+Un transformer, c'est du code qui va te permettre de transformer du contenu dans le RTE au fur et à mesure qu'il est ajouté. Par exemple, tu peux transformer automatiquement `:joy:` en l'émoji correspondant, 😂.
+```
+
+### Composant de toolbar
+
+Ce qui permettra à l'utilisateur d'intéragir avec tes nodes depuis une interface.
+
+A l'heure actuelle, ces composants n'existent pas encore en tant que tel et font partie du composant `ToolbarPlugin`. Leur future séparation permettra d'ajouter facilement des composants (boutons, etc) custom dans cette toolbar.
+
+## Côté serveur
+
+Bien que le serveur n'ait pas à gérer l'édition en temps réel, il doit pouvoir effectuer quelques opérations sur le contenu généré par l'utilisateur. Cela inclut la validation du contenu lexical et l'export en HTML (pour pouvoir l'utiliser dans des emails par exemple).
+
+```{admonition} Structure Lexical
+La structure envoyée entre le client est le front est un JSON (créé avec `LexicalNode#exportJSON`). Il contient les nodes imbriquées les unes dans les autres.
+```
+
+### La validation
+
+La validation vérifie que le contenu fourni utilisateur a bien une structure comprise par le serveur. Cela vérifie :
+
+- que c'est bien du JSON
+- que l'éditeur lexical le comprend
+- qu'il n'y a pas de node absente du bundle
+- qu'il n'y a pas de propriétés inconnues sur les nodes
+
+```{attention}
+Les propriétés des nodes doivent apparaitre dans le même sens lors de l'exportJSON côté front et côté serveur.
+```
+
+### Le rendu
+
+Le rendu permet au serveur de transformer du contenu lexical en html. Il faut faire attention à deux points ici :
+
+- les méthodes `DecoratorNode#decorate` doivent être enlevées et le contenu de la node doit être traduit en instructions DOM dans `DecoratorNode#createDOM`
+- les styles appliqués sur le front doivent être réappliqués sur le DOM produit sur l'API. Cela peut nécessiter des modifications structurelles dans l'HTML généré. En cas de besoin, il est possible d'ajouter des conditions spécifiques dans `NodeStyleInjector.ts`
diff --git a/docs/doc_developers/api/nestjs.md b/docs/doc_developers/api/nestjs.md
@@ -228,7 +228,7 @@ export class DummyModule {}
 ```
 
 ```{tip}
-L'API de EtuUTT utilise des guards personnalisés, ils sont listés [ici](#outils-specifiques-de-etuutt).
+L'API de EtuUTT utilise des guards personnalisés, ils sont listés [ici](#outils-spécifiques-du-site-étu).
 ```
 
 ### Les interceptors [_(docs)_](https://docs.nestjs.com/interceptors)
@@ -292,7 +292,7 @@ Voici une illustration qui permet de récapituler les différentes étapes dans
 
 ### La gestion des erreurs
 
-Nous avons implémenté des messages d'erreurs customisés, voir la page sur [la gestion des erreurs]().
+Nous avons implémenté des messages d'erreurs customisés, voir la page sur [la gestion des erreurs](errors.md).
 
 ### L'authentification nécessaire par défaut
 

diff --git a/docs/doc_developers/api/setup.md b/docs/doc_developers/api/setup.md
@@ -171,14 +171,10 @@ Les tests sont tous lancés. Au bout de quelques secondes / minutes, tous les te
 
 Pour cela, vous devez avoir Python3 installé.
 
-Il faut commencer par installer les dépendances :
-
 ```bash
-# Pour les commandes pip, il est possible d'utiliser python -m pip (ou python3 -m pip) à la place de pip.
-cd docs
-pip install --upgrade pip setuptools sphinx readthedocs-sphinx-ext
-pip install -r docs/requirements.txt
-python -m sphinx -T -b html -d _build/doctrees -D language=fr . build/html
+# Pour la première commande, il faut la faire uniquement la première fois, elle va installer les dépendances python
+pnpm build:docs:configure
+pnpm build:docs
 ```
 
 Le résultat du build se situe alors dans `docs/build/html`. Le fichier racine est `index.html`. Le résultat de la

diff --git a/docs/doc_developers/front/index.md b/docs/doc_developers/front/index.md
@@ -1,4 +1,4 @@
-# Documentation développeurs - Site web
+# Site web
 
 Cette documentation s'adresse aux développeurs du site web de EtuUTT. Elle traite des aspects techniques le concernant :
 outils utilisés, outils développés, choix faits, ...

diff --git a/docs/doc_developers/index.md b/docs/doc_developers/index.md
@@ -1,4 +1,4 @@
-# Documentation développeurs
+# Développeurs
 
 Cette documentation s'adresse aux développeurs de EtuUTT. Elle traite des aspects techniques de l'API, de l'application
 mobile et du site web : outils utilisés, outils développés, choix faits, ...

diff --git a/docs/doc_developers/mobile_app/index.md b/docs/doc_developers/mobile_app/index.md
@@ -1,4 +1,4 @@
-# Documentation EtuUTT - Application mobile
+# Application mobile
 
 Cette documentation s'adresse aux développeurs de l'appli MyUTT. Elle traite des aspects techniques la concernant :
 outils utilisés, outils développés, choix faits, ...

diff --git a/docs/logo.svg b/docs/logo.svg
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,3 @@
 myst-parser
 sphinx
-sphinx-rtd-theme
+shibuya
diff --git a/package.json b/package.json
@@ -7,6 +7,8 @@
   "license": "UNLICENSED",
   "scripts": {
     "build": "npx nest build",
+    "build:docs": "python3 -m sphinx -W -T -b html -d docs/build/doctrees -D language=fr docs docs/build/html",
+    "build:docs:configure": "pip install --upgrade pip setuptools sphinx readthedocs-sphinx-ext && pip install -r docs/requirements.txt",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "start": "NODE_ENV=development npx nest start",
     "start:dev": "NODE_ENV=development npx nest start --watch",
@@ -37,6 +39,14 @@
   },
   "dependencies": {
     "@fast-csv/parse": "^5.0.2",
+    "@lexical/code": "^0.37.0",
+    "@lexical/extension": "^0.37.0",
+    "@lexical/headless": "^0.37.0",
+    "@lexical/html": "^0.37.0",
+    "@lexical/link": "^0.37.0",
+    "@lexical/list": "^0.37.0",
+    "@lexical/rich-text": "^0.37.0",
+    "@lexical/table": "^0.37.0",
     "@nestjs/axios": "^4.0.0",
     "@nestjs/common": "^11.0.11",
     "@nestjs/config": "^4.0.1",
@@ -53,6 +63,7 @@
     "fast-xml-parser": "^5.0.9",
     "file-type": "^20.4.1",
     "ldapts": "^7.3.1",
+    "lexical": "^0.37.0",
     "multer": "1.4.5-lts.1",
     "pactum-matchers": "^1.1.7",
     "passport-jwt": "^4.0.1",