decision/docs/content/dev/10.spike-workflow-engine.md

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.

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