Импорт данных из Excel: проверка, дубли и безопасная загрузка

Как устроить импорт данных из Excel и CSV: сопоставление колонок, проверка строк, ведущие нули, дубли, пробный прогон и отчёт о загрузке.

Автор: Александр Поркулевич, CEO и основатель, 404gen.

Сначала определите, что меняет импорт

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

Опишите объект и границу одной операции. Например, загрузка карточек оборудования не обязана одновременно создавать новые склады, категории и сотрудников из произвольных текстовых значений. Такие автоматические связи легко порождают несколько вариантов одного справочника. Для первой версии разумно использовать проверенные справочники и отправлять неизвестные значения на уточнение, сохраняя исходную строку.

В задании полезна таблица решений: какое поле обязательно, чем определяется существующая запись, какие значения можно менять и что означает пустота. Подтверждает её владелец процесса. Разработчик не должен самостоятельно выбирать, считать ли отсутствие телефона командой удаления. Удобная техническая трактовка может противоречить работе сотрудников и повредить уже собранную базу.

Excel и CSV: разные входные форматы

XLSX — книга с листами, типами ячеек и оформлением. CSV — текстовый формат с определёнными правилами разделения полей. Расширение файла само по себе не подтверждает, что содержимое корректно. Для каждого поддерживаемого варианта определите ограничения, проверку структуры и понятную ошибку. Старые книги, защищённые паролем файлы и нестандартные выгрузки не следует обещать поддерживать без испытаний.

Для книги нужно выбрать лист и строку заголовков. На первом листе может быть инструкция, а рабочая таблица — на втором. Объединённые ячейки, дополнительные подписи и скрытые строки требуют правил. Не импортируйте всё, что визуально похоже на таблицу, без предварительного просмотра. Человек должен увидеть, какой диапазон будет прочитан и какие строки исключены как оформление.

Для CSV задаются кодировка, разделитель, кавычки и обработка переноса строки внутри поля. Простое деление по запятой не учитывает текст, содержащий запятую или перенос. Документация Microsoft Power Query по Text/CSV показывает отдельные настройки кодировки, разделителей и определения типов. В собственном продукте эти параметры также нужно считать частью формата, а не случайным свойством компьютера пользователя.

Импорт данных из Excel: сопоставление колонок

После чтения структуры покажите связь «колонка файла — поле системы». Автоматическая догадка по названию может ускорить начало, но её нужно подтверждать для существенных данных. Поля «код поставщика» и «внутренний код» не становятся взаимозаменяемыми из-за слова «код». Для сомнительного соответствия полезнее состояние «проверьте», чем уверенная подстановка первой похожей колонки.

Рядом с заголовком показывайте несколько исходных значений. Это помогает заметить, что под названием «количество» находится число коробов, а система ожидает штуки. Для преобразования единиц задайте явное правило и источник коэффициента. Если пересчёт зависит от конкретной позиции, одного общего множителя на весь файл недостаточно. Такие строки требуют найденного объекта и его подтверждённой единицы.

Нераспределённые обязательные поля блокируют переход к применению. Необязательные колонки можно пропустить, показывая это в сводке. Если одна колонка сопоставлена нескольким полям или два источника назначены одному полю, интерфейс должен объяснить правило приоритета либо потребовать исправления. Скрытый выбор «последний победил» создаёт результат, который трудно проверить по исходной таблице.

Типы, ведущие нули и точность значений

Код изделия, телефон и номер документа часто выглядят как числа, но используются как идентификаторы. Значение 00127 не всегда равно 127. Задайте тип по смыслу поля, сохраняя значимые символы. Если исходная программа уже превратила длинный идентификатор или дату в другое представление, импортёр не может надёжно восстановить потерянное. Он должен обнаружить риск и запросить исправленный источник.

Числа требуют согласованного десятичного и группового разделителя. Запись «1,250» в разных соглашениях может означать разные величины. Не угадывайте значение по одной ячейке, если весь файл противоречив. Покажите исходный текст, результат преобразования и ошибку для неоднозначной строки. Для денежных полей точность, валюта и округление определяются контрактом продукта; обычное форматирование экрана не задаёт эти правила.

Дата также имеет формат и деловой смысл. Условное «03/04/2026» нельзя без соглашения превратить в третье апреля или четвёртое марта. Если поле является моментом события, дополнительно нужен часовой пояс. Если это календарная дата документа, лишнее преобразование во время устройства может сдвинуть день. Поддерживаемые форматы перечисляют явно и проверяют на пограничных примерах, а не только на первой строке шаблона.

Пустая ячейка, неизвестное значение и очистка

В регулярном обновлении пустота может означать «не менять», «значение неизвестно» или «очистить поле». Выберите правило по каждому полю и режиму загрузки. Для очистки удобно отдельное явное действие или согласованное служебное значение, которое не встречается в обычных данных. Его нужно показать в инструкции и предпросмотре, иначе сотрудник случайно удалит сведения, оставив незаполненную колонку.

Документация PostgreSQL COPY отдельно рассматривает представление NULL, кавычки и пустые строки в CSV. Это технический пример того, почему «пусто в таблице» не является однозначным контрактом. В пользовательском импорте поверх формата потребуется бизнес-правило: какие существующие поля сохраняются и как подтверждается намеренная очистка.

Как отличить обновление от новой записи

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

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

Учебный пример: в файле четыре строки, одна обновляет объект EQ-027, одна создаёт EQ-028, две претендуют на EQ-029 с разными адресами. Предварительный итог должен объяснить все четыре строки: один кандидат на создание, один на обновление и две конфликтные. Нельзя сообщить «импортировано три объекта», потеряв происхождение второго адреса. Порядок последующей обработки конфликтов выбирают отдельно.

Проверка строки и проверка всей операции

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

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

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

Пробный прогон без изменения рабочей базы

До применения покажите будущие действия и различия. Для обновления полезна пара «было — станет», особенно для значимых полей. В сводке отдельно считаются создание, обновление, пропуск и ошибка. Укажите, охватывает ли просмотр весь файл или только выборку. Образец из первых строк помогает понять структуру, но не доказывает, что остальная часть прошла проверку.

Результат пробного прогона связывается с конкретным файлом, сопоставлением, правилами и состоянием исходной базы. Если человек после проверки заменил файл или другой сотрудник изменил объект, прежнее подтверждение может стать неактуальным. Рабочий продукт должен повторить существенные проверки или показать конфликт редакций. Незаметно применять иные значения под старой сводкой нельзя.

Пробный прогон не должен создавать скрытые сущности «для проверки». Если для расчёта нужны временные объекты, они изолируются от рабочей базы и имеют жизненный цикл. В журнале можно сохранить факт проверки, но не выдавать его за загрузку. Такой договор облегчает обучение сотрудников: кнопку проверки можно нажать без страха изменить каталог или отправить внешние документы.

Применение целиком или по допустимым строкам

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

Для частичного режима храните результат каждой строки и объясняйте итог. «Завершено с ошибками» не равно «ничего не записано». Пользователь должен понимать, что уже произошло и можно ли безопасно загрузить исправленный остаток. Не заставляйте его заново отправлять весь файл, не предоставив способ отличить обработанные объекты от неуспешных.

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

Большой файл, потеря связи и повтор запуска

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

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

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

Отчёт, исправление и повторная загрузка

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

Файл с ошибками полезно готовить в пригодном для повторной загрузки виде, отдельно от расширенного диагностического отчёта. Не добавляйте служебные колонки так, чтобы они случайно становились рабочими полями следующего запуска. Укажите версию шаблона и сохраните исходные коды как текст. После исправления пользователь снова проходит проверку: отсутствие прежней ошибки не доказывает актуальность всех остальных условий.

Для сопровождения сохраняйте происхождение изменения: кто запустил импорт, какая редакция правил использована и какие объекты затронуты. Доступ к исходному файлу и отчёту ограничивается по ролям и сроку. Если в таблице есть контакты или закрытые цены, общая ссылка на результат не должна открывать их любому сотруднику. Проблема импорта не должна превращаться в обход прав чтения.

Файлы и безопасное отображение

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

OWASP описывает CSV Injection как риск интерпретации недоверенных значений формулами при открытии выгрузки в табличной программе. Это касается и отчёта об ошибках: исходный ввод может вернуться пользователю в CSV. Не считайте обычные кавычки универсальной защитой для всех программ и повторных сохранений. Формат отчёта и обращение со значениями проверяют на целевых инструментах.

Ограничьте размер файла, число листов и строк, длину ячейки и ресурс обработки по измеренному рабочему профилю. Не выбирайте огромные пределы только ради рекламного описания. Проверяйте безопасное хранение и срок удаления исходников. Детальнее общий путь описан в статье про загрузку файлов; импорт добавляет к нему собственные правила преобразования и записи.

Как добавить импорт в существующий продукт

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

Начните с одного объекта, шаблона и режима записи. Согласуйте контрольную выборку с ожидаемыми действиями и проверьте её на тестовой базе. Усложняйте формат после того, как понятны результаты и восстановление. Материал про миграцию данных CRM рассматривает перенос между системами; регулярный импорт отличается повторяемостью и необходимостью понятного самообслуживания сотрудников.

До запуска определите поддержку: где искать задание, кто разбирает конфликт справочника и кто меняет шаблон. При выпуске новой версии формата старые файлы должны давать понятное сообщение, а не молча загружаться по другой схеме. Если поддерживаются несколько версий, у каждой остаются собственные правила и тесты. Совместимость — часть продукта, а не одноразовая настройка парсера.

Контрольные примеры для приёмки

Подготовьте небольшой набор, в котором результат каждой строки известен заранее. Включите корректное создание, обновление, пустоту, дубль, неизвестный справочник и конфликт редакции. Отдельно используйте CSV с текстом в кавычках и переносом внутри поля, а также XLSX с несколькими листами. Такой набор проверяет смысл функции лучше, чем большой случайный файл без ожидаемого результата.

1. Код с ведущими нулями остаётся текстовым идентификатором.
2. Неверный десятичный разделитель даёт объяснимую ошибку, а не другую величину.
3. Отсутствующая колонка и пустая ячейка обрабатываются по разным согласованным правилам.
4. Две строки с одним ключом и разными значениями остаются видимым конфликтом.
5. Пробный прогон не изменяет рабочие объекты.
6. Изменение файла или схемы сбрасывает прежнее подтверждение.
7. Потеря ответа после запуска возвращает номер существующего задания.
8. Частичное завершение объясняет результат каждой строки и повторную загрузку.
9. Чужой отчёт и исходный файл недоступны по прямой ссылке.
10. Выгрузка ошибок безопасно открывается в согласованной табличной программе.

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

Частые вопросы

Можно ли автоматически определить все поля по заголовкам?

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

Как не создавать дубли при повторной загрузке?

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

Нужно ли отклонять весь файл из-за одной ошибки?

Это зависит от связности данных. Для неделимого документа частичная запись может нарушить смысл. Для независимых карточек допустима обработка корректных строк, если пользователь видит режим и получает результат каждой строки. Главное — не скрывать уже сделанные изменения и дать понятный путь исправить остаток, не повторяя выполненные действия бесконтрольно.

Можно ли вернуть всё после импорта?

Восстановление требует заранее спроектированной истории и границ операции. Если после загрузки другие сотрудники изменили объекты или внешние сервисы выполнили действия, простое удаление записей может повредить новую работу. Для первой версии полезны пробный прогон, ограниченный объём и подтверждение различий. Возможность отката проверяют отдельно и не обещают шире реализованного сценария.

Что подготовить для оценки доработки

Соберите несколько типовых файлов, правила создания и обновления, описание ключей и примеры ошибок. Укажите, кто отвечает за справочники и как сотрудники узнают результат. В концепте «Сверка» показаны сопоставление колонок, пробный прогон и блокировка применения после изменения исходных условий. Это авторский макет с вымышленными данными, а не внедрённая система.

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