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

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