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

185
docs/content/dev/3.api-reference.md
View File

@@ -44,7 +44,10 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
| POST | `/` | Creer une nouvelle decision | Oui |
| GET | `/{id}` | Obtenir une decision avec ses etapes | Non |
| PUT | `/{id}` | Mettre a jour une decision | Oui |
| DELETE | `/{id}` | Supprimer une decision (brouillon uniquement) | Oui |
| POST | `/{id}/steps` | Ajouter une etape a une decision | Oui |
| POST | `/{id}/advance` | Avancer la decision a l'etape suivante | Oui |
| POST | `/{id}/steps/{step_id}/create-vote-session` | Creer une session de vote pour une etape | Oui |
## Votes (`/api/v1/votes`)
@@ -71,6 +74,10 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
| DELETE | `/{id}` | Supprimer un mandat (brouillon uniquement) | Oui |
| POST | `/{id}/steps` | Ajouter une etape a un mandat | Oui |
| GET | `/{id}/steps` | Lister les etapes d'un mandat | Non |
| POST | `/{id}/advance` | Avancer le mandat a l'etape suivante | Oui |
| POST | `/{id}/assign` | Assigner un mandataire au mandat | Oui |
| POST | `/{id}/revoke` | Revoquer un mandat actif | Oui |
| POST | `/{id}/steps/{step_id}/create-vote-session` | Creer une session de vote pour une etape | Oui |
## Protocoles (`/api/v1/protocols`)
@@ -448,6 +455,184 @@ Simule le calcul de seuil d'une formule avec des parametres arbitraires, sans cr
}
```
## Details des endpoints Sprint 4
### `POST /api/v1/decisions/{id}/advance` -- Avancer une decision
Avance une decision a l'etape suivante de son workflow. Complete l'etape active courante et active la prochaine etape en attente. Si toutes les etapes sont terminees, le statut global de la decision avance au statut suivant dans le cycle de vie (`draft` -> `qualification` -> `review` -> `voting` -> `executed` -> `closed`).
**Comportement** :
- S'il y a une etape `active` : elle passe a `completed`, la prochaine etape `pending` est activee.
- S'il n'y a pas d'etape active : la premiere etape `pending` est activee. Si la decision est en `draft`, elle passe a `qualification`.
- Si toutes les etapes sont terminees : le statut global avance.
**Preconditions** :
- La decision ne doit pas etre au statut `closed`.
- L'utilisateur doit etre authentifie.
**Reponse** : `200 OK` avec un `DecisionAdvanceOut` :
```json
{
"id": "uuid",
"title": "Runtime upgrade v3.2.0",
"description": "...",
"context": "...",
"decision_type": "runtime_upgrade",
"status": "review",
"voting_protocol_id": "uuid",
"created_by_id": "uuid",
"created_at": "2026-02-28T10:00:00Z",
"updated_at": "2026-02-28T12:00:00Z",
"steps": [
{"id": "uuid", "step_order": 0, "step_type": "qualification", "status": "completed", "...": "..."},
{"id": "uuid", "step_order": 1, "step_type": "review", "status": "active", "...": "..."},
{"id": "uuid", "step_order": 2, "step_type": "vote", "status": "pending", "...": "..."}
],
"message": "Etape 'Qualification' completee. Etape 'Examen' activee."
}
```
**Code 400** : Si la decision est deja cloturee ou qu'aucun avancement n'est possible.
---
### `DELETE /api/v1/decisions/{id}` -- Supprimer une decision
Supprime une decision. La suppression n'est autorisee que si la decision est au statut `draft`. Les etapes associees sont supprimees en cascade.
**Preconditions** :
- La decision doit etre au statut `draft`.
- L'utilisateur doit etre authentifie.
**Reponse** : `204 No Content`.
**Code 400** : Si la decision n'est pas au statut `draft`.
---
### `POST /api/v1/decisions/{id}/steps/{step_id}/create-vote-session` -- Creer une session de vote pour une etape de decision
Cree une session de vote liee a une etape specifique d'une decision. La session est configuree automatiquement a partir du protocole de vote de la decision.
**Comportement** :
1. Verifie que la decision et l'etape existent.
2. Verifie que l'etape est de type `vote` et au statut `active`.
3. Cree une session de vote avec le protocole de la decision.
4. Fait un snapshot des tailles WoT, Smith et TechComm.
5. Calcule la date de fin a partir de la duree de la formule.
6. Rattache la session a l'etape via `vote_session_id`.
**Reponse** : `201 Created` avec un `VoteSessionOut`.
**Code 400** : Si l'etape n'est pas de type `vote`, n'est pas `active`, ou si une session est deja liee.
---
### `POST /api/v1/mandates/{id}/advance` -- Avancer un mandat
Avance un mandat a l'etape suivante de son workflow. Fonctionne de maniere identique a l'avancement des decisions, avec le cycle de vie specifique aux mandats (`draft` -> `candidacy` -> `voting` -> `active` -> `reporting` -> `completed`).
**Comportement** :
- S'il y a une etape `active` : elle passe a `completed`, la prochaine etape `pending` est activee.
- S'il n'y a pas d'etape active : la premiere etape `pending` est activee. Si le mandat est en `draft`, il passe a `candidacy`.
- Si toutes les etapes sont terminees : le statut global avance.
**Preconditions** :
- Le mandat ne doit pas etre au statut `completed` ou `revoked`.
- L'utilisateur doit etre authentifie.
**Reponse** : `200 OK` avec un `MandateAdvanceOut` :
```json
{
"id": "uuid",
"title": "Membre Comite Technique 2026",
"description": "...",
"mandate_type": "techcomm",
"status": "candidacy",
"mandatee_id": null,
"decision_id": null,
"starts_at": null,
"ends_at": null,
"created_at": "2026-02-28T10:00:00Z",
"updated_at": "2026-02-28T12:00:00Z",
"steps": [
{"id": "uuid", "step_order": 0, "step_type": "formulation", "status": "completed", "...": "..."},
{"id": "uuid", "step_order": 1, "step_type": "candidacy", "status": "active", "...": "..."}
],
"message": "Etape 'Formulation' completee. Etape 'Candidature' activee."
}
```
**Code 400** : Si le mandat est deja en statut terminal (`completed` ou `revoked`).
---
### `POST /api/v1/mandates/{id}/assign` -- Assigner un mandataire
Assigne un mandataire (membre elu) a un mandat apres un vote reussi.
**Corps de la requete** :
```json
{
"mandatee_id": "uuid-de-l-identite-duniter"
}
```
**Comportement** :
1. Verifie que le mandat existe et qu'il est dans un statut permettant l'assignation.
2. Definit le `mandatee_id` du mandat.
3. Le mandat peut ensuite etre avance vers le statut `active`.
**Preconditions** :
- L'utilisateur doit etre authentifie.
- Le `mandatee_id` doit correspondre a une identite Duniter existante.
**Reponse** : `200 OK` avec un `MandateOut` mis a jour.
**Code 404** : Si le mandat ou l'identite Duniter n'existe pas.
---
### `POST /api/v1/mandates/{id}/revoke` -- Revoquer un mandat
Revoque un mandat actif de maniere anticipee. Le statut du mandat passe directement a `revoked`, mettant fin aux responsabilites du mandataire.
**Preconditions** :
- Le mandat doit etre au statut `active` ou `reporting`.
- L'utilisateur doit etre authentifie.
**Reponse** : `200 OK` avec un `MandateOut` mis a jour (statut `revoked`).
**Code 400** : Si le mandat n'est pas dans un statut permettant la revocation.
---
### `POST /api/v1/mandates/{id}/steps/{step_id}/create-vote-session` -- Creer une session de vote pour une etape de mandat
Cree une session de vote liee a une etape specifique d'un mandat. Fonctionne de maniere identique a la creation de session pour les decisions.
**Comportement** :
1. Verifie que le mandat et l'etape existent.
2. Verifie que l'etape est de type `vote` et au statut `active`.
3. Cree une session de vote avec le protocole associe.
4. Fait un snapshot des tailles WoT, Smith et TechComm.
5. Calcule la date de fin a partir de la duree de la formule.
6. Rattache la session a l'etape via `vote_session_id`.
**Reponse** : `201 Created` avec un `VoteSessionOut`.
**Code 400** : Si l'etape n'est pas de type `vote`, n'est pas `active`, ou si une session est deja liee.
---
## Pagination
Les endpoints de liste acceptent les parametres `skip` (offset, defaut 0) et `limit` (max 200, defaut 50).

40
docs/content/dev/4.database-schema.md
View File

@@ -89,38 +89,42 @@ Historique des versions proposees pour chaque item. Lors de l'acceptation d'une
### `decisions`
Processus decisionnels multi-etapes.
Processus decisionnels multi-etapes. Le cycle de vie suit un ordre strict de statuts gere par le service `decision_service.advance_decision()`.
| Colonne | Type | Description |
| ------------------- | ------------ | -------------------------------------------------------- |
| id | UUID (PK) | Identifiant unique |
| title | VARCHAR(256) | Titre de la decision |
| description | TEXT | Description |
| context | TEXT | Contexte additionnel |
| decision_type | VARCHAR(64) | Type : runtime_upgrade, document_change, mandate_vote, custom |
| context | TEXT | Contexte additionnel (cadrage) |
| decision_type | VARCHAR(64) | Type : runtime_upgrade, document_change, mandate_vote, parameter_change, custom |
| status | VARCHAR(32) | Statut : draft, qualification, review, voting, executed, closed |
| voting_protocol_id | UUID (FK) | -> voting_protocols.id |
| created_by_id | UUID (FK) | -> duniter_identities.id |
| created_at | TIMESTAMPTZ | Date de creation |
| updated_at | TIMESTAMPTZ | Date de derniere mise a jour |
**Workflow des statuts** : `draft` -> `qualification` -> `review` -> `voting` -> `executed` -> `closed`. La transition est geree par le service `advance_decision` qui complete l'etape active, active la suivante, et avance le statut global quand toutes les etapes sont terminees. La suppression n'est autorisee qu'en statut `draft`.
### `decision_steps`
Etapes d'un processus decisionnel.
Etapes d'un processus decisionnel. Chaque etape est traitee sequentiellement selon `step_order`. Le service `advance_decision` complete l'etape `active` et active la prochaine `pending`.
| Colonne | Type | Description |
| ---------------- | ------------ | -------------------------------------------------------- |
| id | UUID (PK) | Identifiant unique |
| decision_id | UUID (FK) | -> decisions.id |
| step_order | INTEGER | Ordre de l'etape |
| decision_id | UUID (FK) | -> decisions.id (cascade delete) |
| step_order | INTEGER | Ordre de l'etape (0-indexed, determine la sequence) |
| step_type | VARCHAR(32) | Type : qualification, review, vote, execution, reporting |
| title | VARCHAR(256) | Titre de l'etape |
| description | TEXT | Description |
| status | VARCHAR(32) | Statut : pending, active, completed, skipped |
| vote_session_id | UUID (FK) | -> vote_sessions.id (session de vote associee) |
| vote_session_id | UUID (FK) | -> vote_sessions.id (renseigne via create-vote-session pour les etapes de type `vote`) |
| outcome | TEXT | Resultat de l'etape |
| created_at | TIMESTAMPTZ | Date de creation |
**Types d'etapes** : `qualification` (verification recevabilite), `review` (examen communautaire), `vote` (session de vote formelle), `execution` (mise en oeuvre), `reporting` (compte-rendu). Les etapes de type `vote` sont les seules a pouvoir avoir un `vote_session_id` renseigne.
### `vote_sessions`
Sessions de vote avec snapshot des tailles WoT et decompte en temps reel.
@@ -170,7 +174,7 @@ Votes individuels avec preuve cryptographique.
### `mandates`
Mandats assignes a des membres.
Mandats assignes a des membres. Le cycle de vie suit un ordre strict de statuts gere par le service `mandate_service.advance_mandate()`. La revocation (`POST /mandates/{id}/revoke`) permet de passer directement au statut terminal `revoked`.
| Colonne | Type | Description |
| ------------- | ------------ | ------------------------------------------------------- |
@@ -179,30 +183,34 @@ Mandats assignes a des membres.
| description | TEXT | Description |
| mandate_type | VARCHAR(64) | Type : techcomm, smith, custom |
| status | VARCHAR(32) | Statut : draft, candidacy, voting, active, reporting, completed, revoked |
| mandatee_id | UUID (FK) | -> duniter_identities.id (titulaire du mandat) |
| decision_id | UUID (FK) | -> decisions.id (decision associee) |
| starts_at | TIMESTAMPTZ | Date de debut |
| ends_at | TIMESTAMPTZ | Date de fin |
| mandatee_id | UUID (FK) | -> duniter_identities.id (titulaire du mandat, renseigne via `POST /mandates/{id}/assign`) |
| decision_id | UUID (FK) | -> decisions.id (decision associee, optionnel) |
| starts_at | TIMESTAMPTZ | Date de debut (renseignee lors de l'assignation) |
| ends_at | TIMESTAMPTZ | Date de fin (renseignee lors de l'assignation) |
| created_at | TIMESTAMPTZ | Date de creation |
| updated_at | TIMESTAMPTZ | Date de derniere mise a jour |
**Workflow des statuts** : `draft` -> `candidacy` -> `voting` -> `active` -> `reporting` -> `completed`. Les statuts terminaux sont `completed` et `revoked`. La suppression n'est autorisee qu'en statut `draft`. La revocation est possible depuis les statuts `active` ou `reporting`.
### `mandate_steps`
Etapes du cycle de vie d'un mandat.
Etapes du cycle de vie d'un mandat. Chaque etape est traitee sequentiellement selon `step_order`. Le service `advance_mandate` complete l'etape `active` et active la prochaine `pending`.
| Colonne | Type | Description |
| ---------------- | ------------ | ------------------------------------------------------------- |
| id | UUID (PK) | Identifiant unique |
| mandate_id | UUID (FK) | -> mandates.id |
| step_order | INTEGER | Ordre de l'etape |
| mandate_id | UUID (FK) | -> mandates.id (cascade delete) |
| step_order | INTEGER | Ordre de l'etape (0-indexed, determine la sequence) |
| step_type | VARCHAR(32) | Type : formulation, candidacy, vote, assignment, reporting, completion, revocation |
| title | VARCHAR(256) | Titre de l'etape |
| description | TEXT | Description |
| status | VARCHAR(32) | Statut : pending, active, completed, skipped |
| vote_session_id | UUID (FK) | -> vote_sessions.id (session de vote associee) |
| vote_session_id | UUID (FK) | -> vote_sessions.id (renseigne via create-vote-session pour les etapes de type `vote`) |
| outcome | TEXT | Resultat de l'etape |
| created_at | TIMESTAMPTZ | Date de creation |
**Types d'etapes** : `formulation` (definition du mandat), `candidacy` (depot des candidatures), `vote` (election par vote WoT), `assignment` (attribution au candidat elu), `reporting` (compte-rendu), `completion` (fin normale), `revocation` (fin anticipee). Les etapes de type `vote` sont les seules a pouvoir avoir un `vote_session_id` renseigne.
### `voting_protocols`
Protocoles de vote reutilisables.

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`.