Abrest Імпорт — Довідник конфігурацій

Кожне завдання імпорту керується YAML-конфігурацією, що зберігається у S_BLOCKYAML.BLOCK_CONTENT. Імпортер знаходить рядок заголовків (перший рядок, що містить усі зовнішні назви стовпців, згадані в fields), а потім обробляє кожен наступний рядок у такому порядку: виявлення ієрархії → співставлення стовпців → обчислення значень → розв'язання групового шляху → пошук/створення товару → присвоєння тегів → опціональний переклад → вставка в БД.

Повний приклад

Прайс-лист XLSX із триrівневою ієрархією (виявлення за стилем), перевизначенням категорій, присвоєнням тегів і перекладом з української на англійську.

---
file_type: xlsx
sheet: 0

global:
    root_group_id: 0
    tovar_type: 1
    translation:
        from: uk
        to: en
        translate_items: true
        translate_groups: true
        translate_tags: true

fields:
    GROUP_ID:
        resolve: group_path
        levels:
            - name: category
              tag: CATEGORY
              detect:
                  column: 0
                  method: formatting
                  bold: true
                  font_size: 14
            - name: subcategory
              detect:
                  column: 0
                  method: formatting
                  bg_color: 92D050
                  bold: true
            - name: product_type
              detect:
                  column: 0
                  method: formatting
                  bg_color: D9FECC
        categories:
            depth: 2
            default: tag
            default_tag_name: ProductType
            mapping:
                - source: "House brand"
                  action: map
                  group_id: 42
                - source: "Legacy products"
                  action: exclude
                - source: "Mixed fertilisers"
                  action: inherit
    TOVAR_ID:
        resolve: find_or_create
        name_source: "Назва товару"
        ean_source: "Штрихкод"
        article_source: "Артикул"
    PRICE:
        source: "Ціна"
        type: number
    IMPORT_DATE:
        value: today
        tag: IMPORT_DATE
...

Ключі верхнього рівня

Ключ	Обов'язковий	Призначення
`file_type`	так	`csv`, `xlsx`, `xls`, `xml`
`sheet`	ні	Індекс листа для XLSX/XLS (за замовчуванням `0`)
`global`	ні	Налаштування рівня документа (коренева група, тип товару за замовчуванням, переклад)
`fields`	так	Визначення полів — по одному запису на кожне поле БД або розв'язане значення

`global`

Необов'язкова секція для налаштувань, що застосовуються до всього імпорту.

Ключ	За замовчуванням	Опис
`root_group_id`	`0`	ID батьківської групи, що є початковою точкою для пошуку і співставлення груп
`tovar_type`	`1`	Тип товару, що записується в `R_TOVAR.TTYPE` при створенні (`1` = товар, `2` = послуга/робота)
`translation`	—	Налаштування перекладу через LLM (див. нижче)

`global.translation`

global:
    translation:
        from: uk
        to: en
        translate_items: true
        translate_groups: true
        translate_tags: true

Ключ	За замовчуванням	Опис
`from`	—	Мова джерела (BCP 47: `uk`, `en`, `de`, `pl`, …)
`to`	—	Цільова мова
`translate_items`	`true`	Перекласти назви товарів після розв'язання `find_or_create`
`translate_groups`	`true`	Перекласти назви груп після розв'язання `group_path`
`translate_tags`	`true`	Перекласти значення тегів після їх присвоєння

Переклад активний тільки якщо задані і from, і to, і сервіс перекладу LLM увімкнений в abrest.ini. Кожна сутність перекладається не більше одного разу (ключ (entity_type, entity_id, lang) у CR_TRANSLATIONS).

`fields`

Основна частина конфігурації. Кожен ключ — це внутрішня назва поля БД (у верхньому регістрі, за конвенцією Firebird). Значення — об'єкт, що описує, звідки беруться дані.

Існує чотири різновиди полів, що визначаються підключами.

Різновид 1 — `source` (відображення стовпця)

Відображає стовпець файлу у поле БД.

PRICE:
    source: "Ціна"
    type: number

Ключ	Обов'язковий	Опис
`source`	так	Точна назва заголовка стовпця у файлі (з урахуванням регістру)
`type`	ні	`number` або `integer` — видаляє нечислові символи та перетворює; при помилці повертає `0`
`tag`	ні	Після розв'язання `TOVAR_ID` присвоює значення цього поля як тег під вказаною назвою тега

Різновид 2 — `value` (константа або обчислення)

Дає фіксоване або обчислене значення без стовпця-джерела.

IMPORT_DATE:
    value: today
    tag: IMPORT_DATE

STATUS:
    value: 1

Ключ	Обов'язковий	Опис
`value`	так	Буквальна константа або спеціальне слово `today` (генерує сьогоднішню дату у форматі `рррр-мм-дд`)
`tag`	ні	Те саме, що для полів типу `source`

Різновид 3 — `resolve: group_path`

Шукає (або створює) ланцюжок груп (категорій) товару від батьківської до дочірньої і запам'ятовує ID кінцевої групи. Тут також налаштовується виявлення групових рядків у файлі.

GROUP_ID:
    resolve: group_path
    levels:
        - name: category
          tag: CATEGORY
          detect:
              column: 0
              method: single_value
        - name: subcategory
          detect:
              method: merged_cells
    categories:
        depth: 1
        default: tag
        default_tag_name: Subcategory
        mapping:
            - source: "House brand"
              action: map
              group_id: 42

`levels`

Шукає категорії товару по рівнях групування, так звані "плюсики" ліворуч від номерів рядків в Екселі. Правила мають бути впорядковані від більшого рівня (що включає більше рядків) до меншого. Кожен рівень описується такими параметрами:

Ключ	Обов'язковий	Опис
`name`	так	Внутрішній ключ, що зберігає поточну назву групи. При збігу вищого рівня всі нижчі скидаються.
`tag`	ні	Якщо задано, всім товарам цієї групи буде присвоєно відповідний тег з назвою групи (на додачу до того що вони будуть включені в цю групу)
`detect`	так	Як розпізнавати групові рядки для цього рівня (детально нижче)

`detect`

Ключ	За замовчуванням	Опис
`column`	`0`	Індекс стовпця для структурних та атрибутних перевірок
`method`	`single_value`	Метод виявлення (таблиця нижче)
`outline_level`	—	Рівень структурування рядка (тільки XLSX), для методу `outline_level`
`bg_color`	—	Колір фону комірки `RRGGBB` або `AARRGGBB` (байт прозорості ігнорується)
`font_color`	—	Той самий формат
`font_size`	—	Пункти, допуск ±0.01
`font_name`	—	Без урахування регістру
`bold`	—	`true`/`yes`/`1` або `false`/`no`/`0`
`italic`	—	Ті самі значення

Методи виявлення

Метод	Умова
`single_value`	Рядок має ≤ 1 непорожню комірку. Атрибути комірки (якщо задані) застосовуються через «І».
`merged_cells`	Комірка у `column` займає більше одного стовпця (XLSX/XLS). Для CSV/XML поводиться як `single_value`.
`formatting`	Без структурної вимоги — збіг тільки за атрибутами комірки у `column`. Використовується, коли категорійні рядки заповнені так само, як і рядки даних, але відрізняються стилем.
`outline_level`	Рівень структурування рядка дорівнює `outline_level` І рядок є `single_value` або `merged_cells`.

`categories`

Необов'язкові перевизначення поведінки для категорій. Використовуйте, коли структура категорій постачальника не збігається з внутрішньою R_GROUPS.

categories:
    depth: 2
    default: tag
    default_tag_name: Subcategory
    default_group_id: 0
    mapping:
        - source: "House brand"
          action: map
          group_id: 42
        - source: "Legacy products"
          action: exclude

Ключ	Опис
`depth`	Рівні `1..depth` без явного відображення отримують `create`. Глибші рівні без явного відображення отримують `default`. `0` = усі рівні отримують `create`, якщо не перевизначено.
`default`	Дія для глибоких рівнів без явного відображення. Допустимі: `create`, `map`, `tag`, `inherit`, `exclude`.
`default_tag_name`	Використовується при `default: tag`, якщо у записі `mapping` не задано `tag_name`.
`default_group_id`	Використовується при `default: map`, якщо у записі `mapping` не задано `group_id`.
`mapping`	Перевизначення за точним (без урахування регістру) збігом назви категорії.

Поля елемента mapping:

Ключ	Обов'язковий для	Опис
`source`	всіх	Назва категорії у файлі.
`action`	всіх	`create`, `map`, `tag`, `inherit` або `exclude`.
`group_id`	`map`	Наявний `R_GROUPS.ID`, що використовується замість створення нової групи.
`tag_name`	`tag`	Назва тега (автоматично створюється в `TAG_NAMES`), під якою записується значення сегмента.

Дії

Дія	Вплив
`create`	Знайти або створити сегмент під поточним батьком; він стає батьком для наступного сегмента.
`map`	Використати заданий `group_id` як батька. `group_id = 0` припиняє розв'язання; товар не розміщується.
`tag`	Сегмент пропускається в шляху; після розв'язання товару значення присвоюється як тег.
`inherit`	Проходження зупиняється; товар потрапляє до останнього розв'язаного батька.
`exclude`	Весь рядок відкидається — без вставки в БД, без тегів, без перекладу. Заноситься у список пропущених.

Різновид 4 — `resolve: find_or_create`

Пошук товару з урахуванням постачальника. Записує розв'язаний R_TOVAR.ID у поле.

TOVAR_ID:
    resolve: find_or_create
    name_source: "Назва товару"
    ean_source: "Штрихкод"
    article_source: "Артикул"

Ключ	Обов'язковий	Опис
`name_source`	так	Заголовок стовпця файлу з назвою товару
`ean_source`	ні	Заголовок стовпця для штрихкоду EAN13
`article_source`	ні	Заголовок стовпця для артикула постачальника

Порядок пошуку: 1. IMPORT_GETITEM — пошук за EAN13 + артикулом + назвою у CR_TOVAR_ARTICLES зі скопом за EXT_CONTRAGENT із заголовка запиту. 2. Якщо переклад/вбудовування увімкнені й крок 1 не знайшов: семантичний пошук за векторним вбудовуванням із підтвердженням LLM. У разі збігу перевикористовується існуючий товар, доповнюється CR_TOVAR_ARTICLES. 3. Інакше: IMPORT_SETITEM створює новий R_TOVAR всередині групи, розв'язаної попереднім полем GROUP_ID (якщо GROUP_ID = 0, створюється товар лише за назвою без CR_TOVAR_ARTICLES).

Тип товару при створенні береться з global.tovar_type (за замовчуванням 1).

Порядок виконання

Знайти рядок заголовків — перший рядок, що містить усі стовпці, перераховані в fields. Все що до цього рядка - ігнорується. Далі для всіх рядків до кінця листа виконуються наступні операції:

Якщо рядок відповідає будь-якому levels[*].detect, оновити інформацію про групу і продовжити; рядок не імпортується.
Співставити стовпці з файлу із полями у fields; додати поточні значення категорії.
Застосувати перетворення type: number і підстановки value:.
Проаналізувати поля типу group_path. Якщо дія categories є exclude — рядок відкидається.
Проаналізувати поля типу find_or_create (тут відбувається створення товару — до вставки в БД).
Застосувати присвоєння тегів — tag: для полів і рівнів, плюс теги з категорій.
Виконати global.translation для товару, груп і значень тегів.
Сформувати дані для вставки та вставити у таблицю тіла документа.

Abrest Імпорт — Довідник конфігурацій

Повний приклад

Ключі верхнього рівня

global

global.translation

fields

Різновид 1 — source (відображення стовпця)

Різновид 2 — value (константа або обчислення)

Різновид 3 — resolve: group_path

levels

detect