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

View File

@ -84,12 +84,37 @@ Cependant suite à une demande des utilisateurs, il existe un **FAUX** module no
!!! 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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/models/assiduites.py))
- `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
@ -133,8 +158,8 @@ Le tableau si dessous reprend la représation des données d'un justificatif.
#### Etudiants
Chaque justificatif est obligatoirement associée à un étudiant (Identite).
Il est possible de récupérer toutes les justificatifs d'un étudiant en utilisant la relation à partir du modèle Identite.
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.
```py
etudiant : Identite = Identite.get_etud(1234)
@ -150,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.
@ -199,7 +222,7 @@ L'ensemble des fonctionnalités relatives aux archives justificatives (fichiers
Les archives sont enregistrées dans le dossier `/opt/scodoc-data/archives/`.
Voici la représentation de l'arboressence des fichiers justificatifs:
Voici la représentation de l'arborescence des fichiers justificatifs:

caractère unicode à enlever

caractère unicode à enlever
```text
justificatif/
@ -253,3 +276,100 @@ La classe `JustificatifArchiver` possède plusieurs fonctions pour simplifier la
- `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ées

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 retrouvent 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 calcul 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és 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és 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és 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` &rightarrow; `ajout_assiduite_etud.j2`