Команди та співпраця

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

Членство в робочому просторі

Кожен користувач належить до одного або кількох робочих просторів із конкретною роллю. Ролі визначають, які дії може виконувати користувач.

Запрошення учасників

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

1. Відкрийте Workspace Settings → Members
2. Натисніть Invite Member
3. Введіть електронну адресу особи
4. Оберіть роль
5. Натисніть Send

Якщо SMTP налаштовано, надсилається електронний лист із запрошенням з унікальним посиланням. Без 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"
  }'

Видалення учасників

Адміністратори робочого простору можуть видаляти учасників через Settings → Members → натисніть на користувача → Remove.

Видалення учасника негайно скасовує його доступ. Його минулі редагування та записи журналу аудиту зберігаються.

Зміна ролей

Натисніть на поточну роль учасника, щоб змінити її. Зміни ролей набувають чинності негайно — активні сесії оновлюються при наступному API-виклику.

Ролі

DocPlatform використовує 5-рівневу ієрархію ролей. Вищі ролі успадковують усі права нижчих ролей.

Super Admin
    └── Admin
          └── Editor
                └── Commenter
                      └── Viewer

Роль за замовчуванням для нових учасників

Налаштуйте роль за замовчуванням, що призначається при прийнятті запрошення:

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

Доступ на рівні сторінки

Обмежте доступ до окремих сторінок для конкретних ролей за допомогою frontmatter:

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

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

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

Коли кілька користувачів активні в одному робочому просторі, веб-редактор показує, хто онлайн:

• Індикатори на бічній панелі — кольорові крапки поруч зі сторінками, які переглядаються або редагуються іншими користувачами
• Стек аватарів — аватари користувачів у заголовку сторінки, що показують, хто ще переглядає поточну сторінку

Присутність працює через WebSocket з’єднання та оновлюється в реальному часі.

Як працює присутність

WebSocket з’єднання також доставляє події контенту в реальному часі:

Одночасне редагування

DocPlatform не підтримує спільне редагування в реальному часі (у стилі Google Docs). Якщо два користувачі одночасно редагують одну сторінку:

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

Щоб уникнути конфліктів:

• Використовуйте домовленості щодо відповідальності за сторінки (один автор на сторінку одночасно)
• Індикатори присутності допомагають команді координувати, хто що редагує
• Для команд із високим рівнем паралельної роботи розгляньте коротші інтервали синхронізації git

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

Кожна мутація контенту логується з:

Перегляд журналу аудиту

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

Фільтруйте за:

• Користувач — побачити всі зміни конкретного члена команди
• Сторінка — побачити повну історію конкретної сторінки
• Діапазон дат — звузити до часового вікна
• Тип операції — фільтрувати за створеннями, оновленнями, видаленнями тощо

Типи дій аудиту

Поле action у журналі аудиту використовує крапкову нотацію для точної фільтрації:

Зберігання

Журнали аудиту зберігаються в SQLite разом із вашими звичайними даними. Вони включаються в щоденні резервні копії. Термін зберігання за замовчуванням — 1 рік (налаштовується). Щотижнева задача очищення видаляє записи, старші за термін зберігання.

Email-сповіщення

З налаштованим SMTP DocPlatform надсилає транзакційні листи для:

DocPlatform не надсилає сповіщень по електронній пошті про зміни контенту. Оновлення через 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, зливайте після ревʼю
• Аудит перед публікацією — перегляньте журнал аудиту на предмет неочікуваних змін перед публікацією контенту