Использование initializeproject и seed-данных для тестирования и отладки¶

Новое поведение:

С версии [дата изменения] команда initializeproject выполняет python manage.py migrate первым шагом в общем списке команд. Все этапы (включая migrate) логируются и сопровождаются комментариями по единому механизму, что облегчает отладку и контроль процесса инициализации.

Назначение¶

Команда initializeproject позволяет быстро развернуть проект с необходимой бизнес-метаинформацией и тестовыми данными. Это удобно для: - комплексного тестирования бизнес-логики - отладки и ручной проверки - воспроизводимости среды для новых разработчиков

Как это работает¶

Команда вызывает цепочку management-команд: 1. migrate — применение всех миграций базы данных 2. collectscripts — сбор служебных скриптов 3. generatecalendar — генерация календаря (например, недель) 4. loadhierarchy — загрузка иерархий (уровни, связи, элементы) 5. loadparameters — загрузка параметров, измерений, мер

Подробнее о синхронизации: См. Синхронизация параметров (для разработчиков) — что происходит при синхронизации параметров. 6. loaddata — загрузка фактических данных (фактов)

В процессе выполнения в консоль выводятся подробные сообщения о каждом этапе, а также ведётся логирование через стандартный logging Python для всех шагов.

Организация seed-данных и фикстур¶

1. Мета-информация (fixtures)¶

Файлы должны называться строго:
hierarchy.yaml — описание типов иерархий и уровней
parameters.yaml — описание параметров, измерений, мер
Формат файлов соответствует структуре фикстур моделей (см. Базовые понятия).

Пример структуры fixtures/hierarchy.yaml:

- model: hierarchy.type
  fields:
    key: planning
    shortname: Планирование

- model: hierarchy.level
  fields:
    type: [planning]
    key: dpu
    shortname: Объект планирования спроса
    description: ...
# и т.д. для всех уровней

Пример структуры fixtures/parameters.yaml:

- model: parameters.dimension
  fields:
    key: dpu
    hierarchy_level: [dpu]
    shortname: Объект планирования спроса

- model: parameters.parameter
  fields:
    key: demand_plan
    app_name: demand
    shortname: План продаж
    dimensions:
      - [dpu]
      - [horizon__week]
# и т.д. для всех параметров и мер

Примеры реальных файлов: см. файлы test_basics/fixtures/hierarchy.yaml и test_basics/fixtures/parameters.yaml в репозитории

2. Данные для наполнения элементов иерархии¶

Должны храниться в папке: data/hierarchy/
Каждый уровень — отдельный CSV-файл: dpu.csv, brand.csv, category.csv и т.д.
Формат соответствует структуре элементов иерархии и связей между ними.

Пример data/hierarchy/dpu.csv:

key,shortname,description
DPU1,Объект 1,Описание 1
DPU2,Объект 2,Описание 2

Примеры реальных файлов: см. папку test_basics/data/hierarchy/ в репозитории

3. Данные для заполнения таблицы фактов¶

Обычно размещаются в папке data/ (или подкаталогах, если есть разделение по параметрам/фактам).
Формат: CSV-файлы, структура которых соответствует структуре таблицы фактов (см. базовые понятия и структуру параметров).

Пример:

parameter_key,level_dpu,level_month,qty
sales,DPU1,2024-01,100
sales,DPU1,2024-02,120

Проверьте, поддерживается ли импорт фактов из этих файлов в вашей версии загрузчика.

4. Пример структуры приложения¶

test_basics/
  fixtures/
    hierarchy.yaml
    parameters.yaml
  data/
    hierarchy/
      dpu.csv
      brand.csv
      ...
    # facts/ (если реализовано)

5. Как использовать¶

Добавьте приложение с такой структурой в INSTALLED_APPS.

Запустите команду:

python manage.py initializeproject <start-date> <end-date> [add_tech_week]

<start-date> — начальная дата (формат YYYY-MM-DD)
<end-date> — конечная дата (формат YYYY-MM-DD)
[add_tech_week] — опциональный аргумент (true/false), включает технические недели в календаре. По умолчанию false (технические недели не создаются).

Примеры:

python manage.py initializeproject 2024-01-01 2024-12-31           # без технических недель
python manage.py initializeproject 2024-01-01 2024-12-31 true      # с техническими неделями

3. Данные из meta- и data-файлов будут загружены автоматически.

Внимание! Суперпользователь (администратор) не создаётся автоматически. После инициализации проекта обязательно выполните команду для создания суперпользователя:
```
python manage.py createsuperuser
```
Следуйте инструкциям в консоли для ввода имени пользователя, email и пароля.

Загрузка данных элементов иерархии из CSV-файлов¶

После выполнения команды initializeproject необходимо выполнить следующие шаги для загрузки данных элементов иерархии:

Убедитесь, что CSV-файлы находятся в правильной директории:
```
test_basics/
  data/
    hierarchy/
      dpu.csv
      brand.csv
      ...
```
Запустите команду для импорта данных:
```
python src/manage.py import_hierarchy_items_dir data/hierarchy
```

Команда: - Ищет CSV-файлы в указанной директории - Имена файлов должны соответствовать ключам уровней иерархии (например, dpu.csv, brand.csv) - Поддерживаются форматы CSV и XLSX - Импортирует данные "сверху вниз" для соблюдения целостности иерархии

Проверьте логи выполнения команды:
Успешный импорт: "Импорт иерархии из директории data/hierarchy закончен"
Если директория не найдена: "Директория data/hierarchy не найдена ни в одном из установленных приложений"
Если директория пуста: "Директория пуста, нечего импортировать"
Если нет подходящих файлов: "Нечего импортировать. В директории не обнаружены файлы..."
Структура CSV-файлов должна содержать обязательные колонки:
shortname - уникальный идентификатор элемента
description - описание элемента
Колонки для связей с родительскими уровнями (если есть)

Пример содержимого CSV-файла:

shortname,description,parent_level
DPU1,Торговая точка 1,REGION1
DPU2,Торговая точка 2,REGION1

Советы и best practices¶

Структура YAML-файлов должна строго соответствовать структуре фикстур моделей (см. Базовые понятия).
Для каждого уровня иерархии — отдельный CSV-файл в data/hierarchy/.
Для фактов — отдельные CSV-файлы (если поддерживается импорт).
Документируйте структуру файлов для команды.
Используйте реальные примеры из приложения test_basics как шаблон.

Такой подход позволяет быстро развернуть тестовую или отладочную среду, а также гарантировать, что тесты и ручная проверка работают на одних и тех же данных.

Генерация тестовых данных для иерархий¶

Для быстрого создания больших объемов тестовых данных элементов иерархии используется команда generate_fake_hierarchy_items. Эта команда особенно полезна при:

Тестировании производительности с большими объемами данных
Создании тестовых сред с реалистичными данными
Отладке функциональности, требующей множества элементов иерархии

Синтаксис команды¶

python manage.py generate_fake_hierarchy_items <level_key> <count> [options]

Параметры: - level_key — ключ уровня иерархии (например, dpu, brand, sales_point) - count — количество элементов для создания

Основные опции: - --csv-only, --dry-run — создать только CSV файл без импорта в базу данных - --keep-csv — сохранить CSV файл после импорта - --shortname-method — метод faker для генерации shortname (по умолчанию: ean) - --description-method — метод faker для генерации description (по умолчанию: sentence) - --shortname-args — аргументы для метода shortname в JSON формате - --description-args — аргументы для метода description в JSON формате - --seed — seed для воспроизводимости результатов - --output-dir — директория для сохранения CSV (по умолчанию: temp)

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

Создание 1000 элементов dpu с импортом:

python manage.py generate_fake_hierarchy_items dpu 1000

Создание только CSV файла без импорта:

python manage.py generate_fake_hierarchy_items brand 500 --csv-only

Создание с кастомными методами faker:

python manage.py generate_fake_hierarchy_items sales_point 100 \
  --shortname-method company \
  --description-method empty \
  --keep-csv

Создание с аргументами для методов:

python manage.py generate_fake_hierarchy_items product_plan_level 200 \
  --description-method sentence \
  --description-args '{"nb_words": 3}' \
  --seed 42

Особенности работы¶

Автоматические связи: система автоматически создает связи с родительскими уровнями на основе существующих элементов
Уникальность: shortname всегда уникальный, система обрабатывает коллизии
Гибкость: поддержка любых методов faker с передачей аргументов
Валидация: проверка существования методов faker и уровней иерархии
Прогресс: отображение прогресса генерации для больших объемов данных

Файлы команды¶

Основная логика: src/planiqum/core/hierarchy/libs/generate_fake_hierarchy_items.py
Management command: src/planiqum/core/hierarchy/management/commands/generate_fake_hierarchy_items.py

Интеграция с процессом разворачивания¶

Команда может использоваться как дополнение к стандартному процессу разворачивания:

Запустите initializeproject для базовой структуры
Используйте generate_fake_hierarchy_items для создания дополнительных тестовых данных
При необходимости создавайте CSV файлы для последующего импорта через import_hierarchy_items_dir

Генерация тестовых данных для параметров¶

Команда `generate_fake_parameter_data`¶

Команда для создания тестовых данных в таблицах фактов параметров. Генерирует случайные значения для измерений (из иерархий) и мер (по типам данных) с использованием векторизованных операций для высокой производительности.

Синтаксис¶

python manage.py generate_fake_parameter_data <parameter_key> <count> [options]

Параметры¶

parameter_key - ключ параметра для генерации данных
count - количество записей для генерации

Опции¶

--measures MEASURES - список ключей мер для заполнения (по умолчанию: все невычисляемые меры)
--measure-ranges JSON - JSON с диапазонами для мер: {"m_qty": {"min": 0, "max": 1000}}
--seed SEED - seed для воспроизводимости генерации
--output-dir DIR - директория для сохранения CSV файла (по умолчанию: temp)
--keep-csv - сохранить CSV файл после импорта
--csv-only, --dry-run - создать только CSV файл без импорта в базу данных
--flush - очистить таблицу фактов перед импортом
--batch-size SIZE - размер батча для генерации данных (по умолчанию: 500000)
--no-log - не создавать записи в журнале импорта (рекомендуется для больших объемов данных, чтобы избежать накопления больших журналов)

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

Базовые примеры:

# Создать 100 записей для параметра demand_plan
python manage.py generate_fake_parameter_data demand_plan 100

# Создать только CSV файл с настройками диапазонов
python manage.py generate_fake_parameter_data demand_plan 50 --csv-only --seed 42 \
  --measure-ranges '{"m_qty": {"min": 100, "max": 500}}'

# Импортировать с очисткой таблицы и сохранением CSV
python manage.py generate_fake_parameter_data demand_plan 1000 --flush --keep-csv

# Заполнить только определенные меры
python manage.py generate_fake_parameter_data demand_plan 200 --measures m_qty m_value

Примеры для больших объемов данных:

# Создать 2 миллиона записей с отключенным журналом импорта
python manage.py generate_fake_parameter_data demand_plan 2000000 --no-log

# Создать 5 миллионов записей с кастомным размером батча
python manage.py generate_fake_parameter_data demand_plan 5000000 --batch-size 1000000 --no-log

# Создать данные с настройкой диапазонов для мер
python manage.py generate_fake_parameter_data demand_plan 1000000 \
  --measure-ranges '{"m_qty": {"min": 50, "max": 2000}, "m_value": {"min": 1000, "max": 50000}}' \
  --no-log

Особенности генерации¶

Измерения: - Календарные (is_calendar=True): случайные даты из HorizonItem (активные элементы) - Обычные: случайные коды (shortname) из Item (активные элементы иерархии) - Используются только активные элементы иерархии (is_available=True) - При отсутствии активных элементов выдается ошибка

Меры по типам: - Float (0): числа с плавающей точкой (по умолчанию 0.0-1000.0) - Integer (1): целые числа (по умолчанию 1-100) - Boolean (2): логические значения (True/False) - String (3): текстовые строки (предложения из 3 слов) - Item (4): ID элементов из связанного уровня иерархии - DateTime (5): даты и время (за последний год)

Вычисляемые меры (is_calculated=True) автоматически пропускаются.

Производительность и батчевая обработка¶

Векторизованная генерация: - Использует NumPy и Pandas для быстрой генерации больших объемов данных - Генерация происходит батчами для управления памятью - Размер батча по умолчанию: 500,000 записей

Батчевая обработка: - При --keep-csv: генерирует все данные в один файл, затем импортирует - Без --keep-csv: обрабатывает батчами (генерирует → импортирует → удаляет временный файл) - Показывает прогресс и время выполнения для каждого батча - Останавливается при ошибке импорта батча

Пример вывода:

Батчевая обработка: 4 батчей по 500000 записей
Обработка батча 1/4: 500000 записей
  Измерение dpu: 1000160 элементов
  Измерение horizon__week: 1090 элементов
  Измерение activity: 2 элементов
  Батч 1: импортировано 500000, ошибок 0, время батча: 24.91с, общее время: 24.91с
Прогресс: 500000/2000000 (25.0%)
...
Итого импортировано: 2000000 записей, ошибок: 0
Общее время процесса: 115.22с

Валидация и обработка ошибок¶

Проверка существования параметра с выводом списка доступных
Проверка существования мер с выводом списка доступных
Проверка наличия активных элементов в уровнях иерархии
Обработка ошибок импорта с сохранением CSV для анализа
Валидация флагов: --csv-only автоматически подразумевает --keep-csv

Файлы команды¶

Основная логика: src/planiqum/core/parameters/libs/generate_fake_parameter_data.py
Management command: src/planiqum/core/parameters/management/commands/generate_fake_parameter_data.py

Интеграция с процессом разворачивания¶

Команда может использоваться как дополнение к стандартному процессу разворачивания:

Запустите initializeproject для базовой структуры
Используйте generate_fake_hierarchy_items для создания тестовых данных иерархий
Используйте generate_fake_parameter_data для создания тестовых данных параметров
При необходимости создавайте CSV файлы для последующего импорта

Типичный workflow для создания тестовой среды:

# 1. Инициализация базовой структуры
python manage.py initializeproject 2024-01-01 2024-12-31

# 2. Создание тестовых данных иерархий
python manage.py generate_fake_hierarchy_items dpu 10000
python manage.py generate_fake_hierarchy_items brand 1000

# 3. Создание тестовых данных параметров
python manage.py generate_fake_parameter_data demand_plan 1000000 --no-log
python manage.py generate_fake_parameter_data sales_plan 500000 --no-log

См. также¶

Генерация календаря (generatecalendar, generate_calendar)

Использование initializeproject и seed-данных для тестирования и отладки¶

Назначение¶

Как это работает¶

Организация seed-данных и фикстур¶

1. Мета-информация (fixtures)¶

2. Данные для наполнения элементов иерархии¶

3. Данные для заполнения таблицы фактов¶

4. Пример структуры приложения¶

5. Как использовать¶

Загрузка данных элементов иерархии из CSV-файлов¶

Советы и best practices¶

Генерация тестовых данных для иерархий¶

Синтаксис команды¶

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

Особенности работы¶

Файлы команды¶

Интеграция с процессом разворачивания¶

Генерация тестовых данных для параметров¶

Команда generate_fake_parameter_data¶

Синтаксис¶

Параметры¶

Опции¶

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

Особенности генерации¶

Производительность и батчевая обработка¶

Валидация и обработка ошибок¶

Рекомендации по оптимальному использованию¶

Файлы команды¶

Интеграция с процессом разворачивания¶

См. также¶

Команда `generate_fake_parameter_data`¶