Refonte Structure

knowledge/backend/patterns/async.md

@@ -0,0 +1,79 @@
+# Backend — Patterns : Async
+
+> Extrait de la base de connaissance Lead_tech. Voir `knowledge/backend/patterns/README.md` pour l'index complet.
+
+---
+
+<a id="pattern-execution-asynchrone-taches-longues"></a>
+
+## Pattern : Exécution asynchrone des tâches longues (queue + outbox light)
+
+- Objectif : sortir les opérations longues ou fragiles du chemin request/response.
+- Contexte : envoi d'emails, appels SaaS, génération de PDF, traitements batch, webhooks sortants.
+- Quand l'utiliser : dès qu'une opération peut dépasser la latence acceptable ou dépendre d'un service externe.
+- Quand l'éviter : opérations réellement instantanées et sans dépendances externes.
+- Avantage :
+  - API plus rapide et plus fiable
+  - Retries maîtrisés
+  - Meilleure résilience aux pannes externes
+- Limites / vigilance :
+  - Demande une discipline stricte sur l'idempotence
+  - Nécessite une stratégie minimale de dead-letter ou d'alerting
+- Validé le : 25-01-2026
+- Contexte technique : Backend agnostique + DB transactionnelle + worker
+
+### Implémentation (exemple minimal)
+
+```txt
+- API écrit un job ou event en DB dans la transaction métier
+- Worker lit les jobs en attente et exécute
+- Retries avec backoff + compteur
+- Statut FAILED ou dead-letter + alerte
+- Idempotence par clé métier ou idempotency key
+```
+
+### Checklist
+
+- Job créé dans une transaction (évite les pertes)
+- Retries et backoff définis
+- Dead-letter ou statut FAILED visible
+- Idempotence garantie
+- Logs corrélés (requestId/traceId)
+
+---
+
+<a id="pattern-webhooks-sortants-robustes-idempotents"></a>
+
+## Pattern : Webhooks sortants robustes et idempotents
+
+- Objectif : garantir des intégrations fiables avec des systèmes externes.
+- Contexte : notifications, synchronisations, événements métier sortants.
+- Quand l'utiliser : dès qu'un événement doit être transmis à un tiers.
+- Quand l'éviter : intégrations strictement synchrones et internes.
+- Avantage :
+  - Tolérance aux pannes réseau
+  - Retries maîtrisés
+  - Observabilité des échecs
+- Limites / vigilance :
+  - Gestion des retries et du volume
+  - Nécessite une idempotence côté consommateur
+- Validé le : 25-01-2026
+- Contexte technique : Backend + HTTP + worker/queue
+
+### Implémentation (exemple minimal)
+
+```txt
+- Événement persisté (outbox) en DB
+- Envoi asynchrone via worker
+- Retries avec backoff
+- Signature du payload (HMAC)
+- Idempotency key dans le header
+```
+
+### Checklist
+
+- Payload signé et vérifiable
+- Retries + backoff définis
+- Dead-letter ou statut FAILED visible
+- Idempotence documentée
+- Logs corrélés (requestId/traceId)