# Loop Plugin Starter Template

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

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

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

| Инструмент | Версия |
|-----------|--------|
| Go        | 1.21+  |
| Node.js   | 22+    |
| Yarn      | 4.x    |

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

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

```bash
git clone <url-репозитория> my-plugin
cd my-plugin
```

### 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
find server/ -type f -name "*.go" | 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                   # Пример переменных окружения
│
├── server/
│   ├── main.go                    # Точка входа серверной части
│   └── plugin/
│       ├── plugin.go              # Основная логика плагина (OnActivate/OnDeactivate)
│       ├── api.go                 # HTTP маршруты и обработчики
│       ├── configuration.go       # Конфигурация плагина
│       ├── store.go               # Работа с key-value хранилищем
│       └── telemetry.go           # Телеметрия
│
└── 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 dist          # Полная сборка (server + webapp + tar.gz)
make server        # Только серверная часть
make webapp        # Только клиентская часть
make check-style   # Линтинг (golangci-lint + eslint)
make test          # Запуск тестов
make clean         # Очистить артефакты сборки
make deploy        # Сборка и деплой на сервер (требует .env)
make watch         # Сборка + hot reload webapp
```

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

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

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

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

| Переменная | Описание |
|-----------|----------|
| `MM_SERVICESETTINGS_SITEURL` | URL вашего Loop-сервера (для деплоя) |
| `MM_ADMIN_TOKEN` | Токен администратора (для деплоя через `make deploy`) |
| `MM_SERVICESETTINGS_ENABLEDEVELOPER` | `true` — билд только под текущую ОС (ускоряет разработку) |
| `MM_DEBUG` | `true` — билд без оптимизаций (для отладчика dlv) |

## Деплой

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

1. Соберите плагин: `make dist`
2. Загрузите `dist/<plugin-id>-<version>.tar.gz` в Loop:
   **Администрирование → Управление плагинами → Загрузить плагин**

### Деплой через `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)