From de615356752e7c42b6a4f6f45a08714a15805907 Mon Sep 17 00:00:00 2001
From: Jean-Marie PLACE <jean-marie.place@univ-lille1.fr>
Date: Thu, 25 Aug 2022 18:39:17 +0200
Subject: [PATCH] ajout doc (permission, correctifs tableaux,
 formsemestre-programme, ...)

---
 docs/ScoDoc9API.md                            | 154 +++++++++---------
 .../sample_formsemestre-programme.json.md     |   1 +
 2 files changed, 82 insertions(+), 73 deletions(-)

diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md
index e55590ff..ae41f004 100644
--- a/docs/ScoDoc9API.md
+++ b/docs/ScoDoc9API.md
@@ -27,7 +27,11 @@ L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction
 
 ## Configuration de ScoDoc pour utiliser l'API
 
-Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.
+Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. 
+
+Les droits à accorder dépendent des fonctionnalités nécessaires. la permission `ScoView` est généralement suffisante car elle permet toutes les consultations.
+Cependant si, par l'API, on veut effectuer des opérations de modification ou encore consulter les comptes utilisateurs, d'autres droits (`ScoChangeGroups`, `ScoUsersView`, `ScoSuperAdmin`, ...) peuvent être requis.
+La consultation du [tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) ou la ligne `permission`de chaque entrée vous donnera la permission requise pour chaque opération.
 
 En général, il est recommandé de créer un rôle, de lui attribuer les permissions
 que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.
@@ -204,77 +208,75 @@ Ce tableau est trié selon le type des informations renvoyées:
 * suivi de `:` puis d'un nom en majuscule indique une requête (POST) qui modifie
   les données de ScoDoc.
 
-| Retour                  | Remarque                                | Méthode | Navigation                                                                |
-|:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------|
-| departement**`*`**      | tous les depts                          | GET     | [departements](#departements)                                             |
-| departement**`#`**      | tous les ids des depts                  | GET     | [departements-ids](#departements-ids)                                     |
-| departement             | recherche par id                        | GET     | [departement](#departement)                                               |
-| departement             | recherche par acronyme                  | GET     | [departement](#departement)                                               |
-| departement:CREATE      | création d'un département               | POST    | [departement-create](#departement-create)                                 |
-| departement:EDIT        | modification d'un département           | POST    | [departement-edit](#departement-edit)                                     |
-| departementDELETE       | suppression d'un département            | POST    | [departement-delete](#departement-delete)                                 |
-| formation**`*`**        | toutes les formations accessibles       | GET     | [formations](#formations)                                                 |
-| formation**`#`**        | ids des formations accessibles          | GET     | [formations-ids](#formations-ids)                                         |
-| formation               | une formation                           | GET     | [formation](#formation)                                                   |
-| export                  |                                         | GET     | [formation-export](#formation-export)                                     |
-| export**`+`**           |                                         | GET     | [formation-export_with_ids](#formation-export_with_ids)                   |
-| referentiel_competences |                                         | GET     | [formation-referenciel_competences](#formation-referenciel_competences)   |
-| formsemestre**`#`**     |                                         | GET     | [departement-formsemestres_ids](#departement-formsemestres_ids)           |
-| formsemestre**`*`**     |                                         | GET     | [departement-formsemestres_courants](#departement-formsemestres_courants) |
-| formsemestre**`*`**     |                                         | GET     | [formsemestre-query](#formsemestre-query)                                 |
-| formsemestre**`*`**     |                                         | GET     | [etudiant-formsemestres](#etudiant-formsemestres)                         |
-| formsemestre            |                                         | GET     | [formsemestre](#formsemestre)                                             |
-| moduleimpl              |                                         | GET     | [moduleimpl](#moduleimpl)                                                 |
-| partition**`*`**        |                                         | GET     | [formsemestre-partitions](#formsemestre-partitions)                       |
-| partition               |                                         | GET     | [partition](#partition)                                                   |
-| partition:CREATE        |                                         | POST    | [formsemestre-partition-create](#formsemestre-partition-create)           |
-| partition:EDIT          |                                         | POST    | [partition-edit](#partition-edit)                                         |
-| partition:ACTION        |                                         | POST    | [formsemestre-partitions-order](#formsemestre-partitions-order)           |
-| partition:DELETE        |                                         | POST    | [partition-delete](#partition-delete)                                     |
-| partition:ACTION        |                                         | POST    | [partition-remove_etudiant](#partition-remove_etudiant)                   |
-| group:CREATE            |                                         | POST    | [partition-group-create](#partition-group-create)                         |
-| group:EDIT              |                                         | POST    | [group-edit](#group-edit)                                                 |
-| group:ACTION            |                                         | POST    | [partition-groups-order](#partition-groups-order)                         |
-| group:DELETE            |                                         | POST    | [group-delete](#group-delete)                                             |
-| group*                  |                                         | POST    | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups)             |
-| group:ACTION            |                                         | GET     | [group-set_etudiant](#group-set_etudiant)                                 |
-| group:ACTION            |                                         | POST    | [group-remove_etudiant](#group-remove_etudiant)                           |
-| etudiant**`*`**         | recherche par etudid, nip ou i          | GET     | [etudiants-clé](#etudiants-clé)                                           |
-| etudiant**`*`**         | les étudiants actuels                   | GET     | [etudiants-courant](#etudiants-courant)                                   |
-| etudiant**`*`**         |                                         | GET     | [departement-etudiants](#departement-etudiants)                           |
-| etudiant**`*`**         |                                         | GET     | [formsemestre-etudiants](#formsemestre-etudiants)                         |
-| etudiant**`*`**         |                                         | GET     | [formsemestre-etudiants-query](#formsemestre-etudiants-query)             |
-| etudiant**`*`**         |                                         | GET     | [group-etudiants](#group-etudiants)                                       |
+| Retour                  | Remarque                                | Méthode | Navigation                                                                | Permission          |
+|:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------|---------------------|
+| departement**`*`**      | tous les depts                          | GET     | [departements](#departements)                                             |                     | 
+| departement**`#`**      | tous les ids des depts                  | GET     | [departements-ids](#departements-ids)                                     | ScoView             |
+| departement             | recherche par id                        | GET     | [departement](#departement)                                               | ScoView             |
+| departement             | recherche par acronyme                  | GET     | [departement](#departement)                                               | ScoView             |
+| departement:CREATE      | création d'un département               | POST    | [departement-create](#departement-create)                                 | ScoSuperAdmin       |
+| departement:EDIT        | modification d'un département           | POST    | [departement-edit](#departement-edit)                                     | ScoSuperAdmin       |
+| departementDELETE       | suppression d'un département            | POST    | [departement-delete](#departement-delete)                                 | ScoSuperAdmin       |
+| formation**`*`**        | toutes les formations accessibles       | GET     | [formations](#formations)                                                 | ScoView             |
+| formation**`#`**        | ids des formations accessibles          | GET     | [formations-ids](#formations-ids)                                         | ScoView             |
+| formation               | une formation                           | GET     | [formation](#formation)                                                   | ScoView             |
+| export                  |                                         | GET     | [formation-export](#formation-export)                                     | ScoView             |
+| export**`+`**           |                                         | GET     | [formation-export_with_ids](#formation-export_with_ids)                   | ScoView             |
+| referentiel_competences |                                         | GET     | [formation-referenciel_competences](#formation-referenciel_competences)   | ScoView             |
+| formsemestre**`#`**     |                                         | GET     | [departement-formsemestres_ids](#departement-formsemestres_ids)           | ScoView             |
+| formsemestre**`*`**     |                                         | GET     | [departement-formsemestres_courants](#departement-formsemestres_courants) | ScoView             |
+| formsemestre**`*`**     |                                         | GET     | [formsemestre-query](#formsemestre-query)                                 | ScoView             |
+| formsemestre**`*`**     |                                         | GET     | [etudiant-formsemestres](#etudiant-formsemestres)                         | ScoView             |
+| formsemestre            |                                         | GET     | [formsemestre](#formsemestre)                                             | ScoView             |
+| moduleimpl              |                                         | GET     | [moduleimpl](#moduleimpl)                                                 | ScoView             |
+| partition**`*`**        |                                         | GET     | [formsemestre-partitions](#formsemestre-partitions)                       | ScoView             |
+| partition               |                                         | GET     | [partition](#partition)                                                   | ScoView             |
+| partition:CREATE        |                                         | POST    | [formsemestre-partition-create](#formsemestre-partition-create)           | ScoEtudChangeGroups |
+| partition:EDIT          |                                         | POST    | [partition-edit](#partition-edit)                                         | ScoEtudChangeGroups |
+| partition:ACTION        |                                         | POST    | [formsemestre-partitions-order](#formsemestre-partitions-order)           | ScoEtudChangeGroups |
+| partition:DELETE        |                                         | POST    | [partition-delete](#partition-delete)                                     | ScoEtudChangeGroups |
+| partition:ACTION        |                                         | POST    | [partition-remove_etudiant](#partition-remove_etudiant)                   | ScoEtudChangeGroups |
+| group:CREATE            |                                         | POST    | [partition-group-create](#partition-group-create)                         | ScoEtudChangeGroups |
+| group:EDIT              |                                         | POST    | [group-edit](#group-edit)                                                 | ScoEtudChangeGroups |
+| group:ACTION            |                                         | POST    | [partition-groups-order](#partition-groups-order)                         | ScoEtudChangeGroups |
+| group:DELETE            |                                         | POST    | [group-delete](#group-delete)                                             | ScoEtudChangeGroups |
+| group*                  |                                         | GET     | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups)             | ScoView             |
+| group:ACTION            |                                         | POST    | [group-set_etudiant](#group-set_etudiant)                                 | ScoEtudChangeGroups |
+| group:ACTION            |                                         | POST    | [group-remove_etudiant](#group-remove_etudiant)                           | ScoEtudChangeGroups |
+| etudiant**`*`**         | recherche par etudid, nip ou ine        | GET     | [etudiants-clef](#etudiants-clef)                                         | ScoView             |
+| etudiant**`*`**         | les étudiants actuels                   | GET     | [etudiants-courant](#etudiants-courant)                                   | ScoView             |
+| etudiant**`*`**         |                                         | GET     | [departement-etudiants](#departement-etudiants)                           | ScoView             |
+| etudiant**`*`**         |                                         | GET     | [formsemestre-etudiants](#formsemestre-etudiants)                         | ScoView             |
+| etudiant**`*`**         |                                         | GET     | [formsemestre-etudiants-query](#formsemestre-etudiants-query)             | ScoView             |
+| etudiant**`*`**         |                                         | GET     | [group-etudiants](#group-etudiants)                                       | ScoView             |
 | etudiant**`*`**         |                                         | GET     | [group-etudiants-query](#group-etudiants-query)                           |
-| etudiant                |                                         | GET     | [etudiant](#etudiant)                                                     |
-| bulletin**`*`**         |                                         | GET     | [formsemestre-bulletin](#formsemestre-bulletin)                           |
-| bulletin                |                                         | GET     | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin)         |
-| programme               |                                         | GET     | [formsemestre-programme](#formsemestre-programme)                         |
-|                         |                                         | GET     | [formsemestre-etat_evals](#formsemestre-etat_evals)                       |
-|                         |                                         | GET     | [formsemestre-resultats](#formsemestre-resultats)                         |
-| jury                    |                                         | GET     | [formsemestre-decisions_jury](#formsemestre-decisions_jury)               |
-| evaluation*             |                                         | GET     | [evaluations](#evaluations)                                               |
-| note*                   |                                         | GET     | [evaluation-notes](#evaluation-notes)                                     |
-| logo**`*`**             |                                         | GET     | [logos](#logos)                                                           |
-| logo**`*`**             |                                         | GET     | [departement-logos](#departement-logos)                                   |
-| logo                    |                                         | GET     | [logo](#logo)                                                             |
-| logo                    |                                         | GET     | [departement-logo](#departement-logo)                                     |
-| user                    |                                         | GET     | [user](#user)                                                             |
-| user**`*`**             |                                         | GET     | [users-query](#users-query)                                               |
-| user:CREATE             |                                         | POST    | [user-create](#user-create)                                               |
-| user:EDIT               |                                         | POST    | [user-edit](#user-edit)                                                   |
-| user:PASSWORD           | change le mot de passe d'un utilisateur | POST    | [user-password](#user-password)                                           |
-| user:DELETE             |                                         | POST    | [user-delete](#user-delete)                                               |
-| user:ACTION             |                                         | POST    | [user-role-add](#user-role-add)                                           |
-| user:ACTION             |                                         | POST    | [user-role-remove](#user-role-remove)                                     |
-| permission**`*`**       |                                         | GET     | [permissions](#permissions)                                               |
-| role**`*`**             |                                         | GET     | [roles](#roles)                                                           |
-| role**`*`**             |                                         | GET     | [role](#role)                                                             |
-| role:ACTION             |                                         | POST    | [role-add_permission](#role-add_permission)                               |
-| role:ACTION             |                                         | POST    | [role-remove_permission](#role-remove_permission)                         |
-| role:CREATE             |                                         | POST    | [role-create](#role-create)                                               |
-| role:EDIT               |                                         | POST    | [role-edit](#role-edit)                                                   |
-| role:DELETE             |                                         | POST    | [role-delete](#role-delete)                                               |
+| etudiant                |                                         | GET     | [etudiant](#etudiant)                                                     | ScoView             |
+| bulletin**`*`**         |                                         | GET     | [formsemestre-bulletin](#formsemestre-bulletin)                           | ScoView             |
+| bulletin                |                                         | GET     | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin)         | ScoView             |
+| programme               |                                         | GET     | [formsemestre-programme](#formsemestre-programme)                         | ScoView             |
+|                         |                                         | GET     | [formsemestre-etat_evals](#formsemestre-etat_evals)                       | ScoView             |
+|                         |                                         | GET     | [formsemestre-resultats](#formsemestre-resultats)                         | ScoView             |
+| jury                    |                                         | GET     | [formsemestre-decisions_jury](#formsemestre-decisions_jury)               | ScoView             |
+| note*                   |                                         | GET     | [evaluation-notes](#evaluation-notes)                                     | ScoView             |
+| logo**`*`**             |                                         | GET     | [logos](#logos)                                                           | ScoSuperAdmin       |
+| logo**`*`**             |                                         | GET     | [departement-logos](#departement-logos)                                   | ScoSuperAdmin       |
+| logo                    |                                         | GET     | [logo](#logo)                                                             | ScoSuperAdmin       |
+| logo                    |                                         | GET     | [departement-logo](#departement-logo)                                     | ScoSuperAdmin       |
+| user                    |                                         | GET     | [user](#user)                                                             | ScoUsView           |
+| user**`*`**             |                                         | GET     | [users-query](#users-query)                                               | ScoUsView           |
+| user:CREATE             |                                         | POST    | [user-create](#user-create)                                               | ScoUserAdmin        |
+| user:EDIT               |                                         | POST    | [user-edit](#user-edit)                                                   | ScoUserAdmin        |
+| user:PASSWORD           | change le mot de passe d'un utilisateur | POST    | [user-password](#user-password)                                           | ScoUserAdmin        |
+| user:ACTION             |                                         | POST    | [user-role-add](#user-role-add)                                           | ScoUserAdmin        |
+| user:ACTION             |                                         | POST    | [user-role-remove](#user-role-remove)                                     | ScoUserAdmin        |
+| permission**`*`**       |                                         | GET     | [permissions](#permissions)                                               | ScoUsView           |
+| role**`*`**             |                                         | GET     | [roles](#roles)                                                           | ScoUsView           |
+| role**`*`**             |                                         | GET     | [role](#role)                                                             | ScoUsView           |
+| role:ACTION             |                                         | POST    | [role-add_permission](#role-add_permission)                               | ScoUserAdmin        |
+| role:ACTION             |                                         | POST    | [role-remove_permission](#role-remove_permission)                         | ScoUserAdmin        |
+| role:CREATE             |                                         | POST    | [role-create](#role-create)                                               | ScoUserAdmin        |
+| role:EDIT               |                                         | POST    | [role-edit](#role-edit)                                                   | ScoUserAdmin        |
+| role:DELETE             |                                         | POST    | [role-delete](#role-delete)                                               | ScoUserAdmin        |
 
 #### Note sur les exemples d'utilisation 
 Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API. Il n'est par exemple pas garanti que les clés des objets json sont triées:
@@ -483,6 +485,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
   l'id passé en paramètres.
   Les codes INE et NIP sont uniques au sein d'un département.
   Si plusieurs objets étudiant ont le même code, on renvoie le plus récemment inscrit.
+* Pour obtenir tous les étudiants répondant au critère, utiliser [etudiant-clefs](#etudiants-clef)
 * **Exemple de résultat:**  [etudiant.json](samples/sample_etudiant.json.md)
 
 ### **API Formation**
@@ -841,7 +844,7 @@ d'un nombre quelconque de groupes d'étudiants.
 #### **`partition-remove_etudiant`**
 * **Méthode: POST**
 * **Permission: `ScoEtudsChangeGroups`**
-* **Permission: `ScoEtudChangeGroups`***
+* **Permission: `ScoEtudChangeGroups`**
 * **Paramètres:** `partition_id`
 * **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>`
 * **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/remove_etudiant/12107`
@@ -1054,7 +1057,12 @@ mais pas JSON compliant à cause des _NaN_.
 * **Paramètres:** `dept`, `formsemestre_id`
 * **Routes:** `/formsemestre/<int:formsemestre_id>/programme`
 * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme`
-* **Résultat:** Retourne la liste des UEs, modules, ressources et SAE d'un semestre.
+* **Résultat:** Retourne la struture d'un formsemestre sous 5 entrées d'un dictionnaire:
+    * **`ues`**: liste des UEs, 
+    * **`ressources`**: liste des ressources (BUT),
+    * **`saes`**: liste des saes (BUT),
+    * **`modules`**:  liste des modules classiques (DUT ou sport/culture)
+    * **`malus`**: listes des modules de type bonus/malus.
 * **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md)
 
 #### **formsemestre-resultats**
diff --git a/docs/samples/sample_formsemestre-programme.json.md b/docs/samples/sample_formsemestre-programme.json.md
index 9805395e..dbb3004d 100644
--- a/docs/samples/sample_formsemestre-programme.json.md
+++ b/docs/samples/sample_formsemestre-programme.json.md
@@ -3,6 +3,7 @@
 #### GET /formsemestre/1/programme
 ```json
 {
+    "malus": [],
     "modules": [],
     "ressources": [
         {