12. Отладка и диагностика

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

Платформа предоставляет встроенные средства отладки для разработчиков DSL. Все отладочные выводы пишутся в консоль (лог-файл) платформы.

ВАЖНО: Функции отладки (ВЫВЕСТИ, ОТЛАДКА, EXPLAIN QUERY PLAN) доступны ТОЛЬКО авторизованным разработчикам с ролью, имеющей соответствующие права. Обычные пользователи не видят отладочную информацию в интерфейсе.

12.2. Команда ВЫВЕСТИ — вывод текстовых сообщений

Команда ВЫВЕСТИ выводит текстовое сообщение в лог-консоль платформы. Используется для логирования хода выполнения процедур и отметки ключевых точек.

ВЫВЕСТИ "Текст сообщения"
ВЫВЕСТИ "Значение переменной: " + ИмяПеременной

Примеры:

ПРОЦЕДУРА ПримерВывести
    ВЫВЕСТИ "=== НАЧАЛО процедуры ==="
    ВЫВЕСТИ "Запуск обработки заказа ID: " + IDЗаказа
    # ... код ...
    ВЫВЕСТИ "=== КОНЕЦ процедуры ==="
КОНЕЦ_ПРОЦЕДУРЫ

12.3. Команда ОТЛАДКА — вывод структуры данных (дамп)

Команда ОТЛАДКА выводит полную структуру объекта, массива или переменной в читаемом формате. Незаменима для анализа содержимого сложных данных.

ОТЛАДКА Переменная
ОТЛАДКА Объект
ОТЛАДКА Массив

Примеры из конфигурации:

# Дамп сохранённой задачи
ВЫЧИСЛИТЬ НоваяЗадача = СОЗДАТЬ("Задачи")
ВЫЧИСЛИТЬ Успех = ЗАПИСАТЬ(НоваяЗадача)
ВЫВЕСТИ "[ОТЛАДКА] Сохраненная новая задача:"
ОТЛАДКА НоваяЗадача

# Дамп массива найденных задач
ВЫЧИСЛИТЬ СписокЗадач = НАЙТИ_ВСЕ("Задачи", "Статус='Новая'")
ВЫВЕСТИ "[ОТЛАДКА] Массив найденных новых задач:"
ОТЛАДКА СписокЗадач

# Дамп результатов SQL-запроса
ВЫЧИСЛИТЬ Статистика = ЗАПРОС("SELECT Статус, COUNT(id) as Количество FROM Задачи GROUP BY Статус")
ВЫВЕСТИ "Статистика задач в базе:"
ОТЛАДКА Статистика

12.4. EXPLAIN QUERY PLAN — анализ SQL-запросов

Платформа поддерживает выполнение команды EXPLAIN QUERY PLAN перед SQL-запросом. Это позволяет увидеть план выполнения запроса и оптимизировать его.

ВЫЧИСЛИТЬ План = ЗАПРОС("EXPLAIN QUERY PLAN SELECT ...")
ОТЛАДКА План

Примеры из конфигурации:

# Анализ статистики задач
ВЫЧИСЛИТЬ ЗапросСтатистики = "SELECT Статус, COUNT(id) as Количество FROM Задачи GROUP BY Статус"
ВЫЧИСЛИТЬ ЗапросЭксплейн = "EXPLAIN QUERY PLAN SELECT Статус, COUNT(id) as Количество FROM Задачи GROUP BY Статус"
ВЫЧИСЛИТЬ План = ЗАПРОС(ЗапросЭксплейн)
ВЫВЕСТИ "[ОТЛАДКА] План SQL-запроса статистики:"
ОТЛАДКА План

# Анализ JOIN запроса
ВЫЧИСЛИТЬ ЭксплейнСводки = "EXPLAIN QUERY PLAN SELECT К.Наименование as КлиентИмя, COUNT(ЗН.id) as КолВоЗаказов FROM ЗаказНаряд ЗН JOIN Клиенты К ON ЗН.Клиент = К.id WHERE ЗН.Статус = 'В работе' GROUP BY К.id"
ВЫЧИСЛИТЬ ПланСводки = ЗАПРОС(ЭксплейнСводки)
ВЫВЕСТИ "[ОТЛАДКА] План запроса JOIN (Сводка):"
ОТЛАДКА ПланСводки

# Анализ UPDATE запроса
ВЫЧИСЛИТЬ ЗапросЭксплейн = "EXPLAIN QUERY PLAN UPDATE ЗаказНаряд SET Статус = 'Закрыт' WHERE id = " + Запись.id
ВЫЧИСЛИТЬ ПланАпдейта = ЗАПРОС(ЗапросЭксплейн)
ВЫВЕСТИ "[ОТЛАДКА] План выполнения UPDATE:"
ОТЛАДКА ПланАпдейта

12.5. Обработка ошибок — ПОПЫТКА...ИСКЛЮЧЕНИЕ

Конструкция ПОПЫТКА...ИСКЛЮЧЕНИЕ позволяет перехватывать ошибки и логировать их без остановки выполнения процедуры.

ПОПЫТКА
    # Опасный код
    ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("POST", "https://external.com/api", Данные)
ИСКЛЮЧЕНИЕ Ошибка
    ВЫВЕСТИ "Ошибка: " + Ошибка
    # Дополнительное логирование ошибки
    ВЫЧИСЛИТЬ Лог = СОЗДАТЬ("ЖурналОшибок")
    ЗАПОЛНИТЬ Лог.Дата = ТЕКУЩАЯ_ДАТА_ВРЕМЯ()
    ЗАПОЛНИТЬ Лог.ТекстОшибки = Ошибка
    ЗАПОЛНИТЬ Лог.Процедура = "ИмяПроцедуры"
    ВЫЧИСЛИТЬ _ = ЗАПИСАТЬ(Лог)
    ВОЗВРАТ {"status": "error", "message": Ошибка}
КОНЕЦ_ПОПЫТКИ

12.6. Логирование ошибок и предупреждений

В процедурах рекомендуется логировать не только критические ошибки, но и предупреждения:

ЕСЛИ data.СуммаДокумента > 1000000 ТО
    ВЫВЕСТИ "Внимание! Сумма документа превышает 1 млн рублей"
КОНЕЦ

ЕСЛИ НулевыеЦены > 0 ТО
    ВЫВЕСТИ "Внимание! " + НулевыеЦены + " позиций имеют нулевую цену"
КОНЕЦ

12.7. Практические рекомендации по отладке

1. Логируйте начало и конец процедур:

ПРОЦЕДУРА СложнаяЛогика
    ВЫВЕСТИ "=== НАЧАЛО процедуры СложнаяЛогика ==="
    # ... код ...
    ВЫВЕСТИ "=== КОНЕЦ процедуры СложнаяЛогика ==="
КОНЕЦ_ПРОЦЕДУРЫ

2. Логируйте ключевые переменные перед их использованием:

ВЫЧИСЛИТЬ SQL = "SELECT * FROM Клиенты WHERE Телефон = '" + Телефон + "'"
ВЫВЕСТИ "[ОТЛАДКА] Выполняется SQL: " + SQL
ВЫЧИСЛИТЬ Результат = ЗАПРОС(SQL)

3. Проверяйте и логируйте пустые результаты:

ВЫЧИСЛИТЬ Результат = ЗАПРОС(Запрос)
ЕСЛИ ПУСТО(Результат) ТО
    ВЫВЕСТИ "ВНИМАНИЕ: Запрос вернул 0 строк. Возможно, проблема в RLS или фильтрах."
КОНЕЦ

4. Сохраняйте важные логи в отдельную коллекцию для аудита:

ПОПЫТКА
    # код
ИСКЛЮЧЕНИЕ Ошибка
    ВЫВЕСТИ "ОШИБКА: " + Ошибка
    ВЫЧИСЛИТЬ Лог = СОЗДАТЬ("ЖурналОшибок")
    ЗАПОЛНИТЬ Лог.Дата = ТЕКУЩАЯ_ДАТА_ВРЕМЯ()
    ЗАПОЛНИТЬ Лог.ТекстОшибки = Ошибка
    ЗАПОЛНИТЬ Лог.Процедура = "ИмяПроцедуры"
    ВЫЧИСЛИТЬ _ = ЗАПИСАТЬ(Лог)
КОНЕЦ_ПОПЫТКИ

12.8. Best Practices

• Используйте структурированные метки в сообщениях ВЫВЕСТИ: [ОТЛАДКА], [ОШИБКА], [ПРЕДУПРЕЖДЕНИЕ], [INFO] — это упрощает поиск в логах.
• Не оставляйте отладочные выводы в production-коде без необходимости — они создают шум в логах.
• Для сложных процедур логируйте этапы выполнения с указанием процента выполнения или количества обработанных записей.
• Используйте ОТЛАДКА только при реальной необходимости, так как вывод больших объектов может быть ресурсоёмким.
• При отладке проблем с RLS выводите в лог итоговый SQL-запрос вместе с подставленными значениями ТЕКУЩИЙПОЛЬЗОВАТЕЛЬ().id и ТЕКУЩАЯ_ОРГАНИЗАЦИЯ().id.
• Логируйте время выполнения длительных операций:

ВЫЧИСЛИТЬ ВремяНачала = ТЕКУЩАЯ_ДАТА_ВРЕМЯ()
# ... длительная операция ...
ВЫЧИСЛИТЬ ВремяОкончания = ТЕКУЩАЯ_ДАТА_ВРЕМЯ()
ВЫВЕСТИ "Операция выполнена за " + (ВремяОкончания - ВремяНачала) + " секунд"