1.0.0-beta1

Дата релиза: 21 апреля 2026

Первый публичный релиз ms3PromoCode — промо-коды для MiniShop3.

Скидки

• Два типа: процент или фиксированная сумма.
• Две области применения: вся корзина или только позиции, подпадающие под правила.
• Учёт скидки в позициях — цена со скидкой пишется в msOrderProduct.price. Чек 54-ФЗ, email-уведомления и личный кабинет показывают корректные суммы без правок шаблонов.
• Точная сумма скидки — копейки от пропорционального распределения компенсируются, итог совпадает с заявленной суммой до копейки.

Правила

• Включить / исключить конкретные товары.
• Категории, бренды.
• Универсальный фильтр по любому полю modx_ms3_products с операторами =, !=, <, <=, >, >=, IN, NOT IN, BETWEEN, LIKE, CONTAINS.
• Фильтр по опциям товара (цвет, размер, материал и т.п.).
• Секции объединяются по «И», значения внутри секции — по «ИЛИ».

Жизненный цикл

• Период действия: даты начала и окончания.
• Общий лимит применений.
• Минимальная сумма заказа для применения.
• Включён / выключен.
• Автоматические статусы: scheduled (ещё не начался), active (штатное окно), expired, exhausted, disabled.
• Для покупателя disabled маскируется как not_found — факт существования отключённого кода не раскрывается.

Генерация кодов

• Ручное создание одного кода.
• Пакетная генерация по маске: # — цифра 0–9, ? — буква, * — буква или цифра, литералы.
• Исключение путающих при наборе символов: ? не выдаёт O/I/L, * — ещё и 0/1.
• Защита от коллизий, предпросмотр в админке.

Админка (Vue 3 + PrimeVue 4)

• Список промо-кодов с серверной пагинацией, сортировкой и фильтрами.
• Редактор кода с тремя вкладками: основные параметры, правила, статистика.
• Раздел «Аналитика»: KPI и подробный журнал использований с фильтрами.
• Вкладка «Промо-код» в карточке заказа с автопересчётом при изменении состава. Правка блокируется для статусов из ms3promocode.lock_statuses.

Фронтенд

• Сниппет ms3PromoCodeForm с SSR-гидратацией — форма не «мигает» при загрузке страницы.
• Готовый чанк ms3promocode_form, переопределяемый через &tpl.
• Headless JS-API window.ms3PromoCode — apply, remove, validate, current, события.
• Необязательный UI-слой, монтируется по [data-ms3-promocode="form"].
• Автоматический перерасчёт корзины после применения или снятия (с возможностью отключения для AJAX-корзин).
• Папка переопределений assets/components/ms3promocode-overrides/ — замена ассетов (CSS, UI, headless) без правок пакета.
• Системная настройка ms3promocode.frontend_assets_preset (core_ui / core / none) управляет набором подключаемых ассетов — для SPA-страниц или собственной сборки.

Интеграция с MS3

• Подписка на msOnAddToCart, msOnChangeInCart, msOnChangeOptionInCart, msOnRemoveFromCart — пересчёт скидки при любом изменении состава или опций корзины.
• Подписка на msOnCreateOrderProduct, msOnUpdateOrderProduct, msOnRemoveOrderProduct — пересчёт скидки при правке позиций заказа через стандартные процессоры MODX.
• Подписка на msOnCreateOrder — фиксация применения в ms3_promo_code_usages.
• Подписка на msOnChangeOrderStatus — откат применения при переходе в статусы из ms3promocode.cancel_statuses и восстановление при возврате.
• Ручное редактирование заказа в Vue-админке MS3 — через JS-перехватчик fetch (обходное решение для отсутствующих событий, см. MiniShop3#207).
• Запись ms3promocode_auto_remove в msOrderLog при автоматическом снятии кода.

Web API

Метод	Путь	Назначение
POST	/api/v1/promo/apply	Применить код к корзине
POST	/api/v1/promo/remove	Снять применённый код
POST	/api/v1/promo/validate	Проверить код без записи
GET	/api/v1/promo/current	Получить текущий применённый код

Авторизация, CORS и rate limiting наследуются от MS3-роутера.

Manager API

Собственный коннектор для админки с процессорами:

• Mgr/PromoCode/{GetList,Get,Create,Update,Remove,Generate,PreviewMask}.
• Mgr/Order/{ApplyPromo,RemovePromo,GetPromo,Resync}.
• Mgr/Analytics/{GetKpi,GetLog}.
• Вспомогательные для конструктора правил: Mgr/Product/Search, Mgr/Category/Search, Mgr/Vendor/GetList, Mgr/ProductData/GetFields, Mgr/ProductOption/{GetKeys,GetValues}.

Установка

• Phinx-миграции применяются автоматически при установке и обновлении.
• При удалении пакета таблицы остаются — для сохранения истории.
• Анонимные метрики установки (версии PHP, MODX, MS3, БД, OS, web-сервер) один раз отправляются на metrics.modx.pro — для улучшения совместимости. Без персональных данных, домена и IP.

Системные требования

• PHP 8.2+
• MODX Revolution 3.0+
• MiniShop3 1.10+
• pdoTools (для Fenom-чанков фронтенд-формы)
• VueTools (для Vue-админки)