From c688bf6578254e0de987412fa743d88b7cc7c9cd Mon Sep 17 00:00:00 2001 From: Iziram Date: Tue, 23 Jul 2024 09:10:03 +0200 Subject: [PATCH 1/3] dev-assi : modifs + typos --- docs/AssiduitesDev.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/AssiduitesDev.md b/docs/AssiduitesDev.md index 07193da..660d7a0 100644 --- a/docs/AssiduitesDev.md +++ b/docs/AssiduitesDev.md @@ -84,11 +84,36 @@ 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 : + + - `` : 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) @@ -199,7 +224,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: ```text justificatif/ From ffba18c883c880a94f54cff992bbcd685ab96076 Mon Sep 17 00:00:00 2001 From: Iziram Date: Thu, 25 Jul 2024 17:55:14 +0200 Subject: [PATCH 2/3] DocAssiduitesDev : ajout cache, vue, formulaires, tableaux, calendriers, templates --- docs/AssiduitesDev.md | 101 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 3 deletions(-) diff --git a/docs/AssiduitesDev.md b/docs/AssiduitesDev.md index 660d7a0..2a7b56d 100644 --- a/docs/AssiduitesDev.md +++ b/docs/AssiduitesDev.md @@ -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 \ No newline at end of file +- `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](https://git.scodoc.org/ScoDoc/ScoDoc/src/branch/master/app/scodoc/sco_cache.py) + +### 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. + +!!! 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)) + +### 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) + +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. + +!!! 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` \ No newline at end of file From 83efd5fe7da9b1b64371bb07bf90215d5bcde892 Mon Sep 17 00:00:00 2001 From: Iziram Date: Fri, 26 Jul 2024 09:38:41 +0200 Subject: [PATCH 3/3] AssiduitesDev : correction typos --- docs/AssiduitesDev.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/AssiduitesDev.md b/docs/AssiduitesDev.md index 2a7b56d..74bd612 100644 --- a/docs/AssiduitesDev.md +++ b/docs/AssiduitesDev.md @@ -222,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’arborescence des fichiers justificatifs: +Voici la représentation de l'arborescence des fichiers justificatifs: ```text justificatif/ @@ -282,7 +282,7 @@ La classe `JustificatifArchiver` possède plusieurs fonctions pour simplifier la Le module assiduité utilise le cache pour stocker temporairement certaines informations qui demandent des calculs importants. -### Classes liés +### Classes liées Il y a deux classes concernant les caches du module : @@ -290,7 +290,7 @@ Il y a deux classes concernant les caches du module : - `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) + 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) ### Fonctions liées @@ -300,7 +300,7 @@ Des fonctions simplifiant la gestion des caches sont disponibles dans [app/scodo - `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. +- `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. !!! 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) @@ -320,7 +320,7 @@ Des fonctions simplifiant la gestion des caches sont disponibles dans [app/scodo 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)) +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)) ### Calendriers @@ -354,9 +354,9 @@ Il y a 2 type de tableaux d'assiduité. Le tableau simple utilisé dans la page - `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) +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) -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. +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. !!! 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).