From 85fdb885cc7b9b18b7b1d88b17477ce2f08adbda Mon Sep 17 00:00:00 2001 From: viennet Date: Fri, 26 Jan 2024 11:53:55 +0100 Subject: [PATCH] misc corrections --- docs/DevInternals.md | 40 ++++++------ docs/EmploisDuTemps.md | 2 +- docs/GuideDeveloppeurs.md | 4 +- docs/ScoDoc9API.md | 124 +++++++++++++++++++++++++++----------- docs/ScoDocApogee.md | 19 +++--- docs/TestsScoDoc.md | 6 +- 6 files changed, 127 insertions(+), 68 deletions(-) diff --git a/docs/DevInternals.md b/docs/DevInternals.md index dfb9a7dce..41f97a488 100644 --- a/docs/DevInternals.md +++ b/docs/DevInternals.md @@ -7,15 +7,15 @@ est normalement intégré à votre éditeur (VSCode et PyCharm sont deux choix judicieux). - outre Python, les principaux composants logiciels sont: - - [Flask](https://flask-sqlalchemy.palletsprojects.com/en/2.x/): le - framework Web, dont on utilise notamment: - - l'ORM [SQLAlchemy](https://www.sqlalchemy.org/) - - les templates [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/) - - [Postgresql](https://www.postgresql.org/) - - [Redis](https://redis.io/) cache persistant - - [NGINX](https://www.nginx.com/) serveur Web frontal - - [gunicorn](https://gunicorn.org/) WSGI HTTP server - - et bien sûr Linux (Debian 12 en 2023-2024) et systemd. + - [Flask](https://flask-sqlalchemy.palletsprojects.com/en/2.x/): le + framework Web, dont on utilise notamment: + - l'ORM [SQLAlchemy](https://www.sqlalchemy.org/) + - les templates [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/) + - [Postgresql](https://www.postgresql.org/) + - [Redis](https://redis.io/) cache persistant + - [NGINX](https://www.nginx.com/) serveur Web frontal + - [gunicorn](https://gunicorn.org/) WSGI HTTP server + - et bien sûr Linux (Debian 12 en 2023-2024) et systemd. ## Principaux objets @@ -29,9 +29,9 @@ Principales classes (les noms des classes Python sont en `CamelCase`). - Étudiants (classe `Identite`): nom, codes INE/NIP, etc - Formations: programmes pédagogiques, contenant - - Unités d'Enseignement (`UniteEns`); - - Matières et Modules (`Module`, avec son type standard, bonus, ressources - ou SAÉ). + - Unités d'Enseignement (`UniteEns`); + - Matières et Modules (`Module`, avec son type standard, bonus, ressources + ou SAÉ). - FormSemestre: instanciation d'une session de formation, avec un programme pédagogique donné (Formation), les dates de début et fin, des étudiants inscrits, des responsables, divers codes, et les ModuleImpl mis en œuvre. @@ -46,13 +46,13 @@ Principales classes (les noms des classes Python sont en `CamelCase`). Une vue ordinaire (Web) pourrait ressembler à cela. Noter la présence de décorateurs: - - `@scodoc` récupère le département (présent dans l'URL) et initialise quelques - trucs, notamment `g.scodoc_dept` (l'acronyme du département courant) et - `g.scodoc_dept_id` (l'id du dépt. courant). - - `@permission_required`: permet de contrôler l'accès, en se basant sur les - permissions définies dans la classe `Permission`. +- `@scodoc` récupère le département (présent dans l'URL) et initialise quelques + trucs, notamment `g.scodoc_dept` (l'acronyme du département courant) et + `g.scodoc_dept_id` (l'id du dépt. courant). +- `@permission_required`: permet de contrôler l'accès, en se basant sur les + permissions définies dans la classe `Permission`. -``` +```py @bp.route("/un_exemple") @scodoc @permission_required(Permission.EditFormation) @@ -66,8 +66,8 @@ def un_exemple(): # Effectuer au besoin un traitement resultat = ... # Afficher le résultat - return render_template( - "exemple_template.html", + return render_template( + "exemple_template.html", resultat=resultat, # par exemple formation=formation, ... # etc diff --git a/docs/EmploisDuTemps.md b/docs/EmploisDuTemps.md index ca0c994fa..2912947a3 100644 --- a/docs/EmploisDuTemps.md +++ b/docs/EmploisDuTemps.md @@ -88,7 +88,7 @@ On a ici: - 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`. +- identifiant de l'enseignant: ici `1234`, présent dans `SUMMARY`, `DESCRIPTION` et `X-ALT-DESC`. ## Extraction des identifiants: semestres, groupes, modules, enseignants diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index b2fbd54f0..a2e07d00e 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -86,7 +86,7 @@ Au besoin, mémo: - afficher les clés: `redis-cli KEYS '*'` -- `redis-cli TTL key` affiche le TTL d'un clé, -1 si infini. +- `redis-cli TTL key` affiche le TTL d'une clé, -1 si infini. - `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_), affiche toutes les 3 secondes. @@ -112,7 +112,7 @@ bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ain Puis soit vous installez les versions "officielles" (testées) ```bash - pip install -r requirements-3.9.txt + pip install -r requirements-3.9.txt ``` Soit vous prenez les versions les plus à jour disponibles. Une façon rapide de diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 0134dad29..bf4082422 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -87,7 +87,7 @@ Si vous êtes intéressé par le développement, voir *Autorise connexion via CAS si CAS est activé* dans leur formulaire de configuration. - * Si l'utilisateur est associé à un département (cas des comptes créés via l'interface Web), + * Si l'utilisateur est associé à un département (cas des comptes créés via l'interface Web), il ne pourra accéder à l'API que via une *route départementale*, c'est à dire une route comprenant l'acronyme de son département, de la forme `https://...//ScoDoc/DEPARTEMENT/api/...`. @@ -171,7 +171,7 @@ Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des systèmes, voir plus haut pour la même chose avec la commande `http`): ```bash -curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens +curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens ``` où `SERVEUR` est l'adresse (IP ou nom) de votre serveur. @@ -368,7 +368,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post- - **Exemple d'utilisation:** `/api/departements` - **Résultat:** Liste de tous les départements (visibles ou non). - **Exemple de résultat:** [departements.json](samples/sample_departements.json.md) - + #### **departements-ids** - **Méthode:** GET @@ -1042,8 +1042,10 @@ responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut * **Résultat:** Description du moduleimpl. * **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md) -#### **`moduleimpl-inscriptions`** +Note: la liste des `ModuleImpl` d'un `FormSemestre` peut être obtenue via +[formsemestre-programme](#formsemestre-programme). +#### **`moduleimpl-inscriptions`** * **Méthode:** GET * **Permission: `ScoView`** @@ -1053,6 +1055,59 @@ responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut * **Résultat:** Liste des inscriptions à ce moduleimpl. * **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl_inscriptions.json.md) +#### **`moduleimpl-evaluations`** + +* **Méthode:** GET +* **Permission: `ScoView`** +* **Paramètres:** `moduleimpl_id` +* **Routes:** `/moduleimpl//evaluations` +* **Exemple d'utilisation:** `/ScoDoc/api/moduleimpl/1/evaluations` +* **Résultat:** Liste ordonnée des évaluations dans ce moduleimpl. + +#### **`moduleimpl-notes`** + +* **Méthode:** GET +* **Permission: `ScoView`** +* **Paramètres:** `moduleimpl_id` +* **Routes:** `/moduleimpl//notes` +* **Exemple d'utilisation:** `/ScoDoc/api/moduleimpl/1/notes` +* **Résultat:** Liste des notes dans ce moduleimpl. + +Exemple en formation classique: + +```json + [ + { + "etudid": 18270, + "nom": "Ball", + "prenom": "Jane", + "38083": 11.0, // Note evaluation d'id 38083 + "38084": 14.5, // Note evaluation 38084 + "moymod": 12.75 // Moyenne au module + }, + ... + ] +``` + +Exemple de résultat en BUT: + +```json + [ + { + "etudid": 17776, // code de l'étudiant + "nom": "DUPONT", + "prenom": "Luz", + "38411": 16.0, // Note dans l'évaluation d'id 38411 + "38410": 15.0, + "moymod": 15.5, // Moyenne INDICATIVE module + "moy_ue_2875": 15.5, // Moyenne vers l'UE 2875 + "moy_ue_2876": 15.5, // Moyenne vers l'UE 2876 + "moy_ue_2877": 15.5 // Moyenne vers l'UE 2877 + }, + ... + ] +``` + ### **API Partition** #### Structure Partition @@ -1207,7 +1262,7 @@ d'un autre). * **Data:** `{ "permissions" : [ permission, ... ] }` * **Routes:** `/role/create/` * **Exemple d'utilisation:** `/role/create/LaveurDecarreaux` - + > `{ "permissions" : [ 'ScoView', 'UsersView' ] }` * **Résultat:** Crée un nouveau rôle, avec les permissions indiquées. @@ -1229,7 +1284,7 @@ d'un autre). * **Data:** `{ "permissions" : [ permission, ... ] }` * **Routes:** `/role/edit/` * **Exemple d'utilisation:** `/role/create/LaveurDecarreaux` - + > `{ "name" : "LaveurDeVitres", "permissions" : [ 'ScoView' ] }` * **Résultat:** Modifie le rôle: son nom et/ou ses permissions. @@ -1398,15 +1453,15 @@ mais pas JSON compliant à cause des `NaN`. (format court spécial BUT, disponible en format PDF seulement). * format `json` ou `pdf` (`json` par défaut, ajoutez `/pdf` pour la version pdf) - + (*à vérifier*) Pour les formations classiques (toutes sauf BUT), les bulletins JSON peuvent ou non indiquer les matières. Par défaut (version `long`), il est structuré en `UEs / modules`. - + Les notes moyennes de matières ne sont calculées que si l'option "*Afficher les matières sur les bulletins*" est activée pour le formsemestre considéré (sinon, la note vaut toujours "*nd*"). ` - + Les versions PDF sont par défaut identiques à celles servies dans ScoDoc. Avec l'option `/pdf/nosig`, les signatures en fin de bulletin sont omises. @@ -1424,13 +1479,13 @@ mais pas JSON compliant à cause des `NaN`. * **Routes:** `/formsemestre//programme` * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme` * **Résultat:** Retourne la structure d'un formsemestre sous 5 entrées d'un dictionnaire: - + * **`ues`**: liste des UEs * **`ressources`**: liste des ressources (BUT) * **`saes`**: liste des SAÉs (BUT) * **`modules`**: liste des modules classiques (DUT ou sport/culture) * **`malus`**: listes des modules de type bonus/malus. - + * **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md) #### **formsemestre-resultats** @@ -1561,15 +1616,15 @@ valeurs numériques mais pas JSON compliant à cause des `NaN`. * **Permission: `ScoSuperAdmin`** * **Paramètres:** Aucun * **Route :** - + * `/departement//logos` * `/departement/id//logos` - + * **Exemple d'utilisation :** - + * `/departement//logos` * `/departement/id//logos` - + * **Résultat :** Liste des noms des logos définis pour le département visé qui peut être désigné par son id ou par son acronyme (selon la forme de la route). * **Exemple de résultat:** [departement-logos.json](samples/sample_departement-logos.json.md) @@ -1582,10 +1637,10 @@ valeurs numériques mais pas JSON compliant à cause des `NaN`. * `/departement//logo/` * `/departement/id//logo/` * **Exemple d'utilisation:** - + * `/ScoDoc/api/departement/MMI/logo/header` * `/ScoDoc/api/departement/id/3/logo/header` - + * **Résultat :** l'image (format png ou jpg) * **Exemple de résultat:** [departement-logo.json](samples/sample_departement-logo.json.md) @@ -1626,7 +1681,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Méthode:** GET * **Permission: `ScoView`** -* **Paramètres:** +* **Paramètres:** * `etudid` * `nip` * `ine` @@ -1658,7 +1713,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Méthode:** GET * **Permission: `ScoView`** -* **Paramètres:** +* **Paramètres:** * `etudid` * `nip` * `ine` @@ -1767,7 +1822,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. ```json [ - { + { "etudid":, "date_debut": , @@ -1793,7 +1848,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Méthode:** POST * **Permission: `ScoAbsChange`** -* **Paramètres:** +* **Paramètres:** * `etudid` * `nip` * `ine` @@ -1901,15 +1956,16 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. | attribut | type | commentaire | | :----------- | :------------- | :------------------------------------------------------------ | -| *justif_id* | int | identifiant unique | -| *etudid* | int | identifiant unique de l'étudiant concerné par le justificatif | -| *date_debut* | string | date ISO du début de la période du justificatif | -| *date_fin* | string | date ISO de la fin de la période du justificatif | -| *etat* | string | état du justificatif ( attente, valide, non_valide, modifie) | -| *raison* | string ou null | explication du justificatif si présente | -| *fichier* | string | identifiant de l'archivage des fichiers | -|*user_id* | int or null | identifiant de l'utilisateur ayant créé le justificatif | -| *entry_date* | string | date ISO de l'entrée du justificatif | +| *justif_id* | int | identifiant unique | +| *etudid* | int | identifiant unique de l'étudiant concerné par le justificatif | +| *date_debut* | string | date ISO du début de la période du justificatif | +| *date_fin* | string | date ISO de la fin de la période du justificatif | +| *etat* | string | état du justificatif ( attente, valide, non_valide, modifie) | +| *raison* | string ou null | explication du justificatif si présente | +| *fichier* | string | identifiant de l'archivage des fichiers | +| *user_id* | int or null | id de l'utilisateur ayant créé le justificatif | +| *user_name* | str ou null | login de l'utilisateur ayant créé le justificatif | +| *entry_date* | string | date ISO de l'entrée du justificatif | #### **justificatif** @@ -1925,7 +1981,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Méthode:** GET * **Permission: `ScoView`** -* **Paramètres:** +* **Paramètres:** * `etudid` * `nip` * `ine` @@ -1953,7 +2009,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Méthode:** POST * **Permission: `ScoAbsChange`** -* **Paramètres:** +* **Paramètres:** * `etudid` * `nip` * `ine` @@ -1973,7 +2029,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. > Un fichier justificatif peut être importé dans scodoc après avoir créer l'objet justificatif voir [importer un justificatif](FichiersJustificatifs.md#importer-un-fichier) -* **Routes:** +* **Routes:** * `/justificatif//create` * `/justificatif/etudid//create` * `/justificatif/nip//create` @@ -2094,7 +2150,7 @@ Cette API est disponible à partir de ScoDoc 9.6 et remplace les absences. * **Paramètres:** `justif_id` * **Routes:** `/justificatif//list` * **Exemple d'utilisation:** `/api/justificatif/1/list` -* **Résultat:** +* **Résultat:** ```json { "filenames" : [ diff --git a/docs/ScoDocApogee.md b/docs/ScoDocApogee.md index 67c391633..5d1592914 100644 --- a/docs/ScoDocApogee.md +++ b/docs/ScoDocApogee.md @@ -59,10 +59,10 @@ Par ailleurs, chaque semestre est associé à une étape Apogée (VET), et, en option, à un code d'élément annuel et un code d'élément semestre. Pour le deuxième semestre 5S2) du DUT R&T Villetaneuse, cela donne: -* Code étape (VET): `V1RT` (l'étape est annuelle) -* Code année (ELP): `VRT1A` (cet élément contiendra exactement les mêmes +- Code étape (VET): `V1RT` (l'étape est annuelle) +- Code année (ELP): `VRT1A` (cet élément contiendra exactement les mêmes informations que le VET) -* Code semestre (ELP): `VRTW2` (la note de ces élément sera la moyenne générale +- Code semestre (ELP): `VRTW2` (la note de ces élément sera la moyenne générale du semestre) Notez que la nomenclature est variable et souvent peu prévisible, même au sein @@ -97,13 +97,13 @@ Apogée. ### Précautions à prendre et remarques diverses -* **Codage des fichiers**: Apogée (du moins à l'Université Paris 13) exporte et +- **Codage des fichiers**: Apogée (du moins à l'Université Paris 13) exporte et importe des fichiers maquettes codés en latin-1 (ISO-8859-1). Les web services (portail Apogée), tout comme ScoDoc, travaillent en utf8. Pour faciliter les échanges, les fichiers maquettes importés et exportés de ScoDoc sont en latin-1 (sauf celui reçu du portail Apogée). -* **Format des nombres** (notes): les notes sont calculées par ScoDoc en haute +- **Format des nombres** (notes): les notes sont calculées par ScoDoc en haute précision, mais affichées avec deux chiffres après la virgule dans l'application (ce qui donne 4 chiffres significatifs, par exemple *12,34*, soit une précision de un pour dix mille, ce qui semble plus que suffisant @@ -118,14 +118,15 @@ Apogée. ![Config. précision exports Apogée](screens/apo-precision.png) -* **Étudiants démissionnaires**: on note les démissions dans ScoDoc (sur la fiche +- **Étudiants démissionnaires**: on note les démissions dans ScoDoc (sur la fiche de l'étudiant), mais en général pas dans Apogée. Le résultat Apogée sera DEF. Ne jamais désinscrire du semestre ScoDoc les démissionnaires ! -* Exports à **mi-année** (après jurys de janvier): Si `periode==1` (jury de janvier), +- Exports à **mi-année** (après jurys de janvier): Si `periode==1` (jury de janvier), alors l'étape Apogée (annuelle) n'est pas terminée. Donc on ne remplit pas le code annuel (`elt_annee_apo`, comme `VRT1A`) ni le `VET` sauf si l'année est en fait validée grâce à un semestre de l'an précédent: (voir r1525) - * jury de fin de S1: si le S2 est validé; - * jury de fin de S3: si le S4 est validé. + + - jury de fin de S1: si le S2 est validé; + - jury de fin de S3: si le S4 est validé. diff --git a/docs/TestsScoDoc.md b/docs/TestsScoDoc.md index 9bd249890..c7253e332 100644 --- a/docs/TestsScoDoc.md +++ b/docs/TestsScoDoc.md @@ -42,7 +42,7 @@ première erreur, et `--pdb` lance directement le debugger sur l'erreur. Ainsi, ```bash -pytest --pdb -x tests/api/test_api_departements.py +pytest --pdb -x tests/api/test_api_departements.py ``` lancera un test en mode "interactif", utile pour les mises au point. @@ -78,7 +78,7 @@ même hôte, donc `http://localhost:8678`. Lancement: ```bash -/opt/scodoc/tools/fakeportal/fakeportal.py +/opt/scodoc/tools/fakeportal/fakeportal.py ``` ## Tests de l'API ScoDoc9 @@ -121,6 +121,8 @@ l'initialiser et la peupler de données fictives pour les tests. flask run --host 0.0.0.0 --debug ``` +Le script `tests/api/start_api_server.sh -p 5555` fait tout cela pour vous ! + ### Configuration du client de test API 1. Copier le fichier `scodoc/tests/api/dotenv_exemple` dans