Bitrix24 Bi Reports

---
name: bitrix24-bi-reports
description: "Отчёты Директ → лид → сделка → выручка в BI Конструкторе Битрикс24 (Apache Superset): датасеты crm_lead, crm_deal, crm_lead_status_history, telephony_call, tracking_source_expenses, SQL Lab, атрибуция обращений, проверка цифр по REST, безопасная правка датасетов и дашборда с откатом."
---

# Битрикс24 BI Конструктор: сквозные отчёты

## Граница задачи

Навык строит и проверяет отчёты в BI Конструкторе. По умолчанию — чтение: SQL Lab только `SELECT`, просмотр дашбордов, экспорт. Правка датасетов, графиков, фильтров, CSS и дашбордов — только после плана, снимка «до», независимой проверки кода записи и «да» владельца. Рекламу и CRM этот навык не меняет; CRM читает навык `bitrix24-crm-api`, Директ — `yandex-direct-unified`.

## Как устроен BI Конструктор

1. Отчёты строятся в редакторе на Apache Superset. Данные Битрикс24 лежат в базе `trino`, схема `bitrix24`; SQL пишется в «SQL > SQL Lab», результат сохраняется кнопкой «Сохранить датасет» (виртуальный датасет).
2. Таблицы: лиды `crm_lead`, `crm_lead_uf` (пользовательские поля, связь `crm_lead.ID = crm_lead_uf.LEAD_ID`), `crm_lead_status_history` (`TYPE_ID`: 1 создание, 2 промежуточная, 3 финальная); сделки `crm_deal`, `crm_deal_uf`, `crm_deal_stage_history`; дела `crm_activity`; звонки `telephony_call` (`CALL_TYPE`: 1 исходящий, 2 входящий, 3 входящий с перенаправлением, 4 обратный звонок); контакты `crm_contact`, компании `crm_company`; пользователи `user`; реклама `tracking_source` и `tracking_source_expenses` (расход по дням, кампания, группа, объявление, показы, клики, UTM). Состав таблиц сверяй приложением «Справочник BI-таблиц» или справкой.
3. Рекламные кабинеты (Яндекс, VK, Google Ads) подключаются в «Рабочее место аналитика → Подключения». Для Яндекс.Директа метки UTM обрабатываются только у объявлений типов `TEXT_AD` и `TEXT_IMAGE_AD`; чужие шаблоны вроде `{keyword}` передаются как есть.
4. Таблица расходов не хранит данные: каждый запрос идёт в Директ. Фильтруй её по периоду через `WHERE`, иначе запрос может упасть.
5. Права: отдельных учётных записей BI нет, отчёт работает под правами пользователя. Права на отчёты задаются в «Настройки BI-аналитики».
6. Диагностика медленных отчётов: в SQL Lab со схемой `bitrix24` — `SELECT * FROM TABLE(bitrix24.bi_queries_t())` (история запросов, по умолчанию 1000 строк, добавляй `LIMIT`) и `SELECT bi_explain_query('<query_id>', '<время запроса>')` (время ровно как в истории, без лишних знаков).

## Вход в редактор

Вход в Superset из портала, роли и владельцы объектов, CSRF-токен и проверенные вызовы API — в [справочнике](references/superset-api.md); прочитайте его целиком до первой записи.

Меню отчёта «⋯» в шапке — элемент `div#more-btn.dashboard-header-buttons-more`, а не `button`; пункт «Редактировать отчёт» открывает Superset. Отсутствие кнопки в дереве доступности не доказывает отсутствие прав: проверь DOM шапки и нажми. Права и ключи не меняй. Работай во вкладке, где владелец уже вошёл; отдельный вход не создавай.

## Датасеты: правила SQL

1. Одна строка атрибуции на лид: группируй по ID лида и считай число совпадений кампании и объявления; при нескольких совпадениях выводи «неоднозначно», не `min()`.
2. Фильтр тестовых и служебных записей один и тот же во всех датасетах, для сделок — и по связанному лиду. Поля такого признака у каждого портала свои: сначала найди их в схеме (`crm.lead.userfield.list` через `bitrix24-crm-api` или `DESCRIBE` в SQL Lab) и запиши соответствие «признак → поле». Пример для портала с пользовательскими полями `is_test`, `is_service`, `form_type`: `NOT coalesce(uf.is_test, false) AND NOT coalesce(uf.is_service, false) AND NOT starts_with(coalesce(uf.form_type, ''), 'service_')`. В `LIKE` символ `_` означает любой символ: для буквального префикса используй `starts_with` или `LIKE 'service\_%' ESCAPE '\'`.
3. Порядок атрибуции как в `bitrix24-crm-api`: точная метка с кампанией из таблицы расходов, затем номер коллтрекинга при создании лида (окно 300 секунд, ближайший звонок, номера из карты значениями `VALUES`), затем подпись источника CRM. Для лида всегда есть запасное значение источника (`coalesce`), иначе при рассинхроне чтения таблиц появляются строки `NULL`.
4. Вариант метки `ya` принимай только при `cpc` и кампании из расходов. Названия статических источников в SQL должны совпадать побуквенно с названиями источников в расходах и коллтрекинге.
5. Исходящие звонки операторов — отдельный источник «Исходящий звонок оператора» (звонок типа 1 в пределах нескольких секунд от создания лида), не «не реклама».
6. Этапные столбцы включают все статусы лида, в том числе «нет показаний» и «некачественная заявка»; сумма этапов должна равняться числу лидов. «Первое достижение этапа» считай как «дошёл до этапа или дальше».
7. Воронки сделок: перечисли все категории; если отчёт охватывает не все, подпиши на дашборде, какие исключены и какую выручку это даёт. Успешные стадии определяй по семантике `S`, а не только по `WON`.
8. Выручка — сумма успешных сделок CRM по дате создания лида или по дате закрытия (укажи на дашборде), не оплата. Показатели без источника данных (показы, клики, CPL у источников без рекламы) помечай «нет данных», не нулём.
9. Показатели сводной таблицы присутствуют в каждой строке событий (значение 0), чтобы число столбцов не зависело от фильтра. Подписи столбцов, привязанные CSS к позиции `nth-child`, сдвигаются, если показателя нет в выборке: после каждой правки проверь все источники и периоды.
10. Для динамического фильтра по дате: колонка даты в `SELECT`, кнопка «Синхронизировать столбцы из источника», условия `from_dttm`/`to_dttm` через `from_iso8601_timestamp`; поле даты в блоке фильтров графика задай всегда, иначе данные грузятся за всё время; верхняя граница строгая `<`.
11. Не заводи в SQL коэффициентов НДС «по памяти»: сначала проверь признак НДС источника расходов.

## Период и кэш

1. Период «По умолчанию Последние 30 дней» заканчивается вчера: новые кампании и сегодняшние лиды не видны. Для рабочего отчёта задай «Текущий месяц» или нужный интервал и перечитай настройку после сохранения.
2. Последняя дата расходов в отфильтрованном отчёте не доказывает остановку выгрузки: сначала сверь обе границы периода, их включительность и данные за сегодня.
3. Копия данных BI и кэш отстают (до десятков минут, кэш до часа). Сверяй цифры через час после последней правки CRM. Свежие лиды и звонки могут попасть в разные датасеты в разное время.

## Проверка цифр

1. Независимый пересчёт: выгрузи лиды, сделки и звонки навыком `bitrix24-crm-api` на ту же границу времени, разнеси по тем же правилам и сравни с BI построчно по источникам (итог лидов, лиды по источникам, число и сумма успешных сделок, расход по кампаниям). Расхождение — ошибка либо задержка копии: повтори через час; остаточная ошибка остаётся ошибкой.
2. Контрольные записи: заранее выбери 3–5 известных лидов (с меткой, с рекламным номером, исходящий, без источника) и проверь, в какую строку каждый попал.
3. SHA-256 живого SQL каждого датасета сверяй с локальным файлом до записи и после неё.
4. Все графики и фильтры дашборда прогони после правки на ответ 200; проверь фильтры по каждому источнику, период без успешных сделок и период «всё время».
5. В отчёте клиенту пиши, какой период, какая граница времени, что сверено и что нет. Числа бери только из вывода инструментов этого прогона.

## Сбой источника расходов

Если Директ перестал отвечать (например, пустой ответ HTTP 204 на любой запрос), падают все датасеты, читающие таблицу расходов, вместе с фильтрами; ошибку таблицы внутри запроса перехватить нельзя. План: (1) резервные датасеты без таблицы расходов, справочник кампаний, групп и объявлений значениями в CTE (предел движка — 150 стадий, поэтому справочник через `VALUES`, не чтением таблиц), расходы, показы и клики равны 0 при сохранённом числе столбцов; (2) вторая вкладка дашборда «Без Директа»; на время сбоя ставь её первой; (3) после восстановления сверь резервные и живые наборы за один период (лиды, сделки, выручка совпадают) и пересобери справочник.

## Запись в BI

Изменения Superset выполняются из консоли вкладки, где владелец уже вошёл (внешнего API с токеном у BI нет; нужен CSRF-токен страницы).

1. Снимок «до»: `GET /api/v1/dataset/{id}` (SQL, `always_filter_main_dttm`, `normalize_columns`), `GET /api/v1/dashboard/{id}` (`position_json`, `json_metadata`, `css`), список графиков дашборда. Сохрани локально вместе с SHA-256.
2. Код записи прогони на моке, который воспроизводит ответы сервера (401, 403, 500, повтор), и покажи независимой проверке.
3. Запись датасета: `PUT /api/v1/dataset/{id}` с телом `{sql, always_filter_main_dttm, normalize_columns}` (тело только с `sql` может сбросить настройку фильтра времени). Создание нового датасета: `POST /api/v1/dataset/` без поля `catalog` (с ним встречался HTTP 500); дублирование датасета ролью может быть запрещено (403).
4. Дашборд: `PUT /api/v1/dashboard/{id}` с `position_json`, `json_metadata`, `css`; перед записью проверь привязку графиков и область действия каждого фильтра (фильтр на втором датасете сам не включается из-за одинакового имени поля).
5. Сразу после записи прочитай всё обратно и сравни SHA; остановись при первом расхождении. Скрипт отката держи готовым в консоли.
6. Копия отчёта штатной кнопкой «Сделать копию» безопаснее правки рабочего отчёта: создай копию, свои датасеты и переключи графики, исходный отчёт не трогай до сверки.
7. Ответ 500 на запись означает «исход неизвестен»: перечитай датасет, не повторяй запись вслепую.

## Граница публикации

Не публикуй адреса порталов, ID отчётов, датасетов и графиков клиента, названия кампаний, телефоны и номера рекламных линий. В публичных примерах используй вымышленные значения.