Админ-панель: все пути и контракты API

Документация по всем путям встроенной админ-панели telesrv — адресам страниц (SPA) и API-маршрутам, которые за ними стоят. Сервер панели живёт в cmd/telesrv-admin, маршруты объявлены в функции (*server).routes() (server.go:50).

Панель — это обычный HTTP-сервер: он отдаёт собранный фронтенд (/) и JSON-API под префиксом /api/. Все API-пути требуют сессию (cookie), а все изменяющие запросы — ещё и CSRF-токен. Многие маршруты дополнительно проверяют права оператора (permission).

Как пользоваться этим документом

• Для каждого GET-эндпоинта указаны параметры запроса (query) и краткая форма ответа.
• Для каждого POST-эндпоинта в блоке /api/actions/* и решений верификации указано тело запроса (JSON). Все они разделяют общие поля (см. ниже) плюс свои специфичные поля.
• int64 в JSON можно передавать и как число, и как строку (например, "user_id": "123" или "user_id": 123) — сервер принимает оба варианта (flexInt64). flexUnix принимает Unix-секунды или дату 2006-01-02 / RFC3339.
• Все изменяющие запросы идут в Admin API. Ответ команды — либо {"status":..., "message":..., "command_id":...} при успехе (HTTP 200), либо {"error":..., "code":...} при ошибке. Конфликт оптимистичной блокировки — 409.

Аутентификация и сессия

Сессия живёт в подписанной cookie (TTL по умолчанию 12 часов), серверного хранилища сессий нет. Все запросы, кроме GET/HEAD/OPTIONS и /api/login, обязаны предъявить:

• cookie telesrv_admin_csrf;
• заголовок X-CSRF-Token с тем же значением;
• Origin, совпадающий с хостом (если Origin присутствует).

Нарушение любого из трёх условий — 403 Forbidden.

Права и их проверка

Панель различает обычную авторизацию (requireAuthAPI) и проверку права (requirePermission). Имена прав совпадают со строками в TELESRV_ADMIN_UI_PERMISSIONS, и список ниже — это ровно то, что assignablePermissions() (cmd/telesrv-admin/security.go) предлагает экрану управления операторами. Право, которого нет в этом списке, невозможно выдать именованной учётной записи оператора.

Заголовки колонок и подписи в них — английские строки из nav.ts и permissionLabels (web/src/permissions.tsx), и они не переводятся: экран прав выводит их как есть, поэтому в русском интерфейсе они остаются английскими. Таблицы ниже приводят их дословно, чтобы документ описывал то, что видит оператор, а не то, что было бы идеально.

Большинство разделов — это пара read/manage: право на чтение открывает страницу, право на управление нужно её кнопкам. Панель проверяет read на GET-эндпоинтах страницы, а manage — на каждое действие, поэтому выданное только accounts.read даёт рабочий экран аккаунтов в режиме чтения.

Часть прав намеренно независима от своего раздела: verification.review и botverification.review выдаются отдельно, потому что это две разные очереди поверх разных таблиц, а verification.revoke проверяется в дополнение к verification.review. admins.manage — единственное право, способное выдать любое другое, поэтому оно не подразумевается ничем, а audit.read относится к надзорным правам, а не к тем разделам, которые охватывает.

Список прав сессии возвращается в /api/session, и фронтенд по нему решает, какие разделы показывать в боковом меню и какие страницы закрыть — см. раздел «Навигация и права в интерфейсе» ниже.

Навигация и права в интерфейсе

Боковое меню панели, вкладочные полосы внутри страниц и таблица маршрутов — три представления одного объявления: cmd/telesrv-admin/web/src/nav.ts. В нём перечислены все разделы, относящиеся к ним пути и право, которое каждый из этих путей проверяет на сервере. Layout.tsx рисует из него боковое меню и, над каждой страницей, полосу вкладок активного раздела через SectionTabs.tsx, который берёт оттуда список вкладок раздела; Routes.tsx задаёт ему ровно один вопрос — routePermission(path) — и проверяет права одним местом на всю поверхность.

Два следствия, о которых стоит знать до правок:

• Раздел показывается, если у сессии есть право хотя бы на одну его вкладку, а ссылка ведёт на первую доступную вкладку. Оператор с одним лишь prices.manage увидит одну строку Economy, открывающуюся на Bot prices. Раздел, у которого доступна единственная вкладка, вообще не рисует полосу вкладок.
• Страница не может быть показана в меню и затем ответить 403. До того как появилась эта таблица, двенадцать пунктов бокового меню отрисовывались безусловно, хотя все эндпоинты за ними были закрыты: оператор без accounts.read всё равно видел Accounts, и нажатие давало голый 403 вместо объяснения от PermissionDenied. Теперь проверка берётся из тех же строк, которые читает меню.

Как добавить страницу в панель

По порядку — пропуск любого шага и приводит ровно к тому дрейфу, ради которого этот раздел существует:

1. Решите, это новый раздел или вкладка существующего. Если страница соседствует с уже имеющейся — делает ту же работу над другим срезом данных, — это вкладка, а не вторая строка меню. В Economy уже живут Stars balances, Premium, Bot prices, Donations и Account Rating, в Server — Storage, Operators и журнал аудита. Новая строка меню — только для действительно новой работы.
2. Добавьте её в nav.ts вместе с правом, которое проверяет её маршрут на сервере. Если нужно право, которого ещё нет, добавьте его в permissions.tsx (permissionLabels и permissionGroups) и в assignablePermissions() в security.go: право, которого нет в assignable-списке, невозможно выдать, и экран операторов его не покажет.
3. Добавьте маршрут в Routes.tsx. Не оборачивайте его в PermissionGate: проверка уже применяется из routePermission, и именно ручная обёртка позволяла накапливаться старым пробелам.
4. Добавьте страницу в web/src/pages/ и примите проп navigate, если он нужен. Не рисуйте в ней <SectionTabs>: оболочка (Layout.tsx) уже выводит полосу вкладок активного раздела над каждой страницей из nav.ts, и страница со своей полосой покажет две. gen_admin_panel_doc_tables.py --check падает на любом <SectionTabs в pages/.
5. Переведите её. Каждая пользовательская строка идёт через useI18n() и получает запись во всех трёх языковых блоках i18n.tsx.
6. Пересоберите бандл. В cmd/telesrv-admin/server.go стоит //go:embed web/dist, поэтому в сборке вне Docker отдаётся именно web/dist. Выполните npm run build и закоммитьте результат вместе с удалением старых хэшированных файлов. Изменение в src без пересобранного dist не доедет до пользователя.
7. Перегенерируйте таблицы этого документа: python3 scripts/gen_admin_panel_doc_tables.py --write.

Генерируемые таблицы

И таблица разделов ниже, и таблица прав выше порождаются скриптом scripts/gen_admin_panel_doc_tables.py из nav.ts, permissions.tsx и security.go. Однажды они сильно разошлись с кодом — целого десятка маршрутов в них просто не было, — потому что их никто не проверял. Не правьте их руками: правьте исходники и перезапускайте скрипт. --check возвращает ненулевой код, когда таблицы устарели, — именно этот вызов имеет смысл вызывать в CI.

Страницы интерфейса (SPA)

SPA-роуты декларативны: любой неизвестный путь фронтенда отдаётся сервером как / (index.html), а роутер решает, что рендерить (web/src/pages/Routes.tsx). Таблицы ниже порождены nav.ts — тем самым объявлением, которое читают и меню, и роутер.

Вкладки разделов

Все вкладки всех разделов с правом, которое проверяет их маршрут. /statistics — единственный путь без вкладки: графики статистики перенесены в обзор, и старый URL по-прежнему приводит туда, а не в 404 по закладке.

Раздел с одной доступной вкладкой не рисует полосу вкладок, и его ссылка в меню ведёт прямо на неё.

Детальные и вложенные маршруты

Эти пути принадлежат перечисленному выше разделу, но не являются его вкладками: это конкретная запись внутри него, и каждая проверяется тем же правом, что и список.

/premium — постоянный алиас /monetization. /messages — алиас /messages/private.

Несуществующий API-путь возвращает 404 {"error":"api route not found"}; любой неизвестный путь фронтенда отдаётся как /.

Соглашения ответов

• Успешные чтения — 200 + JSON; файлы (аватары, анимации, превью) — сам файл.
• Ошибки — JSON вида {"error": "...", "code": "..."} с соответствующим HTTP-статусом.
• 401 — нет/просрочена сессия; 403 — нарушение CSRF/Origin или не хватает права (в requirePermission к телу добавляется поле permission); 409 — конфликт оптимистичной блокировки (кейс модерации, верификация); 502 — Admin API недоступен.
• Ошибки команд, ушедших в Admin API, возвращаются как {"status": ..., "message": ..., "error": ...}.

Общие поля команд (POST /api/actions/*)

Каждый изменяющий запрос несёт в теле:

API: дашборд и хранилище

API: аккаунты

API: каналы и супергруппы

API: боты и рассылки

API: медиа-каталоги

API: аудит сообщений

API: звёздные подарки и коллекционки

API: Premium

Все маршруты раздела требуют права premium.manage (проверяется и на уровне панели, и на стороне Admin API).

API: модерация

Все чтения пробрасывают query-параметры в Admin API как есть (/v1/moderation/...). Решения — POST (см. ниже).

API: официальная верификация

Все маршруты требуют права verification.review. Чтения идут напрямую из PostgreSQL, решения — всегда через Admin API (журнал команд, статусная машина, оптимистичная блокировка).

Конфликт «решил другой модератор» возвращается как 409 Conflict.

API: сторонняя (ботовая) верификация

Отдельный механизм с отдельными таблицами, правами и маршрутами. Чтения и решения очереди требуют botverification.review; управление верификаторами, каталогом иконок и снятие меток — botverification.manage.

API: действия над аккаунтами

Все маршруты — POST /api/actions/..., требуют сессию и CSRF. Тело запроса всегда содержит общие поля команд (command_id, reason, confirm) плюс поля из таблицы ниже.

Пример (выдача Premium, как в вопросе выше):

POST /api/actions/grant-premium
Content-Type: application/json
X-CSRF-Token: <csrf из /api/session>

{
  "command_id": "grant-premium-001",
  "reason": "Компенсация за инцидент",
  "confirm": true,
  "user_id": 123456789,
  "months": 12
}

API: программный поиск аккаунта (v1)

POST /v1/accounts/resolve-by-phone — защищённый bearer-токеном, только читающий поиск аккаунта, который использует Telegram-бот магазина в сценарии «найти мой ID». Endpoint находит числовой ID аккаунта по номеру телефона без приватной проекции просмотра, чтобы бот мог автоматически сохранить серверный ID пользователя, если тот уже создал аккаунт. В отличие от всех маршрутов /api/actions/... запрос не содержит метаданных команды: endpoint никогда не меняет состояние и не пишет запись в аудит.

Ответ 200 OK:

Ошибки: 401 — неверный/отсутствующий bearer-токен; 500 — сбой поиска; 501 — сборка без бэкенда поиска. Отсутствие номера — это успех с found: false, а не 404.

Пример:

POST /v1/accounts/resolve-by-phone
Authorization: Bearer <token>
Content-Type: application/json

{ "phone": "+79991234567" }

// 200
{ "found": true, "user_id": 1780243207 }

API: действия над каналами

API: действия над ботами

API: действия над стикерами и emoji

API: действия над GIF-каталогом

API: действия над подарками и коллекционками

API: действия над коллекционными юзернеймами

API: действия над анонимными номерами

API: действия над рейтингом аккаунтов

API: удаление сообщений

API: решения верификации (тела запросов)

Официальная верификация — revoke-verification:

Сторонняя верификация — действия верификатора/меток (botverification.manage):

Все они также несут общие поля (command_id, reason, confirm).