Загрузка спецификации в ERPNext из Excel: Data Import без ошибок и дублей

Спецификацию договора из Excel в ERPNext загружают через Data Import: готовят чистый файл, скачивают шаблон нужного DocType, переносят данные, гоняют пробный импорт на 20–30 строках и только потом грузят всё. Ниже порядок действий, типовые ошибки и сверка итогов.

Как загрузить спецификацию из Excel в ERPNext: порядок действий

Я начинаю не с ERPNext, а с файла. Excel заказчика почти всегда содержит объединённые ячейки, пробелы в конце кодов, «шт.» и «шт» в одной колонке и итоговые строки внутри таблицы. Data Import ничего из этого не простит, поэтому первый шаг — привести файл к плоской таблице: одна строка — одна позиция, один код материала — одно написание. Если вы внедряете систему сами, начните с обзора возможностей ERPNext — там видно, какие модули вообще задействованы. Если нужна помощь с запуском, мы делаем это в рамках внедрения ERPNext под ключ.

Дальше последовательность одна и та же для любой спецификации. Открываете Data Import, выбираете тип документа, режим Insert New Records, скачиваете шаблон (Download Template), переносите в него данные, загружаете файл и смотрите предпросмотр с предупреждениями по строкам и колонкам. Предупреждения сгруппированы по номерам строк. Кнопка Start Import при этом не блокируется, поэтому правило простое: пока список предупреждений не пуст, импорт не запускаем, и Start Import нажимается последней.

Пять шагов я держу в голове как короткий чек-лист: 1. Чистка Excel: единые коды, единицы измерения, без объединённых ячеек и итогов. 2. Скачивание шаблона из Data Import для нужного DocType, без ручной правки заголовков. 3. Перенос данных в шаблон: родительские поля только в первой строке документа, строки таблицы — на следующих. 4. Пробный импорт 20–30 строк и проверка результата глазами. 5. Полная загрузка и сверка итогов с исходным Excel.

Про размер. В документации ERPNext прямо сказано: жёсткого лимита на число записей нет, но загружать лучше по нескольку тысяч за раз. Спецификация на объект — это обычно от нескольких десятков до пары тысяч строк, так что упираться в лимит вы не будете. Опасность в другом: ошибка в 800-й строке при загрузке на 1 500 позиций заставит вас разбираться с частично созданными записями. Поэтому пробный кусок — не формальность.

Куда класть спецификацию: отдельный DocType, а не BOM

Самая частая ошибка новичков — попытка уложить перечень материалов договора в BOM. BOM в ERPNext — это Bill of Materials, производственная спецификация изделия из модуля Manufacturing: из чего собрать один прибор или шкаф. Для длительной стройки или монтажа с поэтапным расходом он не подходит: нет привязки к договору и проекту, нет контроля плановых количеств по этапам. В обзорах встречается формулировка «спецификация как BOM» — это упрощение, и я бы её не повторял клиентам.

Рабочий вариант — собственный DocType. Я условно называю его Contract BOQ: основной документ с полями Project (ссылка на проект), номер договора и статус, плюс дочерняя таблица позиций с полями Item (ссылка на номенклатуру), плановое количество и цена. Дочерний DocType создаётся с галочкой Is Child Table, а в основной документ добавляется поле типа Table, которое на него ссылается — так устроены все дочерние таблицы Frappe, например строки заказа. Названия полей и самого DocType — ваши, называйте как удобно команде; в статье я использую рабочие имена.

Сравнение, которое я показываю заказчикам: | Критерий | BOM | Спецификация договора (свой DocType) | |---|---|---| | Назначение | состав изделия для производства | перечень материалов и объёмов по договору | | Где живёт | модуль Manufacturing | кастомный DocType, создаётся через Customize | | Привязка к проекту | нет в коробке | поле Project | | Строки | компоненты изделия | Item, плановое количество, цена | | Подходит для контроля перебора | нет | да, но сам контроль — доработка | | Работа на длительной стройке | неудобна | рассчитана на поэтапный расход |

Оговорка, которую нельзя пропускать. Загрузка спецификации — это только половина задачи. Контроль «заказали больше, чем запланировано» в коробке по количеству не работает: бюджет Budget следит за суммами по статьям, а запрет превышения по количеству приходится дорабатывать. Это отдельная доработка, и в конце статьи на примере подрядчика видно, где проходит граница между коробкой и кастомизацией.

Что должно существовать до импорта: Item, единицы измерения, проект

Любая ссылочная колонка в файле — это обещание, что запись с таким именем уже есть в системе. Колонка Item в спецификации ссылается на карточку номенклатуры, единица измерения — на справочник UOM, проект — на документ Project. Если в базе нет хотя бы одной из этих записей, строка не пройдёт. Порядок загрузки данных при запуске ERPNext я всегда держу таким: пользователи, справочники, компании и контрагенты, контакты, и только потом документы. Спецификация — документ, она идёт после всего остального.

Практически это значит три загрузки подряд. Сначала единицы измерения: «м», «м.п.», «шт», «компл.» — ровно в том написании, которое будет в спецификации. Затем номенклатура: Item с кодом, названием, группой и единицей по умолчанию. Затем проект, под который загружается спецификация. Только после этого — сам файл с позициями. Перенос мастер-данных — самостоятельная задача со своими граблями (дубли контрагентов, остатки на дату отсечки), и если вы переезжаете из 1С, она занимает больше времени, чем загрузка спецификации.

Что я проверяю в справочниках до пробного импорта: уникальность кодов в Excel (формулой «повторы» или сводной таблицей), совпадение единиц в колонке спецификации и в карточке Item, отсутствие лидирующих и хвостовых пробелов, одинаковую «ё/е» в названиях. Нужная строка в ERPNext находится по имени записи, и «Кабель ВВГнг» и «Кабель ВВГнг » с пробелом для системы — разные значения.

Какие ошибки выдаёт Data Import и что с ними делать

Типичных симптомов три, и все они возникают на этапе проверки файла или в журнале импорта. Первый — Duplicate Name: в файле повторяется ключ строки либо запись с таким именем уже есть в системе, часто потому, что файл уже загружали раньше. Второй — ссылка на несуществующий Item или UOM: справочник не загружен или написан иначе. Третий — колонки не сопоставились: шаблон правили вручную, переименовали заголовок или вставили колонку посередине.

Для каждого симптома свой разбор: | Симптом | Вероятная причина | Что делать | |---|---|---| | Duplicate Name | дубль ключа в файле или повторная загрузка | удалить дубли в Excel, открыть журнал импорта и проверить, что уже создано | | Не найдена ссылка на Item или UOM | справочник не загружен или другое написание | сначала загрузить номенклатуру и единицы, затем спецификацию | | Колонка не сопоставилась | вручную правили шаблон | снова скачать шаблон и перенести данные в него | | Пустое обязательное поле | пропущена колонка с красной звёздочкой | заполнить, обязательные поля видны в шаблоне |

Про журнал. После запуска Frappe хранит результат по каждой строке в логе импорта (в коде это DocType Data Import Log): создана или обновлена запись, текст ошибки, номера строк. Это основной инструмент разбора: не гадайте по сообщению на экране, а откройте журнал и найдите первую упавшую строку. Остальные ошибки часто тянутся за ней.

Про фоновую обработку. Импорт запускается как фоновая задача. В коде Frappe (ветки version-15 и develop) импорт ставится в очередь default, а не в long, хотя в обзорах часто пишут обратное. В frappe_docker очередь default слушают оба сервиса воркеров: queue-short и queue-long. Практический вывод от этого не меняется: если на экране импорта прогресс не движется, откройте Background Jobs и убедитесь, что воркеры вообще запущены. В контейнерной установке frappe_docker это отдельные сервисы-воркеры, и бывает, что их забыли поднять:

docker compose ps
docker compose logs --tail=50 queue-short queue-long

Имена сервисов зависят от вашего compose-файла, проверьте их через docker compose ps.

Как убедиться, что загрузилось всё и ничего не задвоилось

Сообщение «Import completed» ничего не доказывает. Я сверяю три числа и одно выборочное сравнение. Число документов: сколько спецификаций в файле, столько и должно появиться в списке с фильтром по проекту. Число строк: общее количество позиций в Excel и сумма строк дочерней таблицы по всем загруженным документам. Сумма: плановое количество по каждому коду и стоимость — сводной таблицей в Excel и отчётом по списку в ERPNext.

Сверку делают двое: тот, кто готовил файл, и тот, кто будет с ним работать — на стройке это начальник участка, в торговле — снабженец. Выборочно проверяют 10–15 строк с разных концов файла: первую, последнюю, строки с нестандартной единицей, строки с дробным количеством. Чаще всего ошибка находится именно в дробных значениях: запятая вместо точки или неправильная локаль в Excel превращают 1,5 в 15 или в текст.

Повторную загрузку исправленного файла не делайте поверх созданных записей. Если нужно обновить уже загруженное, используйте режим Update Existing Records: экспортируйте записи с колонкой ID, исправьте значения и загрузите обратно. Загрузка того же файла заново в режиме вставки даст дубли — или, если ключи совпадают, ошибки Duplicate Name. Так же в режиме Update заменяют цену или количество у позиции без пересоздания документа.

Как «Теплоконтур Монтаж» загрузила спецификацию на котельную (условный пример)

Подрядчик по инженерным системам «Теплоконтур Монтаж», 5 рабочих мест, получил от заказчика спецификацию на монтаж котельной: Excel на 412 строк, три листа — трубопроводы, арматура, электрика. Смету сметчик считал во внешней программе, в ERPNext нужна была только итоговая ресурсная спецификация. Расценок ФЕР/ТЕР и форм КС-2 в коробке нет, и их туда не переносили. Все цифры здесь условные, чтобы показать порядок работ.

Подготовка заняла полдня. В файле нашли 37 строк-итогов внутри таблицы, 11 дублей кода (одна позиция на двух листах) и 19 вариантов написания единицы измерения для четырёх реальных единиц. Сметчик свёл три листа в один, администратор привёл единицы к списку из шести значений. После чистки осталось 364 позиции. Справочники грузились первыми: 6 единиц измерения, 241 карточка Item, один проект.

Пробный импорт на 25 строках выдал две ошибки: у двух позиций код Item отличался от справочника одним символом, и в колонке количества была запятая. Исправили в исходном файле, повторили пробу — чисто. Полная загрузка 364 строк прошла за несколько минут. Сверка показала совпадение числа строк, а в суммах расхождение нашлось у одной позиции: количество «12,5» превратилось в «125» в одной строке, её поправили в режиме Update Existing Records. Начальник участка просмотрел список и принял спецификацию как опорную для заявок.

Что осталось за рамками. Контроль перебора по количеству не заработал после загрузки — это доработка: пользовательские поля в строках заявки и проверка при сохранении. Печатная форма спецификации по ГОСТ делается конструктором печатных форм отдельно. Показать, как выглядит такая спецификация и импорт, мы можем на демостенде erp-demo.itfresh.ru по запросу.

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