Срок действия подписки + фоновый планировщик автоотключения по истечении

[Postlog]

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

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

Поле «Срок действия» в форме пользователя: режимы «Без срока» / «До даты» (date-picker) / «N дней от первого подключения» (число + чекбокс «активировать при первом подключении»); бейдж «истекает через N дней» в строке (жёлтый/красный у порога) и бейдж «истёк». Фоновый воркер раз в интервал отключает истёкших.

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

Marzban (unix expire), Marzneshin (expire_strategy: fixed_date / start_on_first_use / never), 3x-ui (expiryTime, режим активации при первом подключении), Remnawave (статус expired), Hiddify (package days).

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

fleet/build.go уже читает cs.Expiry, а sub/handler.go:139 отдаёт expire в Subscription-Userinfo, но это read-only зеркало панели — subgen не задаёт expiryTime (add_client.go шлёт expiryTime:0), не показывает дату/остаток дней и не отключает истёкших. Планировщика/cron в кодовой базе нет.

Зачем

Операторы продают планы с ограничением по времени (30/90/365 дней); «активация при первом подключении» критична для предоплаченных ваучеров — часы не идут, пока код не активирован. Subgen сегодня не умеет ограничивать доступ по времени вообще.

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

ClientSpec.ExpiryTime + убрать хардкод; колонка expiry_ms в users (отрицательная для режима «от первого использования», как у 3x-ui) + поля в Create/EditParams. Новый internal/service/reconciler (горутина-тикер в cmd/service/main.go): читает флит, сравнивает Expiry с now, переводит истёкших в disabled (через флаг #89, re-bind без удаления uuid/subId). Режим first-use — флип отрицательной длительности в дату при первом успешном /sub (хендлер уже резолвит юзера по токену). Остаток дней — в users_get, бейдж во Vue.

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

• internal/entity/panel.go (ClientSpec.ExpiryTime), internal/entity/user.go
• internal/clients/xui/add_client.go, update_client.go (новый) + тест
• internal/service/provisioning/service.go, internal/service/reconciler/ (новый), cmd/service/main.go
• migrations/NNNN-user-expiry.sql, openapi/{user_create,user_edit}.yaml
• internal/handlers/users_get/, internal/handlers/sub/handler.go (first-use), internal/handlers/web/static/

---

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

[Postlog]

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

Резюме. Добавляем пользователю «срок действия» (без срока / до даты / N дней от первого подключения) — он начинает реально провижиниться в 3x-ui (expiryTime), показывается в админке (остаток дней / истёк), а фоновый воркер-тикер периодически отключает истёкших. Режим «от первого подключения» активируется при первом успешном /sub.

ВАЖНО — зависимость от #89. Issue открыт и ещё не реализован. Реконсайлер по истечении срока должен отключать пользователя (suspend), а не удалять (удаление сменит sub_id/uuid и сломает ссылку). Механизма disable в коде сегодня нет (users не имеет enabled, единственный рычаг — DeleteUser). Поэтому план разбит на две части: B1 (база срока действия) не зависит от #89 и поставляется сразу; B2 (автоотключение реконсайлером) строится поверх suspend-механики #89. Если #89 ещё не смёржен — реализуем suspend-примитив здесь (как описано в #89: re-bind с enable:false, сохраняя uuid/subId) и согласуем с владельцем во избежание двойной работы (см. открытые вопросы).

Модель срока действия (как у 3x-ui, code-обоснована)

3x-ui кодирует режим «активация при первом подключении» знаком expiryTime: отрицательное значение = «осталось |N| мс с момента первого использования» (панель сама флипает его в абсолютную ms-epoch дату при первом коннекте). Мы храним то же в своей колонке и не перекладываем флип на панель (subgen — источник истины, панель read-only-зеркало): subgen сам флипает отрицательное → положительную дату при первом /sub.

Семантика колонки users.expiry_ms (INTEGER NOT NULL DEFAULT 0):

• 0 — без срока (режим never);
• > 0 — абсолютная дата истечения, ms-epoch (режим fixed_date, или уже активированный first-use);
• < 0 — длительность в мс (режим start_on_first_use, ещё не активирован): -30*86400_000 = «30 дней с первого подключения».

---

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

1. entity (internal/entity)

• panel.go — ClientSpec: добавить поля Enable bool и ExpiryTime int64 (ms-epoch; знак — как выше). Сейчас AddClient хардкодит enable:true/expiryTime:0 — переносим решение в caller (provisioning), чтобы тот же тип обслуживал и обычный provisioning, и suspend, и срок действия.
• user.go:
  • в User добавить ExpiryMS int64 (0 = без срока) и Enabled bool (если Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 не введёт раньше — вводим здесь);
  • в UserCreateParams и UserEditParams добавить ExpiryMS int64;
  • новый типизированный режим не нужен как enum в entity — режим однозначно выводится из знака ExpiryMS (документировать комментарием у поля). Хелпер func (u User) ExpiryDate() (ms int64, activated bool) и func (u User) IsExpired(nowMS int64) bool — чистые методы без I/O (entity это разрешает; «без срока» и неактивированный first-use → не истёк).
• errors.go / validation_errors.go: добавить sentinel ErrValidationExpiry = errors.New("invalid expiry") (в validation_errors.go, рядом с прочими ErrValidation*) — для отрицательного абсолютного срока / даты в прошлом и т.п. Человеко-текст — только в хендлере.

2. clients/xui

• add_client.go: заменить хардкод на поля spec: "enable": cs.Enable, "expiryTime": cs.ExpiryTime. Обновить add_client_test.go — проверить, что тело несёт переданные enable/expiryTime (в т.ч. отрицательный и нулевой кейсы).
• update_client.go (новый, один метод — один файл). Метод UpdateClient(ctx, t entity.PanelTarget, inboundIDs []int, cs entity.ClientSpec) error → POST /panel/api/clients/update/:uuid (на 3.2.x роут update идёт по client uuid, тело идентично add: {"client":{…},"inboundIds":[…]}). Нужен, чтобы менять enable/expiryTime, сохраняя uuid без delete-then-add (атомарнее текущего re-bind и не теряет client при сбое между del и add). DTO/тело — приватная деталь пакета; наружу entity.*.
  • ⚠️ Перед кодом подтвердить на проде точный путь update в сборке 3.2.6 (update/:uuid vs update/:email) — read-only разведка GET-ом по живой панели (см. AGENTS «Dev-гочи»). Если update нестабилен — fallback на существующий del-then-add c AddClient (он уже сохраняет uuid через panelLookup).
• update_client_test.go (новый): TestClient_UpdateClient — table-driven, httptest.Server, кейсы success, error.status, error.envelope_success_false.

3. repository/users

• set_expiry.go (новый, один метод — один файл): SetExpiry(ctx, userID int64, expiryMS int64) error → UPDATE users SET expiry_ms=? WHERE id=?. Понадобится реконсайлеру для флипа first-use (отрицательное → дата) и при необходимости suspend.
• create.go: добавить expiry_ms в INSERT (...,description,expiry_ms,created_at), значение u.ExpiryMS.
• get.go / list_page.go / list.go: добавить expiry_ms (и enabled, если вводим здесь) в SELECT и Scan во все места, где сейчас читается id,name,sub_id,description,created_at. Это 3+ запроса — проверить grep'ом, чтобы ни один не разъехался по числу колонок.
• set_expiry_test.go (новый): TestRepository_SetExpiry — но репозиторные тесты тут идут через реальную SQLite (см. существующие *_test.go в пакете, они используют in-memory/temp db). Покрыть: запись, чтение обратно через Get.
• contract провижининга (userRepo) расширить методом SetExpiry (см. ниже).

4. service/provisioning

• contract.go: в userRepo добавить SetExpiry(ctx, userID, expiryMS int64) error; в panelClient добавить UpdateClient(...) (если используем) — затем go generate ./internal/service/provisioning/ для перегенерации contract_mocks.go.
• service.go:
  • валидация срока в validateExpiry(expiryMS int64) error (value-валидация — в сервисе, не в схеме): запретить положительное значение-дату в прошлом относительно now (опционально — мягко; обычно UI шлёт будущую дату); 0 и любое отрицательное — валидны. → entity.ErrValidationExpiry.
  • CreateUser: прокинуть p.ExpiryMS в entity.User{... ExpiryMS: expiry, Enabled: true} (валидация перед users.Create).
  • EditUser: после ReplaceConnections/SetDescription вызвать users.SetExpiry(ctx, u.ID, expiry); затем syncPanels должен отправить актуальный expiryTime на панели → передавать его в ClientSpec.
  • syncPanels → ClientSpec: сейчас собирает ClientSpec{ID,Email,Flow:"",SubID} — добавить Enable: u.Enabled и ExpiryTime: u.ExpiryMS. Так срок и suspend едут на панель тем же путём, что и привязки.
  • suspend-примитив (для B2 / Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89): метод SetEnabled(ctx, id int64, enabled bool) error — users.SetEnabled + re-bind клиента на всех панелях с Enable=enabled (через UpdateClient, либо del-then-add как сейчас). Если Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 уже смёржен — переиспользуем его метод, новый не плодим.
• service_test.go: расширить существующие table-driven TestService_CreateUser/TestService_EditUser кейсами с ExpiryMS (0 / положительное / отрицательное), проверяя, что ClientSpec в AddClient/UpdateClient-EXPECT несёт ожидаемые Enable/ExpiryTime. Не дробить на *_Success/*_Error. Добавить TestService_SetEnabled если вводим suspend здесь.

5. service/reconciler (новый пакет) — B2

internal/service/reconciler/:

• contract.go: интерфейсы под нужды пакета (interface segregation):
  • fleetReader { Fleet(ctx) (*entity.Fleet, error) } — НЕТ. Источник истины по сроку — наш стор, не панель (issue прямо называет панель read-only-зеркалом). Берём userLister { ListAllForExpiry(ctx) ([]entity.User, error) } (или переиспользуем ListPage с большим лимитом — но честнее лёгкий метод-стрим/итерация).
  • provisioner { SetEnabled(ctx, id int64, enabled bool) error } — суспенд истёкших.
  • clock { Now() time.Time } (по умолчанию time.Now, мокается в тестах).
  • //go:generate go tool mockgen -source=contract.go ....
• reconciler.go: Service с методом RunOnce(ctx) error (чистая логика: загрузить пользователей → для каждого IsExpired(now) и Enabled → SetEnabled(false); лог slog.Info сколько отключено) и Run(ctx, interval) — тикер, вызывающий RunOnce, завершается по ctx.Done(). Один тик = одна транзакция-проход; ошибки отдельного юзера логируются и не валят весь проход.
• first-use флип живёт не в реконсайлере, а в sub-хендлере (см. ниже) — реконсайлер только отключает уже-истёкших.
• reconciler_test.go: TestService_RunOnce — table-driven, мок userLister+provisioner+clock; кейсы: empty, no_expired, one_expired_disabled, already_disabled_skipped, first_use_not_activated_not_expired, error.list, error.set_enabled (один падает — остальные обрабатываются).

6. handlers/sub — активация first-use

• handler.go: после успешного резолва userID по токену, если у пользователя ExpiryMS < 0 (неактивированный first-use), флипнуть в абсолютную дату: newExpiry = now_ms + (-ExpiryMS) и вызвать provisioning.ActivateExpiry(ctx, userID) (или узкий users.SetExpiry + ре-провижининг expiryTime на панель). Это меняет состояние на read-пути — делать идемпотентно и без блокировки рендера: флип только когда ExpiryMS<0, ошибку флипа логировать slog.Warn и не проваливать выдачу подписки (клиент должен получить конфиг даже если панель временно недоступна — догоним следующим тиком/коннектом).
  • contract sub-хендлера (userResolver) расширить нужным методом; перегенерить мок; добавить кейс в handler_test.go (TestHandler_Sub): first-use токен → ожидается вызов активации.
  • Замечание: Subscription-Userinfo уже отдаёт expire из sub.Expiry (зеркало панели). После того как subgen сам задаёт expiryTime, зеркало станет совпадать — отдельной правки userinfo() не нужно, но для неактивированного first-use панель вернёт отрицательное/будущее — отфильтровать в userinfo: отдавать expire только при expiryMs > now (уже есть > 0, дополнить).

7. handlers/users_get — остаток дней / бейджи

• handler.go: в строку добавить поля срока из entity.User (не из флита — срок наш): expiryMS, производные expiresInDays *int (nil для без-срока и неактивированного first-use), expired bool, expiryMode (none/date/first_use). Считать дни от now (хендлер знает время; для тестируемости можно вынести, но допустимо time.Now() локально — read-путь). enabled тоже отдать (для бейджа suspend из Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89).
• contract / openapi: см. ниже.

8. openapi / ogen

• openapi/user_create.yaml и user_edit.yaml: в requestBody-схему добавить одно поле expiryMS (type: integer, format: int64, optional). Кладём в схему только форму (type/format); никаких minimum/maximum — value-валидация в сервисе (ErrValidationExpiry). Не добавляем строковый «mode» — фронт кодирует режим в знак/значение expiryMS (договорённость; см. ниже), бэк остаётся минимальным.
• openapi/users_get.yaml: в usersItem добавить опциональные поля: expiryMS (int64), expiresInDays (int, nullable/omit), expired (bool), enabled (bool). Добавить в properties; в required класть только то, что всегда присутствует (expiryMS, expired, enabled — да; expiresInDays — нет).
• go generate ./internal/oas/ после правок спеки. Хендлеры писать под перегенерённые oas.* типы.
• openapi.yaml менять не нужно (новых путей нет; sub-путь существует).

9. cmd/service/main.go — запуск тикера

• Сконструировать reconciler.New(usersRepo, prov, clock) и запустить go rec.Run(ctx, interval) рядом с go mirror.Run(ctx) (строка ~113), завязав на тот же ctx (graceful shutdown по SIGINT/SIGTERM уже есть).
• Интервал — новый конфиг ReconcileInterval time.Duration в config.Config с env:"SUBGEN_RECONCILE_INTERVAL" envDefault:"5m"; пробросить конкретное поле (не Config) в reconciler.New/Run (AGENTS: Config не течёт по слоям). Добавить запись в .env.example.

10. frontend (internal/handlers/web/static/)

• Форма пользователя (app.js): блок «Срок действия» с тремя радио-режимами: «Без срока» / «До даты» (<input type=date>) / «N дней от первого подключения» (число + неявный чекбокс first-use задаётся самим режимом). Кодирование в expiryMS на стороне фронта:
  • none → 0;
  • date → Date.parse(value) (ms, положительное);
  • first_use N дней → -(N*86400000) (отрицательное).
• Строка пользователя: бейдж «истекает через N дней» (нейтральный → жёлтый у порога, напр. ≤7 дней → красный ≤3), бейдж «истёк» (красный) при expired, бейдж «отключён» при !enabled. Декод expiryMS<0 показывать как «N дней от первого подключения (не активирован)».
• Токены темы — существующие (3x-ui dark skin); никаких новых webfont'ов. Правки видны через SUBGEN_STATIC_DIR без пересборки Go.

---

Миграции БД

Новый файл migrations/0004-user-expiry.sql (forward-only, чистый DDL, в транзакции — это простой ALTER, не rebuild, legacy_alter_table не нужен):

ALTER TABLE users ADD COLUMN expiry_ms INTEGER NOT NULL DEFAULT 0;
-- enabled: добавить здесь ТОЛЬКО если #89 не вводит её раньше (иначе конфликт миграций).
-- ALTER TABLE users ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1;

expiry_ms: 0 без срока, >0 дата ms-epoch, <0 длительность first-use. Семантику задокументировать комментарием в SQL. Базлайн 0001-init.sql не править.

Порядок-коллизия с #89: если оба issue добавляют колонку в users, второй мёрджащийся PR должен взять следующий свободный NNNN и не дублировать enabled. Координируется через номер миграции (см. зависимости).

---

OpenAPI / ogen

• Править: user_create.yaml, user_edit.yaml (поле expiryMS), users_get.yaml (поля строки). Только форма контракта; value-constraints — в сервис.
• go generate ./internal/oas/ → писать хендлеры под новые oas.*.

---

Тесты

• xui: TestClient_AddClient (расширить — enable/expiryTime в теле), TestClient_UpdateClient (новый файл/тест).
• repository/users: TestRepository_SetExpiry (новый), правки сканов проверяются существующими TestRepository_Get/ListPage/Create (расширить ожидания на expiry_ms).
• provisioning: расширить TestService_CreateUser/TestService_EditUser (ExpiryMS → ClientSpec); TestService_SetEnabled если suspend вводим здесь. Моки — из своего contract.go (go generate).
• reconciler: TestService_RunOnce (новый пакет, мок userLister+provisioner+clock).
• sub: расширить TestHandler_Sub — активация first-use (вызов активации при ExpiryMS<0, не-провал при ошибке флипа).
• users_get: расширить TestHandler_UsersGet — поля expiresInDays/expired/enabled в строке.
• Все — строго table-driven, один Test{Type}_{Method} на метод, t.Parallel(), sentinel-проверки require.ErrorIs.
• apitest (apitest/): добавить сценарий в UserSuite (или новый файл) — создать юзера с expiryMS (положительное), убедиться, что 3x-ui отдаёт ненулевой expiryTime у клиента (чёрный ящик: тело — map[string]any, не oas.*). Required-массивы (inboundIDs) слать [], не null.

---

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

• CHANGELOG.md — новая запись сверху: ## YYYY-MM-DD — Срок действия подписки + фоновый реконсайлер автоотключения (#104) + 1–2 строки сути + ссылка на ADR.
• ADR (нетривиально — есть развилки: модель срока знаком expiry_ms, флип first-use на read-пути, отдельный сервис-тикер vs cron, зависимость suspend от Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89). Новый docs/decisions/0006-subscription-expiry-and-reconciler.md по шаблону 0000-template.md (Context / Considered Options / Decision / Consequences). Зафиксировать: (a) почему знак-кодирование expiry_ms (паритет с 3x-ui, одна колонка, без enum-таблицы); (b) почему subgen сам флипает first-use, а не доверяет панели (источник истины снизу вверх); (c) почему реконсайлер — горутина-тикер в cmd/service, а не внешний cron (нет cron-инфры, AGENTS: «планировщика/cron в кодовой базе нет»); (d) отключение, а не удаление истёкших (сохранение ссылки/uuid/subId).

---

Риски и edge-cases

• Зависимость от Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (suspend). Реконсайлер бессмыслен без обратимого disable. Если Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 не готов — реализуем suspend здесь, но рискуем разойтись с его дизайном миграции/метода. Координировать (см. вопросы).
• Флип first-use на read-пути /sub. Не блокировать рендер при ошибке панели; идемпотентность (флипать только при ExpiryMS<0); гонка параллельных /sub одного токена — флип через UPDATE ... WHERE expiry_ms < 0 (condition в WHERE) делает его «первый выигрывает», повторный no-op.
• Часы/таймзоны. Везде ms-epoch UTC; «дата» из UI — конец дня по таймзоне оператора? По умолчанию трактуем дату как полночь UTC выбранного дня (задокументировать; уточнить у владельца, если важна локальная TZ).
• Зеркало Subscription-Userinfo. До того как панель примет expiryTime, заголовок может отдавать старый/отрицательный expire — фильтровать expire по > now.
• Истёкший, но enabled на панели после ручной правки оператором. Реконсайлер сверяет наш стор, не панель — повторно отключит на следующем тике (идемпотентно).
• Граничный порог бейджа (жёлтый/красный) — захардкоженные дефолты (≤7 жёлтый, ≤3 красный) на фронте; не конфиг.
• Большой users-список в реконсайлере — итерация страницами, чтобы не материализовать всех (переиспользовать пагинацию репозитория).

---

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

• Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (per-user enable/disable, suspend с сохранением subId/uuid) — жёсткая зависимость для B2 (автоотключение). B1 (поле срока + провижининг expiryTime + UI-бейджи + first-use флип) самодостаточна и поставляется независимо.
• Коллизия миграций с Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89: оба трогают таблицу users. Тот, кто мёржится вторым, берёт следующий NNNN и не дублирует колонку enabled.

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

1. Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 (suspend) — порядок поставки. Реализуем suspend-примитив (enabled + re-bind enable:false) прямо в этом PR, или ждём мёрджа Per-user enable/disable (suspend) с сохранением subId/uuid и ссылки подписки #89 и переиспользуем его метод/миграцию? От этого зависит, чья миграция добавляет enabled и чтобы не было двойной работы/конфликта NNNN-файлов.
2. Трактовка «До даты». Дату из date-picker считать полночью UTC выбранного дня, или концом дня в таймзоне оператора? (Влияет на то, истечёт ли подписка «в этот день» по локальному времени пользователя.)
3. 3x-ui update-роут. Использовать POST /panel/api/clients/update/:uuid (атомарный апдейт enable/expiry без потери клиента) — подтвердить точный путь/тело на проде 3.2.6; либо остаёмся на текущем del-then-add через AddClient (он уже сохраняет uuid)? Предпочтительно update, но требует read-only проверки на живой панели.

[Postlog]

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

Проверено по исходникам 3x-ui v3.2.6 + подтверждено upstream-issues:

• Энфорсмент срока делегируем панели: subgen пушит expiryTime (мс epoch), фоновая джоба 3x-ui (XrayTrafficJob @every 5s) сама ставит enable=false и выселяет креды из живого Xray (RemoveUser). Свой планировщик/воркер в subgen не нужен — убираем из плана.
• 3x-ui принимает любой expiryTime, включая now+пара мс и прошлое, без минимума («1 час» и т.п. нет); многократная установка/снятие на одном клиенте поддерживается; expiryTime=0 = бессрочный.
• ⚠️ Resume = enable:true + expiryTime:0 одним апдейтом. Обнуление срока само по себе НЕ включает уже отключённого джобой клиента (enable — отдельное поле; force-enable живёт только в add-пути, не в update/:email).
• Лаг отключения ~5с (тик джобы); активная сессия может дожить до естественного обрыва — «мгновенный кат» не обещаем.
• Отрицательный expiryTime = «активация при первом подключении» доступен нативно (ваучерная модель), если понадобится.
• Первый шаг реализации — apitest против реальной панели (expiry = now+Nс → disable на следующем тике; suspend через update → enable:false держится): прибиваем края «нет минимума» / «force-enable» для нашей сборки.