Ajout Bonus Sport-culture WIP

docs/BonusMalus.md

@@ -0,0 +1,164 @@
+
+# Bonus/Malus
+
+Scodoc permet l'application de modificateurs de type bonus/malus sur les moyennes générales (formation non BUT) et/ou d'UE.
+Il existe deux mécanismes complémentaires pour cela:
+
+1. Le bonus sport/culture permet de calculer un modificateur sur la moyenne générale (formations non BUT) ou sur chacune des UE (BUT).
+La valeur du bonus est calulée à partir d'un note sur 20 et au moyen d'une formula propre à chaque IUT.
+
+2. Les modules de type Malus peuvent être créés pour tout ou partie des UE. La valeur du modificateur est spécifiée dans la (ou les) évaluation(s) déclarées dans ce module.
+On inscrira donc directement dans cette évaluation la valeur du malus (entre 0 et 20) ou du bonus (entre -20 et 0) souhaitée pour ce module.
+
+Le comparatif de ces deux mécanismes est détaillé dans le tableau ci-dessous:
+
+| Critère                            | Bonus Sport/culture              |  Module de Malus                           |
+|:-----------------------------------|:---------------------------------|:-------------------------------------------|
+|   Structure                        |  UE Spécifique                   | Module spécifique                          |
+|   Valeur du modificateur           |  Calculé à partir d'une note     | Saisie directe                             |
+|   Application sur toutes les UE    |  Automatique (avec seule UE)     | Autant de modules que d'UE modifiées       |
+|   Application sur une seule UE     |  Impossible                      | Un module par UE modifiée                  |                                   |
+|   Modification                     |  Bonus seulement                 | Malus ou Bonus                             |
+|   Affichage                        | Affichage du bonus et du détail  | Affichage du bonus/malus seulement         |
+|   Cumul de plusieurs modificateurs | Impossible                       | Déclarer une évaluation par type de modif. |
+
+## Mise en œuvre du bonus Sport/Culture
+
+L'étape [Intégration de la formule](#integration-de-la-formule) est à réalisé une fois pour toutes et pour tous les départements
+
+L'étape [Ajout d'UE et de module Sport/Culture](#ajout-due-et-de-module-sportculture) doit être faite lors de la conception ou lors d'une modification de programme, mais n'a pas a être réitérée lors de la création d'une nouvelle version d'un programe avec UE sport.
+
+L'étape [Application de l'UE Sport/Culture à un semestre](#application-de-lue-sportculture-a-un-semestre) doit être faite à la création d'un semestre mais n'a pas à être réitérée lors du clonage d'un semestre
+
+
+### Intégration de la formule
+
+Il faut tout d'abord régler ScoDoc pour utiliser la formule propre à votre établissement.
+
+Pour cela ml'administrateur du site (lui seul y est autorisé) doit aller sur la page de configuration de Scodoc (bandeau en haut de la page d'accueil)
+
+![configuration](screens/BonusMalus_01.png)
+
+puis section '`Calcul des "bonus" définis par l'établissement`' et sélectionner l'établissement dans le dans le menu déroulant.
+
+![choix-bonus-sport](screens/BonusMalus_02.png)
+
+Si l'établissement n'apparaît pas:
+
+1. L'item '`Bonus "Direct"`' permet de saisir directement la valeur du modificateur (après un calcul préalable hors scodoc)
+
+2. Vous pouvez demander la création de la formule spécifique à votre établissement sur le serveur discord en précisant:
+    * Le nom de votre établissement,
+    * l'extrait du règlement intérieur qui décrit cette bonification, (celui ci apparaîtra dans l'encadré explicatif)
+    * Quelques cas d'usages (pour les tests)
+
+### Ajout d'UE et de module Sport/Culture
+
+L'opération suivante consiste à ajouter dans le programme l'UE Sport/Culture dans le semestre visé. Une méthode parmi d'autre est:
+
+1. Entrer dans le semestre,
+2. activer le menu `SEMESTRE > Voir la formation...` (ceci permet d'aller dans LE programme associé au semestre),
+3. ajouter une UE,
+    Donner un titre (en y incluant le semestre visé - toutes les UE d'une formation doivent avoir leur propre nom et il y aura aussi probablement des UE sport pour les autres semestres)
+    Idem pour l'acronyme
+    Choisissez le Type `Sport/Culture (points bonus)`
+    Indiquez 0 ECTS (obligatoire bien que cette valeur n'ait pas d'importance)
+   ![ajout-UE-sport](screens/BonusMalus_03.png)
+4. ajouter un module à l'UE sport et l'attacher à l'UE Sport du semestre
+    Attention ! ce module est un module standard (pas un module de malus, ni une ressource, ni une SAÉ)
+   ![module-sport](screens/BonusMalus_04.png)
+
+### Application de l'UE Sport/Culture à un semestre
+
+La procédécure d'inclusion du bonus sport dans un semestre selon que le programme a été modifié avant ou après la création de ce semestre. 
+De plus le résultat de toutes les opérations décrites hormis la finalisation des inscriptions est conservé lors du clonage d'un semestre.
+
+#### Stratégies d'inscription
+
+Dans tous les cas de figure, l'objetif est d'intégrer le module sport au semestre et d'y inscrire au moins les étudiants qui en bénéficient.
+On a deux stratégies possibles:
+
+1. Inscription de tous les étudiants du semestres et attribuer la note `EXC`aux étudiants non concernés. à éviter car ces notes `EXC` apparaissent sur le bulletin. (inscription générale)
+2. N'inscrire que les étudiants concernés.(inscription sélective)
+    **Note**: si le bonus peut découler de plusieurs activités (par exemple sport et LV2) on peut tout de même être amené à placer des `EXC`
+
+#### Si le semestre avait déjà été créé 
+
+C'est en général le cas (On reçoit les notes de sport et on réalise que le bonus n'avait pas été prévu, donc on actualise)
+
+1. Entrer dans le semestre,
+
+2. activer le menu `SEMESTRE > Modifier le semestre`
+    ![modifier-le-semestre](screens/BonusMalus_05.png)
+
+3. Le module sport apparaît mais n'est pas activé
+    ![activation-module-sport](screens/BonusMalus_06.png)
+
+4. Activer le module et y affecter les étudiants selon la stratégie choisie (inscription générale: tous, inscription sélective: aucun) 
+
+4.Valider les modifications opérées
+
+#### Mise en place d'un nouveau semestre après modification du programme
+
+Dans ce cas de figure, le semestre est créé par défaut avec le module sport et l'ensemble des étudiants inscrits.
+
+#### Finaliser l'inscription des étudiants concernés (si inscription sélective):
+
+**Note**: cette finalisation peut être faite juste avant la saisie des notes de sport.
+
+1. Se placer dans le module sport
+   ![sélection-module-sport](screens/BonusMalus_07.png)
+
+2. Affiner les inscriptions en cliquant sur le lien de modification:
+   ![inscriptions-module-sport](screens/BonusMalus_08.png)
+
+#### Saisie des notes
+
+* Créer si besoin une évaluation dans le module sport
+
+* Saisir les notes des étudiants.
+    Sauf application du `Bonus "direct"` (cf. [Intégration de la formule](#integration-de-la-formule)), il s'agira d'un note traditionnelle (sur 20).
+
+##### Remarques
+
+* Le `Bonus "direct"` autorise des bonus de 0 à 20 mais plafonne les notes d'UE à 20 
+* On peut avoir plusieurs évaluations dans le module sport. 
+    Dans ce cas ScoDoc calcul la note de module comme habituellement (y compris en prenant en compte les éventuels coefficients),
+    puis calcul la valeur du bonus à partir de cette note de module. On ne peut donc pas 'cumuler' un bonus sport et un bonus LV2 par exemple.
+* On peut avoir plusieurs modules attachées à l'UE sport.
+    Dns ce cas, ScoDoc calcule le bonus qui produirait chacun de ces modules et les additionne. Dans ce cas, les bonus sont cumulables. Les notes d'UE restent plafonnées à 20.
+
+**Exemple**:
+On a déclaré dans une UE sport 2 modules:
+
+* `Sport` alimenté par 2 évaluations (Sport et Autre),
+
+* `LV2` alimenté par une seule évaluation
+
+Un étudiant participe aux deux activités et obtient les notes suivantes:
+![notes-sport-exemple](screens/BonusMalus_09.png)
+
+Le calcul effectué par ScoDoc est le suivant:
+
+* Calcul de la moyenne du module `Sport` ( 13.00 (coef. 1) et 10.00 (coef. 2)): résultat : 11.00 soit un bonus de 1 pt x 5% (calcul Villetaneuse) = 0.05 pts
+
+* Calcul de la moyenne `LV2`: 15.00 (une seule note) soit un bonus de 5 pts x 5% = 0.25 pts
+
+* Le bonus total sera donc de 0.30 pts
+
+* L'UE1 qui est de base à 19.80 sera donc amenée à 20 (plafond) grâce au bonus de 0.30
+  ![notes-sport-exemple-UE1](screens/BonusMalus_10.png)
+    Les autres UE bénficient du bonus de 0.30 pts
+
+
+
+
+### Affichages UE Sport/Culture
+
+## Mise en œuvre de modules de malus
+
+### Application d'un module Malus à un semestre
+
+### Affichage Malus/Bonus
+
+### Implémentation dans un semestre