loop-plugin-starter-template/README.md

# Loop Plugin Starter Template

Стартовый шаблон для разработки плагинов под Loop.

Шаблон включает серверную часть на Go и клиентскую часть на React/TypeScript, настроенный билд через Makefile, пример REST API и базовую структуру Redux store.

Подробное руководство по разработке плагинов: [developers.loop.ru/integrate/plugin-development](https://developers.loop.ru/integrate/plugin-development).

> **Совместимость.** Возможности плагинов в Loop соответствуют Mattermost 9.11.7. Поэтому серверная часть зафиксирована на `github.com/mattermost/mattermost/server/public v0.1.6` — в этой версии ровно те методы API и хуки, что есть в Loop, и компилятор не даст вызвать недоступный метод. Не обновляйте этот пакет.

## Требования

| Инструмент | Версия |
|-----------|--------|
| Go        | 1.24+  |
| Node.js   | 22+    |
| Yarn      | 4.x (`corepack enable`) |

## Быстрый старт

### 1. Клонировать шаблон

```bash
git clone https://git.wilix.dev/loop/loop-plugin-starter-template.git my-plugin
cd my-plugin
rm -rf .git && git init
```

### 2. Переименовать плагин

Откройте `plugin.json` и замените значения:

```json
{
  "id": "ru.loop.plugin.my-plugin",
  "name": "My Plugin",
  "description": "Описание вашего плагина",
  "version": "0.1.0"
}
```

### 3. Обновить Go-модуль

В `go.mod` замените имя модуля:

```
module git.example.com/your-org/my-plugin
```

Затем обновите все импорты в `server/`:

```bash
# macOS
grep -rl 'git.wilix.dev/loop/loop-plugin-starter-template' server build | \
  xargs sed -i '' 's|git.wilix.dev/loop/loop-plugin-starter-template|git.example.com/your-org/my-plugin|g'

# Linux / WSL
grep -rl 'git.wilix.dev/loop/loop-plugin-starter-template' server build | \
  xargs sed -i 's|git.wilix.dev/loop/loop-plugin-starter-template|git.example.com/your-org/my-plugin|g'
```

### 4. Установить зависимости и собрать

```bash
# Go-зависимости устанавливаются автоматически при сборке

# Webapp-зависимости
cd webapp && yarn install && cd ..

# Полная сборка (server + webapp + bundle)
make dist
```

Собранный плагин будет в `dist/<plugin-id>-<version>.tar.gz`.

## Структура проекта

```
├── plugin.json                    # Манифест плагина (ID, имя, версия)
├── Makefile                       # Команды сборки
├── .env.example                   # Пример переменных окружения
├── assets/                        # Файлы, которые попадут в архив (иконка и т. п.)
│
├── server/
│   ├── main.go                    # Точка входа серверной части
│   └── plugin/
│       ├── plugin.go              # Основная логика плагина (OnActivate/OnDeactivate)
│       ├── api.go                 # HTTP маршруты и обработчики
│       ├── configuration.go       # Конфигурация плагина
│       ├── store.go               # Работа с key-value хранилищем
│       └── telemetry.go           # Телеметрия (включается ключами RudderStack при сборке)
│
└── webapp/
    └── src/
        ├── index.tsx              # Точка входа клиентской части
        ├── registerApp.tsx        # Регистрация компонентов в Loop
        ├── components/
        │   └── RootComponent.tsx  # Корневой React-компонент
        ├── store/
        │   ├── actions.ts         # Redux actions
        │   └── reducers.ts        # Redux reducers
        └── utils/
            ├── api.ts             # Запросы к серверной части плагина
            └── usePlugin.ts       # Хук для доступа к API плагина
```

## Что нужно изменить

### Серверная часть

**`server/plugin/plugin.go`** — основная логика:
- `OnActivate` — вызывается при включении плагина
- `OnDeactivate` — вызывается при выключении

**`server/plugin/api.go`** — REST API:
- Добавляйте маршруты в `InitApi()`
- Пример маршрута `/example` уже включён

**`server/plugin/configuration.go`** — настройки плагина:
- Добавьте поля в структуру `Configuration`
- Они будут доступны в панели администратора Loop

### Клиентская часть

**`webapp/src/registerApp.tsx`** — регистрация в Loop:
- Регистрация Redux reducer
- Регистрация React-компонентов через `registry`

**`webapp/src/components/RootComponent.tsx`** — основной компонент:
- Точка входа для отображения вашего UI

**`webapp/i18n/`** — переводы:
- `en.json` — английские строки
- `ru.json` — русские строки

## Makefile: команды сборки

```bash
make               # Линтинг, тесты и полная сборка
make dist          # Полная сборка (server + webapp + tar.gz)
make server        # Только серверная часть
make webapp        # Только клиентская часть
make check-style   # Линтинг (golangci-lint v2 + eslint)
make test          # Запуск тестов
make clean         # Очистить артефакты сборки
make deploy        # Сборка и деплой на сервер (требует .env)
make watch         # Пересборка webapp при изменениях (загрузка — make deploy-from-watch)
make deps          # Установить golangci-lint и goi18n
```

Полный список команд: `make help`

## Переменные окружения

Скопируйте `.env.example` в `.env` и заполните:

```bash
cp .env.example .env
```

| Переменная | Описание |
|-----------|----------|
| `MM_SERVICESETTINGS_SITEURL` | URL вашего Loop-сервера (для деплоя) |
| `MM_ADMIN_TOKEN` | Токен администратора (для деплоя через `make deploy`) |
| `MM_SERVICESETTINGS_ENABLEDEVELOPER` | `true` — билд только под текущую ОС и linux-amd64 (ускоряет разработку, но не запустится на ARM-сервере) |
| `MM_DEBUG` | `true` — билд без оптимизаций (для отладчика dlv) и webapp с source maps |
| `MM_RUDDER_CALLS_PROD`, `MM_RUDDER_DATAPLANE_URL` | Ключи RudderStack для серверной телеметрии. Пустые — телеметрия выключена |

## Деплой

### Ручной деплой

1. Соберите плагин: `make dist`
2. Загрузите `dist/<plugin-id>-<version>.tar.gz` в Loop:
   **Системная консоль → Плагины → Управление плагинами → Загрузить плагин**.
   Загрузка должна быть разрешена на сервере: `PluginSettings.EnableUploads = true` (или `MM_PLUGINSETTINGS_ENABLEUPLOADS=true`)

### Деплой через `make deploy`

Требует заполненного `.env` с `MM_SERVICESETTINGS_SITEURL` и `MM_ADMIN_TOKEN`:

```bash
make deploy
```

### CI/CD

В директории `.gitea/workflows/` есть пример workflow для Gitea Actions.
Адаптируйте его под вашу CI/CD систему.

## Отладка

Для удалённой отладки серверной части с помощью [Delve](https://github.com/go-delve/delve):

```bash
MM_DEBUG=true make deploy   # Билд без оптимизаций
make attach-headless         # Attach dlv на порт 2346
```

## Лицензия

[MIT](LICENSE)