docs/BonusMalus.md

@@ -0,0 +1,235 @@
+
+# Composants de 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:
+
+## Les bonus sport/culture
+
+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.
+
+## Les modules de malus
+
+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 d'un malus (entre 0 et 20) ou d'un bonus (entre -20 et 0) souhaitée pour ce module.
+Les modules de malus sont essentiellement prévus pour permettre d'affecter un malus (généralement un malus pour absences) spécifier dans les réglements locaux.
+
+* A la différence du bonus sport/culture, ces modifications ne portent pas uniformément sur la totalité des UE.
+    Si on veut que le malus s'applique à plusieurs UE, il faudra créer plusieurs modules de malus.
+
+* De plus, aucune formule n'est implémentée et on saisira directement la valeur du malus (ou bonus)
+
+* Les valeurs saisies ne sont pas affichées telles quelles sur les bulletins. Seule la somme des modificateurs est affichée (à coté de l'UE sur laquelle elle porte)
+
+* Il est possible de décrire plusieurs évaluations (donc plusieurs saisies) qui sont cumulatives
+
+* Le modificateur saisi peut être négatif (et donnera alors un bonus); l'affichage est mis à jour en conséquence.
+    C'est donc la possibilité d'inclure un bonus donc la valeur n'est pas calculée par la formule configurée (cf. [Intégration de la formule](#intégration-de-la-formule)).
+
+Le résumé de ce comparatif est détaillé dans le tableau ci-dessous:
+
+| Critère                              | Bonus Sport/culture                               | Module de Malus                            |
+|:-------------------------------------|:--------------------------------------------------|:-------------------------------------------|
+| **Structure**                        | UE Spécifique et modules (type standard) attachés | Module spécifique (type malus)             |
+| **Valeur du bonus/malus**            | 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** | voir [les remarques](#remarques)                  | Déclarer une évaluation par type de modif. |
+
+## Procédures
+
+L'étape [Intégration de la formule](#intégration-de-la-formule) est à réalisé une fois pour toutes et pour tous les départements, seulement si le bonus sport/culture est utilisé.
+
+L'étape [Ajout d'UE et de module Sport/Culture](#ajout-due-sportculture-etou-de-module-de-malus) doit être faite lors de la conception d'un 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 à un semestre](#application-à-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 Sport/culture et/ou de module de malus
+
+#### Bonus sport/culture
+
+L'opération suivante consiste à ajouter dans le programme l'UE Sport/Culture dans le semestre visé. Une méthode parmi d'autres 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 'Sport/Culture',
+    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)
+
+#### Ajout de module Malus
+
+1. Entrer dans le semestre,
+
+2. activer le menu `SEMESTRE > Modifier le semestre`
+   ![modifier-le-semestre](screens/BonusMalus_05.png)
+
+A ce niveau, vous pouvez soit:
+
+* ajouter les modules malus en une seule fois pour toutes les UE par le lien `ajouter un module de malus dans chaque UE su S...`
+  ![ajout-global-malus](screens/BonusMalus_11.png)
+
+* Ou, si une des UE ne demande pas l'application d'un malus, ajouter seulement les modules nécessaires en les créant un par un:
+  ![ajout-simple-malus](screens/BonusMalus_12.png)
+  en précisant le type `Malus`  et en l'attachant à l'UE concernée.
+  ![ajout-simple-malus-détail](screens/BonusMalus_13.png)
+
+### Application à un semestre
+
+Quel que soit le type de bonus utilisé, le semestre concerné doit  intégrer le ou les modules créés précédemment,
+que ce soit les modules appartenant à l'UE sport/culture ou les modules de malus.
+
+Si la création du semestre est postérieur à la modification du programme,
+ou si le semestre résulte du clonage d'un semestre déjà configuré,
+les éléments de bonus/malus sont déjà pris en compte et on peut passer directement à la partie [inscription des étudiants](finaliser-linscription-des-étudiants-concernés-si-inscription-sélective)
+
+Dans le cas contraire (le bonus n'avait pas été prévu au départ et doit être ajouté en cours de semestre) la manipulation suivante permet lapplication des éléments de bonus/malus aux au semstre existant:
+
+#### Stratégies d'inscription
+
+Dans tous les cas de figure, l'objectif est d'inscrire aux modules de bonus/malus 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 pour le bonus sport/culture 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 sport/culture peut résulter de plusieurs activités (par exemple sport et LV2) on peut tout de même être amené à placer des `EXC`
+
+#### Application des modifications du programme à un semestre existant
+
+1. Entrer dans le semestre,
+
+2. activer le menu `SEMESTRE > Modifier le semestre`
+   ![modifier-le-semestre](screens/BonusMalus_05.png)
+
+3. Les éléments de bonus/malus apparaissent mais ne sont pas activés
+   ![activation-module-sport](screens/BonusMalus_06.png)
+
+4. Activer les modules utilisés 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
+
+#### 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 bonus/malus
+  ![sélection-module-sport](screens/BonusMalus_07.png)
+  ou
+  ![sélection-module-malus](screens/BonusMalus_14.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 courant
+
+* Saisir les notes des étudiants.
+  * Pour un bonus sport/culture
+    Sauf application du `Bonus "direct"` (cf. [Intégration de la formule](#intégration-de-la-formule)), il s'agira d'un note traditionnelle (sur 20).
+  * Pour un module de malus
+    Saisir directement la valeur du malus (pour que l'étudiant bénéficie d'un bonus, entrer une valeur négative)
+
+#### 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) par ce biais.
+* On peut avoir plusieurs modules attachées à l'UE sport.
+    Dans ce cas, ScoDoc calcule le bonus qui produirait chacun de ces modules et les additionne. Dans ce cas, les bonus sont cumulés, mais:
+
+  * Cette méthode n'est applicable que si les formules de calcul de chacun des bonus cumulés sont identiques.
+
+  * 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énéficient du bonus de 0.30 pts
+
+----------------------------------------------------------------------------------------------------------------------------------------------
+La rubrique suivante n'est peut être pas utile.
+
+## Affichages
+
+La forme que prend cet affichage varie en fonction des circonstances:
+
+* Aucun bonus/malus
+
+* Cas 1: Bonus sport/culture seulement
+
+* Cas 2: Malus
+
+* Cas 3: Malus négatif (traité comme bonus)
+
+Les bonus/malus sont affichés principalement sur:
+
+### La table récapitulative des notes
+
+Deux colonnes sont affichées pour chaque UE. pour indiquer le bonus sport/culture d'une part et le malus (ou bonus complémentaire) comme indiqué ci-dessous
+![Table-des-notes](screens/BonusMalus_15.png)
+
+### le relevé de notes web d'un étudiant (y compris sur la passerelle)
+
+La description de l'UE inclut la valeur des bonus et malus (même si nulle) comme indiqué dans les exemple ci-dessous.
+La moyenne avant altération figure en bas tandis que la valeur supérieure (en gras) affiche la moyenne après bonus/malus (plafonnée si besoin):
+![relevé-web-cas1](screens/BonusMalus_16.png)
+![relevé-web-cas2](screens/BonusMalus_17.png)
+![relevé-web-cas3](screens/BonusMalus_18.png)
+![relevé-web-cas4](screens/BonusMalus_19.png)
+
+### le relevé de notes en version pdf
+![relevé-pdf-cas1](screens/BonusMalus_20.png)
+![relevé-pdf-cas2](screens/BonusMalus_21.png)
+![relevé-pdf-cas3](screens/BonusMalus_22.png)
+![relevé-pdf-cas4](screens/BonusMalus_23.png)