Documentation Développeur du module Assiduité #66

Merged
viennet merged 3 commits from iziram/DocAssiduites:doc-assi-dev into master 2024-07-26 09:41:29 +02:00
Showing only changes of commit ffba18c883 - Show all commits

View File

@ -175,8 +175,6 @@ prem_abs: Justificatif = justificatifs_etud.filter(
## Fonctionnements des Assiduités
### Cache
### Métriques
Les métriques d'assiduités permettent le suivi de l'assiduité d'un étudiant avec plusieurs niveaux de précisions.
@ -277,4 +275,101 @@ La classe `JustificatifArchiver` possède plusieurs fonctions pour simplifier la
- `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
- `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

liées

liées
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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/scodoc/sco_cache.py)

retrouvent

retrouvent
### Fonctions liées
Des fonctions simplifiant la gestion des caches sont disponibles dans [app/scodoc/sco_assiduites.py](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/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.

calcul

calcul
!!! 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](#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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/views/assiduites.py))

utilisés

utilisés
### 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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/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](#templates).
### 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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/tables/visu_assiduites.py)

gérés

gérés
Les tableaux complexes sont géré par le fichier [app/tables/liste_assiduites.py](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/tables/liste_assiduites.py). Ceux-ci sont plus polyvalents et utilise le système de cache.

gérés

gérés
!!! 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](#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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/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`