Admin Gateway Service¶

Назначение¶

Admin Gateway — HTTP-шлюз для административного интерфейса платформы Univex. Обслуживает запросы сотрудников биржи: управление пользователями, ручные операции, AML-проверки, управление активами, P2P-диспуты и настройка конфигурации.

Фреймворк: Fiber v2. Авторизация: JWT + Casbin RBAC. Документация API: Swagger (OpenAPI).

Интерактивная документация API

Открыть ReDoc — Admin Gateway API

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

┌────────────────────────────────────────────────┐
│              Fiber v2 HTTP Server              │
│  JWT Middleware (проверка admin access-токена) │
│  Casbin RBAC Middleware (проверка прав)        │
│  Swagger UI (/docs)                            │
└───────────────────────┬────────────────────────┘
                        │
          ┌─────────────┼──────────────┐
          │             │              │
┌─────────▼──────┐ ┌────▼────┐ ┌──────▼──────┐
│  univex-id     │ │ ledger  │ │     p2p     │
│  gRPC client   │ │  gRPC   │ │  gRPC client│
└────────────────┘ └─────────┘ └─────────────┘
          │
┌─────────▼──────────────┐
│  exchange-integration  │
│     gRPC client        │
└────────────────────────┘

Casbin RBAC¶

Права доступа к маршрутам определяются политиками Casbin. Каждый администратор имеет роль (или набор ролей), роли определяют доступ к конкретным группам маршрутов.

Роль	Основные права
`CASHIER`	Фиатные операции, управление фиатными кассами
`OPERATOR`	Ручные операции с балансами
`P2P_ARBITRATOR`	P2P-диспуты
`SUPPORT_STAFF`	Просмотр аккаунтов, транзакций
`ADMINISTRATOR`	Большинство административных операций
`OWNER`	Полный доступ, управление администраторами

Ролевая модель (Casbin RBAC)¶

Модель RBAC¶

Casbin использует следующую конфигурацию модели:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, "OWNER") || g(r.sub, r.sub) && g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

Матчер даёт роли OWNER безусловный доступ ко всем ресурсам (bypass на уровне матчера). Для всех остальных ролей проверяется тройка (sub, obj, act) по загруженным политикам.

Роли и наследование¶

Роль	Наследует	Назначение
`CASHIER`	—	Фиатные операции (READ, WRITE)
`OPERATOR`	—	Просмотр пользователей + фиатные операции
`P2P_ARBITRATOR`	—	Просмотр пользователей + P2P (READ, WRITE)
`ADMINISTRATOR`	CASHIER, OPERATOR, P2P_ARBITRATOR	Полный доступ ко всем ресурсам
`OWNER`	— (hardcoded bypass)	Безусловный доступ ко всему (bypass в matcher)

Ресурсы¶

Защищённые ресурсы (20 единиц):

ADMIN_PROFILE, ADMIN_ROLE, ADMIN_SESSIONS, ASSETS, CRYPTO_OPERATIONS, FIAT_OPERATIONS, HOTWALLETS, LIMITS, MANUAL_OPERATIONS, MANUAL_VERIFICATION, NOTIFICATIONS, P2P, POLICY, SETTINGS, TICKERS, TIERS, USERS, WALLETS, WITHDRAWAL

Действия¶

Действие	Описание
`READ`	Чтение данных (GET-запросы)
`WRITE`	Изменение данных (POST, PUT, PATCH-запросы)
`DELETE`	Удаление данных (DELETE-запросы)
`*`	Wildcard — все действия

Хранение политик¶

Политики хранятся в PostgreSQL через GORM-адаптер Casbin. Начальная инициализация выполняется командой cmd/init_roles/, которая загружает политики из файла policies.csv в базу данных.

Механизм проверки¶

sequenceDiagram
    participant Client as Клиент (Admin UI)
    participant AGW as admin-gateway middleware
    participant JWT as JWT Manager
    participant UID as univex-id (gRPC)
    participant CB as Casbin enforcer

    Client->>AGW: HTTP-запрос (Authorization: Bearer <token>)
    AGW->>JWT: Извлечь userID из JWT
    JWT-->>AGW: userID
    AGW->>AGW: CheckAccess(resource, action)
    AGW->>UID: gRPC CheckAdminAccess(userID, resource, action)
    UID->>CB: enforcer.Enforce(userID, resource, action)
    CB-->>UID: true / false
    UID-->>AGW: разрешено / запрещено
    alt Доступ разрешён
        AGW-->>Client: 200 OK
    else Доступ запрещён
        AGW-->>Client: 403 Forbidden
    end

Привязка к маршрутам¶

Проверка прав выполняется на уровне каждого маршрута (per-endpoint):

Маршрут	Middleware
`GET /api/account/find`	`CheckAccess(USERS, READ)`
`POST /api/account/:id/ban`	`CheckAccess(USERS, WRITE)`
`POST /api/role/change`	`CheckAccess(ADMIN_ROLE, WRITE)`
`PATCH /api/assets/`	`CheckAccess(ASSETS, WRITE)`

HTTP-маршруты¶

/auth — Аутентификация администраторов¶

Метод	Путь	Описание
`POST`	`/auth/sign-in`	Вход администратора по учётным данным
`POST`	`/auth/refresh`	Обновление access-токена
`POST`	`/auth/totp/create`	Инициировать привязку TOTP
`POST`	`/auth/totp/complete`	Завершить привязку TOTP

/explorer — Конфигурация эксплорера¶

Метод	Путь	Описание
`GET`	`/explorer`	Получить настройки шаблона эксплорера
`PUT`	`/explorer`	Обновить настройки шаблона эксплорера

/account — Управление пользователями¶

Метод	Путь	Описание
`GET`	`/account`	Список пользователей с фильтрацией
`GET`	`/account/:id`	Данные пользователя по ID
`POST`	`/account/:id/ban`	Заблокировать аккаунт
`POST`	`/account/:id/unban`	Разблокировать аккаунт
`GET`	`/account/:id/ban-events`	История блокировок/разблокировок
`POST`	`/account/:id/verification`	Установить статус KYC вручную
`GET`	`/account/:id/notes`	Заметки о пользователе
`POST`	`/account/:id/notes`	Добавить заметку о пользователе
`GET`	`/account/:id/wallets`	Кошельки пользователя
`GET`	`/account/:id/balances`	Балансы пользователя
`GET`	`/account/:id/tier`	Торговый уровень пользователя
`POST`	`/account/:id/tier`	Изменить торговый уровень

/admin — Профиль и управление администраторами¶

Метод	Путь	Описание
`GET`	`/admin/profile`	Профиль текущего администратора
`GET`	`/admin/sessions`	Список активных административных сессий
`DELETE`	`/admin/sessions/:id`	Отозвать административную сессию
`GET`	`/admin`	Список администраторов
`POST`	`/admin`	Создать нового администратора
`DELETE`	`/admin/:id`	Удалить администратора
`GET`	`/admin/actions`	Лог административных действий

/role — Управление ролями¶

Метод	Путь	Описание
`GET`	`/role`	Список ролей
`POST`	`/role`	Создать роль
`PUT`	`/role/:id`	Изменить роль администратора

/tiers — Торговые уровни¶

Метод	Путь	Описание
`GET`	`/tiers`	Список торговых уровней
`POST`	`/tiers`	Создать торговый уровень
`GET`	`/tiers/:id`	Данные торгового уровня
`PUT`	`/tiers/:id`	Обновить торговый уровень

/operations — Ручные операции¶

Метод	Путь	Описание
`POST`	`/operations/topup`	Ручное пополнение торгового баланса
`POST`	`/operations/withdraw`	Ручной вывод с торгового баланса
`POST`	`/operations/transfer`	Перевод между торговыми аккаунтами
`POST`	`/operations/balance/topup`	Ручное пополнение балансового аккаунта
`POST`	`/operations/balance/withdraw`	Ручное снятие с балансового аккаунта
`POST`	`/operations/balance/transfer`	Перевод между балансовыми аккаунтами
`GET`	`/operations/limits`	Лимиты на операции
`PUT`	`/operations/limits`	Установить лимиты на операции

/orders — Управление P2P-ордерами¶

Метод	Путь	Описание
`GET`	`/orders`	Список P2P-ордеров с фильтрацией
`GET`	`/orders/:id`	Данные ордера
`GET`	`/orders/:id/events`	История событий ордера

/manual-verification — Ручная верификация¶

Метод	Путь	Описание
`GET`	`/manual-verification`	Список заявок на ручную верификацию
`POST`	`/manual-verification/:id/approve`	Подтвердить верификацию
`POST`	`/manual-verification/:id/reject`	Отклонить верификацию

/p2p — P2P-диспуты¶

Метод	Путь	Описание
`GET`	`/p2p/disputes`	Список диспутов
`GET`	`/p2p/disputes/:id`	Данные диспута
`POST`	`/p2p/disputes/:id/accept`	Принять диспут в работу
`POST`	`/p2p/disputes/:id/decision`	Вынести решение по диспуту

/fiat — Фиатные операции¶

Метод	Путь	Описание
`GET`	`/fiat/bids`	Список фиатных заявок
`GET`	`/fiat/bids/:id`	Данные фиатной заявки
`POST`	`/fiat/bids/:id/process`	Принять фиатную заявку в обработку
`POST`	`/fiat/bids/:id/complete`	Завершить фиатную заявку
`POST`	`/fiat/bids/:id/funds-issued`	Подтвердить выдачу средств

/notifications — Уведомления администраторов¶

Метод	Путь	Описание
`GET`	`/notifications`	Список уведомлений
`POST`	`/notifications/:id/read`	Отметить уведомление прочитанным

/confirm — Подтверждение операций¶

Метод	Путь	Описание
`POST`	`/confirm/:id`	Подтвердить операцию кодом 2FA
`GET`	`/confirm/high-risk-withdrawals`	Список выводов с высоким риском, ожидающих подтверждения
`POST`	`/confirm/high-risk-withdrawals/:id`	Подтвердить/отклонить рискованный вывод

/hotwallets — Горячие кошельки¶

Метод	Путь	Описание
`GET`	`/hotwallets`	Список горячих кошельков
`POST`	`/hotwallets/transfer`	Перевод активов между кошельками
`GET`	`/hotwallets/transfer/:id/status`	Статус перевода активов

/transit-wallets — Транзитные кошельки¶

Метод	Путь	Описание
`GET`	`/transit-wallets`	Список транзитных кошельков
`GET`	`/transit-wallets/:id`	Данные транзитного кошелька
`POST`	`/transit-wallets`	Создать транзитный кошелёк
`GET`	`/transit-wallets/:id/topups`	История пополнений кошелька
`GET`	`/transit-wallets/:id/withdrawals`	История выводов с кошелька
`POST`	`/transit-wallets/:id/bypass-aml`	Пропустить AML-проверку пополнения

/access — Управление доступом (Casbin)¶

Метод	Путь	Описание
`GET`	`/access/policies`	Список политик Casbin
`POST`	`/access/policies`	Добавить политику
`DELETE`	`/access/policies`	Удалить политику

/frozen-assets — Замороженные активы¶

Метод	Путь	Описание
`GET`	`/frozen-assets`	Список замороженных активов
`POST`	`/frozen-assets/freeze`	Заморозить активы
`POST`	`/frozen-assets/unfreeze`	Разморозить активы
`POST`	`/frozen-assets/spend`	Списать замороженные активы

/fiat-places — Фиатные кассы¶

Метод	Путь	Описание
`GET`	`/fiat-places`	Список фиатных касс
`POST`	`/fiat-places`	Создать фиатную кассу
`PUT`	`/fiat-places/:id`	Обновить кассу
`DELETE`	`/fiat-places/:id`	Удалить кассу

/elliptic — Проверка рисков (Elliptic)¶

Метод	Путь	Описание
`POST`	`/elliptic/check`	Запустить проверку риска адреса через Elliptic
`GET`	`/elliptic/:id`	Результат проверки риска

/config — Конфигурация¶

Метод	Путь	Описание
`POST`	`/config/validate`	Валидировать конфигурацию биржевого движка

/assets — Управление активами¶

Метод	Путь	Описание
`GET`	`/assets`	Список активов
`GET`	`/assets/:asset/status`	Статус актива (торговля, пополнение, вывод)
`POST`	`/assets/:asset/trading`	Включить/выключить торговлю активом
`POST`	`/assets/:asset/networks/:network/topup`	Включить/выключить пополнение актива в сети
`POST`	`/assets/:asset/networks/:network/withdraw`	Включить/выключить вывод актива в сети
`POST`	`/assets/:asset/networks/:network/commission`	Установить комиссию на вывод

/tickers — Управление тикерами¶

Метод	Путь	Описание
`GET`	`/tickers`	Список торговых пар
`POST`	`/tickers/:ticker/trading`	Включить/выключить торговлю по паре

/api-keys — Управление API-ключами пользователей¶

Метод	Путь	Описание
`GET`	`/api-keys/:account_id`	Список API-ключей пользователя
`DELETE`	`/api-keys/:id`	Удалить API-ключ пользователя

/blockchain — Управление выводами¶

Метод	Путь	Описание
`GET`	`/blockchain/withdraw-availability`	Статус доступности вывода для активов/сетей
`POST`	`/blockchain/withdraw-availability`	Установить доступность вывода

/risk-categories — Категории риска¶

Метод	Путь	Описание
`GET`	`/risk-categories`	Список категорий риска
`POST`	`/risk-categories/:id/thresholds`	Установить пороги для категории
`POST`	`/risk-categories/:id/rename`	Переименовать категорию
`DELETE`	`/risk-categories`	Удалить категории риска
`GET`	`/risk-categories/blacklist`	Список заблокированных адресов

/transactions — Блокчейн-транзакции¶

Метод	Путь	Описание
`GET`	`/transactions`	Список блокчейн-транзакций
`GET`	`/transactions/:id/hashes`	Хэши транзакций по выводу
`GET`	`/transactions/topups`	Все пополнения
`GET`	`/transactions/topups/:id`	Детали пополнения (AML-информация)
`GET`	`/transactions/topups/:id/history`	История смены статусов пополнения

/withdrawals — Управление выводами¶

Метод	Путь	Описание
`GET`	`/withdrawals`	Список выводов
`POST`	`/withdrawals/:id/aml-clean`	Пометить вывод как прошедший AML
`POST`	`/withdrawals/:id/aml-refund`	Инициировать возврат по AML
`POST`	`/withdrawals/:id/refund-address`	Установить адрес возврата

Middleware¶

Middleware	Назначение
JWT Auth	Проверка и парсинг admin access-токена
Casbin RBAC	Проверка прав доступа к конкретному маршруту по роли
Request Logger	Логирование запросов с данными администратора
Error Handler	Маппинг gRPC-кодов в HTTP-статусы
CORS	Политика cross-origin для админ-интерфейса

Конфигурация¶

Параметр	Описание
`HTTP_PORT`	Порт HTTP-сервера
`JWT_SECRET`	Секрет для верификации JWT
`CASBIN_MODEL_PATH`	Путь к файлу модели Casbin
`CASBIN_POLICY_PATH`	Путь к файлу политик Casbin (или DSN БД)
`UNIVEX_ID_GRPC_ADDR`	Адрес UnivexID gRPC
`LEDGER_GRPC_ADDR`	Адрес Ledger gRPC
`P2P_GRPC_ADDR`	Адрес P2P gRPC
`EXCHANGE_INTEGRATION_GRPC_ADDR`	Адрес Exchange Integration gRPC
`SWAGGER_ENABLED`	Включить/выключить Swagger UI