Iziram ffba18c883 DocAssiduitesDev : ajout cache, vue, formulaires, tableaux, calendriers, templates

2024-07-25 17:55:14 +02:00

20 KiB

Raw Blame History

Module Assiduité

!!! warning Attention vous vous trouvez sur la documentation Développeur du module Assiduité.

La documentation utilisateur est [ici](Assiduites.md).

Le module Assiduité est le nouveau module introduit en 9.6 permettant la saisie précise de l'assiduité des étudiants et étudiantes.

Ce module a été développé par Matthias HARTMANN, pendant son alternance entre 2022 et 2024 (alternance financée par l'association ScoDoc) et remplace l'ancien module Absence.

Représentation en BDD

Le module Assiduité introduit deux nouveaux objets à la base ScoDoc :

Assiduite : l'objet représentant une assiduité (absent,retard,present)
Justificatif : l'objet représentant un justificatif (permet de justifier ou non une assiduité / plusieurs assiduités)

La modélisation est gérée dans le fichier app/models/assiduites.py.

Représentation de l'Assiduité

Le tableau si dessous reprend la représation des données d'une assiduité.

!!! warning Dans ScoDoc, l'heure affichée doit être celle affichée sur la montre des étudiants.

Assurez vous que la **timezone** du serveur soit la bonne.

champs	type	commentaire
id / assiduite_id	Integer	L'identifiant de l'assiduité
date_debut	DateTimeTZ	La date (+heure) de début de l'assiduité. Doit avoir une TIMEZONE
date_fin	DateTimeTZ	La date (+heure) de fin de l'assiduité. Doit avoir une TIMEZONE
etudid	Integer	L'identifiant de l'étudiant concerné par l'assiduité (clé externe)
moduleimpl_id	Integer	L'identifiant du moduleimpl concerné par l'assiduité. (plus d'infos) Peut être None (clé externe)
etat	Integer	L'état de l'assiduité (plus d'infos)
description	Text	La description de l'assiduité Peut être None
entry_date	DateTimeTZ	La date (+heure) de saisie de l'assiduité. Doit avoir une TIMEZONE. Par défaut à la date actuelle
user_id	Integer	L'identifiant de l'utilisateur qui a saisie l'assiduité. Peut être None (clé externe)
est_just	Boolean	Indique si l'assiduité est justifiée
external_data	JSON	Champs de données JSON peu utilisées dans ScoDoc même mais facilite la vie aux utilisateurs de l'API Peut être None

!!! tip Il est conseillé d'utiliser les méthodes du modèle Assiduité afin de créer / éditer / supprimer une assiduité.

Etats d'assiduité

!!! info Une classe EtatAssiduite simplifiant la traduction ETAT ↔ VALEUR est disponible dans app/scodoc/sco_utils.py

état	valeur
PRESENT	0
RETARD	1
ABSENT	2

!!! warning Seules les assiduités RETARD et ABSENT peuvent être justifiées.

Etudiants

Chaque assiduité est obligatoirement associée à un étudiant (Identite). Il est possible de récupérer toutes les assiduités d'un étudiant en utilisant la relation à partir du modèle Identite.

etudiant : Identite = Identite.get_etud(1234)
assiduites_etud : Query = etudiant.assiduites

# Identite.assiduites est une query et permet donc les filtrages etc.

# Première absence
prem_abs: Assiduite = assiduites_etud.filter(
    Assiduite.etat == scu.EtatAssiduite.ABSENT
).first()

ModuleImpl

Une assiduité peut être reliée à un ModuleImpl à l'aide du moduleimpl_id.

Cependant suite à une demande des utilisateurs, il existe un FAUX module nommé autre. Ce module permet de contourner la sécurité de la préférence forcer la saisie d'un module dans le cas où la saisie d'assiduité n'est pas directement en lien avec un module enregistré dans ScoDoc.

!!! warning Ce FAUX module n'est pas inscrit dans le moduleimpl_id mais dans external_data.

Voici le format de `external_data` : 
```json
{
    "module":"Autre",
    "cle-non-scodoc" : "valeur-non-scodoc"
}
```

Des fonctions ont été rédigées pour faciliter la gestion de ce FAUX module. Elles sont toutes disponibles dans la classe de l'objet Assiduité. (voir le code)

get_module : récupère (si existant) le module associé à l'assiduité
- Si module ScoDoc : renvoie l'objet Module (ou le titre du module si la traduction est active)
- Si module external_data:Autre : renvoie la chaîne Autre module (pas dans la liste)
- Si module external_data:? : renvoie la valeur liée à la clé "module" de external_data
- Si pas de module : renvoie None (ou Module non spécifié si la traduction est active)
get_moduleimpl_id : récupère (si existant) le moduleimpl_id associé à l'assiduité (comprend le module autre)
- Si moduleimpl ScoDoc : renvoie l'id du moduleimpl
- Si module dans external_data : renvoie la valeur liée à la clé "module" de external_data
- Si pas de module : renvoie None
set_moduleimpl_id : permet de mettre à jour le moduleimpl_id (prend en compte le module autre)

On peut donner :
- <int/str:moduleimpl_id> : l'identifiant d'un moduleimpl
- "autre" : le module autre
- "" : pas de module

Représentation du Justificatif

Le tableau si dessous reprend la représation des données d'un justificatif.

!!! warning Dans ScoDoc, l'heure affichée doit être celle affichée sur la montre des étudiants.

Assurez vous que la **timezone** du serveur soit la bonne.

champs	type	commentaire
id / justif_id	Integer	L'identifiant du justificatif
date_debut	DateTimeTZ	La date (+heure) de début du justificatif. Doit avoir une TIMEZONE
date_fin	DateTimeTZ	La date (+heure) de fin du justificatif. Doit avoir une TIMEZONE
etudid	Integer	L'identifiant de l'étudiant concerné par le justificatif (clé externe)
etat	Integer	L'état du justificatif(plus d'infos)
raison	Text	La raison du justificatifPeut être None
entry_date	DateTimeTZ	La date (+heure) de saisie du justificatif. Doit avoir une TIMEZONE. Par défaut à la date actuelle
user_id	Integer	L'identifiant de l'utilisateur qui a saisie le justificatif. Peut être None (clé externe)
fichier	Text	l'identifiant de l'archive justificatif si existante (plus d'infos)
external_data	JSON	Champs de données JSON non utilisé dans ScoDoc mais facilite la vie aux utilisateurs de l'API Peut être None

!!! tip Il est conseillé d'utiliser les méthodes du modèle Justificatif afin de créer / éditer / supprimer un justificatif.

Etats de Justificatif

!!! info Une classe EtatJustificatif simplifiant la traduction ETAT ↔ VALEUR est disponible dans app/scodoc/sco_utils.py

état	valeur
VALIDE	0
NON_VALIDE	1
ATTENTE	2
MODIFIE	3

!!! warning Seul l'état VALIDE permet de justifier des assiduités. Les autres états permettent d'organiser le travail administratif.

Etudiants

Chaque justificatif est obligatoirement associé à un étudiant (Identite). Il est possible de récupérer tous les justificatifs d'un étudiant en utilisant la relation à partir du modèle Identite.

etudiant : Identite = Identite.get_etud(1234)
justificatifs_etud : Query = etudiant.justificatifs

# Identite.justificatifs est une query et permet donc les filtrages etc.

# Première justificatif valide
prem_abs: Justificatif = justificatifs_etud.filter(
    Justificatif.etat == scu.EtatJustificatif.VALIDE
).first()

Fonctionnements des Assiduités

Métriques

Les métriques d'assiduités permettent le suivi de l'assiduité d'un étudiant avec plusieurs niveaux de précisions.

Il existe 4 métriques :

compte : un simple comptage du nombre d'assiduités sans autre calcul
journee : le calcul du nombre de journées concernées par les assiduités (chaque journée n'est comptée qu'une fois)
demi : le calcul du nombre de demi-journées concernées par les assiduités (chaque demi-journée n'est comptée qu'une fois)
heure : le calcul du nombre d'heures concernées par les assiduités.

Ces calculs sont réalisés grâce à la classe CountCalculator trouvable dans app/scodoc/sco_assiduites.py.

Il n'est pas nécessaire de créer un objet CountCalculator à chaque fois que vous voulez un calcul. Vous pouvez utiliser directement la fonction sco_assiduites.py#get_assiduites_stats.

!!! warning Les métriques sont utilisées dans les bulletins, sidebar et bilan.

Ces valeurs utilisent le [cache](#cache).

Permissions

Les fonctions relatives aux assiduités utilisent les permissions suivantes :

AbsChange : permet de créer / éditer / supprimer les assiduités
AbsJustifView : permet de voir les informations (descriptions) des assiduités (données personnelles cachées par défaut)

Fonctionnements des Justificatifs

Permissions

Les fonctions relatives aux justificatifs utilisent les permissions suivantes :

AbsChange : permet de créer / éditer / supprimer les justificatifs
AbsJustifView : permet de voir les informations (raison, fichiers) des justificatifs (données personnelles cachées par défaut)
JustifValidate : permet de changer l'état d'un justificatif de Attente à Valide / Non Valide / Modifie

Gestion des archives justificatives

L'ensemble des fonctionnalités relatives aux archives justificatives (fichiers importés) est disponible dans le fichier app/scodoc/sco_archives_justificatifs.py

!!! note Le système global d'archive est disponible ici

Les archives sont enregistrées dans le dossier `/opt/scodoc-data/archives/`.

Voici la représentation de l’arborescence des fichiers justificatifs:

justificatif/
        └── <dept_id>/
            └── <etudid/oid>/
                └── <archive_id>/
                    ├── [_description.txt]
                    ├── [<filename.ext>]
                    └── [_trace.csv]

Les archives sont organisées par département, puis par étudiant.

Gestion des fichiers

La classe JustificatifArchiver possède plusieurs fonctions pour simplifier la gestion des fichiers.

save_justificatif : enregistre un fichier pour un étudiant. Génère l'archive si elle n'existe pas. Génère le fichier trace s'il n'existe pas et log le fichier. Renvoie le nom de l'archive et le nom du fichier (traduit en nom serveur).
delete_justificatif : supprime un fichier d'une archive d'un étudiant. (Ajoute à la trace l'action). Si on ne donne pas de nom de fichier, supprime l'archive (et donc tous ses fichiers).
list_justificatifs : retourne la liste des fichiers avec l'user_id de l'importateur.
get_justificatif_file : renvoie une réponse de téléchargement (pour les vues) du fichier demandé.
remove_dept_archive : supprime toutes les archives d'un département, supprime aussi toutes les traces

Cache

Le module assiduité utilise le cache pour stocker temporairement certaines informations qui demandent des calculs importants.

Classes liés

Il y a deux classes concernant les caches du module :

RequeteTableauAssiduiteCache qui gère les caches liés aux calendrier et tableaux d'assiduité.
AbsSemEtudCache qui gère les caches liés aux comptes d'absences (nonjust et just) utilisées dans les semestres

!!! info Les classes liées aux caches se retrouve dans le fichier app/scodoc/sco_cache.py

Fonctions liées

Des fonctions simplifiant la gestion des caches sont disponibles dans app/scodoc/sco_assiduites.py (aussi appelé scass)

Récupération de valeurs

get_assiduites_count(etudid: int, sem: dict) : retourne le nombre d'absences de l'étudiant dans le semestre donné.
formsemestre_get_assiduites_count(etudid: int, formsemestre: FormSemestre, moduleimpl_id: int = None) : retourne le nombre d'absences de l'étudiant dans le semestre donné. (filtrage avec un moduleimpl possible)
get_assiduites_count_in_interval : fonction utilisée par les deux fonctions du dessus (et par d'autres) qui s'occupe du calcule et de la mise en cache.

!!! info Les valeurs des tableaux sont directement calculés dans la génération des tableaux. Plus d'informations dans la partie dédiée aux tableaux

Invalidations

simple_invalidate_cache(obj: dict, etudid: str | int = None) : invalide le cache à partir d'un objet et d'un etudiant. Permet d'invalider tous les caches (semestre et tableaux).
invalidate_assiduites_count(etudid: int, sem: dict) : invalide les calculs d'absences (nb just/njust) pour un semestre
invalidate_assiduites_etud_date(etudid: int, the_date: datetime) : invalide les cache de semestre,bulletin et absence (calcul nb just, njust)

!!! tip Le plus simple pour invalider le cache est d'utiliser la fonction simple_invalidate_cache car elle invalide tous les caches en utilisant les autres fonctions d'invalidation.

C'est la fonction la plus sûre concernant l'invalidation des caches du module Assiduité.

Vues

Le module Assiduité propose des éléments variés pour les pages.

Ces éléments sont ensuite utilisé dans le script de vue du module (app/views/assiduites.py)

Calendriers

Le module assiduité propose un calendrier pour voir l'assiduité d'un étudiant sur une année.

La vue se nomme calendrier_assi_etud et peut servir d'exemple sur l'utilisation du générateur de calendrier (les classes JourAssi et CalendrierAssi sont définies en bas du script de la vue)

La génération des calendriers utilise le script app/scodoc/sco_gen_cal.py

!!! tip Ce même script possède la fonction calendrier_choix_date permettant d'afficher un calendrier pour choisir un jour ou une semaine entre deux dates données.

Formulaires

Les formulaires sont une partie importante des UI du module Assiduité.

L'ensemble des formulaires du module peut se trouver dans les fichiers suivants :

app/forms/assiduite/ajout_assiduite_etud.py : Formulaires d'ajout d'une assiduité, d'ajout d'un justificatif et de modification d'un justificatif
app/forms/assiduite/edit_assiduite_etud.py : Formulaire de modification d'une assiduité

Ces formulaires (basés sur Flask-WTF) sont ensuite utilisés dans les templates jinja.

Tableaux

Il y a 2 type de tableaux d'assiduité. Le tableau simple utilisé dans la page visu_assi_group et les tableaux complexes qui sont présentés dans les pages suivantes :

bilan_dept
bilan_etud
ajout_assiduite_etud
ajout_justificatif_etud
recup_assiduites_plage

Les tableaux simples sont géré par le fichier app/tables/visu_assiduites.py

Les tableaux complexes sont géré par le fichier app/tables/liste_assiduites.py. Ceux-ci sont plus polyvalents et utilise le système de cache.

!!! info Une fonction a été écrite pour faciliter la préparation des tableaux complexes, elle se nomme _prepare_tableau et se trouve dans le fichier de vues.

La vue recup_assiduites_plage est un bon exemple d'utilisation des tableaux complexes.

Templates

L'ensemble des templates du module assiduité est organisé dans le dossier app/templates/assiduites

On y retrouvera les pages (l'organisation des éléments de UI/UX et des scripts de fonctionnement) et les widgets (Des éléments d'UI/UX qui seront intégrés dans une page)

Les templates liés aux pages ont le même nom que la vue qui l'utilise.

Exemple : ajout_assiduite_etud → ajout_assiduite_etud.j2

20 KiB Raw Blame History Unescape Escape

Module Assiduité

Représentation en BDD

Représentation de l'Assiduité

Etats d'assiduité

Etudiants

ModuleImpl

Représentation du Justificatif

Etats de Justificatif

Etudiants

Fonctionnements des Assiduités

Métriques

Permissions

Fonctionnements des Justificatifs

Permissions

Gestion des archives justificatives

Archive

_description.txt

_traces.csv

Gestion des fichiers

Cache

Classes liés

Fonctions liées

Récupération de valeurs

Invalidations

Vues

Calendriers

Formulaires

Tableaux

Templates

20 KiB

Raw Blame History