Restructure Engagement Forgeron + fix GenesisBlock + InertiaSlider
- Seed: restructure Engagement Forgeron (51→59 items) avec 3 nouvelles sections: Engagements fondamentaux (EF1-EF3), Engagements techniques (ET1-ET3), Qualification (Q0-Q1) liée au protocole Embarquement - Seed: ajout protocole Embarquement Forgeron (5 jalons: candidature, miroir, évaluation, certification Smith, mise en ligne) - GenesisBlock: fix lisibilité — fond mood-surface teinté accent au lieu de mood-text inversé, texte mood-aware au lieu de rgba blanc hardcodé - InertiaSlider: mini affiche "Inertie" sous le curseur, compact en width:fit-content pour s'adapter au label - Frontend: ajout section qualification dans SECTION_META/SECTION_ORDER - Pages, composants et tests des sprints précédents Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
239
docs/content/dev/10.spike-workflow-engine.md
Normal file
239
docs/content/dev/10.spike-workflow-engine.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Spike : Moteur de workflow — Protocole Embarquement Forgerons
|
||||
|
||||
**Date** : 2026-03-02
|
||||
**Statut** : Spike / Pré-étude
|
||||
**Auteur** : Yvv + Claude
|
||||
|
||||
---
|
||||
|
||||
## Contexte : deux objets distincts
|
||||
|
||||
L'app a déjà deux concepts qui se côtoient dans "Protocoles" :
|
||||
|
||||
| Objet | Ce que c'est | Exemple |
|
||||
|-------|-------------|---------|
|
||||
| **VotingProtocol** | Règle de vote (formule, seuils, critères) | "Vote forgeron (Smith)" — D30M50B.1G.2S.1 |
|
||||
| **Decision + Steps** | Processus multi-étapes (one-shot) | "Runtime Upgrade" — 5 étapes séquentielles |
|
||||
|
||||
Il manque un **troisième** objet : le **Protocole opérationnel réutilisable** — un template de workflow qui s'instancie pour chaque candidat/cas.
|
||||
|
||||
### Exemple : Embarquement Forgerons
|
||||
|
||||
Ce n'est pas une décision ponctuelle. C'est un **processus répétable** :
|
||||
|
||||
```
|
||||
[Candidat] ──invite──▶ [Invitation on-chain]
|
||||
│
|
||||
◀──accept──
|
||||
│
|
||||
──setSessionKeys──▶ [Preuve technique]
|
||||
│
|
||||
┌──checklist aspirant (aléatoire, avec pièges)
|
||||
│
|
||||
├──certif smith 1 (checklist certificateur)
|
||||
├──certif smith 2 (checklist certificateur)
|
||||
└──certif smith 3 (checklist certificateur)
|
||||
│
|
||||
──goOnline──▶ [Autorité active]
|
||||
```
|
||||
|
||||
Chaque étape a :
|
||||
- Un **acteur** (candidat, certificateur, système)
|
||||
- Des **prérequis** (étapes précédentes complétées)
|
||||
- Une **preuve** (on-chain tx, checklist complétée, vote)
|
||||
- Un **délai** (optionnel)
|
||||
|
||||
---
|
||||
|
||||
## Volume croissant prévisible
|
||||
|
||||
| Protocole opérationnel | Acteurs | Instances/an estimées |
|
||||
|----------------------|---------|----------------------|
|
||||
| Embarquement Forgerons | candidat + 3 certifieurs | ~10-50 |
|
||||
| Embarquement Membre (Certification) | certifié + 5 certifieurs | ~500-2000 |
|
||||
| Runtime Upgrade | CoTec + forgerons + communauté | ~4-12 |
|
||||
| Modification Document | proposeur + communauté | ~10-50 |
|
||||
| Mandat (élection/révocation) | candidat + communauté | ~5-20 |
|
||||
| Engagement CoTec | candidat + CoTec | ~2-5 |
|
||||
|
||||
**Observation clé** : l'Embarquement Membre est le plus massif et partage la même structure que l'Embarquement Forgeron (checklist + certifications multiples). L'architecture doit être pensée pour ce volume.
|
||||
|
||||
---
|
||||
|
||||
## Options évaluées
|
||||
|
||||
### Option A : n8n (workflow automation)
|
||||
|
||||
**n8n** est un outil d'automatisation visuel (self-hosted, open source).
|
||||
|
||||
| Pour | Contre |
|
||||
|------|--------|
|
||||
| Éditeur visuel de workflows | Dépendance externe lourde (~500 MB Docker) |
|
||||
| Webhooks, triggers, crons intégrés | Latence réseau (appels HTTP entre services) |
|
||||
| 400+ intégrations (email, matrix, etc.) | Pas de MCP server configuré actuellement |
|
||||
| Pas de code à écrire pour l'orchestration | Pas de concept natif de "checklist aléatoire" |
|
||||
| | Les preuves on-chain nécessitent du dev custom de toute façon |
|
||||
| | La communauté Duniter refuse les dépendances centralisées |
|
||||
|
||||
**Verdict** : n8n est excellent pour les **automations périphériques** (notifications, alertes, reporting), pas pour le **cœur du workflow**. Le cœur doit rester dans l'app.
|
||||
|
||||
**Usage recommandé de n8n** : connecteur optionnel pour les triggers de notification (webhook quand une étape change de statut → email/matrix/telegram). Ne pas en faire le moteur.
|
||||
|
||||
### Option B : Dev maison — étendre Decision/DecisionStep
|
||||
|
||||
Étendre le modèle `Decision` existant avec un concept de **template**.
|
||||
|
||||
```python
|
||||
class ProcessTemplate(Base):
|
||||
"""Reusable workflow template (e.g. "Embarquement Forgeron")."""
|
||||
id: UUID
|
||||
slug: str # "embarquement-forgeron"
|
||||
name: str # "Embarquement Forgerons"
|
||||
description: str
|
||||
category: str # "onboarding", "governance", "upgrade"
|
||||
step_templates: JSON # Ordered list of step definitions
|
||||
checklist_document_id: UUID # FK to Document (engagement forgeron)
|
||||
voting_protocol_id: UUID # FK to VotingProtocol
|
||||
is_active: bool
|
||||
|
||||
class ProcessInstance(Base):
|
||||
"""One execution of a template (e.g. "Embarquement de Matograine")."""
|
||||
id: UUID
|
||||
template_id: UUID # FK to ProcessTemplate
|
||||
candidate_id: UUID # FK to DuniterIdentity (le candidat)
|
||||
status: str # invited, accepted, keys_set, checklist, certifying, online, failed
|
||||
current_step: int
|
||||
started_at: datetime
|
||||
completed_at: datetime | None
|
||||
metadata: JSON # on-chain tx hashes, certifier IDs, etc.
|
||||
|
||||
class ProcessStepExecution(Base):
|
||||
"""One step within an instance."""
|
||||
id: UUID
|
||||
instance_id: UUID
|
||||
step_order: int
|
||||
step_type: str # "on_chain", "checklist", "certification", "manual"
|
||||
actor_id: UUID | None # Who must act
|
||||
status: str # pending, active, completed, failed, skipped
|
||||
proof: JSON | None # tx_hash, checklist_result, vote_session_id
|
||||
started_at: datetime | None
|
||||
completed_at: datetime | None
|
||||
```
|
||||
|
||||
| Pour | Contre |
|
||||
|------|--------|
|
||||
| Zéro dépendance externe | Plus de code à écrire |
|
||||
| Contrôle total sur la checklist (ordre aléatoire, pièges) | Faut designer le moteur de transitions |
|
||||
| Les preuves on-chain sont natives (substrate-interface) | Le workflow avancé (timeouts, escalation) sera simpliste |
|
||||
| S'intègre avec le vote engine existant | |
|
||||
| La DB track tout (audit trail complet) | |
|
||||
| Volume OK avec PostgreSQL (100k instances/an = rien) | |
|
||||
|
||||
**Verdict** : c'est la voie naturelle. Le modèle actuel `Decision + Steps` est une version simplifiée de ça. On l'étend proprement.
|
||||
|
||||
### Option C : Temporal.io / autre moteur de workflow distribué
|
||||
|
||||
| Pour | Contre |
|
||||
|------|--------|
|
||||
| Garanties transactionnelles fortes | Énorme pour le use case (~GB de RAM) |
|
||||
| Retry/timeout/escalation natifs | Cluster Temporal = infra supplémentaire |
|
||||
| Bon pour les longs workflows (jours/semaines) | Surcharge conceptuelle |
|
||||
| | Aucune intégration native blockchain |
|
||||
|
||||
**Verdict** : overkill. À considérer uniquement si on dépasse 10 protocoles actifs avec des centaines d'instances simultanées. Pas avant 2028.
|
||||
|
||||
---
|
||||
|
||||
## Recommandation
|
||||
|
||||
### Sprint 2 : Option B — Dev maison, progressif
|
||||
|
||||
**Phase 1** (Sprint 2) — Fondations :
|
||||
1. Créer `ProcessTemplate` + `ProcessInstance` + `ProcessStepExecution`
|
||||
2. Seed : template "Embarquement Forgerons" avec ses 7 étapes
|
||||
3. Frontend : page `/protocols/embarquement-forgerons` avec timeline visuelle
|
||||
4. API : `POST /processes/{template_slug}/start` → crée une instance
|
||||
5. API : `POST /processes/instances/{id}/advance` → passe à l'étape suivante
|
||||
|
||||
**Phase 2** (Sprint 3) — Checklist interactive :
|
||||
1. UI de checklist avec ordre aléatoire + détection pièges
|
||||
2. Liaison avec le Document (engagement forgeron) pour les clauses
|
||||
3. Signature Ed25519 du résultat de checklist (preuve cryptographique)
|
||||
|
||||
**Phase 3** (Sprint 4+) — On-chain :
|
||||
1. Trigger on-chain via substrate-interface (invite, accept, certify, goOnline)
|
||||
2. Listener d'événements blockchain pour compléter automatiquement les étapes on-chain
|
||||
3. Optionnel : webhook n8n pour notifications matrix/telegram
|
||||
|
||||
### Architecture cible
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Frontend │
|
||||
│ /protocols/embarquement-forgerons │
|
||||
│ ├── Vue template (timeline, étapes) │
|
||||
│ ├── Checklist interactive (aléatoire + pièges) │
|
||||
│ └── Instance dashboard (candidats en cours) │
|
||||
└──────────────────┬──────────────────────────────┘
|
||||
│ API REST
|
||||
┌──────────────────▼──────────────────────────────┐
|
||||
│ Backend │
|
||||
│ ProcessService │
|
||||
│ ├── create_instance(template, candidate) │
|
||||
│ ├── advance_step(instance, proof) │
|
||||
│ ├── evaluate_checklist(instance, answers) │
|
||||
│ └── on_chain_trigger(instance, extrinsic) │
|
||||
│ │
|
||||
│ SubstrateService (substrate-interface) │
|
||||
│ ├── smithsMembership.invite() │
|
||||
│ ├── smithsMembership.acceptInvitation() │
|
||||
│ ├── smithsMembership.setSessionKeys() │
|
||||
│ └── authorityMembers.goOnline() │
|
||||
└──────────────────┬──────────────────────────────┘
|
||||
│ Events
|
||||
┌──────────────────▼──────────────────────────────┐
|
||||
│ n8n (optionnel) │
|
||||
│ Webhook → Notification matrix/telegram/email │
|
||||
│ Cron → Relance candidats inactifs │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Ce que n8n ne fait PAS (et qu'on doit coder) :
|
||||
- Checklist aléatoire avec clause piège et interruption
|
||||
- Signature Ed25519 du résultat
|
||||
- Appels substrate-interface (invite, certify, goOnline)
|
||||
- Calcul de seuil unani-majoritaire
|
||||
- Intégrité du workflow (preuve on-chain de chaque étape)
|
||||
|
||||
### Ce que n8n PEUT faire (optionnel, sprint 4+) :
|
||||
- Webhook → notification email quand un candidat arrive à l'étape "certification"
|
||||
- Cron → rappel hebdo aux certificateurs qui n'ont pas agi
|
||||
- Webhook → post forum automatique quand un forgeron est accepté
|
||||
- Dashboard monitoring (combien de candidats en cours, taux de completion)
|
||||
|
||||
---
|
||||
|
||||
## Nomenclature proposée dans l'UI
|
||||
|
||||
| Menu | Sous-section | Contenu |
|
||||
|------|-------------|---------|
|
||||
| **Protocoles** | Protocoles de vote | VotingProtocol (binaire, nuancé, smith, techcomm) |
|
||||
| | Simulateur de formules | FormulaConfig interactif |
|
||||
| | **Protocoles opérationnels** | ProcessTemplate (embarquement, upgrade, etc.) |
|
||||
| **Décisions** | (inchangé) | Decision + Steps (instances one-shot) |
|
||||
|
||||
Les protocoles opérationnels ont leur propre section dans `/protocols` avec :
|
||||
- Carte par template (nom, description, nb d'instances actives)
|
||||
- Page détail : timeline template + liste d'instances en cours
|
||||
- Page instance : suivi temps réel d'un candidat spécifique
|
||||
|
||||
---
|
||||
|
||||
## Prochaine étape
|
||||
|
||||
Valider cette orientation avec Yvv, puis :
|
||||
1. Créer les 3 tables (ProcessTemplate, ProcessInstance, ProcessStepExecution)
|
||||
2. Migration Alembic
|
||||
3. Seed le template "Embarquement Forgerons" (7 étapes)
|
||||
4. Router + service backend
|
||||
5. Frontend : page template + page instance
|
||||
Reference in New Issue
Block a user