Début doc sur emplois du temps

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

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.
 
 

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)