87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 📝 Guide Édition & collaboration temps réel
|
|
|
|
Plusieurs utilisateurs peuvent éditer le **même document Markdown
|
|
simultanément**, façon Google Docs, grâce à Yjs (CRDT) et à un canal WebSocket.
|
|
Ce guide explique le fonctionnement et l'utilisation.
|
|
|
|
> **Public :** tous les utilisateurs · **Fiche technique :**
|
|
> [`features/collaboration.md`](../features/collaboration.md)
|
|
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [API REST](./API_REST.md)
|
|
|
|
---
|
|
|
|
## 1. Ce que fait la collaboration
|
|
|
|
- **Fusion sans conflit** via **Yjs (CRDT)** : deux personnes peuvent taper au
|
|
même endroit, aucune modification n'est perdue.
|
|
- **Curseurs distants colorés** et sélections visibles dans CodeMirror, étiquetés
|
|
avec le nom de chaque utilisateur.
|
|
- **Indicateur de présence** dans l'en-tête de l'éditeur (avatars + statut de
|
|
connexion).
|
|
- **Reconnexion automatique** (backoff exponentiel) : l'état est fusionné au retour.
|
|
- **Persistance serveur** : le document est écrit sur disque **2 s** après la
|
|
dernière modification.
|
|
|
|
---
|
|
|
|
## 2. Utilisation
|
|
|
|
Aucune configuration n'est nécessaire :
|
|
|
|
1. Ouvrez le même fichier dans **deux navigateurs** (ou deux fenêtres).
|
|
2. Passez en mode **Editer** (ou **Forge**) dans les deux.
|
|
3. Tapez : les modifications apparaissent en temps réel des deux côtés, avec les
|
|
curseurs de chacun.
|
|
|
|
> L'édition collaborative nécessite que la vault soit **accessible en écriture**
|
|
> (le volume Docker doit être monté **sans** `:ro` pour les vaults modifiables).
|
|
|
|
---
|
|
|
|
## 3. Transport & protocole
|
|
|
|
| Élément | Valeur |
|
|
|---|---|
|
|
| Endpoint | `ws(s)://<hôte>/ws/collab/{vault}/{chemin}` |
|
|
| Authentification | Cookie `access_token` (ou paramètre `?token=`) |
|
|
| Autorisation | Contrôle d'accès **par vault** appliqué à chaque connexion |
|
|
| Protocole | Yjs / CRDT — updates + awareness (curseurs) |
|
|
| Persistance | Écriture disque débouncée (2 s) côté serveur |
|
|
|
|
Le canal est mis à niveau à partir de la même origine que l'application. Derrière
|
|
un reverse proxy, autorisez les **upgrades WebSocket** et augmentez
|
|
`proxy_read_timeout` (voir [Déploiement Docker](./DEPLOIEMENT_DOCKER.md)).
|
|
|
|
---
|
|
|
|
## 4. Sécurité
|
|
|
|
- L'accès au document est **revérifié à la connexion** (permissions du compte).
|
|
- Un utilisateur sans droit sur la vault ne peut pas rejoindre la session.
|
|
- Les échanges passent par le même domaine que l'application (pas de serveur
|
|
tiers).
|
|
|
|
---
|
|
|
|
## 5. Limitations & bonnes pratiques
|
|
|
|
- La collaboration vise les fichiers **Markdown**.
|
|
- Évitez d'éditer le même fichier simultanément depuis ObsiGate **et** une
|
|
application de synchronisation externe (risque de conflits au niveau fichier).
|
|
- Le document est écrit après un court délai ; attendez la fin de la sauvegarde
|
|
avant de fermer brutalement l'onglet.
|
|
- En cas de conflit de synchronisation externe (Syncthing), l'écran
|
|
**Conflits** (`/api/conflicts`) aide à résoudre.
|
|
|
|
---
|
|
|
|
## 6. Dépannage
|
|
|
|
| Symptôme | Piste |
|
|
|---|---|
|
|
| Les curseurs des autres n'apparaissent pas | Vérifier le WebSocket (proxy sans support `Upgrade`) |
|
|
| Reconnecté sans cesse | Réseau instable ou timeout proxy trop court |
|
|
| Modifications non persistées | Vault montée en lecture seule (`:ro`) ? |
|
|
| `401` à la connexion | Session expirée — se reconnecter |
|
|
| Accès refusé | Le compte n'a pas la permission sur cette vault |
|