Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки

[Postlog]

Приоритет: high · Размер: L · Бэклог-ранг: 7/20

Проблема

users (0001-init.sql:42-47) содержит только id/name/sub_id/created_at — нет колонки enabled; grep не находит концепта suspend/disable/active. Единственный рычаг отключения доступа — DeleteUser (service.go:253), разрушающий строку; пересоздание минтит новый sub_id (genID на service.go:184) → новый URL, который каждый клиент должен переимпортировать. Обратимо приостановить и восстановить доступ на той же ссылке невозможно.

Почему важно

Обратимый suspend (неоплата, абьюз, диагностика) с сохранением ссылки — базовая возможность подписочного сервера, полностью отсутствует. Высокая операторская ценность.

Предлагаемое решение

Флаг enabled на users (новая NNNN-миграция), тоггл в админке, путь провижининга, флипающий 3x-ui-клиента Enable (или снимающий/добавляющий привязки) с сохранением uuid/subId.

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

• internal/service/provisioning/service.go, internal/handlers/users_get/handler.go, migrations/0001-init.sql, internal/handlers/web/static/app.js

---

_{Из аудита кодовой базы subgen (10 подсистем → adversarial-верификация, 71 находка). Бэклог-ранг указан для приоритизации.}

[Postlog]

Issue #89 — Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки

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

Резюме

Добавляем обратимый флаг users.enabled (новая миграция) и путь suspend/resume: при выключении пользователь остаётся в БД (тот же sub_id, та же ссылка, тот же uuid на панели), но его 3x-ui-клиент провижинится с enable:false — доступ закрыт, ссылка живёт. Тоггл в админке (POST /admin/api/users/toggle), флаг прокидывается из стора через provisioning.syncPanels в xui.AddClient.

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

• users (migrations/0001-init.sql:42-47) действительно не имеет enabled. Описание добавлялось отдельной миграцией 0002-users-description.sql — тот же паттерн ALTER годится.
• Единственный «рычаг» — DeleteUser (internal/service/provisioning/service.go:253), sub_id минтится s.genID(16) в CreateUser (service.go:184) — пересоздание = новый токен. Подтверждено.
• 3x-ui клиент уже умеет нести признак включённости: xui.AddClient (internal/clients/xui/add_client.go:18) хардкодит "enable": true. Это и есть точка, через которую suspend опускается на панель — делаем поле enable параметром, а не константой.
• syncPanels (service.go:303) уже выполняет re-bind delete-then-add с сохранением uuid (uuidByEmail, service.go:367) и subId (u.SubID, service.go:393). Suspend/resume = тот же re-bind, но с нужным enable. Никакого нового пути на панель не требуется — переиспользуем существующий.
• ClientSpec (internal/entity/panel.go:58-64) — DTO для создания клиента; добавляем сюда Enabled bool.
• Поле description (User.Description, users.SetDescription, 0002-*.sql) — эталон для нового скалярного апдейта SetEnabled.

Решение по механике (допущение, явно фиксирую): suspend реализуем как ре-байнд того же клиента с enable:false через имеющийся syncPanels, а не через 3x-ui-роут update/:email. Причины: (а) syncPanels/AddClient уже сохраняют uuid/subId/email — требование issue выполняется без нового клиентского метода; (б) update/:email потребовал бы отдельного тонкого метода клиента и новой ветки логики, дублирующей re-bind. Если владелец предпочитает in-place update (см. открытые вопросы) — план меняется только в слое клиента+сервиса, схема/миграция/фронт те же.

---

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

1. Миграция БД — migrations/0003-users-enabled.sql

Новый forward-only файл (нумерация: 0003-strict-mihomo-refs.notx.sql уже занят — берём 0004-users-enabled.sql, чтобы не конфликтовать по имени; см. раздел «Миграции БД»). Чистый DDL, в транзакции (без .notx):

-- 0004: reversible per-user suspend flag. DEFAULT 1 so every existing user stays
-- enabled after adoption; NOT NULL keeps the domain bool total (no *bool needed).
ALTER TABLE users ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1;

2. internal/entity — доменная модель и sentinel

• internal/entity/user.go:
  • Добавить поле Enabled bool в User (после Description).
  • Сканеры в репозитории должны его читать (см. шаг 3).
• internal/entity/panel.go:
  • В ClientSpec добавить Enabled bool — признак, который клиент опустит в enable тела add.
• internal/entity/errors.go:
  • Sentinel не нужен для самого тоггла (нет value-валидации входа — id суррогатный, enabled — bool, оба без constraints). Ошибки users.Get/панелей остаются инфраструктурными → 500. Не заводить искусственных доменных ошибок.

3. 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
  }

• Чтение — расширить SELECT-ы, чтобы Enabled приезжал в User:
  • get.go:15-16 — добавить enabled в список колонок и в Scan (&u.Enabled).
  • list_page.go — добавить enabled во все четыре SELECT id,name,sub_id,description,created_at … (строки 31/35/39/43) и в rows.Scan (list_page.go:69).
  • Проверить прочие селекты users на полноту: list.go, list_names.go, list_page.go. Те, что не материализуют User целиком (sub_ids.go, id_by_sub_id.go, list_names.go), не трогаем. list.go (если возвращает entity.User) — добавить колонку.
• SQLite пишет INTEGER-bool; database/sql сканит 0/1 в bool штатно.

4. internal/clients/xui — enable как параметр, не константа

• add_client.go: заменить "enable": true на "enable": cs.Enabled (cs entity.ClientSpec). Это единственная правка клиента при выбранном механизме re-bind.
• add_client_test.go: добавить кейс таблицы, проверяющий, что при Enabled:false тело содержит "enable":false (ассерт по сырому JSON запроса в httptest-моке). Это новый столбец входа в существующем TestClient_AddClient.

5. internal/service/provisioning — пробросить enabled в re-bind + метод SetUserEnabled

• contract.go: в userRepo добавить SetEnabled(ctx, userID int64, enabled bool) error. Перегенерить мок: go generate ./internal/service/provisioning/... (mockgen по contract.go).
• syncPanels (service.go:303-403): при сборке entity.ClientSpec (service.go:393) проставлять Enabled: u.Enabled. Поскольку *entity.User уже передаётся в syncPanels, флаг доступен без изменения сигнатуры. Это автоматически чинит и CreateUser/EditUser/RecreateUser — все провижинят с актуальным enable.
• Новый метод SetUserEnabled(ctx context.Context, id int64, enabled bool) error (новый файл set_enabled.go в пакете, или в service.go рядом с RecreateUser):

  func (s *Service) SetUserEnabled(ctx context.Context, id int64, enabled bool) error {
      u, err := s.users.Get(ctx, id)            // fmt.Errorf("users.Get: %w", err)
      if u.Enabled == enabled { return nil }    // no-op: не дёргаем панели зря
      if err := s.users.SetEnabled(ctx, id, enabled); err != nil { ... }
      u.Enabled = enabled
      byID, _, err := s.nodeIndex(ctx)
      // re-bind по текущим connections как в RecreateUser (forceAll=true),
      // чтобы enable долетел до панели на тех инбаундах, где клиент уже есть.
      var desired []connTarget
      for _, c := range u.Connections { desired = append(desired, connTarget{NodeID:c.NodeID, Node:c.Node, Port:c.Port, InboundID:c.InboundID}) }
      return s.syncPanels(ctx, byID, u, u.Connections, desired, true)
  }

  • forceAll=true нужен: множество инбаундов не меняется, иначе sameInboundIDs (service.go:351) сократил бы re-bind и enable не обновился бы. Re-bind сохраняет uuid (через uuidByEmail) и subId — требование issue (сохранение ссылки) выполнено.
  • Порядок: сперва пишем флаг в БД (источник истины), затем панели best-effort (как в существующих методах — частичный успех возвращает ошибку, но строка уже консистентна).

6. OpenAPI + ogen — новая ручка userToggle

• Новый openapi/user_toggle.yaml (по образцу user_recreate.yaml):
  • operationId: userToggle, POST, security: [adminSession].
  • Тело: required: [id, enabled], id: {type: integer, format: int64}, enabled: {type: boolean}. Только форма — никаких value-constraints (правило AGENTS).
  • Ответы: 200 → MessageResponse, 400 → ErrorResponse, 401 → ErrorResponse (как у recreate).
• openapi/openapi.yaml: добавить путь

  /admin/api/users/toggle:
    $ref: './user_toggle.yaml'

  (рядом с users/recreate, openapi.yaml:40-41).
• Прогнать go generate ./internal/oas/.

7. Handler — internal/handlers/user_toggle/handler.go

По образцу user_recreate (тонкий, без 4xx-доменки — все ошибки инфраструктурные → 500):

• Пакет user_toggle, метод UserToggle(ctx, req *oas.UserToggleReq) (oas.UserToggleRes, error).
• Зависимость — contract.go с интерфейсом toggler { SetUserEnabled(ctx, id int64, enabled bool) error } + mockgen.
• Текст-константы (две, т.к. сообщение зависит от направления):

  const (
      MsgEnabled  = "Пользователь включён"
      MsgDisabled = "Пользователь отключён"
  )

• Логика: SetUserEnabled(req.ID, req.Enabled); при ошибке slog.Error("handler user_toggle: toggle failed", "id", req.ID, "enabled", req.Enabled, "err", err) → return nil, err (500). Успех → MessageResponse{Message: ...} по req.Enabled.

8. Композит + main — регистрация

• internal/handlers/api/server.go: добавить UserToggle *userToggleHandler.Handler в Handlers, форвард-метод func (s *Server) UserToggle(...), импорт.
• cmd/service/main.go: UserToggle: userToggleHandler.New(prov) рядом с UserRecreate (main.go:212). prov (provisioning) уже сконструирован.

9. Отдача статуса в админку (read-ручка)

• internal/handlers/users_get/handler.go (UsersGet, строка 75): добавить Enabled: u.Enabled в oas.UsersGetOKUsersItem.
• openapi/users_get.yaml: добавить в схему элемента списка булево поле enabled (required, type: boolean) — фронт рисует тоггл по нему. Регенерация ogen.

10. Фронт — тоггл в строке пользователя

• internal/handlers/web/static/index.html (блок строки tr v-for="u in users", ~строка 81-88): добавить кнопку/переключатель статуса в .act-group, напр.:

  <button class="btn btn-sm act" :class="u.enabled ? 'btn-outline-secondary' : 'btn-warning-soft'"
          :disabled="busy" @click="toggleUser(u)">{{ u.enabled ? 'Отключить' : 'Включить' }}</button>

  Визуально пометить отключённого (CSS-класс на <tr>, напр. :class="{acting:..., disabled:!u.enabled}" + приглушённый стиль в app.css).
• internal/handlers/web/static/app.js: метод toggleUser(u) по образцу recreateUser (app.js:419):

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

• app.css: класс приглушения отключённой строки в палитре темы (bg/opacity), при желании бейдж «отключён».

---

Миграции БД

• Имя файла: migrations/0004-users-enabled.sql (не 0003 — 0003-strict-mihomo-refs.notx.sql занят; лексический порядок = порядок наката, см. migrations/run.go:57).
• Содержимое — см. шаг 1. Обычная транзакция (не .notx): простой ALTER ADD COLUMN, без перестройки таблицы и без переключения foreign_keys.
• DEFAULT 1 критичен: усыновлённые/существующие пользователи остаются включёнными. NOT NULL — чтобы домен был bool, а не *bool.
• Откатов нет (forward-only) — правило репозитория.

OpenAPI/ogen

• Новый openapi/user_toggle.yaml + $ref в openapi/openapi.yaml (шаг 6).
• Правка openapi/users_get.yaml — поле enabled в item (шаг 9).
• go generate ./internal/oas/ после правок спеки.
• Value-валидации в схеме нет (правило AGENTS): тело {id, enabled} без constraints; id суррогатный — не валидируем.

Тесты

• internal/service/provisioning — TestService_SetUserEnabled (table-driven, один тест на метод). Кейсы: success.disable (Get→enabled, SetEnabled(false), re-bind с Enabled:false через мок panelClient.AddClient), success.enable, noop.same_state (флаг уже равен — ни SetEnabled, ни панелей), error.users_get, error.set_enabled. Моки — локальные Mock* из provisioning/contract.go (с добавленным SetEnabled). Проверять, что AddClient получает ClientSpec{Enabled: ...} и тот же SubID/сохранённый uuid.
  • Сверить/дополнить существующий TestService_CreateUser/EditUser/RecreateUser: теперь AddClient получает Enabled: u.Enabled — поправить ожидаемые ClientSpec в service_test.go (там, где сверяется AddClient, строки ~151), иначе gomock-матчер на полную структуру упадёт.
• internal/clients/xui — расширить TestClient_AddClient кейсом Enabled:false → "enable":false в теле (ассерт по сырому JSON).
• internal/repository/users — обновить get_test.go/list_page_test.go, чтобы фикстуры/ожидания содержали enabled (фейковая БД отдаёт колонку; ожидаемый User.Enabled). Новый set_enabled_test.go по образцу — если в пакете тестируются простые сеттеры; если set_description.go без отдельного теста — следовать тому же уровню покрытия (проверить наличие set_description_test.go; его в листинге нет → отдельный тест SetEnabled не обязателен, но не противоречит правилам).
• internal/handlers/user_toggle — TestHandler_UserToggle (мок toggler): success.enable/success.disable (проверить текст сообщения), error.infra → 500 (return nil, err).
• apitest (apitest/, build-тег apitest) — добавить сценарий в UserSuite: создать юзера, POST /admin/api/users/toggle {enabled:false} → 200, проверить через GET /admin/api/users, что enabled=false и sub.url/sub.id не изменились (ключевая гарантия issue). Тело — map[string]any (чёрный ящик, не из oas).

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

• CHANGELOG.md: запись ## 2026-06-12 — Per-user enable/disable (suspend) (#<PR>) + 1-2 строки: обратимый флаг users.enabled, тоггл в админке, suspend ре-байндит 3x-ui-клиента с enable:false, sub_id/uuid/ссылка сохраняются.
• ADR: пограничный случай. Решение «re-bind vs update/:email» — нетривиальный выбор механизма. Если выбран re-bind по умолчанию — короткий ADR-0004 «User suspend via client re-bind» (Context/Considered Options: re-bind delete+add vs 3x-ui update/:email vs delete-then-recreate; Decision; Consequences). Рекомендую завести ADR — есть развилка и trade-off. Ссылку положить в CHANGELOG.

Риски и edge-cases

• AddClient enable-семантика: убедиться на живой панели (read-only сначала), что enable:false в /panel/api/clients/add реально выключает доступ, но клиент остаётся в инбаунде (а не отбрасывается). Если 3x-ui игнорирует enable:false на add — fallback на update/:email (см. открытые вопросы). Это главный технический риск.
• Частичный провижининг: как и сейчас, при недоступной панели флаг в БД уже записан, а панель вернёт ошибку → 500; оператор повторит (idempotent). Документировать в комментарии метода.
• Фронт-фильтры: тоггл не должен ломать существующие пагинацию/фильтры (loadUsers перезагружает страницу — ок).
• Рендер подписки: проверить, что отключённый клиент корректно выпадает из fleet/build.go (там уже if !cs.Enable пропускает, build.go:57) — т.е. отключённый юзер получит пустую/урезанную подписку, но ссылка валидна. Это согласуется с issue (доступ закрыт, ссылка жива).
• enabled в прочих read-путях: если где-то ещё материализуется entity.User без новой колонки в SELECT — Scan упадёт. Прогнать grep "SELECT .* FROM users" по internal/repository/users и обновить все полные выборки.

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

Самодостаточно, без зависимости от других issue (#83–#113). Затрагивает те же области, что #15 (description) — конфликтов нет, паттерн переиспользуется.

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

1. Механизм suspend на панели: re-bind (delete+add с enable:false, сохраняя uuid) — мой дефолт; либо завести тонкий xui.UpdateClient поверх 3x-ui update/:email и флипать enable in-place (без delete). Re-bind проще и переиспользует существующий код, но кратко «снимает» клиента. Какой вариант предпочесть? (Влияет только на слой клиента+сервиса; схема/миграция/фронт идентичны.)
2. Семантика отключённого в подписке: подтвердить, что отключённый пользователь должен получать пустую/без-прокси подписку по той же ссылке (текущее поведение fleet/build.go его прокси выкидывает), а не 403/ошибку на /sub/.... Дефолт — отдавать валидную, но пустую подписку.

[Postlog]

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

Механика проверена по исходникам 3x-ui v3.2.6:

• Suspend/resume — через новый метод xui.UpdateClient (POST /panel/api/clients/update/:email) с in-place флипом enable. НЕ через delete+add: add-путь панели делает force-enable (if !client.Enable { Enable = true }), что молча снимет suspend.
• Resume = слать enable:true (при необходимости вместе с expiryTime); сохраняем тот же uuid/subId/email.
• ClientSpec.Enabled вместо хардкода "enable": true в internal/clients/xui/add_client.go.
• Этот же UpdateClient переиспользуют Лимит трафика (ГБ) на пользователя с учётом расхода и ручным сбросом #103 (трафик), Срок действия подписки + фоновый планировщик автоотключения по истечении #104 (срок), Переключатель Включён/Отключён в строке пользователя (мгновенный kill-switch) #107 (тоггл) — один новый метод клиента на всю панельную механику фич.