ms3PromoCode

Промо-коды для интернет-магазинов на MiniShop3 — гибкие правила применения, ручная и пакетная генерация, современная Vue-админка, готовая фронтенд-форма для покупателя и корректный учёт скидки прямо в позициях заказа.

Возможности

• Два типа скидки — процент или фиксированная сумма.
• Две области применения — вся корзина или только подпадающие под правила позиции.
• Учёт скидки в позициях — цена со скидкой записывается в msOrderProduct.price. Чек 54-ФЗ, email-уведомления и личный кабинет показывают корректные суммы без правок шаблонов.
• Точная сумма скидки — копейки от пропорционального распределения автоматически компенсируются.
• Богатые правила таргетинга — товары, категории, бренды, универсальный фильтр по любому полю карточки товара с операторами (=, !=, <, IN, BETWEEN, LIKE, CONTAINS и др.), фильтр по опциям товара.
• Жизненный цикл — старт/конец действия, лимит применений, минимальная сумма заказа, on/off. Автоматические статусы (scheduled, expired, exhausted, disabled).
• Маскирующая безопасность — отключённый код для покупателя выглядит как «не найден», существование кода не раскрывается.
• Генерация по маске — SALE-####-??, безошибочный набор символов, защита от дублирования, превью.
• Современная Vue 3 админка — DataTable с фильтрами, редактор кода, аналитика, вкладка в карточке заказа.
• SSR-форма для покупателя — никакого «мигания» при загрузке.
• Headless JS API — для собственных интеграций (SPA, кастомные темы).
• Override-папка — переопределяй любой ассет без правок пакета.

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

Требование	Версия
MODX Revolution	3.0+
MiniShop3	1.10+
PHP	8.2+
MySQL / MariaDB	8.0+ / 10.3+

Зависимости

• MiniShop3 — корневая корзинно-заказная система.
• pdoTools — для рендера фронтенд-чанка через Fenom.
• VueTools — для админ-панели.

Установка

Через менеджер пакетов

1. Перейдите в Extras → Installer.
2. Нажмите Download Extras, найдите ms3PromoCode.
3. Нажмите Download и затем Install.

После установки:

1. В дереве админ-меню появится раздел Промо-коды с двумя вкладками: «Управление кодами» и «Аналитика».
2. Phinx-миграции применятся автоматически — таблицы ms3_promo_codes и ms3_promo_code_usages будут созданы.
3. Опционально настройте системные настройки — см. Системные настройки.

Быстрый старт

{* В шаблоне корзины *}
{'!ms3PromoCodeForm' | snippet}

Готово — покупатель видит форму ввода промо-кода, скидка применяется и распределяется по позициям, при оформлении заказа применение фиксируется в учётной таблице.

Подробнее: Быстрый старт →

Архитектура

┌─────────────────────────────────────────────────────────────┐
│                       Покупатель                            │
├──────────────────────┬──────────────────────────────────────┤
│   SSR-сниппет        │       Headless JS-API                │
│ (ms3PromoCodeForm)   │      (window.ms3PromoCode)           │
├──────────────────────┴──────────────────────────────────────┤
│                       Web API                               │
│       /api/v1/promo/{apply,remove,validate,current}         │
├─────────────────────────────────────────────────────────────┤
│                       Сервисы                               │
│   ApplicationService → ValidationService → DiscountCalc.    │
│              → RuleEngine → UsageTracker                    │
├─────────────────────────────────────────────────────────────┤
│                  Плагин ms3PromoCode                        │
│  msOnAddToCart / msOnChangeInCart / msOnRemoveFromCart      │
│  msOnCreateOrder / msOnChangeOrderStatus                    │
│  msOnManagerCustomCssJs / OnLoadWebDocument                 │
├─────────────────────────────────────────────────────────────┤
│                      База данных                            │
│      ms3_promo_codes  │  ms3_promo_code_usages              │
└─────────────────────────────────────────────────────────────┘

Учёт скидки в позициях

В отличие от классических компонентов, ms3PromoCode не выводит скидку отдельной строкой в итогах. Вместо этого скидка распределяется по подпадающим позициям и записывается напрямую в msOrderProduct.price (с сохранением оригинальной цены в properties.ms3promocode.original_price).

Что это даёт:

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

Подробнее: Интеграция с MiniShop3 →