Лимит трафика (ГБ) на пользователя с учётом расхода и ручным сбросом

[Postlog]

Категория: feature · Приоритет: high · Размер: XL · Ранг: 1/10

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

Поле «Лимит трафика (ГБ)» (0 = без лимита) в форме создания/редактирования пользователя; колонка «использовано / лимит» с прогресс-баром и процентом в таблице; кнопка «Сбросить трафик» в меню действий строки. Бэкенд хранит лимит на пользователе и прокидывает его в 3x-ui при провижининге.

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

Marzban/Marzneshin (data_limit + used_traffic), 3x-ui (ClientTraffic.totalGB + resetClientTraffic), Remnawave и Hiddify — у всех квота трафика с живым учётом. Базовый биллинговый примитив.

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

entity.ClientSpec несёт только ID/Email/Flow/SubID, а add_client.go жёстко шлёт totalGB:0 — квота никогда не задаётся. Фронт (users_get) уже показывает Up/Down из кэша флита (fleet/build.go суммирует cs.Up/cs.Down, берёт max cs.Total), но Total не редактируется, нет прогресс-бара, нет принудительного отключения при исчерпании и нет сброса. xui-клиент умеет только ListInbounds/AddClient/DelClient — нет UpdateClient и resetClientTraffic.

Зачем

Операторы продают планы с фиксированной квотой (напр. 50 ГБ/мес) и требуют жёсткого ограничения плюс сброса в один клик без пересоздания клиента. Это самый важный недостающий продуктовый примитив — на его данных стоят бары, предупреждения и автоотключение.

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

Расширить entity.ClientSpec полем TotalGB, убрать хардкод в add_client.go (брать из спеки). Колонка total_bytes в users (миграция) + поле в UserCreateParams/UserEditParams; provisioning прокидывает в AddClient. Учёт расхода уже доступен — вынести used/total/percent в users_get-ответ, нарисовать бар во Vue SPA. Для сброса — новый метод xui-клиента ResetClientTraffic (один файл reset_client_traffic.go + httptest-тест), сервисный метод ResetUsage, ручка user_reset_traffic (openapi → ogen → handler). Энфорсмент исчерпания — через флаг enable (опирается на #89).

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

• internal/entity/panel.go (ClientSpec.TotalGB), internal/entity/user.go
• internal/clients/xui/add_client.go, reset_client_traffic.go (новый) + тест, contract.go
• internal/service/provisioning/service.go, migrations/NNNN-user-traffic-limit.sql
• openapi/{user_create,user_edit,user_reset_traffic}.yaml, internal/handlers/{users_get,user_reset_traffic}/
• internal/handlers/web/static/{app.js,index.html,app.css}

---

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

[Postlog]

Issue #103 — Лимит трафика (ГБ) на пользователя с учётом расхода и ручным сбросом

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

Резюме. Добавляем квоту трафика на пользователя (total_bytes, 0 = безлимит): храним на users, прокидываем в 3x-ui при провижининге (вместо хардкода totalGB:0), показываем «использовано / лимит» с прогресс-баром в таблице и кнопку «Сбросить трафик» (новый xui-метод ResetClientTraffic + сервис ResetUsage + ручка userResetTraffic).

Контекст из кода (сверка с issue)

• entity.ClientSpec (internal/entity/panel.go:58-64) несёт только ID/Email/Flow/SubID. add_client.go:21 жёстко шлёт "totalGB": 0. Подтверждено — issue прав.
• Расход уже доступен: fleet/build.go суммирует cs.Up/cs.Down и берёт max(cs.Total) в entity.Subscriber{Up,Down,Total} (internal/entity/fleet.go:36-48). Total из панели == квота, выставленная в 3x-ui. Но это «зеркало панели», а не наша source-of-truth. Лимит должен жить на users.total_bytes (он один на пользователя, а на панели он размазан по ClientTraffic каждого инбаунда и может рассинхрониться). В ответе users_get отдаём наш лимит из БД + использовано из флита.
• users_get/handler.go:84-86 уже кладёт Stats{Up,Down} из fl.Sub(u.SubID). Расширяем ответ полями total (лимит из БД) и used (Up+Down).
• xui-клиент умеет ListInbounds/AddClient/DelClient (internal/clients/xui/, contract.go провижининга internal/service/provisioning/contract.go:26-30). Нет ResetClientTraffic.
• users репозиторий: Create (create.go:23 INSERT), Get/ListPage (SELECT-列 id,name,sub_id,description,created_at), SetDescription (узкий апдейт одного поля). Никакого total_bytes. Миграции: 0001/0002/0003, последняя — 0003-strict-mihomo-refs.notx.sql → новая будет 0004.
• Провижининг — один клиент на панель, привязанный ко всем инбаундам одним AddClient. Лимит totalGB в 3x-ui — это per-ClientTraffic, т.е. учитывается на каждом инбаунде отдельно; шлём один и тот же totalGB во всех add.

Зависимость от #89 (важно)

Issue №103 в разделе «энфорсмент исчерпания» опирается на флаг enable из #89 (per-user enable/disable). Жёсткий автоэнфорсмент (отключение при исчерпании квоты) выношу за рамки этого PR — он требует механики enable/disable из #89 и фонового воркера, которого в subgen нет (SIGHUP-релоада/cron нет, данные текут снизу вверх по запросу). Этот PR доставляет: хранение лимита + прокидывание в 3x-ui (где сам Xray режет трафик по totalGB на стороне узла) + отображение + ручной сброс. См. «Открытые вопросы».

Замечание: 3x-ui/Xray сам останавливает раздачу при достижении totalGB на инбаунде (depleted), так что «жёсткое ограничение» по сути обеспечивается передачей totalGB в панель — отдельный subgen-энфорсмент не обязателен для MVP.

---

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

1. entity

• internal/entity/panel.go: добавить в ClientSpec поле TotalGB int64 — лимит в байтах (3x-ui totalGB принимает байты, не гигабайты, несмотря на имя — проверить на apitest; имя поля 3x-ui историческое). Комментарий: «0 = безлимит».
• internal/entity/user.go:
  • User: добавить TotalBytes int64 (0 = безлимит).
  • UserCreateParams: добавить TotalBytes int64.
  • UserEditParams: добавить TotalBytes int64.
• internal/entity/validation_errors.go: добавить sentinel ErrValidationTrafficLimit = errors.New("invalid traffic limit") (для отрицательного лимита; валидация — в сервисе).

2. repository/users

• create.go: добавить total_bytes в INSERT (INSERT INTO users(name,sub_id,description,total_bytes,created_at) VALUES(?,?,?,?,?)), bind u.TotalBytes.
• get.go и list_page.go: добавить total_bytes в SELECT-列 и в Scan (после description). В list_page.go это 5 запросов (count не трогаем, только page-列 в каждой ветке switch).
• новый set_traffic_limit.go (узкий апдейт по образцу set_description.go): func (r *Repository) SetTrafficLimit(ctx, userID int64, totalBytes int64) error → UPDATE users SET total_bytes=? WHERE id=?. Используется в EditUser.
• (reset traffic не пишет в users — сброс обнуляет счётчик на панели, лимит остаётся; БД не трогаем.)

3. clients/xui — ResetClientTraffic (один метод = один файл)

• новый internal/clients/xui/reset_client_traffic.go:

  // ResetClientTraffic zeroes the used-traffic counter of a client on ONE inbound
  // (3x-ui keys reset by inbound id + email). The quota (totalGB) is untouched.
  func (c *Client) ResetClientTraffic(ctx, t entity.PanelTarget, inboundID int, email string) error {
      return c.postJSON(ctx, t, "/panel/api/inbounds/resetClientTraffic/"+strconv.Itoa(inboundID)+"/"+url.PathEscape(email), nil)
  }

  Эндпойнт 3x-ui 3.x: POST /panel/api/inbounds/resetClientTraffic/{inboundId}/{email}. Сброс per-inbound (счётчик ClientTraffic скоупится инбаундом), поэтому метод берёт inboundID; сервис вызовет его по каждому инбаунду пользователя.
• internal/clients/xui/add_client.go: заменить "totalGB": 0 → "totalGB": cs.TotalGB.
• Тест reset_client_traffic_test.go (httptest, по образцу add_client_test.go/del_client_test.go): проверить path (/panel/api/inbounds/resetClientTraffic/3/bob), Bearer-заголовок, разбор {success}-конверта, ветки success/error.envelope/error.status.
• add_client_test.go: дополнить проверкой cl["totalGB"] (передаём не-ноль).

4. service/provisioning

• contract.go (panelClient): добавить метод
  ResetClientTraffic(ctx, t entity.PanelTarget, inboundID int, email string) error. Перегенерить мок: go generate ./internal/service/provisioning/.
• contract.go (userRepo): добавить SetTrafficLimit(ctx, userID int64, totalBytes int64) error.
• service.go:
  • validateTrafficLimit(n int64) error — n < 0 → entity.ErrValidationTrafficLimit (0 и положительные ок).
  • CreateUser: провалидировать p.TotalBytes, положить u.TotalBytes; в syncPanels прокинуть лимит в ClientSpec.TotalGB (см. ниже).
  • EditUser: провалидировать p.TotalBytes, вызвать s.users.SetTrafficLimit(ctx, u.ID, p.TotalBytes) (рядом с SetDescription), обновить u.TotalBytes в памяти перед syncPanels (чтобы ре-байнд унёс новый лимит на панель).
  • syncPanels: в AddClient(... entity.ClientSpec{..., TotalGB: u.TotalBytes}) подставить лимит из *entity.User (он уже передаётся в syncPanels).
  • новый метод ResetUsage(ctx, id int64) error: users.Get → nodeIndex → для каждого Connection пользователя вызвать client.ResetClientTraffic(ctx, target(node), inboundPortID, u.Name). Важно: reset берёт 3x-ui inbound id, а у нас в Connection есть Port, не панельный id. Резолвим как в syncPanels: panelLookup → idByPort[c.Port]. Собираем failures []string по образцу syncPanels, в конце fmt.Errorf("%s", strings.Join(...)). Best-effort нежелателен (оператор ждёт подтверждения сброса) — возвращаем ошибку, если хоть один инбаунд не сброшен.
• service_test.go: расширить таблицы CreateUser/EditUser кейсами с лимитом (валидный, отрицательный → ErrValidationTrafficLimit, прокидывание TotalGB в AddClient-EXPECT); добавить TestService_ResetUsage (один Test{Type}_{Method} на метод; кейсы: success, error.get, error.list_inbounds, error.reset_downstream, error.no_inbound_on_port).

5. openapi → ogen

Правим спеки, затем go generate ./internal/oas/.

• openapi/user_create.yaml и openapi/user_edit.yaml: добавить в request properties поле

  totalBytes:
    type: integer
    format: int64
    description: Лимит трафика в байтах (0 = без лимита). Значение валидируется на сервере.

  Не required (бэк-совместимо, дефолт 0). Value-constraints (minimum) не кладём — валидация отрицательного в сервисе (ADR-0003).
• openapi/users_get.yaml: в stats добавить total и used (оба integer/int64, required) рядом с up/down. total = лимит из БД, used = up+down (удобно фронту для процента).
• новый openapi/user_reset_traffic.yaml (по образцу user_recreate.yaml): POST /admin/api/users/reset-traffic, operationId: userResetTraffic, body {id:int64} required, ответы 200 MessageResponse / 400 ErrorResponse / 401 ErrorResponse.
• openapi/openapi.yaml: зарегистрировать путь /admin/api/users/reset-traffic: $ref: './user_reset_traffic.yaml' (рядом с recreate, строки 40-41).

6. handlers

• internal/handlers/user_create/handler.go и user_edit/handler.go: прокинуть req.TotalBytes (опциональное oas.OptInt64 → .Or(0)) в entity.UserCreateParams.TotalBytes / UserEditParams.TotalBytes. Добавить ветку errors.Is(err, entity.ErrValidationTrafficLimit) → 400 с локальной текст-константой MsgInvalidTrafficLimit = "Лимит трафика не может быть отрицательным".
• internal/handlers/users_get/handler.go: в row.Stats добавить Total: u.TotalBytes (из БД-модели, не из флита) и Used: sub.Up+sub.Down. Лимит берём из u всегда; used — только если sub != nil.
• новый пакет internal/handlers/user_reset_traffic/ (по образцу user_recreate):
  • contract.go: type trafficResetter interface { ResetUsage(ctx, id int64) error } + //go:generate mockgen.
  • handler.go: MsgReset = "Трафик сброшен"; UserResetTraffic зовёт svc.ResetUsage. Доменных 4xx нет (как у recreate — missing user / панель-фейл = инфра) → любой не-nil error: slog.Error + return nil, err (500). Если решим различать «панель не сбросила» как 4xx — не нужно: это инфра.
  • handler_test.go, contract_mocks.go (через go generate).

7. api composite + main.go

• internal/handlers/api/server.go: импорт userResetTrafficHandler, поле UserResetTraffic *userResetTrafficHandler.Handler в Handlers, forwarder
  func (s *Server) UserResetTraffic(ctx, req *oas.UserResetTrafficReq) (oas.UserResetTrafficRes, error) { return s.h.UserResetTraffic.UserResetTraffic(ctx, req) }.
• cmd/service/main.go: UserResetTraffic: userResetTrafficHandler.New(prov) в сборке Handlers (рядом со строкой 212).

8. фронт (internal/handlers/web/static/)

• index.html:
  • Колонка трафика (строка 79): заменить на «использовано / лимит» + прогресс-бар. Используем u.stats.used/u.stats.total; при total>0 рисуем bar с процентом Math.round(used/total*100) (clamp 100), при total===0 — «↑↓ + ∞» (как сейчас, без бара). Стиль bar — Bootstrap .progress/.progress-bar в Ant-токенах (см. app.css), цвет primary #1668dc, warn при >90%.
  • В act-group (строка 83-87) добавить кнопку «Сбросить трафик» → @click="resetTraffic(u)".
  • В модалке пользователя (uForm, строка 340-366) добавить поле <input type="number" min="0"> «Лимит трафика (ГБ), 0 = без лимита» → uForm.limitGB.
• app.js:
  • openCreateUser/openEdit: завести limitGB в uForm (limitGB: u.totalBytes ? u.totalBytes/1024/1024/1024 : 0 при редактировании — конверсия байты↔ГБ).
  • submitUser: params.totalBytes = Math.round((Number(f.limitGB)||0) * 1024**3).
  • новый resetTraffic(u): confirm("Сбросить трафик у " + u.name + "?") → this.post("/admin/api/users/reset-traffic", {id:u.id}) → loadUsers() (по образцу recreateUser, с actingId).
  • helper форматирования процента/бара (или inline в шаблоне).
  • colspan пустой строки (index.html:90) при необходимости подправить (число колонок не меняется — колонок столько же).

---

Миграции БД

Новый файл migrations/0004-user-traffic-limit.sql (forward-only, чистый DDL, в транзакции — обычный ALTER ADD COLUMN, не .notx):

-- 0004: per-user traffic quota in bytes (0 = unlimited). NOT NULL DEFAULT 0 so
-- existing users are unlimited and reads need no COALESCE.
ALTER TABLE users ADD COLUMN total_bytes INTEGER NOT NULL DEFAULT 0;

total_bytes — байты (тип int64 в домене; единицы ГБ — только UI-конвертация). NOT NULL DEFAULT 0 корректно для ADD COLUMN в SQLite.

OpenAPI/ogen

Правки трёх спек + новый user_reset_traffic.yaml + регистрация в openapi.yaml → go generate ./internal/oas/ (директива в internal/oas/generate.go). Value-валидация (отрицательный лимит) — в сервисе, не в схеме (ADR-0003); в спеку кладём только type/format.

Тесты

• xui: TestClient_ResetClientTraffic (httptest, новый файл); дополнить TestClient_AddClient проверкой totalGB.
• provisioning: расширить TestService_CreateUser/TestService_EditUser (лимит валиден / отрицательный → sentinel / прокидывание TotalGB в AddClient-EXPECT / SetTrafficLimit-EXPECT в Edit); новый TestService_ResetUsage. Моки — перегенерить contract_mocks.go после правки panelClient/userRepo.
• users repo: Create/Get/ListPage тесты — обновить ожидаемые модели полем TotalBytes; добавить TestRepository_SetTrafficLimit (если репо покрыт интеграционно — следовать существующему стилю set_description/create_test.go).
• handlers: TestHandler_UserResetTraffic (новый, по образцу recreate); обновить users_get/handler_test.go (поля Total/Used в Stats); дополнить user_create/user_edit тесты кейсом отрицательного лимита → MsgInvalidTrafficLimit.
• contract.go-моки: новые/изменённые в provisioning, user_reset_traffic. go generate ./....
• apitest (apitest/): расширить UserSuite (или добавить сценарий) — создать пользователя с totalBytes, проверить, что 3x-ui-клиент получил totalGB (через ListInbounds/панель), вызвать reset-traffic, проверить обнуление up/down. Тела — map[string]any/сырой JSON (чёрный ящик, не internal/oas-структуры). Это наружу-видимая фича против реального 3x-ui → apitest желателен.

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

• CHANGELOG.md: одна запись ## 2026-06-12 — Лимит трафика на пользователя + ручной сброс (#<PR>) — 1-2 строки сути.
• ADR: вероятно не нужен (фича аддитивная, развилок мало). Если в ревью выберем явный subgen-энфорсмент исчерпания (вместо «Xray сам режет по totalGB») — это развилка под ADR. По умолчанию без ADR; решение «лимит хранится в БД как source-of-truth, а не зеркалится из панели» зафиксировать одной фразой в CHANGELOG/описании PR.

Риски и edge-cases

• Единицы 3x-ui totalGB: несмотря на имя, поле принимает байты (в 3x-ui 3.x). Зафиксировать apitest'ом перед мёрджем; если окажется иначе — конверсия в add_client.go. Это единственный реальный риск контракта.
• Reset per-inbound: пользователь висит на N инбаундах одной панели → reset надо вызвать N раз (по inbound id). Резолв id по порту через panelLookup (как в syncPanels). На нескольких узлах — по каждому узлу свой target.
• Лимит = source-of-truth в БД vs зеркало панели: users_get отдаёт лимит из БД (u.TotalBytes), used — из флита. Если оператор поменял totalGB руками в панели, БД «победит» при следующем Edit/Recreate (ре-байнд унесёт БД-значение). Это намеренно.
• used > total: clamp прогресс-бара на 100% во фронте.
• Reset не трогает лимит — только счётчик; БД при reset не пишем.
• Безопасность типов: лимит — int64 байты везде; ГБ-конверсия только в UI. Отрицательный — sentinel в сервисе.

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

• Мягкая связь с Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (enable/disable): автоэнфорсмент исчерпания вынесен за рамки (нужен флаг enable из Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 + воркер). Этот PR самодостаточен и не блокируется Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89.
• Обе фичи (Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89, Лимит трафика (ГБ) на пользователя с учётом расхода и ручным сбросом #103) добавляют колонку в users миграцией — мерджить последовательно, чтобы номера 0004/0005 не столкнулись (кто первый — тот 0004).

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

1. Энфорсмент исчерпания. Достаточно ли, что Xray/3x-ui сам останавливает раздачу при достижении totalGB (передаём лимит в панель — узел режет)? Или нужен явный subgen-энфорсмент (отключение клиента при used>=total), который требует механики enable/disable из Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 и фонового пересчёта? Предлагаю MVP без явного энфорсмента (Xray режет сам), автоотключение — отдельным PR поверх Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89.
2. Семантика «Сбросить трафик». Подтвердить: сброс обнуляет счётчик использования на панели (resetClientTraffic), лимит остаётся прежним, БД не меняется. (Так и планирую.)

[Postlog]

✅ Решения зафиксированы (по итогам обсуждения с владельцем)

• Лимит трафика и сброс идут через общий новый метод xui.UpdateClient (update/:email) + xui.ResetClientTraffic. ClientSpec.TotalGB вместо хардкода "totalGB": 0.
• Энфорсмент исчерпания — на стороне 3x-ui (фоновая джоба @5S сама ставит enable=false при up+down >= total); своего шедулера в subgen нет.
• Сброс = ResetClientTraffic (обнуляет счётчик на панели), лимит totalGB не меняется, БД не трогаем.