portal/docs/superpowers/specs/2026-06-27-admin-db-connection-path-a-design.md

Дизайн: восстановление доступа SaaS-админки к данным после переезда на Managed PG (Путь А)

Дата: 2026-06-27 Автор: Claude (контроллер) + Дмитрий (владелец) Статус: approved (способ A), готов к плану

Проблема

После переезда боевой базы на управляемый PostgreSQL (Путь А, 26.06.2026) SaaS-админка liderra.ru/admin в разделах «Тенанты» и «Биллинг» перестала показывать данные.

Уточнение по факту кода (27.06.2026)

Первичный замер делался по голым таблицам под ролью crm_app_user и переоценил масштаб. По факту кода admin-контроллеры делятся на две группы:

• Уже используют bypass-подключение pgsql_supplier (роль crm_supplier_worker, видит все тенанты) → работают: AdminIncidentsController, AdminPdSubjectRequestsController, AdminSupplierIntegrationController, ImpersonationController.
• Читают глобальные (не tenant-scoped) таблицы под default-подключением → работают: AdminPricingTiersController (tariff_plans), AdminSystemSettingsController (system_settings), AdminSuppliersController (supplier_projects/project_suppliers).
• Ходят под default-подключением pgsql (роль crm_app_user) по tenant-scoped таблицам → СЛОМАНЫ:
  • AdminTenantsController — список тенантов, карточка тенанта (users/projects/deals/balance), правка баланса (updateBalance).
  • AdminBillingController — агрегаты биллинга, refund, смена статуса/тарифа.

Замер таблиц (боевая база)

Таблица	crm_app_user (default)	bypass-роль	Затронутый раздел
tenants	0	6	Тенанты, Биллинг — СЛОМАНЫ
balance_transactions	0	919	Биллинг — СЛОМАН
deals / projects	0 / 0	1016 / 122	Карточка тенанта — СЛОМАНА
tariff_plans	4	4	Тарифная сетка — ок
system_settings	46	46	Система — ок
supplier_projects	401	401	Проекты поставщика — ок

Данные целы (деньги/сделки/клиенты на месте) — сломан только доступ двух контроллеров, ходящих под crm_app_user.

Корень

При переезде BYPASSRLS заменён на политики srv_bypass (cmd=ALL, qual=true), выданные ролям crm_admin_user, crm_supplier_worker, crm_migrator. Админка же ходит в базу под crm_app_user, которая:

• подпадает под tenants_self_isolation (id = current_setting('app.current_tenant_id')) → на админ-страницах GUC не выставлен → 0 строк;
• не имеет табличного GRANT на чисто-админские таблицы (incidents_log, saas_admin_audit_log, impersonation_tokens, pd_subject_requests) → 42501.

Роль crm_admin_user — штатно предназначенная для админки — уже полностью готова на кластере:

• политика srv_bypass (видит все тенанты);
• SELECT/INSERT/UPDATE на все админ-таблицы (проверено has_table_privilege);
• canlogin=true, пароль в Lockbox liderra-secrets и /home/ubuntu/liderra-secrets.txt (ключ crm_admin_user).

Не хватает единственного: подключения в приложении под этой ролью.

Решение (способ A — connection swap на входе в админку)

1. Новое подключение pgsql_admin

В config/database.php добавить pgsql_admin = базовый $pgsqlConnection

• override username/password из новых env-ключей DB_ADMIN_USERNAME=crm_admin_user, DB_ADMIN_PASSWORD=<из Lockbox>. Паттерн идентичен существующему pgsql_supplier.

2. Переключатель только для админ-группы

Новый middleware UseAdminConnection (alias admin-db) добавляется в группу Route::middleware('saas-admin') после saas-admin (EnsureSaasAdmin), на время обработки запроса делает DB::setDefaultConnection('pgsql_admin') и восстанавливает прежнее значение в finally.

• Восстановление в finally обязательно: в Pest-тестах несколько «запросов» идут в одном процессе → без restore default-подключение утечёт в соседние тесты.
• Tenant-facing запросы — отдельная middleware-группа (tenant) → остаются на pgsql (crm_app_user) → изоляция клиентов не тронута.
• Переключатель меняет default, поэтому чинит ровно те контроллеры, что ходят под default (AdminTenantsController, AdminBillingController) — это и есть сломанный набор. Контроллеры, явно прибитые к pgsql_supplier (Incidents/Pd/SupplierIntegration/Impersonation), переключатель не трогает — они уже работают и продолжат работать под своей ролью.

Middleware ставится после saas-admin, чтобы проверка impersonation/гейта прошла до смены подключения.

Швы (обязательны к проверке в плане)

1. Изоляция клиентов не должна пострадать. Обычный кабинет остаётся на crm_app_user. Проверить агентом rls-reviewer + регресс-тест: tenant-facing эндпоинт видит только свой тенант.
2. Hardcoded-подключения (учтены). AdminIncidentsController, AdminPdSubjectRequestsController, AdminSupplierIntegrationController, ImpersonationController явно прибиты к pgsql_supplier — переключатель их не затрагивает, они уже работают. Это осознанно оставляем как есть (YAGNI; рабочий код не трогаем). Известный долг: набор admin-доступа неоднороден (часть под crm_supplier_worker, новые два — под crm_admin_user) — унификация на crm_admin_user возможна позже отдельным безопасным шагом. Проверить отсутствие protected $connection в моделях, которые читает AdminTenantsController/AdminBillingController (Tenant, BalanceTransaction) — если есть пин на pgsql, он обойдёт переключатель (на момент аудита — нет).
3. Фоновые джобы из админки выполняются в worker'е под обычным default (pgsql/pgsql_supplier) — убедиться, что admin-действия, ставящие джобы, не полагаются на admin-подключение внутри джобы.
4. Тестовый шов (главный). dev/test-база работает под суперпользователем postgres, который игнорирует RLS → баг не всплывал в тестах. Нужен тест, реально проверяющий поведение под ролями (через SET ROLE / отдельное подключение), иначе фикс «зелёный в тестах, мёртвый на проде».
5. Запись под admin-ролью. Права INSERT/UPDATE подтверждены; протестировать реальную правку (баланс тенанта, system_settings, запись saas_admin_audit_log).
6. Impersonation. EnsureSaasAdmin запрещает вход в админ-зону при активной impersonation — переключатель не должен это ослаблять (ставить ПОСЛЕ проверки impersonation в цепочке middleware).

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

Автоматизированное (портативно, любой стенд):

• Connection-config: pgsql_admin определён, username = crm_admin_user (через env с fallback на default — как у pgsql_supplier).
• Middleware unit: UseAdminConnection ставит default на pgsql_admin и восстанавливает прежнее значение после запроса (включая ветку с исключением).
• Routing: admin-группа /api/admin/* имеет middleware admin-db в пайплайне.

Шов №4 (честно): dev/test-база под суперпользователем postgres игнорирует RLS, поэтому факт «cross-tenant данные видны» автотестом на dev не доказывается. Реальная проверка — на боевой/изолированной базе под ролями:

• live-приёмка: тот же замер «default-роль vs admin-роль» (скрипт из раздела «Проблема») после выката показывает, что AdminTenantsController под crm_admin_user видит все тенанты;
• изоляция: tenant-facing эндпоинт под crm_app_user по-прежнему видит только свой тенант (regress);
• write: правка баланса тенанта проходит и пишет saas_admin_audit_log.

Выкат и откат

• Код: gitea → прод (rsync overlay, БД не трогается).
• Прод-настройка: добавить DB_ADMIN_USERNAME/DB_ADMIN_PASSWORD в .env (из Lockbox), php artisan config:cache.
• Перед выкатом — отдельное разрешение владельца + prod-deploy-validator.
• Откат: убрать middleware-переключатель (поведение возвращается к текущему, которое и так сломано) / revert коммита.

Не делаем (YAGNI)

• Не трогаем настоящий saas-admin SSO (Yandex 360) — отдельный гейт Б-1/DO-4.
• Не меняем RLS-политики и роли на кластере — они уже корректны.
• Не правим nginx-дверь админки.