diff --git a/docs/DevAbsencesCalendrier.md b/docs/DevAbsencesCalendrier.md new file mode 100644 index 000000000..0e181c43f --- /dev/null +++ b/docs/DevAbsencesCalendrier.md @@ -0,0 +1,127 @@ +# Absences et emplois du temps (développeurs) + +Les emplois du temps sont gérés par un autre logiciel, comme: + +- Hyperplanning +- Celcat +- GPU +- VT [Visual Timetabling](http://visual.timetabling.free.fr) +- ... + +Ces logiciels peuvent exporter les calendriers au format ICS (iCalendar, +[RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)). + +## Calendriers et évènements + +Un calendrier est ici une liste d'évènements, chaque cours étant un évènement. L'évènement +comporte: + +- dates début et fin; +- identifiant du groupe d'étudiants concerné (dans la formation, par ex. groupe + de TD); +- identifiant du module (enseignement): par exemple, l'élément Apogée. +- identifiant de l'enseignant concerné. + +On suppose qu'on a un calendrier par "formation" (`FormSemestre` ScoDoc), +identifié par un code (par exemple, code étape Apogée) que l'on appellera `edt_id`. + +### Fuseaux horaires + +La lecture de l'ics donne des dates avec time zone, en général en UTC. + +L'affichage se fait en heure locale du client. + +Problèmes: + +- les paramètres `assi_morning_time`, `assi_afternoon_time` semblent se référer + à l'heure serveur ? + +### Exemple: cas de l'USPN + +Cet établissement utilise HyperPlanning. Les calendrier sont exportés +régulièrement, on a un fichier ics par formation (code Apogée). + +```ics +BEGIN:VEVENT +CATEGORIES:HYPERPLANNING +DTSTAMP:20231101T140300Z +LAST-MODIFIED:20230905T094241Z +UID:Cours-423101-5-BUT2_RT_pa._CYBER-Index-Education +DTSTART:20230920T060000Z +DTEND:20230920T083000Z +SUMMARY;LANGUAGE=fr:TP2 GPR1 - VCYR303 - Services reseaux ava (VCYR303) - 1234 - M. VIENNET EMMANUEL - V2ROM - BUT2 RT pa. ROM - Groupe 1 +LOCATION;LANGUAGE=fr:P202 CRIT - P202 CRIT.RESEAUX +DESCRIPTION;LANGUAGE=fr:Matière : VCYR303 - Services reseaux ava (VCYR303)\nEnseignant : 1234 - M. VIENNET EMMANUEL\nPromotion : V2ROM - BUT2 RT pa. ROM\nTD : Groupe 1\nSalle : P202 CRIT - P202 CRIT.RESEAUX\nMémo : TP2 GPR1\n +X-ALT-DESC;FMTTYPE=text/html:Matière : VCYR303 - Services reseaux ava (VCYR303)
Enseignant : 1234 - M. VIENNET EMMANUEL
Promotion : V2ROM - BUT2 RT pa. ROM
TD : Groupe 1
Salle : P202 CRIT - P202 CRIT.RESEAUX
Mémo : TP2 GPR1
+END:VEVENT +``` + +On a ici: + +- identifiant de la formation: dans le nom du fichier calendrier (ici `V2CYB.ics`); +- identifiant du groupe: dans `SUMMARY`, `* - ` +- identifiant du module: on a le code `VCYR303` à trois endroits: `SUMMARY`, + `DESCRIPTION`, `X-ALT-DESC`. +- identifiant de l'enseignant: `SUMMARY`, `DESCRIPTION`, `X-ALT-DESC`. + +## Transcodage des identifiants + +ScoDoc n'utilise évidemment pas les mêmes identifiants que ceux trouvés dans les +calendriers. + +### "Formation" + +Il s'agit du `FormSemestre`. On a déjà les codes étapes Apogée. On +proposera un champs "identifiant emploi du temps" (`edt_id`), et à défaut on +utilisera le premier code étape Apogée. + +### Groupes + +Chaque groupe ScoDoc peut indiquer son ou ses identifiants edt (`edt_id`). A défaut, on +utilisera son nom (il sera donc conseillé aux utilisateurs d'adopter les mêmes +noms de groupes dans ScoDoc et dans leur logiciel d'emploi du temps). + +### Module + +Ajouter `etd_id` dans `Module`, avec utilisation de `code_apogee` si absent. + +### Enseignant + +`edt_id` (dans l'exemple précédent `"1234"`), doit être renseigné dans ScoDoc. A +l'USPN, on peut récupérer cette information dans le CAS (dans `supannEmpId` et +`employeeNumber`). + +Champ `edt_id` dans `User`. Affecté par l'authentification CAS, qui peut +récupérer une information dans la réponse XML du serveur CAS, grâce à +l'expression `cas_edt_id_from_xml_regexp` de la config générale. SuperAdmin peut +aussi forcer manuellement l'`edt_id` des comptes utilisateurs. + +## Architecture technique + +### Principes généraux + +- ScoDoc consomme la donnée "emploi du temps" mais n'a pas vocation à la +republier (on ne proposera aucune API pour ce faire, les clients intéressés +devant s'adresser à l'API (ou équivalent) du logiciel d'emplois du temps). + +- ScoDoc est agnostique sur le logiciel d'emploi du temps et n'effectue aucune +requête API vers celui-ci. Il se contente de consommer des calendriers (ics) copiés +(par exemple chaque heure) dans un répertoire accessible au serveur ScoDoc. + +- Chaque `FormSemestre` va chercher à s'associer à un (et un seul ?) calendrier. + +## Fonctions proposées aux utilisateurs + +L'objectif est de simplifier la saisie des absences: afficher l'emploi du temps +par semaine, et permettre la saisie des absences d'un cours donné en ayant +automatiquement pré-rempli le module, la date, l'heure de début et l'heure de +fin. + +En option, restreindre la saisie des absences par les enseignants aux seules +plages/groupes qui les concernent. + +!!! note "Voir aussi" + + - Emplois du temps: [doc utilisateur](EmploisDuTemps.md) + - [Contacts](Contact.md) + diff --git a/docs/DevConventions.md b/docs/DevConventions.md index c9cc42433..e12f2030c 100644 --- a/docs/DevConventions.md +++ b/docs/DevConventions.md @@ -20,7 +20,7 @@ Pour les nouveaux codes, respecter les principes suivants: - l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire - l'usage de pylint et mypy est fortement recommandé -- Pour le code JS, indentation avec 2 espace (sous VS Code, utiliser Prettier). +- Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser *Prettier*). ## Conventions standard Python @@ -42,7 +42,7 @@ def _upload_justificatif_files( ## Vues et templates -Les vues utilisent un template Jinja, fichier avec extension j2. +Les vues utilisent un template *Jinja*, fichier avec extension j2. On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template. @@ -79,7 +79,7 @@ du serveur. Cela signifie que, quelle que soit l'emplacement de l'utilisateur, les heures affichées et saisies par ScoDoc seront données dans le fuseau horaire du serveur. -L'API publie et reçoit des heures avec fuseau horaire (*timezone*) et n'est pas +L'API publie et reçoit des heures au format ISO avec fuseau horaire (*timezone*) et n'est pas concernée par cette remarque. diff --git a/docs/EmploisDuTemps.md b/docs/EmploisDuTemps.md new file mode 100644 index 000000000..2180c1098 --- /dev/null +++ b/docs/EmploisDuTemps.md @@ -0,0 +1,62 @@ +# Utilisation des emplois du temps + +ScoDoc peut être interfacé avec un logiciel de gestion des emplois du temps. +Le paramétrage peut-être assez complexe, mais une fois mis en place cela permet +à ScoDoc d'afficher l'emploi du temps des étudiants d'un semestre et facilite +grandement la saisie des absences. + +TODO **document en cours de rédaction : passer par le Discord pour en savoir plus** + +## Principes généraux + +principe général: ics, ... +TODO + +### Fichiers ics + +TODO + +### Fuseau horaire + +Les calendriers sont exportés avec des dates comportant l'indication du fuseau +horaire. ScoDoc affiche en principe toutes les heures en *heure locale du +serveur*, c'est à dire à la montre des étudiants (et non dans l'heure locale de +l'utilisateur qui peut être en déplacement dans un autre pays). + +## Paramétrage global (administrateur) + +**par le super-admin: Indiquer comment paramétrer les regexp, avec un exemple VEVENT.** + +TODO + +## Identifiants: semestres, groupes, modules, enseignants + +**indiquer où renseigner les identifiants (admin de dept) avec copies d'écran** +TODO + +### Semestres + +TODO + +### Groupes d'étudiants + +TODO + +### Modules + +TODO + +### Enseignants + +TODO + +## Problèmes fréquents (FAQ) + +- Les évènements sont tous attribués à a promotion et non à leur groupe de TD + (ou TP, etc): vérifier le paramétrage de l'extraction du groupe et la + correspondance entre groupes emplois du temps et groupes ScoDoc. + +!!! note "Voir aussi" + + - Emplois du temps: [doc développeurs](DevAbsencesCalendrier.md) + - [Contacts](Contact.md)