Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch)

[Postlog]

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

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

Switch «Включён» в строке таблицы пользователей и в форме редактирования. Отключение = ре-байнд того же клиента с enable:false (сохраняя uuid/subId), включение — обратно.

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

3x-ui (enable-флаг на клиенте), Marzban/Marzneshin (status disabled), Remnawave/Hiddify (enable toggle). Включение/отключение без удаления — у всех.

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

fleet/build.go:57 уже читает cs.Enable и пропускает выключенных, но subgen никогда сам не выставляет enable (add_client.go хардкодит enable:true), и в UI нет переключателя. #89 закладывает enabled-флаг — эта фича добавляет к нему UI-переключатель/кнопку в строке как ручной kill-switch и опору для автоотключения по квоте/сроку (#103/#104).

Зачем

Оператор мгновенно приостанавливает неоплатившего/злоупотребляющего пользователя и возвращает после оплаты, не теряя UUID/subId/историю. И ручной kill-switch, и фундамент для энфорсмент-джоб. Subgen сегодня умеет только удалять.

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

Поверх #89: новый метод xui-клиента UpdateClient (POST /panel/api/clients/update/:email с enable) — один файл update_client.go + httptest-тест; provisioning.SetEnabled (re-bind того же uuid с флагом). Ручка user_set_enabled (openapi → ogen), тонкий хендлер (sentinel→4xx). Во Vue — switch в строке/форме. ClientSpec.Enable вместо хардкода.

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

• internal/entity/panel.go (ClientSpec.Enable), internal/clients/xui/update_client.go (новый) + тест, contract.go, add_client.go
• internal/service/provisioning/service.go (SetEnabled), openapi/user_set_enabled.yaml (новый)
• internal/handlers/user_set_enabled/, internal/handlers/web/static/{app.js,index.html}

---

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

[Postlog]

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

Issue: #107 — Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch)

Резюме

Добавляем оператору ручной reversible kill-switch: тоггл enabled на пользователе, который ре-байндит того же 3x-ui-клиента (uuid/subId/email сохраняются) с enable:false/true. Фича — UI-надстройка поверх enabled-флага из #89; снизу нужен новый метод xui-клиента UpdateClient, путь провижининга SetEnabled, ручка user_set_enabled и переключатель во Vue.

Зависимость от #89 (КРИТИЧНО — прочитать первым)

Issue #89 (Per-user enable/disable) — OPEN, не смёржен. Он вводит:

• колонку enabled на таблице users (новая NNNN-миграция),
• поле entity.User.Enabled bool,
• сам сервисный путь suspend/restore во provisioning.

Issue #107 в своём теле прямо пишет: «Поверх #89: … добавляет к нему UI-переключатель». То есть #107 не самодостаточен: ему нужны и колонка БД, и проброс enabled в read-ручку, и сервисный путь. Реальный код подтверждает, что этого ещё нет: migrations/ содержит только 0001..0003, в users нет enabled (0001-init.sql:42), entity.User (internal/entity/user.go) поля Enabled не имеет, add_client.go:18 хардкодит "enable": true, метода UpdateClient/SetEnabled нет.

Рекомендуемый порядок: делать #107 в одном PR с #89 (или строго после мёрджа #89). Если #89 ещё не сделан — этот PR обязан включить и серверную часть #89 (колонка + entity.User.Enabled + read-проброс), иначе фронт-тоггл не на что опереть. План ниже самодостаточен — описывает полный стек, помечая, что относится к зоне #89, что — собственно к #107 (клиент UpdateClient, ручка, UI). Дублирования миграции/поля не допускать: если #89 уже их завёл — переиспользуем, не плодим вторую миграцию на enabled.

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

1. entity (зона #89, нужно #107)

• internal/entity/user.go: добавить поле Enabled bool в User (по умолчанию провижинится true). Это значение читается в read-ручке и пишется тоглом.
• internal/entity/panel.go: в ClientSpec добавить поле Enable bool — чтобы AddClient/re-bind перестали хардкодить enable:true и несли состояние явно. Это убирает магический хардкод add_client.go:18.
• internal/entity/errors.go: новый sentinel не нужен — у тоггла нет доменной 4xx-развилки (несуществующий id → not-found → 500, см. конвенцию «суррогатные id не валидируем»). Логическое состояние enabled булево, валидировать нечего.

2. repository/users (зона #89)

• Новый файл internal/repository/users/set_enabled.go (один метод — один файл, по аналогии с set_description.go):

  func (r *Repository) SetEnabled(ctx context.Context, userID int64, enabled bool) error {
      _, err := r.db.ExecContext(ctx, `UPDATE users SET enabled=? WHERE id=?`, enabled, userID)
      return err
  }

• Проброс enabled в чтения: get.go и list_page.go — добавить enabled в SELECT и в Scan (&u.Enabled). Сейчас оба тянут id,name,sub_id,description,created_at; станет …,enabled. Проверить также list.go/load_connections.go — но connections к флагу не относятся, трогать только пользовательские SELECT'ы. SQLite хранит bool как 0/1 — database/sql скан в *bool работает.
• create.go: вставлять enabled явным 1 (или положиться на DEFAULT 1 из миграции — предпочтительно DEFAULT, чтобы INSERT не разъезжался).

3. clients/xui — UpdateClient (собственно #107, ядро)

• Новый файл internal/clients/xui/update_client.go (один метод — один файл):

  // UpdateClient re-binds an existing client (same uuid/email/subId) on the given
  // inbounds, flipping its enable flag. 3x-ui route: POST /panel/api/clients/update/:email.
  func (c *Client) UpdateClient(ctx context.Context, t entity.PanelTarget, inboundIDs []int, cs entity.ClientSpec) error

  Тело идентично AddClient ({"client":{…,"enable":cs.Enable,"tgId":0,…},"inboundIds":[…]}), путь — /panel/api/clients/update/+url.PathEscape(cs.Email). enable берётся из cs.Enable (не хардкод). tgId остаётся int 0 (иначе 400 — см. AGENTS.md). Использует существующий c.postJSON.

• Уточнение реализации (решено дефолтом): issue предлагает update/:email. Но update на 3x-ui требует точного совпадения inboundIds с текущей привязкой, иначе клиент слетит с части инбаундов. Безопаснее и единообразнее с уже существующим syncPanels — re-bind через delete-then-add того же uuid (как делает EditUser/RecreateUser), просто с Enable=false. Это переиспользует проверенный путь и не вводит хрупкий update. Поэтому метод UpdateClient опционален: если идём путём delete-then-add, достаточно прокинуть ClientSpec.Enable в существующий AddClient и не заводить новый клиентский метод. Решение зафиксировать в ADR (см. ниже). По умолчанию выбираю delete-then-add re-bind (меньше нового API-surface, переиспользование syncPanels); update_client.go тогда не создаём, а ClientSpec.Enable прокидываем в AddClient.

• internal/clients/xui/add_client.go: заменить "enable": true на "enable": cs.Enable.

4. service/provisioning — SetEnabled (собственно #107)

• В service.go новый метод:

  // SetEnabled flips a user's enabled flag in the store and re-binds the same client
  // (uuid/subId preserved) on every panel with the new enable state.
  func (s *Service) SetEnabled(ctx context.Context, id int64, enabled bool) error

  Логика:
  1. u, err := s.users.Get(ctx, id) → 500-обёртка.
  2. s.users.SetEnabled(ctx, id, enabled) → 500-обёртка.
  3. byID, _, err := s.nodeIndex(ctx).
  4. Сформировать desired []connTarget из u.Connections (как в RecreateUser).
  5. Прокинуть enabled в re-bind. Чистый способ: расширить syncPanels сигнатурой enabled bool (или хранить состояние в *entity.User и читать u.Enabled), чтобы entity.ClientSpec{…, Enable: enabled} уходил в AddClient. forceAll=true (как Recreate — перепривязать все панели независимо от диффа инбаундов).
  • Так как state живёт на u.Enabled, чище всего: после SetEnabled выставить u.Enabled = enabled и в syncPanels/при сборке ClientSpec читать u.Enabled. Тогда CreateUser/EditUser/RecreateUser тоже начнут проставлять Enable: u.Enabled (у нового юзера Enabled=true). Это единая точка — никаких хардкодов true.
• internal/service/provisioning/contract.go: в userRepo добавить SetEnabled(ctx, userID int64, enabled bool) error; в panelClient — оставить как есть, если идём delete-then-add (метод UpdateClient не нужен). Перегенерить мок: go generate ./internal/service/provisioning/.

5. openapi + ogen (собственно #107)

• Новый openapi/user_set_enabled.yaml — копия user_recreate.yaml, но тело запроса несёт enabled:

  post:
    operationId: userSetEnabled
    summary: Enable or disable a user (reversible kill-switch)
    security: [ { adminSession: [] } ]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [id, enabled]
            properties:
              id:      { type: integer, format: int64 }
              enabled: { type: boolean }
    responses:
      '200': { MessageResponse }   # как в recreate
      '400': { ErrorResponse }
      '401': { ErrorResponse }

  Только форма (required/type), без value-constraints (правило AGENTS.md).
• openapi/openapi.yaml: добавить путь /admin/api/users/set-enabled → $ref: './user_set_enabled.yaml' (рядом с /admin/api/users/recreate).
• users_get.yaml: в схему элемента списка users[]. добавить enabled: { type: boolean } и внести его в required. Это read-проброс (зона Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89, нужен фронту для начального состояния тоггла).
• go generate ./internal/oas/ — перегенерить internal/oas (типы UserSetEnabledReq, UserSetEnabledRes, поле Enabled в UsersGetOKUsersItem).

6. handlers (собственно #107)

• Новый пакет internal/handlers/user_set_enabled/ (handler.go + contract.go + contract_mocks.go + handler_test.go), по образцу user_recreate:

  // contract.go
  type enabler interface { SetEnabled(ctx context.Context, id int64, enabled bool) error }
  // handler.go
  const MsgEnabled  = "Пользователь включён"
  const MsgDisabled = "Пользователь отключён"
  func (h *Handler) UserSetEnabled(ctx, req *oas.UserSetEnabledReq) (oas.UserSetEnabledRes, error) {
      if err := h.svc.SetEnabled(ctx, req.ID, req.Enabled); err != nil {
          slog.Error("handler user_set_enabled: set failed", "id", req.ID, "enabled", req.Enabled, "err", err)
          return nil, err  // нет доменной 4xx-развилки → 500
      }
      return &oas.MessageResponse{Message: msg(req.Enabled)}, nil
  }

  Доменных sentinel'ов у операции нет (как у user_recreate) → любая ошибка = логированный 500. Тексты — локальные константы (две: вкл/выкл).
• internal/handlers/users_get/handler.go: проставить row.Enabled = u.Enabled при сборке oas.UsersGetOKUsersItem.
• internal/handlers/api/server.go: добавить поле UserSetEnabled *userSetEnabledHandler.Handler в Handlers, импорт, и метод-форвард func (s *Server) UserSetEnabled(...) {...} (по аналогии с UserRecreate, строки 142-143). Без UnimplementedHandler — компилятор проверит полноту oas.Handler.
• cmd/service/main.go: завести UserSetEnabled: userSetEnabledHandler.New(prov) в литерале Handlers{} (рядом со UserRecreate, ~строка 212) + импорт пакета.

7. фронт (собственно #107)

• internal/handlers/web/static/app.js:
  • В строке таблицы пользователей — switch/тоггл, читающий u.enabled. Метод:

    async toggleEnabled(u) {
      this.actingId = u.id;
      try { const d = await this.post("/admin/api/users/set-enabled", { id: u.id, enabled: !u.enabled }); if (d.ok) await this.loadUsers(); }
      finally { this.actingId = 0; }
    }

    (по образцу recreateUser, строки 419-423).
  • В форме редактирования (uForm) — переключатель «Включён»; openEdit уже строит uForm из u, добавить enabled: u.enabled. Можно либо тоглить отдельной ручкой (как kill-switch в строке), либо включить enabled в submitUser тело edit'а — дефолт: отдельная ручка set-enabled (issue называет это «kill-switch в строке/форме», атомарный тоггл лучше, чем смешивать с edit-формой, у которой другая семантика провижининга). В форме переключатель тоже зовёт toggleEnabled.
  • Стиль — в токенах темы 3x-ui (см. app.css); визуально отличать выключенного пользователя (приглушённая строка/бейдж «Отключён»).
• internal/handlers/web/static/index.html: разметка switch'а в строке/форме (если шаблон строки там, а не в app.js-template — проверить; основной template в app.js).
• app.css: при необходимости — стиль бейджа/приглушённой строки.

Миграции БД

Зона #89. Новая миграция migrations/0004-users-enabled.sql (если #89 её ещё не добавил; следующий свободный номер после 0003-strict-mihomo-refs.notx.sql):

-- 0004-users-enabled.sql — reversible per-user kill-switch.
ALTER TABLE users ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1;

Чистый DDL, обычная tx-миграция (не .notx — RENAME/FK-перестройки нет). Forward-only. Если #89 уже завёл 0004-…enabled-миграцию — не дублировать, переиспользовать.

OpenAPI/ogen

• openapi/user_set_enabled.yaml (новый) + $ref в openapi/openapi.yaml.
• openapi/users_get.yaml: добавить enabled: boolean в схему/required элемента списка.
• go generate ./internal/oas/ после правок спеки.
• Value-валидации в схеме нет (булев флаг + id; id суррогатный — не валидируем).

Тесты

• internal/service/provisioning/service_test.go: новый TestService_SetEnabled (table-driven, один тест на метод). Кейсы: success.disable (мокаются users.Get→юзер с connections, users.SetEnabled, nodes.List, client.ListInbounds+DelClient+AddClient с ClientSpec.Enable=false), success.enable (Enable=true), error.users_get (downstream err), error.set_enabled, error.panel (AddClient падает → агрегированная ошибка). Проверять, что в AddClient уходит правильный Enable. Моки — из локального contract.go (перегенерить после добавления SetEnabled в userRepo).
• internal/clients/xui/update_client_test.go — только если выберем путь UpdateClient (httptest.Server, проверка пути /panel/api/clients/update/:email, тела с enable, разбора {success,msg}). При дефолтном delete-then-add отдельный клиентский тест не нужен; вместо него — обновить add_client_test.go, чтобы он проверял, что enable берётся из cs.Enable (а не хардкод).
• internal/handlers/user_set_enabled/handler_test.go: TestHandler_UserSetEnabled (table-driven). Кейсы: success.enable/success.disable (мок enabler.SetEnabled → nil, ассерт MsgEnabled/MsgDisabled), error.downstream (→ возврат ошибки = 500). Мок enabler из локального contract.go.
• internal/repository/users: если репозиторий покрыт unit-тестами на CRUD — добавить ветку на SetEnabled и проверить, что Get/ListPage читают enabled. (Репо-тесты в проекте есть: get_test.go, list_page_test.go — расширить ассерты на новое поле.)
• apitest (apitest/): желателен сценарий в UserSuite — создать юзера, дёрнуть POST /admin/api/users/set-enabled {id,enabled:false} (тело — сырой map[string]any, не из oas), проверить 200 + {message}, затем что GET /admin/api/users отдаёт enabled:false для этого юзера. Опционально проверить против реального 3x-ui, что клиент стал enable:false. apitest — чёрный ящик, тела руками.

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

• CHANGELOG.md — одна запись:
  ## 2026-06-12 — Per-user kill-switch: тоггл Включён/Отключён (#107) + 1-2 строки сути + ссылка на ADR (если делаем). Если Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 и Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch) #107 идут одним PR — одна запись, покрывающая обе.
• ADR — да, нетривиальная развилка есть: как реализовать disable на стороне 3x-ui — (a) POST /panel/api/clients/update/:email с enable:false против (b) delete-then-add re-bind того же uuid (переиспользование syncPanels). Завести docs/decisions/0004-per-user-kill-switch.md (следующий свободный номер — проверить, не занял ли Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89; если Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 завёл ADR на сам enabled-флаг, этот — на способ провижининга/UI и Supersedes/ссылку не нужен). Секции Context/Considered Options/Decision/Consequences. Зафиксировать выбор delete-then-add (или update) с обоснованием.

Риски и edge-cases

• Зависимость от Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 — главный риск. Без серверной части Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 фронт-тоггл повиснет в воздухе. См. раздел «Зависимость» — делать совместно или строго после.
• update vs delete-then-add: update/:email на 3x-ui требует, чтобы inboundIds точно совпадали с текущей привязкой, иначе клиент слетит с части инбаундов; delete-then-add (с сохранением uuid через panelLookup) — уже проверенный путь в syncPanels. Дефолт — delete-then-add.
• Частичный провижининг: панель недоступна → syncPanels агрегирует failures в одну ошибку (хендлер вернёт 500), но строка users.enabled уже обновлена. Это согласовано с поведением CreateUser/EditUser (строка пишется, провижининг может быть partial). Оператор повторит/нажмёт Recreate.
• fleet-кеш: fleet/build.go:43,57 уже пропускает !pi.Enable/!cs.Enable — после disable выключенный клиент исчезнет из подписки на следующем обновлении кеша флита (TTL). Мгновенности на стороне /sub нет — это ожидаемо (kill-switch на уровне панели + кеш). Health-бейджи в users_get берутся из кеша флита.
• ClientSpec.Enable рефактор: добавление поля и его проброс через CreateUser/EditUser/RecreateUser нужно сделать аккуратно, чтобы новые юзеры по-прежнему создавались Enabled=true. Все три пути должны читать u.Enabled, а не хардкод.
• Read-проброс enabled: убедиться, что ВСЕ SELECT'ы юзера (get.go, list_page.go, при наличии — list.go) тянут колонку, иначе скан разъедется или поле будет нулевым.

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

• Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (Per-user enable/disable) — прямая зависимость: даёт колонку enabled, entity.User.Enabled, базовый suspend-путь. Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch) #107 = UI-надстройка поверх. Делать в одном PR с Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 либо строго после его мёрджа.
• Смежные (не блокеры, фундамент на будущее): Лимит трафика (ГБ) на пользователя с учётом расхода и ручным сбросом #103/Срок действия подписки + фоновый планировщик автоотключения по истечении #104 (автоотключение по квоте/сроку) переиспользуют SetEnabled как энфорсмент-примитив — учесть, что SetEnabled должен быть вызываем и из джоб, не только из хендлера (он уже сервисный — ок).

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

1. Порядок с Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89: мёржим Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 отдельно и Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch) #107 поверх, или собираем оба в один PR? От этого зависит, входит ли в этот PR серверная часть (миграция + entity.User.Enabled + read-проброс) или она уже будет в основной ветке.
2. Способ disable на 3x-ui: ок ли дефолт «delete-then-add re-bind того же uuid» (переиспользование syncPanels, меньше нового API) вместо буквального POST /clients/update/:email из тела issue? Re-bind безопаснее (не зависит от точного совпадения inboundIds), но делает лишний DelClient+AddClient на каждый тоггл.

[Postlog]

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

• Тоггл Включён/Отключён использует общий xui.UpdateClient (update/:email), не delete+add (см. Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 — add-путь force-enable'ит).
• Серверная часть (enabled в схеме/entity.User/read-проброс) — общая с Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89; порядок: Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 первым, Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch) #107 поверх (либо один PR).