Обновлена документация компонента ms3FirstTimeBuyerDiscount: уточнены условия применения скидки, добавлены новые параметры и улучшены описания методов. Включены изменения для поддержки исключения текущего заказа из подсчёта оплаченных, а также обновлены настройки и интеграция с MiniShop3.

Author: Ibochkarev

docs/components/ms3firsttimebuyerdiscount/api.md

@@ -18,10 +18,11 @@ public function __construct(modX $modx)
 
 #### isEligible
 
-Проверяет, можно ли применить скидку: включена настройка и 0 оплаченных заказов.
+Проверяет право на скидку: настройка включена и найдено 0 оплаченных заказов.
 
-- Для авторизованного пользователя проверка выполняется по `user_id`.
-- Для гостя (`user_id = 0`) проверка выполняется по `email` или `phone` из `draft->getOne('Address')`.
+- Для авторизованных: проверка по `user_id`
+- Для гостей: проверка по `email`/`phone` из `draft -> Address`
+- При наличии `draft` текущий заказ исключается из подсчёта
 
 ```php
 public function isEligible(int $userId, ?object $draft = null): bool
@@ -30,64 +31,70 @@ public function isEligible(int $userId, ?object $draft = null): bool
 | Параметр | Тип | Описание |
 |----------|-----|----------|
 | `userId` | int | ID пользователя |
-| `draft`  | object\|null | Объект черновика заказа (опционально), используется для гостей |
+| `draft`  | object\|null | Черновик заказа (опционально) |
 
 **Возврат:** `true`, если скидку можно применить, иначе `false`.
 
 ---
 
 #### getPaidOrdersCount
 
-Количество оплаченных заказов пользователя в статусах из настройки MiniShop3 `ms3_status_for_stat`.
+Количество оплаченных заказов пользователя в статусах из `ms3_status_for_stat`.
 
 ```php
-public function getPaidOrdersCount(int $userId): int
+public function getPaidOrdersCount(int $userId, int $excludeOrderId = 0): int
 ```
 
 | Параметр | Тип | Описание |
 |----------|-----|----------|
 | `userId` | int | ID пользователя |
+| `excludeOrderId` | int | ID заказа, который нужно исключить из подсчёта (`0` — не исключать) |
 
 **Возврат:** число заказов (0 и больше).
 
 ---
 
 #### getGuestContactFromDraft
 
-Извлекает контакты гостя (email/phone) из `draft`.
+Извлекает контакты гостя из `draft -> Address` и нормализует значения.
 
 ```php
 public function getGuestContactFromDraft(?object $draft): array
 ```
 
 | Параметр | Тип | Описание |
 |----------|-----|----------|
-| `draft` | object\|null | Черновик заказа (ожидается связь `Address`) |
+| `draft` | object\|null | Черновик заказа |
 
 **Возврат:** массив вида `['email' => string, 'phone' => string]`.
 
 ---
 
 #### getPaidOrdersCountByContact
 
-Количество оплаченных заказов по контактам гостя (совпадение по `Address.email` или `Address.phone`).
+Количество оплаченных заказов гостя по email/phone.
 
 ```php
-public function getPaidOrdersCountByContact(string $email, string $phone): int
+public function getPaidOrdersCountByContact(string $email, string $phone, int $excludeOrderId = 0): int
 ```
 
 | Параметр | Тип | Описание |
 |----------|-----|----------|
 | `email` | string | Email гостя |
 | `phone` | string | Телефон гостя |
+| `excludeOrderId` | int | ID заказа, который нужно исключить из подсчёта (`0` — не исключать) |
+
+Сравнение:
+- `email` — в lower-case
+- `phone` — по нормализованным цифрам (для телефона используется tail-10 сопоставление через `LIKE`)
 
 **Возврат:** число заказов (0 и больше).
 
 ---
 
 #### calculateDiscount
 
-Вычисляет стоимость после скидки (процент или фиксированная сумма).
+Вычисляет стоимость после скидки (процент или фикс).
 
 ```php
 public function calculateDiscount(float $cost, string $type, float $value): float
@@ -96,85 +103,82 @@ public function calculateDiscount(float $cost, string $type, float $value): floa
 | Параметр | Тип | Описание |
 |----------|-----|----------|
 | `cost`   | float | Исходная сумма |
-| `type`   | string | `percent` или `fixed` (сравнение без учёта регистра) |
+| `type`   | string | `percent` или `fixed` |
 | `value`  | float | Процент (0–100) или фиксированная сумма |
 
-**Возврат:** новая сумма (`fixed`: `max(0, cost - max(0, value))`; `percent`: диапазон 0–100%).
+**Возврат:** новая сумма (`fixed`: `max(0, cost - max(0, value))`; `percent`: c ограничением 0–100%).
 
 ---
 
 #### apply
 
-Полный цикл: проверка права → `ftbOnBeforeApply` → расчёт → `ftbOnApply`. Используется плагином из `msOnGetCartCost`.
+Полный цикл: проверка права → `ftbOnBeforeApply` → расчёт → `ftbOnApply`.
 
 ```php
 public function apply(array $scriptProperties): ?float
 ```
 
-**Вход (scriptProperties):** массив из события `msOnGetCartCost`:
+| Ключ | Тип | Описание |
+|------|-----|----------|
+| `cost` | float | Текущая стоимость корзины |
+| `cart` | mixed | Объект/данные корзины MiniShop3 |
+| `draft` | object\|null | Черновик заказа |
 
-| Ключ   | Тип    | Описание |
-|--------|--------|----------|
-| `cost` | float  | Текущая стоимость корзины |
-| `cart` | mixed  | Данные корзины (зависит от MS3) |
-| `draft`| object\|null | Черновик заказа (если есть) |
+Дополнительно учитывается настройка `ftb_allow_combination`:
+- если `false` и в корзине уже есть скидка (`total_discount > 0`), FTB-скидка не применяется
 
-**Возврат:** новая стоимость (`float`) при успешном применении скидки, иначе `null`.
+**Возврат:** новая стоимость (`float`) или `null`.
 
 ---
 
 ## События MODX
 
 ### ftbOnBeforeApply
 
-Вызывается до расчёта скидки. Плагины могут отменить применение или подменить базовую сумму.
-
-**Параметры:**
-
-| Ключ       | Тип    | Описание |
-|------------|--------|----------|
-| `user_id`  | int    | ID пользователя |
-| `cost`     | float  | Текущая стоимость |
-| `draft`    | object\|null | Черновик заказа |
-| `cart`     | mixed  | Корзина |
-| `settings` | array  | Текущие настройки (`ftb_enabled`, `ftb_discount_type`, `ftb_discount_value`) |
+Вызывается до расчёта скидки. Позволяет отменить применение или подменить базовую сумму.
 
-**Возвращаемые значения (returnedValues):**
+| Ключ | Тип | Описание |
+|------|-----|----------|
+| `user_id` | int | ID пользователя |
+| `cost` | float | Текущая стоимость |
+| `draft` | object\|null | Черновик заказа |
+| `cart` | mixed | Корзина |
+| `settings` | array | `ftb_enabled`, `ftb_discount_type`, `ftb_discount_value`, `ftb_allow_combination` |
 
-| Ключ   | Тип   | Описание |
-|--------|-------|----------|
-| `apply`| bool  | `false` — отменить применение скидки |
-| `cost` | float | Подменить сумму, к которой применяется скидка |
+`returnedValues`:
 
-Если `apply === false`, сервис возвращает `null`. Если задан `cost`, он используется вместо исходного `cost` для расчёта.
+| Ключ | Тип | Описание |
+|------|-----|----------|
+| `apply` | bool | `false` — отменить применение скидки |
+| `cost` | float | Подменить сумму для расчёта скидки |
 
 ---
 
 ### ftbOnApply
 
-Уведомление после успешного применения скидки (для логирования, аналитики).
+Вызывается после успешного применения скидки.
 
-**Параметры:**
-
-| Ключ             | Тип    | Описание |
-|------------------|--------|----------|
-| `user_id`        | int    | ID пользователя |
-| `cost_before`    | float  | Стоимость до скидки |
-| `cost_after`     | float  | Стоимость после скидки |
-| `discount_amount`| float  | Размер скидки |
-| `draft`          | object\|null | Черновик заказа |
+| Ключ | Тип | Описание |
+|------|-----|----------|
+| `user_id` | int | ID пользователя |
+| `cost_before` | float | Стоимость до скидки |
+| `cost_after` | float | Стоимость после скидки |
+| `discount_amount` | float | Размер скидки |
+| `draft` | object\|null | Черновик заказа |
 
 ---
 
 ## Системные настройки
 
-Префикс в конфиге: `ms3firsttimebuyerdiscount_` (например, `ms3firsttimebuyerdiscount_ftb_enabled`).
+Префикс: `ms3firsttimebuyerdiscount_`.
 
 | Ключ | xtype | По умолчанию | Описание |
-|------|--------|--------------|----------|
-| `ftb_enabled` | combo-boolean | true | Включить скидку для первых покупок |
-| `ftb_discount_type` | textfield | percent | Тип: `percent` (процент) или `fixed` (фиксированная сумма). Ввод вручную; сравнение без учёта регистра. |
-| `ftb_discount_value` | number | 10 | Значение: процент (0–100) или сумма в валюте |
-| `ftb_allow_combination` | combo-boolean | true | Зарезервировано на будущее (совмещение с другими скидками) |
-
-Получение в коде: `$modx->getOption('ms3firsttimebuyerdiscount_ftb_enabled', null, true)`.
+|------|-------|--------------|----------|
+| `ftb_enabled` | combo-boolean | true | Включить скидку для first-time buyer |
+| `ftb_discount_type` | textfield | percent | Тип: `percent` или `fixed` (регистр не важен) |
+| `ftb_discount_value` | number | 10 | Значение скидки: процент (0–100) или сумма |
+| `ftb_allow_combination` | combo-boolean | true | Разрешить совмещение с уже применёнными скидками корзины |
+
+Связанные настройки MiniShop3:
+- `ms3_status_for_stat` — статусы оплаченных заказов
+- `ms3_status_new` — добавляется в список учитываемых статусов как маркер первого заказа

docs/components/ms3firsttimebuyerdiscount/extension.md

@@ -18,16 +18,16 @@ $modx->services->add('ms3ftb_discount', function () use ($modx) {
 });
 ```
 
-Ваша реализация должна предоставлять метод `apply(array $scriptProperties): ?float` (и при необходимости остальные публичные методы, если вы вызываете их из своего кода).
+Реализация должна предоставлять минимум метод `apply(array $scriptProperties): ?float`; остальные публичные методы — по необходимости при вызове из своего кода.
 
 ## Наследование FtbDiscountService
 
 Сервис спроектирован так, чтобы ключевую логику можно было переопределить в наследнике:
 
 - **isEligible(int $userId, ?object $draft): bool** — изменить условия права на скидку (например, по группе пользователя или по полю черновика).
-- **getPaidOrdersCount(int $userId): int** — изменить способ подсчёта оплаченных заказов.
-- **getGuestContactFromDraft(?object $draft): array** — изменить извлечение email/phone гостя из черновика.
-- **getPaidOrdersCountByContact(string $email, string $phone): int** — изменить подсчёт оплаченных заказов для гостей по контактам.
+- **getPaidOrdersCount(int $userId, int $excludeOrderId = 0): int** — изменить способ подсчёта оплаченных заказов (с исключением текущего заказа).
+- **getGuestContactFromDraft(?object $draft): array** — изменить извлечение/нормализацию email/phone гостя из черновика.
+- **getPaidOrdersCountByContact(string $email, string $phone, int $excludeOrderId = 0): int** — изменить подсчёт оплаченных заказов для гостей.
 - **calculateDiscount(float $cost, string $type, float $value): float** — изменить формулу (например, минимум суммы заказа).
 
 Пример: скидка только для группы «Партнёр»:
@@ -44,7 +44,7 @@ class PartnerFtbService extends FtbDiscountService
         if (!parent::isEligible($userId, $draft)) {
             return false;
         }
-        $user = $this->modx->getObject(\modUser::class, $userId);
+        $user = $this->modx->getObject(\MODX\Revolution\modUser::class, $userId);
         if (!$user) {
             return false;
         }
@@ -96,6 +96,10 @@ $modx->log(modX::LOG_LEVEL_INFO, sprintf(
 // или отправить в CRM/аналитику по $params['user_id'], $params['discount_amount']
 ```
 
+## Константы и настройки
+
+В сервисе используются внутренние константы типов скидки: `percent`, `fixed`. Ключи настроек: `ftb_enabled`, `ftb_discount_type`, `ftb_discount_value`, `ftb_allow_combination`. Полный список и типы см. в [API](api#системные-настройки).
+
 ## Логирование
 
 Плагин пишет в лог MODX при успешном применении скидки:

docs/components/ms3firsttimebuyerdiscount/index.md

@@ -14,17 +14,16 @@ items: [
 ---
 # ms3FirstTimeBuyerDiscount
 
-Компонент для [MiniShop3](/components/minishop3/): автоматическая скидка на первый заказ. При нуле оплаченных заказов к стоимости корзины применяется скидка (процент или фиксированная сумма). Для авторизованных учитывается `user_id`, для гостей — `email`/`phone` из `Address` черновика заказа. Оплаченные заказы определяются по настройке MiniShop3 `ms3_status_for_stat`.
-
-**Именование:** для пользователя — **ms3FirstTimeBuyerDiscount**; в коде (папки, namespace, плагины) — **ms3firsttimebuyerdiscount**.
+Компонент для [MiniShop3](/components/minishop3/): автоматическая скидка на первый заказ. При нуле оплаченных заказов к стоимости корзины применяется скидка (процент или фиксированная сумма). Для авторизованных учитывается `user_id`, для гостей — `email`/`phone` из `Address` черновика заказа. Статусы оплаченных заказов берутся из `ms3_status_for_stat` с учётом `ms3_status_new`.
 
 ## Возможности
 
 - **Скидка на первый заказ** — применяется при расчёте корзины (событие `msOnGetCartCost`), без правки шаблонов
 - **Тип скидки** — процент от суммы или фиксированная сумма в валюте магазина
 - **Определение «первого» покупателя** — для пользователя по `user_id`, для гостя по `email`/`phone`, с учётом статусов из `ms3_status_for_stat`
+- **Контроль комбинации скидок** — настройка `ftb_allow_combination` позволяет запретить применение FTB, если в корзине уже есть скидка
 - **События** — `ftbOnBeforeApply` (отмена или подмена суммы), `ftbOnApply` (логирование, аналитика)
-- **Интеграция с фронтендом** — в ответ `getCost()` добавляется `ftb_discount` (`amount`, `message`) для показа уведомления
+- **Плашка на странице заказа** — сниппет `ms3ftbDiscountBanner` + frontend-логика проверки eligibility по email/phone
 - **Расширяемость** — подмена сервиса в контейнере `ms3ftb_discount`, наследование `FtbDiscountService`
 
 ## Системные требования
@@ -51,14 +50,14 @@ items: [
 
 ### После установки
 
-Включите плагин **ms3FirstTimeBuyerDiscount** и привяжите его к событию **msOnGetCartCost**. Задайте настройки скидки в **Настройки → ms3firsttimebuyerdiscount**.
+Задайте настройки скидки в **Настройки → ms3firsttimebuyerdiscount**.
 
 Подробнее: [Быстрый старт](quick-start).
 
 ## Термины
 
 | Термин | Описание |
 |--------|----------|
-| **First-Time Buyer** | Авторизованный пользователь или гость с нулём заказов в статусах из настройки MiniShop3 `ms3_status_for_stat` |
+| **First-Time Buyer** | Авторизованный пользователь или гость с нулём заказов в статусах из `ms3_status_for_stat` (с учётом `ms3_status_new`) |
 | **Оплаченный заказ** | Заказ в одном из статусов, перечисленных в `ms3_status_for_stat` (например, «Оплачен», «Доставлен») |
-| **Скидка** | Сумма или процент, вычитаемые из стоимости корзины при расчёте в `msOnGetCartCost`; дополнительно в API-ответ добавляется `ftb_discount` |
+| **Скидка** | Сумма или процент, вычитаемые из стоимости корзины при расчёте в `msOnGetCartCost` |