docs/Assiduites.md

@@ -1,16 +1,17 @@
+<!-- markdownlint-disable MD007 -->
 # Suivi de l'assiduité
 
 Ce module de ScoDoc remplace l'ancien module de suivi des absences de Scodoc.
 Il propose des fonctions plus étendues: absences, retards, justificatifs (et
 gestion des documents associés) avec une granularité fine, des outils de
-*reporting* et une API complète permettant d'interfacer des modules tiers.
+_reporting_ et une API complète permettant d'interfacer des modules tiers.
 
 Ce projet a été développé de 2022 à 2024, par Matthias Hartmann, apprenti de l'IUT de
 Lannion financé par l'Association ScoDoc.
 
 **Ce module est disponible à partir de ScoDoc version 9.6**.
 
-[Vidéo de présentation du module d'assiduités ](https://youtu.be/p7xips26W54)
+[Vidéo de présentation du module d'assiduités](https://youtu.be/p7xips26W54)
 
 ## Fonctionnalités
 
@@ -21,20 +22,9 @@ Le module fournit:
   heure de fin au lieu de demi-journées)
 - Gestion et sauvegarde de justificatifs (documents)
 - Une [API complète](ScoDoc9API.md#api-assiduites)
+- [**EXPERIMENTAL**] Raccordement à un emploi du temps ([documentation](EmploisDuTemps.md))
 
-## Guide d'utilisation
-
-- [Suivi de l'assiduité](#suivi-de-lassiduité)
-  - [Fonctionnalités](#fonctionnalités)
-  - [Guide d'utilisation](#guide-dutilisation)
-    - [Migration de l'ancien module](#migration-de-lancien-module)
-    - [Personnalisation du module](#personnalisation-du-module)
-    - [Saisie des Assiduités](#saisie-des-assiduités)
-      - [Saisie d'un groupe](#saisie-dun-groupe)
-      - [Saisie Journalière](#saisie-journalière)
-      - [Saisie différée](#saisie-différée)
-
-### Migration de l'ancien module
+## Migration de l'ancien module
 
 Afin de favoriser la transition de l'ancien module au nouveau, un script de
 migration a été développé: à l'installation de ScoDoc 9.6, les anciennes
@@ -43,38 +33,40 @@ données d'absences et justificatifs sont traduites pour ce module.
 Voir détails dans [la documentation d'installation](UpgradeToDeb12Sco96.md) et
 sur la [documentation des commandes de migration des absences](AssiduitesMigration.md).
 
-### Personnalisation du module
+## Personnalisation du module
 
 Le module possède deux types de configuration, une générale et une par département/semestre.
 
-**La configuration générale permet de configurer la ligne temporelle visible sur certaines pages de saisie d'assiduités.**
+### La configuration générale
+
+Elle permet de configurer les horaires de saisie d'assiduités
+
+!!! warning "Attention"
+    La configuration bloque les saisies en dehors des horaires définis.
 
 ![Configuration de l'assiduité : Général](screens/config_assiduites_gen.png)
 
 Route : `/ScoDoc/config_assiduites`
 
-- `Début de la journée` : l'heure de début de la ligne temporelle (par défaut :
+- `Début de la journée` : l'heure de début des cours (par défaut :
   8h00)
 - `L'heure de midi` : l'heure pivot qui sépare la matinée de l'après-midi (par
   défaut : 13h00)
-- `Fin de la journée` : l'heure de fin de la ligne temporelle (par défaut :
+- `Fin de la journée` : l'heure de fin des cours (par défaut :
   18h00)
-- `Granularité` : La granularité de la ligne temporelle. (par défaut : 15 min)
+- `Granularité` : La granularité de la saisie (par défaut : 15 min)
 
-**La configuration par département/semestre permet de configurer certaines actions liés à l'assiduité**
+### La configuration par département/semestre
+
+Elle permet de configurer certaines actions liés à l'assiduité
 
 ![Configuration de l'assiduité : département](screens/config_assiduites_dept.png)
 
 Route : `/ScoDoc/<Dept>/Scolarite/edit_preferences`
 
-- `Forcer la déclaration du module` : Forcer les utilisateurs de ScoDoc à
+- `Imposer la déclaration du module` : Forcer les utilisateurs de ScoDoc à
   renseigner le module à chaque saisie d'assiduités.
-- `Forcer l'appel des présents` : Force les utilisateurs à noter les
-  présences/absences/retard lors d'une saisie.
-- `Durée par défaut d'un créneau` : Détermine la durée classique d'un cours. (Ce
-  sera la période préenregistrée sur la ligne temporelle)
-- `Définir l'état par défaut` : Défini l'état par défaut qui sera appliqué aux
-  étudiants avant validation d'une saisie d'assiduité.
+- `Désactiver la saisie des présences` : Retire les boutons et les affichages liés aux présences.
 - `Jours non travaillés` : Défini les jours sur lesquels la saisie d'assiduités
   ne sera pas possible.
 - `Métrique de l'assiduité` : Défini l'unité de l'assiduité qui sera utilisé par
@@ -82,177 +74,200 @@ Route : `/ScoDoc/<Dept>/Scolarite/edit_preferences`
     - `1/2 J.` : Demi-Journée
     - `J.` : Journées
     - `H.` : Heures
+- `Seuil d'alerte des absences` : Nombre d'absences limite avant alerte (utilisation de la métrique d'assiduité)
 
-### Saisie des Assiduités
+## Gestion de l'assiduité
 
-La saisie se fait soit sur un groupe soit sur un étudiant. Dans tous les cas il
-y a deux façons de saisir l'assiduité. Une saisie `Journalière` et une saisie
-`Différée`.
+### Saisir l'assiduité d'un groupe
 
-#### Saisie d'un groupe
+#### Saisir par Jour
 
-Comme dans l'ancien système, pour saisir l'assiduité d'un groupe il faut se
-rendre sur la page un semestre du département concerné.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/signal_assiduites_group?formsemestre_id=<formsemestre_id>&group_ids=<group_id,...>&day=<yyyy-mm-dd>`
 
-![Page du semestre concerné](#)
+_Page accessible depuis le tableau de bord d'un semestre (`Saisir l'assiduité`)._
 
-Au bas de cette page vous retrouverez la liste des groupes du semestre. Si vous
-avez la permission de modifier l'assiduité, vous observerez 3 boutons
-supplémentaires sur chaque groupe vous permettant de voir ou saisir l'assiduité
-du groupe.
+_Page accessible depuis le tableau de bord d'un module (`Saisie Absences`)._
 
-#### Saisie Journalière
+![Saisir l'assiduité](screens/signal_assiduites_group.png)
 
-La première chose à faire lorsque vous êtes arrivés sur la page "Saisie
-Journalière" c'est de compléter les informations de la séance :
+##### Composition de la page
 
-![Capture des sélecteurs](#)
+- Choix du/des groupe(s) et de la date
+  ![Choix groupe et date](screens/signal_assiduites_group-groupe.png)
+    - Vous pouvez cliquer sur le calendrier pour changer plus facilement la date. Si la date n'est pas un jour travaillé la page sélectionnera automatiquement le prochain jour travaillé.
+    - Vous pouvez afficher plusieurs groupes en cliquant sur le nom du group affiché ( ici TP1(10) )
+- Timeline / choix de la plage concernée (exemple : durée d'un cours)
+  ![Timeline](screens/signal_assiduites_group-timeline.png)
+    - La zone bleu est un élément intéractif. Elle correspond à la plage concernée. Vous pouvez la déplacer en cliquant dessus puis en déplaçant la souris en gardant maintenu le clic. Vous pouvez également l'agrandir ou rétrécir en effectuant la même action mais depuis un des bords de la zone bleu. Le curseur changera pour vous indiquer que vous aller modifier la taille.
+    - Sinon vous pouvez directement changer les horaires à l'aide des sélecteurs à gauche de la timeline
+    - Vous pouvez aussi utiliser les boutons `Matin` et `Après-midi` pour placer rapidement la zone bleue.
+- Choix du module (et affichage ou non des photos des étudiants)
+  ![Module](screens/signal_assiduites_group-module.png)
+    - Vous pouvez changer de module en cliquant sur le sélecteur. Un message d'avertissement s'affichera si vous ne sélectionnez pas de module alors que la préférence `Imposer la déclaration du module` est active.
+    - Vous pouvez afficher ou non les photos des étudiants en cochant la case `Afficher les photos`
+- Lignes étudiants et saisie
+  ![Lignes étudiantes](screens/signal_assiduites_group-lignes_etud.png)
 
-- Le ou les groupes sélectionnés (dans la plupart des cas, le groupe est déjà
-  présélectionné)
-- Le module concerné (par défaut il n'est pas obligatoire de sélectionner un
-  module, cependant une configuration permet de forcer la sélection)
-- La date de la saisie. Attention, seule les dates comprises dans le semestre
-  sont valides. (Un message d'erreur vous le signalera si la date n'est pas
-  valide)
+##### Composition d'une ligne étudiante
 
-Lorsque vous êtes sûr de vous, appuyer sur le bouton `Valider`.
+![Ligne étudiante classique](screens/signal_assiduites-group-ligne-etud.png)
 
-**Attention : La validation est définitive, si vous avez fait une erreur il faudra recharger la page**
+- En premier il y a les informations de l'étudiant (nom, prenom, photo)
+- ensuite il y a symbolisation des assiduités sur la journée.
+    - le petit carré affiche la dernière assiduité du jour précédent
+    - la ligne affiche l'assiduité de la journée. La taille des blocs est proportionnelle à la taille de l'assiduité saisie.
+    - La zone bleue correspond à la plage de saisie (Timeline)
+- Enfin il y a les boutons de saisie. Dans l'ordre
+    - Présence
+    - Retard
+    - Absence
 
-Après la validation, les champs précédents seront grisés.
+!!! warning "Attention"
+    il est possible que la plage de saisie rentre en conflit avec la plage d'une assiduité.
+    _(Il est impossible d'avoir deux assiduités aux même moment. Cela produit donc un conflit.)_
+    Ce conflit est symbolisé par la mise en évidence de la ligne étudiante
 
-Explication de l'interface
+    ![Conflit](screens/signal_assiduites_group-conflit.png)
 
-![Capture de l'interface](#)
+    Pour résoudre ce conflit il faudra effectuer au moins une de ces actions:
 
-1. La ligne temporelle (Timeline) sert à désigner la période de l'assiduité qui sera saisie.
+    - Changer la plage de saisie
+    - Modifier l'assiduité qui rentre en conflit
+    - Supprimer l'assiduité qui rentre en conflit
+    - Ne pas saisir pour l'étudiant concerné
+    - Utiliser le résolveur de conflit (l’icône à droite de la ligne étudiante)
 
-    Il est possible de la déplacer en maintenant le clic gauche dessus puis en
-    bougeant la souris.
+!!! info "Astuces"
+    - Vous pouvez passer la souris sur les blocs d'assiduités / le petit carré pour avoir plus d'informations.
+    - Vous pouvez cliquer sur un bloc pour changer la plage de saisie à la plage de l'assiduité.
+    - Vous pouvez cliquer sur les ℹ️ pour ouvrir la page de modification d'une assiduité
 
-    Si la période n'est pas de la bonne taille, il est possible de l'agrandir ou
-    de la réduire en plaçant sa souris à l'extrémité droite.
+#### Saisir par Semaine
 
-    Votre curseur devrait changer, à partir de ce moment là vous pouvez cliquer
-    puis bouger l'extrémité pour modifier la taille de la période.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/signal_assiduites_hebdo?formsemestre_id=<formsemestre_id>&group_ids=<group_id,...>&week=<yyyy-Www : 2024-W25 >`
 
-    Si la période bouge toujours alors que vous avez lâché le clic gauche,
-    cliquer à nouveau.
+_Page accessible depuis le tableau de bord d'un semestre (`Saisie hebdomadaire`)._
 
-2. Les boutons d'actions de masse `Mettre tout le monde : `. Ces boutons
-   définirons le même état pour chaque étudiant sur la période sélectionnée.
+_Page accessible depuis le tableau de bord d'un module (`Saisie Absences(Hebdo)`)._
 
-    En cliquant sur un bouton d'état, l'état sera mis pour chaque étudiant, pour
-    modifier cet état il faut appuyer sur un autre bouton d'état.
+!!! warning "Attention"
+    Les semaines sont restreintes au semestre en cours. Vous ne pourrez pas saisir en dehors du semestre.
 
-    Si vous souhaitez retirer les assiduités, il faut cliquer sur le bouton
-    d'état ayant le même état que les étudiants.
+Cliquer sur `autre semaine` affichera un calendrier du semestre en cours. Vous pourrez ensuite choisir la semaine en cliquant sur le calendrier.
 
-3. Les lignes étudiants sont des lignes montrant les informations d'assiduité de
-   chaque étudiant. Chaque ligne est composée de 3 parties :
+!!! info "Astuce"
+    Vous pouvez changer les horaires en cliquant dessus. Par défaut ils correspondent à la configuration générale.
 
-    1. Le nom, le prénom et une photo de l'étudiant afin de le reconnaître
-       facilement
+![Saisie Hebdomadaire](screens/saisie_hebdo.png)
 
-    2. Une petite ligne temporelle montrant l'assiduité de l'étudiant sur la
-       journée.
+### Saisir l'assiduité d'un étudiant
 
-        Le carré au début de la ligne montre la dernière assiduité du jour
-        précédent.
+#### Ajouter une assiduité
 
-        En passant votre souris au dessus des couleurs, vous aurez accès à plus
-        d'informations sur l'assiduité de l'étudiant.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/ajout_assiduite_etud?etudid=<etudid>`
 
-        Cliquer sur une assiduité positionnera la ligne temporelle globale sur
-        la période de l'assiduité.
+_Page accessible en cliquant sur `Ajouter` dans la barre latérale._
 
-        La période globale est représentée par un encadré bleu sur la ligne
-        temporelle.
+!!! warning "Attention"
+    Les modules proposés sont lié au semestre courant. Si vous souhaitez saisir une assiduité pour un semestre passé, vous devez aller sur la page [Bilan](#bilan) du semestre concerné puis cliquer sur `signaler l'assiduité` dans la ligne de l'étudiant concerné.
 
-        Les assiduités justifiées et validés sont représentés par leur couleur
-        respective + un hachage bleu
+![Ajouter une assiduité](screens/ajout_assiduite_etud.png)
 
-        Les assiduités justifiées mais non validées sont représentés par leur
-        couleur respective + un hachage rouge.
+#### Modifier / Voir une assiduité
 
-    3. Les boutons d'assiduités individuels. Ces boutons permettent de déterminer l'état de l'étudiant.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/edit_assiduite_etud/<assiduite_id>`
 
-        Ils fonctionnent de la même façon que les boutons `mettre tout le monde :`.
+_Page accessible en cliquant sur ℹ️ dans les tableaux d'assiduités._
 
-        Si la ligne de l'étudiant est rouge, cela signifie que la période
-        sélectionnée rentre en conflit avec les assiduités de l'étudiant.
-        Cliquer sur un bouton d'assiduité ne modifiera pas l'état de l'étudiant
-        mais ouvrira un menu de résolution de conflit.
+![Modification d'une assiduité](screens/edit_assiduite_etud.png)
 
-        ![Résolution de conflit](#)
+#### Ajouter un justificatif
 
-Les assiduités de la page sont enregistrées en temps réel. Lorsque la saisie est
-terminée vous pouvez fermer la page.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/ajout_justificatif_etud?etudid=<etudid>`
 
-#### Saisie différée
+_Page accessible en cliquant sur `Justifier` dans la barre latérale._
 
-La page saisie différée a pour but de faciliter la saisie d'assiduités avec
-plusieurs périodes.
+Un justificatif peut prendre un des états suivants :
 
-![Page différée](#)
+- En attente de validation
+- Non valide
+- Modifié
+- Valide
 
-La page est composée d'un tableau et d'un bouton valider.
-**Cette page ne sauvegarde pas automatiquement les modifications**
+!!! warning "Attention"
+    Seul l'état `Valide` permet de justifier une assiduité. Les autres états sont là pour faciliter le suivi du justificatif.
 
-Explication du tableau :
+Il est possible d'importer des fichiers (exemple:  une convocation au permis de conduire ) et de donner une description au justificatif.
 
-- La colonne `Noms` : Vous y retrouverez tous les étudiants du groupe
-  sélectionné. En cliquant sur le titre de la colonne vous pourrez changer
-  l'ordre des étudiants (croissant ou décroissant)
-- Les colonnes `Assiduités` : Lorsque vous arrivez sur la page, une seule
-  colonne d'assiduité est présente.
+!!! warning "Attention"
+    Les justificatifs pouvant contenir des informations sensibles, seuls ceux ayant la permission `AbsJustifView` et celui qui a saisie l'information peuvent voir la description et les fichiers.
 
-    Si vous avez besoins d'autres colonnes, appuyer sur le bouton `+`.
+![Ajouter un justificatif à un étudiant](screens/ajout_justificatif_etud.png)
 
-    Si vous souhaitez supprimer une colonne appuyer sur la `croix X` de la
-    colonne.
+#### Modifier / Voir un justificatif
 
-    Il vous faudra remplir la colonne afin de pouvoir saisir l'assiduité des
-    étudiants :
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/edit_justificatif_etud/<justif_id>`
 
-    1. La date de début : Sur la première colonne, la date par défaut sera la
-       date du jour, sur les nouvelles colonnes, la date par défaut sera la date
-       de fin de la colonne précédente.
-    2. La date de fin : La date de fin n'est pas renseignée par défaut,
-       cependant la première fois que vous changer la date de début de la
-       colonne, la date de fin sera automatiquement mise à jour de façon à
-       prendre la taille d'un créneau classique (configuration du
-       semestre/département).
-    3. Le module concerné par l'assiduité. Ce sélecteur n'est pas obligatoire
-       par défaut (configuration du semestre/département).
-    4. `Sélectionner une assiduité` permet de mettre tous les étudiants à un
-       certain état. Ce sélecteur n'est pas obligatoire.
+_Page accessible en cliquant sur ℹ️ dans les tableaux de justificatifs._
 
-- Chaque ligne du tableau correspond à un étudiant. Vous pouvez alors
-  sélectionner l'état de l'assiduité de chaque étudiant pour chaque colonne.
+!!! info "Astuce"
+    Cliquer sur le nom d'un fichier permet de le télécharger
 
-Après avoir rempli le tableau il faudra valider en cliquant sur `valider les assiduités`.
+![Modification d'un justificatif](screens/edit_justificatif_etud.png)
 
-Après validation, toutes les colonnes seront désactivées, si besoins vous pouvez
-les réactiver en cliquant sur `Activer` pour chaque colonne.
+### Voir l'assiduité d'un groupe
 
-Il est possible que des erreurs apparaissent. Les erreurs sont gérées par
-colonnes puis par étudiant. Cela signifie qu'une erreur de colonne (ex: une
-mauvaise date) désactivera complètement la colonne alors qu'une erreur
-d'étudiant (ex: l'étudiant possède déjà une assiduité sur cette période)
-désactivera uniquement l'envoie de l'assiduité le concernant.
+#### Bilan
 
-Vous pouvez obtenir plus d'informations sur l'erreur en plaçant votre souris au dessus du `ℹ️`.
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/visu_assi_group?date_debut=<yyyy-mm-dd>&date_fin=<yyyy-mm-dd>&group_ids=<group_id>`
 
-Il est possible de forcer la mise à jour des assiduités : **Attention, cela ne
-fonctionnera que pour les assiduités ayant exactement la même période** (ceci
-permet de corriger facilement les saisies où l'on aurait oublié d'indiquer le
-module).
+_Page accessible depuis le tableau de bord d'un semestre._
 
-Chaque colonne possède un numéro distinctif qui est visible en laissant la
-souris au dessus de l'entête de la colonne. Ce numéro est utilisé dans les
-messages d'erreurs.
+La page est configurée par défaut pour afficher les comptes sur la durée du semestre. Mais il est possible de changer les dates puis de cliquer sur `Changer`.
+
+L'option `Restreindre aux modules de ce semestre` permet de ne comptabiliser que les assiduités ayant un module spécifié.
+(Le module `Autre` ne sera pas comptabilisé)
+
+![Visualisation de l'assiduité d'un groupe](screens/bilan_assiduites_group.png)
+
+### Voir l'assiduité d'un étudiant
+
+#### Liste/Bilan
+
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/bilan_etud?etudid=<etudid>`
+
+_Page accessible en cliquant sur `Liste/Bilan` dans la barre latérale._
+
+Cette page permet :
+
+- d'afficher les statistiques de l'assiduité d'un étudiant sur une période. (par défaut : l'année scolaire en cours)
+- d'afficher la liste des assiduités et justificatifs enregistrés pour l'étudiant
+- d'afficher si l'étudiant a trop d'absences (par rapport à la préférence `Seuil d'alerte des absences`)
+
+![Liste/Bilan de l'assiduité d'un étudiant](screens/bilan_assiduites_etud.png)
+
+#### Calendrier
+
+Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/calendrier_assi_etud?etudid=<etudid>`
+
+_Page accessible en cliquant sur `Calendrier` dans la barre latérale._
+
+La page calendrier permet d'afficher un calendrier de l'année scolaire en cours et d'afficher l'assiduité de l'étudiant concerné.
+Il est possible de changer l'année en cours à l'aide du sélecteur en bas de page.
+
+En haut de la page se trouve des éléments de configuration de l'affichage :
+
+- `Afficher les présences` : permet d'afficher les présences (par défaut : Non)
+- `Afficher les retards` : permet d'afficher les retards (par défaut : Non)
+- `Mode demi-journée` : permet d'afficher l'assiduité par demi-journée (par défaut : Oui). Si non coché, l'assiduité sera montrée par journée
+
+La zone avec les bordures oranges correspond à la semaine en cours.
+
+![Calendrier de l'Assiduité d'un étudiant](screens/calendrier_assiduite_etud.png)
+
+!!! info "Astuces"
+    Passer sa souris sur un jour affichera une bulle. Cette bulle montre les assiduités de la journée.
+    Il est aussi possible de cliquer sur les assiduités de la bulle pour se rendre sur leur page d'édition.
 
 !!! note "Voir aussi"