Команды и совместная работа

DocPlatform создан для командной работы над документацией. Приглашайте участников, назначайте гранулярные роли и отслеживайте каждое изменение с помощью полного журнала аудита.

Участники workspace

Каждый пользователь принадлежит одному или нескольким workspaces с определенной ролью. Роли определяют, какие действия может выполнять пользователь.

Приглашение участников

Через веб-интерфейс:

  1. Откройте Workspace Settings -> Members
  2. Нажмите Invite Member
  3. Введите email-адрес приглашаемого
  4. Выберите роль
  5. Нажмите Send

Если настроен SMTP, отправляется email с приглашением и уникальной ссылкой. Без SMTP ссылка-приглашение отображается на экране — скопируйте и передайте ее вручную.

Через API:

curl -X POST http://localhost:3000/api/v1/workspaces/{workspace-id}/invitations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "editor"
  }'

Удаление участников

Администраторы workspace могут удалять участников через Settings -> Members -> выберите пользователя -> Remove.

Удаление участника немедленно отзывает его доступ. Предыдущие правки и записи журнала аудита сохраняются.

Изменение ролей

Нажмите на текущую роль участника, чтобы изменить ее. Изменения ролей вступают в силу немедленно — активные сессии обновляются при следующем API-вызове.

Роли

DocPlatform использует 5-уровневую иерархию ролей. Более высокие роли наследуют все права более низких ролей.

Super Admin
    └── Admin
            └── Editor
                  └── Commenter
                        └── Viewer
Роль Область действия Возможности
Viewer Workspace Просмотр страниц и поиск
Commenter Workspace Просмотр + комментирование страниц
Editor Workspace Просмотр + комментирование + редактирование страниц (создание/удаление настраивается для каждого workspace)
Admin Workspace Полное управление workspace (настройки, git, тема, участники)
Super Admin Платформа Полный доступ ко всем workspaces + настройкам платформы

Роль по умолчанию для новых участников

Настройте роль по умолчанию, назначаемую при принятии приглашения:

# .docplatform/config.yaml
permissions:
  default_role: viewer

Доступ на уровне страницы

Ограничьте доступ к отдельным страницам для определенных ролей с помощью frontmatter:

---
title: Internal Runbook
access:
  roles: ["sre-team", "admin"]
  users: []
---

Страницы с правилами access невидимы для пользователей без необходимой роли — они не отображаются в результатах поиска, навигации или опубликованной документации. Правила доступа могут только ограничивать в рамках роли пользователя, но не предоставлять доступ сверх неё.

Присутствие в реальном времени

Когда несколько пользователей активны в одном workspace, веб-редактор показывает, кто онлайн:

  • Индикаторы на боковой панели — цветные точки рядом со страницами, которые просматриваются или редактируются другими пользователями
  • Стек аватаров — аватары пользователей в заголовке страницы, показывающие, кто еще просматривает текущую страницу

Присутствие работает через WebSocket и обновляется в реальном времени.

Как работает присутствие

Параметр Значение
Протокол WebSocket (аутентификация через одноразовый ticket)
Интервал heartbeat Каждые 30 секунд
Тайм-аут отключения 90 секунд без heartbeat
События presence-join (первое подключение), presence-leave (тайм-аут или отключение)
Буфер 256 событий на workspace (предотвращает backpressure)

WebSocket-соединение также доставляет события контента в реальном времени:

Событие Когда
page-created Создана новая страница (из любого источника)
page-updated Страница изменена (из любого источника)
page-deleted Страница удалена
sync-status Изменение статуса синхронизации git (synced, ahead, behind, conflict)
conflict-detected Обнаружен конфликт слияния git
bulk-sync 20+ файлов синхронизировано за одну операцию (одно уведомление, а не по одному на файл)

Одновременное редактирование

DocPlatform не поддерживает совместное редактирование в реальном времени (в стиле Google Docs). Если два пользователя одновременно редактируют одну страницу:

  1. Первое сохранение проходит успешно
  2. Второе сохранение инициирует обнаружение конфликта (HTTP 409)
  3. Обе версии сохраняются для ручного разрешения

Для предотвращения конфликтов:

  • Используйте соглашение о владении страницами (один автор на страницу в каждый момент времени)
  • Индикаторы присутствия помогают координировать, кто что редактирует
  • Для команд с высокой конкурентностью рассмотрите более короткие интервалы синхронизации git

Журнал аудита

Каждая мутация контента логируется с указанием:

Поле Описание
Timestamp Когда произошло действие (UTC)
User Кто выполнил действие (email, ID пользователя)
Operation Что произошло: create, update, delete, publish, unpublish
Page Какая страница затронута (ID, заголовок, путь)
Source Откуда пришло изменение: web_editor, git_sync, api
Content hash SHA-256 нового контента (для проверки)

Просмотр журнала аудита

Доступ к журналу аудита через Workspace Settings -> Activity.

Фильтрация по:

  • Пользователю — просмотр всех изменений конкретного участника
  • Странице — просмотр полной истории конкретной страницы
  • Диапазону дат — ограничение временным окном
  • Типу операции — фильтрация по созданию, обновлению, удалению и т.д.

Типы действий аудита

Поле action в журнале аудита использует точечную нотацию для точной фильтрации:

Действие Описание
page.create Создана новая страница
page.update Изменен контент или frontmatter страницы
page.delete Страница удалена
page.publish Страница опубликована (стала публичной)
page.unpublish Публикация страницы отменена
auth.login Пользователь вошел в систему
auth.register Зарегистрирован новый пользователь
auth.password_reset Выполнен сброс пароля
workspace.create Создан новый workspace
workspace.member_add Пользователь добавлен в workspace
workspace.member_remove Пользователь удален из workspace
workspace.role_change Роль пользователя изменена

Срок хранения

Журналы аудита хранятся в SQLite вместе с основными данными. Они включаются в ежедневные резервные копии. Срок хранения по умолчанию — 1 год (настраивается). Еженедельная задача очистки удаляет записи старше срока хранения.

Email-уведомления

При настроенном SMTP DocPlatform отправляет транзакционные email для:

Событие Получатель Содержание
Приглашение в workspace Приглашенный пользователь Ссылка для присоединения + имя workspace
Сброс пароля Запрашивающий пользователь Одноразовый токен сброса

DocPlatform не отправляет уведомительные email об изменениях контента. Обновления WebSocket в реальном времени служат этой цели для активных пользователей, а журнал аудита обеспечивает исторический обзор.

Настройка SMTP

export SMTP_HOST=smtp.example.com
export SMTP_PORT=587
export SMTP_FROM=[email protected]
export SMTP_USERNAME=[email protected]
export SMTP_PASSWORD=your-app-password

Без SMTP ссылки-приглашения и токены сброса пароля выводятся в stdout (логи сервера).

Рекомендации по командной работе

  • Один автор на страницу — используйте индикаторы присутствия для предотвращения конфликтов
  • Редакторы пишут, администраторы публикуют — разделяйте ответственность с помощью ролей
  • Используйте теги для владения — помечайте страницы тегом owner:jane для уточнения ответственности
  • Git для ревью — пушьте изменения в ветку, откройте PR, мержьте после ревью
  • Аудит перед публикацией — проверяйте журнал аудита на предмет неожиданных изменений перед публикацией контента