Редактор плагинов в панели¶

English

Плагин можно написать прямо в панели: Настройки → Плагины → Добавить → Или создайте свой. Там же тесты, пробный запуск, установка и скачивание. Пока черновик не установлен, он ничего не меняет в панели. Редактор доступен с правом plugins.manage.

Три способа начать¶

	Что получится
Конструктор правил	«Когда событие → если условие → сделать действие», без кода. Панель собирает из правил обычный плагин.
Код	Шаблон `plugin new`: `main.js`, `plugin.json`, миграция, `test.js`, переводы.
Исходники (.zip)	Архив, скачанный из редактора, — продолжить с того же места. Можно открыть и пакет плагина: он станет черновиком с кодом. (Zip, брошенный в поле выше, не открывается, а устанавливается.)

Черновики в списке плагинов¶

Черновики плагинов, которые ещё не установлены, лежат в общем списке после установленных, с серой точкой у названия. Карандаш открывает черновик, корзина удаляет его, Установить ставит.

Установленный плагин открывается в редакторе карандашом на его карточке. Получается черновик с его кодом, и сколько раз ни открывай — это один и тот же черновик: у плагина он один. Отдельной строкой в списке он не показывается: если в нём есть изменения, которые ещё не применены, на карточке плагина появляется оранжевая точка. При наведении точка говорит, в чём дело. Она же показывает незаполненные настройки и паузу, а если плагин не запустился — становится красной.

Конструктор правил¶

Правило — это:

Когда: событие панели (те же, что у вебхуков) или расписание.
Если: условия на поля события — равно, не равно, содержит, больше, меньше, пусто, не пусто; все сразу или любое.
То: одно или несколько действий:

Действие	Что делает
Написать в Telegram	В чат из настроек плагина: ID чата, группы или канала (или `@имя`) и токен бота задаются после установки.
Написать в Discord	В вебхук из настроек плагина.
HTTP-запрос	На ваш адрес; без тела отправится всё событие JSON: `{id, event, created_at, data}`. Заголовок `Authorization` — из настроек.
Продлить подписку	На N дней.
Включить / отключить пользователя
Добавить / снять тег
Записать в лог плагина

В текстах, адресе и теле запроса работают подстановки вида {{user.name}} или {{data.days_left}}. У каждого правила есть «Данные события» — что приносит его событие: поля пользователя (user.*), поля самого события (data.*) и event, event_id, created_at, now, каждое с описанием и примером, плюс всё событие целиком. Клик по полю вставляет его туда, где курсор. Поля со знаком ? есть не в каждом таком событии. В адресе подставляется только путь и query: хост фиксирован, его оператор видит при установке.

Значение можно показать в читаемом виде — {{user.expire_at|date}}:

Формат	Для	Показывает
`date`	времени (unix-секунды или `{{now}}`)	`01.02.2026` в часовом поясе панели; `—`, если 0
`datetime`	времени	`01.02.2026 03:00`
`days`	времени	сколько дней до него осталось: `3`
`gb`	байтов	гигабайты: `80`
`rub`	копеек	рубли: `150.5`

user.* работает на любом событии про пользователя — user.*, plan.*, balance.adjusted, referral.*, promo.* и платёжных (из data.user). У событий серверов, рассылок и заявок на регистрацию пользователя нет: их правила не могут действовать над пользователем. Не могут и правила на user.deleted: поля пользователя в событии есть, а самого его уже нет. Отклонённая заявка называет пользователя, только если аккаунт уже был (data.user_id), — иначе действия над пользователем пропускаются.

Конструктор не пропустит правила, которые запускали бы сами себя: продление на user.limits_changed или включение на user.disabled вместе с отключением на user.enabled.

Права и сеть плагин получает ровно под правила: события дают users.view (денежные — ещё billing.view), действия с пользователем — users.manage; хосты — api.telegram.org, discord.com и хосты ваших HTTP-запросов.

Каждое действие выполняется для события один раз: если доставка повторится после сбоя, уже сделанные действия не повторятся. Правило по расписанию не может менять пользователя — у него нет пользователя.

Вкладка Код показывает собранный main.js: правила лежат в нём как JSON, ниже — код, который их выполняет. Править код вручную переводит черновик на код насовсем — правила остаются в main.js, конструктор для этого черновика закрывается.

Код¶

Слева файлы, справа редактор: подсветка, Tab, поиск (Ctrl/⌘+F), подсказки panel.*. Всё сохраняется само. Файлы, которые не входят в пакет (test.js, dev.config.json, rospanel.d.ts), остаются в черновике и в скачанных исходниках.

Тесты¶

Запустить тесты выполняет test.js в песочнице панели — как rospanel plugin test: интернет и panel.api подменены (mock.http, mock.api), настройки берутся из dev.config.json. Что тесты не проверяют — в тестах и отладке.

Пробный запуск¶

Одно событие в onEvent с вашими данными или вызов любой экспортированной функции с аргументом. Видно результат, лог и все запросы плагина.

По умолчанию запросы не уходят: интернет отвечает «нет мока», panel.api — подсказкой. Две галочки это меняют:

Настоящие запросы в интернет — только к хостам из net, через тот же защищённый fetch, что у установленного плагина. Сообщения и вебхуки уйдут по-настоящему.
Читать данные панели — panel.api только GET, с правами, которые есть и у плагина, и у вас.

Песочница одна на панель, её делят тесты, пробный запуск и проверка: второй запуск ждёт несколько секунд или отвечает «песочница занята». Тесты ограничены 60 секундами, пробный запуск и проверка — 30.

Установка и скачивание¶

Проверить — пакет так, как его прочитает установка: права, сеть, функции, размер или список ошибок. Код при этом загружается, как при запуске, — ошибка в main.js видна сразу.
Установить — обычный экран согласия с паролем.
Если в правилах конструктора есть ошибки, Проверить покажет их, а тесты, пробный запуск, установка и скачивание пакета откажут, пока их не исправите: иначе ушёл бы код прошлых правил, а не тех, что на экране.
Черновик — копия: автосохранение не трогает работающий плагин. В шапке видно, совпадает ли черновик с установленной версией. Если плагин уже установлен, кнопка называется Применить: это обновление со снимком базы и откатом. Если версия в черновике не выше установленной, она поднимается сама (0.1.0 → 0.1.1).
Скачать — пакет для установки на другой панели или исходники с тестами, чтобы продолжить в своём редакторе с rospanel plugin test | dev | pack. Исходники снова открываются в панели через Исходники (.zip); черновик конструктора остаётся конструктором (правила лежат в rules.json). Секретные настройки из dev.config.json в архив не попадают — их значения стираются.

Черновики хранятся в базе панели зашифрованными, как настройки плагинов.