Pitchou

Mieux contrôler les dérogations d'espèces protégées

Installer

Installer docker et docker-compose Peut-être via Docker Desktop, bonne chance !

Architecture

Front-end en Svelte Back-end en Node.js Base de données Postgres

Le serveur récupère les données des dossiers via l'API Démarche Numérique. Il en fait une sauvegarde régulière, parce que Démarches Simplfiées ne sauvegarde les données que temporairement (1 an pour le moment, nous allons demander 5 ans)

En dév

En dev, on peut lancer pnpm run dev pour lancer le tout.
Le repo est synchronisé dans le conteneur du serveur via un volume.
Les données de la base de données sont sauvegarder dans un volume dans le repo (pour faire des test facilement)

http://localhost:2648/ http://localhost:2648/saisie-especes

### Créer une migration

exécuter knex migrate:make <nom de la migration> modifier les fonction up() down() du fichier ./migrations/XXX-nom.js

documentation sur les migrations knex

Types

Pour régénérer tous les types : just generate-types

Regénérer les types des tables SQL

exécuter just generate-types-db Les types sont crées dans le dossier ./scripts/types/database/public

Re-générer les types à partir du schéma DS

just generate-types-ds

Cette commande télécharge aussi la dernière version du schéma avant de créer les types.

Pour éviter le téléchargement et créer les types à partir du fichier schéma existant dans le repo : just generate-types-ds-local

Pour pgadmin

Pour se connecter au serveur postgres depuis un container : ce container doit être exposé au réseau et utiliser postgres_db (le container_name de la base de donnée Postgres) comme hostname

URL pour pgadmin en dev : http://localhost:5050/

Visualiser la documentation en local avec Jekyll

La documentation (dossier docs/) est déployée en production sur GitHub Pages, qui utilise Jekyll pour transformer les fichiers .md en site web statique.

Pour visualiser la documentation en local (avant de pousser sur GitHub), vous pouvez utiliser Docker pour lancer un serveur Jekyll identique à celui de GitHub Pages.

Construire l'image Docker Jekyll

cd docs
docker build -t mon-jekyll .
cd ..

Lancer le serveur Jekyll en local

Toujours depuis la racine du projet :

docker run --rm -p 4000:4000 -v "$PWD/docs":/srv/jekyll -e PAGES_REPO_NWO="dev" mon-jekyll

Le site sera accessible à l'adresse : http://localhost:4000/

Tests automatisés avec Playwright

1. Installer le navigateur de test et les dépendances système: pnpm exec playwright install --with-deps firefox
2. Lancer Pitchou en mode dev: pnpm run dev
3. Lancer les tests pnpm exec playwright test tests/e2e

En prod

pnpm start:production

L'application est déployée sur Scalingo

Nous utilisons l'outil ligne de commande de Scalingo

Base de données

On utilise une base de données Postgres 15.7 en prod

Backups

Scalingo fournit des backups https://doc.scalingo.com/databases/postgresql/backing-up

Actuellement, on a un backup quotidien des 7 derniers jours, un backup hebdomadaire des 4 dernières semaines et 10 backups manuels

Restorer un backup en local

Récupérer le dernier backup

cd backups

# Télécharger le dernier backup
scalingo --app especes-protegees --addon postgresql backups-download

# Dézipper le fichier .pgsql
tar -xf <nom_fichier>.tar.gz
# ignorer le message qui dit "tar: Suppression de « / » au début des noms des membres"

ll # afficher le nom du fichier .pgsql
cd -

Restore le dernier backup

# Supprimer la base de données existante
docker exec postgres_db dropdb -f --username=dev especes_pro_3731

# Recréer la base de données
docker exec postgres_db createdb --username=dev especes_pro_3731

# Restore des données
docker exec postgres_db pg_restore --no-owner --no-privileges --dbname=especes_pro_3731 --username=dev --jobs=6 /var/lib/pitchou/backups/<nom du fichier>.pgsql

Restorer un backup en prod

On peut faire un restore en un clic d'un backup dans l'onglet BACKUPS du dashboard de l'addon PostgreSQL

Sinon, on peut suivre la procédure de la documentation Scalingo

Outils

Migration base de données

knex migrate:latest (fait automatiquement à chaque déploiement, voir package.json scripts.prestart:prod-server)

Pour aller en arrière et en avant d'un cran dans la liste des migrations : pnpm run migrate:down pnpm run migrate:up

Fabriquer la liste des espèces protégées

pour les autocomplete de saisie espèces notamment

node outils/liste-espèces.js

### Ajouter une espèce manquante

Dans le fichier data/sources_especes/espèces_manquantes.ods ajouter l'espèce avec son identifiant INPN (CD_NOM), nom latin (LB_NOM), nom vernaculaire (NOM_VERN) et sa justification légale (LABEL_STATUT).

Puis lancer node outils/liste-espèces.js pour régénérer une liste d'espèces complétée.

### Ajouter une espèce ministérielle ou une espèce CNPN

Dans le fichier data/sources_especes/espèces_ministérielles_cnpn.ods ajouter l'espèce avec son nom scientifique et son nom vernaculaire dans la feuille correspondante. Attention, le nom scientifique doit être exactement le nom latin renseigné dans la colonne LB_NOM du fichier espèces_manquantes.ods.

Puis lancer node outils/liste-espèces.js pour régénérer une liste d'espèces à jour.

Synchroniser dossiers récemment modifiés de Démarche Numérique

En dev

just sync-ds (dernières heures par défaut)

just sync-ds 2025-06-01 (synchroniser les dossiers modifiés depuis le 1 juin 2025)

just sync-ds 2024-01-01 (synchroniser tous les dossiers, date très distantes)

En prod

Synchronisation régulière

Un crontab tourne régulièrement pour récupérer les dossiers récemment modifiés dans DS et les synchroniser en base de données

Pour modifier le cron : https://crontab.guru/

Synchronisation complète ponctuelle

Parfois, notamment après des changements dans le modèle de données, il est nécessaire de synchroniser tous les dossiers

Pour le faire, on peut utiliser un [one-off container}(https://doc.scalingo.com/platform/app/tasks) :

scalingo --app especes-protegees run --size 2XL 'node outils/sync-démarche-numérique.js --IdSchemaDS derogation-especes-protegees --lastModified 2024-01-01'

Lister les liens de connexion en local

Utile pour tester rapidement en local après un restore de backup en tant qu'une personne en particulier

node outils/afficher-liens-de-connexion.js --emails adresse1@e.mail,adresse2@e.mail

Pour les lien de connexion en production :

node outils/afficher-liens-de-connexion.js --emails adresse1@e.mail,adresse2@e.mail --prod

Pour donner l'origine de manière libre :

node outils/afficher-liens-de-connexion.js --emails adresse1@e.mail,adresse2@e.mail --origin 'http://example.net'

GeoMCE

Pitchou maintient une API pour que GeoMCE puisse récupérer les données que Pitchou doit déclarer (GeoMCE ne peut pas ouvrir d'API pour des raisons techniques de leur côté)

Pitchou expose une capability url de la forme /declaration-geomce?secret=XXX

Un outil permet de récupérer la capability url pour la transmettre aux personnes de GeoMCE : scalingo --app especes-protegees run "node outils/geomce.js --capability-url"

En cas de compromission ou régulièrement, la capability-url peut être reset: scalingo --app especes-protegees run "node outils/geomce.js --reset-capability-url"

Outils AARRI

Nettoyage des données d'évènements

Les données de tracking nécessaires à AARRI sont stockées exclusivement dans la table évènement_métrique

Pour des raisons de minimisation des données, de protection des personnes et de conformité au RGPD, nous supprimons les données datant de plus d’un an.

Nous avons un outil qui permet de faire ça. En production : scalingo --app especes-protegees run "node outils/aarri/supprimer-evenements.js"

En dev : node outils/aarri/supprimer-evenements.js

Pour nettoyer tous les évènements concernant une personne spécifique :

node outils/aarri/supprimer-evenements.js --email david@example.net

Pour nettoyer tous les évènements plus vieux que x semaines

node outils/aarri/supprimer-evenements.js --conserver-dernières-semaines 20