Вкладка «Обзор»: дашборд с онлайн-юзерами, трафиком и статусами

[Postlog]

Категория: feature · Приоритет: medium · Размер: M · Ранг: 6/10

Что построить

Новая первая вкладка «Обзор» со stat-карточками: всего пользователей, активных/отключённых/истёкших, онлайн сейчас, суммарный трафик флота (вверх/вниз), число узлов и недоступных панелей. Чисто read-only лендинг.

Паритет с конкурентами

Remnawave (Home overview: online users, active/expired, трафик Today/Week/Month), Marzneshin/Marzban (users monitoring + online), 3x-ui (дашборд с графиками). Стартовая сводная страница есть у всех.

Чего не хватает сейчас (код)

В SPA ровно три вкладки (index.html: Пользователи / Узлы / Конфиг Mihomo) — стартового обзора нет. Данные для агрегатов уже в кэше флита (число подписчиков, суммарный Up/Down, истёкшие/отключённые), но нигде не сводятся. Read-эндпоинта со сводкой нет.

Зачем

Сводка с первого взгляда — здоровье и рост: оператор сразу видит, кто активен, сколько истекло и какова нагрузка, без листания таблицы. Самая запрашиваемая операторами фича дашборда; у subgen стартовой страницы нет вообще.

Предлагаемая реализация

Новая ручка dashboard_get (GET /admin/api/dashboard, openapi → ogen) — тонкий хендлер, агрегирующий по кэшу флита (fleet.Fleet) и счётчику юзеров: статусы, суммарный трафик, число узлов/недоступных панелей. Онлайн-число — из #110 (онлайн-монитор), при его отсутствии секция скрыта. Во Vue — новая вкладка с grid карточек в существующих токенах темы (app.css).

Затронутые файлы

• openapi/dashboard_get.yaml (новый) + openapi.yaml
• internal/handlers/dashboard_get/ (новый) + contract.go, internal/service/fleet/ (агрегаты)
• internal/handlers/web/static/{index.html,app.js,app.css}

---

_{Продуктовый ресёрч: изучены аналоги (Marzban/Marzneshin, 3x-ui, Remnawave, Hiddify, sub-store + клиентские стандарты импорта). Паритет и subgen-gap код-обоснованы. Ранг = продуктовый приоритет.}

[Postlog]

Issue #108 — Вкладка «Обзор»: дашборд с онлайн-юзерами, трафиком и статусами

🛠 План реализации

Резюме

Новая read-only ручка GET /admin/api/dashboard (ogen) + сервисный агрегатор по флиту и счётчику пользователей; во Vue — первая вкладка «Обзор» со stat-карточками (всего/активные/отключённые/истёкшие, суммарный трафик up/down, число узлов и недоступных панелей). Онлайн-секция — заглушена до #110.

Сверка issue с кодом (важно — issue местами расходится с реальностью)

1. «Данные для агрегатов уже в кэше флита» — неверно. internal/service/fleet/fleet.go явно без кэша («fresh on every call — there is no cache»). Агрегаты собираются на живом снимке панелей при каждом вызове. Дашборд будет вызывать fleet.Fleet(ctx) как и users_get.
2. У subgen нет пользовательского статуса enable/expiry. entity.User (internal/entity/user.go) знает только Name/SubID/Description/CreatedAt/Connections. Признаки «активен/отключён/истёк/квота» живут в панели на entity.PanelClientStat{Enable,Expiry,Total} и агрегируются флитом в entity.Subscriber{Up,Down,Total,Expiry} (internal/entity/fleet.go, internal/service/fleet/build.go). Значит статусы дашборда — это статусы подписчиков на панелях, а «всего пользователей» — это COUNT по таблице users (это разные множества, см. риски).
3. buildFleet отбрасывает выключенных клиентов (build.go:57: if !cs.Enable || cs.SubID == ""), поэтому текущий Subscriber не позволяет посчитать «отключённых». Нужно протащить «отключённость» во флит (см. шаг 2), иначе карточка «Отключено» всегда 0.
4. Недоступные панели сейчас глотаются в fleet.fetch (fleet.go:48-53, slog.Warn), наружу не отдаются. Для карточки «Недоступно панелей» надо протащить число в entity.Fleet (см. шаг 1-2).
5. Онлайн-юзеры требуют Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110 (онлайн-монитор), которого нет в коде. Карточку online на бэке не вводим вовсе в этом PR — иначе пришлось бы возвращать заведомо-ложный ноль. Фронт секцию online просто не рисует. Это явное допущение (см. открытые вопросы).
6. Маршрут /admin/{view} уже свободно-сегментный (openapi/admin_shell_view.yaml, {view}: type string) — для вкладки overview openapi-страница НЕ меняется; правится только SPA-роутинг во фронте.

---

Пошаговый план (снизу вверх)

1. entity — расширить Fleet и Subscriber (internal/entity/fleet.go)

• В entity.Fleet добавить поле UnreachableNodes int — счётчик узлов, чья панель не ответила в этом снимке (заполняется флитом, см. шаг 2). Документировать: «число узлов, чьи панели не ответили при этом обновлении флита;健康-сигнал для дашборда».
• В entity.Subscriber добавить Enabled bool — есть ли у подписчика хоть один включённый клиент-стат (сейчас выключенные вообще не попадают; см. шаг 2). Документировать смысл.
• Никаких новых sentinel-ошибок здесь не нужно (read-only путь, доменных 4xx нет).

2. service/fleet — собрать недоступность и отключённых (internal/service/fleet/{fleet.go,build.go})

• fetch (fleet.go): после цикла по нодам передать len(errs) (число упавших панелей) в buildFleet. Сменить сигнатуру buildFleet(snaps, unreachable int) и проставить fleet.UnreachableNodes = unreachable. (Сейчас errs уже копится — используем его длину; ровно одна панель на узел, поэтому len(errs) == число недоступных узлов.)
• buildFleet (build.go): чтобы посчитать «отключённых», нужно учитывать и cs.Enable==false. Минимальное изменение: не пропускать выключенные стэты из агрегации статуса, но не добавлять их прокси в подписку. Предлагаемый рефактор внутреннего цикла по pi.Stats:
  • пропуск по cs.SubID == "" остаётся (без subId подписки нет);
  • подписчик создаётся/находится по subId для любого стэта с непустым subId;
  • sub.Enabled = sub.Enabled || cs.Enable (подписчик активен, если активен хотя бы один его клиент);
  • прокси (sub.Proxies), трафик (Up/Down), Total, Expiry агрегируются как сейчас, но только когда cs.Enable (выключенный клиент не должен раздувать выдачу подписки/рендер). То есть: if cs.Enable { … добавить прокси/трафик … }, а Enabled/учёт в множестве подписчиков — безусловно при непустом subId.
  • Это сохраняет текущее поведение подписки (sub.yaml/рендер видят только включённые прокси), но даёт дашборду признак «отключён».
• Новый метод-агрегатор service/fleet/summary.go:

  // FleetSummary — сводка по живому флиту для дашборда.
  type FleetSummary struct {
      ActiveSubs   int   // подписчики с ≥1 включённым клиентом и не истёкшие
      DisabledSubs int   // подписчики без единого включённого клиента
      ExpiredSubs  int   // подписчики с Expiry>0 && Expiry<now (по включённым)
      Up, Down     int64 // суммарный трафик флита
      UnreachableNodes int
  }
  func (s *Service) Summary(ctx context.Context, now int64) (FleetSummary, error)

  • тянет s.fetch(ctx) (тот же путь, что Fleet), затем сводит по fl.Subs: для каждого подписчика классифицирует ровно одну корзину (disabled, иначе expired при Expiry>0 && Expiry<now, иначе active), суммирует Up/Down, переносит UnreachableNodes. now — параметр (тестируемость; хендлер передаёт time.Now().UnixMilli()).
  • человеко-текста ошибок нет — только обёрнутая fmt.Errorf("fetch: %w", err).
• Замечание: Summary живёт в service/fleet, а не в хендлере — агрегация статусов/трафика это бизнес-логика (AGENTS: «fleet/build и подобная логика — сервисный слой»).

3. repository/users — счётчик пользователей (internal/repository/users/count.go — новый)

• Новый метод func (r *Repository) Count(ctx context.Context) (int64, error) — SELECT COUNT(*) FROM users. Один метод — один файл (как delete.go/get.go). Без фильтров (дашборд показывает «всего»).
• Это «всего пользователей» из issue — берётся из нашей БД, а не из флита (в БД могут быть юзеры, которых ещё нет/уже нет на панели).

4. repository/nodes — счётчик узлов

• Проверить, есть ли дешёвый счётчик. По коду дашборду нужно «число узлов» — его уже отдаёт fleet/nodes.List. Чтобы не плодить запрос, число узлов берём из длины nodes.List, который флит и так зовёт; но хендлер не должен звать репозиторий узлов отдельно. Решение: добавить TotalNodes int в FleetSummary (заполняется в fetch/Summary как len(nodes)), и не трогать repository/nodes. (Узлы уже перечисляются внутри fetch; протащим их количество в summary тем же путём, что UnreachableNodes.)
  • Конкретно: buildFleet уже не видит общее число нод (видит только дошедшие снимки). Поэтому проще считать totalNodes в fetch (len(nodes)) и класть в entity.Fleet рядом с UnreachableNodes, либо возвращать из Summary напрямую. Предпочесть: добавить entity.Fleet.TotalNodes int (симметрично UnreachableNodes), Summary читает оба из fl.

5. handlers/dashboard_get — новый тонкий хендлер (internal/handlers/dashboard_get/)

• Файлы: handler.go, contract.go, handler_test.go, contract_mocks.go (mockgen).
• contract.go:

  type usersCounter interface {
      Count(ctx context.Context) (int64, error)
  }
  type fleetSummarizer interface {
      Summary(ctx context.Context, now int64) (fleet.FleetSummary, error)
  }

  — два узких интерфейса (interface segregation). FleetSummary — тип из service/fleet; импортировать его в contract допустимо (хендлер выше сервиса по слоям).
• handler.go: New(users usersCounter, fleet fleetSummarizer) *Handler. Метод DashboardGet(ctx) (oas.DashboardGetRes, error):
  • total, err := h.users.Count(ctx) — при ошибке slog.Error("handler dashboard_get: count users failed", "err", err); return nil, err (→ 500).
  • sum, err := h.fleet.Summary(ctx, time.Now().UnixMilli()) — флит может частично падать, но Summary/fetch ошибается только при полном ауте всех панелей. Решение: при ошибке summary не валить весь дашборд — отдать карточки пользователей и нули по флиту + флаг/секцию «панели недоступны»? Либо просто 500. Дефолт: при ошибке summary вернуть nil, err (500) — дашборд бесполезен без флита, а полный аут панелей это реальная авария, которую оператору и надо увидеть. (Альтернатива — graceful degradation — в открытых вопросах.)
  • Собрать oas.DashboardGetOK{ Users: {Total, Active, Disabled, Expired}, Traffic:{Up,Down}, Nodes:{Total, Unreachable} }.
• Логирование строго полями ("err", err), без интерполяции; доменных 4xx тут нет (read-only, без пользовательского ввода) → только slog.Error+500 на инфра-сбой.

6. handlers/api — форвардинг (internal/handlers/api/server.go)

• В Handlers добавить DashboardGet *dashboardGetHandler.Handler.
• Добавить метод-форвард func (s *Server) DashboardGet(ctx) (oas.DashboardGetRes, error) { return s.h.DashboardGet.DashboardGet(ctx) }.
• Импорт dashboardGetHandler "…/internal/handlers/dashboard_get".

7. cmd/service/main — композиция (cmd/service/main.go)

• В api.Handlers{…} добавить DashboardGet: dashboardGetHandler.New(usersRepo, fleetSvc).
• Импорт пакета. usersRepo и fleetSvc уже сконструированы.

---

Миграции БД

Не нужны. Все данные — из существующих таблиц (users COUNT) и живого снимка панелей (флит). Новых колонок/таблиц нет.

---

OpenAPI / ogen

• Новый файл openapi/dashboard_get.yaml:

  # GET /admin/api/dashboard — сводка для стартовой вкладки «Обзор».
  get:
    operationId: dashboardGet
    summary: Dashboard summary
    security:
      - adminSession: []
    responses:
      '200':
        description: dashboard summary
        content:
          application/json:
            schema:
              type: object
              required: [users, traffic, nodes]
              properties:
                users:
                  type: object
                  required: [total, active, disabled, expired]
                  properties:
                    total:    { type: integer, format: int64 }
                    active:   { type: integer }
                    disabled: { type: integer }
                    expired:  { type: integer }
                traffic:
                  type: object
                  required: [up, down]
                  properties:
                    up:   { type: integer, format: int64 }
                    down: { type: integer, format: int64 }
                nodes:
                  type: object
                  required: [total, unreachable]
                  properties:
                    total:       { type: integer }
                    unreachable: { type: integer }
      '401':
        description: unauthorized
        content:
          application/json:
            schema:
              $ref: './common.yaml#/components/schemas/ErrorResponse'

  • Только форма контракта (required/type/format) — никаких value-constraints (ADR-0003).
  • total пользователей — int64 (под COUNT); счётчики статусов/узлов — обычный integer (их максимум — число подписчиков/узлов).
• В openapi/openapi.yaml добавить путь /admin/api/dashboard: $ref: './dashboard_get.yaml' (в блоке admin-API, рядом с /admin/api/nodes).
• Затем go generate ./internal/oas/ (см. internal/oas/ с ogen.yml) — сгенерит oas.DashboardGet* типы и расширит интерфейс oas.Handler (композит в api перестанет компилироваться, пока не добавлен форвард — это и есть страховка из шага 6).

---

Тесты

• internal/service/fleet/summary_test.go — TestService_Summary (table-driven, один тест на метод). Кейсы: empty (нет нод/подписчиков), success.mixed (активные+истёкшие+отключённые+трафик, проверка классификации по now), error.all_panels_down (downstream-ошибка от panelClient.ListInbounds на всех нодах → ожидаем ошибку). Моки — локальные MockpanelClient/MocknodeLister из contract.go пакета fleet (уже есть contract_mocks.go).
• internal/service/fleet/build_test.go — дополнить/обновить существующие кейсы под новую семантику: проверить, что выключенный клиент (Enable:false) не добавляет прокси/трафик, но даёт подписчику Enabled корректно (если у него есть и включённый — Enabled==true; если только выключенные — присутствует с Enabled==false). Не дробить на _Success/_Error.
• internal/repository/users/count_test.go — TestRepository_Count (как соседние repo-тесты: на временной SQLite через миграции/фикстуры; см. create_test.go/list_page_test.go за паттерном). Кейсы: empty (0), success.several.
• internal/handlers/dashboard_get/handler_test.go — TestHandler_DashboardGet (table-driven). contract.go+mockgen → MockusersCounter/MockfleetSummarizer. Кейсы: success (маппинг summary+count в oas.DashboardGetOK), error.count (users.Count падает → ошибка/500), error.summary (fleet.Summary падает → ошибка/500). Проверка require.ErrorIs/assert.Equal.
• apitest — добавить лёгкий сценарий в apitest/ (новый DashboardSuite или кейс в существующем): GET /admin/api/dashboard под админ-кукой → 200 + форма JSON (users.total и т.д.), и 401 без куки. Тело читать как map[string]any (чёрный ящик, не oas-структуры — см. apitest/README.md). Это проверит реальный wire-контракт (имена полей users/traffic/nodes, статусы).
• Не забыть go generate ./... (mockgen для новых contract.go).

---

Документация

• CHANGELOG.md — новая запись сверху: ## 2026-06-12 — Вкладка «Обзор»: дашборд (всего/активные/отключённые/истёкшие, трафик, узлы) (#108) + 1–2 строки сути.
• ADR — не требуется. Изменение прямолинейное (read-ручка + сервисный агрегатор по существующим данным), проектных развилок с trade-off нет. Единственное содержательное решение (расширить Subscriber.Enabled/Fleet.UnreachableNodes вместо нового источника статусов) тривиально и описывается строкой CHANGELOG. Если ревью сочтёт семантику «статус подписчика ≠ статус пользователя» нетривиальной — завести краткий ADR docs/decisions/0006-dashboard-summary.md (Context: статусы живут в панели, не в users; Decision: дашборд агрегирует флит, «всего» — из БД).

---

Фронт (internal/handlers/web/static/{index.html,app.js,app.css})

• index.html: добавить первый таб-линк в навбар: <li><a … :class="{active:tab==='overview'}" @click="go('overview')">Обзор</a></li> (перед «Пользователи»). Добавить <section v-if="tab==='overview'"> с grid stat-карточек (карточки: Всего пользователей, Активны, Отключены, Истекли, Трафик ↑/↓, Узлы / Недоступно панелей). Если dashboard.nodes.unreachable>0 — подсветить карточку узлов (предупреждение).
• app.js:
  • data: dashboard: null; сменить дефолт стартовой вкладки на overview (tab: "overview") и в mounted() — this.load("overview") вместо "users". (Issue: «Новая первая вкладка».)
  • load(tab): ветка else if (tab === "overview") { this.dashboard = await this.getJSON("/admin/api/dashboard"); }.
  • Трафик форматировать существующим hsize().
  • (Опц.) производный геттер для отрисовки карточек, чтобы шаблон был чистым.
• app.css: grid .stat-grid + .stat-card (заголовок-подпись + крупное число) в существующих токенах темы (bg #1a1b1f/card #23252b, radius 12, primary #1668dc, системные шрифты) — без новых webfont'ов, в духе 3x-ui-скина.
• Онлайн-секцию не рисуем (нет данных до Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110). Когда Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110 приедет — добавить поле online в схему/summary и карточку.

---

Риски и edge-cases

• «Всего пользователей» (БД) ≠ сумме статусов (панель). Подписчик есть в флите, только если он реально присутствует на инбаунде панели; юзер в users без живого клиента на панели в статусы не попадёт. Это ожидаемо (карточка «всего» — рост базы; статусы — здоровье на панелях), но оператор может удивиться расхождению. Подписать карточки понятно; при необходимости — тултип. (Возможный открытый вопрос.)
• Полный аут всех панелей → Summary вернёт ошибку (как Fleet) → дашборд 500. Это намеренно (авария видна), но первая страница падает целиком. Альтернатива — graceful degrade (см. вопросы).
• Стоимость: dashboard_get дёргает все панели на каждый запрос (нет кэша во флите), как и users_get/nodes health. Стартовая страница = +1 полный обход панелей при каждом заходе. Приемлемо при текущем размере парка (2 панели); если станет дорого — кэш флита это отдельная задача, не этот PR.
• Изменение семантики buildFleet затрагивает путь подписки (sub.yaml/рендер). Гарантировать тестами, что выключенные клиенты по-прежнему не попадают в выдачу подписки (только признак Enabled добавился) — иначе регрессия в рендере конфигов.
• Истёкшие vs отключённые пересекаются: классификация в Summary должна давать ровно одну корзину на подписчика (приоритет: disabled → expired → active), иначе сумма карточек ≠ числу подписчиков.

Зависимости / порядок

• Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110 (онлайн-монитор) — мягкая зависимость: карточка online вводится только после Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110 (в этом PR не делаем, секция скрыта). Остальной дашборд от Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110 не зависит и реализуется самостоятельно.

---

❓ Открытые вопросы (@Postlog)

1. Статусы — это подписчики на панелях, а не пользователи из БД (у subgen нет user-level enable/expiry; они живут в 3x-ui). Карточка «Всего» считается по таблице users, а «активны/отключены/истекли» — по флиту (подписчики на панелях). Эти множества могут расходиться. Ок так (рост базы vs здоровье на панелях), или хочется единого источника (например «всего» тоже считать по флиту)?
2. Поведение при полном ауте всех панелей: отдавать 500 (дашборд бесполезен, авария видна) или graceful-degrade — показать карточки пользователей из БД + нули/прочерки по флиту и явный баннер «панели недоступны»? Дефолт в плане — 500.
3. Online до Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас» #110: подтверждаю, что в этом PR карточку online не вводим вовсе (ни на бэке, ни на фронте), а не показываем «0». Возражений нет?