06. Процедуры

6.1. Общая концепция

Процедуры — это пользовательские скрипты, которые могут:

• Выполнять сложную бизнес-логику
• Взаимодействовать с базой данных (читать, писать, удалять)
• Вызывать API и вебхуки
• Запускаться по расписанию (CRON)
• Вызываться из API-эндпоинтов
• Вызываться из других процедур

Где можно использовать процедуры:

• В расписаниях (РАСПИСАНИЕ)
• В API-эндпоинтах (API_ЭНДПОИНТ ... ВЫЗВАТЬ)
• В кнопках на формах (КНОПКА ... ВЫЗВАТЬ_ПРОЦЕДУРУ)
• Внутри других процедур (ВЫЗВАТЬ Процедура.Имя)
• В бизнес-логике (ЛОГИКА ... ВЫЗВАТЬ)

6.2. Синтаксис объявления процедуры

ПРОЦЕДУРА ИмяПроцедуры
    # Тело процедуры
    ВЫЧИСЛИТЬ Переменная = 10
    ВЫЧИСЛИТЬ Результат = Переменная * 2
    
    ВОЗВРАТ Результат
КОНЕЦ_ПРОЦЕДУРЫ

Правила именования:

• Имя должно быть уникальным в пределах платформы
• Рекомендуется использовать русские названия с заглавной буквы
• Можно использовать точки для группировки: Справочники.ОбновитьКлиента

6.3. Переменные и типы данных

Переменные в процедурах не требуют объявления типа — тип определяется автоматически при присвоении.

Тип	Пример	Примечание
Число	x = 10, y = 3.14	Целые и дробные
Строка	name = "Иван"	В двойных кавычках
Булево	flag = ИСТИНА	Можно 1 и 0
Массив	arr = [1, 2, 3]	Индексация с 0
Объект	obj = {"name": "John"}	JSON-подобный
Дата/Время	dt = ТЕКУЩАЯ_ДАТА_ВРЕМЯ()	Специальный тип
Null	empty = ПУСТО()	Отсутствие значения

6.4. Управляющие конструкции

Условный оператор ЕСЛИ:

ЕСЛИ условие ТО
    # код
ИНАЧЕ ЕСЛИ условие2 ТО
    # код
ИНАЧЕ
    # код
КОНЕЦ_ЕСЛИ

Операторы сравнения: ==, !=, >, <, >=, <=, И, ИЛИ, НЕ

Циклы ЦИКЛ ПО:

ЦИКЛ ПО массив КАК элемент
    # код
    ЕСЛИ условие ТО ПРЕРВАТЬ КОНЕЦ
    ЕСЛИ условие ТО ПРОДОЛЖИТЬ КОНЕЦ
КОНЕЦ_ЦИКЛА

6.5. Работа с данными (CRUD)

Функция	Назначение	Пример
НАЙТИ("Коллекция", "Фильтр")	Найти первую запись	НАЙТИ("Клиенты", "Телефон = '+7...'")
НАЙТИ_ВСЕ("Коллекция", "Фильтр")	Найти все записи	НАЙТИ_ВСЕ("Задачи", "Статус = 'Новая'")
ПРОЧИТАТЬ("Коллекция", ID)	Чтение по ID	ПРОЧИТАТЬ("Клиенты", 123)
СОЗДАТЬ("Коллекция")	Создание объекта	СОЗДАТЬ("Клиенты")
ЗАПИСАТЬ(Объект)	Сохранение	ЗАПИСАТЬ(НовыйКлиент)
УДАЛИТЬ_ОБЪЕКТ(Объект)	Удаление	УДАЛИТЬ_ОБЪЕКТ(Клиент)

6.6. Работа с API и HTTP

ПОПЫТКА
    ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("POST", "https://api.example.com", Данные)
ИСКЛЮЧЕНИЕ Ошибка
    ВЫВЕСТИ "Ошибка: " + Ошибка
КОНЕЦ_ПОПЫТКИ

6.7. Расписания (CRON)

РАСПИСАНИЕ ИмяРасписания
    КРОН "секунды минуты часы дни месяцы дни_недели"
    ВЫЗВАТЬ Процедура.ИмяПроцедуры
КОНЕЦ_РАСПИСАНИЯ

Примеры CRON:

• */10 * * * * * — каждые 10 секунд
• 0 * * * * * — каждую минуту
• 0 0 9 * * * — каждый день в 9:00
• 0 0 2 * * * — каждый день в 2 часа ночи

6.8. Встроенные функции

Функция	Назначение
ТЕКУЩАЯ_ДАТА_ВРЕМЯ()	Текущие дата и время
ТЕКУЩАЯ_ДАТА()	Текущая дата (без времени)
ТЕКУЩИЙПОЛЬЗОВАТЕЛЬ()	Объект текущего пользователя
ТЕКУЩАЯ_ОРГАНИЗАЦИЯ()	Объект текущей организации
СУММА(массив, поле)	Сумма значений поля
КОЛИЧЕСТВО(массив)	Количество элементов
ПУСТО(значение)	Проверка на пустое значение
ОКРУГЛ(число, знаки)	Округление числа
ВЕРХНИЙ_РЕГИСТР(строка)	Преобразование в верхний регистр
НИЖНИЙ_РЕГИСТР(строка)	Преобразование в нижний регистр

6.9. Обработка ошибок

ПОПЫТКА
    # Опасный код
ИСКЛЮЧЕНИЕ Ошибка
    ВЫВЕСТИ "Ошибка: " + Ошибка
    ВОЗВРАТ {"status": "error", "message": Ошибка}
КОНЕЦ_ПОПЫТКИ

6.10. Best Practices

• Используйте осмысленные имена для переменных: ОбщаяСумма, а не x
• Всегда проверяйте результат поиска перед использованием: ЕСЛИ ПУСТО(Объект) ТО ОШИБКА ...
• Не злоупотребляйте прямыми SQL-запросами — они обходят RLS
• Для долгих операций используйте ВЫПОЛНИТЬ_ФОНОВО
• Пишите обработчики ошибок для HTTP-запросов
• Ограничивайте рекурсию счётчиком глубины
• Используйте ВЫВЕСТИ для отладки
• Документируйте параметры процедуры в комментариях