Wiki/.claude/workflows/sync-bidirec.md

# Workflow : SYNC BIDIREC Docmost ↔ Baserow

Orchestration de la synchronisation bidirectionnelle entre Docmost (wiki) et Baserow (DBs). Phase 2 — necessite que le bridge service soit deploye et operationnel.

Equivalent BYAN-natif : event-driven workflow avec idempotence.

## Trigger

L'un des suivants :
- Webhook Baserow `row.created` / `row.updated` / `row.deleted` sur table donnee
- Webhook Docmost `page.created` (si configure cote Docmost custom)
- Action explicite admin : "Sync forcee projet 42 → Docmost"
- Cron periodique de reconciliation (Phase 3+)

## Acteurs

- **bridge-dev** (handler webhook + sync logic)
- **acadenice-devops** (config webhooks + monitoring)
- **bridge-tester** (validation idempotence + anti-loop)
- **Corentin** (alerte si depassement capacite)

## Sequence — type webhook Baserow row.created sur table 'projet'

```
[1] Webhook recu (bridge endpoint POST /api/webhooks/baserow/projet-changed)
    - Verifier signature HMAC X-Baserow-Signature (anti-spoofing)
    - Si invalide : log + 401, ABORT
    - Output : event valide

[2] Idempotence check (bridge + Redis)
    - Lire payload event_id
    - Redis : SET bridge:webhook:event:<event_id> "1" EX 86400 NX
    - Si SET retourne null (key existait) : event deja traite, ABORT 200
    - Sinon : continue
    - Output : event nouveau, marque traite

[3] Anti-loop check
    - Verifier header X-Bridge-Origin sur la row Baserow
    - Si X-Bridge-Origin == "bridge" : c'est nous qui avons cree la row, ABORT
    - Sinon : c'est un user qui a cree, continue
    - Output : event source legitime

[4] Logique metier (bridge service)
    - Pour 'row.created' sur 'projet' :
      * Fetch projet detail depuis Baserow (BaserowClient.getRow)
      * Fetch client lie (BaserowClient.getRow)
      * Calcul nom de page Docmost : "Projet [nom] - [client]"
      * Determiner space cible : "Agence" → fetch space ID
    - Output : payload pour creation Docmost

[5] Action Docmost (bridge service via DocmostClient)
    - DocmostClient.createPage({ spaceId, title, content: template_projet(projet) })
    - Header : X-Bridge-Origin: bridge (eviter loop futur)
    - Output : pageId Docmost cree

[6] Update Baserow row (bridge service)
    - BaserowClient.updateRow(projet_id, { docmost_page_id: pageId })
    - Header : X-Bridge-Origin: bridge
    - Output : projet Baserow enrichi avec docmost_page_id

[7] Cache invalidation (bridge + Redis)
    - RedisCache.invalidatePattern("bridge:projet:*")
    - RedisCache.invalidatePattern("bridge:client:<id>:projets")
    - Output : caches invalides

[8] Notif si capacite formateur depassee (cas attribution)
    - Si event = creation 'attribution' :
      * Recalculer Personne.heures_restantes_total
      * Si < 0 : notifier admin via SMTP/Slack
    - Output : notification envoyee si depassement

[9] Audit log
    - Log structurel : { event_id, source: 'baserow', target: 'docmost', action: 'createPage', success: true, duration_ms, ... }
    - Output : trace persistee

[10] Reponse webhook
     - Return 200 OK { processed: true, page_id: <docmost_page_id> }
```

## Patterns specifiques par event

| Trigger | Action sync |
|---------|-------------|
| Baserow row.created sur `projet` | Auto-create page Docmost dans space Agence |
| Baserow row.created sur `formation` | Auto-create collection Docmost (sub-pages par bloc) |
| Baserow row.updated sur `projet`/`formation` (titre, statut) | Update title/icon page Docmost liee |
| Baserow row.created sur `intervention` | Check capacite → notify admin si depassement |
| Baserow row.created sur `attribution` | Notify formateur (email) + check capacite |
| Docmost page.created (template specifique 'compte-rendu') | Auto-create row dans table `comptes_rendus` Baserow (Phase 3+) |
| Docmost share.created | Log audit + notify admin (alerte data leak risk) |

## Gates humains

Aucun gate bloquant — c'est event-driven temps reel. Mais :
- Notif Corentin sur depassement capacite (asynchrone)
- Notif Corentin sur erreurs critiques (sync echec apres 3 retry)

## Rollback / gestion d'erreurs

| Echec | Strategy |
|-------|----------|
| Docmost API down | Retry 3x exponential backoff. Si tjrs KO : queue Redis pour retry batch |
| Baserow row introuvable (race condition) | Fetch retry x2 avec 200ms delay. Sinon : log + skip event |
| Cache invalidation echec | Log warning, continuer (TTL fallback 5 min) |
| Notification SMTP fail | Log warning, alerte degraded |
| Loop detecte (X-Bridge-Origin manquant cote bridge writes) | URGENT : alerte Corentin, audit code bridge |

## Anti-loop strategy (CRITICAL)

Pour eviter Docmost → bridge → Baserow → bridge → Docmost → ... boucle infinie :

1. **Header X-Bridge-Origin** : tous les writes du bridge vers Baserow et Docmost ajoutent ce header
2. **Detection cote handler** : si l'event provient d'une row/page avec ce flag, ABORT
3. **Idempotence event_id** : meme si une boucle se forme, max 1 cycle (TTL 24h en Redis)
4. **Rate limit** : max 1 sync identique / 5 min sur entite (cle: `bridge:sync:<entity>:<id>`)
5. **Monitoring** : alerter si > 10 events identiques en 1 min (signe de boucle)

## Outputs

- Pages Docmost crees automatiquement
- Rows Baserow enrichies avec ids Docmost (lien bidirec)
- Caches invalides
- Audit log evenement traite
- Notifications metier si necessaire

## Tests obligatoires

- **Test idempotence** : envoyer le meme event 5 fois → un seul effet (bridge-tester)
- **Test anti-loop** : simuler bridge-write → verifier que webhook ignore (bridge-tester)
- **Test rate limit** : 100 events identiques en 1 min → verifier que rate limit kick in
- **Test recovery** : Docmost down 5 min → events queues et processed apres recovery
- **Test webhook signature invalid** : event avec mauvais HMAC → 401 (bridge-tester)

## Exemple invocation

Trigger non-manuel — se declenche automatiquement quand Baserow envoie un webhook au bridge. Mais peut etre invoque manuellement pour :
- Reconciliation : "WF SYNC : force re-sync de tous les projets non-mappes vers Docmost"
- Debug : "WF SYNC : trace l'event ID xyz pour comprendre pourquoi il a abort"

## Notes

- Webhooks Baserow : a configurer cote Baserow UI ou API (apres deploy bridge)
- Endpoint signature secret : `BASEROW_WEBHOOK_SECRET` dans `.env` bridge
- Logs : toutes les operations sync sont loguees structurellement (Pino) avec event_id pour traceability