First-Time Buyer Discount — Документация

Дополнение для MODX Revolution 3 и MiniShop3: автоматическая скидка на первый заказ пользователя (0 оплаченных заказов).

Содержание

Документ	Описание
Архитектура	Компоненты, слои, зависимости, диаграммы структуры
Потоки (flows)	Диаграммы последовательности: расчёт корзины, применение скидки
API и события	Сервис FtbDiscountService, события ftbOnBeforeApply/ftbOnApply, системные настройки
Интеграция с MiniShop3	Событие msOnGetCartCost, контракт входа/выхода
Расширение	Подмена сервиса, плагины на событиях, примеры кода

Требования

• MODX Revolution 3.x
• PHP 8.1+
• MiniShop3 (события корзины, модель msOrder, настройка ms3_status_for_stat)

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

Шаг 1: Установка

• Откройте Extras → Installer, найдите ms3FirstTimeBuyerDiscount и установите пакет.
• Убедитесь, что MiniShop3 уже установлен и работает (корзина, заказы, статусы).

Шаг 2: Включение плагина

• Управление → Элементы → Плагины: найдите ms3FirstTimeBuyerDiscount.
• Включите плагин и привяжите его к событию msOnGetCartCost (должно быть выбрано по умолчанию).
• Сохраните. При расчёте стоимости корзины MiniShop3 будет вызывать этот плагин.

Шаг 3: Настройки

• Управление → Настройки: фильтр по области ms3firsttimebuyerdiscount (или поиск по ftb_).
• Задайте:
  • ftb_enabled — включено (да).
  • ftb_discount_type — «Процент» или «Фиксированная сумма».
  • ftb_discount_value — например 10 (10%) или 500 (500 ₽ фикс).

Шаг 4: Проверка

• В MiniShop3 убедитесь, что настройка ms3_status_for_stat содержит ID статусов «оплаченных» заказов (по умолчанию 2,3).
• Авторизуйтесь пользователем без оплаченных заказов, добавьте товар в корзину — в блоке корзины должна отображаться стоимость уже со скидкой.
• Пользователь с хотя бы одним заказом в этих статусах скидку не получает.

Итог: скидка применяется автоматически при расчёте корзины для first-time buyer; менять шаблоны не обязательно — меняется только итоговая сумма.

---

User Stories

Ниже — типичные сценарии использования с точки зрения ролей и целей.

Владелец магазина / Маркетолог

Как	Я хочу	Чтобы
владелец магазина	давать 10% скидку на первый заказ	повысить конверсию новых покупателей
маркетолог	включать и выключать акцию без правки кода	быстро запускать и останавливать кампанию (ftb_enabled)
маркетолог	тестировать процент vs фиксированную скидку	выбрать тип и значение в настройках (ftb_discount_type, ftb_discount_value)
маркетолог	понимать, кому скидка применилась	смотреть логи (категория ftb) или повесить плагин на ftbOnApply для аналитики

Администратор

Как	Я хочу	Чтобы
администратор	один раз настроить скидку	задать тип и значение в Настройках и забыть
администратор	не давать скидку на определённые доставки/оплаты	повесить плагин на ftbOnBeforeApply и выставить returnedValues['apply'] = false по условию
администратор	считать «оплаченными» только нужные статусы	проверить/изменить в MiniShop3 настройку ms3_status_for_stat

Разработчик

Как	Я хочу	Чтобы
разработчик	ограничить скидку по группе пользователей	подменить сервис или наследовать FtbDiscountService и переопределить isEligible (см. Расширение)
разработчик	изменить формулу скидки (порог, минимум суммы)	наследовать FtbDiscountService и переопределить calculateDiscount или подменить cost в ftbOnBeforeApply
разработчик	отправлять факт применения скидки в CRM/аналитику	подписаться на событие ftbOnApply и использовать user_id, discount_amount (см. API)
разработчик	отладить, применилась ли скидка	смотреть лог MODX (категория ftb) или временно логировать в ftbOnApply

Поддержка / Тестировщик

Как	Я хочу	Чтобы
поддержка	проверить, что скидка считается верно	авторизоваться новым пользователем, добавить товар, сравнить сумму в корзине с ручным расчётом (процент/фикс)
поддержка	воспроизвести «скидка не применилась»	проверить: плагин включён на msOnGetCartCost, ftb_enabled = да, у пользователя 0 заказов в статусах ms3_status_for_stat
тестировщик	проверить отмену скидки через событие	написать плагин на ftbOnBeforeApply с returnedValues['apply'] = false и убедиться, что стоимость не меняется

---

Ключевые понятия

• First-Time Buyer — пользователь с нулём заказов в статусах из ms3_status_for_stat.
• Скидка применяется к стоимости корзины в событии msOnGetCartCost; результат возвращается через returnedValues['cost'].
• Расширяемость: сервис в контейнере ms3ftb_discount, события ftbOnBeforeApply и ftbOnApply для отмены, подмены суммы и аналитики.

Версионирование

• Текущая версия пакета: 1.0.0-pl.
• История изменений: core/.../docs/changelog.txt.

Ссылки

• MiniShop3 — документация
• События MiniShop3 (стоимость)