DocAssiduites/docs/Assiduites.md

<!-- 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.

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)

## Fonctionnalités

Le module fournit:

- Gestion des absences/présences/retards
- Précision des saisies (périodes déterminées par une heure de début et une
  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))

## 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
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

Le module possède deux types de configuration, une générale et une par département/semestre.

### 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 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 des cours (par défaut :
  18h00)
- `Granularité` : La granularité de la saisie (par défaut : 15 min)

### 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`

- `Imposer la déclaration du module` : Forcer les utilisateurs de ScoDoc à
  renseigner le module à chaque saisie d'assiduités.
- `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
  les autres modules de ScoDoc.
    - `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é)

## Gestion de l'assiduité

### Saisir l'assiduité d'un groupe

#### Saisir par Jour

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/signal_assiduites_group?formsemestre_id=<formsemestre_id>&group_ids=<group_id,...>&day=<yyyy-mm-dd>`

_Page accessible depuis le tableau de bord d'un semestre (`Saisir l'assiduité`)._

_Page accessible depuis le tableau de bord d'un module (`Saisie Absences`)._

![Saisir l'assiduité](screens/signal_assiduites_group.png)

##### Composition de la page

- 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)

##### Composition d'une ligne étudiante

![Ligne étudiante classique](screens/signal_assiduites-group-ligne-etud.png)

- 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

!!! 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

    ![Conflit](screens/signal_assiduites_group-conflit.png)

    Pour résoudre ce conflit il faudra effectuer au moins une de ces actions:

    - 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)

!!! 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é

#### Saisir par Semaine

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/signal_assiduites_hebdo?formsemestre_id=<formsemestre_id>&group_ids=<group_id,...>&week=<yyyy-Www : 2024-W25 >`

_Page accessible depuis le tableau de bord d'un semestre (`Saisie hebdomadaire`)._

_Page accessible depuis le tableau de bord d'un module (`Saisie Absences(Hebdo)`)._

!!! warning "Attention"
    Les semaines sont restreintes au semestre en cours. Vous ne pourrez pas saisir en dehors du semestre.

Cliquer sur `autre semaine` affichera un calendrier du semestre en cours. Vous pourrez ensuite choisir la semaine en cliquant sur le calendrier.

!!! info "Astuce"
    Vous pouvez changer les horaires en cliquant dessus. Par défaut ils correspondent à la configuration générale.

![Saisie Hebdomadaire](screens/saisie_hebdo.png)

### Saisir l'assiduité d'un étudiant

#### Ajouter une assiduité

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/ajout_assiduite_etud?etudid=<etudid>`

_Page accessible en cliquant sur `Ajouter` dans la barre latérale._

!!! 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é.

![Ajouter une assiduité](screens/ajout_assiduite_etud.png)

#### Modifier / Voir une assiduité

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/edit_assiduite_etud/<assiduite_id>`

_Page accessible en cliquant sur ℹ️ dans les tableaux d'assiduités._

![Modification d'une assiduité](screens/edit_assiduite_etud.png)

#### Ajouter un justificatif

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/ajout_justificatif_etud?etudid=<etudid>`

_Page accessible en cliquant sur `Justifier` dans la barre latérale._

Un justificatif peut prendre un des états suivants :

- En attente de validation
- Non valide
- Modifié
- Valide

!!! warning "Attention"
    Pour saisir les états `Valide` , `Modifié`, `Non valide` il faut obligatoirement la permission `JustifValidate`

!!! warning "Attention"
    Seul l'état `Valide` permet de justifier une assiduité. Les autres états sont là pour faciliter le suivi du justificatif.

Il est possible d'importer des fichiers (exemple:  une convocation au permis de conduire ) et de donner une description au justificatif.

!!! 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.

![Ajouter un justificatif à un étudiant](screens/ajout_justificatif_etud.png)

#### Modifier / Voir un justificatif

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/edit_justificatif_etud/<justif_id>`

_Page accessible en cliquant sur ℹ️ dans les tableaux de justificatifs._

!!! info "Astuce"
    Cliquer sur le nom d'un fichier permet de le télécharger

!!! warning "Attention"
    Pour saisir les états `Valide` , `Modifié`, `Non valide` il faut obligatoirement la permission `JustifValidate`

![Modification d'un justificatif](screens/edit_justificatif_etud.png)

### Voir l'assiduité d'un groupe

#### Bilan

Route : `/ScoDoc/<DEPT>/Scolarite/Assiduites/visu_assi_group?date_debut=<yyyy-mm-dd>&date_fin=<yyyy-mm-dd>&group_ids=<group_id>`

_Page accessible depuis le tableau de bord d'un semestre._

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"

    - [Migration des absences vers les assiduités](AssiduitesMigration.md)
    - [API](ScoDoc9API.md) : API pour interfaçage avec d'autres applications
    - [API et fichiers justificatifs](FichiersJustificatifs)
    - [FAQ](FAQ.md)
    - [Contacts](Contact.md)