portal/docs/superpowers/specs/2026-06-18-prod-logic-map.md

# Карта логики и функционала боевого портала liderra.ru

**Снято:** 18.06.2026, построчным чтением **прод-кода** (`ssh liderra-prod`, `/var/www/liderra/app`), не локалки.
**Назначение:** прод-верная карта поведения портала как основа для приёмочного теста «глазами пользователя» перед передачей продажникам.
**Метод:** прочитаны все 28 контроллеров API, движок лидов/денег, все джобы, все сервисы, планировщик.

---

## 0. Суть в одном абзаце

Мультитенантный SaaS-CRM для **покупателей лидов**. Клиент заводит **проекты** (источники) → Лидерра агрегирует и **заказывает** у внешнего поставщика **crm.bp-gr.ru** → поставщик шлёт лиды **вебхуком** → роутер раздаёт каждый лид **до 3 клиентам** по региону/лимиту/балансу → создаёт **сделку** и **списывает деньги** по тарифной ступени. Изоляция клиентов — PostgreSQL **RLS** (`app.current_tenant_id`), supplier-джобы — роль `crm_supplier_worker` (BYPASSRLS).

---

## 1. Доступ (auth)

- Sanctum SPA (session-cookie), throttle на логине (5/15мин), 2FA TOTP опц.
- `register()` (`AuthController`) — **цепляет нового пользователя к `Tenant::first()`**, нового клиента НЕ создаёт. ⛔ **G1: самозаписи клиента нет** — новых клиентов заводят сид/админ/БД.
- 2FA: TOTP ±1 окно, 8 recovery-кодов (bcrypt), setup-wizard init→confirm (QR), disable/regenerate под паролем (`TwoFactorController`, `TwoFactorSetupController`).
- Сброс пароля: forgot (anti-enumeration unified-ответ + rate-limit), reset (Laravel Password facade, TTL 60мин) (`PasswordResetController`).
- RLS-контекст ставит middleware `tenant` (`SET app.current_tenant_id`).

## 2. Проект — что задаёт клиент (`StoreProjectRequest`, `ProjectController`, `ProjectService`)

- `signal_type` ∈ {site|call|sms}; site=домен (regex), call=`7XXXXXXXXXX`, sms=`sms_senders[]`(≤11) + опц `sms_keyword`; `regions[]` (1..89, пусто=вся РФ); `daily_limit_target` 1..10000; `delivery_days_mask` 1..127.
- Создание: preflight баланса (409 / `force_save_blocked`→`preflight_blocked_at`); `is_active=true`; **сразу `SyncSupplierProjectJob`** (online → реальный синк к поставщику).
- `signal_type` иммутабелен; `signal_identifier` editable (под `SupplierSnapshotGuard`). Уникальность имени и источника в тенанте.
- Правки источника/лимита/регионов/дней/паузы → resync. `delete`/смена источника блокируются guard'ом (grace до 21:00+24ч).
- bulk: pause/resume/delete/update_regions/update_days/update_limit (≤500).

## 3. Заказ поставщику (`SyncSupplierProjectJob`/`SyncSupplierProjectsJob`/`SupplierPortalClient`/каналы)

- Режим `system_settings.supplier_export_mode`: **online** (сразу полные параметры) / **batch** (каркас + ночной долив 18:05). **На проде = online.**
- Площадки (`resolvePlatforms`): **site/call→B1+B2+B3; sms+keyword→B2+B3; sms→B3** (B1+SMS запрещён constraint'ом).
- Группировка по (signal_type, identifier). **Заказ = `max(наиб.лимит, ⌈Σлимитов/3⌉)`** (`SupplierQuotaAllocator::computeOrder`), делится по площадкам largest-remainder (Σ==заказ).
- HTTP к `/admin/visit/rt-project-save` (сессия PHPSESSID+CSRF из Redis, обновляется `RefreshSupplierSessionJob` через Playwright). Регионы → коды поставщика (ГИБДД).
- Канал: ярус1 AJAX (`AjaxProjectChannel`) → ярус2 Playwright-форма (`FormProjectChannel`) → ярус3 ручная очередь (`FailoverProjectChannel` + алерт).
- Итог: rt-проекты **`B<n>_<identifier>`** в админке crm.bp-gr.ru ← «заказ глазами».

## 4. Слепок — ОСНОВА поставки (`SnapshotProjectRoutingJob`)

- **@18:02 МСК** пишет слепок на **завтра** (active + не-preflight_blocked + не-frozen + дни включают завтра). **ON CONFLICT по дате DO NOTHING** → в существующий слепок дня новый проект не добавит → нужен `snapshot:backfill`.
- Активная дата (роутер): до 21:00 МСК = сегодня, после = завтра.
- Поставщик фиксирует свой слепок в **21:00 МСК** и шлёт по нему весь следующий день. Канон-инвариант: правка до 18:00 → сегодня 21:00; после → завтра 21:00.

## 5. Поставка лида (`SupplierWebhookController`→`RouteSupplierLeadJob`→`LeadRouter`→`LeadDistributor`)

- `POST /api/webhook/supplier/{secret}`: secret(≥32) ИЛИ HMAC + IP-allowlist + rate 600/мин. Поля vid/project/phone(`7\d{10}`)/time(±24ч)/tag/phones[]. Идемпотентность по vid.
- `project`: `B[123]_…`→площадка, иначе **DIRECT**; rest: `7\d{10}`→call, домен→site, иначе→sms.
- Регион: **DaData→Россвязь→tag** (`LeadRegionResolver`, feature-flag `services.dadata.enabled`; кэш sha256(phone); бюджет-гард).
- Роутер (по слепку активной даты): кандидаты — остаток лимита>0, баланс>0, не frozen; B — через pivot `project_supplier_links`; **DIRECT — по signal_type+identifier** (без pivot/синка). Каскад: точный регион → вся РФ → fallback (подмена региона, `region_substituted`). Жребий по остатку лимита. **CAP=3** на лид.
- Каждому получателю (транзакция): lock tenant+project, recheck `is_active` под локом (R-09), лимит из слепка, `supplier_lead_deliveries` (одна поставка=раз) → **Deal** (city=реальный регион) → **списание** → инкременты delivered_today/month + snapshot.delivered_count → ActivityLog + уведомление.
- Сейф-нет: `CsvReconcileJob` (каждые 30мин) сверяет CSV-отчёт поставщика vs webhook-лиды, recovery пропущенных (`source=csv_recovery`), webhook-loss drift >5% → алерт, business-drift per (дата,тенант) shortfall >20% → алерт.

## 6. Деньги (`LedgerService` + биллинг-сервисы)

- Цена = ступень `pricing_tiers` по `(delivered_in_month+1)`. **Прод-ступени: T1 100×500₽, T2 200×450, T3 400×400, T4 800×350, T5 1500×300, T6 3000×270, T7 ∞×250** (`price_per_lead_kopecks`).
- frozen ИЛИ баланс<цены → `InsufficientBalanceException` → откат → автопауза проекта (`is_active=false`) + `ZeroBalancePausedMail` (rate 1/час).
- Списание: `balance_rub-=цена` (bcmath) + `lead_charges`(charge_source=rub) + `balance_transactions`(-amount) + `supplier_lead_costs`.
- `BalanceToLeadsConverter` (₽→лиды по ступеням), `RunwayCalculator` (affordable / средняя скорость 30д), `BalancePreflightService` (capacity≥required в лидах) — общий источник для дашборда/кошелька (F3/F5 починены 17.06, зависят от `pricing_tiers`, которые настроены).
- `topup` (`BillingTopupService`) — **заглушка** (мгновенный кредит, без шлюза, до Б-1). Счета (`invoices`) пусты (до Б-1).
- Карточка сделки `cost_kopecks` = снимок rub-списания (F2).

## 7. Заморозка (`BalancePreflightSweepJob` @18:00 + `BalanceFrozenReminderJob` @18:30)

- Для каждого тенанта: required на завтра vs capacity(баланс по ступеням). Не хватает → freeze (`frozen_by_balance_at` + `paused_at` на проектах) + письмо; хватает → unfreeze (с сохранением ручных пауз). online → sync.
- Повторные письма: reminder 24-48ч, final 72-96ч (throttle через `balance_freeze_log`).

## 8. Работа клиента (`DealController`, `DealBulkActionController`, `DealExportController`, уведомления, напоминания, отчёты, импорт)

- **Сделки**: лента (фильтры статус/проект/менеджер/поиск/даты, keyset/offset, RLS, is_test=false), карточка (+ до 50 событий + `cost_kopecks`), правка comment/manager/status → ActivityLog, ручное создание (без списания). Город = реальный регион.
- Воронка статусов (`StatusRuToSlugMapper`): **new / viewed / in_progress / won / lost** (Новая/Просмотрено/В работе/Сделка/Не реализовано). won = оплачено.
- bulk transition/destroy(soft)/restore (≤1000, аудит).
- Экспорт CSV/XLSX (OpenSpout стриминг): Телефон/Источник/Город/Статус/Комментарий/Поставлен, `;`+BOM.
- **Колокольчик** (`InAppNotification`): list/unread_count/mark-read/mark-all/delete; new_lead → inapp+push(default), email opt-in.
- **Напоминания** (`ReminderController`): CRUD + фильтры. ⛔ **G3: крона рассылки нет** (`reminders:dispatch-due` отсутствует в `console.php`) → уведомления по напоминаниям не шлются.
- **Отчёты** (`ReportJobController`+`GenerateReportJob`): deals_export/billing_summary/sources_summary/managers_summary × csv/xlsx/json (PDF stub→failed); квота 3, retry(3/7д)/cancel/delete, скачивание signed-URL 24ч.
- **Импорт CSV** (`ImportController`+`ImportLeadsJob`+`HistoricalImportService`): идемпотентный upsert через `webhook_dedup_keys`, **баланс не списывается**, мастер незнакомых статусов.
- **Деньги-лента** (`TenantChargesController`): read-only ledger (charged_at/deal_id/tier_no/charge_source/price_rub/balance_rub_after) + CSV.

## 9. Изоляция

- RLS на tenant-таблицах (`app.current_tenant_id`) + явный `where(tenant_id)` defense-in-depth. supplier-flow/SaaS-admin читают cross-tenant через `crm_supplier_worker` (BYPASSRLS).

## 10. Админ (SaaS) — провижининг и управление

- ⛔ **Создания тенанта НЕТ** (`AdminTenantsController`: index/show/updateBalance). **Баланс**: `PATCH /admin/tenants/{id}/balance` (set absolute, append-only + аудит). Тариф/заморозка/возврат (`AdminBillingController`).
- system_settings (`AdminSystemSettingsController`, reason ≥30 + hash-chain), pricing_tiers CRUD, supplier-prices (`AdminSuppliersController`), export-mode toggle, **список supplier_projects + bulk-delete у поставщика** (`AdminSupplierIntegrationController` — это и инструмент teardown rt-проектов).
- 152-ФЗ: инциденты + РКН-notify (`AdminIncidentsController`), обращения субъектов + анонимизация `PdErasureService` (`AdminPdSubjectRequestsController`).
- impersonation (`ImpersonationController`): 6-значный код. ⛔ **G7: email кода не шлётся, сессия не достроена**.
- API-ключи (`ApiKeyController`): один на тенант, scope read. ⛔ **G6: потребляющего endpoint нет**.
- Исходящие вебхуки (`WebhookSettingsController`): настройка+тест (SSRF-гард+DNS-rebind пиннинг). ⛔ **G2: реальной доставки событий нет** (pipeline не построен).

## 11. Планировщик (`console.php`) — 16 задач

00:00 reset-delivered-today · 1-е reset-monthly · daily partitions:create · Вс 03:00 drop-expired · 03:30 pd:scrub-soft-deleted · **18:00 preflight-sweep → 18:02 snapshot → 18:05 sync** · 18:30 frozen-reminder · hourly+17:45 refresh-session · 02:00 cleanup-inactive · hourly retry-failed · 30мин csv-reconcile · 10мин watch-failures · 04:00 verify-chains · hourly check-heartbeats. **Reminder-dispatch отсутствует (G3).**

## 12. Аудит / партиции / целостность

- Hash-chain (`AuditChainConfig`) на 6 audit-таблицах (per-tenant для tenant-таблиц / global для BYPASSRLS); writer = trigger `audit_chain_hash()`, verify = `audit:verify-chains` @04:00. UPDATE/DELETE заблокированы `audit_block_mutation`.
- Месячные партиции (`MonthlyPartitionManager`, 11 таблиц), heartbeat-трекинг (`SchedulerHeartbeatTracker`).

---

## 13. Go-live находки (после полного чтения)

| # | Находка | Статус | До продажи? |
|---|---|---|---|
| G1 | Нет самозаписи клиента (`register`→`Tenant::first()`) | подтв. | решить (онбординг вручную или wizard) |
| G2 | Исходящие вебхуки не доставляются | подтв. | если продаём как фичу — чинить |
| G3 | Напоминания не рассылаются (нет крона) | ✅ подтв. `console.php` | чинить (клиент-видимо) |
| G4 | Push мёртв (VAPID пустые) | ожидаемо post-MVP | к сведению |
| G5 | `topup` заглушка, счета пусты | до Б-1 | блок Б-1 |
| G6 | API-ключи без endpoint | подтв. | к сведению |
| G7 | impersonation email/сессия не достроены | подтв. | к сведению (админ) |
| OK | Ядро (вход/проекты/заказ/слепок/поставка/деньги/заморозка/сделки/экспорт/изоляция/колокольчик/отчёты/импорт) | работает | тестируем |

**Прод-состояние 18.06:** здоров, но спящий — 0 активных проектов, слепков нет с 03.06, 5 тенантов (реальный — lkomega/tenant 2, остальные сидовые), планировщик жив.

---

## 14. Фаза D — механика дочитана (весь прод-код прочитан построчно)

- **Supplier-каналы:** `FailoverProjectChannel` (ярус1 AJAX → ярус2 Playwright-форма → ярус3 ручная очередь+алерт), `AjaxProjectChannel`, `FormProjectChannel` (водит `manage-project.js`), `PlaywrightBridge` (Node-subprocess 75с), `RefreshSupplierSessionJob` (логин реальными кредами → сессия в Redis 6ч).
- **Supplier-import:** `SupplierProjectImporter` (разовое усыновление lkomega), `SupplierImportMapper` (src rt/bl/mt→B1/B2/B3; ГИБДД-регионы; sms split по `+`), `SupplierCsvParser` (Name;Tag;Phone).
- **Отчёты:** `GenerateReportJob` (→storage, expires 30д), 4 провайдера × csv/xlsx/json (pdf-stub→failed).
- **Импорт:** `HistoricalImportService` (идемпотентный upsert через `webhook_dedup_keys`, баланс не списывается), `CsvLeadsParser` (9 колонок, `Y/m/d H:i:s`), `ImportLeadsJob`.
- **Резолв региона:** `DaDataPhoneClient`/`RossvyazPrefixLookup`/`RegionTagResolver`/`DaDataBudgetGuard`.
- **Биллинг-математика:** `BalanceToLeadsConverter`/`RunwayCalculator`/`PricingTierResolver`/`BalancePreflightService`/`BillingTopupService`(stub)/`SupplierQuotaAllocator` (заказ=max(наиб,⌈Σ/3⌉)).
- **Reconcile/teardown:** `CsvReconcileJob`, `DeleteSupplierProjectJob` (авто-чистка rt-проектов), `CleanupInactiveSupplierProjectsJob` (TTL 180д).
- **ПДн/заморозка:** `PdErasureService`, `BalanceFrozenReminderJob`, `OperationsLogger`.
- **Модели:** `Tenant::requiredLeadsForTomorrow` (share-aware), `Project` (PostgresIntArray regions, supplier-FK+pivot), `SupplierProject`, `Deal` (composite PK `(id,received_at)`, партиции).
- **Команды (25):** snapshot:backfill/rebuild, reset-delivered-today/monthly, supplier:retry-failed/rekey-orphans, verify-chains, AuditRebuildChain, partitions:create/drop, billing:preflight-sweep/frozen-reminder, pd:scrub-soft-deleted, **reminders:dispatch-due** (существует!), и др.

## 15. Решающие выводы для теста (новое из фазы D)

- ⛔ **`imitation:seed` ЖЁСТКО запрещён на проде** (`environment('production')→FAILURE`). Сидером тест-клиентов на проде завести **нельзя**.
- ⛔ **Создания тенанта через продукт нет** → провижининг тест-клиентов только: **P1** прямой SQL (sudo postgres, escape) с маркером `TEST-` + скрипт удаления, либо **P3** переиспользовать сидовые тенанты (Demo/Компания 2/3/4; `lkomega`=tenant2 НЕ трогать).
- **G3 уточнён:** команда `reminders:dispatch-due` существует и работает, но **не подключена в `console.php`** → напоминания не рассылаются. Фикс = 1 строка `Schedule::command('reminders:dispatch-due')->everyMinute()`.
- **Рецепт инъекции (из сидера, для прода):** supplier_project (B2 site, `unique_key`=тест-домен) + project + pivot → `snapshot:backfill --date=сегодня` → `POST /api/webhook/supplier/{секрет}` c `raw_payload.project="B2_<тест-домен>"`. DIRECT: `project`=тест-домен без `B`-префикса (без pivot/синка). Любой путь требует строки слепка за активную дату.
- **Слепок-механика:** `snapshot:backfill` (идемпотентно) / `snapshot:rebuild` (DELETE+INSERT). Активная дата: до 21:00 МСК=сегодня, после=завтра.
- **Teardown:** удаление тест-проекта → `DeleteSupplierProjectJob` чистит rt-проект у поставщика; либо админ bulk-delete; тест-тенанты — DELETE по маркеру.

## 16. Финализированная тест-хартия (готова к writing-plans)

**Цель:** убедиться, что платящему клиенту портал реально работает, перед передачей продажникам.
**Метод (гибрид):** глазами в браузере на liderra.ru (Playwright + владелец на ключевых точках и на стороне crm.bp-gr.ru); поставка лидов — контролируемой инъекцией; деньги/изоляция — сверка в боевой БД (read-only).
**Матрица S0–S8:** S0 заказ дошёл до поставщика · S1 шеринг 1→3 (CAP) · S2 каскад региона · S3 лимит · S4 деньги/ступени · S5 заморозка/0-баланс · S6 пауза после слепка · S7 изоляция · S8 типы сигнала (site/call/sms/DIRECT).
**Доп. проверки:** G3 напоминания (подтвердить, что не шлются), отчёты, экспорт, импорт, колокольчик.
**Границы:** безопасность/атаки, нагрузка, юр — вне прогона.
**Критерий:** по каждому S «ожидали/получили/вывод», 0 расхождений в деньгах и изоляции; UX-находки отдельно.

## 17. Открытые решения для плана

1. Провижининг: **P1** (свежие SQL) или **P3** (сидовые).
2. Число клиентов и персоны (предложение: 6 — разные регионы + шеринг×3 + малый баланс под заморозку + пауза).
3. Реальные траты: только S0 (заказ, без живой поставки); остальное инъекцией.

---

## 18. Глубокое чтение движка (18.06.2026) — факты для приёмочного теста

Прочитано построчно с боевого: `SupplierQuotaAllocator`, `LeadRouter`, `LeadDistributor`, `SupplierPortalClient`, `RefreshSupplierSessionJob`, `SyncSupplierProjectJob`, `SupplierRegions`, конфиг очереди.

### 18.1 Формула заказа + деление по площадкам (`SupplierQuotaAllocator`)

- `computeOrder(limits) = max(max(limits), ceil(Σlimits / 3))`. `ceil(Σ/3)` — ёмкость шаринга (лид ≤3 раза); `max` — крупнейший клиент должен добрать.
- Заказ группы **делится** между площадками `distributeForPlatform` (largest-remainder): каждой `floor(order/N)`, остаток +1 первым по порядку. **Σ per-platform == order** (ни переплаты, ни недобора).
- **Сайт/звонок → 3 rt-проекта B1+B2+B3** (заказ÷3), смс+keyword → B2+B3, смс → B3. Пример: 7 клиентов по лимиту 10 → заказ = max(10, ⌈70/3⌉=24) = 24 → B1=8,B2=8,B3=8.
- Регионы/дни группы — объединение (union, dedup, sorted) eligible-на-дату проектов.

### 18.2 Каскад региона + жребий (`LeadRouter`, `LeadDistributor`)

- Источник eligibility — **слепок** `project_routing_snapshots` за активную дату (до 21:00 МСК сегодня, с 21:00 завтра). Из live `projects` — только `delivered_today`; из `tenants` — `balance_rub` + `frozen_by_balance_at`.
- Кандидат: `delivered_today < snap.daily_limit` И баланс>0 И не frozen. По **одному проекту на tenant** (`DISTINCT ON tenant_id`).
- **Каскад (3 фазы по убыванию точности):**
  - Фаза 1 — точное совпадение региона (`subject_code = ANY(snap.regions)`), только если резолвер дал код. `routing_step=1`.
  - Фаза 2 — «вся РФ» (`snap.regions = '{}'`), **добор недостающих слотов**, исключая уже выбранных tenant'ов. `routing_step=2`.
  - Фаза 3 — запасной канал (без фильтра региона), **только если фазы 1+2 пусты**; сделкам подменяется subject_code (`region_substituted`). `routing_step=3`.
  - ⚠️ «Вся РФ» — это **добор фазы 2**, а не равный кандидат с точным регионом: клиент «вся РФ» получит лид региона X только если точно-региональных не хватило на 3 слота.
- **CAP=3** (`LeadDistributor::CAP`) на лид.
- **Жребий внутри фазы при кандидатах > слотов** — взвешенный по остатку лимита без возврата: вес = `max(1, остаток)` (мелкие не отрезаются, шанс ∝ остатку). Кандидатов ≤ слотов → берутся все в SQL-порядке (детерминизм). **В проде Randomizer = CSPRNG (несидируемый)** → состав получателей недетерминирован.
  - **Вывод для теста:** проверяем ИНВАРИАНТЫ, не точный состав: каждый лид → ≤3 разных tenant'а; никто не превышает свой дневной лимит; за много лидов обслуживаются все шерящие; фаза региона корректна.

### 18.3 Регионы: Лидерра → поставщик (`SupplierRegions`)

- Лидерра нумерует субъекты по **конституционному порядку** (1..89); поставщик — по **ГИБДД-кодам**. Без перевода уходил чужой регион (Красноярский Лидерра-29 → у поставщика читался как Архангельск-29).
- `LIDERRA_TO_SUPPLIER` — **биекция на 79** кодов поставщика (79 листьев в дереве регионов формы поставщика).
- **10 субъектов Лидерры поставщик НЕ предлагает** → отбрасываются при переводе (warning): Московская обл.(56), Ленинградская обл.(53), Крым(13), Севастополь(84), ДНР(6), ЛНР(14), Запорожская(43), Херсонская(79), Ненецкий АО(86), Ямало-Ненецкий АО(89). Если это **единственный** регион проекта → у поставщика проект уходит **без гео-фильтра (вся РФ)**.
- NB: Москва-**город** (Лидерра 82 → поставщик 77) поддержана; Московская **область** (56) — нет. Санкт-Петербург (83→78) поддержан.
- **Покрытие 89 проверяется чтением этой таблицы, а не 89 клиентами.**

### 18.4 Одновременность канала (`SyncSupplierProjectJob`, очередь, сессия)

- **Очередь — ОДИН воркер:** systemd `liderra-queue.service` → один процесс `php artisan queue:work redis --tries=3 --max-time=3600 --timeout=300`. Шаблона multi-instance / Horizon / supervisor нет. ⇒ **задания синка выполняются последовательно, по одному.**
  - **Вывод:** «20 клиентов создают разом» → 20 заданий встают в очередь и идут друг за другом; поставщику бьют **последовательно, не параллельно**. Флуд поставщика через нормальное создание архитектурно невозможен. (Подтвердить живым наблюдением — один ли воркер реально.)
  - Нагрузочный тест = «как быстро один воркер разгребает завал из N заданий» (прогноз N/мин) + сбои/повторы/обновление сессии.
- `SyncSupplierProjectJob`: `tries=3`, `backoff=[15,60,300]`, роль `pgsql_supplier` (BYPASSRLS). Транзиентный недосбор площадки → throw → retry (partial-set recovery); escalation/window-defer — свой механизм, retry не вызывают.
- **Правка одного проекта пересчитывает и переписывает у поставщика ВСЮ группу** того же identifier (union регионов/дней, заказ группы) — online == ночной батч. При одном воркере это последовательно (без гонки), но визуально клиент видит результат с задержкой очереди.
- **Сессия поставщика:** Redis `supplier:session` (PHPSESSID+CSRF), TTL 6ч; обновление под замком `Cache::lock('supplier:session:refresh', 90)` block(95) — одновременных логинов нет, конкурентные 401 ждут на замке и переиспользуют свежую сессию. На 401/403 или HTML-логин-страницу (HTTP 200) → `dispatch_sync(RefreshSupplierSessionJob)` + один retry. На 5xx → transient. На HTTP 200 + `status:"Error"` → бизнес-ошибка портала.
- Online create — **по одному save на платформу** (single-flag, надёжный id через `listProjects`-матч); online update — через полный failover-канал; multi-flag только tier-1 AJAX.

**Итог для теста:** глубокая раздача (шеринг/каскад/лимит) проверяется ИНВАРИАНТАМИ на инъекции; заказ у поставщика для сайта = 3 rt-проекта; нагрузка ограничена одним воркером (последовательно) → безопасна; покрытие регионов — сверкой таблицы; 10 регионов без гео-фильтра — отдельная проверка.

---

## 19. Механизм распределения лида в сделки (`RouteSupplierLeadJob`) — построчно

Оркестратор: лид поставщика → до 3 сделок у разных клиентов + списания. `tries=3`, `backoff=60`, `timeout=60`, DB-роль `pgsql_supplier` (BYPASSRLS) для sharing-операций.

### 19.1 Вход и идемпотентность (анти-дубли)
- `lead==null` → **терминал**, return без исключения (иначе retry-шторм — был инцидент 25k записей по удалённому лиду №1).
- `processed_at != null` → skip (на retry не создаёт ghost-дубли сделок).
- Терминальная ошибка (`does not support` / `platform mismatch` / `no matching supplier_project`) → **fast-fail**: помечает `processed_at` + суффикс ошибки, return.

### 19.2 Парсинг поля `project` (`parseProjectField`)
- `B[123]_<rest>` → площадка; без префикса → **DIRECT** (весь project = identifier).
- `rest`: `^7\d{10}$` → call; чистый домен → site; **домен в свободном тексте** («заявка carmoney.ru/», «Платежи cabinet.caranga.ru/login») → site (извлекается домен, lowercase); иначе → sms.

### 19.3 Резолв региона (до цикла, вне транзакции)
- `LeadRegionResolver::resolve` (DaData ~150мс вне tenant-транзакции) → `resolved_subject_code` / `region_source` / `dadata_qc` / `phone_operator` пишутся на лид.
- Затем `LeadRouter::matchEligibleProjects(supplier, subjectCode)` → `LeadDistributor::selectRecipients` (≤CAP=3).

### 19.4 Создание сделки на получателя (`createDealCopyForProject`) — транзакция с `SET LOCAL app.current_tenant_id`
Порядок под локами:
1. `lockForUpdate` Tenant.
2. `lockForUpdate` Project + **recheck `delivered_today` под локом** (CV.11 BLOCKER #2: между слепком и транзакцией конкурентный webhook мог добить лимит).
3. **R-09:** recheck `is_active` под локом — паузнут после слепка → return false (не доставляем).
4. **R-04/R-06:** лимит из **слепка** (`project_routing_snapshots`, lockForUpdate), не live. Нет слепка → skip. `delivered_today >= snapshot.daily_limit` → skip.
5. **Merge с CSV-recovery:** если у webhook есть `vid` и есть csv-recovered сделка (тот же phone+project+tenant, без `source_crm_id`, за 24ч) → **слияние, БЕЗ второго списания**: UPDATE `source_crm_id`, INSERT delivery; регион улучшается, если webhook-резолв (dadata/rossvyaz) выше рангом тега. `received_at` НЕ меняется (partition key + FK lead_charges ON UPDATE NO ACTION — регрессия 26.05).
6. **Per-(supplier_lead, tenant) лок:** `supplier_lead_deliveries insertOrIgnore` → 0 если уже есть → return false (**одна поставка клиенту = один раз**).
7. **Deal::create:** `status='new'`, phone + `phones[]` (из payload), `received_at` (из payload.time), `subject_code` (на шаге 3 — подменён на регион клиента), **`city` = имя РЕАЛЬНОГО резолвнутого региона** (даже при подмене; null → пусто), `region_substituted = (routing_step===3)`.
8. **`LedgerService::chargeForDelivery`** в той же транзакции → `InsufficientBalanceException` → **полный откат** (ни сделки, ни charge).
9. Инкременты: `delivered_today`, `delivered_in_month`, `snapshot.delivered_count`.
10. `ActivityLog` (EVENT_DEAL_CREATED) + `PdAuditLogger` (152-ФЗ) + `notifyNewLead`.

### 19.5 Недостаток баланса → авто-пауза (`handleInsufficientBalance`)
Транзакция уже откатилась → `UPDATE projects.is_active=false` через `pgsql_supplier` (BYPASSRLS) + `ZeroBalancePausedMail` rate-limit **1/час/tenant** (Redis SETNX `Cache::add`) + log. return false (цикл продолжает раздачу остальным).

### 19.6 Аудит резолва + сбои
- `logRegionResolution`: одна строка на лид в `lead_region_resolution_log` (телефон маскирован `7916***4567`); **fail-safe** — сбой записи НЕ роняет доставку (revenue-critical).
- Все получатели упали (`createdCount==0` && все в `failures`) → throw → retry. `failed()` → `failed_webhook_jobs` (tenant_id=null) + `supplier_lead.error`.
- Частичный успех → `processed_at` + `deals_created_count`, целиком не падает.

**Итог для теста (пункт 4 «Распределение»):** проверяем инварианты — один лид раз (vid), одна поставка клиенту раз, merge без второго списания, CAP≤3, лимит/пауза под локом, атомарный откат при нехватке баланса + авто-пауза, город = реальный регион при подмене, следы (ActivityLog/PdAudit/уведомление), retry/failed-поведение.

---

## 20. Заморозка по балансу (`BalancePreflightSweepJob` + `BalanceFrozenReminderJob`) — построчно

Пять писем баланса: `ZeroBalancePausedMail` (мгновенная пауза в доставке, 1/час), `BalanceFrozenMail` (вечерняя заморозка), `BalanceUnfrozenMail` (разморозка), `BalanceFrozenReminderMail` (24–48ч), `BalanceFrozenFinalMail` (72–96ч).

### 20.1 Два триггера заморозки
- **Мгновенный (в доставке, §19.5):** баланс < цены лида → откат + `is_active=false` + `ZeroBalancePausedMail`, rate 1/час/tenant (Redis SETNX).
- **Вечерний sweep @18:00** (`BalancePreflightSweepJob`, команда `BillingPreflightSweepCommand`): бежит в системном контексте, `SET LOCAL app.current_tenant_id` пер-тенант (chunk 200). Для каждого: `requiredLeadsForTomorrow` (share-aware) vs ёмкость по ступеням (`BalancePreflightService::evaluate` → `PreflightResult`). **Смотрит на ЗАВТРА** — тенант может замёрзнуть с положительным балансом, если на завтра не хватает.

### 20.2 Переходы (идемпотентно)
- **active→frozen** (`!passes && !frozen`): `frozen_by_balance_at=now`; **все непаузнутые проекты → `paused_at=freezeAt`** (R-13 — даёт `SupplierSnapshotGuard` зацепку: пока заморожен, клиент не удалит/не сменит источник); log `frozen`; `BalanceFrozenMail`; online → sync per-project.
- **frozen→active** (`passes && frozen`): захват `frozenAtWas`; `frozen_by_balance_at=null`; **снятие паузы ТОЛЬКО у проектов с `paused_at >= frozenAtWas`** (которые паузила заморозка). **Ручные паузы клиента ДО заморозки (`paused_at < frozenAtWas`) сохраняются.** log `unfrozen`; `BalanceUnfrozenMail`; sync.
- Стабильное состояние → ничего (анти-спам).
- ⚠️ freeze/unfreeze в online диспатчит `SyncSupplierProjectJob` по каждому активному не-blocked проекту → пачка единственному воркеру (капасити-связь, слой D).

### 20.3 Повторные письма (`BalanceFrozenReminderJob` @18:30, `BillingFrozenReminderCommand`)
- Только замороженные тенанты; `hours = diffInHours(frozen_by_balance_at)`. Окна: reminder 24–48ч, final 72–96ч.
- Throttle: marker-row в `balance_freeze_log` (`reminder_sent`/`final_sent`), один на тип за 5 дней (`alreadySent`).
- **Пере-оценка `PreflightResult`** → письмо показывает АКТУАЛЬНЫЙ дефицит (частичное пополнение отразится).

**Итог для теста (пункт 9):** мгновенная пауза 1/час; вечерняя заморозка смотрит на завтра; разморозка не трогает ручные паузы; guard при заморозке; идемпотентность (анти-спам); повторные письма с актуальным дефицитом + throttle. Гоняется командами вручную + бэкдейт `frozen_by_balance_at` для окон reminder/final.

---

## 21. Блокировка / preflight (share-aware) — построчно (хитрая логика)

Три уровня «блокировки» + хитрый расчёт `required`.

### 21.1 Три уровня блока
1. **Блок лида получателю (per-lead, §19.4):** лид НЕ доходит клиенту, если — лимит из слепка исчерпан (`delivered_today ≥ snapshot.daily_limit`), `balance_rub ≤ 0` (не кандидат), `frozen_by_balance_at` (frozen), пауза под локом (R-09), нет слепка, уже доставлен (`supplier_lead_deliveries`), или баланс < цены → откат + автопауза.
2. **Заморозка тенанта (вечерний sweep, §20):** `required(завтра) > capacity(баланс→лиды)` → freeze.
3. **Блок создания проекта (preflight):** то же сравнение при создании — не хватает → 409 / `force_save_blocked` → `preflight_blocked_at`.

### 21.2 `Tenant::requiredLeadsForTomorrow` (R-19, share-aware) — ХИТРОСТЬ
`required` — НЕ сумма дневных лимитов клиента, а сумма его **пропорциональных долей** в заказах групп. Для каждого активного проекта:
- Если `signal_type` ∉ {site,call,sms} (legacy webhook-only) → полный `daily_limit_target`.
- Иначе: находит **всю группу** того же источника (по всем тенантам через `pgsql_supplier` BYPASSRLS): site/call → тот же `signal_identifier`; sms → первый sender + (keyword|NULL).
  - `Σ` = сумма `daily_limit_target` группы; `max` = наибольший.
  - `groupOrder = max(max, ⌈Σ/3⌉)` (= заказ поставщика).
  - **`share = ⌈groupOrder × (лимит_проекта / Σ)⌉`** → `total += share`.
- Edge: группа пуста в pgsql_supplier-вью (cross-conn race) → консервативно полный лимит.

**Следствие:** шерящий клиент нуждается в **малой доле** (труднее заморозить); одиночка на источнике — полный лимит. **Тест заморозки/блока (B-измерение) должен считать ожидаемый `required` ПО ЭТОЙ формуле доли, не по сырому лимиту.**

### 21.3 Capacity / converter / runway
- `BalancePreflightService::evaluate`: `required ≤ 0` → passes; иначе `capacity = BalanceToLeadsConverter.convert(...)['leads']`; `passes = capacity ≥ required`; `deficit = required − capacity`.
- `BalanceToLeadsConverter::convert(balanceRub, deliveredInMonth, tiers)`: сколько лидов купит баланс, проходя ступени с учётом уже доставленных в месяце (bcmath, копейки). Возвращает leads + breakdown + current_tier + next_tier. Источник и для калькулятора «хватит на лиды», и для preflight.
- `RunwayCalculator::daysLeft(tenantId, affordableLeads)`: `affordable ≤ 0 → 0`; `lead_charges за 30д = 0 → null` (нет истории); иначе `floor(affordable / (leads30/30))`. Единый источник «хватит на дни» для дашборда и кошелька (F3).

**Итог для теста (блокировка):** ожидаемые freeze/preflight-блоки считать через share-aware `required` vs tier-aware `capacity`; per-lead блоки — по 7 условиям §19.4. На объёме лидов на шеринг-источнике видно красиво: распределение (жребий ∝ остатку), списания (ход по ступеням), блоки (лимит/баланс/заморозка по доле).