Лимит устройств/IP на пользователя (limitIp) с просмотром активных IP

[Postlog]

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

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

Поле «Лимит IP/устройств» (0 = без лимита) в форме пользователя и просмотр текущих IP клиента в детальной карточке. Старт — display-only список активных IP; энфорсмент (отключение при превышении) добавляется позже поверх флага enable (#89).

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

3x-ui (limitIp + CheckClientIpJob по access-логу Xray), Remnawave (HWID device limit по x-hwid заголовкам), Hiddify. Ограничение шеринга — флагманская анти-resale фича.

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

add_client.go хардкодит limitIp:0; ClientSpec не несёт лимита IP. Главное: subgen вообще не читает access-логи узлов (xui-клиент знает только inbounds/clients) — нет источника текущих IP и нет цикла энфорсмента. Самый тяжёлый пункт списка.

Зачем

Один оплаченный аккаунт, расшаренный на компанию друзей, — крупнейшая утечка выручки у VPN-реселлеров; лимит IP/устройств её закрывает. Subgen сегодня не ограничивает число подключений с одного credential.

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

Фаза 1 (display-only): новый метод xui-клиента GetClientIps (POST /panel/api/inbounds/clientIps/:email) — один файл + тест; провести limitIp как ClientSpec.LimitIp в AddClient; колонка limit_ip в users. Карточка пользователя показывает текущие IP. Фаза 2 (энфорсмент): периодический воркер сравнивает число IP с лимитом и отключает через флаг enable (#89). Чтение access-логов узла — отдельный большой кусок, в фазу 2. Поэтому в беклоге это xl, но начинается с дешёвого read-пути.

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

• internal/entity/panel.go (ClientSpec.LimitIp), internal/clients/xui/get_client_ips.go (новый) + тест, contract.go, add_client.go
• internal/service/provisioning/service.go, migrations/NNNN-user-limit-ip.sql
• openapi/{user_create,user_edit,user_ips}.yaml, internal/handlers/user_ips/, internal/handlers/web/static/

---

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

[Postlog]

Issue #109 — Лимит устройств/IP на пользователя (limitIp) с просмотром активных IP

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

Резюме

Фаза 1 (display-only): провести per-user поле limit_ip (0 = без лимита) через всю
вертикаль (entity → миграция → users-repo → provisioning → openapi/ogen → форма
пользователя) и добавить новый read-эндпоинт, показывающий текущие IP клиента (новый
тонкий метод xui-клиента GetClientIps). Энфорсмент (фаза 2) явно вне этого issue — он
поверх per-user enable-флага из #89.

Что подтверждено по коду (сверка issue с репо)

• internal/clients/xui/add_client.go:23 действительно хардкодит "limitIp": 0 — нужно
  завести cs.LimitIp.
• entity.ClientSpec (internal/entity/panel.go:58-64) лимита IP не несёт.
• Источника текущих IP нет: panelClient (контракт provisioning, contract.go:26-30)
  знает только ListInbounds/AddClient/DelClient; access-логов узла subgen не читает.
  Для фазы 1 достаточно clientIps-эндпоинта 3x-ui (panel хранит IP по email из
  CheckClientIpJob), живой access-лог парсить не нужно.
• Миграции форвард-онли, последняя — migrations/0003-strict-mihomo-refs.notx.sql
  → новый файл будет 0004-*.
• users.Create (create.go:23) и ListPage/Get/List SELECT-ы перечисляют колонки
  явно — добавление limit_ip требует правки этих запросов (иначе значение не доедет до
  формы редактирования и до provisioning).
• Поле описания (description) — точный шаблон-эталон для проводки limit_ip (тот же путь:
  entity-поле → миграция → INSERT/SELECT → params → openapi → handler → форма). Копируем его.

---

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

1. entity (internal/entity/)

• panel.go: добавить в ClientSpec поле LimitIp int (0 = без лимита) с комментарием.
• user.go:
  • в User добавить LimitIp int (рядом с Description), комментарий «0 = без лимита».
  • в UserCreateParams и UserEditParams добавить LimitIp int.
• panel.go: новый доменный тип под текущие IP, напр.
  type PanelClientIPs struct { Email string; IPs []string } — то, что отдаёт xui-клиент.
  (Клиент возвращает только entity.*, не wire-DTO.)
• Sentinel-ошибка валидации лимита: errors.go →
  ErrInvalidLimitIP = errors.New("invalid ip limit") (отрицательный лимит). Доменный
  human-text — только в хендлере.

2. xui-клиент (internal/clients/xui/) — тонкий адаптер, один метод = один файл

• add_client.go: заменить "limitIp": 0 на "limitIp": cs.LimitIp.
• Новый файл get_client_ips.go: метод
  func (c *Client) GetClientIps(ctx, t entity.PanelTarget, email string) (entity.PanelClientIPs, error).
  • POST /panel/api/inbounds/clientIps/:email (url.PathEscape email; тело пустое — как
    в del_client.go).
  • Не через postJSON: clientIps отдаёт {success,msg,obj}, где obj —
    либо строка "No IP Record", либо JSON-массив/строка с IP. Нужен собственный разбор
    тела (по образцу list_inbounds.go): проверить success, затем декодировать obj
    в приватный wire-DTO и смаппить в entity.PanelClientIPs. Учесть оба варианта obj
    (нет записей → пустой срез без ошибки).
  • Приватный wire-DTO + маппинг в entity держать в этом файле (anti-corruption).
• Тест get_client_ips_test.go: table-driven TestClient_GetClientIps, HTTP через
  httptest.Server/RoundTripper-мок (как в существующих *_test.go): кейсы
  success.has_ips, empty.no_record (obj = "No IP Record"), error.status,
  error.success_false, error.bad_json. Без живой сети.

3. repository/users (internal/repository/users/)

• create.go: INSERT → добавить колонку limit_ip и значение u.LimitIp.
• get.go, list.go, list_page.go (3 ветки SELECT + count не трогаем): добавить
  limit_ip в SELECT-列 и в Scan(... &u.LimitIp). Внимание: list.go и list_page
  не выбирают limit_ip сейчас — без правки форма редактирования получит 0.
• Новый метод set_limit_ip.go:
  func (r *Repository) SetLimitIP(ctx, userID int64, limitIP int) error — UPDATE users SET limit_ip=? WHERE id=? (зеркало set_description.go). Нужен для пути EditUser.
  Альтернатива — расширить ReplaceConnections-транзакцию; но отдельный метод проще и
  однороден с SetDescription (так и сделаем). Допущение: идём по образцу
  SetDescription (отдельный апдейт в EditUser), не заводим новую обобщённую update-tx.

4. service/provisioning (internal/service/provisioning/)

• contract.go (panelClient): добавить
  GetClientIps(ctx, t entity.PanelTarget, email string) (entity.PanelClientIPs, error);
  в userRepo добавить SetLimitIP(ctx, userID int64, limitIP int) error.
  Затем go generate ./internal/service/provisioning/ (или go generate ./...) для
  перегенерации contract_mocks.go.
• service.go:
  • валидация: func validateLimitIP(v int) error → < 0 ⇒ entity.ErrInvalidLimitIP.
    (Value-валидация в сервисе, не в схеме — по ADR-0003.)
  • CreateUser: провалидировать p.LimitIp, проставить u.LimitIp перед users.Create,
    и прокинуть LimitIp: u.LimitIp в entity.ClientSpec внутри syncPanels (там, где
    собирается ClientSpec, строка ~393). ClientSpec создаётся из u, так что
    syncPanels должен брать лимит из u.LimitIp.
  • EditUser: провалидировать, вызвать users.SetLimitIP(ctx, u.ID, p.LimitIp) (рядом с
    SetDescription), затем обновить u.LimitIp = p.LimitIp до syncPanels, чтобы
    ре-байнд клиента ушёл с новым лимитом.
  • RecreateUser: лимит уже в u.LimitIp (из users.Get) → syncPanels подхватит, правок
    логики не нужно (только убедиться, что ClientSpec берёт u.LimitIp).
  • Новый сервис-метод для read-IP:
    func (s *Service) UserIPs(ctx, id int64) (map[string][]string, error) — users.Get,
    nodeIndex, по узлам подключений вызвать client.GetClientIps(target(n), u.Name),
    собрать node.Name → []IP. Best-effort на узел недоступен (агрегировать как в
    syncPanels: пропуск/частичный результат) — но это read, ошибку узла лучше отдать в
    деталях ответа, не валить весь запрос. Допущение: недоступный узел кладём в ответ
    как пустой список + флаг/строку ошибки, общий запрос 200 (display-only, не критично).
• service_test.go: обновить существующие TestService_CreateUser/EditUser/RecreateUser
  (мок panelClient теперь шире — добавить GetClientIps EXPECT где нужно; добавить кейс с
  limitIp), добавить TestService_UserIPs. Table-driven, один тест на метод.

5. OpenAPI + ogen (openapi/, internal/oas/)

• user_create.yaml, user_edit.yaml: добавить в requestBody.schema.properties
limitIp: { type: integer } (НЕ в required — дефолт 0; НЕ класть minimum — value-
  валидация в сервисе, по AGENTS).
• users_get.yaml: в схему элемента users добавить limitIp (type: integer) в
  properties и в required (всегда есть, дефолт 0) — чтобы форма редактирования
  читала текущее значение.
• Новый эндпоинт user_ips.yaml: GET /admin/api/users/ips?id={id} (или
  POST /admin/api/users/ips с телом {id} — но read ⇒ GET с query-параметром, как
  users_get/config_get). operationId userIps, security adminSession, ответ 200:
  объект { ips: [ { node: string, ips: [string] } ] } (типизированный JSON read-ответ),
  401. Суррогатный id не валидируем (AGENTS): несуществующий → 404/пустой.
  Развилка (см. открытые вопросы): GET+query vs POST+body — по умолчанию GET+query
  (идиоматично для read, гейт /admin/api/* тот же).
• openapi.yaml: добавить $ref на user_ips.yaml под /admin/api/users/ips.
• Прогнать go generate ./internal/oas/, затем писать хендлеры под сгенерённый интерфейс.

6. handlers (internal/handlers/)

• user_create/handler.go и user_edit/handler.go:
  • прокинуть LimitIp: req.LimitIp.Or(0) в entity.UserCreateParams/UserEditParams
    (поле опциональное → ogen даст OptInt).
  • добавить ветку errors.Is(err, entity.ErrInvalidLimitIP) → 400 с локальной
    текст-константой, напр. MsgInvalidLimitIP = "Лимит IP должен быть ≥ 0" (slog.Warn).
• Новый пакет internal/handlers/user_ips/:
  • handler.go: UserIps(ctx, params oas.UserIpsParams) (oas.UserIpsRes, error) —
    дергает svc.UserIPs(ctx, params.ID), маппит в OAS-ответ. Инфра-ошибка узла/панели →
    залогировать slog.Error, отдать 500 (или вложить в ответ — см. п.4).
  • contract.go + mockgen: интерфейс userIPsReader { UserIPs(...) }.
  • handler_test.go: table-driven TestHandler_UserIps.
• internal/handlers/api/ (композит): зарегистрировать форвард UserIps на новый хендлер.
• cmd/service/main.go: сконструировать user_ips.New(provisioningSvc) и передать в
  композит (по образцу прочих хендлеров).

7. Фронт (internal/handlers/web/static/)

• index.html (модалка uForm, ~340-368): добавить числовое поле «Лимит IP / устройств»
  (type=number min=0, подпись «0 = без лимита») рядом с описанием.
• В detail/строке пользователя — кнопку/раскрытие «Текущие IP» (показ списка из нового
  эндпоинта); или мини-секцию в модалке редактирования. Допущение: добавляем кнопку
  «IP» в строку таблицы (рядом с «Пересоздать»), открывающую поповер/модалку со списком —
  минимальный display-only UI.
• app.js:
  • uForm (строка 26): добавить limitIp: 0; openCreateUser/openEdit — инициализация
    из u.limitIp; submitUser (params) — добавить limitIp: f.limitIp.
  • метод loadUserIPs(u) → fetch("/admin/api/users/ips?id="+u.id), рендер результата.
• Тема/токены — как есть (Ant-dark, системные шрифты), без новых либ.

---

Миграции БД

Новый файл migrations/0004-user-limit-ip.sql (обычная tx-миграция, не .notx):

-- 0004: per-user IP/device limit (0 = unlimited). NOT NULL DEFAULT 0 so existing rows
-- and the domain int (0 = no limit) have one representation.
ALTER TABLE users ADD COLUMN limit_ip INTEGER NOT NULL DEFAULT 0;

Форвард-онли, накатывается раннером migrations.Apply на старте, учёт в
schema_migrations. Базлайн 0001-init.sql НЕ трогаем.

OpenAPI/ogen

См. п.5. Принципиально: в схему кладём только форму (type: integer, presence через
required), value-constraints (minimum: 0) — НЕ кладём; отрицательный лимит ловит
сервис sentinel-ошибкой ErrInvalidLimitIP. После правок — go generate ./internal/oas/.

Тесты

• internal/clients/xui/get_client_ips_test.go — TestClient_GetClientIps
  (httptest/RoundTripper, варианты obj: список / «No IP Record» / ошибки).
• internal/repository/users/: добавить set_limit_ip_test.go
  (TestRepository_SetLimitIP) + обновить create_test.go/get_test.go/list_page_test.go
  под новую колонку (если они проверяют SELECT-набор — да, проверяют маппинг).
• internal/service/provisioning/service_test.go: обновить existing per-method тесты
  (расширенный panelClient-мок, кейс с limitIp), добавить TestService_UserIPs.
• internal/handlers/user_ips/handler_test.go — TestHandler_UserIps; правка тестов
  user_create/user_edit (новый sentinel-кейс).
• contract.go-моки регенерить go generate ./... (provisioning, user_ips).
• apitest (apitest/users/): добавить сценарий — создать юзера с limitIp, прочитать
  обратно через usersGet (поле в ответе), и smoke на GET /admin/api/users/ips
  (на реальном 3x-ui вернёт «нет записей» — ассертим 200 + пустой/валидный список).
  Тела — map[string]any/сырой JSON (чёрный ящик), не из internal/oas.

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

• CHANGELOG.md: одна запись ## YYYY-MM-DD — Лимит IP/устройств на пользователя (display-only) (#<PR>) + 1-2 строки сути.
• ADR не обязателен (фаза 1 — прямая проводка поля + read-эндпоинт по существующим
  паттернам, развилок проектных мало). Если выберем спорный вариант ответа user_ips
  (агрегация ошибок узла внутрь 200 vs 500) — кратко зафиксировать решение в ADR
  docs/decisions/000X-user-ip-view.md. Допущение: без ADR, фиксируем выбор в
  комментарии кода + CHANGELOG.

Риски и edge-cases

• 3x-ui clientIps контракт. obj может приходить и строкой «No IP Record», и
  JSON-массивом/строкой с IP — разобрать оба, не падать. (Точный формат — проверить на
  живой панели read-only перед финализацией DTO; см. dev-гочи: prod общий, сначала
  разведка.)
• clientIps отдаёт IP по email, а не per-inbound; у нас один клиент-email на панель —
  совпадает с моделью идентичности. По узлам агрегируем (один email на узле).
• Узел недоступен при чтении IP — не валить весь запрос (best-effort, частичный результат).
• limit_ip хранится у нас и передаётся в панель при add/re-bind; правка лимита без
  Edit/Recreate в панель не долетит (как и сейчас для прочих полей клиента) — это ожидаемо,
  лимит уезжает на следующем sync.
• Энфорсмент (фаза 2) НЕ в скоупе: ни воркера, ни чтения access-логов, ни авто-disable.

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

• Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (per-user enable/disable) — нужен для фазы 2 (энфорсмент через флаг enable).
  Фаза 1 (этот план) от Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 не зависит и делается первой.

---

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

1. Эндпоинт текущих IP — GET /admin/api/users/ips?id= (по умолчанию, идиоматично для
   read) или POST с телом {id}? Беру GET, если не возражаешь.
2. Где показывать текущие IP в UI: отдельная кнопка «IP» в строке таблицы с
   поповером/модалкой, или секция внутри модалки редактирования пользователя? По умолчанию —
   кнопка «IP» в строке (display-only, минимум UI).
3. Поведение user_ips при недоступном узле: вернуть 200 с частичным результатом (пустой
   список + пометка по узлу) или 500? По умолчанию — 200 + частичный (read, не критично).