Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения

[Postlog]

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

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

Публичный HTML-лендинг по тому же токену (content-negotiation: браузер → страница, клиент-приложение → конфиг). На странице: прогресс-бар трафика, дата истечения, копируемая ссылка подписки, QR-код ссылки, и сетка кнопок «Добавить в » (Clash/Mihomo, sing-box, Hiddify, v2rayNG, Streisand, Happ) через их URL-схемы (clash://install-config?url=, sing-box://import-remote-profile?url=, hiddify://import/, streisand://import/, happ://add/), фильтруемых по ОС из User-Agent.

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

Marzban (marz-sub-page), Marzneshin/Remnawave (subscription page + deep-links), 3x-ui (встроенный sub-сервер со страницей), Hiddify (new.html self-service portal). Лендинг подписки есть у всех.

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

Браузер, открывший /sub/mihomo/{token}, получает голый YAML (sub/handler.go отдаёт raw config без UA-разбора). Subgen уже считает Up/Down/Total/Expiry в entity.Subscriber, но визуально их конечному пользователю нигде не показывает. Нет HTML-страницы, нет QR, нет deep-link кнопок.

Зачем

Сегодня конечный пользователь получает лишь YAML и не видит ни остатка квоты, ни срока без приложения, парсящего заголовок. Лендинг даёт нетехническому пользователю самостоятельную проверку статуса, копирование ссылки, скан QR и установку в один тап — самая запрашиваемая user-facing поверхность во всех конкурентах.

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

Новая ogen-операция, отдающая сырой HTML (как admin_shell), вне /admin/api/* (токен = секрет, без auth). В sub-хендлере — UA-гейт: известные клиентские UA (clash, sing-box, v2rayN, hiddify, streisand, happ) получают конфиг как сейчас, браузер — страницу. Каталог приложений (id, имя, иконка, платформы, шаблон URL-схемы, store-ссылки) — типизированный Go-источник с read-эндпоинтом (по образцу config_schema), фронт ничего не хардкодит. QR — вендорной JS-либой (как vue/Sortable/js-yaml, без сборки). Переиспользует QR из #100.

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

• openapi/sub.yaml (UA-ветвление / новая sub_page операция), openapi/clients_catalog.yaml (новый)
• internal/handlers/sub/handler.go (UA-гейт), internal/handlers/sub_page/ (новый, HTML), internal/handlers/clients_catalog/ (новый)
• internal/entity/ (каталог клиентских приложений)
• internal/handlers/web/static/ (sub-page.html, qr.min.js вендорный), internal/handlers/web/render.go

---

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

[Postlog]

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

Issue #106 — Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения

Резюме

Браузер, открывший /sub/{kind}/{token}, сейчас получает голый YAML (sub/handler.go не смотрит на User-Agent). Добавляем content-negotiation по UA: клиентское приложение — конфиг как сейчас, браузер — самодостаточный HTML-лендинг (прогресс трафика, дата истечения, копируемая ссылка, QR, кнопки deep-link импорта в приложения). Каталог приложений — типизированный Go-источник с read-эндпоинтом (по образцу config_schema), фронт ничего не хардкодит.

---

Контекст из кода (что реально есть)

• internal/handlers/sub/handler.go (func (h *Handler) Sub) — резолвит токен → subID → userID → configID, берёт sub := fleet.Sub(subID) (это *entity.Subscriber с уже посчитанными Up/Down/Total/Expiry), рендерит YAML через EngineRenderer.Render. UA нигде не читается (grep -rn "User-Agent" --include=*.go пусто). Хедер Subscription-Userinfo уже формируется (userinfo(...)).
• entity.Subscriber{Up, Down, Total, Expiry} (internal/entity/fleet.go) — всё для прогресс-бара/срока уже есть; Total==0 = безлимит, Expiry==0 = без срока (ms epoch).
• ogen пинит одну медиа-тайп на статус-код операции; у sub 200 = text/yaml (SubOK{Data} — opaque stream, хедеры Content-Disposition/Profile-Title/Subscription-Userinfo хендлер ставит руками как oas.OptString). Это ключевой факт для дизайна (см. ниже).
• Прецедент «ogen-операция отдаёт сырой HTML»: admin_shell (oas.AdminShellOK{Data: *bytes.Reader}, тело из web.ReadPage(staticDir, "index.html")).
• Прецедент «типизированный Go-каталог + read-эндпоинт, фронт не хардкодит»: config_schema (internal/handlers/config_schema/handler.go, GET /admin/api/config/mihomo/schema, схема собирается в build() из mihomo-каталогов).
• Статика: web.assetFS() (embed по умолчанию, диск при SUBGEN_STATIC_DIR), web.ReadPage(), web.StaticHandler() (/admin/static/*). Вшитые либы: vue.global.prod.js, sortable.min.js, js-yaml.min.js — QR-либы пока нет (issue Показывать backend errMessage на read-ошибках + QR-код подписки в админке #100 её только планирует, но не реализована: gh issue view 100 — статус «предлагаемое решение», в static/ файла нет). Значит QR-либу вносим в этом PR.
• Композиция: cmd/service/main.go → buildRouter → api.New(sess, api.Handlers{...}) → oas.NewServer. cfg.PublicBase уже прокидывается (в sub.NewMihomoRenderer и usersGetHandler.New); URL подписки строится как base + "/sub/mihomo/" + token.Make(secret, subID) (см. users_get/handler.go:77).
• Каталог internal/handlers/clients_catalog/ и sub_page/ пока не существуют (в internal/handlers/ их нет).

---

Ключевое дизайн-решение (ogen + UA)

Issue предлагает одновременно «новую операцию sub_page» и «UA-гейт в sub-хендлере». На одном path+method ogen-роутер держит ровно одну операцию, поэтому «отдельная операция на тот же путь» невозможна. А две медиа-тайпы под одним 200 (text/yaml + text/html) ogen разруливает плохо и не идиоматично.

Рекомендуемый подход (один путь, content-negotiation внутри sub):

1. Добавить в операцию sub header-параметр User-Agent (in: header, required: false) — ogen сгенерит params.UserAgent oas.OptString.
2. Тело 200 оставить opaque-стримом (как сейчас), но добавить в 200 response-header Content-Type в спеке, который хендлер ставит руками (oas.NewOptString(...)) — text/yaml; charset=utf-8 для клиента, text/html; charset=utf-8 для браузера. Это ровно тот же приём, которым уже ставятся Content-Disposition/Profile-Title. Так ogen не навязывает медиа-тайп, а реальный тип выбирает хендлер по UA. (ogen фиксит媒a-тайп тела в спеке как text/yaml, но фактический Content-Type в ответе — это хедер, который мы переопределяем; проверить на go generate, что хедер реально пробрасывается. Если ogen жёстко перетирает Content-Type из спецификации — fallback: тело 200 объявить text/html и для клиента всё равно слать YAML-байты с руч-хедером, поскольку клиентам важен сам YAML, а не заявленный в схеме тип. Эту деталь зафиксировать после первого go generate.)
3. UA-детект — в сервисном слое (типизированно, без strings.Contains в хендлере; см. правило «сравнение содержимого строк запрещено»): новый internal/service/useragent (или функция в новом каталоге клиентских приложений entity) с типизированной классификацией Browser | Client. Известные клиентские UA-маркеры (clash, mihomo, meta, sing-box, v2rayng, hiddify, streisand, happ, stash, nekobox) и эвристика «есть Mozilla/AppleWebKit и нет клиентских маркеров → браузер». Маркеры — типизированные константы, не магия по месту.

Альтернатива (если владелец предпочтёт явный путь вместо UA-магии): отдельный роут GET /sub/{kind}/{token}/page (новая операция subPage, чистый HTML, без UA-эвристики) + кнопка/редирект. Это проще и детерминированнее, но не «один токен, авто-negotiation», как просит issue. См. открытый вопрос.

---

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

1. entity — каталог клиентских приложений (типизированный источник)

Новый файл internal/entity/client_app.go:

• Тип ClientApp struct { ID string; Name string; Icon string; Platforms []ClientPlatform; ImportScheme string; StoreURLs map[ClientPlatform]string }.
  • ImportScheme — шаблон URL-схемы с плейсхолдером под {url}, напр. clash://install-config?url=%s, sing-box://import-remote-profile?url=%s, hiddify://import/%s, streisand://import/%s, happ://add/%s, v2rayng (Android-only, через ?url=).
• Тип ClientPlatform string + константы PlatformWindows/MacOS/Linux/Android/iOS (типизировано, не строки).
• Функция-каталог ClientApps() []ClientApp — единый источник (по образцу mihomo.RuleTypeCatalog()); никакого seed в БД, это статический каталог в коде (как mihomo-каталоги). Включить из issue: Clash/Mihomo, sing-box, Hiddify, v2rayNG, Streisand, Happ.
• Тип UA-классификации ClientKind (KindBrowser/KindClientApp) + список клиентских UA-маркеров константами — здесь же или в service/useragent (см. шаг 3). Держать маркеры типизированно.

Sentinel-ошибок здесь не нужно (read-only каталог).

2. service/useragent — классификатор UA (бизнес-логика, не хендлер)

Новый пакет internal/service/useragent/useragent.go:

• func Classify(ua string) entity.ClientKind — по списку клиентских маркеров (lowercase-substr — это разбор внешнего формата UA, допустимое исключение из «сравнение строк запрещено»; обосновать комментарием, как Node.PanelBaseURL). Пустой UA → KindClientApp (консервативно: не-браузер получает конфиг — безопаснее, чем сломать клиент HTML-страницей).
• contract.go не нужен (нет зависимостей). Чистая функция → unit-тест TestClassify table-driven.

Альтернатива: положить Classify прямо в entity рядом с каталогом (нет I/O, нет зависимостей). Тогда отдельный сервис-пакет не нужен. Разумный дефолт — функция в entity (минимум слоёв, нет зависимостей), сервис заводить только если появится состояние/конфиг. Беру этот дефолт.

3. Хендлер sub — UA-гейт

Править internal/handlers/sub/handler.go:

• В Sub(...) после резолва sub/configID, перед renderer.Render, ветвление по entity.Classify(params.UserAgent.Or("")):
  • KindClientApp → текущее поведение (YAML + хедеры) без изменений.
  • KindBrowser → отдать HTML-лендинг: тело web.ReadPage(staticDir, "sub-page.html"), Content-Type: text/html. Страница — статический SPA-shell; данные (трафик/срок/url/каталог приложений) тянет фетчем (см. шаг 6 — read-эндпоинты), либо инлайнятся в HTML минимально. Дефолт: страница тянет данные фетчем — без серверного шаблонизатора (правило «серверных шаблонов нет»).
• Хендлеру добавить зависимость staticDir string в New(...) (как у admin_shell). Обновить вызов в cmd/service/main.go: sub.New(usersRepo, fleetSvc, configsRepo, renderers, cfg.Secret, cfg.StaticDir).
• Контракт sub/contract.go не расширяется (UA — параметр запроса, не зависимость).

4. Read-эндпоинт «данные лендинга» — sub_meta (трафик/срок/ссылка) — публичный, по токену

Лендинг нетехнический, поэтому JS на странице должен получить только свои данные по тому же токену (без admin-auth). Варианты:

• (a) Новая публичная ogen-операция GET /sub/{kind}/{token}/meta → JSON {up, down, total, expiry, subUrl} (резолв токена так же, как в sub). Чистый read, типизированный JSON.
• (b) Инлайнить значения в HTML при отдаче (но это «серверный шаблон» — против правил).

Дефолт: (a) — отдельная публичная read-операция sub_meta, новый хендлер internal/handlers/sub_meta/. Резолв токена выносится в общий приватный хелпер, чтобы sub и sub_meta не дублировали логику (хелпер в пакете token/sub или общий маленький resolver-сервис). Поскольку оба хендлера живут в разных пакетах, аккуратнее — общий мини-resolver internal/service/subresolve с методом Resolve(ctx, kind, token) (subID string, sub *entity.Subscriber, configID int64, ok bool, err error), который зовут оба хендлера (устраняет копипаст резолва). Этот рефактор — часть PR.

5. Read-эндпоинт «каталог приложений» — clients_catalog (по образцу config_schema)

Новый хендлер internal/handlers/clients_catalog/handler.go:

• GET /sub/clients (публичный — лендинг без auth) → JSON-каталог из entity.ClientApps() (id, name, icon, platforms, importScheme, storeUrls). Сборка один раз в New() (как config_schema.build()). Фронт фильтрует по ОС из UA на клиенте.
• Контракт ответов — типизированный JSON (read-ручка).

6. Фронт — internal/handlers/web/static/

• sub-page.html — самостоятельный лендинг (НЕ admin SPA-shell): прогресс-бар трафика (up+down vs total, безлимит при total==0), дата истечения (из expiry, скрыта при 0), копируемая ссылка подписки, QR-код ссылки, сетка кнопок «Добавить в ». Тема — токены 3x-ui (как admin: bg #1a1b1f, primary #1668dc, системные шрифты). Данные тянет фетчем с /sub/{kind}/{token}/meta и /sub/clients; ОС берёт из navigator.userAgent и фильтрует кнопки. Минимальный Vue (global build) или ванильный JS — дефолт: ванильный JS, страница простая, тащить Vue ради одного экрана избыточно (но если хочется единообразия — Vue допустим; решение по месту).
• qr.min.js — вендорная QR-либа (как vue/sortable/js-yaml, без сборки). Рендер QR из URL подписки. (Issue Показывать backend errMessage на read-ошибках + QR-код подписки в админке #100 эту же либу только планирует — здесь она появляется первой; Показывать backend errMessage на read-ошибках + QR-код подписки в админке #100 переиспользует.)
• render.go — менять не нужно (web.ReadPage уже умеет читать произвольный файл из assetFS); sub-page.html отдаётся через ReadPage. Иконки приложений — инлайн-SVG в каталоге или маленькие файлы в static/icons/ (отдаются StaticHandler). Дефолт: инлайн-SVG строкой в entity.ClientApp.Icon (нет новых файловых путей, каталог самодостаточен).

7. OpenAPI + ogen

Править/добавить:

• openapi/sub.yaml — добавить header-параметр User-Agent (in: header, required: false) и response-header Content-Type в 200.
• openapi/sub_meta.yaml (новый) — GET /sub/{kind}/{token}/meta, публичный, типизированный JSON {up, down, total, expiry, subUrl} + 404.
• openapi/clients_catalog.yaml (новый) — GET /sub/clients, публичный, JSON-массив приложений (id/name/icon/platforms/importScheme/storeUrls).
• openapi/openapi.yaml — добавить $ref на новые пути (/sub/{kind}/{token}/meta, /sub/clients).
• Затем go generate ./internal/oas/.
• Value-валидации в схему НЕ кладём (только required/type/format).

8. Композиция

• internal/handlers/api/server.go — добавить поля SubMeta/ClientsCatalog в Handlers, форвард-методы SubMeta/ClientsCatalog; Sub форвард не меняется (сигнатура oas.SubParams обновится автоматически после go generate — UA там новое поле).
• cmd/service/main.go (buildRouter) — сконструировать sub_meta/clients_catalog хендлеры и subresolve-сервис, прокинуть cfg.StaticDir в sub.New. Новые ручки публичные → без adminSession в их спеках.

---

Миграции БД

Не требуются. Каталог приложений — статический Go-источник (как mihomo-каталоги), трафик/срок уже в entity.Subscriber (из флита). БД не трогаем.

---

OpenAPI / ogen

• Править: openapi/sub.yaml (UA header-param + Content-Type response-header в 200).
• Новые: openapi/sub_meta.yaml, openapi/clients_catalog.yaml; $ref в openapi/openapi.yaml.
• go generate ./internal/oas/ после правок.
• Все новые ручки публичные (токен = секрет; каталог — не секрет) — без security: adminSession.

---

Тесты

• entity (если Classify в entity): TestClassify (table-driven, один на метод) — кейсы empty (→ ClientApp), browser.chrome, browser.safari_ios, client.clash, client.singbox, client.hiddify, client.happ. ClientApps() — лёгкий тест на непустоту/уникальность id (или проверить через хендлер-каталог).
• internal/handlers/sub — расширить TestHandler_Sub: добавить кейсы browser.serves_html (UA браузера → Content-Type: text/html, тело непустое) и client.serves_yaml (UA клиента → YAML как сейчас). Моки уже есть (contract_mocks.go); staticDir в тесте указывает на реальный static/ или временный с sub-page.html.
• internal/handlers/sub_meta — TestHandler_SubMeta: not_found.unknown_token, success.maps_traffic_expiry. contract.go + mockgen на резолвере (subresolve/users+fleet).
• internal/handlers/clients_catalog — TestHandler_ClientsCatalog: success.serves_catalog (по образцу config_schema/handler_test.go).
• internal/service/subresolve (если заведён) — TestService_Resolve table-driven, моки на userResolver/fleetReader/configResolver через contract.go.
• apitest: добавить apitest/sub_page_test.go (новый SubPageSuite либо в существующий): чёрный ящик через сырой HTTP с разными User-Agent — браузерный UA → Content-Type: text/html + 200; клиентский UA → YAML; GET /sub/clients → JSON-массив; GET /sub/{kind}/{token}/meta → JSON с трафиком. Тела/проверки — map[string]any/сырой текст, не из internal/oas.

---

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

• CHANGELOG.md — одна запись: ## 2026-06-12 — Лендинг подписки: HTML-страница по UA, QR, deep-link импорт (#106) + 1–2 строки сути + ссылка на ADR.
• ADR-0006 (docs/decisions/0006-subscription-landing-page.md, следующий свободный номер — текущий максимум 0005) — нетривиальное решение: content-negotiation по User-Agent на одном /sub/{kind}/{token} против отдельного /page-роута; почему UA-детект и куда его положить (entity vs service); как обойти ogen-пиннинг медиа-тайпа (ручной Content-Type-хедер); каталог приложений как типизированный Go-источник без БД. Секции Context / Considered Options / Decision / Consequences.

---

Риски и edge-cases

• ogen и Content-Type: главный технический риск — пробросит ли ogen руч-выставленный Content-Type поверх媒a-тайпа из спеки. Проверить сразу после первого go generate на минимальном прототипе; от результата зависит, оставляем ли opaque-stream-подход или уходим на отдельный /page-роут (план описывает fallback).
• UA-эвристика хрупка: новые клиенты/браузеры. Митигировать консервативным дефолтом (пустой/неизвестный UA → отдаём конфиг, не HTML — лучше «лишний YAML в браузере», чем «сломанный импорт в клиенте»). Список маркеров — типизированными константами, легко дополнять.
• Сравнение строк: разбор UA — это парсинг внешнего формата (как 3x-ui inbound-tag); допустимое исключение из правила «strings.Contains запрещён», но обязательно с обоснованием в комментарии.
• Публичность read-ручек: /sub/.../meta отдаёт трафик/срок без auth — но токен и так = секрет (как сам конфиг), так что паритетно. /sub/clients — несекретный каталог, ок.
• Дублирование резолва токена между sub и sub_meta — устранить общим resolver (часть PR), иначе разъедется логика «custom vs base config / fleet.Sub».
• QR-либа: выбрать маленькую (напр. qrcodejs/qrcode-generator), вшить в static/ подSUBGEN_STATIC_DIR/embed; без CDN (RU1 DNS).
• Иконки/StoreURLs: держать в каталоге, не хардкодить во фронте (правило «фронт ничего не хардкодит»).

---

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

• Показывать backend errMessage на read-ошибках + QR-код подписки в админке #100 планирует ту же QR-либу для admin — здесь она вносится первой; Показывать backend errMessage на read-ошибках + QR-код подписки в админке #100 её переиспользует. Жёсткой блокировки нет, но координировать имя файла либы (qr.min.js).
• Заголовки подписки support-url / profile-web-page-url + сортировка таблицы юзеров #112 (заголовки support-url/profile-web-page-url + сортировка таблицы) — смежная по sub-хендлеру; profile-web-page-url может указывать на этот лендинг. Если Заголовки подписки support-url / profile-web-page-url + сортировка таблицы юзеров #112 идёт раньше — переиспользовать его URL-сборку; если позже — Заголовки подписки support-url / profile-web-page-url + сортировка таблицы юзеров #112 сошлётся на страницу отсюда. Не блокирует, но синхронизировать URL лендинга.

---

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

1. Content-negotiation vs явный путь. Дефолт плана — UA-гейт на одном /sub/{kind}/{token} (как просит issue). Но если ogen не даст чисто переопределить Content-Type поверх спеки, упадём на отдельный GET /sub/{kind}/{token}/page (детерминированно, без UA-эвристики). Какой из вариантов предпочтителен как целевой — авто-negotiation (риск ogen-трения) или явный /page-роут?
2. Данные лендинга: тянуть фетчем с публичного /sub/.../meta (дефолт плана, без серверных шаблонов) — ок, или предпочитаешь иной способ доставки трафика/срока на страницу?