В рамках цикла статей по ИИ-ассистированной разработке решений для Битрикс24 — четвёртая часть, посвящённая работе с BI-коннектором. Этот инструмент позволяет интегрировать внешние базы данных с порталом, обеспечивая аналитику не только по внутренним данным (сделкам, клиентам), но и по сторонним источникам.

Что нужно установить перед работой

Для старта используется репозиторий github.com/bitrix24/bi-connector. Итоговый проект доступен в репозитории igorrosliakov-bitrix24/Bitrix24-BIConnector.

Требуемые компоненты:

• Docker и Docker Compose — для контейнеризации;
• Git — для управления версиями;
• make — для удобного запуска команд;
• HTTPS-туннель через CloudPub — для внешнего доступа к локальному сервису.

Что такое BI-коннектор и как он работает

BI-коннектор — это отдельный серверный сервис, который выступает мостом между Битрикс24 и внешними базами данных. Он не встраивается в портал, а принимает от него HTTP-запросы и отвечает в JSON-формате.

Схема работы:

• Внешняя база данных (на сервере, в облаке или локально) подключается через коннектор.
• BI-коннектор передаёт параметры подключения.
• Через коннектор Битрикс24 получает доступ к таблицам и данным.

Анализ проекта для дальнейшей работы

AI-агент (Codex) проанализировал проект и выделил три основных слоя архитектуры.

Основные точки входа

• Application.php — управляет установкой и регистрацией коннекторов в Битрикс24.
• index.php — обрабатывает входящие BI-запросы.
• BiConnector.php — отвечает за подключение к БД и реализацию контракта BI-коннектора.
• QueryBuilder.php — формирует SQL-запросы.

1. Слой установки

Класс Application.php обрабатывает событие установки, сохраняет данные аутентификации и регистрирует в портале два коннектора: MySQL и PostgreSQL. При этом передаются URL-адреса для:

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

2. Слой HTTP-обработки

Входящие запросы обрабатываются через public/index.php, а после оптимизации — через отдельный ConnectorRequestHandler.php. Этот слой:

• читает параметры запроса (action, connection_type);
• парсит JSON-тело;
• валидирует данные;
• создаёт нужный коннектор;
• вызывает соответствующее действие.

3. Слой работы с БД

BiConnector.php управляет подключением к базе, проверкой доступности, получением списка и структуры таблиц. QueryBuilder.php формирует SQL-запросы с учётом select, filter и limit, возвращая данные в формате, ожидаемом порталом.

Задача 1: установка в портал

Чтобы подключить коннектор к Битрикс24, необходимо обеспечить внешний доступ к локальному сервису.

Поднимаем проект локально

Проект запускается через Docker. Требуется:

• клонировать репозиторий;
• создать файл .env;
• запустить контейнеры через docker-compose.

Добавить туннель / внешний доступ

Битрикс24 требует HTTPS-доступ к приложению. Используется туннель через CloudPub. После регистрации и получения токена он добавляется в .env. Проект должен знать свой публичный домен — для этого вводится переменная APP_DOMAIN.

Подключить приложение к порталу

После настройки туннеля приложение регистрируется в портале как локальное. Важно поставить галочку «Использует только API» и указать права biconnector.

Что поменял и добавил агент

В .env.example добавлены:

• CLOUDPUB_TOKEN — для туннеля;
• CLOUDPUB_IMAGE — выбор Docker-образа;
• BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector — фиксация типа приложения.

В docker-compose.yml добавлен сервис cloudpub, который:

• принимает токен;
• прокидывает трафик на app:80;
• работает в одной сети с приложением;
• создаёт HTTPS-адрес для локального сервиса.

В Makefile добавлены команды:

• dev-init — инициализация;
• start-cloudpub — запуск туннеля;
• logs-cloudpub — просмотр логов.

Скрипт scripts/dev-init.sh автоматически:

• запускает приложение и туннель;
• извлекает внешний URL из логов;
• записывает его в APP_DOMAIN;
• перезапускает приложение с новым доменом.

В Application.php уточнена логика формирования URL-адресов на основе APP_DOMAIN.

Проверяем, что приложение установилось

Для проверки:

• в разделе «BI-конструктор» → «Рабочее место аналитика» создаётся новое подключение;
• выбирается тип базы (MySQL/PostgreSQL);
• заполняются параметры подключения;
• выполняется проверка.

При успехе можно выбрать таблицу и просмотреть её данные. Альтернатива — проверка через curl, например:

• проверка подключения;
• запрос списка таблиц;
• описание структуры таблицы.

Задача 2: оптимизация безопасности и покрытие тестами

Проект был улучшен по двум направлениям: безопасность и тестирование.

Усиление безопасности

• Некорректный JSON возвращает 400 Bad Request, а не падает.
• При отсутствии обязательных параметров возвращается понятная ошибка.
• Чувствительные данные (пароли, токены) маскируются в логах.
• Имена таблиц в MySQL-запросах экранируются корректно.

Расширение тестового покрытия

Добавлены тесты для:

• битого JSON;
• отсутствия connection;
• некорректного connection_type;
• неизвестного action;
• нормализации limit;
• преобразования имён полей;
• сборки SQL-запросов;
• безопасного логирования.

Что поменял и добавил агент

ConnectorRequestHandler.php — новый класс для обработки запросов. Он:

• парсит action и connection_type;
• извлекает данные из form-data и JSON;
• валидирует параметры;
• возвращает контролируемые ошибки (400/500);
• централизует вызовы check, table_list, table_description, data.

public/index.php стал проще — делегирует логику ConnectorRequestHandler.

В Application.php добавлен процессор логов, который санитизирует контекст. Чувствительные ключи (password, token, secret и др.) заменяются на ***.

Метод formatResponseForLog() безопасно парсит JSON-ответы и маскирует секреты перед записью в лог.

В BiConnector.php улучшена безопасность при инспекции схемы MySQL.

Добавлен Dockerfile.test с Xdebug для сбора coverage.

В Makefile добавлена команда test-coverage. Отчёт сохраняется в coverage/ в формате HTML.

Расширены unit-тесты.

Задача 3: модернизация проекта — добавляем автомаппинг

Добавлена фича автоматического преобразования имён полей между внешней БД и форматом Битрикс24.

Пример:

• В БД: Created By;
• В Битрикс24: CREATED_BY.

Требуется двусторонний маппинг, чтобы:

• отдавать структуру в безопасном формате;
• преобразовывать запросы из Битрикс24 в реальные имена колонок.

Фича устраняет проблемы с пробелами, регистром, спецсимволами и дефисами.

Что поменял и добавил агент

Шаг 1: создан FieldNameMapper.php. Он:

• принимает список полей;
• преобразует в Bitrix-совместимый формат (например, City / Region → CITY_REGION);
• решает коллизии через суффиксы (например, CREATED_BY_2).

Шаг 2: маппинг интегрирован в BiConnector.php. Метод table_description теперь возвращает нормализованные имена, а getData() передаёт маппинг в слой запросов.

Шаг 3: QueryBuilder.php обновлён. Запросы с CREATED_BY транслируются в Created By для SQL, а в ответе снова возвращаются как CREATED_BY.

Автомаппинг работает для:

• SELECT;
• filter;
• LIKE;
• IN;
• BETWEEN;
• =.

Добавлена демо-таблица friendly_columns с полями: Created By, Office Name, City / Region, Opened At.

Функциональность покрыта тестами в FieldNameMapperTest.php и QueryBuilderTest.php.

Итог: AI-агент успешно модернизировал проект по трём направлениям:

1. настройка HTTPS-туннеля для подключения к порталу;
2. усиление безопасности и тестового покрытия;
3. внедрение автомаппинга полей.

Самым сложным этапом оказалось чёткое формулирование задачи. Исполнение прошло быстро и без зависаний.

Что будет дальше

В следующей статье цикла — работа с чат-ботами на бэкенде. Предыдущие темы: создание приложений с AI-стартером, автоматизация через роботов, воспроизводимая среда разработки.

Содержание цикла статей

1. Пишем первое приложение с AI-стартером, чтобы видеть прибыли и убытки
2. Добавляем в бизнес-портал Битрикс24 роботов для автоматизации
3. Что даёт воспроизводимая среда разработки и как развернуть контейнеры на VPS
4. Анализ и модернизация коннектора баз данных с помощью AI-агентов

Привет! Меня зовут Игорь Росляков, я технический писатель. По приглашению руководителя направления «Маркет и интеграции»Сергея Востриковаготовлю цикл статей на тему ИИ-ассистированной разработки решений дляБитрикс24.

Статьи из цикла можно использовать как туториалы при создании локальных приложений в свой бизнес-портал. Их можно показать своим разработчикам или использовать самому, если работаете один и хотите кастомизировать работу дополнительными удобными функциями.

Сегодня — 4-я статья из цикла. Рассказываем про работу с проектом BI-коннектора. Если упрощённо, то это инструмент для аналитики не только по показателям портала — сделкам, клиентам и другим — но и по внешним базам данных. С ним получается мост между Битрикс24 и любыми другими источниками данных.

Что было в предыдущих статьях:

1. Пишем первое приложение с AI-стартером, чтобы видеть прибыли и убытки
2. Добавляем в бизнес-портал Битрикс24 роботов для автоматизации
3. Что даёт воспроизводимая среда разработки и как развернуть контейнеры на VPS.

Как и в работе с AI-стартером, работать мы будем с помощью AI-агентов. В этом проекте я использовал Codex.

Что будет в статье:

• Что нужно установить перед работой
• Что за BI-connector, зачем он нужен и как работает
• Анализ проекта для дальнейшей работыОсновные точки входа1. Слой установки2. Слой HTTP-обработки3. Слой работы с БД
• Задача 1: установка в порталПоднимаем проект локальноДобавить tunnel / внешний доступПодключить приложение к порталуЧто поменял и добавил агентПроверяем, что приложение установилось
• Задача 2: оптимизация безопасности и покрытие тестамиЧто поменял и добавил агент
• Задача 3: модернизируем проект: добавляем автомаппингЧто поменял и добавил агент
• Результат
• Что будем делать дальше
• Содержание цикла статей про создание приложений с AI-агентами

Что нужно установить перед работой

Репозиторий для старта:github.com/bitrix24/bi-connector. Мы клонируем его на локальную машину и будем работать с ним.

Итоговый репозиторий, который подключен к порталу:github.com/igorrosliakov-bitrix24/Bitrix24-BIConnector

Что ещё понадобится:

• Docker и Docker Compose для контейнеризации.
• Git для контроля версий и пуша в удалённый репозиторий.
• make для коротких команд.
• Публичный HTTPS-туннель черезCloudPub. Получить можно через десктопный клиент или инструмент командной строки clo.

Что за BI-connector, зачем он нужен и как работает

В портале Битрикс24 есть раздел BI-конструктор, а в нём есть вкладка — «Рабочее место аналитика»:

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

BI-коннектор нужен для создания такого внешнего подключения.

Получается такая схема:

• У нас есть база данных, которая может быть на отдельном сервере, в Docker-контейнере, облаке или локально на машине.
• BI-коннектор получает параметры подключения к этой базе.
• И уже через коннектор Битрикс24 начинает видеть таблицы и данные.

Анализ проекта для дальнейшей работы

Я попросил агента тщательно проанализировать проект и составить план работы для подключения к порталу, оптимизации, усиления безопасности и стабильного добавления новых фич. Поэтому сначала агент разобрал репозиторий и составил исходную картину.

Задача агенту:Проанализируй этот проект подробно: объясни, что это за сервис, для чего он нужен и как он работает в связке с Битрикс24. Сначала дай простое верхнеуровневое объяснение, потом опиши техническую архитектуру: основные файлы, точки входа, ключевые классы и поток запроса. Отдельно укажи, что в проекте уже реализовано, а какие части выглядят как кандидаты на доработку.

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

Вот что в итоге Codex рассказал о проекте.

Основные точки входа

Агент нашёл 4 основные точки входа:

• Application.php отвечает за install-flow и регистрацию коннекторов в Битрикс24.
• index.php или затем выделенный request-handler отвечает за входящие BI-запросы.
• BiConnector.php отвечает за доступ к БД и за контракт BI-коннектора.
• QueryBuilder.php отвечает за построение SQL.

Технически сервис умеет подключаться к БД, отдавать список таблиц, отдавать структуру и отдавать данные.

BI-коннектор — это отдельный серверный сервис, которое поднимается локально или на сервере и принимает запросы от Битрикс24. Портал не встраивает этот код себе внутрь, вместо этого он делает HTTP-запросы в наше приложение: «проверь подключение, покажи список таблиц, покажи структуру таблицы». В ответ на это приложение отвечает в JSON-формате.

Кроме точек входа, технически проект состоит из 3 основных частей-слоёв.

1. Слой установки

Главный серверный orchestration-класс — Application.php. Он принимает install-событие от Битрикс24, сохраняет auth и регистрирует в бизнес-портале два коннектора: MySQL и PostgreSQL.

Так мы регистрируем в Битрикс-портале контракт:

• какой URL вызывать для проверки
• какой URL вызывать для списка таблиц
• какой URL вызывать для схемы
• какой URL вызывать для данных

2. Слой HTTP-обработки

Когда Битрикс24 вызывает наш сервис, попадает вpublic/index.php.После оптимизации в сценарий обработки добавился ещё один скрипт —ConnectorRequestHandler.php.

Этот слой делает несколько вещей:

• Читает query-параметры вроде action и connection_type.
• Парсит JSON body.
• Валидирует входные данные.
• Создаёт нужный коннектор.
• Вызывает нужное действие.

3. Слой работы с БД

С базой работает BiConnector.php. Он отвечает за создание подключения, проверку БД, получение списка и структуры таблиц и остальную работу.

Отдельный SQL-builder находится вQueryBuilder.php. Он собирает SQL-запрос, применяет select, filter и limit и возвращает данные в формате, который ожидает портал.

Задача 1: установка в портал

Сначала проект нужно подключить к порталу.

Задача агенту:Помоги подключить этот проект к Битрикс24 как локальное приложение. Сначала определи, чего не хватает для установки и внешней доступности сервиса, потом распиши пошагово, что нужно настроить в проекте, в окружении и в самом портале. Объясняй в двух уровнях: сначала просто для новичка, потом технически с точными файлами, переменными окружения, URL и командами.

Первая проблема простая: Битрикс24 не может установить приложение изlocalhostнапрямую. Если проект просто запущен локально на машине, портал не увидит его, потому что находится снаружи, аlocalhostвиден только на компьютере. Поэтому сначала нужно решить вопрос с доступностью.

Короткий план на этот этап:

1. Сам проект должен запускаться локально.
2. У проекта должен появиться внешний HTTPS-адрес.
3. Проект должен знать свой внешний адрес.
4. Битрикс24 должен получить install URL и handler URL этого проекта. Без этого портал не сможет ни установить приложение, ни ходить в него за BI-запросами.

Поднимаем проект локально

Сначала проект должен начать работать просто как локальный HTTP-сервис. Для этого нужны Docker, файл .env, docker-compose и рабочий app-контейнер.

То есть первый минимум: клонировать репозиторий, создать .env и поднять контейнер приложения.

Добавить tunnel / внешний доступ

Битрикс24 ожидает, что endpoint любого приложения, в том числе локального, доступен как внешний HTTPS URL. Поэтому нужен либо деплой на сервер, либо локальный деплой через туннель. Мы выбрали вариант туннеля через CloudPub.

Для использования CloudPub нужно зарегистрироваться в системе и получить токенна главной странице регистрации. После этого токен можно отдать агенту, чтобы он добавил его в .env-файл. Так мы получим внешний HTTPS-адрес для регистрации в портале Битрикс24.

Сам проект тоже должен понимать, какой у него публичный домен и какие URL он должен зарегистрировать в портале. Например, когда приложение устанавливается, оно регистрирует такие endpoint:

• /?connection_type=mysql&action=check
• /?connection_type=mysql&action=table_list
• /?connection_type=postgresql&action=dataи так далее

Но эти URL должны строиться не отlocalhost, а от реального внешнего адреса. То есть проекту нужен был параметр вида: APP_DOMAIN=https://something.cloudpub.ru.

Подключить приложение к порталу

Когда агент проведёт все приготовления, приложение нужно установить на свой портал по инструкции из 1-й статьи в разделе«Регистрируем приложение на портале Битрикс24».

Обратите внимание, что на последнем экране для сегодняшнего проекта нужно поставить галочку «Использует только API» и не забывать выставить права biconnector:

Что поменял и добавил агент

В .env.exampleрасширился пример окружения, чтобы проект мог работать не только как абстрактный backend, но и как локально публикуемое приложение. Главные добавления были такие:

• CLOUDPUB_TOKEN, нужен для самого туннеля.
• CLOUDPUB_IMAGE, нужен для выбора Docker image CloudPub.
• BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnectorфиксирует, что приложение работает именно как BI connector app.

Вdocker-compose.ymlдобавили отдельный сервис cloudpub. Смысл этого сервиса:

• ПолучаетTOKEN.
• Знает, что HTTP нужно прокидывать вapp:80.
• Работает в одном docker network с приложением.
• Поднимает внешний HTTPS URL для локального app-контейнера.

ВMakefileагент добавил команды, чтобы весь сценарий можно было запускать dev-командами, а не руками. Ключевые команды:

• dev-init
• start-cloudpub
• logs-cloudpub

Появился скрипт автоматизацииscripts/dev-init.sh. Скрипт делает примерно следующее:

• Запускает app.
• Запускает cloudpub.
• Читает из логов CloudPub реальный внешний URL.
• Пишет этот URL вAPP_DOMAIN.
• Перезапускает приложение, чтобы оно уже использовало правильный домен.

Почему это важно: еслиAPP_DOMAINне совпадает с реальным публичным URL-туннелем, то Bitrix24 потом будет вызывать не те адреса, и коннектор не зарегистрируется правильно.

Application.php.Основная логика регистрации коннекторов уже была, но на этапе подключения к порталу нужно убедиться, что она строит URL изAPP_DOMAIN.

Проверяем, что приложение установилось

Для проверки работоспособности коннектора он должен быть связан с базами данных. Можно попросить агента создать новые тестовые, или привязать уже существующие.

Если у вас уже есть готовая база, то в проекте обычно ничего менять не нужно, если:

• база MySQL/PostgreSQL;
• коннектор может до неё достучаться по сети;
• у вас есть доступы.

Менять может понадобиться только окружение:

• .env, если вы хотите сохранить какие-то свои dev-параметры;
• docker-compose.yml, если захотите поднять свою БД рядом в контейнере.

В разделе BI-конструктор сначала нужно зайти в «Рабочее место аналитика» и начать создавать новое подключение:

На следующем экране нужно выбрать «Создать подключение»:

После этого выбираем тип источника данных и заполняем все значения:

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

После создания должна быть возможность выбрать конкретную таблицу из базы данных и просмотреть её:

Второй вариант проверки — через curl-команду такого вида:

Если всё работает, в ответ придёт сообщение такого вида:

Можно запросить список таблиц:

Или описание конкретной таблицы:

Задача 2: оптимизация безопасности и покрытие тестами

После подключения к порталу и проверки основных функций я попросил агента улучшить надёжность проекта и покрытие тестами. В проекте уже были тесты, поэтому агент просто усилил то, что было.

Задача агенту:Проанализируй проект с точки зрения безопасности и качества кода, а затем предложи и внеси улучшения. Сначала улучши обработку входных данных, логирование и другие уязвимые места, потом покрой критические сценарии тестами и настрой удобный запуск покрытия. В конце покажи, какие тесты появились, что именно они проверяют и как запускать тесты, линтеры и coverage.

Когда проект работает как мост между бизнес-порталом Битрикс24 и внешней базой, у него есть три главных риска:

• сломать обработку запросов при доработках;
• случайно пропустить опасные или кривые входные данные;
• создать утечку чувствительных данных в логах.

Агент сделал 2 вещи.

Усилил безопасность поведения.Проект стал аккуратнее принимать запросы, валидировать их и логировать. Например:

• Если приходит битый JSON, приложение теперь не падает «как получится», а возвращает понятный 400 Bad Request.
• Если нет обязательных параметров подключения, оно сразу говорит, что именно не хватает.
• Если в логах есть password, token, secret, authorization, эти значения теперь маскируются и не попадают в лог в открытом виде.
• Для SQL-части мы усилили безопасность одного места, где имя таблицы в MySQL-описании стало проходить через корректное quoting.

Улучшил тестовое покрытие.Перед тем как модернизировать проект дальше, мы должны были зафиксировать его поведение тестами, чтобы новые изменения не ломали старое.

Мы покрыли тестами не только «счастливый путь», но и проблемные сценарии:

• Неправильный JSON.
• Отсутствие connection.
• Неверный connection_type.
• Неизвестный action.
• Нормализацию лимита.
• Преобразование имён полей.
• Сборку SQL-запросов.
• Безопасную обработку логов.

Запуск покрытия стал удобным. То есть теперь проект можно не просто тестировать, а ещё и посмотреть, какие части кода реально покрыты тестами, а какие пока нет.

Если упрощённо, результат работы с безопасностью был такой:

• Проект стал меньше доверять входным данным.
• Проект перестал светить секреты в логах.
• Проект стало безопаснее рефакторить.
• У нас появился понятный способ показать, какие части системы уже проверяются автоматически.

Что поменял и добавил агент

Выделили обработку входящих запросов в отдельный класс.Файл: src/ConnectorRequestHandler.php.

Раньше входная логика была менее изолированной. Теперь появился отдельный request-handler, который:

• Разбирает action и connection_type.
• Вытаскивает input из form-data и JSON.
• Валидирует обязательные параметры.
• Переводит ошибки в контролируемые HTTP-ответы 400 или 500.
• Централизует dispatch на check, table_list, table_description, data.

Сделали entrypoint чище.Файл:public/index.php.

Теперьindex.phpне держит в себе толстую бизнес-логику, а передаёт запрос в ConnectorRequestHandler. Это архитектурно чище и проще для тестирования.

Усилили безопасность логирования.Файл:src/Application.php.

В логгер добавлен processor, который прогоняет context и extra через санитайзер:

И сам санитайзер скрывает чувствительные ключи:

За счёт этого в логах не торчат пароли БД, токены, client secret, authorization payload.

Добавилось безопаснее логирование внешних ответов.В  src/Application.php появился метод formatResponseForLog(), который пытается безопасно распарсить JSON-ответ и замаскировать чувствительные поля, прежде чем они попадут в лог.

Поджали SQL-частьдля MySQL schema inspection в файле src/BiConnector.php

Подготовили отдельную инфраструктуру для coverage.Файл: Dockerfile.test.

В тестовый контейнер добавлен Xdebug в режиме coverage:

Добавили удобную make-команду для покрытия.Файл: Makefile.

Выполняем команду:

И HTML-отчёт лежит в директории coverage/.

В конце агент добавил и расширил unit-тесты.

Задача 3: модернизируем проект: добавляем автомаппинг

Последний шаг работы на сегодня: новая фича.

В базе данных может быть колонка такого вида:Created By

Но Битрикс24 ожидает другое:CREATED_BY

Поэтому для гладкой надёжной работы в приложении коннектора не хватает слоя-переводчика. Нужен двусторонний маппинг такого вида:

• реальное имя в БД:Created By
• имя для Битрикс24:CREATED_BY

Задача агенту:Добавь в проект фичу автомаппинга полей между внешней базой данных и форматом Битрикс24. Если в БД поле называется, например, "Created By" или "City / Region", коннектор должен отдавать его в Битрикс24 как "CREATED_BY" и "CITY_REGION", а при входящих запросах от Битрикс24 уметь переводить эти имена обратно в реальные имена колонок для SQL-запроса. Продумай архитектуру и добавь тесты.

Для этого понадобится слой логики, который работает так:

• получает реальную структуру,
• строит безопасные Bitrix-коды,
• запоминает соответствие,
• при запросе от Б24 подменяет CREATED_BY обратно на Created By,
• выполняет запрос к реальной БД,
• и затем снова отдаёт ответ в Bitrix-формате.

Визуально работать это должно так. В БД есть колонка Created By, но наружу в Битрикс24 мы отдаём:

code = CREATED_BY

name = CREATED_BY

У у себя внутри сохраняем map:

CREATED_BY -> Created By

После этого портал присылаетselect: ["CREATED_BY"]. Мы перед SQL-запросом меняем это на реальное поле Created By, выполняем запрос, а в ответе снова отдаём данные под кодомCREATED_BY.

Без этого могут быть проблемы с пробелами в названиях полей, смешанным регистром, дефисами, спецсимволами. То есть эта фича делает коннектор сильно более совместимым с реальными внешними БД, а не только с аккуратными таблицами, где всё уже называется какCREATED_BY.

Результат работы можно проверить не только на портале. Один из вариантов — через плагины SQL Tools в VS Code.

Здесь мы делаем два разных запроса в уже готовом приложении — в расширении и в терминале, чтобы посмотреть, как выглядят данные в БД в реальности и как их обрабатывает коннектор для передачи в портал Битрикс24.

Нюанс в том, что надо сразу продумать коллизии. Например:

• Created By
• Created-By
• Created_By

Все эти названия могут превратиться в один и тот же кодCREATED_BY. Значит, нужен либо детерминированный способ решить конфликт, либо fallback вродеCREATED_BY__2, либо хранение уникального внутреннего идентификатора.

Что поменял и добавил агент

Шаг 1.Codex добавил отдельный слой нормализации имён полей вFieldNameMapper.php. Он преобразует, например,Created ByвCREATED_BY,City / RegionвCITY_REGION. При коллизиях создаются уникальные коды вродеCREATED_BY_2.

• получает список реальных полей таблицы;
• для каждого поля строит “bitrix-safe” код;
• сохраняет связь нормализованное имя -> реальное имя.

Шаг 2.Этот маппинг подключили в BiConnector.php: table_description теперь отдаёт Bitrix-безопасные имена, а getData() сначала получает mapping, потом передаёт его в query layer.

В этом коде:

• БД отдаёт, например, Created By;
• FieldNameMapper превращает это в CREATED_BY;
• дальше коннектор уже работает с этой нормализованной схемой.

Шаг 3.QueryBuilder.php обновили, чтобы запросы от Битрикс24 работали по нормализованным полям, а внутри SQL использовались реальные имена колонок. То естьselect: ["CREATED_BY"]идёт в БД какCreated By, а в ответе снова возвращаетсяCREATED_BY.

Автомаппинг работает не только для SELECT, но и для:

• filter
• LIKE
• IN
• BETWEEN
• обычного=

Дополнительно агент создал demo-таблицуfriendly_columnsс колонками с реальными названиями:Created By,Office Name,City / Region,Opened At.

Всё это было покрыто тестами вFieldNameMapperTest.phpиQueryBuilderTest.php.

Агент проанализировал существующий проект и успешно модернизировал его трижды:

1. Для подключения к порталу по HTTPS-туннелю.
2. Для усиления безопасности и тестового покрытия.
3. Для внесения оптимизации автомаппинга полей.

В отличие от предыдущих опытов, на этот раз ИИ нигде не зависал надолго и сделал всю работу достаточно быстро. Самой сложной частью было сформулировать задачу и план работы.

Что будем делать дальше

Мы уже добавляли UI-приложения, автоматизировали сделки с роботами, деплоили проекты на сервер и оптимизировали существующие сервисы. В следующий раз попробуем поработать с чат-ботами на бэкенде.

Если вам интересна какая-то тема про кастомизацию портала — напишите в комментариях, а мы постараемся раскрыть её в следующих статьях.

Содержание цикла статей про создание приложений с AI-агентами

1. Пишем первое приложение с AI-стартером, чтобы видеть прибыли и убытки
2. Добавляем в бизнес-портал Битрикс24 роботов для автоматизации
3. Что даёт воспроизводимая среда разработки и как развернуть контейнеры на VPS.
4. Анализ и модернизация коннектора баз данных с помощью AI-агентов