# Дорожная карта разработки

Рабочий план платформы лояльности: один движок, который встраивается по API в собственные продукты
компании и продаётся как самостоятельный SaaS. Основание плана — исследование
[docs/research/report.md](research/report.md), ключевые решения зафиксированы в [docs/adr](adr/).

## Как устроен план

- Этапы идут по порядку. Каждый заканчивается работающим инкрементом: код, тесты, документация и зелёный CI.
- Задача считается сделанной (Definition of Done), когда:
  - написаны unit- и feature-тесты, включая негативные сценарии и межтенантную изоляцию;
  - Pint, Larastan и Deptrac проходят без ошибок;
  - публичный контракт (API, события, схема БД) описан, а если решение необратимое — оформлен ADR;
  - обновлены документы этапа и `CHANGELOG`.
- Порядок этапов 8–10 гибкий. Этап 11 обязателен до пилота.
- Версия для пилота — этапы 0–7, основа этапа 8, встраивание в один собственный продукт (9.1) и этап 11.

Статусы: ⬜ не начато · 🟡 в работе · ✅ готово.

---

## Этап 0. Фундамент ✅

**Цель:** инженерная платформа, на которой строятся все модули, и доказанная тестами изоляция тенантов.

- ✅ 0.1 Окружение: PHP 8.5, PostgreSQL 17 (ICU ru-RU), Laravel 13, скрипты `scripts/dev`, git.
- ✅ 0.2 Качество: Pint со `strict_types`, Larastan (уровень 8), Pest 5 с архитектурными тестами, Deptrac, composer-скрипты `lint`, `analyse`, `test`, `check`.
- ✅ 0.3 Модульный монолит: `internachi/modular`, соглашения о структуре модуля, публичный API модуля (`Contracts`, `Events`), карта зависимостей в `deptrac.php`.
- ✅ 0.4 Платформа БД: роли `owner`, `app`, `system` и групповые роли RLS; команда `db:bootstrap`; соединения `pgsql`, `pgsql_owner`, `pgsql_system`; хелперы миграций (`Rls::enable`, `Rls::appendOnly`, `TenantSchema`); тесты идут ролью приложения.
- ✅ 0.5 Ядро: UUIDv7, `Money`, `IntMath`, `Allocator`, `Clock`, ошибки `application/problem+json`, Request ID, маскирование ПДн в логах. Курсорная пагинация перенесена на этап 1 — вместе с первым списочным API.
- ✅ 0.6 Мультиарендность: контекст тенанта в приложении и в сессии PostgreSQL, трейт `BelongsToTenant`, сброс контекста в каждом запросе (Octane), передача контекста в задачи очереди, межтенантные тесты.
- ✅ 0.7 Оргструктура тенанта: партнёры, тенанты, бренды, юрлица (ИНН, КПП, ОГРН), точки продаж с часовым поясом, кассы.
- ✅ 0.8 CI в GitLab: `composer validate` и `audit`, Pint, Larastan, Deptrac, Pest на PostgreSQL 17 (конфигурация готова, проверится первым пайплайном).
- ✅ 0.9 Документация: дорожная карта, ADR 0001–0008, архитектура, инструкция по окружению, `CLAUDE.md`, README, CHANGELOG.

**Готово, когда:** CI зелёный; роль приложения видит только данные своего тенанта; без контекста тенанта запросы возвращают ноль строк; системная роль видит всё; Deptrac без нарушений.

## Этап 1. Леджер баллов ✅

**Цель:** корректный и проверяемый учёт баллов — единственный источник балансов.

- ✅ 1.1 Программа лояльности (модуль `programs`): тенант, название, неизменяемые часовой пояс и валюта (триггер БД), статус.
- ✅ 1.2 Типы баллов: код, точность, стоимость в копейках, политика долга, приоритет списания; условия неизменяемы.
- ✅ 1.3 Счета участника (`available`, `pending`, `held`) и системные счета (эмиссия, погашение, сгорание, корректировки).
- ✅ 1.4 Проводки: единый писатель, сбалансированность (отложенный триггер), идемпотентность, атомарное обновление балансов, CHECK на отрицательный баланс, append-only для проводок и журнала партий, составные FK на тип баллов.
- ✅ 1.5 Партии: создание при начислении, списание от ближайшего сгорания, журнал движений, возврат в те же партии, погашение долга.
- ✅ 1.6 Операции: начисление (сразу или с активацией), резерв, проведение целиком или частично, отмена, истечение резерва, сгорание, восстановление (в исходные партии или в новую), сторно начисления с тремя политиками, корректировки с кодом причины.
- ✅ 1.7 Запросы: балансы (доступно, ожидает, в резерве, можно потратить, ближайшее сгорание), история с курсорной пагинацией.
- ✅ 1.8 Фоновые команды `ledger:activate-due`, `ledger:expire-due`, `ledger:release-expired-holds` по расписанию; поиск работы — системной ролью, обработка — от имени тенанта. Обработка одним SQL на все партии участника; массовая пакетная обработка — при росте объёмов.
- ✅ 1.9 Сверка `ledger:reconcile` (ежедневно): балансы, сбалансированность, остатки партий, суммы по участнику.
- ✅ 1.10 Тесты: операции и крайние случаи, гарантии БД, рандомизированные прогоны с проверкой инвариантов после каждого шага, параллельные списания через две сессии PostgreSQL, команды обслуживания. Базовый замер `ledger:benchmark`: p50 15–24 мс, ~46 операций/с на процесс (Windows, локальная БД).

**Готово, когда:** инварианты обеспечены на уровне БД; сверка показывает ноль расхождений после рандомизированных прогонов; параллельные списания никогда не уводят баланс ниже допустимого. — выполнено.

## Этап 2. Участники, идентификация и согласия ✅

- ✅ 2.1 Участники программы (модуль `members`): статусы (активен, заморожен, заблокирован, обезличен), профиль, дополнительные атрибуты. Объединение дублей перенесено на этап 4: ему нужен перенос баллов между участниками в леджере.
- ✅ 2.2 Защита ПДн: телефон и email зашифрованы (XChaCha20-Poly1305, контекст «тенант | таблица | участник | поле»), поиск по слепому индексу HMAC, отдельному для каждого тенанта; маскированные значения для касс и интерфейсов; обезличивание сохраняет идентификатор для леджера. Ключи — `php artisan pii:generate-keys`, поддерживается ротация.
- ✅ 2.3 Идентификаторы: телефон (+7, E.164), пластиковые карты (выпуск номеров, привязка, блокировка), внешний ID продукта-носителя, одноразовый 8-значный код для кассы (для QR).
- ✅ 2.4 Согласия (модуль `consents`): версии документов (правила, согласие на ПДн отдельным документом, реклама по каналам) и неизменяемый журнал согласий и отзывов с доказательствами.
- ✅ 2.5 Коды подтверждения (модуль `verification`): хранится только HMAC кода, срок 5 минут, 5 попыток, паузы 60/120/300 с, лимиты на номер (5 в час, 10 в сутки), IP и дневной лимит тенанта, только номера +7, автоматическая остановка при низкой доле подтверждений (SMS pumping), код привязан к цели, номеру и контексту (сумма, касса) и расходуется один раз. ✅ 6f-1: лимит на кассу (30 в час) для кодов, запрошенных ключом кассы, вместо лимита адреса.
- ✅ 2.6 Регистрация одной транзакцией: проверка кода, участник, согласия, карта. HTTP-эндпоинты для кассы, сайта и продукта-носителя — на этапе 4.

**Готово, когда:** поиск по любому идентификатору быстрее 20 мс (p95); ПДн зашифрованы в БД; доказательства согласий хранятся; лимиты OTP подтверждены тестами. — выполнено (поиск — один запрос по уникальному индексу; замер p95 — в нагрузочных тестах этапа 4).

## Этап 3. Программа и движок правил ✅

Этап идёт тремя частями с отдельными коммитами: 3a — каталог, правила программы и базовый расчёт чека
(готово); 3b — акции и промокоды (готово); 3c — уровни и механики (готово). **3c выполняется
после этапа 4:** уровни, welcome, рефералы, штампы и сгорание «от последней активности» считаются от
подтверждённых покупок (антифрод: бонусы — только после первой подтверждённой покупки), поэтому им нужна
модель чека.

- ✅ 3.1 Настройки программы (модуль `rules`): ✅ черновик и публикация; ✅ процент начисления на оплаченное деньгами (базисные пункты, округление вниз один раз на чек); ✅ задержка активации; ✅ сгорание через N дней от активации в конце дня по часовому поясу программы или «никогда»; ✅ лимиты списания (доля строк, принимающих баллы, остаток на единицу товара, минимальная сумма чека); ✅ политики возвратов (потраченные баллы, возврат в новую партию); ✅ сгорание в календарную дату (день и месяц через 0–5 лет после активации) и после N дней без покупок (скользящие партии: каждая подтверждённая покупка продлевает срок всех таких баллов участника, уже просроченные не возвращаются); те же политики у бонусов. Списание нескольких типов баллов по приоритету перенесено в этап 12.
- ✅ 3.2 Каталог (модуль `catalog`): товары и категории по кодам мерчанта с идемпотентным импортом; признаки «ограниченный товар» (табак: ни скидок, ни баллов, ни акций), «не начислять», «не списывать», «не участвует в акциях» наследуются от всех категорий-предков; минимальная цена единицы (МРЦ алкоголя). Ставка НДС движку не нужна — её передаёт касса.
- ✅ 3.3 Уровни: настройка уровней — часть версионируемых правил программы (до 10 уровней, первый — начальный без порогов; пороги по сумме оплат деньгами и числу чеков, нужны оба; свой процент начисления, который умножают множители акций; уровень доступен условиям акций как `member.tier`); окно квалификации — скользящее (N дней) или календарный год в часовом поясе программы; повышение сразу после подтверждённой покупки, в том числе через ступень; мягкое понижение — пока покупки квалифицируют, срок удержания продлевается, после его окончания `tiers:review` (ежечасно) понижает на одну ступень и начинает новый срок; ручная фиксация уровня до даты с причиной (ни покупки, ни пересмотр её не меняют); возвраты и аннулирования вычитаются из дня покупки, но уровень сами не понижают. Модуль `tiers`: дневная статистика покупок участника и состояние уровня; покупки считаются и до включения уровней. Runtime API показывает уровень и сколько не хватает до следующего. ⬜ Окно «от годовщины участника» — по запросу клиента; события смены уровня — с outbox (этап 5), ручная фиксация через API — с Management API (этап 5).
- ✅ 3.4 Акции: условия — строгое подмножество JsonLogic с белым списком переменных чека, покупки и участника (сумма и состав чека, канал, точка, дата, время, день недели, уровень, сегменты, число покупок); выбор строк условием по SKU, категориям, количеству и сумме; эффекты — скидка процентом, суммой на чек или на единицу, спеццена, баллы процентом, фиксом на чек или на единицу, множитель базового начисления; группы совмещения («первая по приоритету», «лучшая для покупателя»), эксклюзивность, приоритеты; расписание (период, дни недели, часы, в том числе через полночь); каналы и точки; «только участникам»; бюджет акции и лимит на участника за день, неделю, месяц или всю акцию. Жизненный цикл: черновик → версия → активна ⇄ пауза → архив. ⬜ Наборы «N по цене M» и подарки — отдельной задачей позже.
- ✅ 3.5 Промокоды: общие (с лимитом использований и лимитом на участника), уникальные одноразовые (партии до 100 000, алфавит без похожих символов, выгрузка), персональные для участника; сроки действия, отключение; проверка перед расчётом с причинами отказа; резерв с блокировками, подтверждение и освобождение по ссылке на чек (идемпотентно). Подключение к кассовому протоколу — этап 4.
- ✅ 3.6 Снапшоты: неизменяемые версии правил программы и версии акций; снапшот программы хранит базовые правила и ссылки на версии активных акций, хэш — от канонического JSON (публикация без изменений не создаёт версию); чек считается по снапшоту момента покупки — офлайн-чеки получают правила своего времени. Ссылка на снапшот в чеке — этап 4.
- ✅ 3.7 Движок расчёта: чистая детерминированная функция без обращений к БД; конвейер «проверка и исключения каталога → выбор акций → скидки акций → списание баллов → базовое начисление → баллы акций»; нижняя граница строки (остаток на единицу и МРЦ) для скидок и списания; распределение по строкам методом наибольшего остатка (с переносом на другие строки для фиксированных сумм); списывается наименьшее число баллов, покрывающее скидку в целых копейках; объяснение расчёта кодами; 18 «золотых» векторов с ручным расчётом (`app-modules/rules/tests/golden`) и property-тесты. Замер `php artisan rules:benchmark`: 50 строк и 20 акций — p50 5,3 мс, p95 8,2 мс (Windows, без OPcache). Dry-run-эндпоинт — этап 4.
- ✅ 3.8 Механики (модуль `bonuses`, настройки — часть версионируемых правил программы): ✅ welcome-бонус сразу при регистрации или после первой подтверждённой покупки от минимальной суммы в течение N дней; ✅ «приведи друга» — у каждого участника свой реферальный код, при регистрации по коду бонусы пригласившему и другу начисляются после первой покупки друга от минимальной суммы, не больше N наград пригласившему в календарный месяц, заблокированному — ничего; ✅ день рождения — баллы за N дней до даты (29 февраля — 28-го в невисокосные годы) участникам со стажем от N дней, раз в год, `bonuses:birthdays` ежечасно по часовому поясу каждой программы; переменная условий акций `member.birthday_offset` (дней до или после ближайшего дня рождения) для скидок и множителей «в день рождения ±N дней»; у бонусов свои задержка активации и срок жизни; возврат или аннулирование чека, который принёс бонус, забирает его по политике программы. ✅ Штампы: до 5 карт в программе, у каждой свой тип баллов в леджере (целые, со своим сроком жизни), товары — условием по строке, цель N штампов; штамп за каждую целую единицу товара, полная карта делает бесплатной самую дешёвую единицу в чеке (после скидок акций, не ниже нижней границы строки); штампы бесплатных единиц резервируются вместе с чеком, начисленные штампы проводятся при подтверждении, отмена и возвраты их возвращают; офлайн-чеки только копят штампы; штампы участника видны в Runtime API.

**Готово, когда:** «золотые» векторы проходят детерминированно; объяснение расчёта доступно; чек на 50 строк с 20 акциями считается быстрее 10 мс.

## Этап 4. Обработка чеков (Checkout API) 🟡

Части: 4a — фундамент Runtime API, 4b — модель чека и кассовый протокол (ADR-0009), 4c — участники и
балансы через API, подтверждение списания, офлайн-пакеты, антифрод, 4d — OpenAPI и контрактные тесты,
производительность. Готово всё, кроме прогона k6 на стенде Linux + Octane.

- ✅ 4.1 Модель чека (модуль `processing`): ✅ чек и строки с построчными эффектами и снапшотом правил; состояния `reserved`, `confirmed`, `cancelled`, `voided`, `partially_returned`, `returned`; естественный ключ (касса, бизнес-дата, номер); фискальные признаки (ФН, ФД, ФП); время покупки отдельно от времени записи; данные покупки неизменяемы (триггер БД). Режим скидок, кратных количеству, для касс, которые не умеют делить строку, перенесён в 9.2 (делается под конкретные кассовые интеграции).
- ✅ 4.2 Эндпоинты: ✅ `receipts:calculate`, регистрация с резервом (или сразу с подтверждением), `:confirm`, `:cancel` (отмена резерва или аннулирование), возвраты, просмотр чека; резерв атомарно берёт баллы, бюджеты и лимиты акций и промокоды, подтверждение проводит баллы и начисляет новые, отмена и возврат всё возвращают. ✅ Участники: `members:lookup` (без полного телефона), регистрация с кодом (`members:send-code`, `verifications/{id}:verify`), коды для приложения; баланс и история баллов; `receipts:batch` для офлайн-чеков.
- ✅ 4.3 Подтверждение списания: политика программы `redemption.confirmation` (`none`, `weak_identifiers` по умолчанию, `always`); код приложения — сильный идентификатор, телефон, карта и ручной ввод — слабые; код отправляется на телефон участника с привязкой к кассе и числу баллов, проверяется отдельным вызовом вне транзакции запроса (неверные попытки всегда считаются), чек только потребляет подтверждённый код; id кода сохраняется с чеком.
- ✅ 4.4 Ключи касс (модуль `access`): ключ на кассу и программу, токен `lk_<префикс>.<секрет>` показывается один раз, хранится SHA-256 секрета; поиск по префиксу до определения тенанта — узкой SECURITY DEFINER-функцией; скоупы `receipts`, `members`, `balances` (с 6f-1 ещё `presentation_codes` — выпуск кодов приложения, только у ключей сайта, приложения и интеграций); срок действия, отзыв (действует в пределах минуты кэша), `last_used_at`; команды `api-keys:issue` и `api-keys:revoke` до появления Management API. ⬜ Ротация с периодом перекрытия и HMAC-подпись запросов — с Management API (этап 5).
- ✅ 4.5 HTTP-идемпотентность: `Idempotency-Key` обязателен для изменяющих вызовов; ключ занимается в той же транзакции, что и работа запроса, — сбой не оставляет следов, параллельный дубль ждёт первый запрос и получает его ответ (`Idempotent-Replayed: true`); другой запрос с тем же ключом — 422; хранение 48 часов, очистка `idempotency:prune` ежечасно.
- ✅ 4.6 Лимиты запросов: на ключ и на тенант (конфиг `access.rate_limits`), 429 в формате problem+json с `RateLimit-*` и `Retry-After`; лимитер Runtime API отдельный от будущего Management API.
- ✅ 4.7 Антифрод-контроли: ✅ пауза списания после смены телефона (24 часа), лимит чеков со списанием на участника в сутки, ручной ввод требует кода, кассир и флаг ручного ввода сохраняются с чеком, возврат только по исходному чеку, переводов между участниками нет, лимиты запросов на ключ. ✅ welcome и реферальные бонусы — только после подтверждённой покупки от минимальной суммы и забираются при её возврате, лимит реферальных наград в месяц, бонус ко дню рождения — только участникам со стажем. ✅ 6f-1: лимит кодов подтверждения на кассу; выпуск кода приложения — отдельный скоуп `presentation_codes`, который ключи касс (`pos`, `web_cashier`) и ключи со скоупом `receipts` получить не могут (иначе касса списывала бы баллы любого участника без SMS); касса, приславшая за 10 минут 20 разных неподошедших кодов участника, до конца этих 10 минут не получает ответов по кодам; офлайн-чеки не принимают код приложения. ✅ 7g-2: уведомление о каждом списании со ссылкой «Не вы?» — она замораживает карту, завершает сеансы покупателя и пишет владельцам (ADR-0022).
- ➡️ 4.11 Объединение дублей участников перенесено в этап 6 (инструменты поддержки): нужна операция переноса партий в леджере, перенос карт, и возвраты чеков объединённого участника должны сторнировать баллы у того, к кому они перенесены. ✅ Сделано в 6k–6l (ADR-0019), см. 6.6.
- ✅ 4.8 TTL резервов (30 минут) и автоосвобождение `receipts:expire-reservations` каждую минуту; офлайн-пакеты до 100 чеков обрабатываются задачей в очереди `offline` отдельно от онлайн-потока: чеки до 30 дней, только начисление, без скидочных акций, результат по каждому чеку.
- ✅ 4.9 OpenAPI 3.1 как источник истины (`docs/api/runtime-v1.yaml`): каждый ответ Runtime API в любом тесте и тело каждого успешного запроса сверяются со спецификацией (`Tests\Support\OpenApiContract`), архитектурный тест требует, чтобы маршруты `/api/v1` и операции спецификации совпадали; каталог ошибок — в описаниях ответов. ✅ SDK из спецификации — этап 5 (5.6).
- 🟡 4.10 Производительность: ✅ число запросов к БД — расчёт 10 → 6, регистрация 32 → 20, подтверждение 33 → 25 (вид чека без перечитывания, сроки начисления и точность баллов хранятся с чеком, баланс одним запросом, наступившие партии одним запросом, id системных счетов и собранные снапшоты правил в памяти воркера); ✅ сценарий k6 `tests/load/checkout.js` и данные для него `processing:load-fixtures` (`docs/dev/load-testing.md`). ⬜ Прогон k6 на стенде Linux + Octane с целью p95 ≤ 200 мс и запись результатов; дальнейшее сокращение запросов внутри операций леджера.

**Готово, когда:** сквозные сценарии (частичные возвраты, повторы, офлайн) проходят; базовые показатели нагрузки задокументированы.

## Этап 5. Management API, партнёры и события 🟡

- ✅ 5.1 Партнёры (собственные продукты — тоже партнёры): OAuth 2.0 client credentials (токены на час, ошибки по RFC 6749), выбор мерчанта заголовком `Loyal-Merchant` только среди своих, ключи мерчантов `lm_...`, скоупы, лимиты; команды `partners:create`, `oauth-clients:issue|revoke`, `merchant-keys:issue` до кабинетов. Пользователи партнёра (люди с входом в кабинет) — с кабинетами на этапе 6: кабинет партнёра (6i), где партнёр сам выпускает и отзывает свои OAuth-клиенты (6i-3).
- ✅ 5.2 Провижининг по API (`docs/api/management-v1.yaml`): ✅ мерчанты партнёра (создание с `external_id` против дублей, список, просмотр), вебхуки мерчанта и каталог событий; ✅ программы, типы баллов (в том числе для карт штампов), документы согласий, черновик правил программы целиком (уровни, бонусы, карты штампов, политики сгорания), публикация и версии; бренды, юрлица, точки, кассы и их отключение, ключи Runtime API касс и их отзыв. Сквозной тест: партнёр создаёт мерчанта, настраивает программу и кассу и проводит чек только через API; ✅ акции (черновик, версии, запуск, пауза, архив), промокоды (общие, партии уникальных с выгрузкой, персональные, отключение); участники для бэк-офиса (поиск по телефону, карте, внешнему id, карточка, история баллов, корректировки с кодом причины и необязательным `Idempotency-Key`, фиксация уровня, заморозка, блокировка, обезличивание, бонусы). Шаблоны программ перенесены в кабинет мерчанта (6.3), отчёт об использовании по мерчантам — в биллинг (этап 10).
- ✅ 5.3 Outbox (модуль `outbox`, ADR-0005): доменные события модулей превращаются в интеграционные в той же транзакции; relay системной ролью (`FOR UPDATE SKIP LOCKED`) передаёт их потребителям в тенанте события, после 10 неудач отказывается; каталог событий с версиями данных — `member.enrolled`, `member.tier_changed`, `receipt.confirmed`, `receipt.cancelled`, `receipt.voided`, `receipt.returned`, `bonus.granted`, `bonus.reversed`; очистка опубликованных через 30 дней.
- 🟡 5.4 Вебхуки (модуль `webhooks`, `docs/api/webhooks.md`): ✅ эндпоинты с подпиской на типы событий, секрет показывается один раз и хранится зашифрованным; подпись Standard Webhooks (сверена с эталонным вектором), пример проверки для интеграторов на PHP (проверяется тестами) и Node.js; 11 попыток за ~2,6 суток, `410 Gone` отключает эндпоинт, журнал попыток, повторная отправка, ротация секрета с сутками подписи обоими секретами; защита от SSRF (https, только публичные адреса, соединение с проверенным адресом, без редиректов). ✅ Управление эндпоинтами через Management API. ⬜ Эндпоинты партнёра, получающие события всех его мерчантов, — по запросу.
- ✅ 5.5 Журнал аудита (модуль `audit`, ADR-0010): каждое изменение через Management API (успешное или нет), отказы 403, выдача токенов, чтение данных участников и выгрузка кодов промокодов; исполнитель, мерчант, операция, объекты, запрос без ПДн и секретов, код ответа и ошибки, `request_id`, IP; append-only для всех ролей; записи о мерчанте — под RLS его тенанта, действия партнёра вне мерчантов читает только системная роль. Выгрузка: `GET /audit-entries` (скоуп `audit`, курсор, период, операция) и `audit:export` в NDJSON для оператора. Кабинеты (этап 6) пишут в тот же журнал через `AuditLog::record()`.
- ✅ 5.6 SDK на PHP и TypeScript из OpenAPI; тестовый режим (sandbox) для интеграторов: ✅ каталог кодов ошибок `x-problem-codes` в спецификациях (проверяется по ответам в тестах и по исходникам), полнота ответов 401/403/429, `x-safe-to-retry`; ✅ генератор SDK в закрытом мире (`sdk/generator`, ADR-0011); ✅ песочница (ADR-0012): отдельное развёртывание с `LOYAL_SANDBOX=true`, маркер `test_` в учётных данных и в их хешах, двойники `RealWorldEffect`, только тестовые телефоны и e-mail, код `000000`, заголовок `Loyal-Environment`; ✅ PHP SDK (`loyal/sdk`, PHP 8.2+, без зависимостей) и TypeScript SDK (`@loyal/sdk`, ESM, Node 22+, без зависимостей): ключи идемпотентности и безопасные повторы, токены партнёра, типизированные ошибки с кодами каталога, перебор страниц, проверка подписи вебхуков, помощники для тестов и песочницы; одинаковое поведение закреплено контрактом `sdk/README.md` и эталонными векторами `sdk/conformance` (проверяются по спецификациям); PHP SDK проверен сквозь приложение (путь партнёра и кассы, песочница, подпись настоящей доставки вебхука), пример быстрого старта `sdk/php/examples/quickstart.php`; CI: PHP SDK на PHP 8.2 и TypeScript SDK. Публикация пакетов — после выбора имён, лицензии и реестров (вопрос владельцу продукта).

**Готово, когда:** партнёр создаёт мерчанта и проводит чек только через API (и через SDK); вебхуки проверяются подписью в примере потребителя и в SDK.

## Этап 6. Кабинеты и веб-касса ✅

Части: 6a — ядро сотрудников (модуль `identity`), 6b — Filament, вход с 2FA, каркас кабинетов и словарь аудита (6b-1 — каркас, 6b-2 — защищённые действия, аудит кабинетов, сотрудники платформы, 6b-3 — почта и забытый пароль, 6b-4 — приглашения),
6c — кабинет мерчанта I (команда, организация, ключи, вебхуки, журнал), 6d — консоль платформы (партнёры, мерчанты и
статусы, ключи, доступ поддержки, состояние системы, журнал платформы, учётные записи), 6e — кабинет мерчанта II (запуск программы, шаблоны, типы баллов,
правила, документы согласий), 6f — веб-касса, 6g — кабинет мерчанта III (участники, ручные корректировки, сводка),
6h — кабинет мерчанта IV (акции, промокоды, каталог), 6m — баллы за действия (6.7, сразу после 6h), 6i — кабинет партнёра, 6j — плоскость участника и виджеты,
6k — перенос партий в леджере, 6l — объединение дублей.

- ✅ 6.1 Пользователи и доступ: членство в тенантах, роли и права, 2FA, политика паролей, сессии. ✅ 6a (ADR-0013): учётные записи сотрудников с зашифрованным e-mail, членство на трёх уровнях (платформа, команды партнёров, команды мерчантов под RLS), фиксированные роли и права, доступ сотрудников партнёра к его мерчантам по роли, явный запрет отключённым членством, правила команд в домене (последний владелец с работающей учётной записью, своё членство, владельцами управляют владельцы, сотрудники партнёра командой мерчанта не управляют), последний администратор платформы, разделение обязанностей операторов платформы; Argon2id и политика паролей, атомарные лимиты попыток входа (без блокировки записи) и второго фактора, реестр сеансов с простоем по кабинетам и абсолютным сроком, журнал безопасности учётных записей, обезличивание сотрудника, команды `staff:*`; жёсткие настройки cookie сеанса вне разработки (проверка на запросе) и доверенные прокси. ✅ 6b-1 (ADR-0014): вход в кабинеты с обязательным TOTP (код ±30 секунд, один раз) и кодами восстановления, лимиты платформы на все шаги входа и на подтверждения в профиле, профиль со сменой пароля, «Мои сеансы», «События безопасности». ✅ 6b-2: администрирование учётных записей из консоли (отключить, включить, сбросить 2FA) с правом `accounts.manage`, без действий над собой и без отключения последнего администратора. ✅ 6b-3: «Забыли пароль?» во всех кабинетах (один ответ для любого адреса, письмо из очереди, ссылка на час и один раз, не больше 3 в час на запись, ссылка строится от `APP_URL`), письма сотрудникам на русском, ссылка для смены пароля из консоли, письмо о сбросе 2FA. ✅ 6b-4: приглашения в консоль и в команды мерчантов — ссылка только письмом, 72 часа и один раз, страница приглашения в кабинетах (новый человек задаёт имя и пароль, существующий принимает как есть), правила команды и права пригласившего при принятии, «Приглашения в консоль»; экран команды мерчанта — в 6c, приглашения партнёрам — в 6i. ✅ 6i-1: кабинет партнёра `/partner/{id}` для команды партнёра (у приостановленного — только чтение): «Мерчанты» — все мерчанты партнёра с поиском и фильтром, добавление по праву `merchants.create`, переход в кабинет мерчанта по роли; «Журнал аудита» партнёра; ссылка «Кабинет партнёра» в кабинете мерчанта. ✅ 6i-2: «Команда» партнёра — приглашения письмом в команду партнёра (страница приглашения в кабинете партнёра), смена ролей, закрытие и открытие доступа, отзыв приглашений со вторым фактором; владельцев трогают только владельцы. ✅ 6i-2b: отзыв приглашения — защитное действие (права `invitations.revoke`, `invitations.revoke_owners`): работает и у приостановленного мерчанта или партнёра. ✅ 6i-3: «Ключи доступа» партнёра — выпуск OAuth-клиентов Management API в кабинете (секрет один раз, второй фактор, у роли свой потолок прав ключа: разработчик не даёт права на участников и журнал), отзыв (`credentials.revoke`, и у приостановленного партнёра), отзыв ключей сотрудника при закрытии ему доступа. ✅ 6i-3b: ключ кассы через Management API выпускают только учётные данные с правами `organization` и `members` (касса находит участников и тратит их баллы), так что клиент разработчика не обходит запрет на данные участников. ✅ 6i-4a: партнёр приглашает первого владельца своего мерчанта (право `merchants.invite_owners`), пока у мерчанта нет владельца; дальше команда мерчанта — его собственное дело. ✅ 6i-4b: консоль приглашает владельца партнёра (письмо действующим владельцам партнёра), в кабинете партнёра — заготовка «Виджеты». ✅ Поправка 2026-10-22 (решение владельца, ADR-0013): вход по e-mail и паролю, «2FA-приложение» — по желанию в профиле (и у операторов); действия подтверждаются кодом или, без второго фактора, паролем; часовой лимит попыток входа на e-mail, кроме браузеров, где с ним уже входили. Требование 2FA от команды мерчанта — позже.
- ✅ 6.2 Админка платформы (Filament): партнёры, тенанты, состояние системы, вход от имени с аудитом (доступ поддержки); тарифы — в 10.1. ✅ 6b-1: консоль `/console` для операторов платформы, вне разработки — только на своём хосте (`CONSOLE_DOMAIN`). ✅ 6b-2: «Сотрудники платформы» — роли, отзыв доступа, отключение и включение учётной записи, сброс 2FA с причиной; изменение подтверждается кодом 2FA, если его не вводили последние 10 минут, и пишется в журнал аудита (действия над людьми мерчанта или партнёра копируются в их журналы — когда консоль начнёт работать с ними, в 6d). ✅ 6d-1 (ADR-0015): «Партнёры» и «Мерчанты» — поиск, добавление, изменение, приостановка, закрытие и повторное открытие; статусы действуют везде: приостановленный мерчант только читает (кассы работают), закрытый недоступен, ключи отключённых касс не принимаются. ✅ 6d-2: ключи доступа партнёров, ключи мерчантов и касс в консоли — просмотр и отзыв с письмом владельцам; консоль ключей не выпускает. ✅ 6d-3: доступ поддержки — оператор открывает кабинет мерчанта под своим именем с причиной, на время (до 120 минут), только чтение по умолчанию и никогда с чувствительными правами; выдача заканчивается вместе с ролью оператора, учётной записью и мерчантом и действует только в браузере, где после её начала подтверждён второй фактор; плашка «Завершить доступ» в кабинете; начало, конец и действия — в журнале мерчанта и платформы. ✅ 6d-4: «Состояние системы» — проверки модулей (планировщик, очереди, сбойные задания, исходящие события, вебхуки, сверка баллов, резервы чеков), последние запуски задач по расписанию и пропущенные запуски, пульс `platform:heartbeat`; проверки раз в минуту считает `platform:health`, консоль только читает результаты; страница обновляется сама и не продлевает сеанс. ✅ 6d-5: «Журнал платформы» — действия в консоли и копии действий поддержки в кабинетах мерчантов, с именами операторов, адресом и браузером. ✅ 6d-6: «Учётные записи» — поиск сотрудника по e-mail или идентификатору (каждый поиск в журнале платформы, без введённого адреса), действия администратора над найденной записью и обезличивание с причиной и словом-подтверждением (ждущие приглашения на адрес отзываются); предупреждение, если команда останется без владельца; копии — в журналы команд человека.
- ✅ 6.3 Кабинет мерчанта (Filament): настройки программы, типы баллов, уровни, конструктор акций, промокоды, каталог, точки, кассы и ключи, участники (маскированные ПДн, история, корректировки), документы согласий, отчёты, пользователи, аудит. ✅ 6b-1: каркас `/merchant/{id}` — мерчант из URL, доступ по членству в команде или роли в партнёре (сотрудникам партнёра переключатель показывает до 50 мерчантов каждого партнёра, остальные — по ссылке до кабинета партнёра в 6i), контекст тенанта на каждом запросе страницы и Livewire, только чтение у приостановленного мерчанта. ✅ 6c-1: «Команда» (участники, сотрудники партнёра, приглашения, роли, закрытие доступа) и «Журнал аудита» (фильтры, названия действий по-русски). ✅ 6c-2: «Организация» — точки (изменение, закрытие с отключением касс), кассы (включая веб-кассу), бренды, юрлица; ключи отключённых касс отклоняются на входе в 6d вместе со статусами мерчанта. ✅ 6c-3: «Ключи касс» и «Ключи мерчанта» — выпуск с показом один раз и вторым фактором, отзыв (и у приостановленного мерчанта), кто выпустил, последнее использование ключа кассы; отзыв ключей при закрытии доступа сотруднику и сотруднику партнёра. ✅ 6c-4: «Вебхуки» — добавление на все или выбранные события, секрет подписи один раз, отключение с причиной, новый секрет, доставки и повторная отправка. ✅ 6e-1: «Программы» (добавление с часовым поясом, переименование) и «Типы баллов» (код, точность, стоимость балла в рублях, минус на балансе; переименование). ✅ 6e-2: «Документы согласий» — действующие версии по видам, публикация новой версии со вторым фактором и отметкой «Текст проверен», история версий с текстами. ✅ 6e-3: «Правила программы» — базовые правила (начисление, доступность и сгорание, оплата баллами, возвраты) черновиком, публикация со вторым фактором после списка изменений, версии. ✅ 6e-4: уровни (пороги суммы и числа покупок, процент начисления, окно подсчёта, срок сохранения уровня) и бонусы (приветственные, ко дню рождения, «Приведи друга» — каждый со своей доступностью и сгоранием) отдельными формами того же черновика. ✅ 6e-5: карты штампов — до пяти, товары по списку артикулов или по категориям каталога, свой тип баллов у каждой карты. ✅ 6e-6: программа по шаблону («Баллы за покупки», «Уровни и бонусы», «Кофейня со штампами») с типами баллов и черновиком правил, шаблоны текстов документов согласий, «Готовность к запуску» на «Обзоре» (юрлицо, программа, опубликованные правила и документы, работающая касса с ключом). **Этап 6e завершён.** ✅ 6g-1: «Участники» — список программы с поиском по фамилии и имени и фильтром по статусу (телефоны маской), поиск участника целиком по телефону, карте или внешнему id, карточка (данные, баллы, уровень, штампы, согласия, бонусы, карты), покупки и история баллов; просмотры и показ телефона — в журнале аудита. ✅ 6g-2: действия с участником — фиксация уровня, заморозка, блокировка и снятие, обезличивание с подтверждением словом и вторым фактором, выдача и блокировка карт, добавление напечатанных карт в программу. ✅ 6g-3: «Скорректировать баллы» в карточке участника — начислить или списать с причиной из списка и комментарием (для «Другое» он обязателен), лимиты на одну корректировку и на день для роли «Поддержка» и доступа поддержки, повторная отправка формы корректировку не повторяет; причины и комментарии видны в истории баллов. ✅ 6g-4: «Сводка» — за 7, 30 или 90 дней по поясу программы: участники и новые, покупки участников и их сумма, баллы из учёта баллов (начислено, оплачено, сгорело, при возвратах, вручную) и баллы на счетах участников, плюс таблица по дням; в консоли «Подробнее» мерчанта — участники и чеки за 30 дней. **Этап 6g завершён.** ✅ 6h-1: «Акции» — конструктор акций (скидки в процентах и рублях, специальная цена, дополнительные баллы процентом, количеством или умножением; товары по артикулам или категориям; условия чека — сумма, артикулы и категории, уровень, первая покупка, день рождения; период, дни недели и часы; точки и каналы; лимиты на участника и бюджет; совместимость с другими акциями; время — в поясе программы), публикация версий с показом JSON, запуск, пауза и архив; условия из API сохраняются как есть, черновик, изменённый пока форма открыта, не перезаписывается и не публикуется. ✅ 6h-2: «Промокоды» акции — общие и персональные коды с поиском по всему коду, создание и отключение; «Партии промокодов» — выпуск партии одноразовых кодов, выгрузка файлом CSV со вторым фактором, отключение партии (и в Management API); «Выдать промокод» в карточке участника; публикация и запуск акций — отдельное право со вторым фактором. ✅ 6h-2b: приостановленный мерчант может отключить утёкший промокод или партию (в кабинете и Management API) и заблокировать потерянную карту (в кабинете), как отзыв ключей. ✅ 6h-3a: каталог в Management API — запись категорий и товаров пачкой, страницы с поиском по артикулу и названию. ✅ 6h-3b: «Категории» и «Товары» в кабинете — правка строк и загрузка из файла CSV (UTF-8, UTF-16 или Windows-1251, все столбцы, целиком или никак, ошибки по строкам). **Этап 6h завершён.** ✅ 6m-2: «Баллы за действия» — действия программы с условиями (запуск и изменение — со вторым фактором, как публикация акции), приостановка (и у приостановленного мерчанта), начисления за действия в карточке участника и названия действий в истории баллов (п. 6.7). ✅ 6l-3: «Объединить дубли» из карточки участника (п. 6.6).
- ✅ 6.4 Веб-касса (PWA) для точек без интеграции. ✅ 6f-1: подготовка Runtime API — скоуп `presentation_codes` (ключ кассы не выпускает коды приложения), защита кодов приложения от подбора, поиск чека кассы по номеру и бизнес-дате, лимит кодов подтверждения на кассу. ✅ 6f-2 (ADR-0016): устройства веб-кассы — одноразовый код привязки на 10 минут (хранится HMAC) и токен устройства для HttpOnly-cookie (её ставит оболочка кассы в 6f-4); ключи смен не больше чем на 12 часов, которые Runtime API принимает только вместе с cookie своего устройства; отзыв устройства останавливает его ключи; у веб-кассы нет своего долгоживущего ключа. Исправлено: кэш ключей касс хранил объекты, которые кэш в базе и Redis не восстанавливает, — каждая проверка ключа из кэша давала бы 401. ✅ 6f-3: модуль `till` — кассиры с PIN-кодами (для всех точек или одной; пять неверных подряд блокируют на 15 минут, у устройства — не больше 20 неверных в окне 15 минут) и смены: PIN открывает смену и даёт устройству ключ смены, блокировка его отзывает, разблокировка PIN-кодом даёт новый, отзыв устройства закрывает его смену. ✅ 6f-4: оболочка кассы `/till` — привязка браузера кодом (сеанс сотрудника в нём завершается), данные устройства и его кассиров, открытие, блокировка, разблокировка и закрытие смены с выдачей ключа; строгая CSP, манифест, свой хост `TILL_DOMAIN`; действия кассы с отказами — в журнале аудита мерчанта (канал «Веб-касса»). ✅ 6f-5: кабинет «Веб-касса» — устройства (код привязки один раз со ссылкой и QR-кодом, «сделать этот браузер кассой», отзыв), кассиры с PIN-кодами, смены (все открытые и закрытые за 30 дней) с закрытием из кабинета. ✅ 6f-6a: приложение кассы (`frontend/till`, `composer till:build`, сборки по версиям) — привязка по ссылке, QR-коду или коду, кассиры и смены по PIN-коду с экранной клавиатуры (автоблокировка через 10 минут, и после сна планшета), поиск участника по телефону, карте или коду из приложения, расчёт и проведение покупки с начислением через Runtime API и SDK (ключ смены только в памяти страницы; чек без ответа повторяется тем же запросом, переживает блокировку и смену ключа и не проводится дважды), service worker держит страницу и файлы сборки; демо-касса `LocalTillSeeder`. ✅ 6f-6b-1: списание баллов (сколько ввёл кассир или все доступные; подтверждение кодом из SMS, где программа его требует, без SMS — по отсканированному коду из приложения, если код нужен только для слабых идентификаторов) и регистрация участника у прилавка (документы программы с текстами — новая операция `GET /api/v1/consent-documents`, телефон подтверждается кодом — это требует и сервер, кассир записывается с согласием); номер чека без ответа закрепляется до выяснения. ✅ 6f-6b-2: возврат покупки участника (список покупок — новая операция `GET /api/v1/members/{member}/receipts`; целиком или на сумму возвращаемых товаров; возврат без ответа не проводится дважды) и итоги смены (чеки, сколько из них с участником, начислено и оплачено баллами, возвраты — по кнопке и при закрытии смены; чеки и возвраты запоминают устройство кассы). ✅ 6f-6b-3a: работа без связи — покупка участника записывается в очередь на устройстве (только начисление, до 72 часов) и уходит пакетом, когда связь вернётся, без дублей; чек и возврат в пути и без ответа переживают перезагрузку (прочитанные чеки уходят после проверки кассиром); пакет запоминает устройство, стирает телефоны и карты участников после обработки и завершается без потерь, даже если задание сдалось (`receipts:finish-batches` и проверка «Состояния системы» для пакетов, которые никто не обработал); хранилище браузера стирается только у отозванного устройства, а временно не работающее хранит чеки до возвращения. Исправлено: отпечатки ключей идемпотентности — HMAC; время чека и возврата проверяется строго. ✅ 6f-6b-3b: камера планшета читает карты и QR-коды приложения участника там, где браузер умеет читать коды сам (`BarcodeDetector`); прочитанное — скан; камера гаснет сразу после чтения, отмены, другого действия или смены экрана; в остальных браузерах — сканер и ручной ввод. **Веб-касса (6f) завершена.** Настройки веб-кассы (предел суммы чека и другие ограничения кассы) перенесены к антифроду кассы.
- ✅ 6.5 Встраиваемые web components поверх публичного API с короткоживущими сессиями и темизацией (white-label). ✅ 6j-1 (ADR-0018): сеансы участника `lms_…` — один участник, один сайт (`Origin` обязателен), 1–60 минут, скоупы `profile`, `history`, `presentation_code` (только учётным данным с `members`), работают, пока действуют открывшие их учётные данные; выпуск и закрытие всех сеансов участника через Management API (скоуп `widgets`, работает у приостановленного мерчанта, журнал аудита называет участника и сеанс); API участника `/api/member/v1` (профиль, история баллов, код для кассы с QR, закрытие своего сеанса; заблокированный или обезличенный участник — 401); лимиты на участника и мерчанта; CORS для Runtime API и API участника, Management API — без CORS. ✅ 6j-2: клиент участника в PHP и TypeScript SDK (`MemberClient`: поставщик сеансов заменяет истёкший сеанс, `Origin` вне браузера, `endSession`; векторы 23–27, сквозной тест партнёр → участник). ✅ 6j-3: веб-компоненты `<loyal-member-card>`, `<loyal-points-history>` и `<loyal-presentation-code>` поверх клиента участника — сеанс от функции сайта `tokenProvider` (один на виджеты страницы, истёкший заменяется сам, событие `loyal-session-expired`, `endSession()`), Shadow DOM только с текстовыми узлами и QR-картинкой, темы переменными `--loyal-*` и `::part()`, свои тексты; один модуль на версию `/embed/v1/<версия>/loyal-widgets.js` с integrity, опубликованные версии хранятся в git и не меняются; руководство `docs/api/widgets.md` (CSP страницы, PHP SDK, заголовки веб-сервера); раздел «Виджеты» кабинета партнёра с кодом для страницы; локальное демо `/widgets-demo`.
- ✅ 6.6 Инструменты поддержки: объединение дублей участников (перенос партий в леджере с сохранением сроков, перенос карт, сторно возвратов у участника, к которому перенесены баллы; запрет при активных резервах), ручные корректировки с причиной и аудитом. ✅ 6g-3: ручные корректировки — модуль `support` (`ManualAdjustments`): проводка в леджере от имени сотрудника, причина и комментарий хранятся отдельно от журнала аудита (комментарий стирается при обезличивании участника), лимиты на операцию и на день проверяются атомарно — корректировки одного человека проходят по очереди. ✅ 6k (ADR-0019): перенос участника в леджере — партии дубля переходят к основной записи с теми же сроками и журналом (порядок списания общий, возвраты прошлых покупок дубля возвращают баллы в те же партии), балансы — через клиринговый счёт, долг дубля — тоже; объединённый участник не получает новых баллов, резервов и корректировок, а возвраты и обслуживание его прошлого идут у основной записи, в том числе по цепочке объединений; запрет при активных резервах; гарантии базы и проверки сверки. ✅ 6l-1: объединение участников в модулях — `MemberMerges` (просмотр и объединение одной транзакцией): карты и внешний идентификатор переходят, контакты и коды для кассы дубля удаляются, согласия отзываются, покупки для уровней и использования акций суммируются, остаётся высший уровень, бонусные награды — по одной каждого вида на человека, персональные промокоды отключаются; отказ при незавершённых покупках, заморозке, блокировке, обезличивании и двух внешних идентификаторах; чеки дубля после объединения (возвраты, офлайн-пакеты) действуют на основную запись, его покупки — её покупки, лимиты за действия и приглашения считают и его награды; вебхук `member.merged`. ✅ 6l-2: API после объединения — запросы с id дубля в Runtime API и изменения дубля в Management API получают 409 `member_merged` с id записи, у которой теперь всё (веб-касса сама показывает её и просит повторить действие), дубль читается в Management API, сеанс виджетов дубля не работает, офлайн-чеки дубля начисляют основной записи. ✅ 6l-3: «Объединить дубли» в кабинете мерчанта — из карточки участника: дубль находят по телефону, карте или внешнему идентификатору, страница показывает, что перейдёт к основной записи и что перестанет работать, или почему объединить нельзя; объединяет владелец или администратор (`members.merge`, второй фактор) с причиной и словом «объединить», журнал аудита называет обе записи; карточка дубля ведёт к основной записи.
- ✅ 6.7 Баллы за действия (решение владельца продукта 2026-10-06, после 6h): мерчант описывает действие — отзыв, опрос, подписку на соцсети — и сколько баллов за него дать, с лимитами («за отзыв — 50 баллов, раз в месяц»); сайт или приложение мерчанта сообщает о действии участника через API, начисление идёт через леджер с аудитом. ✅ 6m-1 (ADR-0017): модуль `activities` — действия программы отдельным списком (меняются сразу, без публикации правил), лимит участника за период и бюджет, одно событие — одно начисление, отмена по политике возвратов; Runtime API (список, сообщение, отмена) со скоупом `activities` только для ключей сайта, приложения и интеграций; Management API; вебхуки `activity.rewarded`, `activity.reversed`. ✅ 6m-2: раздел «Баллы за действия» в кабинете мерчанта — создание, изменение условий и возобновление как публикация акции (право `campaigns.publish` со вторым фактором, не через доступ поддержки), архив — `campaigns.manage`, приостановка — новое защитное право `activities.pause` (и у приостановленного мерчанта); правка не перезаписывает условия, изменённые пока форма открыта; в карточке участника — последние начисления за действия, в истории баллов — название действия.

**Готово, когда:** мерчант настраивает и ведёт программу без API; партнёр встраивает виджет участника в свой продукт.
✅ Этап закрыт 2026-10-15: кабинеты мерчанта и консоль проверены в браузере на локальном стенде (все страницы, объединение
дублей вживую, журналы аудита); отчёты сверх «Сводки» — этап 8.

## Этап 7. Клиентские каналы и коммуникации 🟡

Решения владельца (2026-10-15): провайдеры — аккаунты мерчантов (ADR-0020); самостоятельное вступление в кабинете
покупателя — только с подключённым каналом; вместо Apple Wallet пока веб-карта; «скоро сгорят баллы» — служебное
сообщение. Части: 7a — каналы мерчанта и коды (✅ 7a-1 каналы и коды через них, ✅ 7a-1b регистрация на кассе без
кода по настройке программы, ✅ 7a-2 страница «Каналы»), ✅ 7b — защита
от накрутки SMS, 7c — правила рассылок и e-mail (✅ 7c-1 очередь и правила отправки, ✅ 7c-2 шаблоны, ✅ 7c-3 статусы доставки, ✅ 7c-4a почта мерчанта, ✅ 7c-4b письма участникам), ✅ 7d — «Сообщения» в кабинете (✅ 7d-1 журнал сообщений, ✅ 7d-2 пауза и настройки, ✅ 7d-3 консоль), ✅ 7e — кабинет покупателя (✅ 7e-1 адрес и вход по коду, ✅ 7e-2 вступление и «Выйти везде», ✅ 7e-3a согласия, имя и день рождения, ✅ 7e-3b e-mail с подтверждением, ✅ 7e-4 «Отписаться» и реклама письмами), ✅ 7f — приложение кабинета и веб-карта (✅ 7f-1 приложение, вход, карта и главный экран, ✅ 7f-2 вступление и возраст, ✅ 7f-3 профиль и подписки, ✅ 7f-4 цвет карты), ✅ 7g — автосообщения (✅ 7g-1 приветствие, первая покупка и новый уровень; ✅ 7g-2 уведомление о
списании со ссылкой «Не вы?»; ✅ 7g-3 очередь сообщений в кабинете), 7h — автосообщения по расписанию (✅ 7h-1
поздравление с днём рождения, ✅ 7h-2 «Давно не были», ✅ 7h-3 «Баллы скоро сгорят»), 7i — MAX,
7j — агрегаторы мессенджеров, 7k — API для интеграторов.

- ✅ 7.1 Кабинет покупателя (PWA): вход по OTP, баланс, история, QR, прогресс уровня, управление согласиями.
  Готово (ADR-0021): адрес кабинета программы на хосте платформы и страница «Кабинет покупателя» в кабинете мерчанта
  (ссылка и QR-код), вход по коду из SMS с проверкой «я не робот» и лимитами, сеанс до выхода (не дольше года), выход,
  сеансы плоскости участника для страницы кабинета (7e-1); вступление в программу в кабинете с согласиями, именем, днём
  рождения и кодом друга (по выбору мерчанта), «Выйти везде», завершение сеансов из карточки участника (7e-2);
  согласия, имя и день рождения через API участника (7e-3a); e-mail с подтверждением кодом из письма через почту
  мерчанта, с лимитами писем на покупателя и на адрес (7e-3b); ссылка «Отписаться» в рекламных письмах — страница,
  которая отзывает согласие одной кнопкой, и отписка кнопкой почтового сервиса (7e-4); приложение кабинета — вход с
  проверкой «Я не робот», карта с кодом для кассы, баллами, уровнем и штампами, история баллов, выход, установка на
  главный экран телефона и страница без интернета (7f-1); вступление в приложении — анкета с документами, которые
  можно прочитать тут же, согласиями на рекламу, кодом друга и строкой «Мне есть 14 лет» (мерчант может поставить 18;
  дата рождения младше не принимается) (7f-2); профиль в приложении — имя, день рождения (один раз), e-mail с кодом из
  письма, подписки на рекламу и документы программы; страница отписки ведёт в профиль (7f-3); цвет карты, который
  выбирает мерчант: значок на экране телефона и строка браузера — в этом цвете, кнопки и цифры — в его читаемых
  оттенках для светлой и тёмной темы (7f-4).
- 🟡 7.2 Wallet-карты: Apple Wallet (PassKit, веб-сервис обновлений, push через APNs), веб-карта как запасной вариант.
  Готово: веб-карта — кабинет покупателя на главном экране телефона с кодом для кассы и всегда свежим балансом (7f-1).
  Впереди: Apple Wallet — когда будет аккаунт разработчика Apple (решение владельца продукта).
- 🟡 7.3 Ядро коммуникаций: шаблоны, журнал сообщений, провайдеры (SMS, email, push RuStore/FCM/APNs, бот MAX), маршрутизация с цепочкой запасных каналов, разделение сервисных и рекламных сообщений, проверка согласий, частотные лимиты, «тихие часы» по часовому поясу программы.
  Готово (ADR-0020): каналы — аккаунты мерчантов у SMSC и SMS Aero (SMS и коды в Telegram), коды через них с
  запасным каналом, журнал сообщений без текстов и номеров; регистрация на кассе без кода по настройке программы
  (7a-1b); страница «Каналы» в кабинете — подключение, проверка, проверочное SMS, порядок (7a-2); защита от
  накрутки SMS — лимиты кодов мерчанта на сутки и месяц, автостоп с эскалацией и письмами владельцам (7b); очередь
  сообщений участникам с правилами в момент отправки — согласие на рекламу, «тихие часы» по поясу программы, частота
  рекламы, состояние участника, повторы, хранение 13 месяцев (7c-1); шаблоны автосообщений с проверкой переменных,
  предпросмотром и историей в кабинете (7c-2); статусы доставки — опрос провайдеров по расписанию (7c-3); почтовый
  ящик мерчанта (SMTP) — подключение с проверкой, проверочное письмо, записи SPF и DMARC домена (7c-4a); письма
  участникам — служебные сначала письмом, предупреждения сначала по SMS, с подхватом другим маршрутом (7c-4b); журнал
  сообщений в кабинете — итог, причина, стоимость, поиск по номеру или e-mail (7d-1); пауза рекламы и служебных
  сообщений, свои тихие часы, частота рекламы и порядок «письмо или SMS» (только строже платформы), письмо владельцам
  при 80 % лимита кодов (7d-2); в консоли — остановка сообщений мерчанта и всех сообщений платформы, свои пределы кодов
  мерчанта (7d-3); реклама письмами — только на подтверждённые покупателем адреса, со ссылкой «Отписаться» (7e-4).
  Впереди: запасной маршрут после недоставки принятого SMS, push, MAX.
- ✅ 7.4 Триггеры: welcome, первая покупка, реактивация (30/60/90 дней), день рождения, скорое сгорание, смена уровня, уведомление о списании.
  Готово (ADR-0022): страница «Автосообщения» в кабинете — каждое сообщение мерчант включает для программы сам, по
  умолчанию все выключены; приветствие после вступления, спасибо за первую покупку с баллами, поздравление с новым
  уровнем — в момент события, с текстом шаблона и баллами участника, по правилам отправки (7g-1); уведомление о
  каждом списании со ссылкой «Не вы?», которая замораживает карту, завершает сеансы покупателя и пишет владельцам
  (7g-2); «Очередь» в разделе «Сообщения» и «Сообщения» в карточке участника — что ждёт отправки и чего, что ушло и
  дошло ли, что пропущено или не отправлено и почему (7g-3, ADR-0020); поздравление с днём рождения вместе с баллами ко
  дню рождения, которые дарит программа (7h-1); «Давно не были» — тем, кто не покупал 30, 60 и/или 90 дней (сроки
  выбирает мерчант), по ежедневной проверке утром по часовому поясу программы (7h-2); «Баллы скоро сгорят» — за 3, 7
  или 14 дней до сгорания, с ближайшей датой и суммой, не чаще раза в неделю, служебное сообщение без рекламы (7h-3).
- 7.5 Бот и мини-приложение MAX; Telegram как опциональный адаптер.

**Готово, когда:** триггеры срабатывают с проверкой согласий и лимитов; Wallet-карта обновляется при изменении баланса.

## Этап 8. Отчёты и аналитика ⬜

- 8.1 Операционные отчёты: охват программы по чекам и выручке, начисления, списания, сгорания, обязательства по юрлицам в баллах и рублях, отчёты по кассирам и точкам (в том числе итоги смен веб-кассы по кассирам), результаты акций против контрольной группы.
- 8.2 Глобальная контрольная группа (holdout).
- 8.3 Аналитический контур: outbox → ClickHouse, когорты, удержание, LTV, RFM-сегменты с записью обратно в PostgreSQL.
- 8.4 Выгрузки CSV и XLSX, отчёты по расписанию, доступ для BI.
- 8.5 Данные для МСФО 15: входящий и исходящий остаток обязательств, движение, фактическая доля погашения.

**Готово, когда:** итоги отчётов сходятся с леджером; RFM-сегменты используются в акциях.

## Этап 9. Интеграции ⬜

- 9.1 Встраивание в первый собственный продукт (API и виджет).
- 9.2 МойСклад Loyalty API (касса вызывает наш сервер). Для касс, которые не умеют делить строку, — режим скидок и списания, кратных количеству единиц в строке.
- 9.3 JS-виджет для сайтов и Tilda; модуль для 1С-Битрикс.
- 9.4 Приложение для Эвотора (отдельный репозиторий).
- 9.5 Плагин iikoFront (.NET, отдельный репозиторий, лицензирование через iiko).
- 9.6 Расширение 1С (отдельный репозиторий).
- 9.7 Frontol (через партнёрство с АТОЛ), Saby и другие — по спросу.

**Готово, когда:** пилотные мерчанты проводят реальные чеки минимум через два канала.

## Этап 10. Биллинг SaaS ⬜

- 10.1 Тарифы: оплата за активные точки с включённым объёмом базы, SMS по себестоимости с прозрачной наценкой, оптовые цены для партнёров.
- 10.2 Учёт использования: активные точки, участники, чеки, сообщения.
- 10.3 Счета, акты и УПД через Диадок; рекуррентные платежи ЮKassa, CloudPayments, Т-Касса; работа с должниками и приостановка.
- 10.4 Отчёты и расчёты с партнёрами.

**Готово, когда:** ежемесячное выставление счетов пилотным тенантам работает автоматически.

## Этап 11. Прод, безопасность и комплаенс ⬜

- 11.1 Контейнеры: образы FrankenPHP + Octane, воркеры Horizon, планировщик, health checks.
- 11.2 Инфраструктура: managed Kubernetes, PostgreSQL и Redis в российском облаке с аттестацией УЗ-1, Terraform, секреты, бэкапы и PITR, резервная площадка.
- 11.3 Наблюдаемость: OpenTelemetry → Grafana (метрики, логи, трассировки), self-hosted Sentry, SLO (p95 чека ≤ 200 мс, доступность 99,9%), алерты, runbook'и.
- 11.4 Безопасность: пентест, сканирование зависимостей и секретов, SAST, SSO и MFA для админов; отдельная роль БД для трафика публичных API без прав на таблицы сотрудников (остаточный риск ADR-0013).
- 11.5 Документы по 152-ФЗ: типовое поручение на обработку, модель угроз, акт уровня защищённости, политики, регламент реагирования на инциденты (24/72 часа).
- 11.6 Staging, нагрузочный тест на staging, регламент подключения пилотного клиента.

**Готово, когда:** продуктивная среда работает, первый пилотный мерчант подключён.

## Этап 12 и далее. Развитие ⬜

Подарочные карты (учёт как аванс), несколько типов баллов в программе со списанием по приоритету, платные подписки, геймификация, коалиции и расчёты между юрлицами, SSO (OIDC, SAML), выделенные кластеры, ISO 27001, bug bounty, ML-скоринг антифрода, next best offer, MCP-сервер и `llms.txt`, коннекторы r_keeper и Set Retail, вынос горячего пути в Go — только если SLO не выдерживается после оптимизации.
