194 lines
13 KiB
Markdown
194 lines
13 KiB
Markdown
# Плагин значков для Loop
|
||
|
||
Позволяет пользователям выражать признательность коллегам, выдавая им значки.
|
||
|
||
## Установка
|
||
|
||
Скачайте последний релиз и установите его вручную через системную консоль Loop.
|
||
|
||
## Настройка
|
||
|
||
- **Администраторы значков**: все системные администраторы автоматически являются администраторами значков. Дополнительно можно назначить любое количество администраторов значков через мультиселект в настройках плагина.
|
||
|
||
## Использование
|
||
|
||
### Создание типа значка
|
||
|
||
Администраторы значков могут создавать разные типы значков, каждый со своими правами доступа. Для создания типа необходимы права администратора значков.
|
||
|
||
Выполните слэш-команду `/badges create type`, чтобы открыть диалог создания.
|
||
|
||
- **Название**: название типа, отображаемое в описании значков.
|
||
- **Все могут создавать значки**: если отмечено, любой пользователь Loop может создавать значки этого типа.
|
||
- **Список допущенных к созданию**: username'ы через запятую — кто может создавать значки этого типа.
|
||
- **Все могут выдавать значки**: если отмечено, любой пользователь Loop может выдавать значки этого типа.
|
||
- **Список допущенных к выдаче**: username'ы через запятую — кто может выдавать значки этого типа.
|
||
|
||
### Права доступа
|
||
|
||
Администраторы значков всегда могут создавать типы, создавать значки любого типа и выдавать любые значки — независимо от настроек прав типа. Создатель значка всегда может выдавать созданный им значок. Остальные пользователи подчиняются правам, настроенным для типа.
|
||
|
||
Примеры конфигураций (ECC: все могут создавать, CC: список допущенных к созданию, ECG: все могут выдавать, CG: список допущенных к выдаче):
|
||
|
||
| Права | Пример использования | ECC | ECG | CC | CG |
|
||
|-------|---------------------|-----|-----|----|----|
|
||
| Только администраторы могут создавать и выдавать | | false | false | пусто | пусто |
|
||
| Только user1 создаёт, но выдавать может каждый | Значок "Спасибо" от коллег | false | true | user1 | пусто |
|
||
| Только user1 создаёт, выдают только user2 и user3 | Значок "MVP" — руководство создаёт, тимлиды выдают | false | false | user1 | user2, user3 |
|
||
| user1 и user2 создают, выдают только свои значки | Командные значки без создания нового типа на каждую команду | false | false | user1, user2 | пусто |
|
||
| Все создают и выдают только свои значки | | true | false | пусто | пусто |
|
||
| Все создают и выдают любые значки | | true | true | пусто | пусто |
|
||
|
||
### Создание значка
|
||
|
||
Выполните слэш-команду `/badges create badge`, чтобы открыть диалог создания.
|
||
|
||
- **Название**: название значка.
|
||
- **Описание**: описание значка.
|
||
- **Изображение**: только эмодзи. Укажите имя эмодзи как в сообщении (например `:+1:` или `:smile:`). Кастомные эмодзи тоже поддерживаются.
|
||
- **Тип**: тип значка. В списке отображаются только типы, для которых у вас есть права на создание.
|
||
- **Множественный**: можно ли выдавать этот значок одному человеку несколько раз.
|
||
|
||
### Подробнее о параметре "Множественный"
|
||
|
||
Любой значок можно выдать любому количеству людей. Параметр **Множественный** определяет, можно ли выдать значок одному и тому же человеку более одного раза. Например, значок "Спасибо" стоит сделать множественным — один человек может получить благодарность многократно. А значок "Первый год в компании" должен быть невозможно выдать дважды.
|
||
|
||
### Выдача значка
|
||
|
||
Открыть диалог выдачи можно двумя способами:
|
||
- Выполнить команду `/badges grant`.
|
||
- Нажать **Выдать значок** в поповере профиля пользователя.
|
||
|
||
- **Пользователь**: кому выдаётся значок.
|
||
- **Значок**: какой значок выдаётся.
|
||
- **Причина**: необязательное пояснение (особенно полезно для значков типа "Спасибо").
|
||
- **Уведомить в этом канале**: если отмечено, бот опубликует сообщение в текущем канале о выдаче значка.
|
||
|
||
Получатель значка всегда получает личное сообщение от бота. Дополнительно:
|
||
- Если отмечено **Уведомить в этом канале** — бот публикует сообщение в текущем канале.
|
||
- Если настроена подписка для этого типа — бот публикует сообщение во всех подписанных каналах.
|
||
|
||
### Подписки
|
||
|
||
Подписки позволяют автоматически публиковать сообщение в канале каждый раз, когда выдаётся значок определённого типа. Количество подписок не ограничено.
|
||
|
||
Для создания подписки необходимы права администратора значков. Открыть диалог создания подписки можно двумя способами:
|
||
- Выполнить команду `/badges subscription create`.
|
||
- Нажать **Добавить подписку на значки** в меню канала.
|
||
|
||
- **Тип**: тип значков, на который подписывается канал.
|
||
|
||
Для удаления подписки используйте `/badges subscription remove` или **Удалить подписку на значки** в меню канала.
|
||
|
||
### Редактирование и удаление значков и типов
|
||
|
||
Для редактирования и удаления типов необходимы права администратора значков. Для редактирования и удаления значка — права администратора или создателя значка.
|
||
|
||
Выполните `/badges edit type --type typeID` или `/badges edit badge --id badgeID`, чтобы открыть диалог редактирования. Автодополнение поможет выбрать нужный значок или тип.
|
||
|
||
Диалог редактирования аналогичен диалогу создания, но с дополнительным чекбоксом удаления. Если отметить его и нажать **Изменить** — значок или тип будет удалён.
|
||
|
||
При удалении значка безвозвратно удаляется вся история его выдачи. При удалении типа удаляются тип и все связанные с ним значки.
|
||
|
||
### Список значков
|
||
|
||
Значки отображаются в нескольких местах. В поповере профиля — до 20 последних полученных значков. При наведении на значок появляется подсказка, при клике открывается панель с деталями значка.
|
||
|
||
Кнопка в шапке канала открывает панель со списком всех значков. Клик на любой значок показывает его детали и список пользователей, которым он был выдан. Клик на имя пользователя показывает все его значки.
|
||
|
||
---
|
||
|
||
## REST API
|
||
|
||
Базовый URL: `https://<сервер>/plugins/ru.loop.plugin.achievements`
|
||
|
||
Все запросы требуют токен в заголовке:
|
||
```
|
||
Authorization: Bearer <токен>
|
||
```
|
||
|
||
Токен можно получить в настройках аккаунта Loop: **Профиль → Безопасность → Персональные токены доступа**.
|
||
|
||
### Типы значков
|
||
|
||
| Метод | Эндпоинт | Описание |
|
||
|-------|----------|----------|
|
||
| `GET` | `/api/v1/getTypes` | Список типов, доступных текущему пользователю |
|
||
| `POST` | `/api/v1/createType` | Создать тип (только администраторы) |
|
||
| `PUT` | `/api/v1/updateType` | Обновить тип (только администраторы) |
|
||
| `DELETE` | `/api/v1/deleteType/{typeID}` | Удалить тип и все его значки (только администраторы) |
|
||
|
||
### Значки
|
||
|
||
| Метод | Эндпоинт | Описание |
|
||
|-------|----------|----------|
|
||
| `GET` | `/api/v1/getAllBadges` | Полный список значков |
|
||
| `GET` | `/api/v1/getUserBadges/{userID}` | Значки конкретного пользователя |
|
||
| `GET` | `/api/v1/getBadgeDetails/{badgeID}` | Детали значка и список получателей |
|
||
| `POST` | `/api/v1/createBadge` | Создать значок |
|
||
| `PUT` | `/api/v1/updateBadge` | Обновить значок |
|
||
| `DELETE` | `/api/v1/deleteBadge/{badgeID}` | Удалить значок и историю его выдачи |
|
||
|
||
### Выдача значков
|
||
|
||
| Метод | Эндпоинт | Описание |
|
||
|-------|----------|----------|
|
||
| `POST` | `/api/v1/grantBadge` | Выдать значок пользователю |
|
||
| `POST` | `/api/v1/revokeOwnership` | Отозвать выдачу значка |
|
||
|
||
### Подписки
|
||
|
||
| Метод | Эндпоинт | Описание |
|
||
|-------|----------|----------|
|
||
| `GET` | `/api/v1/getChannelSubscriptions/{channelID}` | Список подписок канала |
|
||
| `POST` | `/api/v1/createSubscription` | Создать подписку (только администраторы) |
|
||
| `POST` | `/api/v1/deleteSubscription` | Удалить подписку (только администраторы) |
|
||
|
||
---
|
||
|
||
## Интеграция с другими плагинами (Plugin API)
|
||
|
||
Плагин поддерживает интеграцию с другими плагинами Loop через механизм `PluginHTTP`. Авторизация выполняется автоматически ядром Loop — токен не нужен.
|
||
|
||
Доступны два эндпоинта:
|
||
|
||
### Ensure — создать значки если не существуют
|
||
|
||
URL: `/ru.loop.plugin.achievements/papi/v1/ensure`
|
||
|
||
Метод: `POST`
|
||
|
||
```json
|
||
{
|
||
"Badges": [
|
||
{
|
||
"name": "My badge",
|
||
"description": "Awesome badge",
|
||
"image": "smile",
|
||
"image_type": "emoji",
|
||
"multiple": true
|
||
}
|
||
],
|
||
"BotId": "botUserId"
|
||
}
|
||
```
|
||
|
||
Создаёт значки, если они ещё не существуют (проверка по имени), и возвращает их с заполненными `id`.
|
||
|
||
### Grant — выдать значок
|
||
|
||
URL: `/ru.loop.plugin.achievements/papi/v1/grant`
|
||
|
||
Метод: `POST`
|
||
|
||
```json
|
||
{
|
||
"BadgeID": "badgeID",
|
||
"BotId": "botUserId",
|
||
"UserID": "userID",
|
||
"Reason": "За крутую работу"
|
||
}
|
||
```
|
||
|
||
Выдаёт значок от имени указанного бота пользователю. `Reason` — необязательное поле.
|