Инструкция к модулю Импорт городов

Что делает модуль

Модуль добавляет в CS-Cart отдельный сценарий импорта городов. Через CSV-файл можно создавать новые города и обновлять существующие, передавая название города, страну, код региона, универсальный почтовый индекс и язык описания.

Модуль работает со справочником стандартного модуля «Города». У него нет отдельной страницы настроек, фонового задания или расписания: импорт запускается вручную через стандартную форму CS-Cart, а универсальный индекс также можно задать в карточке города.

Перед импортом

1. Создайте резервную копию базы данных, особенно перед массовым добавлением или обновлением городов.
2. Сначала подготовьте тестовый файл из одной или нескольких строк и проверьте результат на нём.
3. Убедитесь, что стандартный модуль «Города» активен, а у пользователя есть право на управление каталогом.
4. Для обновления существующих городов добавьте в файл их city_id. Не обновляйте большой справочник только по названиям городов.

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

Где находится модуль

Форма импорта находится в административной панели: Администрирование → Импорт данных → MS: Импорт городов.

Поле Универсальный индекс появляется в форме создания и редактирования города, которую предоставляет стандартный модуль «Города». Точное расположение справочника городов в меню зависит от версии и редакции CS-Cart.

Раздел импорта доступен пользователям с правом управления каталогом. Отдельных настроек в карточке модуля нет.

Поля файла импорта

Названия ниже соответствуют полям схемы импорта. Если заголовки вашего CSV-файла отличаются, сопоставьте их с нужными полями в стандартной форме импорта CS-Cart.

Как подготовить данные

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

Для обновления города: передайте его city_id и заполните обязательные поля city, country и state_code. Не полагайтесь на поиск по названию, если в справочнике могут быть одноимённые города.

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

Как выполнить импорт

1. Откройте Администрирование → Импорт данных → MS: Импорт городов.
2. Загрузите CSV-файл с заголовками столбцов.
3. В параметре языка выберите язык или языки импортируемых описаний городов.
4. Сопоставьте столбцы файла с полями схемы. Проверьте наличие обязательных полей city, country и state_code.
5. Для обновления существующих записей отдельно проверьте сопоставление столбца city_id.
6. Запустите импорт сначала для тестовых строк и изучите итоговое уведомление CS-Cart.
7. После проверки тестовых городов выполните импорт основного файла.

Что происходит во время импорта

• Название из поля country сопоставляется со страной из справочника CS-Cart и преобразуется во внутренний код страны.
• Если передан city_id, он используется как ключ существующего города.
• Если city_id не передан, модуль пытается найти город по точному названию; при отсутствии совпадения создаётся новая запись.
• Код региона проверяется внутри выбранной страны. Отсутствующий регион создаётся автоматически в активном статусе.
• Название города сохраняется для выбранного языка, а zipcode записывается как универсальный индекс города.

Универсальный индекс в карточке города

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

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

Как проверить работу

1. Создайте тестовый CSV-файл с уникальным названием города, существующей страной, существующим кодом региона, языком и заметным тестовым индексом.
2. Импортируйте одну строку и убедитесь, что операция завершилась без ошибок.
3. Найдите город в стандартном справочнике и проверьте его название, страну и регион.
4. Повторите импорт той же записи, указав её city_id и изменив название или индекс. В справочнике не должен появиться дубликат.
5. Если в рабочем файле используется новый код региона, отдельно проверьте автоматически созданный регион и замените техническое название-код на понятное название.
6. Если нужно подтвердить сохранение индекса, проверьте его в сценарии магазина или интеграции, где используется индекс города. Повторно открытая карточка города не подходит для такой проверки, потому что поле в ней не заполняется сохранённым значением.

Возможные проблемы

Страна не распознана. Проверьте написание: значение должно точно совпадать с одним из названий страны в справочнике CS-Cart на установленном языке.

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

Регион отображается кодом. Так выглядит автоматически созданный регион. Откройте справочник регионов и задайте ему понятное название.

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

Импорт сообщает об обязательных полях. Проверьте сопоставление city, country и state_code, а также наличие значений в каждой строке.

Название города попало не в тот язык. Проверьте язык в параметрах импорта и значения столбца Language, если он используется.

Раздел импорта недоступен. Проверьте стандартный модуль «Города» и право пользователя на управление каталогом.

Сохранённый индекс не показан в карточке. Это ограничение формы модуля: поле принимает новое непустое значение, но не выводит ранее сохранённое.