Правила: импорт данных (IMPORT)

Правила импорта (IMPORT)

1. Прежде чем работать с IMPORT, ассистент ОБЯЗАН определить элементы в следующем порядке:

   • модуль и пространство имён, владеющие потоком импорта
   • целевые классы, которые будут создаваться или обновляться
   • промежуточные (staging) свойства, используемые при импорте
   • действия импорта
   • формы импорта, если данные иерархичны

2. Ассистент ОБЯЗАН осознанно выбирать стиль импорта:

   • плоские файлы (CSV, XLS, DBF, TABLE) -> предпочесть IMPORT ... TO или FIELDS
   • вложенные JSON / XML, структуры родитель-потомок, пространства имён или сопоставление EXTID -> предпочесть импорт через форму
   • построчные интеграционные ответы -> предпочесть FIELDS ... DO

3. Для плоских импортов, требующих валидации, дедупликации, многопроходной обработки или постобработки, ассистенту СЛЕДУЕТ сначала складывать данные в LOCAL-свойства, обычно по INTEGER-строке, а затем обрабатывать их отдельным проходом FOR imported(INTEGER i).

4. Ассистенту СЛЕДУЕТ использовать FIELDS ... DO, когда импортируемые значения используются лишь однажды и введение переиспользуемых локальных свойств добавило бы шум.

5. Ассистенту СЛЕДУЕТ указывать сопоставление колонок явно, когда внешний шаблон фиксирован или разрежен.

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

6. Для импорта через форму ассистент ОБЯЗАН объявить выделенную форму импорта до использования.

   Форма ОБЯЗАНА использовать один объект на группу объектов с числовыми или конкретными пользовательскими классами.

   Форме СЛЕДУЕТ отражать внешнюю структуру через:

   • FILTERS для связей родитель-потомок
   • EXTID, FORMEXTID, группы и ATTR только там, где этого требует внешняя схема

   Ассистент ОБЯЗАН помнить, что импорт в форму отменяет ожидающие изменения импортируемых свойств формы в текущей сессии.

7. Ассистент ОБЯЗАН явно выбирать опции формата, когда от них зависит внешний контракт:

   • HEADER / NOHEADER
   • SHEET
   • CHARSET

   Ассистенту СЛЕДУЕТ предпочитать HEADER для стабильных шаблонов CSV / XLS, потому что NOHEADER может незаметно сопоставить отсутствующие или неверно типизированные колонки в NULL.

8. Ассистент ОБЯЗАН валидировать ссылочные бизнес-ключи до создания или обновления постоянных объектов.

   Типичные ключи в этом проекте — id, number, коды партнёров или товаров и внешние ссылки.

   Каждая ссылка ДОЛЖНА проверяться в отдельном FOR через GROUP SUM 1 BY по импортируемым значениям ключей.

   По возможности ассистенту НЕ СЛЕДУЕТ записывать разрешённые ссылки в отдельный LOCAL до основной логики импорта.

   Отсутствующие мастер-данные или некорректные данные ДОЛЖНЫ останавливать импорт или выдавать понятную ошибку.

9. Ассистенту СЛЕДУЕТ разделять сырой импорт и доменное разрешение:

   • сначала разобрать файл или данные в локальные свойства или форму импорта
   • затем проверить ссылки, такие как товар, партнёр, статус, тип или другие справочники
   • только потом создавать или обновлять доменные объекты

10. Для запускаемых пользователем пакетных импортов и внешних интеграций ассистенту СЛЕДУЕТ изолировать сохранение в NEWSESSION и СЛЕДУЕТ выполнять APPLY; после доменных записей одного импорта.

    Три правила сессий изменений задевают любой импорт, поэтому они приведены здесь, а не оставлены на второй запрос:

    • буфер, заполненный в верхней сессии, доходит до новой только через NESTED — в операторе либо в самом объявлении DATA LOCAL NESTED, — и не доходит вовсе под NEWSQL, который не переносит ничего;
    • после APPLY; ассистент ОБЯЗАН проверить canceled(), прежде чем считать импорт состоявшимся;
    • ошибку, поднятую самим APPLY, платформа уже показала интерактивному пользователю, поэтому интерактивный импорт НЕ ДОЛЖЕН сообщать её повторно; импорт из API или фоновый ОБЯЗАН сообщить её сам — через applyMessage() или исключение.

    Остальные — в статье про сессии изменений: lsfusion_retrieve_docs(type='rules', query='change sessions').

11. Ассистент НЕ ДОЛЖЕН частично сохранять неудавшийся импорт молча. Для ошибок, которые ассистент обнаруживает сам (отсутствующие ссылки, некорректные данные, валидация до APPLY), ему СЛЕДУЕТ использовать MESSAGE, RETURN, throwException или явный флаг неудачи, согласованно с вызывающей стороной:

    • интерактивный импорт -> MESSAGE
    • API или фоновая интеграция -> исключение или явное состояние неудачи

12. Для импортов-синхронизаций «создать-или-обновить» ассистент ОБЯЗАН разделять создание объектов и обновление свойств.

    Ассистент ОБЯЗАН делать один отдельный проход, только создающий недостающие объекты. FOR — один из способов его записать; множественная форма NEW ... WHERE ... TO создает объект на каждый подходящий набор одной операцией и предпочтительна везде, где подходит.

    Если импортируемые значения ключей могут быть неуникальны, проход создания СЛЕДУЕТ итерировать по сгруппированным ключам через GROUP SUM ... BY, а не по сырым импортируемым строкам.

    Затем ассистент ОБЯЗАН обновить свойства найденных объектов вторым отдельным проходом — прямое <- ... WHERE меняет все подходящие наборы разом, а FOR нужен только там, где тело делает то, чего множественное изменение не умеет.

    Ассистент НЕ ДОЛЖЕН смешивать создание объектов и обновление свойств в одном проходе для импортов-синхронизаций.

    Если требуется полная синхронизация, ассистенту СЛЕДУЕТ добавить явный шаг удаления.

13. Если LOCAL-свойства промежуточного хранения используются только в одном действии импорта, ассистент ОБЯЗАН объявлять их внутри этого действия.

    Ассистенту НЕ СЛЕДУЕТ выносить такие LOCAL-свойства на уровень модуля без необходимости.

    Исключение: LOCAL-свойство можно объявить вне действия только когда оно должно использоваться формой импорта или переиспользоваться несколькими связанными действиями.