Concevoir un node
Un node est un contrat durable du Process Editor. Il doit représenter une opération métier utile à composer dans un graphe, pas la simple disponibilité d’un endpoint ou d’une fonction partenaire.
Quand introduire un node
Un nouveau node est justifié lorsque les cinq conditions suivantes sont réunies :
- un use case de processus concret existe ;
- l’extension détient l’autorité nécessaire à l’effet ou à l’observation ;
- la composition d’éléments existants ne résout pas déjà le besoin proprement ;
- la valeur durable compense le coût de maintenance du contrat ;
- le node ne sert pas uniquement à compléter une symétrie CRUD.
Scalar, Each ou collection
Gardez un contrat scalaire lorsque chaque élément peut être traité indépendamment. Le mécanisme Each porte alors la répétition.
Exposez directement une collection lorsque connaître les autres éléments change réellement le traitement : agrégation, déduplication, comportement batch du partenaire, coordination, stratégie de rate limit ou règle de complétude.
Utilisez un sous-processus par élément lorsque chaque item nécessite lui-même routage, attentes ou interactions humaines.
Inputs et outputs
- préférez un objet métier typé à un identifiant brut lorsque le node a besoin du contexte complet ;
- demandez directement la propriété précise lorsque le node n’a besoin que d’une valeur, par exemple un email ;
- un output doit apporter une nouvelle valeur ou une nouvelle garantie, pas réémettre un input inchangé ;
- un output
platform.*doit être complet et conforme au contrat canonique ; - les projections d ’affichage ne doivent pas dupliquer le contrat d’outputs uniquement pour enrichir la carte UI.
Drafts et mutations
Créez un draft aussi tard que possible, une fois les données nécessaires à son handoff connues. N’introduisez pas de node update_*_draft par défaut uniquement parce qu’un backend permet la mutation progressive.
Une mutation doit rester explicite. Ne mélangez pas une lecture avec un effet caché, et ne masquez pas un échec métier dans un warning ou un output de succès.
Naming et labels
Un node d’extension utilise l’identité canonique <extension_key>.<snake_case>, par exemple stripe.ensure_customer. Le préfixe doit être exactement metadata.name de l’extension. Les exécutables Core utilisent le namespace réservé ormuz dans les artefacts de processus ; une extension ne doit jamais emprunter ce namespace.
Le label utilisateur décrit l’opération en sentence case et avec un verbe métier clair.
Évitez les noms orientés implémentation comme « helper », « handler » ou « API call ». Le designer doit comprendre le résultat métier sans connaître le code partenaire.