# Обзор Collaboration SDK

> Узнайте, какие задачи решает Univer Collaboration SDK, как устроены его модули и точки расширения и какие функции продукта остаются за приложением.

- Human documentation: [https://docs.univer.ai/ru-RU/server/collaboration/overview](https://docs.univer.ai/ru-RU/server/collaboration/overview)

- Agent Markdown: [https://docs.univer.ai/ru-RU/server/collaboration/overview.md](https://docs.univer.ai/ru-RU/server/collaboration/overview.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [collaboration/overview.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/server/collaboration/overview.ru-RU.mdx)

---

**Univer Collaboration SDK** — серверный SDK совместного редактирования для модели документов Univer. Он предоставляет операционное преобразование (OT[^operational-transformation]), ревизии[^collaboration-revision], снимки, синхронизацию в реальном времени и постоянное хранение, чтобы несколько клиентов Univer могли редактировать одну Unit с серверным эталонным состоянием.

Разработчики встраивают его в своё приложение Node.js, подключают идентификацию и авторизацию через Middleware, а журналирование и другую логику — через Middleware или Events. Database Adapter отдельно связывает данные совместной работы с базой данных приложения.

> [!NOTE: Это не готовый продукт для работы с документами]
> Collaboration SDK предоставляет ядро совместного редактирования. В нём нет пользователей, ролей, иерархии, общего доступа, файловых пространств и бизнес-процессов. Эти функции продукта и модели данных остаются ответственностью приложения.

## Какие задачи он решает

Web SDK отображает и редактирует Sheet, Doc, Slide, Board и Base в браузере. Для многопользовательского редактирования также нужен сервер, который загружает содержимое, подтверждает параллельные изменения, продвигает ревизии и восстанавливает согласованное состояние отключившихся клиентов.

SDK подходит приложениям, которые:

* уже используют редактор на Univer и нуждаются в совместном редактировании в реальном времени;
* хотят самостоятельно хранить данные совместной работы и выбирать базу данных;
* должны применять существующие правила идентификации, авторизации или арендаторов к совместным операциям;
* нуждаются в History, Thread Comment или Worktree поверх базового совместного редактирования.

## Полный сервис совместной работы

```mermaid
flowchart LR
    ClientA["Клиент A<br/>Web SDK + Collaboration Client"]
    ClientB["Клиент B<br/>Web SDK + Collaboration Client"]

    subgraph Server["Сервер совместной работы"]
        direction LR
        Transport["Node Transport"]
        Endpoint["Collaboration Endpoint"]
        Service["Collaboration Service"]
        Adapter["Database Adapter"]

        Transport --> Endpoint --> Service --> Adapter
    end

    Database[(База данных)]

    ClientA -->|"HTTP / WebSocket"| Transport
    ClientB -->|"HTTP / WebSocket"| Transport
    Adapter --> Database
```

| Модуль                 | Основная ответственность                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| 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](https://docs.univer.ai/ru-RU/server/collaboration/middleware-and-events.md).

## С чего начать

1. Выполните [быстрый старт](https://docs.univer.ai/ru-RU/server/collaboration/quick-start.md) и проверьте полный путь в двух браузерах.
2. Прочитайте [Границы и связи модулей](https://docs.univer.ai/ru-RU/server/collaboration/modules.md), чтобы понять назначение пакетов.
3. Перейдите к [Middleware и Events](https://docs.univer.ai/ru-RU/server/collaboration/middleware-and-events.md), [Идентификации и авторизации](https://docs.univer.ai/ru-RU/server/collaboration/identity-and-authorization.md) или [Адаптерам баз данных](https://docs.univer.ai/ru-RU/server/collaboration/database-adapters.md) в зависимости от задачи интеграции.
4. History, комментарии, Worktree и преобразование файлов описаны в [Модулях расширения совместной работы](https://docs.univer.ai/ru-RU/server/collaboration/extensions.md).

[^operational-transformation]: Операционная трансформация (OT) согласует одновременные операции, созданные на разных ревизиях документа. Она обрабатывает изменения, а не заменяет весь документ последним полученным снимком.

[^collaboration-revision]: Ревизия обозначает позицию в подтверждённой истории Unit. Changeset содержит операции одной отправки; их подтверждение продвигает историю. Ревизия не является версией SDK или меткой времени.