Apps/WEI.md

@@ -154,7 +154,7 @@ Première règle : on ne supprime rien (sauf si vraiment c'est du mauvais boulot
 
 ##### WEISurvey
 
- Une classe héritant de `wei.forms.surveys.base.WEISurvey`, comportant les éléments suivants :
+Une classe héritant de `wei.forms.surveys.base.WEISurvey`, comportant les éléments suivants :
 
   * Une fonction `get_year(cls)` indiquant l'année du WEI liée au sondage
   * Une fonction `get_survey_information_class(cls)` indiquant la classe héritant de `wei.forms.surveys.base.WEISurveyInformation` contenant les données du sondage (voir plus bas)
@@ -173,4 +173,33 @@ Nativement, la classe `WEISurvey` comprend les informations suivantes :
   * `save(self)`, enregistre les informations du sondage dans l'objet `registration` associé, qui est ensuite enregistré en base de données.
   * `select_bus(self, bus)`, choisit le bus `bus` comme bus préféré. Cela à pour effet de remplir les champs `selected_bus_pk` et `selected_bus_name` par les identifiant et nom du bus, et `valid` à `True`.
 
-Pour information, `WEISurvey.__init__` prend comme paramètre l'inscription `registration`, et récupère les informations du sondage converties en dictionnaire Python puis en objet `WEISurveyInformation`
\ No newline at end of file
+Pour information, `WEISurvey.__init__` prend comme paramètre l'inscription `registration`, et récupère les informations du sondage converties en dictionnaire Python puis en objet `WEISurveyInformation`.
+
+##### WEISurveyInformation
+
+Une classe héritant de `wei.forms.surveys.base.WEISurveyInformation`, comportant les informations brutes du sondage. Le champ `information_json` de `WEIRegistration` est traduit en dictionnaire Python depuis JSON, puis les différents champs de WEISurveyInformation sont mis à jour depuis ce dictionnaire. Il n'y a rien de supplémentaire à ajouter, tout est déjà géré.
+
+Ainsi, plutôt que de modifier laborieusement le champ JSON, préférez utiliser cette classe. Attention : pour des soucis de traduction facile, merci de n'utiliser que des objets primitifs (nombres, chaînes de caractère, booléens, listes, dictionnaires simples). Les instances de modèle sont à proscrire, préférez stocker l'identifiant et créer une fonction qui récupère l'instance à partir de l'identifiant.
+
+Attention, 3 noms sont réservés : `selected_bus_pk`, `selected_bus_name` et `valid`, qui représentent la sortie de l'algorithme de répartition.
+
+À noter que l'interface de validation des inscriptions affiche les données brutes du sondage.
+
+##### WEISurveyAlgorithm
+
+Une classe héritant de `wei.forms.surveys.base.WEISurveyAlgorithm`, qui contient 2 fonctions :
+
+  * `get_survey_class(cls)`, qui renvoie la classe du `WEISurvey` associée à l'algorithme.
+  * `run_algorithm(self)`, la fonction importante. Cette fonction n'est supposée n'être exécutée qu'une seule fois par WEI, et a pour cahier des charges de prendre chaque sondage d'un 1A et d'appeler la fonction `WEISurvey.select_bus(bus)`, en décidant convenablement de quel bus le membre doit prendre. C'est bien sûr la fonction la plus complexe à mettre en oeuvre. Tout est permis tant qu'à la fin tout le monde a bien son bus.
+
+Deux fonctions sont implémentées nativement :
+
+  * `get_registrations(cls)`, renvoie un `QuerySSet` vers l'ensemble des inscriptions au WEI concerné des 1A.
+  * `get_buses(cls)`, renvoie l'ensemble des bus du WEI concerné.
+
+
+La dernière chose à faire est dans le fichier `apps/wei/forms/surveys/__init__.py`, où la classe `CurrentSurvey` est à mettre à jour. Il n'y a rien d'autre à changer, tout le reste est normalement géré pour qu'il n'y ait pas nécessité d'y toucher.
+
+Le lancement de l'algorithme se fait en ligne de commande, via la commande `python manage.py wei_algorithm`. Elle a pour unique effet d'appeler la fonction `run_algorithm` décrite plus tôt. Une fois cela fait, vous aurez noté qu'il n'a pas été évoqué d'adhésion. L'adhésion est ensuite manuelle, l'algorithme ne fournit qu'une suggestion.
+
+Cette structure, complexe mais raisonnable, permet de gérer plus ou moins proprement la répartition des 1A, en limitant très fortement le hard code. Ami nouveau développeur, merci de bien penser à la propreté du code :) En particulier, on évitera de mentionner dans le code le nom des bus, et profiter du champ `information_json` présent dans le modèle `Bus`.
\ No newline at end of file