Sprint 3 : protocoles de vote et boite a outils
Backend: - Sessions de vote : list, close, tally, threshold details, auto-expiration - Protocoles : update, simulate, meta-gouvernance, formulas CRUD - Service vote enrichi : close_session, get_threshold_details, nuanced breakdown - Schemas : ThresholdDetailOut, VoteResultOut, FormulaSimulationRequest/Result - WebSocket broadcast sur chaque vote + fermeture session - 25 nouveaux tests (threshold details, close, nuanced, simulation) Frontend: - 5 composants vote : VoteBinary, VoteNuanced, ThresholdGauge, FormulaDisplay, VoteHistory - 3 composants protocoles : ProtocolPicker, FormulaEditor, ModeParamsDisplay - Simulateur de formules interactif (page /protocols/formulas) - Page detail protocole (/protocols/[id]) - Composable useWebSocket (live updates) - Composable useVoteFormula (calcul client-side reactif) - Integration KaTeX pour rendu LaTeX des formules Documentation: - API reference : 8 nouveaux endpoints documentes - Formules : tables d'inertie, parametres detailles, simulation API - Guide vote : vote binaire/nuance, jauge, historique, simulateur, meta-gouvernance 55 tests passes (+ 1 skipped), 126 fichiers total. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
@@ -48,13 +48,17 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
|
||||
|
||||
## Votes (`/api/v1/votes`)
|
||||
|
||||
| Methode | Endpoint | Description | Auth |
|
||||
| ------- | --------------------------- | -------------------------------------------- | ---- |
|
||||
| POST | `/sessions` | Creer une session de vote | Oui |
|
||||
| GET | `/sessions/{id}` | Obtenir une session de vote | Non |
|
||||
| POST | `/sessions/{id}/vote` | Soumettre un vote (signe) | Oui |
|
||||
| GET | `/sessions/{id}/votes` | Lister les votes d'une session | Non |
|
||||
| GET | `/sessions/{id}/result` | Calculer et retourner le resultat courant | Non |
|
||||
| Methode | Endpoint | Description | Auth |
|
||||
| ------- | ------------------------------- | -------------------------------------------- | ---- |
|
||||
| POST | `/sessions` | Creer une session de vote | Oui |
|
||||
| GET | `/sessions` | Lister les sessions de vote (filtres: status, protocol_id, decision_id) | Non |
|
||||
| GET | `/sessions/{id}` | Obtenir une session de vote | Non |
|
||||
| POST | `/sessions/{id}/vote` | Soumettre un vote (signe) | Oui |
|
||||
| GET | `/sessions/{id}/votes` | Lister les votes d'une session | Non |
|
||||
| GET | `/sessions/{id}/result` | Calculer et retourner le resultat courant | Non |
|
||||
| POST | `/sessions/{id}/close` | Cloturer la session et calculer le resultat final | Oui |
|
||||
| GET | `/sessions/{id}/threshold` | Obtenir le detail du calcul de seuil (formule, parametres, valeurs intermediaires) | Non |
|
||||
| POST | `/sessions/{id}/tally` | Forcer un recomptage des votes et recalcul du seuil | Oui |
|
||||
|
||||
## Mandats (`/api/v1/mandates`)
|
||||
|
||||
@@ -70,13 +74,17 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
|
||||
|
||||
## Protocoles (`/api/v1/protocols`)
|
||||
|
||||
| Methode | Endpoint | Description | Auth |
|
||||
| ------- | --------------- | -------------------------------------------------- | ---- |
|
||||
| GET | `/` | Lister les protocoles de vote | Non |
|
||||
| POST | `/` | Creer un protocole de vote | Oui |
|
||||
| GET | `/{id}` | Obtenir un protocole avec sa configuration formule | Non |
|
||||
| GET | `/formulas` | Lister les configurations de formules | Non |
|
||||
| POST | `/formulas` | Creer une configuration de formule | Oui |
|
||||
| Methode | Endpoint | Description | Auth |
|
||||
| ------- | ------------------- | -------------------------------------------------- | ---- |
|
||||
| GET | `/` | Lister les protocoles de vote | Non |
|
||||
| POST | `/` | Creer un protocole de vote | Oui |
|
||||
| GET | `/{id}` | Obtenir un protocole avec sa configuration formule | Non |
|
||||
| PUT | `/{id}` | Mettre a jour un protocole (meta-gouvernance) | Oui |
|
||||
| GET | `/formulas` | Lister les configurations de formules | Non |
|
||||
| POST | `/formulas` | Creer une configuration de formule | Oui |
|
||||
| GET | `/formulas/{id}` | Obtenir une configuration de formule par son ID | Non |
|
||||
| PUT | `/formulas/{id}` | Mettre a jour une configuration de formule (meta-gouvernance) | Oui |
|
||||
| POST | `/simulate` | Simuler le calcul d'une formule avec des parametres arbitraires | Non |
|
||||
|
||||
## Sanctuaire (`/api/v1/sanctuary`)
|
||||
|
||||
@@ -221,6 +229,225 @@ Retourne toutes les entrees du sanctuaire liees a une entite source (document, d
|
||||
|
||||
**Reponse** : `200 OK` avec une liste de `SanctuaryEntryOut`.
|
||||
|
||||
## Details des endpoints Sprint 3
|
||||
|
||||
### `GET /api/v1/votes/sessions` -- Lister les sessions de vote
|
||||
|
||||
Retourne la liste des sessions de vote avec pagination et filtres optionnels.
|
||||
|
||||
**Parametres de requete** :
|
||||
|
||||
| Parametre | Type | Description |
|
||||
| ------------- | ------ | ---------------------------------------------- |
|
||||
| `status` | string | Filtrer par statut (`open`, `closed`, `draft`) |
|
||||
| `protocol_id` | uuid | Filtrer par protocole de vote |
|
||||
| `decision_id` | uuid | Filtrer par decision associee |
|
||||
| `skip` | int | Offset de pagination (defaut 0) |
|
||||
| `limit` | int | Nombre max de resultats (defaut 50, max 200) |
|
||||
|
||||
**Reponse** : `200 OK` avec une liste de `VoteSessionOut`.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/votes/sessions/{id}/close` -- Cloturer une session
|
||||
|
||||
Cloture une session de vote ouverte et calcule le resultat final. Le calcul inclut la formule WoT, les criteres Smith et TechComm le cas echeant. La session passe au statut `closed` et le resultat est fige.
|
||||
|
||||
**Preconditions** :
|
||||
- La session doit etre au statut `open`.
|
||||
- L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.
|
||||
|
||||
**Reponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid",
|
||||
"status": "closed",
|
||||
"closed_at": "2026-02-28T12:00:00Z",
|
||||
"result": {
|
||||
"votes_for": 97,
|
||||
"votes_against": 23,
|
||||
"total_votes": 120,
|
||||
"wot_size": 7224,
|
||||
"threshold": 94,
|
||||
"adopted": true,
|
||||
"smith_threshold": 2,
|
||||
"smith_votes_for": 5,
|
||||
"smith_met": true,
|
||||
"techcomm_threshold": null,
|
||||
"techcomm_votes_for": null,
|
||||
"techcomm_met": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/votes/sessions/{id}/threshold` -- Detail du calcul de seuil
|
||||
|
||||
Retourne le detail complet du calcul de seuil pour une session de vote, incluant les valeurs intermediaires de la formule. Utile pour la transparence et le debug.
|
||||
|
||||
**Reponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid",
|
||||
"formula_config_id": "uuid",
|
||||
"mode_params": "D30M50B.1G.2",
|
||||
"parameters": {
|
||||
"constant_base": 0.0,
|
||||
"base_exponent": 0.1,
|
||||
"majority_pct": 50,
|
||||
"gradient_exponent": 0.2,
|
||||
"smith_exponent": null,
|
||||
"techcomm_exponent": null
|
||||
},
|
||||
"inputs": {
|
||||
"wot_size": 7224,
|
||||
"total_votes": 120,
|
||||
"smith_wot_size": 20,
|
||||
"techcomm_size": 5
|
||||
},
|
||||
"computation": {
|
||||
"base_term": 7.943e-08,
|
||||
"participation_ratio": 0.0166,
|
||||
"participation_ratio_powered": 0.4217,
|
||||
"inertia_factor": 0.7892,
|
||||
"effective_threshold": 94.70,
|
||||
"threshold_ceiled": 95,
|
||||
"threshold_final": 94
|
||||
},
|
||||
"criteria": {
|
||||
"smith_threshold": null,
|
||||
"techcomm_threshold": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/votes/sessions/{id}/tally` -- Forcer un recomptage
|
||||
|
||||
Force le recalcul du decompte des votes et du seuil pour une session. Utile si des votes ont ete invalides manuellement ou si la taille WoT a ete corrigee.
|
||||
|
||||
**Preconditions** :
|
||||
- L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.
|
||||
|
||||
**Corps de la requete** (optionnel) :
|
||||
|
||||
```json
|
||||
{
|
||||
"wot_size_override": 7250,
|
||||
"smith_wot_size_override": null,
|
||||
"techcomm_size_override": null
|
||||
}
|
||||
```
|
||||
|
||||
Si aucun corps n'est fourni, les tailles sont reprises du snapshot initial.
|
||||
|
||||
**Reponse** : `200 OK` avec le meme format que le resultat de cloture.
|
||||
|
||||
---
|
||||
|
||||
### `PUT /api/v1/protocols/{id}` -- Mettre a jour un protocole
|
||||
|
||||
Met a jour un protocole de vote existant. Les modifications de protocoles actifs (utilises par des sessions ouvertes) sont soumises a **meta-gouvernance** : une session de vote doit d'abord valider la modification.
|
||||
|
||||
**Corps de la requete** (champs optionnels) :
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Nouveau nom du protocole",
|
||||
"description": "Description mise a jour",
|
||||
"vote_type": "nuanced",
|
||||
"duration_days": 60,
|
||||
"formula_config_id": "uuid-de-la-nouvelle-formule"
|
||||
}
|
||||
```
|
||||
|
||||
**Reponse** : `200 OK` avec le protocole mis a jour (`ProtocolOut`).
|
||||
|
||||
**Code 409** : Si le protocole est utilise par une session ouverte et qu'aucune validation meta-gouvernance n'est fournie.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/protocols/formulas/{id}` -- Obtenir une formule
|
||||
|
||||
Retourne une configuration de formule par son identifiant, incluant tous les parametres et le `mode_params` encode.
|
||||
|
||||
**Reponse** : `200 OK` avec un `FormulaConfigOut`.
|
||||
|
||||
---
|
||||
|
||||
### `PUT /api/v1/protocols/formulas/{id}` -- Mettre a jour une formule
|
||||
|
||||
Met a jour une configuration de formule existante. Comme pour les protocoles, les formules actives sont protegees par la meta-gouvernance.
|
||||
|
||||
**Corps de la requete** (champs optionnels) :
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Configuration amendee",
|
||||
"majority_pct": 66,
|
||||
"base_exponent": 0.05,
|
||||
"gradient_exponent": 0.3,
|
||||
"constant_base": 0.0,
|
||||
"smith_exponent": 0.1,
|
||||
"techcomm_exponent": 0.1,
|
||||
"ratio_multiplier": null,
|
||||
"is_ratio_mode": false
|
||||
}
|
||||
```
|
||||
|
||||
Le champ `mode_params` est recalcule automatiquement a partir des valeurs fournies.
|
||||
|
||||
**Reponse** : `200 OK` avec la formule mise a jour (`FormulaConfigOut`).
|
||||
|
||||
**Code 409** : Si la formule est liee a un protocole actif sans validation meta-gouvernance.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/protocols/simulate` -- Simuler une formule
|
||||
|
||||
Simule le calcul de seuil d'une formule avec des parametres arbitraires, sans creer ni modifier aucune donnee. Endpoint ouvert (pas d'authentification requise) pour permettre l'experimentation.
|
||||
|
||||
**Corps de la requete** :
|
||||
|
||||
```json
|
||||
{
|
||||
"wot_size": 7224,
|
||||
"total_votes": 120,
|
||||
"majority_pct": 50,
|
||||
"base_exponent": 0.1,
|
||||
"gradient_exponent": 0.2,
|
||||
"constant_base": 0.0,
|
||||
"smith_wot_size": 20,
|
||||
"smith_exponent": 0.1,
|
||||
"techcomm_size": 5,
|
||||
"techcomm_exponent": 0.1,
|
||||
"votes_for": 97
|
||||
}
|
||||
```
|
||||
|
||||
**Reponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"threshold": 94,
|
||||
"inertia_factor": 0.7892,
|
||||
"participation_ratio": 0.0166,
|
||||
"base_term": 7.943e-08,
|
||||
"smith_threshold": 2,
|
||||
"techcomm_threshold": 2,
|
||||
"adopted": true,
|
||||
"details": {
|
||||
"wot_threshold_met": true,
|
||||
"smith_met": true,
|
||||
"techcomm_met": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
Les endpoints de liste acceptent les parametres `skip` (offset, defaut 0) et `limit` (max 200, defaut 50).
|
||||
|
||||
Reference in New Issue
Block a user