Импорт иерархий и создание связей в Planiqum¶

Основные сценарии импорта¶

Импорт иерархических данных осуществляется через команды Django:
```
python manage.py importhierarchyitemsdir <путь_к_директории>
```
Путь должен указывать на директорию внутри установленного приложения (например, data/hierarchy внутри test_basics).
Поддерживаются форматы CSV и XLSX. Для каждого уровня иерархии должен быть отдельный файл с именем <level_key>.<csv|xlsx>.
В процессе импорта:
Элементы без родителей корректно импортируются и не создаются связи с NULL-значениями.
Если родитель не найден, связь не создаётся и строка игнорируется.
Все элементы (даже без родителей) попадают в таблицу core_hierarchy_item.

Логика создания связей¶

Для каждого уровня иерархии связи между элементами строятся на основании колонок с ключами родительских уровней.
Если для элемента не указан родитель или родитель не найден — связь не создаётся, IntegrityError не возникает.
В таблицу core_hierarchy_item_parents попадают только валидные связи (оба элемента существуют).

Важные моменты¶

Путь к директории импорта должен быть внутри установленного приложения (см. CUSTOM_INSTALLED_APPS).
Если директория не найдена, будет выброшено исключение с соответствующим сообщением.
Для тестовых данных рекомендуется использовать отдельное приложение (например, test_basics) и хранить данные в data/hierarchy.

Пример структуры данных для импорта¶

test_basics/
└── data/
    └── hierarchy/
        ├── level1.csv
        ├── level2.csv
        └── ...

Пример файла уровня (CSV)¶

shortname	description	parent_level
item1	...	parent1
item2	...

Если parent_level пустой или не найден — связь не создаётся, но элемент импортируется.

Отладка и журналирование¶

Весь процесс импорта логируется (см. core_hierarchy/libs/import_hierarchy_items.py).
В журнале импортов фиксируются:
Количество добавленных, обновлённых элементов
Количество добавленных, обновлённых, удалённых связей
Ошибки и исключения

Типовые ошибки¶

ValueError: Директория не найдена ни в одном из установленных приложений — проверьте путь и настройки INSTALLED_APPS/CUSTOM_INSTALLED_APPS.
IntegrityError: null value in column "to_item_id" — устранено, теперь такие связи не создаются.

См. также¶

Используемые методы и их специфика¶

Основные функции и модули¶

import_hierarchy_items_dir(path, root_='IMPORT_ROOT')
Импортирует иерархические данные из директории.
Автоматически определяет уровни и соответствующие им файлы.
Использует настройки проекта для поиска директории (обычно внутри установленного приложения).
Логирует процесс, выбрасывает ValueError, если директория не найдена.
import_hierarchy_items(level=None, df=None, filename="", ...)
Импортирует элементы иерархии для одного уровня.
Может принимать DataFrame напрямую или путь к файлу.
Автоматически группирует по shortname, чтобы избежать дублирования.
Вызов из import_hierarchy_items_dir происходит для каждого уровня.
_import_hierarchy_items_from_df(level, df)
Основная функция, реализующая логику импорта из DataFrame.
Создаёт/обновляет элементы, вызывает функции для создания связей.
Ведёт журнал импортов (ImportResult).
Обрабатывает ошибки и исключения.
__import_hierarchy_items_body(level, df)
Импортирует и обновляет элементы уровня (core_hierarchy_item).
Обновляет description, is_active, is_new.
Создаёт временные таблицы для ускорения операций.
__import_hierarchy_items_rel(level, df)
Создаёт связи между элементами (core_hierarchy_item_parents).
Использует melt DataFrame для нормализации связей.
Не создаёт связи, если родитель не найден (to_item_id is NULL).
Все операции с временными таблицами и SQL-запросами логируются.

Специфика использования¶

Все функции используют Pandas DataFrame для обработки данных, что позволяет легко интегрировать импорт из различных форматов (CSV, XLSX).
Для ускорения операций массового импорта используются временные таблицы и bulk-операции через SQL.
Вся логика построена так, чтобы не возникало IntegrityError при отсутствии родителей — такие связи просто игнорируются.
Для отладки и аудита используется подробное логирование (см. core_hierarchy/libs/import_hierarchy_items.py).
Импорт можно запускать как через manage.py, так и программно из других частей кода.
Для тестирования рекомендуется использовать отдельные приложения с тестовыми данными и явно указывать их в CUSTOM_INSTALLED_APPS.

Пример программного использования¶

from planiqum.core.hierarchy.libs.import_hierarchy_items import import_hierarchy_items
import pandas as pd

df = pd.read_csv('data/hierarchy/level1.csv')
import_hierarchy_items(level='level1', df=df)