# Отчет по нарушенной переменной ссылочности

Отчет используется для анализа некорректных `gid`-ссылок в данных системы. Он помогает определить, где нарушена переменная ссылочность, какие группы нарушений требуют проверки и в каких объектах хранятся проблемные значения.

Путь: `Настройка системы > Настройки и сервисы > Дополнительно > Отчет по нарушенной переменной ссылочности`.

**Нерабочий `gid`** — это значение `gid`, которое ссылается на несуществующий класс или несуществующий объект класса. Также в статистику могут попадать значения, записанные в атрибут `gid`-ссылки, но не соответствующие формату корректного `gid`.

Описание механизма `gid`, формата ссылки, внешних ключей, переменной ссылочности и генерации идентификаторов приведено в разделе [Глобальный идентификатор GID](https://help.globalerp.ru/books/GlobalServerAppGuide/SNAPSHOT/html/030_class/060_%D0%BA%D0%BB%D0%B0%D1%81%D1%81.html#gid).

## Назначение и принцип работы

Отчет предназначен для диагностики ситуаций, когда в атрибутах с `gid`-ссылками хранятся значения, которые система не может корректно разрешить. По отчету можно определить место возникновения проблемы: класс, атрибут, класс, на который указывает значение `gid`, и конкретные объекты, в которых хранится некорректная ссылка.

С помощью отчета можно:

- определить, в каких классах и атрибутах накопились некорректные `gid`-ссылки;
- оценить масштаб нарушения по количеству найденных значений;
- понять, какие группы нарушений нужно проверять в первую очередь;
- найти конкретные объекты, в которых хранится некорректная ссылка;
- проверить результат исправления данных после повторного обновления статистики.

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

Такие нарушения могут возникать из-за особенностей переменной ссылочности: для `gid`-ссылок нет обычного внешнего ключа на уровне базы данных. Поэтому при изменении, удалении или переносе данных корректность ссылок должна обеспечиваться прикладной логикой. Если в доработке или скрипте не предусмотрена обработка связанных ссылочных таблиц, в данных могут остаться `gid`-ссылки на несуществующие классы или объекты.

Отчет отображает заранее сформированную статистику. Данные не пересчитываются при каждом открытии формы, поэтому содержимое отчета отражает состояние на момент последнего обновления статистики.

## Интерфейс отчета

В таблице статистики данные сгруппированы в виде дерева. Первый уровень показывает, в каком классе и каком атрибуте обнаружены некорректные `gid`-ссылки. Эта строка является итоговой для группы: значение в колонке **Количество нерабочих gid ссылок** равно сумме найденных нарушений по дочерним строкам. Колонка **Класс-источник** для итоговой строки не заполняется.

Второй уровень показывает, на классы каких объектов указывают найденные некорректные значения. Такая группировка помогает понять, с какими типами объектов связана проблема, и сузить область дальнейшей проверки. Если значение `gid` не удается сопоставить с существующим классом, в колонке **Класс-источник** может отображаться не имя класса, а пояснение, почему `gid` не удалось обработать, например **пустой gid (не null)** или **Не существует или повреждена таблица с idClass(...)**.

В таблице статистики отображаются колонки:

- **Класс-ссылка** (`sClassRef`) — системное имя класса, в объектах которого хранится некорректная `gid`-ссылка;
- **Атрибут-ссылка** (`sAttrGidRef`) — системное имя атрибута, в котором хранится `gid`-ссылка;
- **Класс-источник** (`sClassSource`) — системное имя класса, на который указывает значение `gid`-ссылки. Если значение `gid` не удается сопоставить с существующим классом, в колонке может отображаться пояснение, почему `gid` не удалось обработать. Для родительских строк значение не заполняется;
- **Количество нерабочих gid ссылок** (`nCount`) — количество найденных нарушений для строки статистики.

Детализация показывает конкретные объекты, относящиеся к выбранной строке статистики. Если строка в таблице статистики не выбрана, детализация может быть пустой. Чтобы посмотреть записи с некорректными ссылками, раскройте итоговую строку и выберите строку второго уровня.

В детализации отображаются колонки:

- **Объект-ссылка** (`gidRef`) — объект, содержащий некорректную `gid`-ссылку;
- **Код** — код объекта;
- **Наименование** — наименование объекта;
- **Нерабочая gid ссылка** (`sGidRef`) — сохраненное значение некорректной `gid`-ссылки.

**Обновление статистики** запускается операцией **Обновить отчет в фоновом режиме**. При запуске операции система очищает текущую статистику и заново заполняет таблицы статистики по некорректным `gid`-ссылкам. Очистка и заполнение выполняются фоновым заданием **Очистка и заполнение статистики по нерабочим gid** с системным именем `Btk_BrokenGidRefillStat`. Задание настроено в менеджере заданий.

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

**Использование отчета**. Для анализа сначала проверьте группы с наибольшим количеством нарушений, затем раскройте нужную строку и выберите класс-источник. После этого в детализации можно посмотреть объекты, содержащие некорректные значения, и использовать эти данные для дальнейшей проверки.

```{tip}
Администраторам рекомендуется регулярно просматривать отчет, чтобы своевременно выявлять накопление некорректных `gid`-ссылок.  
Разрешение найденных проблем выполняется только с участием программиста, который может подготовить корректный скрипт исправления данных, и проектировщика по соответствующему направлению.
```

## Архитектура

Агрегированная статистика отчета хранится в классе `Btk_BrokenGidStat`. В нем хранятся строки дерева статистики: родительские строки соответствуют комбинациям класса и атрибута, в которых обнаружены некорректные `gid`-ссылки, а дочерние строки распределяют найденные значения по классам-источникам.

Иерархия строк строится через атрибут `idParent`. Родительская строка является суммарной по отношению к дочерним строкам: значение `nCount` у родителя равно сумме значений `nCount` у его дочерних строк. У родительских строк `sClassSource` имеет значение `null`.

Детализация хранится в классе `Btk_BrokenGidStatDet`. Каждая запись детализации соответствует отдельной найденной некорректной `gid`-ссылке: `gidRef` указывает на объект, содержащий некорректное значение, а `sGidRef` хранит само сохраненное значение некорректной `gid`-ссылки.

Обновление статистики реализовано через операцию `refillTable` в отображении `Btk_BrokenGidStatAvi#Tree`. При запуске операции выполняется фоновое задание **Очистка и заполнение статистики по нерабочим gid** с системным именем `Btk_BrokenGidRefillStat`. В JEXL-скрипте задания вызывается API-метод `Btk_BrokenGidStatApi.refillTable`, который очищает и заново формирует статистику отчета.