From 209a1b4acdb93dac7a6ceb06ddaaadab6d916ef0 Mon Sep 17 00:00:00 2001 From: Vincent Hardouin Date: Wed, 9 Oct 2024 20:20:43 +0200 Subject: [PATCH] doc: improve README.md --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 86 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index bc67ca6..18d323a 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,91 @@ # Gymlib UCPA Facilitator -Ce projet a pour but de me faire gagner du temps lors de mes réservations UCPA via Gymlib. +Ce projet a pour but d'automatiser et simplifier les réservations via Gymlib et UCPA, en minimisant les étapes manuelles. Voici les différentes étapes pour pouvoir préparer correctement sa venue : ![Les différentes étapes de réservation](./docs/étapes-reservation.png) -Le projet est composé actuellement de 5 grandes étapes : +Sur ce schéma, on peut voir des tâches sans valeur ajoutée comme remplir le formulaire de contremarque et les deux temps d'attentes de validation. -1. Vérifier qu'une nouvelle réservation a été demandée sur Gymlib -2. Remplir le formulaire de contremarque UCPA -3. Recevoir une notification dès que l'UCPA a validé les informations avec des créneaux arrangeants qui sont disponibles -4. Créer des évènements dans un calendrier et proposer une url pour s'abonner au calendrier `/reservations/calendar`. -5. Créer un pass Apple Wallet qui se met à jour pour chaque réservation +Pour ces différentes raisons, j'ai automatisé les étapes facilement automatisables jusqu'à la réservation et après la réservation. +Ce qui me permet d'avoir juste à faire une demande de code sur Gymlib, et choisir mon créneau horaire sur le site de l'UCPA. +L'après-réservation est transparente pour moi, car je n'ai rien à faire pour avoir les réservations dans mon calendrier, +et j'ai le QRCode sous la main à mon arrivée. -A venir : +## Plus en détail -2. Me notifier de créneaux qui m'arrangent qui se libèrent +Dans le code, les différentes étapes sont lancées par un CRON et sont découpées de cette manière : -La réservation du créneau se fait donc toujours manuellement sur le site de l'UCPA, mais toutes les étapes contraignantes -et d'attente sont désormais automatisées. +### 1. Vérifier qu'une nouvelle réservation a été demandée sur Gymlib -## Usage +Le code analyse les e-mails reçus en provenance de Gymlib et récupère le code de contremarque dans le contenu de ce dernier. + +### 2. Remplir le formulaire de contremarque UCPA + +Le formulaire ayant un token CSRF, le plus rapide à mettre en place a été de faire remplir le formulaire en utilisant [Puppeteer](https://pptr.dev/), +presque tous les champs du formulaire peuvent être remplis dynamiquement grâce à la variable d'environnement : `FORM_RESPONSE`. +D'ailleurs, en phase de tests, vous pouvez désactiver l'envoi du formulaire grâce à la variable d'environnement `FORM_SUBMIT_ENABLED=false`. + +### 3. Recevoir une notification dès que l'UCPA a validé les informations avec des créneaux arrangeants qui sont disponibles + +Même principe que pour la première étape, le code détecte un e-mail en provenance de l'UCPA pour valider la contremarque +et dire que l'e-billet est disponible sur votre espace personnel. Ensuite, le code cherche les créneaux qui vous arrangent, pour cela, il se base sur la variable d'environnement : + +```dotenv +TIME_SLOTS_PREFERENCES='{ + "sun": [ + "17h00", + ], + "mon": [ + "19h00", + "20h00" + ], +}' +``` + +Cette variable d'environnement n'a pas besoin d'avoir tous les jours de la semaine renseignée. + +### 4. Créer des évènements dans un calendrier + +Tous les créneaux réservés sont ajoutés à un calendrier en utilisant la librairie `ical-generator`. + +Le calendrier est un lien auquel on s'abonne, il est disponible sous l'url `/reservations/calendar/${CALENDAR_ID}`, +où `CALENDAR_ID` correspond à ce qu'il y a dans la variable d'environnement. + +### 5. Mettre à jour le pass Apple Wallet pour chaque réservation à venir + +La génération du pass est géré par la librairie `passkit-generator`, il faut avoir un compte Apple Developer pour générer des pass. + +Les prérequis sont : + +- Avoir un compte Apple Developer +- Générer tous les certificats nécessaires aux pass et les avoir mis dans le dossier `certs` +- Fournir les variables d'environnement nécessaire pour le pass + +```dotenv +CERTIFICATES_SIGNER_KEY_PASSPHRASE= +PASS_TYPE_IDENTIFIER= +PASS_TEAM_IDENTIFIER= +``` + +Pour le pass, il faut d'abord en créer un. Pour ça, nous devons récupérer un token : + +```shell +ACCESS_TOKEN=$(node --input-type=module --eval "console.log(await (await import('./src/infrastructure/jsonWebTokenService.js')).jsonWebTokenService.generateToken({}));") +``` + +Après avoir obtenu notre token, nous pouvons faire un curl pour créer le pass : + +```shell +curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:4000/pass +``` + +## A venir : + +1. Me notifier de créneaux qui m'arrangent qui se libèrent + +## Usage en développement 1. Copier le sample.env dans un fichier .env @@ -36,13 +100,13 @@ cp sample.env .env npm ci ``` -4. Lancer la base de donnée +4. Lancer la base de données ```shell docker compose up -d ``` -5. Créer la base de donnée +5. Créer la base de données ```shell npm run db:prepare @@ -53,3 +117,11 @@ npm run db:prepare ```shell npm start ``` + +Voilà votre environnement est prêt ! + +## Contribuer + +Les contributions sont les bienvenues ! +Que ce soit pour corriger des bugs, ajouter de nouvelles fonctionnalités ou améliorer la documentation, +n'hésitez pas à ouvrir une issue ou à proposer une pull request.