yvv/decision
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sprint 5 : integration et production -- securite, performance, API publique, documentation

Browse Source 
Backend: rate limiter, security headers, blockchain cache service avec RPC,
public API (7 endpoints read-only), WebSocket auth + heartbeat, DB connection
pooling, structured logging, health check DB. Frontend: API retry/timeout,
WebSocket auth + heartbeat + typed events, notifications toast, mobile hamburger
+ drawer, error boundary, offline banner, loading skeletons, dashboard enrichi.
Documentation: guides utilisateur complets (demarrage, vote, sanctuaire, FAQ 30+),
guide deploiement, politique securite. 123 tests, 155 fichiers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
2026-02-28 15:12:50 +01:00
parent 3cb1754592
commit 403b94fa2c
31 changed files with 4472 additions and 356 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
docs/content/user/5.voting.md
View File

@@ -19,20 +19,142 @@ Chaque votant choisit **Pour** ou **Contre**. Le seuil est calcule par la formul
Chaque votant exprime son opinion sur une echelle a 6 niveaux :
| Niveau | Label | Comptage |
| ------ | ------------- | --------------- |
| 0 | CONTRE | Negatif |
| 1 | PAS DU TOUT | Negatif |
| 2 | PAS D'ACCORD | Negatif |
| 3 | NEUTRE | Positif |
| 4 | D'ACCORD | Positif |
| 5 | TOUT A FAIT | Positif |
| Niveau | Label | Signification | Comptage |
| ------ | ------------- | --------------------------------------------------- | -------- |
| 0 | CONTRE | Opposition totale et ferme | Negatif |
| 1 | PAS DU TOUT | Desaccord fort, points essentiels non remplis | Negatif |
| 2 | PAS D'ACCORD | Desaccord modere, des reserves importantes | Negatif |
| 3 | NEUTRE | Ni pour ni contre, ou acceptation sans enthousiasme | Positif |
| 4 | D'ACCORD | Approbation avec eventuellement des reserves mineures | Positif |
| 5 | TOUT A FAIT | Approbation totale et enthousiaste | Positif |
Le vote est adopte si les niveaux positifs (3, 4, 5) representent au moins 80% des votes et qu'un nombre minimum de participants est atteint.
Le vote nuance est adopte si les niveaux positifs (3, 4, 5) representent au moins **80%** des votes et qu'un nombre minimum de participants est atteint (par defaut 59).
## Comment voter -- Vote binaire
### Quand utiliser le vote nuance ?
### Etape par etape
Le vote nuance est recommande pour :
- Les textes longs comportant de nombreux articles (les votants peuvent exprimer un accord partiel).
- Les decisions ou la nuance est importante (budget, parametre technique).
- Les cas ou il est utile de mesurer le degre d'adhesion, pas seulement le resultat binaire.
## La formule de seuil expliquee simplement
### L'analogie de l'inertie
Imaginez un gros rocher pose au sommet d'une colline. Pour le deplacer, il faut une force considerable : c'est l'**inertie**. Dans Glibredecision, le rocher represente le statu quo et la force necessaire represente le nombre de votes favorables.
- **Quand peu de personnes poussent** (faible participation) : il faut que presque tout le monde pousse dans la meme direction. Si seulement 10 personnes sur 7000 votent, il faut que 9 sur 10 soient pour.
- **Quand beaucoup de personnes poussent** (forte participation) : la majorite simple suffit. Si 7000 personnes votent, il suffit que 3500 soient pour (50%).
Ce mecanisme empeche qu'un petit groupe prenne des decisions engageant toute la communaute, tout en permettant une gouvernance efficace quand la participation est large.
### La formule
La formule exacte est :
```
Seuil = C + B^W + (M + (1-M) * (1 - (T/W)^G)) * max(0, T-C)
```
Ou :
| Symbole | Signification | Exemple |
| ------- | ------------- | ------- |
| C | Base constante (plancher minimum) | 0 |
| B | Exposant de base (negligeable pour grandes communautes) | 0.1 |
| W | Taille de la Toile de Confiance (membres eligibles) | 7224 |
| T | Nombre total de votes exprimes | 120 |
| M | Ratio de majorite cible a pleine participation | 0.50 (50%) |
| G | Gradient : vitesse de convergence vers la majorite | 0.2 |
### Exemple concret
Pour le vote de l'**Engagement Forgeron v2.0.0** :
- WoT = 7224 membres, 120 votes (1.7% de participation)
- Parametres : M=50%, B=0.1, G=0.2, C=0
- **Seuil calcule : 94 votes favorables requis** (soit 78% des votants)
- Resultat : 97 pour, 23 contre -- **Adopte** (97 >= 94)
La faible participation a rendu le seuil exigeant : 78% au lieu de 50%. C'est l'inertie en action.
### Tableau d'inertie
Le tableau suivant montre comment l'exigence evolue avec la participation, pour les parametres de reference `M50 G.2` avec une WoT de 7224 :
| Participation | % de la WoT | % favorables requis |
| ------------: | ----------: | ------------------: |
| 10 | 0.1% | 87.4% |
| 50 | 0.7% | 82.3% |
| 100 | 1.4% | 80.1% |
| 120 | 1.7% | 79.5% |
| 200 | 2.8% | 77.7% |
| 500 | 6.9% | 74.4% |
| 1000 | 13.8% | 71.2% |
| 2000 | 27.7% | 67.7% |
| 5000 | 69.2% | 62.6% |
| 7224 | 100% | 50.0% |
On constate que meme a 500 votants (6.9%), il faut encore 74.4% de votes favorables. L'inertie ne descend en dessous de 66% qu'au-dela de 2000 votants.
## Criteres additionnels
### Critere Smith (Forgerons)
Certaines decisions exigent un nombre minimum de votes favorables de la part des **forgerons** (membres Smith de la WoT). Ce critere garantit que les decisions qui affectent le reseau sont soutenues par ceux qui le maintiennent.
Le seuil Smith est calcule par : `ceil(SmithWotSize^S)` ou `S` est l'exposant Smith.
**Exemple** : Avec 20 forgerons et S=0.1, le seuil est `ceil(20^0.1) = ceil(1.35) = 2`. Il faut au minimum 2 votes favorables de forgerons.
### Critere TechComm (Comite Technique)
De maniere similaire, certaines decisions exigent un nombre minimum de votes favorables du **Comite Technique**. Cela concerne les decisions techniques (runtime upgrades, modifications d'infrastructure).
Le seuil TechComm est calcule par : `ceil(CoTecSize^T)` ou `T` est l'exposant TechComm.
**Exemple** : Avec 5 membres TechComm et T=0.1, le seuil est `ceil(5^0.1) = ceil(1.17) = 2`. Il faut au minimum 2 votes favorables du Comite Technique.
### Adoption finale
Un vote n'est adopte que si **les trois conditions** sont remplies simultanement :
1. Les votes favorables atteignent le seuil WoT (formule principale)
2. Les votes favorables des forgerons atteignent le seuil Smith (si actif)
3. Les votes favorables du Comite Technique atteignent le seuil TechComm (si actif)
## Mode params : decoder les parametres
Les parametres de formule sont encodes dans une chaine compacte pour faciliter la lecture. Voici comment decoder `"D30M50B.1G.2T.1"` :
| Code | Valeur | Signification |
| ---- | ------ | ------------- |
| D30 | 30 | Duree du vote : **30 jours** |
| M50 | 50% | Majorite cible : **50%** (majorite simple a pleine participation) |
| B.1 | 0.1 | Exposant de base : **0.1** (negligeable pour grandes WoT) |
| G.2 | 0.2 | Gradient : **0.2** (convergence rapide vers la majorite) |
| T.1 | 0.1 | Exposant TechComm : **0.1** (critere TechComm actif) |
Autres codes possibles :
| Code | Parametre | Exemple | Signification |
| ---- | --------- | ------- | ------------- |
| C | Base constante | C3 | Minimum 3 votes favorables quelle que soit la formule |
| S | Exposant Smith | S.1 | Critere Smith actif avec exposant 0.1 |
| N | Multiplicateur ratio | N1.5 | Multiplicateur 1.5 en mode ratio |
| R | Mode ratio | R1 | Mode ratio active |
### Exemples de configurations
- `"D30M50B.1G.2"` : 30 jours, majorite 50%, configuration standard
- `"D30M50B.1G.2S.1T.1"` : idem avec criteres Smith et TechComm
- `"D60M66B.05G.3"` : 60 jours, super-majorite 66%, gradient plus strict
- `"D14M50B.1G.1"` : 14 jours, gradient rapide (decisions urgentes)
## Comment voter : etapes concretes
### Vote binaire
1. **Acceder a la session de vote** : Rendez-vous dans la section **Votes** depuis le menu principal, ou accedez directement a la page d'une decision en cours. Les sessions ouvertes sont signalees par un badge vert "En cours".
@@ -48,6 +170,18 @@ Le vote est adopte si les niveaux positifs (3, 4, 5) representent au moins 80% d
6. **Confirmer la soumission** : Une fois la signature effectuee, cliquez sur **Soumettre**. Un message de confirmation apparait avec le resume de votre vote.
### Vote nuance
1. **Acceder a la session** : Meme procedure que pour le vote binaire. Les sessions de vote nuance sont identifiees par un badge "Nuance" en plus du badge de statut.
2. **Consulter le sujet** : Lisez le document ou la decision soumise au vote.
3. **Choisir votre niveau** : Le panneau de vote nuance affiche une echelle a 6 niveaux sous forme de curseur ou de boutons. Les niveaux 3, 4 et 5 sont comptes comme **positifs**. Les niveaux 0, 1 et 2 sont comptes comme **negatifs**.
4. **Ajouter un commentaire** (optionnel) : Particulierement utile pour les niveaux intermediaires (1, 2, 3, 4), afin d'expliquer vos reserves ou vos attentes.
5. **Signer et soumettre** : Meme procedure que pour le vote binaire.
### Modifier son vote
Tant que la session est ouverte, vous pouvez changer votre vote :
@@ -58,39 +192,7 @@ Tant que la session est ouverte, vous pouvez changer votre vote :
4. Selectionnez votre nouveau choix et signez a nouveau.
5. L'ancien vote est desactive (conserve dans l'historique pour audit) et remplace par le nouveau.
## Comment voter -- Vote nuance
### Etape par etape
1. **Acceder a la session** : Meme procedure que pour le vote binaire. Les sessions de vote nuance sont identifiees par un badge "Nuance" en plus du badge de statut.
2. **Consulter le sujet** : Lisez le document ou la decision soumise au vote.
3. **Choisir votre niveau** : Le panneau de vote nuance affiche une echelle a 6 niveaux sous forme de curseur ou de boutons :
| Niveau | Label | Signification |
| -----: | ------------- | ---------------------------------------------------------- |
| 0 | CONTRE | Opposition totale et ferme |
| 1 | PAS DU TOUT | Desaccord fort, points essentiels non remplis |
| 2 | PAS D'ACCORD | Desaccord modere, des reserves importantes |
| 3 | NEUTRE | Ni pour ni contre, ou acceptation sans enthousiasme |
| 4 | D'ACCORD | Approbation avec eventuellement des reserves mineures |
| 5 | TOUT A FAIT | Approbation totale et enthousiaste |
Les niveaux 3, 4 et 5 sont comptes comme **positifs**. Les niveaux 0, 1 et 2 sont comptes comme **negatifs**.
4. **Ajouter un commentaire** (optionnel) : Particulierement utile pour les niveaux intermediaires (1, 2, 3, 4), afin d'expliquer vos reserves ou vos attentes.
5. **Signer et soumettre** : Meme procedure que pour le vote binaire.
### Quand utiliser le vote nuance ?
Le vote nuance est recommande pour :
- Les textes longs comportant de nombreux articles (les votants peuvent exprimer un accord partiel).
- Les decisions ou la nuance est importante (budget, parametre technique).
- Les cas ou il est utile de mesurer le degre d'adhesion, pas seulement le resultat binaire.
## Comprendre la jauge de seuil
## Comprendre les resultats : la jauge de seuil
La page de chaque session de vote affiche une **jauge de seuil** qui represente visuellement l'etat du vote en temps reel.
@@ -123,6 +225,58 @@ En cliquant sur le bouton **Voir le detail** sous la jauge, une modale s'ouvre a
- Les criteres Smith et TechComm si applicables.
- Un lien vers le simulateur de formules pour experimenter d'autres scenarios.
### Page de resultat
La page de resultat affiche :
| Information | Description |
| ------------------- | ---------------------------------------------------- |
| Votes pour | Nombre de votes favorables |
| Votes contre | Nombre de votes defavorables |
| Total | Nombre total de votes exprimes |
| Taille WoT | Nombre de membres WoT eligibles (snapshot au debut) |
| Seuil requis | Seuil calcule par la formule d'inertie |
| Critere Smith | Seuil et validation des votes Smith (si applicable) |
| Critere TechComm | Seuil et validation des votes TechComm (si applicable) |
| Resultat | **Adopte** ou **Rejete** |
## Simulateur de formules
Le simulateur de formules vous permet de tester le comportement du seuil d'adoption avec differentes configurations, sans creer de session de vote.
### Acceder au simulateur
1. Depuis le menu principal, selectionnez **Outils** puis **Simulateur de formules**.
2. Vous pouvez aussi y acceder depuis le detail du calcul de seuil d'une session de vote (bouton **Ouvrir le simulateur**).
### Utiliser le simulateur
Le simulateur presente un formulaire avec les parametres ajustables :
| Parametre | Description | Curseur/Champ |
| ----------------------- | ---------------------------------------------- | ------------- |
| Taille WoT ($W$) | Nombre de membres eligibles | Curseur |
| Total votes ($T$) | Nombre de votes exprimes | Curseur |
| Majorite ($M$) | Pourcentage de majorite cible | Curseur |
| Base ($B$) | Exposant de base | Champ |
| Gradient ($G$) | Vitesse de convergence | Curseur |
| Base constante ($C$) | Plancher minimum de votes | Champ |
| Votes Pour | Nombre de votes favorables (pour tester l'adoption) | Curseur |
En ajustant les curseurs, le resultat se met a jour en temps reel :
- Le **seuil calcule** est affiche.
- Un graphique montre la courbe du seuil en fonction de la participation.
- Le resultat **Adopte** / **Rejete** s'affiche en fonction des votes pour saisis.
### Exemple de scenario
Vous souhaitez comparer deux configurations pour un vote attendu avec environ 200 participants sur une WoT de 7224 :
1. Configuration actuelle `M50 G.2` : Seuil = 156 (77.7% requis).
2. Configuration proposee `M50 G.4` : Seuil = 171 (85.5% requis).
Le simulateur montre visuellement l'impact : avec un gradient plus eleve, l'exigence est sensiblement plus forte a faible participation.
## Mises a jour en temps reel
Glibredecision utilise une connexion **WebSocket** pour diffuser les mises a jour de vote en temps reel a tous les utilisateurs qui consultent une session de vote.
@@ -166,43 +320,6 @@ Sur la page d'une session de vote, l'onglet **Votes** affiche la liste de tous l
Les votes sont publics et verifiables par tous. Il n'y a pas de vote secret dans Glibredecision : la transparence est un principe fondamental.
## Simulateur de formules
Le simulateur de formules vous permet de tester le comportement du seuil d'adoption avec differentes configurations, sans creer de session de vote.
### Acceder au simulateur
1. Depuis le menu principal, selectionnez **Outils** puis **Simulateur de formules**.
2. Vous pouvez aussi y acceder depuis le detail du calcul de seuil d'une session de vote (bouton **Ouvrir le simulateur**).
### Utiliser le simulateur
Le simulateur presente un formulaire avec les parametres ajustables :
| Parametre | Description | Curseur/Champ |
| ----------------------- | ---------------------------------------------- | ------------- |
| Taille WoT ($W$) | Nombre de membres eligibles | Curseur |
| Total votes ($T$) | Nombre de votes exprimes | Curseur |
| Majorite ($M$) | Pourcentage de majorite cible | Curseur |
| Base ($B$) | Exposant de base | Champ |
| Gradient ($G$) | Vitesse de convergence | Curseur |
| Base constante ($C$) | Plancher minimum de votes | Champ |
| Votes Pour | Nombre de votes favorables (pour tester l'adoption) | Curseur |
En ajustant les curseurs, le resultat se met a jour en temps reel :
- Le **seuil calcule** est affiche.
- Un graphique montre la courbe du seuil en fonction de la participation.
- Le resultat **Adopte** / **Rejete** s'affiche en fonction des votes pour saisis.
### Exemple de scenario
Vous souhaitez comparer deux configurations pour un vote attendu avec environ 200 participants sur une WoT de 7224 :
1. Configuration actuelle `M50 G.2` : Seuil = 156 (77.7% requis).
2. Configuration proposee `M50 G.4` : Seuil = 171 (85.5% requis).
Le simulateur montre visuellement l'impact : avec un gradient plus eleve, l'exigence est sensiblement plus forte a faible participation.
## Meta-gouvernance : voter sur les regles du vote
La meta-gouvernance est la capacite de **modifier les regles du systeme de vote en utilisant le systeme de vote lui-meme**. C'est le mecanisme par lequel la communaute garde le controle sur les parametres fondamentaux de la prise de decision.
@@ -250,32 +367,6 @@ Un membre estime que le gradient $G = 0.2$ est trop permissif et propose de pass
- **Transparence** : toute modification de regle est tracable et soumise au vote.
- **Coherence** : les regles de modification sont les memes que les regles de decision (le systeme s'applique a lui-meme).
## Comprendre les resultats
La page de resultat affiche :
| Information | Description |
| ------------------- | ---------------------------------------------------- |
| Votes pour | Nombre de votes favorables |
| Votes contre | Nombre de votes defavorables |
| Total | Nombre total de votes exprimes |
| Taille WoT | Nombre de membres WoT eligibles (snapshot au debut) |
| Seuil requis | Seuil calcule par la formule d'inertie |
| Critere Smith | Seuil et validation des votes Smith (si applicable) |
| Critere TechComm | Seuil et validation des votes TechComm (si applicable) |
| Resultat | **Adopte** ou **Rejete** |
### Exemple concret
Pour le vote de l'Engagement Forgeron v2.0.0 :
- Taille WoT : 7224 membres
- 97 votes pour, 23 votes contre (120 total)
- Seuil calcule : 94 (avec les parametres M50 B.1 G.2)
- Resultat : **Adopte** (97 >= 94)
La faible participation (120 sur 7224 = 1.7%) a rendu le seuil exigeant (94 pour sur 120 = 78%), bien au-dessus de la majorite simple de 50%.
## Preuve cryptographique
Chaque vote est accompagne d'une signature Ed25519 qui garantit :
@@ -296,3 +387,25 @@ Chaque session de vote est liee a un **protocole de vote** qui definit :
- Les criteres Smith et TechComm eventuels
Les protocoles sont reutilisables et peuvent eux-memes etre soumis a meta-gouvernance.
## FAQ Vote
### Le seuil peut-il changer pendant le vote ?
Oui. Le seuil depend du nombre total de votes exprimes ($T$). A chaque nouveau vote, le seuil est recalcule. Il augmente legerement a mesure que la participation croit, mais converge vers la majorite simple. C'est pourquoi le resultat affiche est toujours provisoire tant que la session est ouverte.
### Que se passe-t-il si le seuil n'est pas atteint a la cloture ?
Le vote est **rejete**. La proposition n'est pas adoptee et le statu quo est maintenu. Le resultat detaille est archive dans le Sanctuaire pour transparence.
### Un vote en cours peut-il etre annule ?
Seul le createur de la session ou un membre du Comite Technique peut cloturer une session de maniere anticipee. La cloture anticipee calcule le resultat avec les votes exprimes a ce moment.
### Comment sont geres les ex aequo ?
Il n'y a pas d'ex aequo possible avec la formule d'inertie. Le seuil est un nombre entier (arrondi inferieur) et le nombre de votes favorables est un entier. Si `votes_pour >= seuil`, le vote est adopte. Sinon, il est rejete.
### Puis-je voter si mon statut WoT change pendant le vote ?
Votre statut WoT est enregistre au moment de votre vote. Si vous perdez votre statut de membre apres avoir vote, votre vote reste comptabilise car le snapshot de la taille WoT est pris au debut de la session.