Модуль для OpenCart: чек-лист перед выходом в прод

Модуль для OpenCart нельзя считать готовым к продакшену после того, как он один раз вывел блок на странице. Перед публикацией нужно проверить установку на чистом магазине, права администратора, события, мультимагазин, тему, журнал ошибок и возможность отката. Ниже — практический чек-лист для OpenCart 3.x и 4.x; полный прогон обычно занимает от одного до нескольких часов, если тестовое окружение уже подготовлено.

Сначала зафиксируйте целевую среду

OpenCart 3.x и OpenCart 4.x отличаются структурой расширений, способом установки и рядом внутренних соглашений. Модуль, который без изменений подключается в одной ветке, не обязан работать в другой. Версия PHP, база данных, тема и веб-сервер тоже входят в контракт модуля.

• запишите точную версию OpenCart и PHP, для которых выпускаете модуль;
• укажите поддерживаемые СУБД и минимальную версию, если модуль меняет структуру базы;
• проверьте магазин с темой по умолчанию и с той темой, которую использует заказчик;
• создайте отдельную копию файлов и базы перед установкой;
• проверьте, что тестовый домен не отправляет настоящие письма, платежи и вебхуки.

Результат этого шага — короткий файл совместимости: версия OpenCart, PHP, тема, список зависимостей и ограничения. Без него ошибку после обновления легко принять за случайный сбой.

Выберите способ встраивания

В OpenCart встречаются три подхода. Их нельзя считать взаимозаменяемыми: цена быстрого запуска часто проявляется при обновлении магазина или удалении модуля.

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

Продакшен готов не тогда, когда модуль работает на вашем компьютере, а когда его можно установить, проверить и удалить без ручного ремонта магазина.

Чек-лист функциональности

Установка и удаление

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

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

Настройки и права

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

CSRF-токен^* — случайное значение, которое связывает отправку формы с открытой сессией администратора и мешает чужому сайту незаметно отправить запрос от его имени.

Проверьте публичную часть магазина

Главная ошибка модулей для OpenCart — проверка только на одной странице и в одной теме. Пройдите сценарии гостя, зарегистрированного покупателя и администратора.

• откройте главную, категорию, карточку товара, корзину и оформление заказа;
• проверьте товар без изображения, товар с опциями, отключённый товар и нулевой остаток;
• пройдите заказ с валидным и невалидным адресом, промокодом и способом доставки;
• проверьте мобильную ширину, длинное название товара, пустой список и ошибку внешнего сервиса;
• откройте страницы при выключенном JavaScript, если модуль заявляет частичную работу без него;
• проверьте повторное обновление страницы и возврат назад после отправки формы.

Особенно внимательно ищите двойное выполнение: повторную запись заказа, два одинаковых уведомления, дублирование блока или повторный вызов внешнего API. В браузере проверьте консоль и сетевые запросы, а на сервере — журнал ошибок OpenCart и веб-сервера.

События, кеш и мультимагазин

Если модуль использует события, составьте таблицу: событие, файл или действие, которое оно изменяет, ожидаемый результат и способ отключения. Одно событие не должно срабатывать дважды после повторной установки.

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

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

Что ломается первым

• После обновления нет изменений. Проверьте кеш модификаций, порядок загрузки и совместимость с новой версией OpenCart. Не редактируйте ядро вручную поверх обновления.
• Фатальная ошибка при открытии страницы. Смотрите первую ошибку в журнале, а не последнюю строку в браузере. Частые причины — несовместимый путь к классу, отсутствующий шаблон или вызов метода, которого нет в целевой версии.
• Настройка сохраняется, но не действует. Сравните ключ настройки, магазин, группу пользователя и место, где значение читается. Затем очистите кеш и повторите проверку.
• Блок есть у администратора, но отсутствует у покупателя. Проверьте статус расширения, макет, позицию, тему и условие, зависящее от авторизации или магазина.
• Заказ создаётся, но внешняя система не получает уведомление. Проверьте журнал запроса, тайм-аут, код ответа и повторную отправку. Не записывайте секретный токен в лог и не показывайте ответ внешнего сервиса покупателю.

Перед публикацией и откатом

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

1. Установите релиз на чистую копию.
2. Пройдите основной сценарий покупателя и административный сценарий.
3. Проверьте журнал ошибок после каждого сценария.
4. Сделайте резервную копию файлов и базы.
5. Проверьте откат на предыдущую версию, включая удаление новых настроек и миграций.
6. Зафиксируйте результат: версия, дата, окружение и список пройденных тестов.

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

Что делать дальше

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

Следующий практический шаг — собрать матрицу поддержки: версии OpenCart и PHP по горизонтали, темы и режимы магазина по вертикали. В каждой ячейке отмечайте не «должно работать», а дату последней проверки и найденные ограничения.