|
|
|
---
|
|
|
|
title: Guide du développeur
|
|
|
|
---
|
|
|
|
# Guide du développeur
|
|
|
|
|
|
|
|
Cette page est destinée aux développeurs qui veulent comprendre Satellisync pour assurer sa maintenance. Il n'est pas utile pour les utilisateurs.
|
|
|
|
|
|
|
|
## Principe du programme
|
|
|
|
|
|
|
|
Le programme repose sur Satellys GPU, le site d'emploi du temps (EDT) utilisé par l'IUT à l'heure actuelle (2025). Le site est assez vieux et ne propose pas de connexion vers les agendas connectés (Google Calendar, calendrier Apple, etc...)
|
|
|
|
|
|
|
|
GPU propose cependant un bouton pour exporter l'EDT de la semaine visualisée en VCalendar, un format standard d'événements de calendrier. Le principe est de fournir un service d'API qui, avec un lien statique, va se connecter à GPU en se faisant passer pour un étudiant, récupérer son emploi du temps, et renvoyer le fichier VCalendar en texte brut.
|
|
|
|
|
|
|
|
Le lien statique est donc utilisé comme URL du calendrier dans les logiciels d'agendas connectés, et ce sont ces logiciels qui vont faire une requête GET sur le lien statique et qui récupéreront les événements, pour les afficher dans l'agenda.
|
|
|
|
|
|
|
|
## Architecture du projet
|
|
|
|
|
|
|
|
Le projet est organisé dans un seul dépôt git. Il est lancé via les fichiers dockers, via la commande `docker compose up --build`.
|
|
|
|
|
|
|
|
Les 2 dossiers principaux sont `frontend` et `backend`.
|
|
|
|
|
|
|
|
### Frontend
|
|
|
|
|
|
|
|
Il s'agit de l'interface wet utilisée pour générer les liens. Le site est très petit, il n'y a qu'une seule page.
|
|
|
|
|
|
|
|
Cette partie est réalisée en React avec le langage TypeScript. Il utilise notamment la librairie React-Bootstrap.
|
|
|
|
|
|
|
|
Pour travailler dessus, il est nécessaire de comprendre le framework React. Le langage TypeScript est simplement une extension du Javascript avec des indices de type sur les variables. [React-Bootstrap](https://react-bootstrap.netlify.app/docs/components/accordion) est une librairie très simple, il s'agit seulement de comprendre HTML et les bases de React.
|
|
|
|
|
|
|
|
Le frontend possède un fichier `.env` contenant les variables d'environnement de base, notamment la version affichée. Il convient de garder ce fichier à jour pour avoir la trace de la version dans le code. Les numéros de versions sont basés sur [semver](https://semver.org/lang/fr/), ce n'est pas au feeling.
|
|
|
|
|
|
|
|
Les valeurs de `.env` peuvent être écrasées avec un fichier adjacent `.env.local`, qui prendra la priorité et ne sera pas suivi par git. Par exemple, il peut contenir:
|
|
|
|
|
|
|
|
```
|
|
|
|
VITE_BACKEND_URL="http://localhost:8000"
|
|
|
|
```
|
|
|
|
|
|
|
|
Cela permettra de pointer sur l'API locale si le frontend et le backend sont lancés séparément.
|
|
|
|
|
|
|
|
On utilise aussi la librairie biome, seulement en mode développement, pour vérifier la qualité et la mise en forme du code.
|
|
|
|
|
|
|
|
### Backend
|
|
|
|
|
|
|
|
C'est là que le travail est réalisé. Il s'agit d'un API réalisée en Python avec FastAPI. Il faut connaître Python et le gestionnaire de packages [uv](https://docs.astral.sh/uv/) pour travailler dessus.
|
|
|
|
|
|
|
|
Il est important de noter qu'on n'utilise pas `pip` mais `uv`. Il est écrit en rust et extrêmement rapide, mais ce n'est pas pour ça qu'il a été utilisé. Contrairement à un fichier `requirements.txt` qui contient quelques dépendances et laisse le reste au hasard, uv permet de suivre toutes les dépendances proprement, de la même manière que npm côté frontend. En bonus, uv gère lui-même la création des environnements virtuels.
|
|
|
|
|
|
|
|
On utilise aussi la librairie ruff, seulement en mode développement, pour vérifier la qualité et la mise en forme du code.
|
|
|
|
|
|
|
|
## Conseils de configuration d'IDE
|
|
|
|
|
|
|
|
Cette partie du guide est écrite pour VSCode.
|
|
|
|
|
|
|
|
Installez les extensions pour ruff et biome, en plus des extensions recommandées pour les langages utilisés. Biome et ruff sont beaucoup plus agréables à utiliser quand l'IDE affiche les erreurs en direct.
|
|
|
|
|
|
|
|
Côté backend, une fois que votre `.venv` est créé (voir `backend/README.md`), il faudra préciser où se trouve votre installation de python à vscode. Généralement, il faut cliquer en bas à droite sur le numéro de version de python, et préciser manuellement le chemin de l'interpréteur, `backend/.venv/bin/python`. Je recommande aussi d'activer la vérification des types en python dans les paramètres vscode: `python.analysis.typeChecking`, au minimum sur "standard".
|
|
|
|
|
|
|
|
Côté frontend, à l'heure actuelle, il est préférable d'ouvrir vscode en partant du dossier `frontend` plutôt que de la racine du projet. Sans cela, l'extension biome ne semble pas fonctionner correctement.
|
|
|
|
|
|
|
|
Ensuite, je recommande d'activer ces paramètres de vscode:
|
|
|
|
|
|
|
|
- files.insertFinalNewline
|
|
|
|
- files.trimFinalNewlines
|
|
|
|
- editor.formatOnSave
|
|
|
|
|
|
|
|
Ensuite, préciser l'outil de mise en forme par défaut. Par exemple, pour utiliser ruff comme outil pour python, aller dans les paramètres de vscode, écrire `@id:editor.defaultFormatter @lang:python`, et sélectionner ruff. Il faut faire la même manipulation avec biome pour les différents langages utilisés dans le frontend.
|
|
|
|
|
|
|
|
## Vision pour le futures versions
|
|
|
|
|
|
|
|
Il y a une branche non-terminée dont l'objectif est d'ouvrir le logiciels aux professeurs. Le code est déjà bien avancé. Il faut demander un identifiant ayant un rôle prof pour faire les quelques changements nécessaires pour obtenir le bon type d'agenda. La plus grosse partie des changements est la sécurisation des données dans l'URL.
|
|
|
|
|
|
|
|
Pour un étudiant, l'URL contient seulement le numéro d'étudiant, en clair. On ne sauvegarde pas le mot de passe car c'est le même pour tout le monde et il n'est pas possible de le changer.
|
|
|
|
|
|
|
|
Les professeurs, eux, ont des mots de passe. On doit donc les sauvegarder quelque part. Pour éviter le cauchemar de sécurité d'une base de données, on met tout dans l'URL directement. Seulement, il faut obligatoirement chiffrer les identifiants pour les profs, car l'URL va fuiter à répétition dans les logs, entre autres.
|
|
|
|
|
|
|
|
Pour cela, on utilise un chiffrement symétrique. Le serveur possède une clé. Quand les identifiants seront renseignés la première fois, ils seront chiffrés par le serveur et on vé générer une URL contenant ces données chiffrées. Lorsque l'URL sera requêtée, on pourra utiliser la même clé pour déchiffrer ces informations et se connecter.
|
|
|
|
|
|
|
|
Les identifiants sont donc sécurisés à tout moment. La première fois que le mot de passe, c'est quand l'utilisateur envoie sa requête via le frontend. À ce moment-là, le mot de passe est protégé par le chiffrement HTTPS. Ensuite, tout les échanges contenant le mot de passe seront chiffrés par le serveur. |
|
|
|
\ No newline at end of file |
