Merge pull request 'Documentation Développeur du module Assiduité' (#66) from iziram/DocAssiduites:doc-assi-dev into master

Reviewed-on: ScoDoc/DocScoDoc#66

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 : 
+
+    - `<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).
+Chaque justificatif est obligatoirement associé à 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.
+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:
 
 ```text
 justificatif/
@@ -252,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é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)
+
+### 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.
+
+!!! 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))
+
+### 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)
+
+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).
+
+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`