# Korzilla (старая версия, kzla): программа лояльности в интернет-магазине — ТЗ для разработчика

Документ для программиста, который встраивает платформу лояльности в магазин старой Korzilla (kzla: собственное ядро
`Kzla\` после Netcat, PHP 8.3, общая база, сайты по `Catalogue_ID`). Здесь — что магазин делает на каждом шаге,
какие запросы к платформе, куда это ложится в коде kzla и как принять работу. Квадратные скобки — то, что выдаёт или
решает владелец продукта.

## 1. Что получит покупатель и магазин

- **Покупатель** вступает в программу в личном кабинете или при оформлении заказа. Телефон он подтверждает кодом
  из SMS, принимает правила программы и согласие на обработку данных.
- **В корзине** покупатель видит свои баллы и «Оплатить баллами»: сколько можно списать, скидка уменьшает сумму
  заказа.
- **За заказ** начисляются баллы. Они становятся доступны после срока возврата, который задают правила программы.
- **Если заказ отменён**, списанные баллы возвращаются, а начисленные снимаются.
- **При возврате** части товаров — так же, пропорционально возвращённому.
- **В личном кабинете** раздел «Бонусы»: баланс, история баллов, покупки.
- **Владелец магазина** ведёт программу в кабинете лояльности платформы: правила, акции, отчёты, рассылки.

## 2. Как устроено

```
Сайт kzla (магазин)  ──(ключ кассы lk_…)──►  Платформа: Runtime API /api/v1     (покупатели, чеки, баллы)
Korzilla (партнёр)   ──(клиент OAuth lc_…)─►  Платформа: Management API         (заводит магазины)
```

- **Каждый магазин** kzla — мерчант платформы. У него программа лояльности, точка «Интернет-магазин» и касса вида
  `ecommerce`. Ключ этой кассы хранится в настройках сайта, через него идут все запросы магазина.
- **Korzilla** — партнёр платформы. Его клиент OAuth заводит магазины через Management API. На пилоте магазин
  заводится вручную, а разработчик получает готовый ключ кассы (раздел 4).
- **Покупатель магазина** — участник программы. Пользователь kzla (`User`) связан с участником по идентификатору
  участника, который магазин хранит у себя.

## 3. Что выдаётся разработчику

| Что | Где |
|---|---|
| Адрес платформы | песочница `https://sandbox.rebonus.ru`: тестовые данные, настоящие SMS не уходят |
| Ключ кассы тестового магазина | передаёт владелец; в песочнице формат `lk_test_…` |
| Кабинет тестового магазина | `https://sandbox.rebonus.ru/merchant`: вход по e-mail, который назначил владелец, пароль — «Забыли пароль?» |
| Быстрый старт в песочнице | `https://rebonus.ru/docs/quickstart/`: вступление с кодом, расчёт и проведение чека, баланс |
| Описание Runtime API | `https://rebonus.ru/docs/api/runtime/`: справочник и `openapi.json` для скачивания (в репозитории — `docs/api/runtime-v1.yaml`) |
| Описание Management API | `https://rebonus.ru/docs/api/management/` — нужно для автоматического подключения магазинов |
| PHP SDK | архив `rebonus-php-sdk.zip` передаёт владелец: в Packagist SDK пока нет (в репозитории — `sdk/php`). PHP 8.2+, расширения curl и json, без Composer-зависимостей. Описание — `https://rebonus.ru/docs/sdk/php/` |
| Повторы, ключи идемпотентности, коды ошибок | `https://rebonus.ru/docs/sdk/php/` и `https://rebonus.ru/docs/errors/` |
| Песочница: тестовые телефоны и код | `https://rebonus.ru/docs/sandbox/` |

**SDK в kzla.** Скопировать папку `src` из архива SDK в `bc/modules/Korzilla/Loyalty/sdk/` и подключить автозагрузку
PSR-4 префикса `Loyal\Sdk\` от этой папки. Клиент магазина:

```php
use Loyal\Sdk\ClientOptions;
use Loyal\Sdk\RequestOptions;
use Loyal\Sdk\RuntimeClient;

$loyalty = RuntimeClient::create($setting['loyaltyKey'], new ClientOptions('https://sandbox.rebonus.ru', timeout: 10.0, appInfo: 'kzla'));
```

Методы клиента повторяют операции API: `listConsentDocuments`, `sendRegistrationCode`, `verifyCode`, `registerMember`,
`lookupMember`, `calculateReceipt`, `registerReceipt`, `cancelReceipt`, `returnReceiptLines`, `getBalance`,
`getPointsHistory`, `listMemberReceipts`. Тела запросов — массивы по схемам OpenAPI, ответы — массивы. Ошибка — исключение
SDK с кодом ошибки API (`problemCode()`).

## 4. Подключение магазина

**Пилот.** Владелец продукта заводит магазин в платформе и передаёт ключ кассы. Ключ показывается один раз.

**В админке kzla** появляется раздел «Программа лояльности»:

- манифест `bc/modules/bitcat/manifestes/loyalty.json` и пункт в `menu_manifest.json` с правом доступа;
- поля:
  - «Программа лояльности включена» (`loyaltyEnabled`);
  - «Ключ кассы» (`loyaltyKey`);
  - «Ссылка на кабинет лояльности» — только для показа.

**Ключ — секрет.** `settings.ini` копируется в `settings_back/` при каждом сохранении, поэтому ключ хранится в отдельном
файле вне этих копий (например, `a/{login}/loyalty.key`, закрытом в `.htaccess`) или зашифрованным. В интерфейсе
показывается только маска. В логах ключа нет.

**Позже: автоматически.** Кнопка суперадмина на вкладке «Система лояльности» (сейчас заготовка `discount_system.json`)
заводит магазин через Management API — порядок вызовов в примере `https://rebonus.ru/docs/sdk/php/quickstart/`
(`examples/quickstart.php` в архиве SDK):

1. мерчант (`external_id` = логин сайта);
2. программа и тип баллов;
3. документы согласий (тексты — `[от юриста]`);
4. правила, их публикация;
5. точка и касса вида `ecommerce`;
6. ключ кассы со скоупами `receipts`, `members`, `balances`.

Клиент OAuth Korzilla хранится в конфигурации ядра, не на сайтах.

## 5. Вступление в программу

**Где:**

- в `/profile/` — блок «Бонусы» с кнопкой «Вступить в программу»;
- при оформлении заказа — галочка «Копить баллы» (по умолчанию снята).

**Шаги:**

1. **Документы.** `listConsentDocuments()` даёт действующие документы программы: правила (`program_rules`), согласие
   на обработку данных (`personal_data`), согласия на рекламу (`marketing_sms`, `marketing_email`).
   - Показать заголовки (`title`), а полный текст (`body`) — по нажатию, без сокращений. Платформа запишет согласие
     к той версии (`version`), которая сейчас действует.
   - Правила и согласие на обработку — обязательные галочки.
   - Реклама — отдельные галочки, по умолчанию сняты.
   - Это документы программы, не политика сайта (`reqpolitika()`): нужны обе пары галочек.
2. **Код подтверждения.** `sendRegistrationCode(['phone' => '+7…'])` отправляет код на телефон через SMS-аккаунт
   магазина, подключённый в кабинете лояльности (`[аккаунт SMSC магазина]`). Ответ — `verification_id`.
3. **Проверка кода.** Покупатель вводит код: `verifyCode($verificationId, ['code' => '…'])`.
4. **Регистрация.** `registerMember` с телефоном, кодом и согласиями, ключ идемпотентности — `kzla:{login}:join:{User_ID}`:

   ```php
   $member = $loyalty->registerMember([
       'phone' => '+79161234567',
       'verification_id' => $verificationId,
       'consents' => ['program_rules', 'personal_data'],   // + 'marketing_sms' и т.п., если отмечены
       'first_name' => $user['ForumName'] ?? null,
       'external_id' => (string) $userId,                  // пользователь kzla
   ], new RequestOptions(idempotencyKey: "kzla:{$login}:join:{$userId}"));
   ```

5. **Связь.** Сохранить `$member['id']` у пользователя: новая колонка `User.loyaltyMemberId` (миграция
   `db/migrations/NNNN_*.sql`). У участника один пользователь kzla: если он уже был связан с другим пользователем, новая
   связь после кода снимает старую — номером владеет тот, кто подтвердил код.

**Отказы:**

| Ошибка | Что делать |
|---|---|
| `member_already_exists` (409) — телефон уже в программе, например вступал на кассе | найти его: `lookupMember(['phone' => …])` и связать с пользователем — после подтверждённого кода этого телефона |
| `invalid_verification_code`, `verification_expired` | «Неверный код» / «Код устарел, запросите новый» |
| `mobile_phone_required` (422) — номер не мобильный российский | попросить мобильный номер |
| `code_delivery_unavailable`, `code_delivery_failed` (409) — у магазина нет SMS-аккаунта или он отказал | «Вступление временно недоступно», сообщить владельцу магазина |
| `verification_throttled`, `verification_suspended` (429) | «Слишком много кодов, попробуйте позже» |

Телефон в kzla сейчас не подтверждается (в заказе он вводится свободно), поэтому связывать покупателя с участником
можно только после кода платформы. Без кода чужой номер получил бы чужие баллы.

## 6. Корзина: расчёт и «Оплатить баллами»

Только для вошедшего покупателя со связанным участником (`User.loyaltyMemberId`).

**Расчёт** (`calculateReceipt`) ничего не меняет, его можно вызывать сколько угодно раз:

```php
$calc = $loyalty->calculateReceipt([
    'purchased_at' => gmdate('Y-m-d\TH:i:s\Z'),
    'member' => ['id' => $memberId],
    'lines' => $lines,              // строки корзины, см. ниже
    'redeem_points' => $points,     // сколько баллов хочет списать покупатель; 0 — только посмотреть
]);
```

**Строки:** по одной на позицию корзины.

| Поле | Что | Пример |
|---|---|---|
| `id` | номер строки в заказе, строкой | `"1"` |
| `sku` | артикул (`art`) или id товара | `"AN-12"` |
| `name` | название | `"Анкер 12 мм"` |
| `quantity` | количество в тысячных | 3 шт. → `3000` |
| `amount` | сумма строки в копейках после скидок магазина (`sum`) | 4 500,50 ₽ → `450050` |

Доставка в строки не входит.

**Ответ:**

- `max_redeemable_points` — сколько можно списать (лимит программы);
- `redeemed_money` — скидка в копейках;
- `payable` — к оплате в копейках;
- `points_earned` — сколько начислится;
- `lines[]` — по каждой строке: `payable`, `discount`, `redeemed_money`.

**Интерфейс корзины:**

- «У вас N баллов, можно списать до M» и поле или переключатель «Оплатить баллами»;
- после выбора — новый расчёт с `redeem_points`;
- скидку записать в сессию корзины: `discont` и цены строк по `lines[].payable`.

**Итоги** в kzla считаются в нескольких местах: `template/class/2005/2006/FormPrefix.html`, `Class2005::getCart()` и
`getItems()`, `Model/Order.php::setTotalSum()`, классы доставки. Скидка баллами должна учитываться во всех, на сервере,
и не пропадать при пересинхронизации цен `getItems()`.

**Фискальный чек.** Платёжные системы строят строки чека из `price` и `sum` позиций, а списывают `totaldelsum`.
Поэтому скидку баллами нужно разнести по строкам: цена строки = `lines[].payable / quantity`. Иначе сумма чека не
совпадёт с суммой оплаты.

## 7. Оформление заказа

В `template/class/2005/AddActionTemplate.html` после записи `Message2005` и до блока оплаты (`$servisePayment`)
провести чек в платформе сразу:

```php
$receipt = $loyalty->registerReceipt([
    'number' => (string) $orderId,                  // Message_ID заказа
    'business_date' => date('Y-m-d'),
    'purchased_at' => gmdate('Y-m-d\TH:i:s\Z'),
    'member' => ['id' => $memberId],                // или ['phone' => …] для гостя, только без списания
    'lines' => $lines,                              // как в расчёте
    'redeem_points' => $redeemPoints,               // 0, если не списывает
    'confirm' => true,
], new RequestOptions(idempotencyKey: "kzla:{$login}:order:{$orderId}"));
```

- **Что сохранить.** `$receipt['id']` — в заказ: новая колонка `Message2005.loyaltyReceiptId`. Списанные и
  начисленные баллы (`redeemed_points`, `points_earned`) — в заказ, для письма и админки.
- **Почему проводить сразу.** Резерв без проведения живёт 30 минут, а оплата при получении приходит через дни. Сразу
  проведённый чек проще: баллы списаны, начисленные ждут срока, а отмена заказа аннулирует чек (раздел 8). Не нужно
  ловить «оплачено» во всех местах, где kzla его пишет (`updateOrder`, `updateStatusOplaty`, `orderWasPayd`, Uniteller,
  админка, 1С).
- **Гость или покупатель без участника.** Если телефон заказа есть в программе, начислить по `['phone' => …]` без
  списания. Иначе без чека.
- **Платформа не ответила.** SDK сам повторяет с тем же ключом.
  - Не вышло — заказ оформляется без списания, а в журнал магазина пишется «чек не проведён».
  - Задача по расписанию (`bc/modules/Korzilla/Cron/`) повторяет `registerReceipt` с тем же ключом для заказов без
    `loyaltyReceiptId`, но с отметкой «нужен чек». Повтор с тем же ключом и телом не создаст второй чек.
- **Расчёт изменился** (баллы потрачены на другом заказе, правила сменились). Ответ — ошибка, например
  `insufficient_points`. Пересчитать, показать покупателю новую сумму и не оформлять заказ молча с другой скидкой.
- **Подтверждение списания.** По умолчанию (`redemption_confirmation: weak_identifiers`) правила программы требуют
  кода, если участник найден по телефону или карте. Касса магазина — вида «Интернет-магазин» (`ecommerce`), и
  покупателя, который вошёл в аккаунт, она называет по `id` участника. Аккаунт связан с участником после кода при
  вступлении, поэтому кода при оплате баллами не нужно (с 2026-11-20, ADR-0009). Ответ `redemption_confirmation_required`
  значит, что в правилах стоит `always`: тогда перед оформлением — `sendRedemptionCode`, ввод кода и
  `redemption_confirmation` в запросе.
- **Участник объединён с другим** (`member_merged`, в ответе `survivor_id`). Сохранить у пользователя `survivor_id` и
  повторить.

## 8. Отмена заказа

Когда заказ становится «Отменён» (`ShopOrderStatus` 6) или оплата «Отменён» (`statusOplaty` 3), вызвать:

```php
$loyalty->cancelReceipt($order['loyaltyReceiptId'], new RequestOptions(idempotencyKey: "kzla:{$login}:cancel:{$orderId}"));
```

Чек аннулируется: списанные баллы вернутся, начисленные снимутся.

**Где ловить.** Статус меняют в нескольких местах:

- хук `orderStatusChangeAfter($id, $new, $old)` — только смена статуса в админке (`adminorders::shopOrderStatus`);
- без хуков: `statusPayment`, обмен с 1С (`1CExport/1c_exchange.php`), cron Frontpad, отмена YooKassa.

Нужна одна функция `loyaltyOrderCancelled($orderId)`, которую вызывают все эти места. Плюс задача по расписанию:
отменённые заказы с проведённым и не аннулированным чеком → `cancelReceipt`.

**Повтор безопасен.** Повтор с тем же ключом отвечает тем же аннулированным чеком. Чек с возвратами не
аннулируется (`receipt_state_conflict`): тогда вернуть оставшиеся строки возвратом (раздел 9).

## 9. Возврат

Когда заказ становится «Возврат» (`ShopOrderStatus` 7) или админ возвращает часть товаров:

```php
$loyalty->returnReceiptLines($order['loyaltyReceiptId'], [
    'number' => "R-{$orderId}",                 // номер возврата; повтор с ним вернёт тот же возврат
    'business_date' => date('Y-m-d'),
    'returned_at' => gmdate('Y-m-d\TH:i:s\Z'),
    'lines' => [['id' => '1', 'quantity' => 1000]],   // строки и количество в тысячных; весь заказ — все строки
], new RequestOptions(idempotencyKey: "kzla:{$login}:return:{$orderId}:1"));
```

- Возврат возвращает списанные баллы и снимает начисленные пропорционально.
- Второй частичный возврат того же заказа — с новым номером (`R-{$orderId}-2`) и ключом.

## 10. Личный кабинет: «Бонусы»

В `/profile/` (`template/class/sys/RecordTemplateFull.html`) для связанного участника:

- баланс — `getBalance($memberId)`:
  - `available` — на счёте;
  - `spendable` — можно потратить;
  - `pending` — ещё не стали доступны;
  - `next_expiration` — ближайшее сгорание: сколько и когда;
- история — `getPointsHistory($memberId, limit: 20)`, дальше по `next_cursor`;
- покупки с баллами — `listMemberReceipts($memberId)`;
- согласия на рекламу пока меняет мерчант в кабинете лояльности. Ссылку «Мои данные и рассылки» можно вести на
  кабинет покупателя программы, если владелец его откроет (`[адрес кабинета покупателя]`).

Баланс в шапке сайта кешировать не дольше минуты и не показывать гостям.

## 11. Ошибки, повторы, данные

- **Повторы.** SDK повторяет запрос при обрыве связи, 502–504 и 429 — с тем же ключом идемпотентности, с паузой. Ключи
  — детерминированные, как в примерах: повтор задачи по расписанию через час с тем же ключом и телом не создаст
  дубль.
  - Тот же ключ с другим телом — 422 `idempotency_key_reused`: значит, заказ изменился, нужен новый ключ.
- **Ошибки.** Все ошибки API — `application/problem+json` с постоянным `code`. Обрабатывать по коду, не по тексту.
  Полный список — `https://rebonus.ru/docs/errors/`, константы — `Loyal\Sdk\Generated\ProblemCode`.
- **Таймаут.** 10 секунд на запрос. Корзина и оформление не должны висеть дольше: не ответила платформа —
  оформить без баллов (раздел 7).
- **Персональные данные:**
  - телефоны, почта, коды, ключ — не в логи. Логи kzla лежат в открытых папках сайта (`a/{login}/*.log`,
    `PaymentMethod/log*/`), поэтому журнал лояльности хранится вне веб-корня или закрыт в `.htaccess`;
  - в журнал — только номер заказа, id чека и код ошибки.
- **Магазин в запросе.** Запросы с ключом кассы сами относятся к своему магазину. Для приёма вебхуков (если
  понадобятся) адрес должен явно называть сайт: `Catalogue::get_by_host_name` при неизвестном хосте возвращает первый
  сайт.
- **Кодировка.** Файлы kzla в CP1251 править только через PHP `str_replace` (см. CLAUDE.md kzla). Тела запросов к
  платформе — UTF-8.

## 12. Приёмка

На тестовом магазине в песочнице `https://sandbox.rebonus.ru`:
- телефоны участников — `+7 900 000-00-00 … +7 900 000-99-99`, код подтверждения всегда `000000`;
- участники, чеки и баллы видны в кабинете тестового магазина;
- начисленные баллы становятся доступны через день. Чтобы проверить списание сразу, начислите баллы вручную в
  карточке участника.

1. **Вступление.** Покупатель вступает в программу в `/profile/` с кодом. В кабинете лояльности появился участник с
   двумя согласиями, а у пользователя kzla — `loyaltyMemberId`.
2. **Второй пользователь с тем же телефоном** вступает с кодом — связывается с тем же участником, новый не создаётся,
   а связь у первого пользователя снимается. Без кода связи нет.
3. **Заказ без списания.** Заказ на 3 000 ₽ — в кабинете лояльности чек с начислением (5 % — 150 баллов), они «ещё не
   стали доступны».
4. **Заказ со списанием.** Заказ со списанием 500 баллов:
   - сумма к оплате меньше на 500 ₽ (1 балл = 1 ₽);
   - строки фискального чека в сумме равны сумме оплаты;
   - баланс уменьшился на 500.
5. **Отмена.** Отмена заказа из пункта 4 в админке — 500 баллов вернулись, начисление снято. Повтор отмены ничего не
   меняет.
6. **Отмена вне админки.** То же при отмене оплаты YooKassa и через обмен с 1С.
7. **Частичный возврат.** Возврат одной позиции из трёх — снята треть начисления, вернулась доля списанных баллов.
8. **Сбой платформы.** Платформа недоступна при оформлении:
   - заказ оформился без списания;
   - задача по расписанию провела чек позже;
   - двух чеков нет.
9. **Гость.** Гость с телефоном участника — начисление без списания.
10. **Лимит списания.** Попытка списать больше лимита — расчёт показывает максимум, больше не списывается.
11. **Утечки.** В логах сайта нет телефонов, кодов и ключа.

## 13. Решения владельца

- `[%]` начисления, `[%]` заказа баллами, `[срок]` жизни баллов, `[дней]` до доступности начисленных (срок возврата).
- Тексты правил программы и согласия на обработку данных — `[юрист]`. Шаблон — `docs/compliance`.
- SMS для кодов — аккаунт SMSC магазина `[чей: каждого магазина или общий Korzilla]`. Платформа шлёт коды только через
  аккаунты мерчанта (ADR-0020).
- Какие магазины первые на пилоте — `[магазин]`. Сейчас на тестовых сайтах kzla нет ни настроенной оплаты, ни
  заказов.
