Extract documentation from the Gitlab wiki and convert it to reStructuredText

docs/apps/note/consumptions.rst

@@ -0,0 +1,88 @@
+Consommations
+=============
+
+Affichage
+---------
+
+La page de consommations est principalement une communication entre l'`API <../api>`_ et la page en JavaScript.
+Elle est disponible à l'adresse ``/note/consos/``, et l'onglet n'est visible que pour ceux ayant le droit de voir au
+moins un bouton. L'affichage, comme tout le reste de la page, est géré avec Boostrap 4.
+Les boutons que l'utilisateur a le droit de voir sont triés par catégorie.
+
+## Sélection des consommations
+
+Lorsque l'utilisateur commence à taper un nom de note, un appel à l'API sur la page ``/api/note/alias`` est fait,
+récupérant les 20 premiers aliases en accord avec la requête. Quand l'utilisateur survole un alias, un appel à la page
+``/api/note/note/<NOTE_ID>/`` est fait pour récupérer plus d'infos sur la note telles que le solde, le vrai nom de la
+note et la photo, si toutefois l'utilisateur a le droit de voir ceci.
+
+L'utilisateur peut cliquer sur des aliases pour ajouter des émetteurs, et sur des boutons pour ajouter des consommations.
+Cliquer dans la liste des émetteurs supprime l'élément sélectionné.
+
+Il ya deux possibilités pour faire consommer des adhérents :
+  - En mode **consommation simple** (mode par défaut), les consommations sont débitées dès que émetteurs et consommations
+    sont renseignées.
+  - En mode **consommation double**, l'utilisateur doit cliquer sur "Consommer !" pour débiter toutes les consommations.
+
+Débit des consommations
+-----------------------
+
+Pour débiter toutes les consommations, pour chaque source et chaque bouton, une requête POST est faite à l'API sur
+l'adresse ``/api/note/transaction/transaction/`` avec le contenu suivant :
+
+.. code:: json
+
+    {
+        "quantity": "<QUANTITÉ>",
+        "amount": "<PRIX_EN_CENTIMES>",
+        "reason": "<NOM_DU_BOUTON> (<CATÉGORIE_DU_BOUTON>)",
+        "valid": true,
+        "polymorphic_ctype": 42,
+        "source": "<ID_DE_NOTE_SOURCE>",
+        "destination": "<ID_DE_NOTE_DESTINATION>",
+        "template": "<ID_BOUTON>",
+        "category": "<ID_CATÉGORIE>",
+        "resourcetype": "RecurrentTransaction"
+    }
+
+Par exemple, pour 3 cocas à 1.10 € (catégorie Soft, numéro 1), bouton numéro 1, à destination de la note Kfet (id 6)
+depuis la note 7, la requête suivante est envoyée :
+
+.. code:: json
+
+    {
+        "quantity": 3,
+        "amount": 110,
+        "reason": "Coca (Soft)",
+        "valid": true,
+        "polymorphic_ctype": 42,
+        "source": 7,
+        "destination": 6,
+        "template": 1,
+        "category": 1,
+        "resourcetype": "RecurrentTransaction"
+    }
+
+Le ``42`` dans ``"polymorphic_ctype": 42`` correspond à l'identifiant du modèle `RecurrentTransaction` dans la table
+des types. Il vaut `42` lors de la rédaction de cette documentation, mais pourra varier à l'avenir, et sera toujours
+à jour : la valeur n'est pas "hard-codée".
+
+Si une erreur survient lors de la requête (droits insuffisants), un message apparaîtra en haut de page.
+Dans tous les cas, tous les champs sont réinitialisés.
+
+L'historique et la balance de l'utilisateur sont ensuite mis à jour via jQuery, qui permet de recharger une partie de page Web.
+
+Validation/dévalidation des transactions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Il est possible aussi de (dé)valider une transaction en cliquant sur le symbole de validation. Lorsqu'un clic est fait,
+une requête PATCH est faite à l'API sur l'adresse ``/api/note/transaction/transaction/<TRANSACTION_ID>/`` de la forme :
+
+.. code:: json
+
+    {
+        "resourcetype": "RecurrentTransaction",
+        "valid": false
+    }
+
+L'historique et la balance sont ensuite rafraîchis. Si une erreur survient, un message apparaîtra.

docs/apps/note/index.rst

@@ -0,0 +1,23 @@
+Application Note
+================
+
+L'application ``note`` gère tout ce qui est en lien avec les flux d'argent et les notes (balances) des utilisateurs.
+
+La gestion des consommations s'effectue principalement via la page dédiée, dont le fonctionnement est expliqué
+dans la page `Consommations <consumptions>`_.
+
+Le fonctionnnemnent des  crédit/débit de note (avec le "monde extérieur" donc avec de l'argent réel) ainsi que les
+transferts/dons entre notes est détaillé sur la page `Transferts <transactions>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Note
+
+   consumptions
+   transfers
+
+Graphe
+------
+
+.. image:: /_static/img/graphs/note.svg
+   :alt: Graphe de l'application note

docs/apps/note/transfers.rst

@@ -0,0 +1,34 @@
+Transferts
+==========
+
+Affichage
+---------
+
+L'interface de la page de transferts est semblable à celles des consommations, et l'auto-complétion de note est géré de
+la même manière. La page se trouve à l'adresse ``/note/transfer/``. La liste des 20 transactions les plus récentes que
+l'utilisateur a le droit de voir est également présente.
+
+Des boutons ``Don``, ``Transfert``, ``Crédit``, ``Retrait`` sont présents, représentant les différents modes de
+transfert. Pour chaque transfert, un montant et une description sont attendus.
+
+Onglet transferts
+-----------------
+
+Cet onglet est visible par tout le monde. Il permet d'effectuer un transfert depuis plusieurs notes vers d'autres notes,
+à l'image des consommations doubles. Si une erreur survient (permission insuffisante), un message d'erreur apparaîtra.
+
+Onglets Crédit et retrait
+-------------------------
+
+Ces onglets ne sont visibles que par ceux qui ont le droit de voir les ``SpecialNote``.
+
+Une boîte supplémentaire apparaît, demandant en plus de la note, du montant et de la raison le nom, le prénom et
+la banque de la personne à recharger/retirer. Lorsqu'une note est sélectionnée, les champs "nom" et "prénom" sont
+remplis automatiquement. Par ailleurs, seule une note peut être choisie.
+
+Transfert
+---------
+
+Les transferts se font à nouveau via l'API, avec le même schéma que précédemment, en remplaçant
+``RecurrentTransaction`` par ``Transaction`` simplement pour don/transfert, et ``SpecialTransaction`` pour
+crédit/retrait, en adaptant le champ ``polymorphic_ctype``.