concepts for exports

user/exports.md

@@ -13,28 +13,129 @@ Les listes peuvent être filtrées selon différents paramètres: âge de l'usag
 
 Les tableaux reprennent un indicateur (par exemple: nombre de parcours, nombre d'usager, durée moyenne des échanges), dont les données servant de base au calcul de cet indicateur peut également être filtré, mais aussi regroupé selon différents paramètres (exemple: statut du parcours, type d'échange, etc.). Ces exports ressemblent donc aux "tableaux croisés dynamiques" disponibles dans les logiciels de tableur.
 
-## Concepts
+## Fonctionnement général et concepts
+
+### Export d'indicateurs
+
+Les exports fonctionnent comme des tableaux croisés:
+
+- un "export" permet de choisir l'indicateur. 
+  
+  Quelques exemples d'export: nombre de parcours, durée moyenne des parcours, nombre d'usagers, etc.
+
+- des filtres permettent de ne retenir qu'une partie des données. 
+ 
+  Exemple de filtre: uniquement les parcours urgent, les usagers de plus de 18 ans, etc.
+
+- des regroupements créent des "classes statistiques" et permettent d'aggréger les données dans ces classes. 
+
+  Cela permet de connaitre, par exemple, le "nombre d'échange par type d'échange", "le nombre de parcours par référent", etc.
+
+### Listes de données
+
+Au sein des exports, Chill propose des "listes" de données: liste des parcours, liste des usagers, etc.
+
+Ces listes sont des données au format tableur, et chaque colonne comporte une information.
+
+Les filtres des exports d'indicateurs sont disponibles pour les listes: il est donc possible de connaitre la liste des usagers de plus de 18 ans, etc.[^grouping-non-sense]
+
+[^grouping-non-sense]: Les regroupements ne sont pas, eux disponibles: ils n'ont pas de sens dans ce contexte.
+
+### Sauvegarde des exports configurés
+
+Lorsqu'un export est configuré, il peut être sauvegardé par l'utilisateur. Ce dernier lui indique donc un titre et une description. L'export peut alors être re-joué plusieurs fois à partir des exports sauvegardés.
+
+![Sélecteur qui permet d'accéder à la liste des exports enregistrés](img/export_select_saved_exports.png)
+
+Les exports enregistrés peuvent être modifiés et sauvegardés sous un autre nom.
 
 ### Filtres
 
+Les filtres permettent donc de filtrer les données avant l'export.
+
+Ils peuvent être additionnés les uns aux autres: activer deux filtres lors d'un export filtrera les données pour ne retenir que les données qui correspondent aux deux filtres combinés.
+
+Certains filtres demandent des paramètres pour être complétés.
+
 ### Regroupements
 
+Les regroupements permettent de créer des classes statistiques pour regrouper les indicateurs.
+
+Typiquement, chaque regroupement va ajouter une colonne dans le résultat, indiquant la nature de la donnée regroupée. Par exemple, le genre des usagers comptabilisés, le nom du référent du parcours, etc.
+
+Ils peuvent également être combinés les uns aux autres. Dans ce cas, cela se matérialise par l'existence de plusieurs colonnes dans le résultat final: une colonne par regroupement.
+
+Lorsque certaines données ne comportent pas de valeur, la cellule de la colonne du regroupement est généralement vide, ou son libellé est explicite.
+
 #### Regroupements dans le cas de relation un-à-plusieurs
 
+Il existe des relations un-à-plusieurs entre différents éléments, et qui font l'objet d'un regroupement. Quelques exemples: un parcours comporte plusieurs problématiques sociales, un échange peut comporter plusieurs utilisateurs participants, etc.
+
+Dans ce cas, l'indicateur est comptabilisé plusieurs fois: une fois en regard de chaque ligne.
+
+Prenons pour exemple les parcours et les problématiques sociales:
+
+- le parcours n°1 comporte les problématiques "Logement", "Santé" et "Emploi";
+- le parcours n°2 comporte les problématiues "Logement" et "Santé".
+
+Le résultat sera le suivant:
+
+| Problématique | Nombre de parcours | Explication |
+|--------------:|---------:|-----------------------------------------------------|
+|Emploi|1|Seul le parcours n°1 est comptabilisé |
+|Logement|2|Le parcours n°1 et 2 sont concernés|
+|Santé|2|Le parcours n°1 et 2 sont concernés|
+
+Notez que le total des colonnes "nombre de parcours" est supérieur à deux (en l'occurrence il est de 5), alors qu'il y a seulement deux parcours concernés. Il est important d'être attentif à ce comportement lors de la comptabilisation des résultats: l'usage de "totaux" (souvent indiqués en bas de colonne, par exemple) n'est pas pertinent.
+
+### Données historiques
+
+Le logiciel Chill enregistre des données historiques: les référents d'un parcours, les référents des actions, l'appartenance d'un utilisateur à un ménage, etc.
+
+Dès lors, de nombreux filtres et regroupements demandent une "date de calcul" pour ces éléments: il s'agit de la date à laquelle le référent était en position de désignation sur un parcours, l'appartenance de l'usager à un ménage à la date indiquée, etc.
+
 ### Dates glissantes
 
+Les parcours peuvent être enregistrés, et rejoués à des dates différentes.
+
+Dès lors, le logiciel utilise des "dates glissantes" pour indiquer une date, plutôt qu'une valeur absolue. Les "dates glissantes" se matérialisent par un menu déroulant dans lequel l'utilisateur indique un calcul de date: 
+
+- le début de l'année précédente,
+- le début de l'année courante;
+- la date du jour,
+- etc.
+
+Cet indicateur est converti **au moment de la génération de l'export**. Ainsi, le "début du mois précédent" sera le 1er janvier 2023 lorsque l'export est généré le 15 février 2023. Lorsqu'il sera généré le 15 mars 2023, le "début du mois précédent" sera le 1er février 2023.
+
+Il n'y a pas de mention de "fin" d'une période ("fin du mois courant", "fin du mois précédent", etc.), car la fin d'une période est le début de la période suivante.
+
+
 ### Couches et zones géographiques
 
+Les adresses sont localisées, dans Chill. La localisation géographique est enregistrée à l'endroit exact lorsque l'utilisateur a choisi l'adresse dans une liste de référence. Lorsque seul le code postal est choisi parmi les suggestions, alors l'adresse est géolocalisée à l'intérieur de la zone géographique du code postal, de manière aléatoire.
+
+Les administrateurs peuvent injecter dans le logiciel des zones géographiques, qui appartiennent chacune à une "couche". Chaque zone est définie par une frontière (un polygone géographique). Ainsi, la couche des "communes" comportent plusieurs communes, appelées par leur nom. Chaque adresse peut être géographiquement associée à une zone géographique en fonction de la localisation: toutes les adresses à l'intérieur des frontières de la zone est associée à cette zone.
+
+Chill est en mesure de proposer, dès lors,
+
+- des filtres par zone géographiques;
+- des regroupements par couche géographiques;
 
 
-## Liste des exports
+::: {.warning}
+Lorsqu'une adresse n'est pas choisie dans la liste des adresses de référence, l'adresse n'est pas géolocalisée. Les statistiques sont donc inopérantes.
 
-(TODO)
+Cependant, Chill "essaie" de donner un géolocalisation aux adresses nouvellement créées par comparaison avec une adresse existante dans la base de donnée de référence, en comparant le nom de la rue et les codes postaux. Cependant, cet essai n'est pas toujours fructueux.
+:::
 
+::: {.info}
+L'association entre les zones géographiques et les adresses est une opération couteuse, et donc lente, en termes informatiques. Pour permettre de générer des exports rapidement, cette association est calculée une fois par nuit. 
+
+En conséquence, l'association entre la zone géographique et les adresses du jour ne sera pas disponible.
+:::
 
 ## Liste des filtres et regroupements
 
-(Cette documentation est encore incomplète)
 
 <!-- PHPFILE: this list was extracted through this command: find src/ -type f -iname '*.php' | grep Export | grep --invert-match Test | grep --invert-match Helper | grep --invert-match Controller | grep --invert-match Constraint | grep --invert-match DependencyInjection | grep --invert-match Interface | grep --invert-match Declaration | sort -->
 

user/exports_accompanying_period.md

@@ -1,3 +1,9 @@
+### Exports liés aux parcours
+
+- liste des parcours;
+- nombre de parcours;
+- durée moyenne et nombre des participations des usagers aux parcours,
+
 ### Filtres liés aux parcours
 
 #### Filtrer les parcours avec une localisation temporaire ou auprès d'un usager
@@ -229,6 +235,12 @@ Seules les adresses géolocalisées sont prises en compte. Les adresses sont gé
 
 La date de prise en compte de l'adresse doit également être indiquée en paramètre. Il s'agira alors de l'adresse temporaire valable sur le parcours à la date indiquée, ou l'adresse de l'usager à la date indiquée (il faut également qu'il ait été désigné comme "localisant" le parcours à la date indiquée).
 
+::: {.info}
+L'association entre les zones géographiques et les adresses est une opération couteuse, en termes informatique. Dès lors, cette association est calculée une fois par nuit. 
+
+En conséquence, l'association entre la zone géographique et les adresses du jour ne sera pas disponible.
+:::
+
 #### Filtrer les parcours par évaluation
 
 <!-- PHPFILE: src/Bundle/ChillPersonBundle/Export/Filter/AccompanyingCourseFilters/EvaluationFilter.php-->
@@ -465,6 +477,12 @@ La date de prise en compte de l'adresse doit également être indiquée en param
 
 Exemple: si les deux couches "région" et "commune" sont cochées; les adresses sont localisées à la fois au niveau communal, et au niveau régional. DAns les résultats de l'export, chaque usager sera comptabilisé une première fois dans la couche "commune" et une autre fois dans la couche région.
 
+::: {.info}
+L'association entre les zones géographiques et les adresses est une opération couteuse, en termes informatique. Dès lors, cette association est calculée une fois par nuit. 
+
+En conséquence, l'association entre la zone géographique et les adresses du jour ne sera pas disponible.
+:::
+
 #### Grouper les parcours par évaluation
 
 <!-- PHPFILE: src/Bundle/ChillPersonBundle/Export/Aggregator/AccompanyingCourseAggregators/EvaluationAggregator.php-->

user/exports_activity.md

@@ -1,3 +1,26 @@
+### Exports relatifs aux échanges
+
+Les échanges peuvent être créés:
+
+- dans un parcours;
+- dans un dossier d'usager.
+
+Les possibilités d'exports séparent les échanges créés dans un dossier d'usager de ceux créés dans un dossier de parcours.
+
+#### Échanges liés à un parcours
+
+- Nombre d'échanges
+- Somme de la durée des échanges
+- Somme de la durée de déplacement des échanges
+- Moyenne de la durée des échanges
+- Moyenne de la durée de déplacement des échanges
+- Liste des échanges liés à un parcours
+
+#### Échanges liés à un usager
+
+- Nombre d'échanges
+- Durée des échanges
+- Liste des échanges
 
 ### Filtres liés aux échanges
 

user/exports_person.md

@@ -1,4 +1,13 @@
-### Filtre liés aux usagers
+### Exports liés aux usagers
+
+- nombre d'usagers;
+- nombre d'usagers concernés par un parcours;
+- liste des usagers;
+- liste des usagers ayant un parcours d'accompagnement;
+- liste des usagers concernés avec le détail de chaque parcours;
+- liste des doublons.
+
+### Filtres liés aux usagers
 
 #### Filtrer les usagers ayant été associés à un échange au cours de la période
 
@@ -68,6 +77,12 @@ Seules les adresses géolocalisées sont prises en compte. Les adresses sont gé
 
 Une date de calcul permet de ne choisir que les adresses valables à la date donnée.
 
+::: {.info}
+L'association entre les zones géographiques et les adresses est une opération couteuse, en termes informatique. Dès lors, cette association est calculée une fois par nuit. 
+
+En conséquence, l'association entre la zone géographique et les adresses du jour ne sera pas disponible.
+:::
+
 #### Filtrer les usagers par âge
 
 <!-- PHPFILE: src/Bundle/ChillPersonBundle/Export/Filter/PersonFilters/AgeFilter.php-->
@@ -174,6 +189,12 @@ L'adresse utilisée est celle valable à la date indiquée en paramètre.
 
 Exemple: si les deux couches "région" et "commune" sont cochées; les adresses sont localisées à la fois au niveau communal, et au niveau régional. DAns les résultats de l'export, chaque usager sera comptabilisé une première fois dans la couche "commune" et une autre fois dans la couche région.
 
+::: {.info}
+L'association entre les zones géographiques et les adresses est une opération couteuse, en termes informatique. Dès lors, cette association est calculée une fois par nuit. 
+
+En conséquence, l'association entre la zone géographique et les adresses du jour ne sera pas disponible.
+:::
+
 #### Grouper les usagers par âge
 
 <!-- PHPFILE: src/Bundle/ChillPersonBundle/Export/Aggregator/PersonAggregators/AgeAggregator.php-->