# Архитектура

Краткая карта системы. Решения и их причины — в [ADR](adr/), план — в [дорожной карте](roadmap.md).

## Модули

Модульный монолит на Laravel 13 (ADR-0001). Модули лежат в `app-modules/`, пространство имён
`Modules\<Module>`. Публичный API модуля — `Contracts` и `Events`; остальное внутреннее.

| Модуль | Отвечает за | Этап |
|---|---|---|
| `kernel` | общее ядро: контекст тенанта, роли БД и RLS, ошибки API, деньги, время, маскирование ПДн | 0 ✅ |
| `tenancy` | партнёры, тенанты, бренды, юрлица, точки, кассы | 0 ✅ |
| `programs` | программы лояльности и их настройки | 1 ✅, 3 |
| `ledger` | учёт баллов: счета, проводки, партии, резервы | 1 ✅ |
| `members` | участники, зашифрованные ПДн, карты, одноразовые коды для кассы | 2 ✅ |
| `consents` | документы согласий и журнал согласий; о каждой записи — событие `ConsentChanged` (вебхук `member.consent_changed`) | 2 ✅ |
| `verification` | коды подтверждения, лимиты, защита от SMS pumping | 2 ✅ |
| `catalog` | товары и категории, ограничения и исключения, МРЦ | 3 ✅ |
| `rules` | правила программы и их снапшоты, движок расчёта чека; акции, промокоды, уровни | 3 🟡 |
| `tiers` | уровни участников: статистика покупок по дням, квалификация, мягкое понижение, ручная фиксация | 3 ✅ |
| `bonuses` | бонусы вне чеков: welcome, «приведи друга», день рождения | 3 ✅ |
| `activities` | баллы за действия: действия программы с лимитами и бюджетом, начисления по сообщениям сайта, отмена (ADR-0017) | 6 ✅ |
| `outbox` | интеграционные события: outbox в транзакции изменения, relay к потребителям | 5 ✅ |
| `webhooks` | эндпоинты вебхуков, подписанные доставки с повторами, журнал | 5 🟡 |
| `access` | ключи Runtime API, OAuth-клиенты партнёров и ключи мерчантов для Management API, устройства веб-кассы и ключи смен (ADR-0016), аутентификация, идемпотентность, лимиты | 4–6 🟡 |
| `management` | Management API: мерчанты партнёров, провижининг программ и организации, акции, участники и их согласия, вебхуки, журнал аудита, каналы сообщений и лимиты кодов мерчанта, автосообщения, настройки сообщений, журнал и очередь сообщений, кабинет покупателя (ADR-0025) | 5 🟡 |
| `audit` | журнал аудита: неизменяемые записи действий без ПДн и секретов, выгрузка | 5 ✅ |
| `processing` | чеки и кассовый протокол: расчёт, резерв, подтверждение, отмена, возвраты | 4 🟡 |
| `identity` | сотрудники платформы, партнёров и мерчантов: учётные записи, членство в командах, роли и права, сеансы, журнал безопасности | 6 ✅ |
| `cabinet` | кабинеты на Filament поверх контрактов: консоль платформы, кабинет мерчанта с веб-кассой, кабинет партнёра | 6 ✅ |
| `till` | веб-касса: кассиры с PIN-кодами, смены на привязанных устройствах, оболочка кассы `/till` (ADR-0016); приложение кассы — `frontend/till` | 6 ✅ |
| `portal` | кабинет покупателя (ADR-0021): адрес программы на хосте кабинета, вход по коду с проверкой «Я не робот», вступление в программу, сеансы кабинета, страница ссылки «Отписаться», кабинет в MAX — вход по данным запуска мини-приложения бота (ADR-0023); приложение кабинета — `frontend/portal` | 7 🟡 |
| `support` | инструменты поддержки: ручные корректировки баллов с причиной, комментарием и лимитами по ролям; объединение дублей участников (ADR-0019) | 6 ✅ |
| `communications` | каналы мерчантов — их аккаунты у провайдеров (SMSC, SMS Aero), коды через них с запасным каналом, журнал сообщений, страница «Каналы» в кабинете, очередь сообщений участникам с правилами отправки, шаблоны автосообщений, статусы доставки, почтовый ящик мерчанта и страница «Почта», письма участникам, журнал сообщений в кабинете, пауза и настройки рассылок, очередь сообщений в кабинете и сообщения участнику в его карточке (ADR-0020), бот MAX мерчанта — его события, привязка MAX к картам участников, сообщения и коды сначала в MAX, вопрос о согласии «Реклама в MAX» (ADR-0023) | 7 🟡 |
| `reports` | отчёты программ (ADR-0026): собирает цифры из модулей, которые хранят данные, — чеков, леджера, участников — для кабинета и Management API сразу; сводка за период со сравнением с прошлым | 8 🟡 |
| `triggers` | автосообщения (ADR-0022): что и когда платформа ставит в очередь участнику сама — приветствие, первая покупка, новый уровень, уведомление о списании, поздравление с днём рождения вместе с баллами к нему, а раз в день программы — «Давно не были» тем, кто давно не покупал, и «Баллы скоро сгорят», — по включению мерчанта для программы; ссылка «Не вы?» уведомления (страница — кабинета покупателя) замораживает карту, завершает сеансы участника и пишет владельцам | 7 ✅ |
| `billing` | тарифы и счета | 10 |

Зависимости разрешены только в сторону ядра и публичных API других модулей; карта разрешённых зависимостей —
`deptrac.php`.

## Изоляция тенантов

```
HTTP-запрос / задача очереди
   │ ResetTenantContext (глобальный middleware) — контекст пуст
   │ аутентификация ключа кассы / партнёра → TenantContext::set(tenant_id)
   ▼
TenantContext ──► Context (логи, задачи очереди)
   │           └► PostgreSQL: set_config('app.tenant_id', …) в сессии соединения pgsql
   ▼
Eloquent: TenantScope (where tenant_id = …)      ← слой 1, приложение
PostgreSQL: RLS tenant_isolation для loyal_rls_tenant ← слой 2, база
```

- Таблица тенанта создаётся так: `TenantSchema::tenantKey($table)` (колонка `tenant_id` и ключ
  `(tenant_id, id)`), ссылки внутри тенанта — `TenantSchema::foreignWithinTenant()`, после создания —
  `Rls::enable('<table>')`. Архитектурный тест проверяет, что RLS включён на каждой таблице с `tenant_id`
  и что уникальные индексы начинаются с `tenant_id`.
- Модель таблицы тенанта наследует `Modules\Kernel\Database\TenantModel`.
- Контекст нельзя менять внутри транзакции: откат вернул бы старое значение в сессии PostgreSQL.

## Леджер баллов

Контракт — `Modules\Ledger\Contracts\Ledger` (операции) и `LedgerMaintenance` (работа по времени);
подробности модели — ADR-0003.

```
начисление ──► pending ──(активация)──► available ──(резерв)──► held ──(проведение)──► redemption
                                            │                     └──(отмена, TTL)──► available
                                            └──(сгорание)──► breakage
возврат товара: restore (redemption ──► available), reversal (available/pending ──► issuance)
```

- Каждая операция: блокировка трёх счетов участника (всегда в одном порядке) → проверка ключа
  идемпотентности → активация и сгорание наступивших по сроку партий → проводки → партии и их журнал.
- Партии тратятся от ближайшего сгорания; при отмене баллы возвращаются в те же партии.
- Объединение дублей (ADR-0019): `transferMember` отдаёт партии дубля основной записи с их сроками и журналом, балансы —
  через клиринговый счёт `transfer`; объединённый участник новых операций не принимает (`member_merged`), а возвраты
  и обслуживание его прошлого идут у основной записи.
- Плановые команды (`ledger:release-expired-holds`, `ledger:activate-due` — ежеминутно,
  `ledger:expire-due` — раз в 5 минут, `ledger:reconcile` — ежедневно в 03:00) находят работу системной
  ролью, а выполняют её от имени тенанта. Локально планировщик запускается `php artisan schedule:work`.
- `php artisan ledger:benchmark` — базовый замер горячего пути на локальной базе.

## Правила и расчёт чека

Контракты модуля `rules` — `ProgramRules` (базовые правила), `Campaigns` (акции), `PromoCodes`,
`CampaignUsage` (бюджеты и лимиты), `RuleSets` (снапшоты) и `Calculator` (движок); подробности — ADR-0007.

```
ProgramRules::publish ──┐                          rule_snapshots (v1, v2, … неизменяемы):
Campaigns::publish /    ├──► SnapshotPublisher ──► базовые правила + id версий активных акций
  activate / pause /    │    (блокировка программы,  │
  archive ──────────────┘     проверка набора)       │ RuleSets::effective(program, время покупки)
                                                     ▼
касса ──► строки + Catalog::resolve ──► Calculator(RuleSet, Basket, MemberSnapshot, CampaignState)
            промокоды ──► PromoCodes::check ─┐                          ▲
            участник ──► CampaignUsage::state ┴─────────────────────────┘
                                                     │
          CalculationResult: построчно скидка, списание, начисление; применённые акции; объяснение
                                                     │ подтверждение чека (этап 4)
                        CampaignUsage::record, PromoCodes::reserve/confirm; отмена — revert/release
```

- Конвейер движка: проверка и исключения каталога → выбор акций → скидки акций → бесплатные единицы по
  картам штампов → списание баллов → базовое начисление (процент уровня) → баллы акций → штампы.
- Движок не обращается к БД: результат зависит только от снапшота, чека, участника и состояния акций,
  поэтому расчёт повторяем, а «золотые» векторы (`app-modules/rules/tests/golden`) проверяют и порт на
  другой язык.
- Все суммы на уровне чека округляются один раз и распределяются по строкам методом наибольшего остатка:
  построчные значения всегда в сумме дают итог.
- `php artisan rules:benchmark` — замер движка на синтетическом чеке (без БД).
- Уровни (модуль `tiers`, ADR-0007): касса передаёт движку уровень участника (`Tiers::current`), после
  подтверждения чека сообщает оплаченную деньгами сумму (`recordPurchase`), при возврате и аннулировании —
  возвращённую (`recordReturn`); `tiers:review` ежечасно понижает уровни с истёкшим удержанием на ступень.
- Бонусы (модуль `bonuses`, ADR-0007): регистрация (`MemberEnrolled`) создаёт welcome- и реферальные
  награды, подтверждённый чек начисляет ждущие награды покупателя (`purchaseConfirmed`), возврат чека
  целиком и аннулирование их забирают (`purchaseCancelled`); `bonuses:birthdays` ежечасно начисляет баллы
  ко дню рождения.
- Баллы за действия (модуль `activities`, ADR-0017): сайт или приложение мерчанта сообщает о действии участника
  (`ActivityRewards::reward`), начисление держит строку действия — лимит участника за период, бюджет и одно
  событие считаются без гонок; отмена (`reverse`) забирает баллы по политике программы для возвратов.

## Кассовый протокол

Контракт — `Modules\Processing\Contracts\Checkout`; решения — ADR-0009. Маршруты `/api/v1/receipts…`
закрыты ключом кассы (`api.key:receipts`), лимитом (`throttle:runtime`) и, для изменений,
идемпотентностью (`api.idempotent`). Ключ смены веб-кассы `api.key` принимает только вместе с cookie его устройства
(ADR-0016).

```
касса                    processing                                   леджер / правила
─────                    ──────────                                   ────────────────
receipts:calculate ───►  участник, снапшот, каталог, промокоды ──────► Calculator (без изменений)
POST receipts ────────►  пересчёт + резерв ──────────────────────────► hold, CampaignUsage::record,
                         чек reserved (30 мин)                          PromoCodes::reserve
печать чека
:confirm ─────────────►  чек confirmed ──────────────────────────────► capture, accrue (активация,
                                                                        сгорание), PromoCodes::confirm
:cancel ──────────────►  cancelled (резерв) / voided (подтверждённый) ► release | reverse + restore, revert
/returns ─────────────►  доля эффектов возвращённых количеств ───────► reverseAccrual, restore, revert
```

Остальные эндпоинты Runtime API: чек кассы по номеру (`GET /receipts?number=&business_date=`), покупки участника
(`members/{id}/receipts`, скоупы `receipts` и `balances`; например, для возврата без номера чека), участники
(`members:lookup`, `POST /members`, `members:send-code`, коды приложения — отдельный скоуп `presentation_codes`, только у
ключей сайта, приложения и интеграций без `receipts`; действующие документы согласий с текстами — `GET /consent-documents`,
скоуп `members`), коды подтверждения (`verifications/{id}:verify`,
`receipts:send-redemption-code`), баланс и история (`members/{id}/balance`, `members/{id}/history`), офлайн-пакеты
(`receipts:batch`, `receipt-batches/{id}`; обработка — задача в очереди `offline`), баллы за действия (`GET /activities`,
`members/{id}/activities`, `activity-rewards/{id}:cancel` — скоуп `activities`, только у ключей сайта, приложения и
интеграций; ADR-0017).

## Сотрудники и доступ

Модуль `identity` (ADR-0013). Учётная запись одна на человека (`users`, e-mail зашифрован, поиск по слепому индексу
области `platform`); членство — на трёх уровнях: операторы платформы (`platform_staff`), команды партнёров
(`partner_memberships`) и команды мерчантов (`tenant_memberships`, под RLS).

```
запрос кабинета ──► сессия Laravel (зашифрованная cookie __Host-…)
                     │ identity.session:<panel> ── staff_sessions: открыт? простой панели? 12 часов?
                     ▼
                 StaffAccess::merchant(user, merchant)          (не трогает контекст тенанта)
                     1. запись активна, мерчант не закрыт
                     2. прямое членство (staff_tenant_memberships) — отключённое запрещает
                     3. иначе роль в команде активного партнёра мерчанта → роль мерчанта
                     4. (6d) доступ поддержки
                     ▼
                 MerchantAccess{role, via, permissions, readOnly}   readOnly — мерчант приостановлен
```

- Роли фиксированы, права — перечисления (`MerchantPermission`, `PartnerPermission`, `PlatformPermission`);
  чувствительные права требуют свежего подтверждения: кодом 2FA, а у кого второй фактор не подключён — паролем
  (второй фактор по желанию с 2026-10-22, поправка ADR-0013). Правила команд (последний владелец, своё членство,
  `team.manage_owners`) проверяет домен, а не интерфейс; командой мерчанта управляют только его собственные члены.
- Операторы платформы не состоят в командах партнёров и мерчантов (разделение обязанностей).
- Вход: Argon2id, политика паролей без правил состава, лимиты попыток (на e-mail с адреса, на адрес и — с 2026-10-22,
  когда второй фактор стал по желанию, — на e-mail отовсюду за час, кроме браузеров, где с этим e-mail уже входили;
  ключи — HMAC e-mail), общий лимит кодов второго фактора и проверок пароля в открытом сеансе, без remember-me; журнал безопасности учётной записи —
  `user_security_events`. Страницы с сессией вне разработки требуют жёстких настроек cookie
  (`RequireHardenedSessions` в группе `web`).
- Командная строка до кабинетов: `staff:create`, `staff:grant`, `staff:revoke`, `staff:disable`.

## Кабинеты

Модуль `cabinet` (ADR-0014): панели Filament над контрактами модулей, без ресурсов над чужими моделями.

```
/merchant/{id}/… ──► панель: identity.hardened (настройки cookie), cookie, сессия, CSRF,
                     │ заголовки безопасности (security.headers:panel)
                     │ Authenticate + identity.session:merchant        ← сотрудник и его сеанс
                     │ IdentifyTenant: MerchantWorkspace из Merchants   ← мерчант из URL (иначе 404)
                     │   canAccessTenant → StaffAccess::merchant
                     ▼ ApplyMerchantContext: TenantContext::set(id), CabinetPrincipal
                 страница / таблица Filament ──► контракты модулей (под RLS этого мерчанта)
запрос Livewire ──► состояние Livewire сброшено (ResetLivewireState); страницы нет на этом хосте или компоненты
                    разных страниц → 404 (RefuseUnroutedUpdates); иначе те же проверки повторяются
                    (постоянные middleware)
```

- `Kit` — общее для всех панелей: вход по паролю, с 2FA у тех, кто её подключил, и лимитами платформы, профиль, «Мои сеансы», «События
  безопасности», `CabinetPanelGate`, постраничный вывод `CursorPage` (`PagesByCursor`); `Platform` — консоль
  (`/console`, вне разработки — на своём хосте `CONSOLE_DOMAIN`), `Merchant` — кабинет мерчанта (на хосте `APP_URL`).
- Кабинеты ничего не отправляют во внешние сервисы (шрифт Filament, аватары с инициалами) и не держат данные
  тенантов вне RLS (без глобального поиска, уведомлений в базе, импорта и экспорта Filament).
- Изменение данных или чужого доступа из кабинета — `GuardedAction`: право при показе и при выполнении (отказ — 403
  в журнале аудита), подтверждение (код 2FA или пароль) для изменений консоли и чувствительных изменений, операция
  контракта, запись
  `CabinetAction` с объявленным вводом (ADR-0010, ADR-0014); своя учётная запись — в журнале безопасности.
- Просмотр персональных данных, который ничего не меняет (карточка участника, его покупки и история баллов, страница
  списка участников, «Объединить дубли», страница журнала сообщений), страница пишет в журнал аудита, когда его
  показывает, — `CabinetAuditor::recordRead`, методом `GET`, как `management.audit:reads`; тот же просмотр в течение
  минуты — одна запись. Поиск одного человека по номеру или адресу (журнал сообщений) — `recordLookup`: каждый поиск
  — своя запись, без того, что искали.

## Кабинет покупателя

Приложение кабинета (ADR-0021, 7f) — `frontend/portal`: TypeScript без зависимостей поверх клиента участника SDK и
исходников виджетов; компилятор — из SDK. `composer portal:build` собирает его, как приложение кассы, в папку сборки
`public/portal-app/<версия>` (не в git) рядом с `build.json` и service worker сборки; страницу `/p/<имя>` отдаёт модуль
`portal`, подставляя папку текущей сборки, а манифест, `/p/<имя>/sw.js`, значки карты и таблицу стилей цвета карты
`/p/<имя>/theme.css` (7f-4) — он же, вне группы `web`.

```
браузер покупателя (cookie __Host-loyal_portal-<имя>, HttpOnly, SameSite=Strict, путь /)
   │ /p/<имя>/: страница, вход по коду, вступление,    ← модуль portal (группа web, CSRF)
   │   сеансы плоскости участника для страницы
   ▼
виджеты карты, профиль + MemberClient SDK          ──► /api/member/v1: баллы, история, код для кассы,
(сеанс lms_ в памяти)                                   имя, день рождения, e-mail, согласия
                                                        (запрос своего хоста — по Sec-Fetch-Site)
```

## Веб-касса

Приложение кассы (ADR-0016) — `frontend/till`: TypeScript без зависимостей, компилятор — из SDK. `composer till:build`
собирает его в папку сборки `public/till-app/<версия>` (не в git) рядом с `build.json` и service worker сборки;
страницу `/till`, манифест и `/till/sw.js` отдаёт модуль `till`, подставляя папку текущей сборки.

```
браузер-устройство (cookie устройства, HttpOnly)
   │ /till: страница, привязка, устройство, смены,    ← модуль till (группа web, CSRF)
   │   итоги смены
   │   PIN кассира → ключ смены (только в памяти страницы)
   ▼
RuntimeClient SDK + свой fetch (cookie на свой источник) ──► /api/v1: участники, расчёт, чеки, возвраты
                                                              (ключ смены принимается только с cookie устройства)
```

Чеки и возвраты, сделанные ключом смены, помнят устройство (`receipts.device_id`, `receipt_returns.device_id`;
офлайн-пакет — `receipt_batches.device_id`): у устройства одна открытая смена, поэтому итоги смены
(`GET /till/shifts/current`, закрытие смены) — это итоги устройства между открытием и закрытием смены
(`Processing\Contracts\ReceiptStats`). Без связи касса копит покупки участников в очереди на устройстве
(`localStorage`, под идентификатором устройства, до 72 часов) и отправляет их пакетами `receipts:batch`, когда связь
возвращается; то, что она прочла после перезагрузки страницы, уходит после проверки кассиром. Хранилище браузера
стирается только у устройства, которое не заработает никогда (`till_device_revoked`, `Clear-Site-Data`). Пакеты, которые
никакое задание не обработало, задача `receipts:finish-batches` передаёт заданию снова, а через сутки завершает.
Камера планшета читает карты и QR-коды приложения участника там, где браузер умеет это сам (`BarcodeDetector`);
изображение остаётся на планшете.

## SDK и песочница

- **SDK** (ADR-0011) лежат в `sdk/`: `sdk/generator` (свой генератор в закрытом мире), `sdk/php` (`loyal/sdk`, PHP 8.2+,
  без зависимостей), `sdk/typescript` (`@loyal/sdk`, ESM, Node 22+). Из спецификаций генерируются типы, методы и
  метаданные операций и коды ошибок (`composer sdk:generate`, сгенерированное коммитится); ручное ядро отвечает за
  аутентификацию, идемпотентность, повторы, ошибки, пагинацию и проверку вебхуков. Поведение обоих SDK одинаково и
  закреплено контрактом `sdk/README.md` и эталонными векторами `sdk/conformance`, которые проверяются по
  спецификациям. PHP SDK проверяется и сквозь приложение: `Tests\Support\Sdk\KernelTransport` отправляет его
  запросы в ядро Laravel в тесте.
- **Песочница** (ADR-0012) — отдельное развёртывание той же сборки с `LOYAL_SANDBOX=true`: учётные данные с маркером
  `test_` (и в хешах), двойники контрактов `RealWorldEffect`, только тестовые телефоны и e-mail, код `000000`,
  заголовок `Loyal-Environment`. Тесты режима песочницы — `tests/Sandbox`.

## Соглашения

- Деньги и баллы — целые минимальные единицы (`Money`, `IntMath`, `Allocator`); float запрещён.
- Код на query builder читает строки через `Modules\Kernel\Database\Row` (типизированный доступ к колонкам),
  а время пишет через `Modules\Kernel\Time\SqlTime` (микросекунды и смещение не теряются).
- Неизменяемые колонки и append-only таблицы защищаются триггерами (`Immutability::columns`,
  `Immutability::appendOnly`).
- Время — только через `Modules\Kernel\Time\Clock`; хранение — `timestamptz` с микросекундами.
- Ошибки API — `application/problem+json` (`ProblemDetails`, доменные ошибки наследуют `ProblemException`).
- Логи проходят маскирование ПДн (`RedactSensitiveData` на каждом канале).
- Код и идентификаторы — на английском, документация и тексты интерфейса — на русском.
