Début doc sur emplois du temps

This commit is contained in:
Emmanuel Viennet 2023-12-24 10:05:05 -03:00
parent 94d0644b9f
commit 60f3ef841e
3 changed files with 192 additions and 3 deletions

View File

@ -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)<br/>Enseignant : 1234 - M. VIENNET EMMANUEL<br/>Promotion : V2ROM - BUT2 RT pa. ROM<br/>TD : Groupe 1<br/>Salle : P202 CRIT - P202 CRIT.RESEAUX<br/>Mémo : TP2 GPR1<br/>
END:VEVENT
```
On a ici:
- identifiant de la formation: dans le nom du fichier calendrier (ici `V2CYB.ics`);
- identifiant du groupe: dans `SUMMARY`, `* - <groupe>`
- 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)

View File

@ -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.

62
docs/EmploisDuTemps.md Normal file
View File

@ -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)