portal/docs/superpowers/specs/2026-06-27-admin-command-center-design.md

Дизайн: SaaS-админка «Командный центр» Лидерры (иерархический дашборд)

Дата: 2026-06-27 Авторы: Дмитрий (владелец) + Claude Статус: концепция одобрена («в принципе пойдёт»), детализация для плана Макет: web/admin-dashboard-mockup.html (кликабельный, фирменные цвета Forest)

Проблема / цель

Текущая админка — плоский список разделов (Тенанты, Биллинг, Инциденты…). Владельцу нужен командный центр: верхний экран с главными цифрами и светофорами, с которого можно проваливаться в детали (иерархия + вложенность).

Иерархия (3 уровня)

• Уровень 1 — Командный центр: landing-экран, 4 плитки со светофором (🟢/🟡/🔴) и 3–4 главными числами. Период: Сегодня / 7 дней / 30 дней.
• Уровень 2 — Область: клик по плитке → разворот области (KPI + графики + таблицы «требует внимания»).
• Уровень 3 — Карточка: клик по строке → существующий экран (карточка тенанта, инцидент, проект поставщика). Переиспользуем, не пишем заново.

Фазы (по решению владельца — этапами)

• Этап 1: Командный центр (L1 каркас) + области Финансы и Здоровье (L2), с проваливанием в существующие экраны (L3).
• Этап 2: области Лиды и Заказ у поставщика (L2) — там есть новые расчёты.

Не делаем (YAGNI)

• Маржа/себестоимость — владелец явно отказался. Прибыль/cost не показываем.
• Не трогаем RLS/роли/схему для Этапа 1 — все цифры читаются из существующих таблиц.
• Не переписываем существующие detail-экраны — они служат Уровнем 3.

---

Архитектура

• Frontend: новый Vue-роут /admin (или /admin/dashboard) — landing «Командный центр» (компонент AdminDashboardView.vue), layout admin. Плитки — компоненты; клик меняет активную область (как в макете) или ведёт на существующий экран. Стек — Vue 3 + Vuetify 3 + Forest (Brandbook).
• Backend: новый AdminDashboardController с эндпоинтами агрегатов:
  • GET /api/admin/dashboard — сводка для L1 (все 4 плитки, по периоду).
  • GET /api/admin/dashboard/finance?period= — L2 Финансы.
  • GET /api/admin/dashboard/health — L2 Здоровье.
  • (Этап 2) GET /api/admin/dashboard/leads, GET /api/admin/dashboard/supplier-order.
• Эндпоинты — в группе Route::middleware(['saas-admin','admin-db']) (та же admin-группа; cross-tenant доступ через подключение pgsql_admin, уже введено фиксом 27.06 — см. spec 2026-06-27-admin-db-connection-path-a-design.md).
• Свежесть данных: запрос при открытии + кнопка «обновить»; период-тумблер пересчитывает агрегаты. Не realtime-push (не нужно).

---

Этап 1 — детальные требования

Плитка 💰 Финансы

L1 (сводка за период):

Метрика	Источник
Пополнения за период	SUM(balance_transactions.amount_rub) WHERE type='topup'
Списано за лиды	SUM(ABS(amount_rub)) WHERE type='lead_charge'
Активных клиентов	tenants WHERE status='active' AND deleted_at IS NULL
Новых за период	COUNT(tenants) WHERE created_at IN period
Светофор	🔴 если есть клиенты с balance_rub < 0; счётчик «N в минусе»

L2 (детали): KPI (пополнения / списано / чистый приток = пополнения−списания / клиентов в минусе); график пополнений vs списаний по дням (из balance_transactions group by день); таблицы:

• «🔴 Требуют внимания» — balance_rub < 0 ИЛИ остаток баланса < 3 дней по среднему 7-дневному списанию (runway). Клик → карточка тенанта (L3).
• «Топ по обороту» — клиенты по сумме пополнений за период.
• «Последние пополнения».

Пороги светофора: 🟢 нет минусов и ни у кого runway<3д; 🟡 есть runway<3д; 🔴 есть balance_rub<0.

Плитка ❤️ Здоровье портала

L1: общий светофор (худший из подсистем) + «открытых инцидентов N» + «последний сбой».

L2 — 6 подсистем, у каждой 🟢/🟡/🔴 + число + «когда»:

Подсистема	Источник	🔴 условие
Очереди / джобы	failed_jobs за сутки	>0 упавших (🟡), spike (🔴)
Планировщик	scheduler_heartbeats.last_run_at vs ожидаемый интервал	просрочка heartbeat
Синхрон с поставщиком	supplier_sync_runs последний status	failed/aborted
Сверка CSV (дрейф)	supplier_csv_reconcile_log последний status/drift_ratio	drift_alert
Вебхуки	failed_webhook_jobs WHERE resolved_at IS NULL	unresolved > порога
Инциденты	incidents_log открытые (resolved_at IS NULL)	есть high-severity

• лента «последние события эксплуатации» (из supplier_sync_runs / reconcile / backups). Клик по подсистеме → существующие экраны Инциденты / Интеграция с поставщиком (L3).

---

Этап 2 — детальные требования

Плитка 🎯 Лиды

L1: доставлено сегодня; зависших; нераспределённых; % доставки. Источники: project_routing_snapshots (expected_volume vs delivered_count), supplier_leads (processed_at IS NULL = необработанные; error IS NOT NULL), supplier_lead_deliveries, supplier_manual_sync_queue (pending). 🔴 условие: есть зависшие (необработанные supplier_leads старше N часов) или нераспределённые (доставлены поставщиком, но не легли клиенту). «Утечка» = закуплено у поставщика − доставлено клиентам (требует нового расчёта).

Плитка 📦 Заказ у поставщика

РЕАЛЬНЫЙ механизм (по коду, не выдумка):

• Спрос клиента по проекту = COALESCE(projects.effective_daily_limit_today, daily_limit_target), замораживается в project_routing_snapshots.daily_limit слепком в 18:02 МСК.
• В 18:05 МСК SyncSupplierProjectsJob группирует проекты по (signal_type, identifier) и считает заказ: order = max( max(спрос в группе) , ⌈ Σ(спрос) / 3 ⌉ ) (SupplierQuotaAllocator::computeOrder) — потому что лид перепродаётся до 3 клиентов.
• Заказ делится между площадками B1/B2/B3 (distributeForPlatform) и пишется в supplier_projects.current_limit (это «заказали по факту»), отправляется поставщику.
• Итог прогона — в supplier_sync_runs (groups_total / synced_ok / failed / …).

L1: Клиенты просят (Σ спроса/день); Надо по формуле; Заказали по факту; Групп с рассинхроном. L2 — таблица по группам/проектам: Клиенты просят (Σ snapshot.daily_limit по группе) → Надо по формуле (computeOrder) → Заказали по факту (Σ supplier_projects.current_limit по группе) → Совпадает? (🟢 факт=формула / 🔴 рассинхрон). 🔴 рассинхрон = «по факту» ≠ «по формуле» (лимит правили руками, или синхрон 18:05 не прошёл — supplier_sync_runs.status != ok / supplier_projects.sync_status='failed').

Новое: сейчас нет готовой сверки «заказ-по-формуле vs заказ-по-факту» (существующая CsvReconcile — про доставленные лиды, не про заказ). Этот расчёт делаем на лету (snapshot.daily_limit сгруппировать + computeOrder + сравнить с current_limit). Новой таблицы не требуется.

---

Тестирование

• Feature-тесты эндпоинтов AdminDashboardController (под admin-группой, trait SharesAdminPdo уже глобальный) — корректные агрегаты на сидов.
• Тесты порогов светофоров (минус баланса → 🔴; runway<3д → 🟡; sync failed → 🔴).
• Этап 2: тест расчёта «формула vs факт» для группы (mirror SupplierQuotaAllocator).
• Frontend (Vitest) — рендер плиток и переключение области (drill-down).

Открытые вопросы

• Кто ещё пользуется дашбордом, кроме владельца (роли)? — пока считаем только владелец/ops; отдельных ролей не вводим (saas-admin SSO ⏸ Б-1).
• Точные числовые пороги (runway дни, webhook unresolved, «зависший» возраст) — уточним при реализации; дефолты: runway<3д 🟡, webhook>0 🟡, зависший >2ч 🔴.