Руководство по импорту данных из 1С в PIM

Назначение

Программа import_from_1c.py предназначена для первоначального импорта номенклатуры из системы 1С в таблицы PIM (pim_products, pim_pirotehnika).

Это первый шаг перед началом работы с PIM системой.

Последовательность работы

1. 1C → PIM               (import_from_1c.py - ЭТА ПРОГРАММА)
   ↓
2. Обогащение PIM         (прайсы, сайты)
   ↓
3. PIM → 1C               (экспорт обратно)

Способы импорта

Способ 1: Через REST API 1С (рекомендуется)

python import_from_1c.py \
  --api-url http://1c-server.local/api/nomenclature \
  --api-key YOUR_API_KEY

Требования к API 1С:
- Метод: GET
- Формат ответа: JSON array
- Аутентификация: Bearer token (опционально)

Пример ответа API:

[
  {
    "code_1c": "НМ-00001234",
    "article": "ART-12345",
    "name": "Название товара",
    "brand": "Бренд",
    "base_price": 1250.50,
    "group_1c": "Группа товаров",
    "unit": "шт",
    "is_active": true
  }
]

Способ 2: Через файл экспорта JSON

Экспортируйте данные из 1С в JSON файл

В 1С можно создать обработку или использовать стандартные средства экспорта.

Запустите импорт из файла:

python import_from_1c.py --file /data/1c_export.json

Пример JSON файла находится в examples/1c_export_example.json

Способ 3: Dry Run (проверка без записи)

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

python import_from_1c.py --file /data/1c_export.json --dry-run

Формат данных

Обязательные поля

Поле	Тип	Описание
`code_1c`	string	Код номенклатуры в 1С (например: "НМ-00001234")
`article`	string	Артикул товара (уникальный)
`name`	string	Название товара

Опциональные поля

Поле	Тип	Описание	Таблица назначения
`brand`	string	Бренд	`pim_products`
`base_price`	number	Базовая цена	`pim_products`
`group_1c`	string	Группа товаров в 1С	-
`unit`	string	Единица измерения	-
`vendor_code`	string	Код производителя	-
`is_active`	boolean	Активен ли товар	-
`description`	string	Описание	`pim_products`

Дополнительные поля для пиротехники

Если is_pyrotechnics: true, создается запись в pim_pirotehnika:

Поле	Тип	Описание
`weight`	string	Вес (например: "2.5 кг")
`caliber`	string	Калибр (например: "30мм")
`height`	string	Высота эффекта (например: "до 50м")
`shots_count`	integer	Количество выстрелов/залпов
`duration`	string	Время работы (например: "90 сек")

Процесс импорта

Программа выполняет следующие шаги:

ШАГ 1: Получение данных

Из API 1С (HTTP GET запрос)
Или из JSON файла

ШАГ 2: Валидация

Проверка обязательных полей
Проверка формата данных
Проверка диапазонов значений

ШАГ 3: Импорт в базу данных

Создание записи в pim_import_log (трейсинг)
Для каждого товара:
Проверка существования по article
Если существует → обновление code_1c, name, base_price
Если не существует → создание нового товара
Если is_pyrotechnics=true → создание записи в pim_pirotehnika
Обновление статуса в pim_import_log

ШАГ 4: Отчет

Выводится таблица с результатами:
- Total Records - всего обработано
- Created - создано новых товаров
- Updated - обновлено существующих
- Skipped - пропущено (не прошли валидацию)
- Errors - ошибки при импорте

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

Пример 1: Первоначальная загрузка из файла

# Сначала проверяем данные
python import_from_1c.py --file examples/1c_export_example.json --dry-run

# Если все ок - импортируем
python import_from_1c.py --file examples/1c_export_example.json

Вывод:

═══════════════════════════════════════════
  1C → PIM Import Tool
═══════════════════════════════════════════

Loading data from file: examples/1c_export_example.json
✓ Loaded 8 items from file

Validating data...
✓ Validation complete: 8 valid, 0 invalid

Importing to PIM database...
✓ Import complete!

┏━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric        ┃ Count ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Total Records │     8 │
│ ✓ Created     │     8 │
│ ✓ Updated     │     0 │
│ ⊘ Skipped     │     0 │
│ ✗ Errors      │     0 │
└───────────────┴───────┘

✓ Import completed successfully!

Пример 2: Синхронизация через API

python import_from_1c.py \
  --api-url http://192.168.1.100/pim/api/nomenclature \
  --api-key "sk_prod_abc123xyz"

Пример 3: Обновление существующих данных

При повторном запуске программа обновит существующие товары (по article):

# Первый запуск - создаст 8 товаров
python import_from_1c.py --file data.json
# Created: 8

# Второй запуск с теми же данными - обновит 8 товаров
python import_from_1c.py --file data.json
# Updated: 8, Created: 0

Логирование

Файл логов

Все операции записываются в:

/var/log/pim/import_1c.log

Формат:

2025-12-23 10:15:32 - __main__ - INFO - Created import log #42
2025-12-23 10:15:35 - __main__ - INFO - Created new product: ART-12345
2025-12-23 10:15:36 - __main__ - INFO - Updated existing product: ART-12346

База данных

В таблице pim_import_log создается запись для каждого импорта:

SELECT
    id,
    source,
    import_type,
    status,
    records_processed,
    records_imported,
    errors_count,
    started_at,
    completed_at
FROM pt7k98pv0fwi1el.pim_import_log
ORDER BY started_at DESC
LIMIT 10;

Проверка результатов

После импорта проверьте:

-- Количество товаров
SELECT COUNT(*) FROM pt7k98pv0fwi1el.pim_products;

-- Последние добавленные
SELECT article, name, brand, base_price, created_at
FROM pt7k98pv0fwi1el.pim_products
ORDER BY created_at DESC
LIMIT 10;

-- Товары с кодами 1С
SELECT COUNT(*) FROM pt7k98pv0fwi1el.pim_products
WHERE code_1c IS NOT NULL;

-- Характеристики пиротехники
SELECT p.article, p.name, pir.caliber, pir.shots_count, pir.duration
FROM pt7k98pv0fwi1el.pim_products p
JOIN pt7k98pv0fwi1el.pim_pirotehnika pir ON p.id = pir.product_id
LIMIT 10;

Через CLI:

# Список товаров
python -m pim products list --limit 10

# Информация о товаре
python -m pim products get ART-12345

Устранение проблем

Проблема: "Missing required field: code_1c"

Причина: В данных из 1С отсутствует поле code_1c

Решение: Убедитесь что экспорт из 1С включает это поле, или измените логику валидации

Проблема: "Invalid price format"

Причина: Цена содержит нечисловое значение

Решение: Проверьте формат данных, цена должна быть числом: 1250.50

Проблема: "File not found"

Причина: Неверный путь к файлу

Решение: Используйте абсолютный путь: /data/export.json

Проблема: "HTTP error: 401"

Причина: Неверный API ключ

Решение: Проверьте API ключ в параметре --api-key

Автоматизация

Создайте cron задачу для регулярной синхронизации:

# Редактируем crontab
crontab -e

# Добавляем задачу (каждый день в 2:00)
0 2 * * * cd /opt/pirotehnika/app/pim && python import_from_1c.py --api-url http://1c-server/api/nomenclature --api-key YOUR_KEY >> /var/log/pim/cron.log 2>&1

Или через systemd timer:

Файл: /etc/systemd/system/pim-import-1c.service

[Unit]
Description=Import nomenclature from 1C to PIM
After=network.target postgresql.service

[Service]
Type=oneshot
User=pim
WorkingDirectory=/opt/pirotehnika/app/pim
ExecStart=/usr/bin/python3 import_from_1c.py --api-url http://1c-server/api/nomenclature
StandardOutput=journal
StandardError=journal

Файл: /etc/systemd/system/pim-import-1c.timer

[Unit]
Description=Daily import from 1C to PIM

[Timer]
OnCalendar=daily
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target

Активация:

systemctl enable pim-import-1c.timer
systemctl start pim-import-1c.timer
systemctl status pim-import-1c.timer

Следующие шаги

После успешного импорта данных из 1С:

Обогащение данных:
```bash
# Импорт прайс-листов поставщиков
python -m pim update --source prices --price-file supplier.xlsx --brand "BrandName"

# Обогащение с сайтов производителей
python -m pim update --source sites
```

Проверка и расчет цен:
bash # Создать правила скидок # Рассчитать cost_price для всех товаров
Экспорт обратно в 1С:
bash # Когда данные обогащены - отправить обратно в 1С # (см. ALGORITHM_1C_SYNC.md)

Поддержка

Логи: /var/log/pim/import_1c.log
Документация API: http://localhost:8000/docs
CLI help: python import_from_1c.py --help