# Плагин значков для 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` — необязательное поле.