Обзор Collaboration SDK
Узнайте, какие задачи решает Univer Collaboration SDK, как устроены его модули и точки расширения и какие функции продукта остаются за приложением.
Univer Collaboration SDK — серверный SDK совместного редактирования для модели документов Univer. Он предоставляет операционное преобразование (OT1), ревизии2, снимки, синхронизацию в реальном времени и постоянное хранение, чтобы несколько клиентов Univer могли редактировать одну Unit с серверным эталонным состоянием.
Разработчики встраивают его в своё приложение Node.js, подключают идентификацию и авторизацию через Middleware, а журналирование и другую логику — через Middleware или Events. Database Adapter отдельно связывает данные совместной работы с базой данных приложения.
Это не готовый продукт для работы с документами
Collaboration SDK предоставляет ядро совместного редактирования. В нём нет пользователей, ролей, иерархии, общего доступа, файловых пространств и бизнес-процессов. Эти функции продукта и модели данных остаются ответственностью приложения.
Какие задачи он решает
Web SDK отображает и редактирует Sheet, Doc, Slide, Board и Base в браузере. Для многопользовательского редактирования также нужен сервер, который загружает содержимое, подтверждает параллельные изменения, продвигает ревизии и восстанавливает согласованное состояние отключившихся клиентов.
SDK подходит приложениям, которые:
- уже используют редактор на Univer и нуждаются в совместном редактировании в реальном времени;
- хотят самостоятельно хранить данные совместной работы и выбирать базу данных;
- должны применять существующие правила идентификации, авторизации или арендаторов к совместным операциям;
- нуждаются в History, Thread Comment или Worktree поверх базового совместного редактирования.
Полный сервис совместной работы
| Модуль | Основная ответственность |
|---|---|
| Collaboration Client | Загружает Units, отправляет наборы изменений и поддерживает состояние совместной работы в браузере |
| Node Transport | Принимает HTTP/WebSocket-трафик и выполняет входные middleware приложения |
UniverCollabEndpoint | Реализует клиентский протокол, Sessions, Rooms, Presence, ACK и рассылку |
UniverCollabService | Управляет жизненным циклом Unit, выполняет OT и подтверждает непрерывные ревизии |
| Database Adapter | Атомарно хранит снимки, наборы изменений, ревизии и состояние идемпотентности отправок |
Что предоставляет SDK
Основные возможности:
- создание, загрузка, удаление и восстановление Units Sheet, Doc, Slide, Board и Base;
- снимки, наборы изменений, ревизии, OT и идемпотентность отправок;
- загрузка содержимого по HTTP, а также Sessions, Rooms, Presence, ACK и рассылка по WebSocket;
- Middleware на границах Transport, Endpoint и Service;
- локальные для процесса Events создания Unit, фиксации изменений, удаления и восстановления;
- контракты Database Adapter для Memory, SQLite и собственных реализаций;
- горизонтальное масштабирование за счёт развёртывания на нескольких узлах: узлы взаимодействуют через pub/sub-адаптер и общее хранилище session tickets, реализация на Redis входит в SDK.
После запуска основного пути можно добавить историю версий, ветки комментариев, черновики Worktree и серверное преобразование файлов Office. У этих возможностей есть собственные Services, Middleware, Events или Database Adapters.
За что отвечает приложение
| Collaboration SDK | Приложение |
|---|---|
| Состояние совместной работы Unit | Пользователи, арендаторы, иерархия и связи общего доступа |
| OT, ревизии и снимки | Вход, Sessions и сопоставление идентификаторов |
| Sessions, Rooms и Presence совместной работы | Роли, ACL и политики продукта |
| Database Adapters совместной работы | Файлы, объектное хранилище и базы данных продукта |
| Точки расширения Middleware и Event | Журналирование, аудит, метрики и внешние интеграции |
| Endpoints клиентского протокола | Бизнес-API и процессы, например создание документов |
Три общие точки расширения
| Точка расширения | Какие задачи решает |
|---|---|
| Middleware | Проверяет или дополняет Context, отклоняет запросы или записывает ход обработки во время операции |
| Event | Наблюдает подтверждённые изменения для локального производного состояния или некритичных последующих действий |
| Database Adapter | Выбирает хранилище и реализует контракты атомарности, CAS и идемпотентности |
Идентификация и авторизация подключаются через Middleware. Используйте Middleware для проверок и ограничений до выполнения операции, а Events — для записи изменений и последующих действий после подтверждения состояния. Оба механизма подходят для журналирования, трассировки запросов, метрик и обновления производного состояния. Границы выполнения описаны в разделе Middleware и Events.
С чего начать
- Выполните быстрый старт и проверьте полный путь в двух браузерах.
- Прочитайте Границы и связи модулей, чтобы понять назначение пакетов.
- Перейдите к Middleware и Events, Идентификации и авторизации или Адаптерам баз данных в зависимости от задачи интеграции.
- History, комментарии, Worktree и преобразование файлов описаны в Модулях расширения совместной работы.
Footnotes
-
Операционная трансформация (OT) согласует одновременные операции, созданные на разных ревизиях документа. Она обрабатывает изменения, а не заменяет весь документ последним полученным снимком. ↩
-
Ревизия обозначает позицию в подтверждённой истории Unit. Changeset содержит операции одной отправки; их подтверждение продвигает историю. Ревизия не является версией SDK или меткой времени. ↩
Насколько полезно это руководство?