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

Sprint 4 : decisions et mandats -- workflow complet + vote integration

Browse Source 
Backend: 7 nouveaux endpoints (advance, assign, revoke, create-vote-session),
services enrichis avec creation de sessions de vote, assignation de mandataire
et revocation. 35 nouveaux tests (104 total). Frontend: store mandates, page
cadrage decisions, detail mandats, composants DecisionWorkflow, DecisionCadrage,
DecisionCard, MandateTimeline, MandateCard. Documentation mise a jour.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
2026-02-28 14:28:34 +01:00
parent cede2a585f
commit 3cb1754592
24 changed files with 3988 additions and 354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/content/user/4.decisions.md
View File

@@ -7,55 +7,136 @@ description: Guide des processus decisionnels sur Glibredecision
## Principe
Une decision est un processus structure qui conduit a un choix collectif. Chaque decision suit un ensemble d'etapes definies, de la qualification a l'execution.
Une decision est un processus structure qui conduit a un choix collectif. Chaque decision suit un ensemble d'etapes definies, de la qualification a l'execution. Le systeme garantit la tracabilite de chaque etape et l'integration avec le systeme de vote WoT.
## Types de decisions
| Type | Description |
| ------------------ | ------------------------------------------------------ |
| Document change | Modification d'un item de document de reference |
| Runtime upgrade | Mise a jour du runtime de la blockchain Duniter |
| Mandate vote | Vote pour l'attribution d'un mandat |
| Custom | Decision personnalisee |
| Type | Description | Cas d'usage |
| ------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
| `runtime_upgrade` | Mise a jour du runtime de la blockchain Duniter | Upgrade du reseau, changement de parametres consensus |
| `document_change` | Modification d'un item de document de reference | Amendement de la Licence G1, modification d'un engagement |
| `mandate_vote` | Vote pour l'attribution d'un mandat | Election d'un membre du Comite Technique |
| `parameter_change` | Modification de parametres systeme | Changement de duree de vote, seuil de majorite |
| `custom` | Decision personnalisee | Tout autre type de decision collective |
## Etapes d'une decision
## Cycle de vie d'une decision
Une decision progresse a travers les etapes suivantes :
| Etape | Description |
| --------------- | ---------------------------------------------------------------- |
| Qualification | Verification que la proposition est recevable |
| Examen (review) | Periode d'examen et de discussion par la communaute |
| Vote | Session de vote formelle avec seuil de validation |
| Execution | Mise en oeuvre de la decision adoptee |
| Rapport | Compte-rendu de l'execution et archivage des resultats |
Certaines etapes peuvent etre sautees selon le type de decision.
## Cycle de vie
Une decision progresse a travers six statuts successifs :
```
Brouillon --> Qualification --> Examen --> Vote --> Executee --> Cloturee
--> Rejetee
|
+--> Rejetee (si le vote echoue)
```
## Suivre une decision
| Statut | Description |
| ----------------- | ---------------------------------------------------------------- |
| `draft` | Brouillon initial. La decision est en cours de redaction et peut etre modifiee librement ou supprimee. |
| `qualification` | Phase de verification. On s'assure que la proposition est recevable (forme, competence, pertinence). |
| `review` | Periode d'examen et de discussion par la communaute. Les membres peuvent commenter et suggerer des amendements. |
| `voting` | Session de vote formelle. Le seuil de validation WoT s'applique. Une session de vote est creee et liee a l'etape correspondante. |
| `executed` | La decision a ete adoptee et est en cours de mise en oeuvre. |
| `closed` | La decision est cloturee. Le resultat est archive dans le sanctuaire. |
1. Rendez-vous dans la section **Decisions**.
2. Filtrez par type ou statut pour trouver la decision qui vous interesse.
3. La page de detail affiche toutes les etapes avec leur statut.
4. Si une etape de vote est active, vous pouvez voter directement depuis la page de decision.
Si le vote echoue (seuil non atteint), la decision passe en statut "rejetee" et ne peut plus avancer.
## Etapes d'une decision (decision_steps)
Chaque decision est composee d'etapes ordonnees qui definissent le workflow concret. Les types d'etapes disponibles sont :
| Type d'etape | Description |
| --------------- | ---------------------------------------------------------------- |
| `qualification` | Verification que la proposition est recevable |
| `review` | Periode d'examen et de discussion par la communaute |
| `vote` | Session de vote formelle avec seuil de validation WoT |
| `execution` | Mise en oeuvre de la decision adoptee |
| `reporting` | Compte-rendu de l'execution et archivage des resultats |
Chaque etape possede un statut individuel :
| Statut | Description |
| ----------- | ---------------------------------------------------------- |
| `pending` | L'etape n'a pas encore commence |
| `active` | L'etape est en cours |
| `completed` | L'etape est terminee avec succes |
| `skipped` | L'etape a ete ignoree (non applicable pour ce type de decision) |
## Comment le workflow avance
Le workflow d'une decision avance via l'action **"Avancer"** (endpoint `POST /decisions/{id}/advance`). A chaque appel :
1. **S'il y a une etape active** : elle est marquee `completed`, et la prochaine etape `pending` est activee.
2. **S'il n'y a pas d'etape active** : la premiere etape `pending` est activee. Si la decision est en `draft`, elle passe automatiquement en `qualification`.
3. **Si toutes les etapes sont terminees** : le statut global de la decision avance au statut suivant dans le cycle de vie.
Ce mecanisme garantit que les etapes sont parcourues dans l'ordre defini (`step_order`) et qu'aucune etape ne peut etre sautee involontairement.
## Creation d'une session de vote
Quand une etape de type `vote` est active, il faut creer une session de vote liee a cette etape. Cela se fait via l'action **"Creer une session de vote"** (endpoint `POST /decisions/{id}/steps/{step_id}/create-vote-session`).
La session de vote :
- Est automatiquement liee au protocole de vote de la decision
- Prend un snapshot des tailles WoT, Smith et TechComm au moment de la creation
- Calcule la date de fin en fonction de la duree definie dans la formule du protocole
- Est rattachee a l'etape via le champ `vote_session_id`
Une fois la session de vote cloturee (manuellement ou par expiration), l'etape peut etre completee et le workflow peut avancer.
## Creer une decision
Les membres authentifies peuvent creer une decision :
1. Cliquez sur **Nouvelle decision**.
2. Renseignez le titre, la description, le contexte et le type.
3. Selectionnez un **protocole de vote** qui definit les parametres de la formule de seuil.
4. Ajoutez les etapes necessaires.
5. Soumettez. La decision passe en statut "brouillon" jusqu'a ce que la premiere etape soit lancee.
2. Renseignez le **titre** : un intitule clair et concis de la proposition.
3. Renseignez la **description** : le detail de ce qui est propose.
4. Renseignez le **contexte** : pourquoi cette decision est necessaire (cadrage).
5. Choisissez le **type de decision** : `runtime_upgrade`, `document_change`, `mandate_vote`, `parameter_change` ou `custom`.
6. Selectionnez un **protocole de vote** qui definit les parametres de la formule de seuil WoT (duree, majorite, gradient, criteres Smith/TechComm).
7. **Ajoutez les etapes** necessaires dans l'ordre souhaite (qualification, examen, vote, execution, reporting).
8. Soumettez. La decision est creee en statut `draft`.
9. Utilisez l'action **"Avancer"** pour lancer la premiere etape et demarrer le processus.
## Supprimer une decision
Les decisions en statut `draft` peuvent etre supprimees via l'action **"Supprimer"** (endpoint `DELETE /decisions/{id}`). Une fois le processus demarre (statut `qualification` ou au-dela), la decision reste dans le systeme pour tracabilite.
## Suivre une decision
1. Rendez-vous dans la section **Decisions**.
2. Filtrez par type ou statut pour trouver la decision qui vous interesse.
3. La page de detail affiche toutes les etapes avec leur statut (en attente, active, terminee, ignoree).
4. Si une etape de vote est active et qu'une session de vote est ouverte, vous pouvez voter directement depuis la page de decision.
5. Le resultat du vote (seuil, participation, criteres Smith/TechComm) est affiche en temps reel.
## Exemple : Processus de Runtime Upgrade
Un Runtime Upgrade suit un processus en 5 etapes strictement definies :
```
1. Qualification -> Verification technique par le Comite Technique
2. Examen -> Review du code par les forgerons, discussion communautaire
3. Vote -> Vote WoT avec criteres Smith et TechComm obligatoires
4. Execution -> Deploiement du runtime sur le reseau
5. Reporting -> Compte-rendu post-deploiement, verification de stabilite
```
**Deroulement concret :**
1. Un membre cree une decision de type `runtime_upgrade` avec le contexte technique (version, changelog, hash du wasm).
2. Il ajoute les 5 etapes dans l'ordre.
3. Il avance la decision : l'etape "Qualification" devient active. Le Comite Technique verifie le build.
4. Une fois la qualification validee, il avance : l'etape "Examen" devient active. Les forgerons reviewent le code.
5. Il avance : l'etape "Vote" devient active. Une session de vote est creee avec le protocole incluant les criteres Smith et TechComm.
6. Les membres votent. Le seuil WoT s'applique avec inertie. Les criteres Smith (`ceil(SmithWotSize^S)`) et TechComm (`ceil(CoTecSize^T)`) doivent aussi etre atteints.
7. Si adopte, il avance : l'etape "Execution" devient active. Le runtime est deploye.
8. Il avance : l'etape "Reporting" devient active. Le compte-rendu est redige.
9. Il avance une derniere fois : la decision passe en statut `closed`.
## Lien avec les documents
Quand une decision de type "document change" est adoptee, la modification proposee est automatiquement appliquee a l'item du document concerne. L'ancienne version est conservee dans l'historique.
Quand une decision de type `document_change` est adoptee, la modification proposee est automatiquement appliquee a l'item du document concerne. L'ancienne version est conservee dans l'historique des versions (`item_versions`).
## Lien avec les mandats
Les decisions de type `mandate_vote` sont utilisees pour les elections de mandats. La decision contient une etape de vote qui determine le resultat de l'election. Voir la section [Mandats](/user/mandates) pour plus de details.

165
docs/content/user/6.mandates.md
View File

@@ -7,51 +7,166 @@ description: Guide des mandats sur Glibredecision
## Principe
Un mandat est une responsabilite attribuee a un membre de la communaute pour une duree determinee, apres validation par vote collectif. Les mandats permettent de formaliser les roles au sein de la gouvernance Duniter.
Un mandat est une responsabilite attribuee a un membre de la communaute pour une duree determinee, apres validation par vote collectif. Les mandats permettent de formaliser les roles au sein de la gouvernance Duniter et d'assurer la redevabilite des mandataires.
## Types de mandats
| Type | Description |
| --------- | ------------------------------------------------------- |
| TechComm | Mandat de membre du Comite Technique |
| Smith | Mandat lie au role de forgeron (Smith) |
| Custom | Mandat personnalise pour tout autre role |
| Type | Description | Cas d'usage |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------- |
| `techcomm` | Mandat de membre du Comite Technique | Administration du reseau, validation des runtime upgrades |
| `smith` | Mandat lie au role de forgeron (Smith) | Production de blocs, maintenance de la blockchain |
| `custom` | Mandat personnalise pour tout autre role | Tresorier, secretaire, moderateur, etc. |
Chaque type de mandat peut avoir des criteres de vote specifiques. Par exemple, un mandat `techcomm` peut exiger un critere TechComm (`ceil(CoTecSize^T)`), tandis qu'un mandat `smith` peut exiger un critere Smith (`ceil(SmithWotSize^S)`).
## Cycle de vie d'un mandat
Un mandat progresse a travers les etapes suivantes :
Un mandat progresse a travers les statuts suivants :
```
Brouillon --> Candidature --> Vote --> Actif --> Rapport --> Termine
--> Revoque
| |
+--> Rejet (si le +--> Revoque (revocation
vote echoue) anticipee)
```
| Etape | Description |
| Statut | Description |
| ------------ | ------------------------------------------------------------ |
| Formulation | Definition du mandat, de ses objectifs et de sa duree |
| Candidature | Periode de depot des candidatures |
| Vote | Vote collectif pour designer le mandataire |
| Assignation | Attribution du mandat au candidat elu |
| Rapport | Periode de reporting sur l'execution du mandat |
| Completion | Fin normale du mandat a echeance |
| Revocation | Fin anticipee du mandat (en cas de manquement) |
| `draft` | Brouillon initial. Le mandat est en cours de definition et peut etre modifie ou supprime. |
| `candidacy` | Periode de depot des candidatures. Les membres interesses se declarent candidats. |
| `voting` | Vote collectif pour designer le mandataire. Une session de vote est ouverte. |
| `active` | Le mandat est en cours. Le mandataire exerce ses responsabilites. |
| `reporting` | Periode de reporting. Le mandataire rend compte de ses actions. |
| `completed` | Fin normale du mandat a echeance. Le bilan est archive. |
| `revoked` | Fin anticipee du mandat suite a une revocation. |
## Consulter les mandats
## Etapes d'un mandat (mandate_steps)
1. Rendez-vous dans la section **Mandats**.
2. Filtrez par type (techcomm, smith, custom) ou statut.
3. Chaque mandat affiche le titulaire, les dates et les etapes.
Chaque mandat est compose d'etapes ordonnees qui definissent le processus complet. Les types d'etapes disponibles sont :
| Type d'etape | Description |
| -------------- | ------------------------------------------------------------ |
| `formulation` | Definition du mandat, de ses objectifs et de sa duree |
| `candidacy` | Periode de depot et d'examen des candidatures |
| `vote` | Vote collectif pour designer le mandataire |
| `assignment` | Attribution formelle du mandat au candidat elu |
| `reporting` | Periode de reporting sur l'execution du mandat |
| `completion` | Fin normale du mandat a echeance |
| `revocation` | Fin anticipee du mandat (en cas de manquement) |
Chaque etape possede un statut individuel :
| Statut | Description |
| ----------- | ---------------------------------------------------------- |
| `pending` | L'etape n'a pas encore commence |
| `active` | L'etape est en cours |
| `completed` | L'etape est terminee avec succes |
| `skipped` | L'etape a ete ignoree (non applicable) |
## Comment le workflow avance
Le workflow d'un mandat avance via l'action **"Avancer"** (endpoint `POST /mandates/{id}/advance`). Le fonctionnement est identique a celui des decisions :
1. **S'il y a une etape active** : elle est marquee `completed`, et la prochaine etape `pending` est activee.
2. **S'il n'y a pas d'etape active** : la premiere etape `pending` est activee. Si le mandat est en `draft`, il passe automatiquement en `candidacy`.
3. **Si toutes les etapes sont terminees** : le statut global du mandat avance au statut suivant dans le cycle de vie.
Les statuts terminaux (`completed` et `revoked`) bloquent tout avancement ulterieur.
## Creer un mandat
Les membres authentifies peuvent proposer un nouveau mandat :
1. Cliquez sur **Nouveau mandat**.
2. Renseignez le titre, la description et le type.
3. Definissez les dates de debut et de fin.
4. Ajoutez les etapes du processus.
5. Le mandat passe en phase de candidature puis de vote.
2. Renseignez le **titre** : intitule du role ou de la mission.
3. Renseignez la **description** : objectifs, responsabilites, criteres de reussite.
4. Choisissez le **type de mandat** : `techcomm`, `smith` ou `custom`.
5. Optionnellement, liez le mandat a une **decision** existante de type `mandate_vote`.
6. **Ajoutez les etapes** dans l'ordre souhaite (formulation, candidature, vote, assignation, reporting, completion).
7. Soumettez. Le mandat est cree en statut `draft`.
8. Utilisez l'action **"Avancer"** pour demarrer le processus.
## Candidatures
Pendant la phase de candidature (`candidacy`), les membres de la communaute peuvent se declarer candidats. La page du mandat affiche la liste des candidats avec leur profil Duniter (adresse SS58, statut WoT, statut Smith/TechComm).
## Vote pour un mandat
Quand l'etape de type `vote` est active, une session de vote doit etre creee via l'action **"Creer une session de vote"** (endpoint `POST /mandates/{id}/steps/{step_id}/create-vote-session`).
La session de vote fonctionne exactement comme pour les decisions :
- Snapshot des tailles WoT, Smith, TechComm
- Application de la formule de seuil avec inertie
- Criteres supplementaires Smith/TechComm selon le protocole choisi
- Cloture automatique ou manuelle
Le resultat du vote determine si le mandat est attribue au candidat elu.
## Assignation du mandataire
Apres un vote reussi, le mandataire est assigne au mandat via l'action **"Assigner"** (endpoint `POST /mandates/{id}/assign`). Cette action :
- Definit le `mandatee_id` : l'identite Duniter du membre elu
- Definit les dates de debut et de fin du mandat
- Fait passer le mandat en statut `active`
Le corps de la requete contient l'identifiant de l'identite Duniter du mandataire :
```json
{
"mandatee_id": "uuid-de-l-identite-duniter"
}
```
## Reporting et redevabilite
Pendant la phase active du mandat, le mandataire est tenu de rendre compte de ses actions. Quand l'etape de `reporting` est active :
- Le mandataire peut publier des comptes-rendus via le champ `outcome` de l'etape
- Les membres de la communaute peuvent consulter les rapports
- Le bilan est archive dans le sanctuaire a la fin du mandat
## Revocation
Un mandat actif peut etre revoque de maniere anticipee via l'action **"Revoquer"** (endpoint `POST /mandates/{id}/revoke`). La revocation :
- Passe le statut du mandat a `revoked`
- Met fin immediatement aux responsabilites du mandataire
- Archive le motif de revocation
La revocation est une action de gouvernance qui peut necessiter un vote prealable (decision de type `mandate_vote` avec motif de revocation).
## Suppression
Seuls les mandats au statut "brouillon" peuvent etre supprimes. Une fois le processus de candidature lance, le mandat reste dans le systeme pour tracabilite.
Seuls les mandats au statut `draft` peuvent etre supprimes via l'action **"Supprimer"** (endpoint `DELETE /mandates/{id}`). Une fois le processus de candidature lance, le mandat reste dans le systeme pour tracabilite.
## Consulter les mandats
1. Rendez-vous dans la section **Mandats**.
2. Filtrez par type (`techcomm`, `smith`, `custom`) ou par statut.
3. Chaque mandat affiche le titulaire, les dates, les etapes et leur statut.
4. La page de detail montre le workflow complet avec l'historique des etapes.
## Exemple : Election d'un membre du Comite Technique
```
1. Formulation -> Definition du poste : responsabilites, duree (1 an), competences requises
2. Candidature -> Les membres Smith se declarent candidats pendant 14 jours
3. Vote -> Vote WoT avec critere TechComm obligatoire, duree 30 jours
4. Assignation -> Attribution du mandat au candidat elu
5. Reporting -> Rapport d'activite trimestriel
6. Completion -> Fin du mandat apres 1 an, bilan final archive
```
**Deroulement concret :**
1. Un membre cree un mandat de type `techcomm` avec la description du poste.
2. Il ajoute les 6 etapes dans l'ordre.
3. Il avance le mandat : l'etape "Formulation" est activee, puis completee.
4. Il avance : la phase de candidature s'ouvre. Les candidats se declarent.
5. Il avance : l'etape "Vote" est activee. Une session de vote est creee.
6. Les membres votent. Le seuil WoT et le critere TechComm doivent etre atteints.
7. Si adopte, il avance : l'etape "Assignation" est activee. Le mandataire est designe via l'action "Assigner".
8. Il avance : le mandat passe en phase active. Le mandataire exerce ses fonctions.
9. A l'echeance, l'etape "Reporting" est activee pour le bilan.
10. Il avance une derniere fois : le mandat passe en statut `completed`.