mise à jour de la doc api au 24/05/2022

docs/ModelisationParcoursBUT.md

@@ -43,9 +43,9 @@ compétences*.
 Le programme de formation est constitué des classes suivantes (en BUT et dans
 tous les types de formation. La notion de "matière" n'est pas utilisée en BUT).
 
- - Formation (ex: "BUT R&T")
+ - `Formation` (ex: "BUT R&T")
-    - UniteEns (UE, ex: "Administrer les réseaux")
+    - `UniteEns` (UE, ex: "Administrer les réseaux")
-        - Modules (ressources, SAÉs) *<-> ApcAppCritique*, *<-> ApcAnneeParcours*
+        - `Modules` (ressources, SAÉs) *<-> `ApcAppCritique`*, *<-> `ApcAnneeParcours`*
 
 On voit que les modules ont toujours une UE de rattachement. Cependant, en BUT,
 un module peut intervenir dans le calcul des notes de plusieurs UE, via une
@@ -56,60 +56,76 @@ pouvoir vérifier que les parcours couvrent les AC, et à faciliter les
 inscriptions des étudiants aux modules (par ex. page présentant les modules
 auxquels inscrire un groupe).
 
+#### Cas des modules présents dans plusieurs parcours 
+
+Si un module est utilisé dans plusieurs parcours de la même formation BUT, cela
+ne pose aucun problème, _sauf_ si ce module doit avoir des coefficients (vers
+les UEs) différents selon le parcours dans lequel il intervient. Dans ce cas,
+*il sera conseillé de créer plusieurs versions du module*, que l'on associera
+aux divers parcours.
+
 ### Référentiel de compétences
 Le référentiel de compétences est structuré par les classes suivantes:
 
- - ApcReferentielCompetences
+ - `ApcReferentielCompetences`
-    - ApcCompetence
+    - `ApcCompetence`
-        - ApcSituationPro
+        - `ApcSituationPro`
-        - ApcComposanteEssentielle
+        - `ApcComposanteEssentielle`
-        - ApcNiveau (année (BUT1, BUT2, ...), ordre (1,2) ou (1,2,3)) *<-> UE*
+        - `ApcNiveau` (année (BUT1, BUT2, ...), ordre (1,2) ou (1,2,3)) *<-> UE*
-            - ApcAppCritique *<-> Module*
+            - `ApcAppCritique` *<-> `Module`*
-    - ApcParcours
+    - `ApcParcours`
-        - ApcAnneeParcours (ordre=1,2,3) *<-> Module*
+        - `ApcAnneeParcours` (ordre=1,2,3) *<-> Module*
-    - *ApcCompetence* <- ApcParcoursNiveauCompetence (niveau 1, 2, 3) -> *ApcAnneeParcours*
+    - *`ApcCompetence`* <- `ApcParcoursNiveauCompetence` (niveau 1, 2, 3) -> *`ApcAnneeParcours`*
 
-Notons le lien entre les apprentissages critiques (ApcAppCritique) et les
+Notons:
+ 
+ - Le lien entre UE et Niveau de compétence (`ApcNiveau`). 
+ 
+ - Le lien à entre Compétence et Année de Parcours à travers la table
+   (*many-to-many*) `ApcParcoursNiveauCompetence` qui indique le niveau ce
+   compétence concerné.
+
+ - Le lien entre les apprentissages critiques (`ApcAppCritique`) et les
 modules, qui permet d'établir les critères d'évaluation de chaque module.
 
 ### FormSemestres
-La formation est mise en œuvre dans des FormSemestre (date début, fin,
+La formation est mise en œuvre dans des `FormSemestre` (date début, fin,
-enseignants responsables, ...) constitués de ModuleImpl (module avec enseignant,
+enseignants responsables, ...) constitués de `ModuleImpl` (module avec enseignant,
 évaluations, ...).
 
- - FormSemestre
+ - `FormSemestre`
-    - ModuleImpl
+    - `ModuleImpl`
-        - Evaluation
+        - `Evaluation`
 
 ### Inscriptions des étudiants
 Les étudiants sont inscrits:
 
- - dans un FormSemestre (FormSemestreInscription, avec état (I, D, DEF) et étape
+ - dans un `FormSemestre` (`FormSemestreInscription`, avec état (`I`, `D`,
-   Apogée)
+   `DEF`) et étape Apogée)
- - dans un ModuleImpl (ModuleImplInscription)
+ - dans un ModuleImpl (`ModuleImplInscription`)
- - et, pour le BUT, dans un ApcParcours (TODO)
+ - et, pour le BUT, dans un `ApcParcours` (**TODO**)
 
 ### Associations (nouvelles pour le BUT):
 
 Pour la gestion des parcours BUT, il faut introduire les associations suivantes,
 qui n'existent pas dans ScoDoc 9.2:
 
- - UE <-> ApcNiveau : choix sur la page `ue_edit`
+ - UE <-> `ApcNiveau` : choix sur la page `ue_edit`
- - Module <-> ensemble de ApcParcours
+ - `Module` <-> ensemble de `ApcParcours`
- - Module ||--o{ ApcAppCritique : choix sur la page `module_edit`
+ - `Module` ||--o{ `ApcAppCritique` : choix sur la page `module_edit`
- - FormSemestre ||--o{ ApcParcours : choix sur la page
+ - `FormSemestre` ||--o{ `ApcParcours` : choix sur la page
    `formsemestre_editwithmodules`
- - Identite }o--o{ ApcParcours : inscription au parcours, page à créer. 
+ - `Identite` }o--o{ `ApcParcours` : inscription au parcours, page à créer. 
 
 ### Cas d'usage
 
 #### Niveau de compétence d'un formsemestre
 
-Le formsemestre est lié à un ensemble d'ApcParcours.
+Le formsemestre est lié à un ensemble d'`ApcParcours`.
 
 #### Inscription d'un étudiant aux ModuleImpls
 L'inscription reste libre (chaque individu peut être inscrit à un sous-ensemble
-quelconque des ModuleImpl du FormSemestre), mais il sera commode de pouvoir:
+quelconque des `ModuleImpl` du `FormSemestre`), mais il sera commode de pouvoir:
 
  - créer des groupes de parcours
  - inscrire les étudiants d'un groupe à tous les modules du parcours.
@@ -184,5 +200,72 @@ Il faut donc:
     l'étudiant, et vérifier que les UE de S1 et S2 sont validées.
 
 
+#### Cas particulier: formations dont le nombre d'ECTS varie selon le parcours
 
+Ce cas a été soulevé à propos du BUT MMI, qui préconiserait par exemple, au S4,
+une compétence développer avec 10 ECTS dans le parcours "web", et 5 ECTS dans le
+parcours "crea".
 
+Si on veut pouvoir utiliser la même formation, et éventuellement mélanger les
+étudiants des différents parcours dans le même `FormSemestre` (ce qui
+simplifierait la gestion des modules communs), il faut modifier la modélisation:
+Les ECTS sont actuellement des attributs de UEs.
+Il faudrait avoir une association `UniteEns` }o..o{ `ApcParcours` qui contienne
+les valeurs des ECTS.
+
+### Diagramme de classes
+
+Juste pour rire, car ce diagramme est quasiment inexploitable.
+
+``` mermaid
+erDiagram
+  FormSemestre ||--|{ ModuleImpl : contient
+  ModuleImpl ||--o{ Evaluation : contient
+  Module ||--o{ ModuleImpl : ""
+  Formation ||--o{ UE : ""
+  UE ||--|{ Module : ""
+
+  Formation {
+    str titre
+    str acronym
+    str code
+  }
+
+  Etudiant {
+    str nom
+  }
+
+  FormSemestre {
+    int dept_id
+    str titre
+    date date_debut
+    date date_fin
+  }
+
+  Etudiant }|..|{ ModuleImpl : ModuleImplInscription
+  Etudiant }|..|{ FormSemestre : FormSemestreInscription
+  Etudiant }|..|{ ApcParcours : "optionnel"
+
+  Formation ||--o{ FormSemestre : ""
+
+  ApcReferentielCompetences ||--o{ ApcCompetence : ""
+  ApcCompetence ||--o{ ApcNiveau : ""
+  ApcCompetence ||--o{ ApcSituationPro : ""
+  ApcCompetence ||--o{ ApcComposanteEssentielle : ""
+  ApcNiveau }o..|| UE : "optionnel"
+  ApcNiveau ||--o{ ApcAppCritique : ""
+  ApcAppCritique }o..o{ Module : "optionnel"
+
+  ApcReferentielCompetences ||--o{ ApcParcours : ""
+  ApcParcours ||--o{ ApcAnneeParcours : ""
+
+  ApcAnneeParcours {
+    int ordre
+  }
+
+  ApcCompetence }o--o{ ApcAnneeParcours : "ApcParcoursNiveauCompetence (1,2,3)"
+
+  Module }o--o{ ApcParcours : "parcours_modules"
+  FormSemestre }o--o{ ApcParcours : "parcours_formsemestre"
+  UE }o..o{ ApcParcours : "pour les ECTS"
+```

docs/ProblemesMail.md

@@ -1,19 +1,25 @@
 
 #  Problèmes d'envoi de courriers électroniques 
-ScoDoc envoie des mails en plusieurs occasions (bulletins de notes, importation d'utilisateurs, alertes sur absences, exceptions dans le code).
+ScoDoc envoie des mails en plusieurs occasions (bulletins de notes, importation
+d'utilisateurs, alertes sur absences, exceptions dans le code). 
 
-Cette page explique ce qu'il faut vérifier si l'envoi des messages ne fonctionne pas.
+Cette page explique ce qu'il faut vérifier si l'envoi des messages ne fonctionne
+pas. 
+
+## Configuration du serveur
+ScoDoc suppose que la machine serveur sur laquelle il s'exécute est dotée d'un
+serveur de mail capable d'envoyer des messages (soit directement, soit via un
+relais). L'installeur propose d'installer le logiciel serveur Postfix. 
 
 
-ScoDoc suppose que la machine serveur sur laquelle il s'exécute est dotée d'un serveur de mail capable d'envoyer des messages (soit directement, soit via un relais). L'installeur propose d'installer le logiciel serveur Postfix.
+ 1. Vérifier que votre serveur de messagerie est bien configuré: dans un
-
+    terminal, envoyez un message 
-
- 1. Vérifier que votre serveur de messagerie est bien configuré: dans un terminal, envoyez un message
 ```
 mail mon_adresse@universite.fr
 ... entrer votre texte, terminez par ctrl-d ...
 ```
-Si vous ne recevez pas le message que vous vous envoyiez, revoir la configuration de votre serveur, par exemple avec la commande 
+Si vous ne recevez pas le message que vous vous envoyiez, revoir la
+configuration de votre serveur, par exemple avec la commande 
 ```
 dpkg-reconfigure postfix
 ```
@@ -29,14 +35,19 @@ Connected to localhost.
 Escape character is '^]'.
 220 nom_du_serveur ESMTP Postfix (Debian/GNU)
 ```
-(quitter avec ctrl-] puis quit)
+(quitter avec ctrl-] puis `quit`)
 
- 3. Si cela fonctionne, passer au test de ScoDoc: créer un étudiant bidon, lui attribuer une adresse mail que vous pouvez lire, l'inscrire à un semestre, et lui envoyer son bulletin par mail. (sur la page web de son bulletin, petit menu "Autres opérations").
+## Tests avec ScoDoc
 
-A ce moment, regarder le log
+Une fois que le mail, fonctionne, passer au test de ScoDoc: créer un étudiant
+bidon, lui attribuer une adresse mail que vous pouvez lire, l'inscrire à un
+semestre, et lui envoyer son bulletin par mail. (sur la page web de son
+bulletin, petit menu "Autres opérations").
+
+À ce moment, regarder le log
 `/opt/scodoc/instance/log/notes.log`
 
-on devrait voir quelque chose ressemblant à:
+On devrait voir quelque chose ressemblant à:
 ```
 [Sun Sep 07 11:37:40 2008] mail bulletin a emmanuel.viennet@gmail.com
 [Sun Sep 07 11:37:40 2008] sendEmail: ok
@@ -51,6 +62,17 @@ delays=0.03/0/0.41/1, dsn=2.0.0, status=sent (250 2.0.0 OK 1220942550 y2si226470
 
 Cela devrait permettre de savoir:
 
- 1. si ScoDoc tente d'envoyer un mail (notes.log)
+ 1. si ScoDoc tente d'envoyer un mail (`notes.log`);
+ 
  2. si le serveur SMTP arrive à traiter ce mail.
 
+## Redirection des tous les mails de ScoDoc
+
+Afin de vérifier les envois de mail, il peut être pratique de détourner tous les
+envois vers une adresse (cela permet par exemple de tester les envois de
+notification ou de bulletins sans déranger les étudiants ou les collègues).
+
+Pour cela, aller sur la page *Paramétrage*, tout en bas, et indiquer une
+*Adresse de test*. Ne pas oublier de l'enlever une fois les essais effectués !
+
+

docs/ScoDoc9API.md

@@ -316,7 +316,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le
   * **`etudiant`**
     * **Méthode:** GET
     * **Paramètres:**  `etudid`, `nip`, `ine`
-    * **Routes:** `/etudiant/etudid/<int:etudid>` ou `/etudiant/nip/<int:nip>` ou `/etudiant/ine/<int:ine>`
+    * **Routes:** `/etudiant/etudid/<int:etudid>` ou `/etudiant/nip/<string:nip>` ou `/etudiant/ine/<string:ine>`
     * **Exemple d'utilisation:** `/api/etudiant/nip/1`
     * **Résultat:** Retourne les informations de l'étudiant correspondant à l'id passé en paramètres. (json)
     * **Exemple de résultat:**
@@ -355,7 +355,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le
  * **`etudiant_formsemestres`**
     * **Méthode:** GET
     * **Paramètres:** `etudid`, `nip`, `ine`
-    * **Routes:** : `/etudiant/etudid/<int:etudid>/formsemestres` ou `/etudiant/nip/<int:nip>/formsemestres` ou `/etudiant/ine/<int:ine>/formsemestres`
+    * **Routes:** : `/etudiant/etudid/<int:etudid>/formsemestres` ou `/etudiant/nip/<string:nip>/formsemestres` ou `/etudiant/ine/<string:ine>/formsemestres`
     * **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres`
     * **Résultat:** Retourne la liste des semestres qu'un étudiant a suivis, triés par ordre chronologique. (json)
     * **Exemple de résultat:**
@@ -402,10 +402,21 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le
     * **Paramètres:**  `formsemestre_id`, `etudid`, `nip`, `ine`
     * **Routes:**
       `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin`
-      ou `/etudiant/nip/<int:nip>/formsemestre/<int:formsemestre_id>/bulletin`
+      ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin`
-      ou `/etudiant/ine/<int:ine>/formsemestre/<int:formsemestre_id>/bulletin`
+      ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin`
+      ou `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin/pdf`
+      ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin/pdf`
+      ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin/pdf`
+      ou `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin/short`
+      ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin/short`
+      ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin/short`
+      ou `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin/short/pdf`
+      ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin/short/pdf`
+      ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin/short/pdf`
     * **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin`
     * **Résultat:** Bulletin de l'étudiant dans le formsemestre. 
+                    Deux versions disponibles `long` et `short` (par défaut long ajoutez **/short** pour la version plus courte). 
+                    Possible de récupérer le pdf en version pdf avec **/pdf** XXX ATTENTION PAS ENCORE DISPONIBLE XXX
     * **Exemple de résultat:**
         ```
         {
@@ -582,7 +593,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le
   * **`etudiant_groups`**
     * **Méthode:** GET
     * **Paramètres:**  `formsemestre_id`, `etudid`, `nip`, `ine`
-    * **Routes:** `/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/nip/<int:nip>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/ine/<int:ine>/semestre/<int:formsemestre_id>/groups`
+    * **Routes:** `/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/nip/<string:nip>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/ine/<string:ine>/semestre/<int:formsemestre_id>/groups`
     * **Exemple d'utilisation:** `/etudiant/nip/1/semestre/1/groups`
     * **Résultat:** Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json)
     * **Exemple de résultat:**
@@ -1341,9 +1352,9 @@ d'un nombre quelconque de groupes d'étudiants.
 
  * **`absences`**
      * **Méthode:** GET
-     * **Paramètres:**  `etudid`, `nip`, `ine`
+     * **Paramètres:**  `etudid`
-     * **Routes:** `/absences/etudid/<int:etudid>` ou `/absences/nip/<int:nip>` ou `/absences/ine/<int:ine>`
+     * **Routes:** `/absences/etudid/<int:etudid>`
-     * **Exemple d'utilisation:** `/ScoDoc/api/absences/ine/1`
+     * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/1`
      * **Résultat:** Retourne la liste des absences d'un étudiant donné
      * **Exemple de résultat:**
         ```
@@ -1371,9 +1382,9 @@ d'un nombre quelconque de groupes d'étudiants.
        
  * **`absences_just`**
      * **Méthode:** GET
-     * **Paramètres:**  `etudid`, `nip`, `ine`
+     * **Paramètres:**  `etudid`
-     * **Routes:** `/absences/etudid/<int:etudid>/just` ou `/absences/nip/<int:nip>/just` ou `/absences/ine/<int:ine>/just`
+     * **Routes:** `/absences/etudid/<int:etudid>/just`
-     * **Exemple d'utilisation:** `/ScoDoc/api/absences/ine/1/just`
+     * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/1/just`
      * **Résultat:** Retourne la liste des absences justifiées d'un étudiant donné
      * **Exemple de résultat:**
         ```
@@ -1400,7 +1411,7 @@ d'un nombre quelconque de groupes d'étudiants.
         ```
 
     
- * **`abs_groupe_etat`**
+ * **`abs_groupe_etat`** **NON IMPLEMENTE**
     * **Méthode:** GET
     * **Paramètres:** `group_id`, `date_debut`, `date_fin` (dates au format ISO)
     * **Routes:** `/absences/abs_group_etat/<int:group_id>` ou `/absences/abs_group_etat/group_id/<in:group_id>/date_debut/<string:date_debut>/date_fin/<string:date_fin>`
@@ -1440,6 +1451,27 @@ d'un nombre quelconque de groupes d'étudiants.
         ]
         ```
       
+ * **`reset_etud_abs`** **NON IMPLEMENTE**
+    * **Méthode:** POST
+    * **Paramètres:** `etudid`, `list_abs`
+    * **Routes:** `/absences/etudid/<int:etudid>/list_abs/<str:list_abs>/reset_etud_abs` ou `/absences/etudid/<int:etudid>/list_abs/<str:list_abs>/reset_etud_abs/only_not_just` ou `/absences/etudid/<int:etudid>/list_abs/<str:list_abs>/reset_etud_abs/only_just`
+    * **Exemple {LIST_ABS} json:** 
+            ```
+              [
+                {
+                  "matin": true,
+                  "estabs": true,
+                  "estjust": true,
+                  "description": "",
+                  "begin": "2022-04-15 08:00:00",
+                  "end": "2022-04-15 11:59:59"
+                },
+                ...
+              ]
+            ```
+    * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/1/list_abs/{LIST_ABS}reset_etud_abs`
+    * **Résultat:** Set la liste des absences d'un étudiant sur tout un semestre. (les absences existant pour cet étudiant sur cette période sont effacées)
+      
 
 ### Jury