# Documentation technique

## Préambule
Ce document vise à décrire d'un point de vue technique de l'application "registre de preuve de covoiturage" construite selon les méthodes des Startups d'État depuis Octobre 2018, grâce au financement de l’équipe par l’ADEME, puis de la DGITM et à l’appui opérationnel de la DINUM.
Le focus est mis sur le backend.

## Concepts
L'application est découpée en services de manière fonctionnelle. Chaque service forme un paquet NodeJS indépendant. Actuellement, l'ensemble est monté en monolithe par le "proxy" mais il est possible de monter chaque service de manière indépendante sans évolution majeure de code.

> Le `proxy` joue un rôle d'_API manager_ (routes, auth)

Pour ce faire, ils ont un socle commun regroupé dans le dépôt "ilos". Ce socle (_framework_) vise à fournir :
- un moteur d'IoC ([Inversion de contrôle](https://fr.wikipedia.org/wiki/Inversion_de_contr%C3%B4le)) ;
- une couche d'abstraction pour appeler les services entre eux au format [JsonRPC](https://www.jsonrpc.org/specification) ;

Pour plus d'informations à ce sujet, il faut se référer à la [documentation d'Ilos](https://ilos.tech/).

## Installation

Nécessite `docker` et `docker-compose`.

1. Clone the repository and `cd` to it
2. `cp api/.env.example api/.env`
3. Edit the `api/.env` file
4. `docker-compose build`
5. `docker-compose run api yarn`
6. `docker-compose run api yarn run build`
7. `docker-compose run api yarn migrate`
8. `docker-compose run api yarn set-permissions`

### Variables d'environnement

| Service | slug | ENV | URL | Folder |
| --------------- | ---------- | ---------------- | -------------------------------------------- | ---------- |
| Frontend \* | `-` | APP_APP_URL | http://localhost:4200 | /dashboard |
| API | `api` | APP_API_URL | http://localhost:8080 | /api |
| Printer | `printer` | APP_PRINTER_URL | http://localhost:3000 | /printer |
| MongoDB \*\* | `mongo` | APP_MONGO_URL | mongodb://mongo:mongo@mongo:27017 | - |
| Redis | `redis` | APP_REDIS_URL | redis://redis:6379 | - |
| Redis Client | `arena` | - | http://localhost:4567 | - |
| Postgres | `postgres` | APP_POSTGRES_URL | postgresql://postgres:postgres@postgres:5432 | - |
| Postgres Client | `pgadmin` | - | http://localhost:5050 | - |

> \* The Frontend doesn't run in Docker. Install NodeJS locally and run it with `yarn start` from the `dashboard` folder.
> \*\* Mongo is being deprecated and will be removed when Postgres migration is complete.
> ⚠️ `docker-compose.yml` is used in `local` environment only

### Utiliser la version `dev` de ilos

Ilos est le _framework_ de micro-services sur lequel l'application est basée.
Son installation en local est nécessaire afin d'utiliser la branche `dev` du code qui n'est pas encore complètement stabilisé.

Procédure d'installation :

# installation de ilos dans le répertoire api/ilos
cd api
git clone https://github.com/betagouv/ilos.git
cd ilos
yarn
yarn build

# installation des paquets Ilos dans l'application et build du code
cd .. (api/)
yarn
yarn build

## Base de données
### Avant propos
L'application utilise une base de données PostgreSQL pour stocker les données persistantes et une base Redis pour gérer les files d'attente des actions asynchrones.

### Commandes
- Appliquer les migrations

docker-compose run api yarn migrate

- Lister les migrations à exécuter

docker-compose run api yarn migrate:check

- Revenir en arrière (1 étape)

docker-compose run api yarn migrate:down

### Démarrer l'application

Terminal 1:
$ cd api
$ docker-compose up api

Terminal 2:
$ cd dashboard
$ yarn start

### Schemas

## Services
### Généralités
#### Avant-propos

Chaque service suit l'architecture suivante :

[root]
   |_ src/
   |   |_ actions/ (3) : les actions exposées par le service
   |   |_ commands/ : les commandes (CLI)
   |   |_ config/ : les fichiers de configuration
   |   |_ interfaces/ : les interfaces
   |   |_ providers/ : les providers consommés par les actions
   |   |_ ServiceProvider.ts (1)
   |   |_ bootstrap.ts (2)
   |_ tests : les tests d'intégration

Les trois éléments les plus importants sont :

1. Le service provider
Cela correspond à la configuration du container d'IoC, on retrouver dedans les bindings entre les interfaces et les providers, la liste des actions à exposer ainsi que les middlewares, les commandes ou autre.

2. Le bootstrap
Simple fichier permettant de charger le _service provider_ et éventuellement d'écraser les paramètres par défaut fournis par Ilos.

3. Les actions
C'est le coeur du réacteur : il s'agit du code métier propre à l'application. Chaque action est exposée par le service, rendant l'appel à cette action possible par un autre service ou directement via une interface (http, cli, etc.).

#### Architecture

graph TD;
acquisition
carpool
certificate
fraud
normalization
policy
proxy
trip

proxy --> acquisition
acquisition --> normalization
acquisition --> |format error| acquisition
normalization --> |data error| acquisition
normalization --> carpool
carpool --> trip
carpool --> fraud
carpool --> policy

### Proxy
#### Objectifs et dépendances
Le proxy est un service un peu particulier puisqu'il n'offre pas directement d'action mais qu'il ouvre un serveur HTTP et lance l'ensemble des services de l'application. Il a vocation à moyen terme à disparaître pour être remplacé par un _reverse-proxy_ ou un _API manager_.

On trouve notamment dedans :
- les middlewares HTTP pour gérer l'authentification des requêtes (Cookies, Token JWT)
- les sessions
- un mapping entre des routes REST et des services (routes publiques)

> Les routes publiques sont au format REST (envoi des preuves, connection d'un utilisateur, etc.)
> Les routes privées sont au format RPC avec un handler global sur la route `/rpc`

Le fichier le plus important dans ce service est `HttpTransport.ts` qui correspond au serveur HTTP.

#### Commandes
- **GeoFetchCommand** : importe les données manquantes de `common.insee` à partir de l'API geo d'Etalab
- **MapIdCommand** (depréciée) : helper pour "réparer" les id
- **MigrateInseeCommand**: seed les données à partir d'API geo
- **ProcessJourneyCommand**: process un couple acquis (voir acquisition)
- **SyncMongoCommand** (déprécié): helper pour la migration mongo
- **UpgradeJourneyCommand** (déprécié)

### Acquisition
#### Objectifs et dépendances
Le service acquisition :
- valide les flux en provenance des opérateurs ;
- les enregistre ;
- les adresse au service de normalization ;

Ce service utilise le schema SQL `acquisition`.

#### Actions
- **CreateJourneyAction** : action d'importation d'un couple passager/conducteur ;
- **CreateLegacyJourneyAction** : action d'importation d'un couple passager/conducteur (v1, déprécié) sera supprimé dès que tous les utilisateurs auront migré vers la nouvelle version de l'API ;
- **LogErrorAction** : enregistre une erreur sur une acquisition (format JSON non validé)

### Application
#### Objectifs et dépendances
Le service application gère la création/révocation des applications (mécanisme d'identification des opérateurs).

Son schema SQL est `application`.

#### Actions
- **CreateApplicationAction** : crée une application pour un opérateur
- **FindApplicationAction** : trouver une application
- **ListApplicationAction** : liste les applications
- **RevokeApplicationAction** : révoque une application

#### Commandes
Les deux commandes **MigrateCommand** et **MigrateDataCommand** sont des helpers pour la migration mongo et sont dépréciées.

### Carpool (covoiturages)
#### Objectifs et dépendances
Carpool centralise les trajets, reconstruit les identités et assemble les couples passager/conducteur pour reformer des voitures.

#### Actions
- **CrosscheckAction** : Procède à l'enregistrement/recollement d'un trajet ;
- **DispatchAction** : à paramétrer, permet de dispatcher un trajet vers d'autres services (fraud, policy, etc.) ;

### Certificate (attestations)
#### Objectifs et dépendances

Génération et impression en PDF ou PNG des attestations de covoiturage des usagers. Par l'intermédiaire de son opérateur, l'usager peut demander un _état des lieux_ de ses trajets de covoiturage sur une période à un instant T. Ce document est produit pour une identité et un opérateur seulement.
Une fois générée, les données sont conservées en base avec un identifiant unique permettant l'impression du document. Une URL publique de vérification inscrite sur l'attestation (avec une version lisible et QR-Code) permet d'afficher les données clé pour une comparaison visuelle.
Aucune comptabilité des € / points n'est effectuée par le Registre.

Les données sont extraites de `carpool` et aggrégées par mois sur la période donnée.

Un log des connexions à l'interface de vérification est conservé dans `certificate.accesslog`.

La conversion en PDF et PNG est effectuée par le service `printer` qui est externalisé par rapport à l'application. Les appels sont sécurisés par des tokens JWT pour limiter l'accès au `printer` et la route de rendu de l'API `certificates/render/:uuid`

#### Actions

- **CreateCertificateAction.ts**: Génère une attestation
- **DownloadCertificateAction.ts**: Télécharge le document généré
- **FindCertificateAction.ts**: Charge une attestation par identifiant unique
- **LogAccessCertificateAction.ts**: Enregistre une entrée dans le log d'accès
- **RenderCertificateAction.ts**: Affiche une page HTML sur base du modèle d'attestation et y injecte les données de l'utilisateur. Cette page est convertie par le _Printer_ en PDF ou PNG.

#### Commandes

- **SeedCommand.ts**: Injecte de FAUSSES données dans la base. A utiliser pour faire des démos seulement.

### Company
#### Objectifs et dépendances
Le service company gère les informations des entités juridiques des opérateurs et des territoires. Elle dépend du service [API entreprise](https://entreprise.data.gouv.fr/) et est consommé par les services `operator` et `territory`.

#### Actions
- **FetchAction** : récupère les données d'une entreprise et la stocke en base ;
- **FindAction** : retourne les données de l'entreprise (recherche par siren)

### Fraud
#### Objectifs et dépendances
Le service fraud contient le moteur de détection d'irrégularité. Il est articulé de la manière suivante :

graph TD;
ext
FraudCheckAction
FraudCheckAllAction
Engine
Check1
Check2
Check3
FraudCheckRepositoryProvider
ext --> FraudCheckAction
ext --> FraudCheckAllAction
FraudCheckAction --> Engine
FraudCheckAllAction --> Engine
Engine -.- Check1
Engine -.- Check2
Engine -.- Check3
Engine --> FraudCheckRepositoryProvider

Les actions utilisent le moteur qui procède à l'application des différents tests. Ceux-ci produisent un résultat qui est enregistré dans la base via le repository.

Le service consomme la vue `common.carpools`.

#### Actions
- **FraudCheckAction** : Lance un test spécifique sur un trajet
- **FraudCheckAllAction** : Lance tous les tests disponibles sur un trajet

### Normalization
#### Objectifs et dépendances
Le service normalization prend un payload d'entrée qui peut être partiellement complet puis standardise les données. Les données standardisées sont envoyées vers carpool, celles qui n'ont pas pu l'être retournent vers l'acquisition.

Ce service n'utilise pas de base de données.

Les erreurs lancées lors des étapes de normalisation sont conservées en base et le processus complet doit être relancé (Pas de re-jeu partiel).

#### Actions
- **NormalizationCostAction** : normalisation des éléments financiers (incitations/cout/etc.)
- **NormalizationGeoAction** : normalisation des éléments géographiques (litteral to geo position, etc.)
- **NormalizationIdentityAction** : normalisation des identités
- **NormalizationRouteAction** : normalisation des meta données (durée, distance)
- **NormalizationTerritoryAction** : ajoute le territoire (recherche par code insee)

### Operator
#### Objectifs et dépendances
Ce service gère les données de opérateurs. Il s'agit principalement d'un CRUD autour de ces données.
Ce service utilise le schema SQL `operator` et consomme le service `company`.

#### Actions
- **CreateOperatorAction** : crée un opérateur
- **DeleteOperatorAction** : supprime un opérateur
- **FindOperatorAction** : trouver un opérateur
- **ListOperatorAction** : liste les opérateurs
- **PatchContactsOperatorAction** : met à jour les contacts d'un opérateur
- **PatchOperatorAction** : met à jour partiellement un opérateur
- **UpdateOperatorAction** : met à jour un opérateur

#### Commandes
Les deux commandes présentes (MigrateCommand et MigrateDataCommand) sont des helpers pour la migration mongo, elles sont dépréciées.

### Policy
#### Objectifs et dépendances
Le service politique gère deux aspects :
- la mise en place de politiques d'incitation ;
- l'application d'une politique d'incitation ;

Le premier aspect est principalement un CRUD. Le second est détaillé dans la rubrique [engine](#Engine)

#### Actions
- **ApplyAction** : applique les politiques sur un trajet
- **CreateCampaignAction** : crée une campagne
- **DeleteCampaignAction** : supprime une campagne
- **LaunchCampaignAction** : lance une campagne
- **ListCampaignAction** : list les campagnes
- **PatchCampaignAction** : met à jour une campagne

#### Commandes
- **PolicyProcessCommand** : applique les politiques sur des trajets ;
- **SeedCommand** : seed la base de données avec les templates de campagne fournit par le registre ;

#### Engine
Le moteur d'incitation fonctionne par trajet (voiture). Pour chaque personne du trajet (conduteur/passager), on process l'ensemble des règles. Le résultat crée une incitation rattaché à la politique et à la personne du trajet (carpool_id).

graph TD
Trip
Campaign
Engine
ProcessableCampaign
RuleSet1
RuleSet2
Rule1
Rule2
Rule3
Incentives
Trip --> Engine
Campaign --> Engine
Engine --> ProcessableCampaign
ProcessableCampaign --> RuleSet1
ProcessableCampaign --> RuleSet2
RuleSet1 --> Rule1
RuleSet1 --> Rule2
RuleSet2 --> Rule3
RuleSet2 --> Rule2
Engine --> Incentives

##### Les parcours
On peut ajouter des règles de deux manières :
- les règles générales, appliquées dans tous les cas ;
- les parcours de règles (RuleSet) qui sont appliqués successivement ;

Si un filtre bloque une personne dans une règle générale, on arrête le traitement. Par contre, si c'est bloqué au niveau d'un parcours, on arrête le parcours et non le traitement.

##### Types de règles
Une règle peut :
- Utiliser les champs suivants valable pour une personne (passager ou conducteur) sur un trajet donné :

- `is_driver` ;
- `is_adult` ;
- `has_travel_pass` ;
- `operator_id` ;
- `operator_class` ;
- `datetime` ;
- `duration` ;
- `start_insee` ;
- `start_territory` ;
- `end_insee` ;
- `end_territory` ;
- `distance` ;
- `seats`.

- Utiliser les champs des autres personnes du même trajet (voir ci-avant)
- Incrémenter des valeurs pour créer des seuils

Il existe plusieurs types de règle définis dans l'engine (par ordre d'application) :

graph TD
Engine
f0(global filters)
Engine-->f0
f0 --> |first|f1
f0 -->|then|f2
subgraph RuleSet2
f2(filters)
t2(transformers)
s2(setters)
m2(modifiers)
f2 --> t2
t2 --> s2
s2 --> m2
end
subgraph RuleSet1
f1(filters)
t1(transformers)
s1(setters)
m1(modifiers)
f1 -->|success| t1
t1 --> s1
s1 --> m1
end

###### 0. Meta règles
Permet de combiner des règles au sein d'une autre règle.
Par exemple : `progressive_distance_range_meta => distance_range_filter + distance_bounding_transformer`

###### 1. Filtres
Les actions sont toutes indépendantes et sont binaires (applicables/non applicables). Si applicable, le parcours peut continuer, sinon le parcours (ou l'ensemble) est stoppé.

* `adult_only_filter` : filtre sur les personnes majeures
* `distance_range_filter` : filtre par borne de distance
* `driver_only_filter` : filtre par conducteur
* `insee_whitelist_filter` : filtre par insee
* `insee_blacklist_filter` : filtre par insee
* `operator_whitelist_filter` : filtre par opérateur
* `passenger_only_filter` : filtre par passager
* `per_km` : multiplie le résultat précedent par le nombre de km du trajet
* `rank_whitelist_filter` : filtre par classe de preuve
* `time_range_filter` : filtre par heure de la journée
* `weekday_filter` : filtre par jour de la semaine

###### 2. Transformers
Permet de modifier le payload qui est en train d'être itéré (pour le parcours seulement).

###### 3. Setters
Initialise le résultat du calcul.
* `fixed_amount_setter` : montant fixe
* `cost_based_amount_setter` : affectation du résultat de l’incitation en fonction du coût du trajet

###### 4. Modifiers
Modifie le résultat.

* `per_passenger_modifier` : multiplie le résultat précédent par le nombre total de passager (prise en compte également du passenger.seat)
* `per_km_modifier` : multiplie le résultat par le nombre de km.

###### 5. Post-processors (interne)
Plus interne, utilisé pour tout ce qui est état de la campagne. Par exemple, tous les seuils : max_trip_...
* `max_amount_restriction` : plafond de montant
* `max_trip_per_target_restriction` : plafond de trajet par passager/conducteur par plage temporelle (jour, mois, campagne)
* `max_amount_per_target_restriction` : plafond de montant par passager/conducteur par plage temporelle (jour, mois, campagne)
* `max_trip_restriction` : plafond de trajet

### Trip
#### Objectifs et dépendances
Le service trip est un service d'exposition des données des trajets uniquement, dont notamment :
- affichage des trajet
- statistiques
- export des données
- export open data

Il dépend de l'alimentation des tables faites par carpool via une vue matérialisée dans son schema sql "trip".

#### Actions
- **BuildExportAction** : envoie un export csv des données par mail via firefox send ;
- **ExportAction** : lance l'export
- **ListAction** : list les trajets
- **RefreshAction** : rafraichit la vue matérializée
- **StatsAction** : renvoit les statistiques

### User
#### Objectifs et dépendances
Ce service accueille les données utilisateurs ainsi qu'une partie de l'authentification (à séparer par la suite ?).
#### Actions
- **ChangePasswordUserAction** : met à jour le mot de passe (user connecté)
- **ChangePasswordWithTokenUserAction** : met à jour le mot de passe via un reset token
- **ChangeRoleUserAction** : met à jour le role de l'utilisateur
- **CheckForgottenTokenUserAction** : vérifie la validité d'un token
- **ConfirmEmailUserAction** : valide un mail via un token
- **CreateUserAction** : créer un utilisateur
- **DeleteUserAction** : supprime un utilisateur
- **FindUserAction** : trouve un utilisateur
- **ForgottenPasswordUserAction** : envoie un token par mail
- **ListUserAction** : liste les utilisateurs
- **LoginUserAction** : challenge le mot de passe d'un utilisateur
- **MeUserAction** : renvoit les informations de l'utilisateur connecté (à déprécier)
- **NotifyUserAction** : adresse une notification à un utilisateur
- **PatchUserAction** : met à jour les informations d'un utilisateur
- **SendConfirmEmailUserAction** : envoie un mail de confirmation à un utilisateur
- **SendInvitationEmailUserAction** : envoie une invitation à un (futur) utilisateur :)

#### Commandes
- **MigrateDataCommand** (déprécie): helper pour la migration mongo
- **SeedUsersCommand** : seed des utilisateurs
- **SetPermissionsCommand** : met à jour les permissions - seeding

### Territoire

#### Process de déploiement manuel du chantier territoire

##### 1 - Application des migrations en production

Application des migrations en ignorant la migration de clean ```20200705000003-update_territory_table.js```

##### 2 - Import de la db de prod

export SCALINGO_POSTGRESQL_URL= ... #accès de la db en production
export LOCAL_SCALINGO_POSTGRESQL_URL= ... # accès db tunnel de prod 

scalingo -a pdc-production db-tunnel -i ~/.ssh/id_rsa_scalingo SCALINGO_POSTGRESQL_URL

pg_dump $LOCAL_SCALINGO_POSTGRESQL_URL -F t > prod_backup.pgsql

pg_restore -d pdc_prod prod_backup.pgsql --no-owner

##### 3 - Application des migrations de données sur `pdc_prod` en local

# synchronisation des données de région
yw @pdc/proxy ilos sync:region_dep


# mise à jour de la table territory_view sur base du contenu migré
psql < api/db/migrations/territory/20200606000004_populate_territory_view.up.sql

##### 4 - Export des données territoires

:::warning
Pas à jour ! Il faut récupérer le bon déroulé pour cette migration
:::

# Exporter les données de territoires en local

echo 'ALTER TABLE territory.territories DISABLE TRIGGER ALL;
ALTER TABLE territory.territory_relation DISABLE TRIGGER ALL;
ALTER TABLE territory.territories_view DISABLE TRIGGER ALL;
ALTER TABLE territory.territory_operators DISABLE TRIGGER ALL;
ALTER TABLE territory.territory_codes DISABLE TRIGGER ALL;
ALTER TABLE territory.insee DISABLE TRIGGER ALL;
ALTER TABLE carpool.carpools DISABLE TRIGGER ALL;
ALTER TABLE auth.users DISABLE TRIGGER ALL;
ALTER TABLE policy.policies DISABLE TRIGGER ALL;
ALTER TABLE trip.list DISABLE TRIGGER ALL;
ALTER TABLE trip.stat_cache DISABLE TRIGGER ALL;

delete from territory.territories;
delete from territory.territory_codes;
delete from territory.territory_relation;
delete from territory.territories_view;
delete from territory.territory_operators;
' > ./territoire.sql
 pg_dump -d pdc_staging --clean --if-exists  --no-owner -F c -f pdc_staging_full_clean.pgsql
 
pg_dump \
    --disable-triggers \
    --data-only \
    -d pdc_local \
    --table territory.territories \
    --table territory.territory_relation  \
    --table territory.territory_code \
    --table territory.territory_view \
    --table territory_operators \
    >> ./territoire.sql

echo '
ALTER TABLE territory.territories ENABLE TRIGGER ALL;
ALTER TABLE territory.territory_relation ENABLE TRIGGER ALL;
ALTER TABLE territory.territories_view ENABLE TRIGGER ALL;
ALTER TABLE territory.territory_operators ENABLE TRIGGER ALL;
ALTER TABLE territory.territory_codes ENABLE TRIGGER ALL;
ALTER TABLE carpool.carpools ENABLE TRIGGER ALL;
ALTER TABLE auth.users ENABLE TRIGGER ALL;
ALTER TABLE policy.policies ENABLE TRIGGER ALL;
ALTER TABLE territory.insee ENABLE TRIGGER ALL;
ALTER TABLE trip.list ENABLE TRIGGER ALL;
ALTER TABLE trip.stat_cache ENABLE TRIGGER ALL;' >> ./territoire.sql

# En production : suppression des données :boom:

\q

# import des données migrées sur le serveur distant
psql $LOCAL_SCALINGO_POSTGRESQL_URL < ./territoire.sql

##### 5 - Application des migrations restantes en production

Réactiver `api/db/migrations/20200705000003-update_territory_table.js` et pousser pour déployer les dernières migrations.

##### 6 - Remplissage de `trip.list`

:::warning
Peut être long en fonction du nombre de trajets à migrer !
:::

À lancer manuellement une fois que toutes les migrations sont faites.

-- migration des données
INSERT INTO trip.list SELECT * FROM trip.list_view;

-- reset de la cache d'affichage
TRUNCATE trip.stat_cache;