Разработка
ТЗ на импорт каталога: схема данных, ошибки и безопасный повтор
Как подготовить массовый импорт товаров: ключи, типы полей, обновление и удаление, пробная загрузка, отчёт расхождений и восстановление.
Сначала определите смысл импортируемого файла
ТЗ на импорт большого каталога начинается с ответа, что означает полученная выгрузка. Это полный снимок ассортимента или только изменения? Отсутствующий товар нужно удалить, отключить или оставить без изменений? Пока эти правила не согласованы, увеличение скорости загрузки опасно: система просто быстрее применит неверное решение ко всему каталогу.
Опишите источники, получателей и расписание. Один поставщик может присылать товары, другой — остатки, а редактор — описания. У каждого потока свой владелец и границы влияния. Не объединяйте всё в абстрактный «файл каталога». Полезно дать каждому потоку имя, версию формата, ожидаемый состав и условие, при котором его разрешено применять.
Возьмите несколько реальных обезличенных образцов, включая неудачную выгрузку. Добавьте сведения об объёме, количестве вариантов и изображений, длине описаний. Если этих данных пока нет, оценка производительности остаётся предварительной. Миллион коротких строк и небольшой каталог с тяжёлыми изображениями нагружают систему по-разному, поэтому одно число товаров не описывает задачу целиком.
Согласуйте ключи и связи объектов
Для товара, предложения, категории и изображения нужны правила идентификации. Артикул может быть уникален только внутри поставщика, а название обычно вообще не подходит как ключ. Если товар переименован, импорт должен узнать прежний объект, а не создать дубль. Область уникальности и порядок сопоставления обязательно входят в бриф.
Отдельно опишите связи: вариант принадлежит модели, товар входит в категории, изображение относится к определённому предложению. Решите, можно ли создать дочерний объект до родителя и где хранить запись, если родитель отсутствует. Неявная автоматическая категория «прочее» иногда скрывает ошибку классификации; её допустимость должна быть осознанным решением, а не побочным эффектом загрузчика.
Учебный пример: два поставщика используют артикул A17 для разных товаров, а один товар имеет три размера. Приёмка должна показать, что ключ поставщика учитывается, размеры не превращаются в независимые дубли, а повторный файл обновляет прежние записи. Сохраните ожидаемую структуру до запуска теста: сравнение только общего количества товаров не выявит ошибочных связей.
Опишите поля, пустоту и нормализацию
Для каждого поля задайте тип, обязательность, допустимые значения, единицу измерения и источник. Цена требует валюты и правила округления, масса — единицы, дата — формата и временной зоны. Значение «10» само по себе не сообщает, что измерено. Если нормализация выполняется автоматически, её результат должен быть виден в пробном отчёте.
RFC 4180 описывает распространённые правила CSV, включая строки, разделители и экранирование. На практике поставщики используют разные диалекты, поэтому в контракте файла явно укажите кодировку, разделитель, кавычки и заголовок. Название расширения .csv не заменяет договорённость. Обязательно проверьте запятую и перенос строки внутри описания, кавычки в названии и символы другого языка.
Особое внимание уделите пустому значению. «Поле не передано», «поле неизвестно» и «очистить поле» могут требовать разных действий. То же относится к нулю: нулевая цена может быть допустимой, запрещённой или признаком отсутствия данных в конкретном источнике. Не исправляйте такие случаи догадкой. Задайте правило отклонения, карантина или уточнения с понятной причиной.
Разделите проверку и применение изменений
Перед записью в рабочий каталог полезен режим предварительного просмотра. Он показывает новые, изменяемые, отключаемые и отклонённые объекты, а также конфликты справочников. Пользователь должен видеть не только число строк, но и выборку последствий: старая цена, новая цена, изменение категории, очищаемое описание. Это помогает обнаружить неверный смысл файла до массовой записи.
Документация PostgreSQL COPY демонстрирует, что поведение при ошибках загрузки зависит от выбранных параметров и возможностей версии. Для вашей системы важнее сформулировать наблюдаемый контракт: остановить весь пакет, пропустить отдельную строку или изолировать связанный набор. Не оставляйте это случайным следствием используемой команды. Технический механизм выбирают после согласования требуемой целостности.
Опишите пределы автоматического применения. Например, необычно большая доля отключений, неизвестный формат или отсутствие обязательного справочника переводят пакет на рассмотрение. Конкретные пороги определяют по данным проекта и тестируют. Сам факт успешного разбора файла не означает, что его содержание безопасно для бизнеса. Разбор формата и проверка ожидаемых последствий — разные этапы.
Сделайте повтор и продолжение предсказуемыми
Большая загрузка может остановиться после части записей. В ТЗ нужно определить единицу фиксации, идентификатор пакета, контрольную точку и способ продолжения. Пользователь должен понимать, какие изменения уже применены и что произойдёт при повторном запуске. Кнопка «загрузить ещё раз» без этих правил создаёт риск дублей или повторного изменения данных.
Учебный сценарий: пакет содержит сто товаров, после сорокового запись прервалась. Числа здесь нужны только для наглядности. Команда должна показать, как повтор обрабатывает уже применённые строки, как узнаёт изменившийся файл и что делает с исправленной строкой из карантина. Если файл заменили под тем же именем, система не должна автоматически считать его прежним пакетом.
Для конкурентных изменений задайте приоритеты. Редактор мог исправить описание между чтением источника и применением импорта. Нужно ли сохранять ручную правку, перезаписывать её или показывать конфликт? Решение может различаться по полям. Правило «последняя запись победила» допустимо только тогда, когда участники понимают его последствия и согласовали именно такой способ работы.
Проверьте изображения и связанные файлы отдельно
Успех товарной части не подтверждает загрузку медиа. Изображение может быть недоступно, иметь неверный формат, относиться к другому варианту или превышать согласованный размер. В требованиях задайте проверку доступности, допустимые типы, обработку ошибок и повтор. Не заменяйте неудачное изображение случайной картинкой, чтобы формально закрыть пустое место.
Опишите, какие файлы сохраняются после обновления и как удаляются больше не используемые. Если несколько товаров ссылаются на одно изображение, удаление одной карточки не должно ломать остальные. Для прав использования нужен ответственный источник подтверждения; импортёр не может установить права по имени файла. До получения разрешённых материалов проект может использовать явно согласованный порядок без выдуманного контента.
В отчёте разделяйте импорт данных и обработку медиа. Пользователь должен видеть, что товар создан, но изображение ещё ожидает загрузки, и понимать, когда карточка считается готовой к показу. Скрытое продолжение фоновой обработки после сообщения «всё завершено» затрудняет приёмку. Состояния пакета должны отражать весь согласованный результат, а не только первый быстрый шаг.
Сверьте результат независимыми способами
Проверка включает количество объектов, уникальность ключей, связи, критические суммы и выборочные карточки. Одного равенства количества строк недостаточно: дубли и пропуски могут взаимно компенсироваться. Сравните отдельно созданные, обновлённые, пропущенные и отклонённые записи. Для каждого отклонения должны быть причина и путь исправления.
Подготовьте эталонный набор с обычным товаром, несколькими вариантами, длинным текстом, пустым полем, неизвестной категорией и недоступной картинкой. Добавьте полный повтор, частичный сбой и пустую выгрузку. Для каждого случая определите ожидаемое поведение заранее. Время обработки измеряйте в описанном окружении и вместе с объёмом медиа, чтобы показатель можно было воспроизвести.
Откат также нужно испытать. Возврат базы к прежнему состоянию может затронуть ручные изменения, сделанные после начала импорта. Опишите границы восстановления, снимок исходных данных и порядок согласования. Иногда безопаснее отменить конкретный пакет через журнал изменений, иногда нужен другой механизм. Выбор должен опираться на модель данных и допустимое окно остановки, а не на обещание «всегда всё вернём».
Передайте исполнителю контракт и контрольный пакет
Готовое ТЗ включает схему данных, образцы файлов, правила сопоставления, карту владельцев полей и приёмочные сценарии. Приложите описание окружения, ограничений доступа и ожидаемой частоты. Скачиваемый бриф помогает отметить открытые вопросы и назначить владельца каждого решения. Он особенно полезен, когда поставщик данных и разработчик каталога работают в разных командах.
Перед оценкой попросите участников независимо объяснить смысл отсутствующей строки и пустой ячейки. Если ответы различаются, контракт пока не готов. Затем проведите пробную загрузку в изолированное окружение и разберите отчёт вместе с человеком, который знает ассортимент. Технически корректная запись в базе может оставаться неверной с точки зрения товара или учёта.
Запуск первой версии лучше ограничить согласованным потоком и наблюдать за повторными выгрузками. Назначьте владельца карантина и срок разбора ошибок. Автоматизация не устраняет ответственность за исходные данные; она делает её особенно заметной. Практический результат проекта — каталог, который обновляется предсказуемо и допускает проверку, а не просто быстро завершающийся скрипт.
Источники
- RFC 4180: CSV files
IETF / RFC Editor / доступ 2026-10-12
Первичный источник для соответствующей технической темы. Структура брифа и учебные проверки разработаны редакцией; возможности конкретной системы проверяются перед внедрением.
- COPY
PostgreSQL Documentation / доступ 2026-10-12
Первичный источник для соответствующей технической темы. Структура брифа и учебные проверки разработаны редакцией; возможности конкретной системы проверяются перед внедрением.
- Скачать заполняемый бриф / ТЗ (.txt)
Малевич — практическое приложение / доступ 2026-10-12
Сохраните файл и заполните исходные данные, решения и критерии приёмки своего проекта.
FAQ
Нужно ли отклонять весь файл из-за одной строки?
Это бизнес-правило, которое следует зафиксировать заранее. Независимые товары можно отправить в карантин отдельно, а связанный комплект иногда требует целостного отклонения. При любом варианте отчёт должен показывать, что применено, что пропущено и какие действия необходимы для безопасного повторного запуска.
Означает ли пустая ячейка удаление значения?
Только если так определён контракт. Пустота может означать неизвестное значение, отсутствие изменения или явное очищение поля. Эти случаи нужно различить в формате входных данных; иначе повторная выгрузка способна удалить описание, цену или связь, которые источник вообще не собирался менять.
Как оценить скорость импорта до разработки?
Соберите представительный образец с длинными описаниями, изображениями, вариантами и ошибочными строками, задайте ограничения окружения и выполните пилот. Отдельно измеряйте чтение, проверку, запись и обработку медиа. Скорость обработки короткого чистого файла нельзя без проверки переносить на полный каталог.
