Система скриптов

• Все действия должны выполняться от имени авторизованного пользователя.
• Скриптами может управлять только администратор или выше (роль admin / superadmin или право scripts.edit / scripts.run).

SCRIPT_STRUCT

{
    "alias": "bad_weather_light",
    "filename": "bad_weather_light.php",
    "path": "/srv/http/smart-home-serv.local/automation/Scopes",
    "state": "enabled",
    "created_by": "Eugene Sukhodolskiy",
    "create_at": "2025-06-02 23:35:11"
}

GET /api/v1/scripts/actions/list

Получить список action-скриптов.

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "scripts": [
            {
                "alias": "script_alias",
                "name": "script name",
                "state": "enabled",
                "description": "script description",
                "filename": "TestScriptsScope.php",
                "path": "/srv/http/smart-home-serv.local/automation/Scopes",
                "created_by": "Eugene Sukhodolskiy",
                "params_schema": {
                    "level": {
                        "type": "range",
                        "label": "Яркость, %",
                        "min": 0,
                        "max": 100,
                        "default": 50,
                        "required": true
                    }
                }
            }
        ],
        "total": 1
    }
}

GET /api/v1/scripts/regular/list

Получить список regular-скриптов.

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "scripts": [
            {
                "alias": "script_alias",
                "name": "script name",
                "state": "enabled",
                "description": "script description",
                "filename": "TestScriptsScope.php",
                "path": "/srv/http/smart-home-serv.local/automation/Scopes",
                "created_by": "Eugene Sukhodolskiy"
            }
        ],
        "total": 1
    }
}

GET /api/v1/scripts/scopes/list

Получить список Scope-классов.

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "scopes": [
            {
                "name": "TestScriptsScope",
                "filename": "TestScriptsScope.php",
                "state": "enabled",
                "path": "/srv/http/smart-home-serv.local/automation/Scopes"
            }
        ],
        "total": 1
    }
}

GET /api/v1/scripts/scopes/name/{filename}

Получить исходный код PHP-файла Scope.

Требуемое право: scripts.view

Пример ответа

<?php /* code */ ?>

POST /api/v1/scripts/scopes/update

Обновить исходный код Scope. Перед записью выполняется проверка синтаксиса (php -l), валидация namespace (ControlScripts\Scopes) и имени класса.

Требуемое право: scripts.edit

Пример запроса

{
    "name": "LightHubScope",
    "source": "<?php\nnamespace ControlScripts\\Scopes;\nclass LightHubScope extends ..."
}

Пример НЕ успешного ответа

{
    "status": false,
    "error_alias": "syntax_error",
    "failed_fields": ["source"],
    "msg": "..."
}

Возможные ошибки: invalid_alias | invalid_source | syntax_error | invalid_namespace | class_name_mismatch | write_failed

GET /api/v1/scripts/scopes/name/{name}/remove

Удалить Scope из системы. Удаляет PHP-файл и связанную запись в БД.

Требуемое право: scripts.edit

GET /api/v1/scripts/actions/alias/{alias}/enable

GET /api/v1/scripts/actions/alias/{alias}/disable

Включить / выключить action-скрипт.

Требуемое право: scripts.edit

GET /api/v1/scripts/regular/alias/{alias}/enable

GET /api/v1/scripts/regular/alias/{alias}/disable

Включить / выключить regular-скрипт.

Требуемое право: scripts.edit

GET /api/v1/scripts/actions/scope/{name}/enable

GET /api/v1/scripts/actions/scope/{name}/disable

Включить / выключить Scope (все его скрипты перестают регистрироваться при следующем старте сервера).

Требуемое право: scripts.edit

POST /api/v1/scripts/actions/run

Запустить action-скрипт. Проверяется, что скрипт включён (state = enabled). Если у скрипта есть params_schema, параметры валидируются перед вызовом.

Требуемое право: scripts.run

Пример запроса (без params)

{
    "alias": "script_alias",
    "params": {}
}

Пример запроса (с params)

{
    "alias": "dim_lights",
    "params": {
        "level": 80,
        "room": "kitchen",
        "instant": true
    }
}

Пример ответа

{
    "status": true,
    "data": {
        "return": {
            "result": {},
            "exec_time": "0.042 seconds"
        }
    }
}

Ошибки:

• action_script_not_found — alias не существует или скрипт disabled
• invalid_params — параметры не прошли валидацию по params_schema (в failed_fields перечислены поля с ошибками)

Таймеры

GET /api/v1/scripts/timers/list

Получить список таймеров (все статусы: pending, executed, cancelled, failed).

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "timers": [
            {
                "id": 1,
                "timer_alias": "kitchen_auto_off",
                "scope_name": "LightHubScope",
                "target_type": "action",
                "target_alias": "kitchen_light_switcher",
                "params": "{}",
                "execute_at": "2026-06-08 15:30:00",
                "status": "pending",
                "created_at": "2026-06-08 15:25:00"
            }
        ],
        "total": 1
    }
}

POST /api/v1/scripts/timers/cancel

Отменить pending-таймер по timer_alias.

Требуемое право: scripts.edit

Пример запроса

{
    "timer_alias": "kitchen_auto_off"
}

Размещение в областях

POST /api/v1/scripts/place-in-area

Поместить скрипт в область.

Тело: { "target_id": 5, "place_in_area_id": 2 }

GET /api/v1/scripts/id/{id}/unassign-from-area

Отвязать скрипт от области.

Моды (Modes)

GET /api/v1/modes/list

Получить список всех системных модов с метаданными (label, description) и текущим состоянием (is_active).

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "modes": [
            {
                "tag": "home",
                "label": "Дома",
                "description": "Основной режим присутствия...",
                "is_active": true,
                "updated_at": "2026-06-08 14:30:00"
            },
            {
                "tag": "away",
                "label": "Не дома",
                "description": "Никого нет дома...",
                "is_active": false,
                "updated_at": "2026-06-08 14:30:00"
            }
        ],
        "total": 2
    }
}

GET /api/v1/modes/active

Массив активных тегов модов.

Требуемое право: scripts.view

Пример ответа

{
    "status": true,
    "data": {
        "active": ["home", "night"]
    }
}

POST /api/v1/modes/{tag}/enable

POST /api/v1/modes/{tag}/disable

Активировать / деактивировать мод. tag должен соответствовать реестру automation/ModesRegistry.php.

Требуемое право: scripts.edit

Ошибка: invalid_alias (если тег не соответствует ^[a-z0-9_]+$).