Modules d’extension de collaboration

History, Thread Comment, File et Worktree sont des modules indépendants, activables selon les besoins. Ils peuvent réutiliser le Transport, le système d’identité et la base physique, tout en conservant leurs propres frontières de Service, Middleware, Event, Database Adapter et cycle de vie.

La conversion Office côté serveur associe File et Collaboration Service : elle convertit entre fichiers Office et Units collaboratives, avec ses propres Service, Endpoint et Middleware.

Relations entre modules

History, Thread Comment, File et Worktree configurent chacun leurs Middleware, Events et Database Adapters.

Historique des versions

History regroupe la création d’Unit et les modifications confirmées en entrées d’historique visibles par l’utilisateur. C’est un index dérivé : les modifications confirmées dans le Collaboration Service central restent la source faisant autorité pour le contenu Unit.

const historyService = new UniverHistoryService({  collabService,  dbAdapter: historyDatabase,  userProvider,});transport.register(new UniverHistoryEndpoint(historyService));

Le constructeur s’abonne aux Events unitCreated et changesetCommitted du Service central et met l’index à jour. dispose() retire ces abonnements. La politique par défaut regroupe les changements par fenêtre temporelle et mutations particulières, au lieu de créer une entrée pour chaque jeu de modifications.

History expose des Middleware de lecture pour getHistoryList, listHistoryCreators et getHistoryChangesets. L’indexation s’exécute à l’intérieur du Service. userProvider enrichit uniquement les données d’affichage, comme les noms et avatars ; il n’authentifie ni n’autorise. L’échec d’un Event Listener n’annule pas une modification centrale déjà confirmée : History doit toujours être considéré comme une donnée dérivée reconstructible.

Commentaires en fil

Comment Service gère le corps des commentaires, les réponses, modifications, suppressions et états résolus pour Sheets et Docs :

const commentService = new UniverCommentService({  database: commentDatabase,  userProvider,});transport.register(  new UniverCommentEndpoint({    service: commentService,    roomHost: collabEndpoint,  }),);

Le corps des commentaires appartient au Comment Adapter. Les ancres qui suivent le contenu Sheet ou Doc restent dans les instantanés et modifications centraux. Le Comment Endpoint peut publier comment_update via la Room Unit du Collaboration Endpoint principal, mais le message temps réel n’est pas l’état faisant autorité ; le client peut récupérer l’état en relisant la liste des commentaires.

Comment Service fournit des Middleware d’ajout, de liste, de réponse, de résolution/réouverture, de modification et de suppression, ainsi qu’un Event commentCommitted. Il n’hérite pas des politiques de lecture ou d’édition du Service central.

Stockage de fichiers

File stocke les fichiers binaires envoyés par les clients Univer : images et pièces jointes insérées dans une Unit, ainsi que les fichiers source et résultat de l’import et de l’export. Les données de l’Unit n’enregistrent que l’ID du fichier ; le client le résout en URL de téléchargement au chargement, ce qui garde les snapshots et changesets légers.

const fileService = new UniverFileService({  database: fileDatabase,  blobStore,});transport.register(new UniverFileEndpoint(fileService));

Métadonnées et contenu sont deux contrats indépendants : IFileDatabaseAdapter stocke les enregistrements de fichier et IFileBlobStore le contenu. Les fichiers temporaires d’échange ne sont accessibles qu’à leur auteur et le Service les nettoie périodiquement ; les images et pièces jointes de l’Unit sont contrôlées par les droits de l’Unit via les Middleware upload, signUrl et download.

Conversion Office côté serveur

Exchange Service importe des fichiers Office en Units collaboratives et exporte des Units en fichiers. Il s’appuie sur @univerjs-pro/exchange-node pour la conversion, crée et lit les Units via Collaboration Service et stocke les fichiers source et résultat via File Service :

const exchangeService = new UniverExchangeService({ collabService, fileService });transport.register(new UniverExchangeEndpoint(exchangeService));

L’import et l’export sont des task : le client crée une task puis interroge le résultat. L’import passe par le Middleware createUnit du Core Service et l’export par readUnitData ; les Middleware import et export propres à Exchange couvrent limitation de débit, quotas et audit.

Les task vivent dans l’instance du Service : déployez un seul nœud d’import et d’export et routez-y les trois routes d’Exchange.

Brouillons Worktree et fusion

Worktree ajoute des brouillons isolés, le gel, l’évaluation de fusion et la fusion par Unit pour une ou plusieurs Units :

create → draft → ready → merging → merged           ↑       │           └ reopen┘draft / ready → discarded

const worktreeService = new UniverCollabWorktreeService({  trunk: {    service: collabService,    dbAdapter: coreDatabase,  },  dbAdapter: worktreeDatabase,});

Worktree stocke des modifications de brouillon indépendantes par (worktreeID, unitID) tout en réutilisant les moteurs Unit, OT et de soumission du Service central. Seul l’état draft accepte de nouvelles éditions. markReady() gèle la révision courante du brouillon et mergeWorktree() fusionne les Units une par une dans le tronc.

Worktree Service possède des Middleware indépendants de cycle de vie, lecture et soumission/application/commit de brouillon, ainsi que des Events de création, changement d’état, résultat de fusion et commit de modifications de brouillon. L’écriture finale dans le tronc traverse toujours les Middleware du Service central.

Une fusion multi-Unit n’est pas atomique entre Units. L’application doit afficher le résultat de chaque Unit.

Points d’extension indépendants

À l’activation d’un module, examinez chaque frontière séparément :

Ces Adapters peuvent utiliser la même base de données tout en restant des objets distincts aux contrats distincts. Services et Adapters se libèrent aussi indépendamment.

Office Exchange réutilise le stockage de Core et de File : après ses propres Middleware import et export, l’import et l’export passent toujours par les Middleware de Core et de File.

Choisir une fonction

Consultez l’index des exemples pour les commandes complètes et les URL des pages.

Connecter l’interface d’historique du Web SDK

Montez le History Endpoint avec les endpoints collaboratifs. historyServerUrl est le préfixe commun de /{unitId}/list, /{unitId}/creators et /{unitId}/cs, avec /universer-api/history par défaut. Si vous utilisez un autre chemin, configurez la même URL dans le plugin History de l’hôte et le plugin History UI du produit.

La restauration passe par une mutation collaborative, sans endpoint REST de restauration distinct. Conservez la configuration du chargement, de la soumission et des autorisations collaboratives. La comparaison en lecture seule de snapshots complets avec createUnitComparisonEngine() ne nécessite aucun service d’historique et ne conserve ni ne restaure les versions.