docs: add documentation for new features (wip)

Creation d'un nouveau fichier pour expliquer l'entrée par groupe de site et site Modification de la présentation du module monitoring Modification du paragraphe de Permissions Ajout d'images descriptives Reviewed-by: andriacap docs: add description type site form Add part to explain link between type site field in edit and creation site form Reviewed-by: andriacap
PnX-SI · Oct 4, 2024 · 1969b0e · 1969b0e
1 parent e0e1a05
commit 1969b0e
Show file tree

Hide file tree

Showing 10 changed files with 182 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 ## Module générique de gestion des données de protocoles de type suivis
 
-Ce module permet de gérer de façon générique des données de protocoles "simples" articulés en 3 niveaux : des sites (nom, type, localisation) dans lesquels on fait des visites (dates, observateurs) dans lesquelles on peut faire des observations (espèces).
+Ce module permet de gérer de façon générique des données de protocoles "simples" articulés jusqu'à 4 niveaux : des groupes de site, puis des sites associés à ces groupes de site (nom, type, localisation) dans lesquels on fait des visites (dates, observateurs) dans lesquelles on peut faire des observations (espèces).
 
-Ces 3 niveaux peuvent être complétés des données spécifiques à chaque protocole, qui sont stockées dynamiquement dans la base de données sous forme de jsonb.
+Les 3 niveaux que sont le sites, visites et observations peuvent être complétés des données spécifiques à chaque protocole, qui sont stockées dynamiquement dans la base de données sous forme de jsonb.
 
 ![Liste des sites du protocole de test](docs/images/apercu.png)
 
@@ -16,14 +16,21 @@ Pour chaque sous-module, correspondant à un protocole spécifique de suivi, il
 
 Des fonctions SQL ainsi qu'une vue définie pour chaque protocole permettent d'alimenter automatiquement la synthèse de GeoNature à partir des données saisies dans chaque sous-module.
 
-![MCD du schema gn_monitoring](docs/images/2020-06-MCD-monitoring.jpg)
+Via le module monitoring on peut également entrer directement via les sites et groupes de sites. Il est possible de crééer des groups de sites, des sites, associer des sites à des groupes de sites et ensuite pouvoir associer ces sites / groupes de site à différents sous modules.
+
+![Page d'accueil accès aux sites](docs/images/page_accueil_monitoring_acces_sites.png)
+
+Les sites et groupes de sites sont désormais multi protocoles.
+
+![MCD du schema gn_monitoring](docs/images/2023-10-MCD_schema_monitoring.png)
 
 ## Sommaire
 
 * [Installation](#installation)
 * [Gestion de la synthèse](docs/synthese.md)
 * [Documentation technique](docs/documentation_technique.md)
 * [Création d'un sous-module](docs/sous_module.md)
+* [Gestion des sites et groupes de site](docs/gestion_sites_groupes_de_site.md)
 * [Mise à jour du module](docs/MAJ.md)
 * [Liste des commandes](docs/commandes.md)
 * [Permissions](#permissions)
@@ -69,7 +76,32 @@ Créer le dossier suivant dans le dossier `media` de GeoNature
 mkdir ~/geonature/backend/media/monitorings
 ```
 
-Il vous faut désormais attribuer des permissions aux groupes ou utilisateurs que vous souhaitez, pour qu'ils puissent accéder et utiliser le module (voir https://docs.geonature.fr/admin-manual.html#gestion-des-droits). Si besoin une commande permet d'attribuer automatiquement toutes les permissions dans tous les modules à un groupe ou utilisateur administrateur.
+Il vous faut désormais attribuer des permissions aux groupes ou utilisateurs que vous souhaitez, pour qu'ils puissent accéder et utiliser le module (voir <https://docs.geonature.fr/admin-manual.html#gestion-des-droits>). Si besoin une commande permet d'attribuer automatiquement toutes les permissions dans tous les modules à un groupe ou utilisateur administrateur.
+
+### Configuration générale du module monitoring
+
+Un fichier de config `monitorings_config.toml.example` peut être modifié puis copié à la racine du dossier de config de GeoNature : `~/geonature/config`.
+
+Trois champs sont paramétrable :
+
+- `TITLE_MODULE` : Titre présent sur la page d'accueil du module monitoring
+- `DESCRIPTION_MODULE` : Description du module monitoring également présente sur la page d'accueil
+- `CODE_OBSERVERS_LIST` : Liste d'observateur qui est utilisé pour le fichier de config de `site.json` , qui permet d'avoir une liste d'observateur spécifique aux créateurs lorsqu'on entre directement par les sites/groupe de site . (Par défaut c'est la liste d'observateur occtax qui est utilisée)
+
+<details open><summary> Exemple d'utilisation du paramètre `CODE_OBSERVERS_LIST`</summary>
+
+```json
+"id_inventor": {
+      "type_widget": "observers",
+      "attribut_label": "Observateur",
+      "type_util": "user",
+      "code_list":"CODE_OBSERVERS_LIST",
+      "required": true,
+      "multi_select": false
+}
+```
+
+</details>
 
 ### Installation d'un sous-module
 
@@ -131,7 +163,7 @@ Modules installés :
 - module2: Module 2 (Deuxième exemple de module)
 ```
 
-Il vous faut désormais attribuer des permissions aux groupes ou utilisateurs que vous souhaitez, pour qu'ils puissent accéder et utiliser le sous-module (voir https://docs.geonature.fr/admin-manual.html#gestion-des-droits). Si besoin une commande permet d'attribuer automatiquement toutes les permissions dans tous les modules à un groupe ou utilisateur administrateur.
+Il vous faut désormais attribuer des permissions aux groupes ou utilisateurs que vous souhaitez, pour qu'ils puissent accéder et utiliser le sous-module (voir <https://docs.geonature.fr/admin-manual.html#gestion-des-droits>). Si besoin une commande permet d'attribuer automatiquement toutes les permissions dans tous les modules à un groupe ou utilisateur administrateur.
 
 ### Configurer le sous-module
 
@@ -179,19 +211,20 @@ D'autres exemples de sous-modules sont disponibles sur le dépôt
 
 ## Permissions
 
-Les permissions ne sont implémentées que partiellement. La notion de portée (mes données, les données de mon organisme, toutes les données) n'est pas prise en compte. Si un utilisateur a le droit de réaliser une action sur un type d'objet, il peut le faire sur l'ensemble des données.
+Les permissions peuvent désormais être définies avec une notion de portée ('mes données', 'les données de mon organisme', 'toutes les données' si on ne précise pas de portée mais qu'on accorde une permission). Ces permissions peuvent être définies sur chaque objet défini ci dessous.
 
 La gestion des permissions pour les rôles (utilisateur ou groupe) se réalise au niveau de l'interface d'administration des permissions de GeoNature.
 
-Les permissions sont définis pour chaque type d'objet (modules, groupes de sites, sites, visites et observations) :
- * MONITORINGS_MODULES - R : permet a l'utilisateur d'accéder au module, de le voir dans la liste des modules
- * MONITORINGS_MODULES - U : action administrateur qui permet de configurer le module et de synchroniser la synthèse
- * MONITORINGS_MODULES - E : action qui permet aux utilisateurs d'exporter les données (si défini par le module)
- * MONITORINGS_GRP_SITES - CRUD : action de lire, créer, modifier, supprimer un groupe de site
- * MONITORINGS_SITES - CRUD : action de lire, créer, modifier, supprimer un site
- * MONITORINGS_VISITES - CRUD : action de lire, créer, modifier, supprimer les visites, observations, observations détails
+Les permissions sont définis pour chaque type d'objet (modules, groupes de sites, sites, visites, observations et types de site) :
 
-Par défaut, dès qu'un utilisateur a un droit supérieur à 0 pour une action (c-a-d aucune portée) il peut réaliser cette action.
+- MONITORINGS_MODULES - R : permet a l'utilisateur d'accéder au module, de le voir dans la liste des modules
+- MONITORINGS_MODULES - U : action administrateur qui permet de configurer le module et de synchroniser la synthèse
+- MONITORINGS_MODULES - E : action qui permet aux utilisateurs d'exporter les données (si défini par le module)
+- MONITORINGS_GRP_SITES - CRUD : action de lire, créer, modifier, supprimer un groupe de site
+- MONITORINGS_SITES - CRUD : action de lire, créer, modifier, supprimer un site
+- MONITORINGS_VISITES - CRUD : action de lire, créer, modifier, supprimer les visites, observations, observations détails
+- TYPES_SITES- CRUD : action de lire, créer, modifier, supprimer les types de sites via l'interface administrateur
 
+Par défaut, dès qu'un utilisateur a un droit supérieur à 0 pour une action (c-a-d aucune portée) il peut réaliser cette action.
 
 Il est possible de mettre à jour les permissions disponibles pour un module en utilisant la commande `update_module_available_permissions`
diff --git a/docs/gestion_sites_groupes_de_site.md b/docs/gestion_sites_groupes_de_site.md
@@ -0,0 +1,101 @@
+# Entrée par les sites et groupes de sites
+
+Il est possible de créer, éditer, supprimer, modifier des sites et des groupes de site de manière indépendante à la gestion de sous modules.
+
+Lorsqu'on entre par `Accès aux sites` depuis la page d'accueil (voir image ci dessous) on arrive sur deux onglets : `Groupe de sites` et `Sites`.
+
+<details open><summary> Image représentant la page d'accueil avec l'accès aux sites</summary>
+
+![Accès aux sites depuis la page d'accueil](docs/../images/page_accueil_monitoring_acces_sites.png)
+
+</details>
+
+Via ces deux onglets on peut créer , éditer, supprimer des groupes de sites et des sites.
+On peut ensuite directement via l'onglet "Sites" créer des visites en choisissant au préalable le protocole qui sera associé au site (voir exemple image ci dessous). La liste des protocoles sélectionnables dépend des types de site associés aux protocoles (comme expliqué [ici](./sous_module.md#structure-dun-module) )
+
+<details open><summary> Image représentant l'ajout d'une visite en passant par l'ongle "Site"</summary>
+
+![Ajout de visite enfant à un site avec chpix de protocole](docs/../images/ajout_visite_via_site.png)
+
+</details>
+
+Dans le formulaire d'édition et de création de site il y a un champ `Choix des types de sites` obligatoire et qui est lié au fichier de configuration créer dans l'interface administrateur dans le menu `TYPES DE SITES`.
+La structure du fichier de configuration d'un type de site est basé sur le même modèle que ceux présentés [ici](./sous_module.md#définir-une-nouvelle-variable) dans la partie `Configuration sous module` .
+
+<details open>
+<summary>Exemple d'un fichier de configuration de type de site (ici pour l'Eolienne)</summary>
+
+```json
+{
+  "display_list": ["modele_eolienne", "contexte_saisie"],
+  "display_properties": [
+    "type_lisiere",
+    "diametre_rotor",
+    "modele_eolienne",
+    "contexte_saisie",
+    "distance_lisiere",
+    "hauteur_eolienne"
+  ],
+  "filters": {
+    "inactif": false
+  },
+  "genre": "M",
+  "geometry_type": "Point",
+  "label": "Eolienne",
+  "label_list": "Eoliennes",
+  "sorts": [
+    {
+      "dir": "asc",
+      "prop": "last_visit"
+    }
+  ],
+  "specific": {
+    "contexte_saisie": {
+      "attribut_label": "Contexte de saisie",
+      "required": true,
+      "type_widget": "select",
+      "values": ["Ini: initial", "Rep: repowering", "Ext: extension"]
+    },
+    "diametre_rotor": {
+      "attribut_label": "Diamètre du rotor",
+      "min": 0,
+      "required": true,
+      "type_widget": "number"
+    },
+    "distance_lisiere": {
+      "attribut_label": "Distance à la lisière arborée",
+      "min": 0,
+      "required": true,
+      "type_widget": "number"
+    },
+    "hauteur_eolienne": {
+      "attribut_label": "Hauteur éolienne",
+      "min": 0,
+      "required": true,
+      "type_widget": "number"
+    },
+    "modele_eolienne": {
+      "attribut_label": "Modèle de l'éolienne",
+      "required": true,
+      "type_widget": "text"
+    },
+    "type_lisiere": {
+      "attribut_label": "Type de lisière la plus proche",
+      "required": true,
+      "type_widget": "select",
+      "values": ["Haie: Haie", "Foret: Forêt"]
+    }
+  }
+}
+```
+
+<details open>
+<summary>
+Et ci dessous l'image représentant le formulaire d'édition d'un site au quel on ajoute un type de site Eolienne
+</summary>
+
+![image représentant le formulaire d'édition d'un site au quel on ajoute un type de site Eolienne](./images/formulaire_site_type_site_champs.png)
+
+</details>
+
+</details>
diff --git a/docs/images/2023-10-MCD_schema_monitoring.png b/docs/images/2023-10-MCD_schema_monitoring.png
diff --git a/docs/images/ajout_visite_via_site.png b/docs/images/ajout_visite_via_site.png
diff --git a/docs/images/formulaire_site_type_site_champs.png b/docs/images/formulaire_site_type_site_champs.png
diff --git a/docs/images/page_accueil_monitoring_acces_sites.png b/docs/images/page_accueil_monitoring_acces_sites.png
diff --git a/docs/images/type_site_module_config_admin_panel.png b/docs/images/type_site_module_config_admin_panel.png
diff --git a/docs/images/type_site_module_config_admin_panel_config.png b/docs/images/type_site_module_config_admin_panel_config.png
diff --git a/docs/images/type_site_module_config_front.png b/docs/images/type_site_module_config_front.png
diff --git a/docs/sous_module.md b/docs/sous_module.md
@@ -36,6 +36,31 @@ title: 'Création d''un sous-module'
 * `nomenclature.json` (pour l'ajout de nomenclatures spécifiques au sous-module)
 * `synthese.sql` (vue pour la synchronisation avec la synthèse) voir
 
+S'ajoute à ces fichiers,  des fichiers de config de `types de site` que l'on devra associer aux sous modules installés.
+
+Pour cela , il faut créer les types de sites via l'interface administrateur (voir les deux imags ci dessous) . 
+
+<details><summary> Images représentant l'interface administrateur au niveau du menu "Types de site"</summary>
+
+![Menu dans interface admin pour les types de site](docs/../images/type_site_module_config_admin_panel.png)
+
+
+![Config dans interface admin pour les types de site](docs/../images/type_site_module_config_admin_panel_config.png)
+
+</details>
+
+Ces types de site , une fois créés pourront être associés au sous module dans la configuration du module.
+
+<details open><summary> Image représentant la configuration du module avec l'association aux types de sites</summary>
+
+![Association des types de site au sous module](docs/../images/type_site_module_config_front.png)
+
+</details>
+
+
+
+
+
 ## Les exports
 
 * `exports`
@@ -254,17 +279,24 @@ nommée `specific` dans les fichiers `site.json`, `visit.json` ou
 }
 ```
 
-* **utilisateur** : choix de plusieurs noms d'utilisateurs dans une
-    liste
+* **utilisateur** : Il est possible de choisir des observateurs de deux manières différentes. Soit les observateurs sont issus d'une liste d'observateurs (voir `observers` ci dessous) soit on choisit de renseigner textuellement une liste d'observateurs (avec le champ `observers_txt` )
 ```json
 "observers": {
     "attribut_label": "Observateurs",
     "type_widget": "observers",
     "type_util": "user",
     "code_list": "__MODULE.ID_LIST_OBSERVER",
+    "hidden": false,
+    "required": true
+},
+"observers_txt": {
+      "hidden": true,
+      "required": false
 },
 ```
 
+Par défaut c'est la liste d'observateurs lié au sous module qui est choisi. Si l'on veut plutôt renseigner des observateurs textuellement il suffit d'inverser les champs `hidden` et `required` entre `observers` et `observers_txt`.
+
 Il est important d'ajouter `"type_util": "user"`.
 
 * **nomenclature** : un choix obligatoire parmi une liste définie par