misc corrections

This commit is contained in:
Emmanuel Viennet 2024-01-26 11:53:55 +01:00
parent 4c58b40eef
commit 85fdb885cc
6 changed files with 127 additions and 68 deletions

View File

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

View File

@ -88,7 +88,7 @@ On a ici:
- 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`.
- identifiant de l'enseignant: ici `1234`, présent dans `SUMMARY`, `DESCRIPTION` et `X-ALT-DESC`.
## Extraction des identifiants: semestres, groupes, modules, enseignants

View File

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

View File

@ -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
```
`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/<int:moduleimpl_id>/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/<int:moduleimpl_id>/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/<str:role_name>`
* **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/<str:role_name>`
* **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/<int:formsemestre_id>/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/<string:dept>/logos`
* `/departement/id/<int:departement_id>/logos`
* **Exemple d'utilisation :**
* `/departement/<string:dept>/logos`
* `/departement/id/<int: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/<string:dept>/logo/<string:nom>`
* `/departement/id/<int:departement_id>/logo/<string:nom>`
* **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":<int>,
"date_debut": <string>,
@ -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/<int:etudid>/create`
* `/justificatif/etudid/<etudid>/create`
* `/justificatif/nip/<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/<int:justif_id>/list`
* **Exemple d'utilisation:** `/api/justificatif/1/list`
* **Résultat:**
* **Résultat:**
```json
{
"filenames" : [

View File

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

View File

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