# Импорт документов

← [Назад к разделу «Модули»](README.md)

Модуль `document_import` загружает CSV, XLSX, XLS и XML в документы выбранной
рубрики. Он заменяет старый универсальный импорт: данные сохраняются через
штатный `DocumentMutationService`, поэтому выполняются проверка alias, поля,
хуки сохранения, аудит и сброс связанного кеша.

## Быстрый запуск

1. Откройте **Модули → Импорт документов** и создайте профиль.
2. Выберите рубрику и формат файла. Для XML укажите повторяемый элемент, для
   Excel при необходимости задайте лист.
3. Нажмите запуск профиля и загрузите новый исходный файл.
4. Проверьте найденные колонки и первые строки.
5. Сопоставьте колонки источника с реквизитами документа и полями рубрики.
6. Для обновления существующих документов отметьте один или несколько ключей
   поиска.
7. Запустите импорт и дождитесь завершения всех порций.

Файл не хранится в профиле. Профиль запоминает формат, сопоставление, ключи и
режим выполнения, а при каждом запуске принимает новый источник.

## Форматы источника

| Формат | Настройка | Примечание |
| --- | --- | --- |
| CSV | разделитель или автоопределение | Первая строка должна содержать названия колонок. |
| XLSX | название или номер листа | Пустое значение выбирает первый лист. |
| XLS | название или номер листа | Читается встроенной библиотекой PHPExcel. |
| XML | имя повторяемого элемента | Дочерние элементы и атрибуты становятся колонками. |

Максимальный размер источника составляет 50 МБ. Загруженный файл проходит
общую `UploadPolicy` и хранится вне публичного каталога до завершения или
удаления запуска.

## Сопоставление

Каждое правило связывает одну колонку источника с одной целью. Одну цель нельзя
выбрать дважды. Доступны системные реквизиты документа и все актуальные поля
выбранной рубрики.

Для правила можно задать:

- преобразование: без изменений, обрезка пробелов, целое, десятичное число,
  дата, логическое значение, нижний или верхний регистр, JSON;
- значение по умолчанию для пустой колонки;
- обязательность значения;
- шаблон, в котором `{Название колонки}` подставляет данные текущей строки;
- участие в поиске существующего документа;
- точное совпадение или поиск по вхождению.

Для создания документа обязательно сопоставьте название. В качестве ключей
допустимы название, alias и поля рубрики. Несколько ключей объединяются
условием **И**: документ должен совпасть по каждому из них. Для стабильного
повторного импорта лучше использовать внешний ID, артикул или иной уникальный
реквизит, а не название.

## Режим запуска

| Опция | Поведение |
| --- | --- |
| Создавать новые | Создаёт документ, когда совпадение по ключам не найдено. |
| Обновлять найденные | Изменяет только сопоставленные реквизиты найденного документа. |
| Отключить отсутствующие | После успешного прохода выключает активные документы рубрики, которых не было в источнике. |
| Стоп при ошибке | Прерывает запуск на первой ошибочной строке. |

Отключение отсутствующих разрешено только при настроенном ключе. Оно начинается
после полного прохода без ошибок строк, поэтому повреждённый или неполный файл
не должен массово выключить документы.

Импорт выполняется порциями. Позиция хранится в БД, поэтому прерванный браузером
запуск можно продолжить из вкладки **Запуски**. В истории видны созданные,
обновлённые, пропущенные и ошибочные строки.

## Хуки

| Хук | Назначение |
| --- | --- |
| `document_import.source.prepared` | Источник разобран, известны профиль и запуск. |
| `document_import.row.normalized` | Позволяет изменить значения одной строки до сопоставления. |
| `document_import.document.payload` | Изменяет payload перед штатным сохранением документа. |
| `document_import.document.saved` | Документ успешно создан или обновлён. |
| `document_import.run.started` | Запуск настроен и начал обработку. |
| `document_import.run.completed` | Все строки и финализация обработаны. |
| `document_import.run.cancelled` | Пользователь остановил запуск. |

Общие хуки документов `content.document.saving` и
`content.document.saved` также выполняются, потому что модуль не обходит
нативный цикл сохранения.

## Удаление

Деинсталляция удаляет профили, историю, ошибки, временные источники и все
таблицы модуля. Созданные или обновлённые документы остаются в своих рубриках:
они являются контентом сайта, а не служебными данными импорта.