# [`\Shef\InSync\Sync`] Импорт

> Импорт идёт в два шага через таблицу импорта \Shef\InSync\Sync\Model\SyncTable
(shef_insync_model):

Импорт идёт в два шага через таблицу импорта `\Shef\InSync\Sync\Model\SyncTable`
(`shef_insync_model`):

1. **процесс** (`\Shef\InSync\Sync\IProcess`) забирает данные — из файла,
   из CRM, из API — и складывает строки в таблицу импорта;
2. **агент разбора** (`\Shef\InSync\Sync\FromFile\AAgent`) берёт строки из
   таблицы пачками и разносит по сущностям. Сколько брать и что делать с
   ошибочными строками, решает стратегия
   (`\Shef\InSync\Sync\FromFile\Strategy\IStrategy`).

> Пример смотреть в модуле **[shef.demosync](https://marketplace.1c-bitrix.ru/solutions/shef.demosync/)**

## Процессы

| класс | что это | примечание |
|---|---|---|
| FromFile\AFileProcess | абстракция импорта файла | каталоги, движение файла, строки в таблицу |
| FromFile\ACsvProcess | импорт CSV | разделитель, заголовок, карта колонок |
| FromFile\AXmlProcess | импорт XML | потоково, по тегу элемента, см. [Парсинг XML](/modules/insync/xml) |
| Crm\ACrmProcess | строки из сущностей CRM | проходит по типу сущности CRM |

## Агент разбора и стратегии

| класс | что делает |
|---|---|
| FromFile\AAgent | берёт строки своего импорта, помечает «в работе», зовёт `processRow()`, успешные удаляет |
| FromFile\Strategy\Simple | берёт все строки; ошибочные остаются и будут взяты снова |
| FromFile\Strategy\MarkFail | ошибочные помечает маркером `.error` в коде импорта; берутся снова |
| FromFile\Strategy\HideFail | ошибочные помечает и больше не берёт |

Статусы строк — `\Shef\InSync\Sync\EStatus`: `U` — не определён, `N` — новая,
`P` — в работе, `S` — успешно, `F` — ошибка.

Очистить таблицу импорта из кода:

```php
\Bitrix\Main\Loader::includeModule('shef.insync');
$collection = \Shef\InSync\Sync\Model\SyncTable::createCollection();
$collection->clear('ShefDemosyncFromFileCsv');   // строки одного импорта
$statistic = $collection->getStatistic();
```

## Каталоги для файлов

Файлы кладутся в каталог `\Shef\InSync\Sync\FromFile\AFileProcess::getImportFolder()`,
по умолчанию **{каталог импорта}/{код импорта}/**. Каталог импорта — вне корня
сайта, `\Shef\InSync\Main\Constants::getImportDir()`: на BitrixVM это
`/home/bitrix/sh_import`, свой задаётся в `/bitrix/.settings_extra.php`, см.
[security.md](/modules/insync/security). Имя файла начинается с префикса — например,
`cart-xxx.xml`: `getExistFiles('cart-', 'xml')` берёт файлы, имя которых
**начинается** с префикса, с этим расширением (несколько — через `|`:
`'xml|zip'`), старые первыми. Файлы в обработке (`process_<код>_…`) и файлы
без расширения не берутся.

> Картинки стоит так же выкладывать в эту папку, например в подпапку **img**.

После обработки файл переезжает в **{каталог импорта}/copy/{код импорта}/**,
при проблеме — в **{каталог импорта}/problem/{код импорта}/**. Имя архивного
файла — `done_<код>_<дата>_<случайный хвост>.<расш>`.

До 2.0.0 каталог был `/upload/import`, под корнем сайта. Внешние обмены,
которые кладут туда файлы, после обновления перенастраиваются на новый
каталог — порядок в [security.md](/modules/insync/security).

> Сколько дней хранить файлы в архиве, задаётся в настройках модуля, по
> умолчанию 3 дня. Процесс импорта может переопределить срок
(`getMaxDayOffDoneFile()` в своём наследнике `AFileProcess`).

Загрузить файл руками — страница импорта из файла, см. [Компоненты](/modules/insync/components).

## Модели
В модуле преследуется цель работать со сущностями Битрикс только через ORM.

По этой причине созданы необходимые для работы модели и аннотации к ним.
Все остальные модели/аннотации в Битрикс уже присутствуют.

> Аннотацию для модели собирать через [механизм Битрикс](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=11733):
> ```shell
> php bitrix.php orm:annotate -m shef.insync <путь к модулю>/meta/orm.php
> ```
>
> Или использовать `shef-cli`, если он доступен:
> ```shell
> shef-cli module:annotate shef.insync
> ```
>
> Аннотации лежат в одном `meta/orm.php` в корне модуля — как у модулей ядра.

### [`\Shef\InSync\Sync\Model\SyncTable`] Таблица синхронизации
Работает через модель `EO_`, поддерживает интерфейс `\Shef\InSync\Sync\IElement`. 

Интерфейс и магические методы `EO_` связаны через фасад.

### [`\Shef\InSync\Sync\Model\Store`] Склады
Работает через модель `EO_`, для работы со складами (Название, адрес и тп)

### [`\Shef\InSync\Sync\Model\IBlock\*`] Инфоблоки
Добавили в `*Table` поддержку IblockId.

Работает через модель `EO_`, для работы с сущностями инфоблоков, поддерживает интерфейсы `Model\IBlock\IIBlockId`, `Model\IBlock\IFixGetList`.

* разделы `Model\IBlock\Section`
* элементы `Model\IBlock\Element`
* перечисления для свойства типа список `Model\IBlock\PropertyEnumeration`

Свойства элемента по коду — трейт `\Shef\InSync\Sync\Model\IBlock\Element\PropertyTrait`
для драйвера или процесса импорта: строка, число, флажок, файл, список
(`getPropertyEnum()` и `getEnum()` — найти значение списка по XML_ID или по
значению без учёта регистра, нет — создать). Описание свойства читается один
раз на объект; класс задаёт `static::$dataClass` — свой `*Table` инфоблока.

> Для использования аннотаций на конкретный инфоблок нужно:
>
> * задать код ORM в инфоблоке
> * унаследоваться от `\Shef\InSync\Sync\Model\IBlock\*\*Table`
> * переопределить в нем свои классы для `EO_`
> * построить аннотацию для своего класса `*Table`


### [`\Shef\InSync\Sync\Model\Catalog\ProductTable`] Каталог
Работает через модель `EO_`. Наследник `\Bitrix\Catalog\ProductTable`.

Добавлена связь со ставкой НДС `SH_VAT` с `\Bitrix\Catalog\VatTable`.

## Драйверы
Надстройка над штатным API для чтения/записи данных.

### [`\Shef\InSync\Sync\Model\Catalog\Driver\*`] для Bitrix\Catalog

> При работе со складским учётом - нужно импортировать остатки через документы складского учета

Модуль битрикса `catalog` использует _модели_ и апи _v2_. Тк. на текущий момент для _v2_ написано в коде что оно не стабильно, используем **модели**.

Интерфейс `Driver\ICatalogModel` указывает что используется модель каталога.

|            Класс | Интерфейс              | Описание                                                                                                    |
|-----------------:|:-----------------------|:------------------------------------------------------------------------------------------------------------|
| `Driver\Product` | `Driver\ICatalogModel` | Работа с данными по товару  -> вес, габариты, единица измерения, <br/>цена закупки, НДС, общий остаток и тп |
|   `Driver\Price` | `Driver\ICatalogModel` | Работа с ценами на товары                                                                                   |
|  `Driver\Amount` |                        | Остатки по складам                                                                                          |


---

[← Агенты](/modules/insync/agents) | [↑ Содержание](/modules/insync) | [API →](/modules/insync/api)

::note
Источник: [insync/docs/2_import.md](https://github.com/bx-shef/insync/blob/main/docs/2_import.md) — правки туда, сайт пересобирается сам.
::