Módulos de extensión de colaboración

History, Thread Comment, File y Worktree son módulos independientes que se activan según las necesidades. Pueden reutilizar Transport, el sistema de identidad y la base física, pero mantienen sus propios límites de Service, Middleware, Event, Database Adapter y ciclo de vida.

La conversión Office del servidor combina File con Collaboration Service: convierte entre archivos Office y Units colaborativas, con su propio Service, Endpoint y Middleware.

Relaciones entre módulos

History, Thread Comment, File y Worktree configuran sus propios Middleware, Events y Database Adapters.

Historial de versiones

History agrupa la creación de Units y los cambios confirmados en entradas visibles para el usuario. Es un índice derivado: los cambios confirmados en el Collaboration Service principal siguen siendo la fuente autoritativa del contenido Unit.

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

El constructor se suscribe a los Events unitCreated y changesetCommitted del Service principal y actualiza el índice. dispose() elimina esas suscripciones. La política predeterminada agrupa cambios por ventana temporal y mutaciones especiales, en vez de crear una entrada por cada conjunto de cambios.

History expone Middleware de lectura para getHistoryList, listHistoryCreators y getHistoryChangesets. La indexación se ejecuta dentro del Service. userProvider solo amplía datos de presentación, como nombres y avatares; no autentica ni autoriza. El fallo de un Event Listener no revierte un cambio principal ya confirmado, por lo que History siempre debe tratarse como datos derivados reconstruibles.

Comentarios en hilos

Comment Service gestiona cuerpos de comentarios, respuestas, ediciones, eliminación y estado resuelto para Sheets y Docs:

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

El cuerpo del comentario pertenece al Comment Adapter. Los anclajes que se mueven con el contenido Sheet o Doc permanecen en las instantáneas y cambios principales. Comment Endpoint puede publicar comment_update por la Room Unit del Collaboration Endpoint principal, pero ese mensaje en tiempo real no es el estado autoritativo: el cliente puede recuperarlo consultando otra vez los comentarios.

Comment Service ofrece Middleware para añadir, listar, responder, resolver/reabrir, editar y eliminar, más un Event commentCommitted. No hereda las políticas de lectura o edición del Service principal.

Almacenamiento de archivos

File almacena los archivos binarios que suben los clientes Univer: imágenes y adjuntos insertados en una Unit, además de los archivos de origen y resultado de la importación y exportación. Los datos de la Unit solo registran el ID del archivo; el cliente resuelve el ID a una URL de descarga al cargar, así que snapshots y changesets se mantienen pequeños.

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

Metadatos y contenido son dos contratos independientes: IFileDatabaseAdapter guarda los registros de archivo e IFileBlobStore guarda el contenido. Los archivos temporales de intercambio solo son accesibles para quien los subió y el Service los limpia periódicamente; las imágenes y adjuntos de la Unit se controlan con los permisos de la Unit mediante el Middleware upload, signUrl y download.

Conversión Office del lado del servidor

Exchange Service importa archivos Office como Units colaborativas y exporta Units como archivos. Depende de @univerjs-pro/exchange-node para la conversión, crea y lee Units a través de Collaboration Service y guarda los archivos de origen y resultado a través de File Service:

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

Importación y exportación son task: el cliente crea una task y consulta el resultado. La importación pasa por el Middleware createUnit del Core Service y la exportación por readUnitData; el Middleware propio import y export de Exchange cubre límites de tasa, cuotas y auditoría.

Las task viven en la instancia del Service, así que despliega un único nodo de importación y exportación y enruta a él las tres rutas de Exchange.

Borradores Worktree y fusión

Worktree añade borradores aislados, congelación, evaluación de fusión y fusión por Unit para una o varias Units:

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

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

Worktree almacena cambios de borrador independientes por (worktreeID, unitID) y reutiliza los motores Unit, OT y de envío del Service principal. Solo draft admite más ediciones. markReady() congela la revisión actual del borrador y mergeWorktree() fusiona las Units en el tronco una a una.

Worktree Service tiene Middleware independientes de ciclo de vida, lectura y envío/aplicación/commit de borrador, además de Events de creación, cambios de estado, resultados de fusión y commits de cambios de borrador. La escritura final al tronco sigue pasando por el Middleware del Service principal.

Una fusión multi-Unit no es atómica entre Units. La aplicación debe mostrar el resultado de cada Unit.

Puntos de extensión independientes

Al activar un módulo, evalúa cada límite por separado:

Estos Adapters pueden usar la misma base de datos y seguir siendo objetos separados con contratos distintos. Services y Adapters también deben liberarse por separado.

Office Exchange reutiliza el almacenamiento de Core y File: tras ejecutar su propio Middleware import y export, la importación y la exportación siguen pasando por el Middleware de Core y File.

Elegir una función

Consulta el índice de ejemplos para los comandos completos y las URL de las páginas.

Conectar la interfaz de historial de Web SDK

Monta History Endpoint junto con los endpoints colaborativos. historyServerUrl es el prefijo común de /{unitId}/list, /{unitId}/creators y /{unitId}/cs; su valor predeterminado es /universer-api/history. Si utilizas otra ruta, configura la misma URL en el plugin History del editor principal y en el plugin History UI del producto.

La restauración se envía como una mutación colaborativa, no mediante un endpoint REST de restauración independiente. Mantén la configuración de carga, envío y autorización colaborativa. La comparación de solo lectura de snapshots completos con createUnitComparisonEngine() no necesita un servicio de historial y no conserva ni restaura versiones.