Заголовки подписки support-url / profile-web-page-url + сортировка таблицы юзеров

[Postlog]

Категория: ux · Приоритет: low · Размер: S · Ранг: 10/10

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

1. Несколько операторских полей во вкладке Конфиг (support URL, текст анонса) → новые заголовки ответа /sub; profile-web-page-url выводится автоматически из host+token (ведёт на лендинг из Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106). 2) Кликабельные заголовки столбцов таблицы пользователей (имя, трафик, истечение) для сортировки.

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

Заголовки: Hiddify/Marzban/Remnawave/v2RayTun (profile-web-page-url, support-url, announce). Сортировка таблицы: Remnawave/Marzneshin/Hiddify. Обе мелочи есть у всех.

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

sub/handler.go отдаёт только 4 заголовка (Subscription-Userinfo, Profile-Title, Profile-Update-Interval, Content-Disposition) — нет support-url/profile-web-page-url/announce, поэтому клиенты не рисуют кнопки «Дом»/«Поддержка». mihomo.Profile несёт только Title/Filename/UpdateInterval. В SPA таблица юзеров не сортируется по столбцам (только серверная пагинация/фильтр).

Зачем

Заголовки дают in-app кнопки «Дом»/«Поддержка»/анонсы без выхода из прокси-приложения — паритет с Marzban/Remnawave/v2RayTun почти бесплатно. Сортировка таблицы — базовое удобство для поиска тяжёлых/истекающих юзеров, которого в subgen нет.

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

Заголовки: расширить mihomo.Profile полями SupportURL/Announce; добавить optional response-headers в openapi /sub-операцию (ogen-параметры), хендлер их выставляет; web-page-url derive из request host + token. Поля редактируются в config_save/config_get (Профиль уже сохраняется). Сортировка: users_get уже серверно-пагинируется — добавить параметры sort/order (openapi), ORDER BY в users-репозитории; во Vue — кликабельные th с индикатором направления.

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

• internal/mihomo/profile.go (SupportURL/Announce), internal/handlers/sub/handler.go
• openapi/{sub,config_save,config_get,users_get}.yaml, internal/repository/users/list.go (ORDER BY)
• internal/handlers/{users_get,config_save,config_get}/, internal/handlers/web/static/{app.js,index.html}

---

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

[Postlog]

Issue #112 — Заголовки подписки support-url / profile-web-page-url + сортировка таблицы юзеров

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

Резюме

Две независимые мелочи: (1) расширить профиль mihomo операторскими полями supportURL/announce, отдать их (+ выведенный profile-web-page-url) как ответные заголовки /sub; (2) добавить серверную сортировку таблицы пользователей по кликабельным заголовкам столбцов. Ниже — важная поправка к issue по сортировке: трафик и истечение живут в кеше флита, а не в БД, поэтому сортировать по ним при серверной пагинации нельзя без смены модели — по умолчанию сортируем только по имени/дате.

---

Сверка issue с кодом (что подтвердилось, что нет)

• mihomo.Profile (internal/mihomo/profile.go) реально несёт только Title/Filename/UpdateInterval — как в issue. Хранится в таблице mihomo_profile (migrations/0001-init.sql:158), пишется атомарно в SaveMihomoConfig (internal/repository/routing/save_mihomo_config.go:140), читается routing.Profile (internal/repository/routing/profile.go).
• sub/handler.go действительно ставит только 4 заголовка (Subscription-Userinfo, Profile-Title, Profile-Update-Interval, Content-Disposition) через oas.SubOKHeaders. Меты собираются в RenderMeta (internal/handlers/sub/handler.go:21) и заполняются MihomoRenderer.Render (internal/handlers/sub/mihomo_renderer.go:47).
• Поправка №1 (файл): issue в «Затронутые файлы» называет internal/repository/users/list.go для ORDER BY. Это неверно — хендлер users_get ходит в ListPage (internal/repository/users/list_page.go), а list.go (List) — легаси-метод, хендлером не используется. Правим list_page.go.
• Поправка №2 (модель сортировки — развилка): issue говорит «users_get уже серверно-пагинируется — добавить ORDER BY». Пагинация подтверждается (ListPage + entity.UserListParams{Limit,Offset}). НО трафик (stats.up/down) и истечение в таблицу приходят не из БД, а из кеша флита (entity.Subscriber.Up/Down/Expiry, fleet.Sub(subID) в internal/handlers/users_get/handler.go:84). В БД (users) есть только name, sub_id, description, created_at. Поэтому ORDER BY в SQL умеет сортировать только по name (и created_at), но не по трафику/истечению. Сортировка по трафику/истечению при серверной пагинации потребовала бы материализации всего флита и сортировки до пагинации (сейчас страница тянется из БД, а флит-данные джойнятся уже к странице) — это другой data-flow. Дефолт плана: серверная сортировка по name (asc/desc), плюс по created_at если нужно. Сортировку по трафику/истечению — см. «Открытые вопросы».

---

Часть A. Заголовки подписки (support-url / profile-web-page-url / announce)

Снизу вверх.

1. internal/mihomo/profile.go — расширить Profile

• Добавить поля SupportURL string и Announce string (оба операторские, опциональные; по аналогии с существующими — trimmed, без code-defaults).
• profile-web-page-url в Profile не хранится — он выводится из base+token на лету (см. шаг 6).

2. internal/mihomo/decode.go — декод новых полей

• В configDTO добавить SupportURL string \json:"supportURL"`иAnnounce string `json:"announce"``.
• В DecodeConfig (блок Profile: Profile{…} около decode.go:113) проставить SupportURL: strings.TrimSpace(dto.SupportURL), Announce: strings.TrimSpace(dto.Announce) (announce можно не тримить целиком, но trim краёв безопасен).

3. internal/mihomo/validate.go — валидация (минимальная)

• SupportURL/Announce опциональны → пустые допустимы, валидации присутствия нет.
• Если непусто — SupportURL стоит проверить на отсутствие управляющих символов/переводов строк (заголовок HTTP), как уже делается для Filename через isControl. Завести sentinel ErrProfileSupportURLInvalid (в internal/mihomo/errors.go) и проверку в ValidateProfile. Announce тоже уходит в заголовок — отрезать CR/LF (header injection). Дефолт: при наличии CR/LF/control в SupportURL/Announce → sentinel-ошибка. (Без интерполяции — чистый sentinel.)
• Если решим не валидировать вовсе — тогда обязателен sanitize при выставлении заголовка (вырезать \r\n) в хендлере. Дефолт — валидируем sentinel'ом (консистентно с filename).

4. internal/repository/routing — персист новых колонок

• Миграция (см. раздел «Миграции БД»): добавить support_url, announce в mihomo_profile.
• internal/repository/routing/profile.go — расширить SELECT title,filename,update_interval,support_url,announce и Scan в новые поля.
• internal/repository/routing/save_mihomo_config.go:140 — расширить INSERT … ON CONFLICT … DO UPDATE колонками support_url, announce (+ соответствующие excluded.*), передать draft.Profile.SupportURL, draft.Profile.Announce.

5. internal/handlers/sub — RenderMeta + выставление заголовков

• RenderMeta (handler.go:21) — добавить SupportURL string, Announce string, WebPageURL string.
• MihomoRenderer.Render (mihomo_renderer.go:47) — пробросить profile.SupportURL, profile.Announce в RenderMeta. WebPageURL рендерер не знает (нет токена) — оставить пустым здесь.
• Handler.Sub (handler.go:106) — на 200 выставить новые заголовки через oas.SubOKHeaders:
  • support-url ← meta.SupportURL (если непустой).
  • announce ← meta.Announce (если непустой).
  • profile-web-page-url ← вывести из base + token. Источник base: в sub.Handler сейчас base нет (есть только secret). Дефолт: добавить в sub.Handler поле base string (конструктор New(... , secret, base string)), и в cmd/service/main.go:200 прокинуть cfg.PublicBase (он уже используется рядом, см. main.go:185,208). URL: strings.TrimRight(base,"/") + "<путь лендинга из #106>/" + params.Token. Путь лендинга зависит от Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 — см. «Зависимости».
  • Имена заголовков клиентских стандартов — profile-web-page-url, support-url, announce (как в issue; их читают Hiddify/Marzban/Remnawave/v2RayTun).
• Эти заголовки опциональны → ставить только когда значение непустое (через if + oas.NewOptString), чтобы не слать пустые хедеры.

6. OpenAPI — openapi/sub.yaml + openapi/config_save.yaml + openapi/config_get.yaml + openapi/common.yaml (см. раздел OpenAPI).

7. Фронт — internal/handlers/web/static/{index.html,app.js}

• В карточку «Параметры подписки» (index.html:248–266) добавить два поля: Support URL (v-model="cfg.supportURL") и Announce (textarea, v-model="cfg.announce"). profile-web-page-url редактировать не нужно — он выводится автоматически; можно показать read-only подсказку.
• app.js: в дефолт cfg (app.js:33) добавить supportURL:"", announce:""; в загрузке конфига (app.js:228) — this.cfg.supportURL = c.supportURL||"", this.cfg.announce = c.announce||""; в save-payload (app.js:340) — supportURL: this.cfg.supportURL||"", announce: this.cfg.announce||"". Стиль/токены — как у соседних полей (Ant-dark скин).

---

Часть B. Сортировка таблицы пользователей

Снизу вверх.

1. internal/entity/user.go — параметры сортировки

• В entity.UserListParams добавить типизированное поле сортировки. Не магическая строка (правило entity): завести type UserSortField string + type SortOrder string (или bool Desc) с константами UserSortName (+ опц. UserSortCreatedAt) и SortAsc/SortDesc. Поля: Sort UserSortField, Order SortOrder (или Desc bool). Дефолт (zero value) = сортировка по имени asc — сохраняет текущее поведение.

2. internal/repository/users/list_page.go — ORDER BY по whitelisted колонке

• Сейчас все 4 ветки pageQuery зашиты ORDER BY name. Заменить на выбор ORDER BY <col> <dir> из фиксированного whitelist (никакой конкатенации пользовательского ввода в SQL — мапим типизированный UserSortField→имя колонки name/created_at, SortOrder→ASC/DESC через switch, дефолт name ASC). Колонки — только реально присутствующие в users (name, created_at). Стабильность: добавить вторичный ключ , id ASC для детерминизма при равных значениях. Count-запросы не трогаем.
• Тонкость: ветки строятся как константные строки — собрать pageQuery остаётся фиксированной строкой на каждую (фильтр × сорт) комбинацию, либо вынести суффикс ORDER BY … в маленький хелпер, возвращающий одну из нескольких констант (а не string-build). Дефолт: хелпер orderClause(p) string возвращает одну из 4 фиксированных констант (name ASC|DESC, created_at ASC|DESC), конкатенируемую к базовому SELECT … LIMIT ? OFFSET ?. Это конкатенация константы, не ввода — соответствует духу комментария в файле.

3. internal/handlers/users_get — проброс параметров

• openapi/users_get.yaml — добавить query-параметры sort (string) и order (string). Без enum/pattern в схеме (правило: value-constraints не в OpenAPI) — просто type: string.
• handler.go (UsersGet, users_get/handler.go:35) — прочитать params.Sort/params.Order, смапить строку запроса в типизированные entity.UserSortField/SortOrder локальным switch (неизвестное значение → дефолт name/asc, не ошибка — сортировка не критична, 400 здесь избыточен). Передать в entity.UserListParams. Контракт userLister.ListPage не меняется по сигнатуре (поля добавлены в UserListParams).
• В ответ возвращать применённые sort/order? Дефолт — не возвращаем (фронт хранит своё состояние). Если фронту нужно эхо — добавить в ответ users_get.yaml; дефолт: не добавляем.

4. Фронт — internal/handlers/web/static/{index.html,app.js}

• index.html:60 — заголовки <th>Имя</th> … сделать кликабельными для столбцов, где сортировка реально поддержана бэком (Имя; при дефолте — только имя). Добавить индикатор направления (стрелка ▲/▼) на активном столбце. Стиль курсора/hover — в токенах темы.
• app.js — состояние userSort ("name"), userOrder ("asc"/"desc"); метод toggleSort(field) — переключает направление/поле, сбрасывает userPage=1, зовёт loadUsers(). В loadUsers (app.js:120) добавить в URLSearchParams sort/order.
• Важно для фронта (issue говорит «имя, трафик, истечение»): при дефолте бэка сортируемы только колонки, по которым умеет SQL (имя). Колонки «Трафик»/«Истечение» кликабельными делать не будем, пока не решена развилка из «Открытые вопросы» (иначе клик не даст эффекта или потребует клиентской сортировки только текущей страницы — вводит в заблуждение). Колонки «Истечение» в таблице сейчас вообще нет (есть только Имя/Подключения/Трафик/Подписка) — добавление столбца истечения — отдельный скоуп, не входит в эту мелочь.

---

Миграции БД

Новый файл migrations/0004-mihomo-profile-links.sql (forward-only, чистый DDL, по имени = по порядку после 0003-*):

-- mihomo_profile: операторские support URL и текст анонса для заголовков /sub
-- (support-url / announce). profile-web-page-url не хранится — выводится из base+token.
ALTER TABLE mihomo_profile ADD COLUMN support_url TEXT NOT NULL DEFAULT '';
ALTER TABLE mihomo_profile ADD COLUMN announce    TEXT NOT NULL DEFAULT '';

• ADD COLUMN … NOT NULL DEFAULT '' совместим с SaveMihomoConfig, который всегда пишет все колонки явно (комментарий в 0001-init.sql:156). Существующие строки получают пустые значения (= «не задано», заголовок не выставляется). Это обычный ALTER без rebuild → транзакционная миграция (.sql, не .notx.sql).
• Сортировка пользователей миграций не требует (name/created_at уже есть в users).

---

OpenAPI / ogen

Править спеку, затем go generate ./internal/oas/.

1. openapi/common.yaml → MihomoConfig (схема read+save, около строки 110): добавить свойства supportURL: {type: string} и announce: {type: string}. В required их НЕ добавлять (опциональные; иначе ogen потребует присутствия). Текущие required — [groups, rules, providers, baseYAML, profileTitle, filename, profileUpdateInterval] — оставить как есть. Это сразу даёт поля и в config_save (тело — allOf с MihomoConfig), и в config_get (ответ — MihomoConfig). Хендлеры config_get.go (около out := &oas.MihomoConfig{…}, строка ~87) и маппинг ответа нужно дополнить новыми полями.
2. openapi/sub.yaml — в responses.200.headers добавить три заголовка (type: string каждый):
   • Support-Url (или точное имя support-url),
   • Profile-Web-Page-Url,
   • Announce.
     ogen сгенерит соответствующие optional-поля в oas.SubOKHeaders — выставлять их в хендлере. Имя заголовка в HTTP — как объявлено ключом в headers: (ogen сохраняет регистронезависимо; согласовать с тем, что читают клиенты: support-url, profile-web-page-url, announce).
3. openapi/users_get.yaml — добавить query-параметры sort и order (оба in: query, schema: {type: string}, без enum). ogen добавит params.Sort/params.Order (oas.OptString).
4. Value-валидация — в коде, не в схеме (правило): не класть в OpenAPI enum/pattern/minLength на новые поля; sentinel-валидация SupportURL/Announce — в mihomo.ValidateProfile; неизвестный sort/order — дефолтится в хендлере.

После правок — go generate ./internal/oas/ и подогнать хендлеры под обновлённые типы (oas.SubOKHeaders, oas.MihomoConfig, oas.UsersGetParams).

---

Тесты

Строго table-driven, один Test{Type}_{Method} на метод.

• internal/mihomo/decode_test.go — расширить TestDecodeConfig кейсами с supportURL/announce (маппинг + trim).
• internal/mihomo/validate_test.go — TestValidateProfile (уже есть, validate_test.go:215): кейсы success.support_announce_set, error.support_url_control_char, error.announce_crlf (новые sentinel'ы). Пустые support/announce — остаются в success-кейсах.
• internal/repository/routing/profile_test.go и save_mihomo_config_test.go — round-trip новых колонок (save → read возвращает SupportURL/Announce); дефолт пустых для старых строк.
• internal/handlers/sub/handler_test.go — TestHandler_Sub: кейс, проверяющий, что при непустых SupportURL/Announce и заданном base выставляются заголовки support-url/announce/profile-web-page-url (через RenderMeta/EngineRenderer-мок из sub/contract.go); кейс с пустыми — заголовки не выставлены. Web-page-url проверить как base + path + token.
• internal/handlers/sub/mihomo_renderer.go покрывается через публичный Render — если у пакета есть renderer-тест, добавить проверку проброса support/announce из routing.Profile-мока.
• internal/repository/users/list_page_test.go — расширить TestRepository_ListPage кейсами сортировки: sort.name_desc, sort.created_at_asc/desc, дефолт (zero UserListParams → name asc), неизвестный sort → дефолт. Проверять порядок Users.
• internal/handlers/users_get/handler_test.go — TestHandler_UsersGet: маппинг params.Sort/Order → entity.UserListParams.Sort/Order (через userLister-мок, EXPECT().ListPage(gomock-матчер на параметры)); неизвестные значения → дефолт.
• apitest (apitest/): не обязателен для этой мелочи. Можно расширить ConfigSuite ассертом, что support_url/announce сохраняются и возвращаются config_get (чёрный ящик, map[string]any), и проверить заголовки /sub. Дефолт: добавить лёгкий ассерт в существующий конфиг-сценарий, новый файл не заводить. Сортировку юзеров — проверить unit'ами репозитория, apitest опционален.

---

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

• CHANGELOG.md — одна запись: ## YYYY-MM-DD — Заголовки подписки support-url/profile-web-page-url/announce + сортировка таблицы юзеров (#112) + 1–2 строки сути.
• ADR — не требуется (изменение тривиально-аддитивное: новые опциональные поля профиля + whitelisted ORDER BY). Единственная развилка с проектным весом — «сортировка по трафику/истечению vs только по DB-колонкам»; если владелец выберет «материализовать флит ради сортировки по трафику» — это меняет data-flow страницы и потребует ADR. По дефолту (сортировка по имени) ADR не нужен.

---

Риски и edge-cases

• Header injection: support-url/announce уходят в HTTP-заголовки ответа /sub. Обязательно отрезать/запретить CR/LF (sentinel-валидация в ValidateProfile, как у filename). Без этого оператор может инжектить заголовки.
• profile-web-page-url зависит от Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106: точный путь лендинга (/sub-page/<token>? иной?) определяет Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106. Если Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 не смержен — оставить URL-шаблон конфигурируемым/выводить по соглашению, согласовать путь при мёрдже. См. «Зависимости».
• Сортировка vs пагинация: SQL ORDER BY сортирует весь отфильтрованный набор до LIMIT/OFFSET — корректно. Но только по DB-колонкам (name/created_at). Трафик/истечение (из флита) так не сортируются — не обещать это во фронте (см. развилку).
• Стабильность сортировки: при равных значениях добавить вторичный id в ORDER BY, иначе страницы могут «дрожать» между запросами.
• Обратная совместимость профиля: старые mihomo_profile-строки получают пустые support_url/announce → заголовки просто не выставляются (клиенты не рисуют кнопки) — мягкая деградация.
• Опциональные заголовки: не слать пустые support-url/announce (иначе клиенты могут показать пустую кнопку).

---

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

• Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 (человеко-ориентированная страница подписки с QR/кнопками импорта) — profile-web-page-url должен указывать на лендинг из Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106. Issue Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 открыт. Порядок: если Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 ещё не смержен, web-page-url выводить по согласованному пути-соглашению (напр. <base>/sub-page/<token>) и финально сверить путь при мёрдже Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106; либо мёржить Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 первым. Заголовки support-url/announce и сортировка от Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 не зависят — их можно делать сразу.
• Части A (заголовки) и B (сортировка) независимы — можно делать в любом порядке/раздельными коммитами в одном PR.

---

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

1. Сортировка по трафику/истечению. Issue просит кликабельные заголовки «имя, трафик, истечение». Но трафик и истечение приходят из кеша флита (entity.Subscriber), а не из БД, при этом таблица серверно-пагинируется (сортировать в SQL можно только name/created_at). Варианты: (а) дефолт плана — серверная сортировка только по имени (и, при желании, дате создания), столбцы Трафик/Истечение не кликабельны; (б) материализовать весь флит и сортировать набор до пагинации (меняет data-flow страницы, дороже, нужен ADR); (в) клиентская сортировка только текущей страницы по трафику (дёшево, но сортирует лишь видимую страницу — может вводить в заблуждение). Какой вариант берём? По умолчанию иду по (а).
2. Путь лендинга для profile-web-page-url (Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106). Какой финальный путь у человеко-страницы подписки из Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106 (напр. /sub-page/{token} vs /p/{token})? От него зависит вывод заголовка. По умолчанию использую <PublicBase>/sub-page/{token} и сверю при мёрдже Человеко-ориентированная страница подписки с QR и кнопками импорта в приложения #106.

[Postlog]

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

• Серверная сортировка таблицы пользователей — только по БД-полям (name, created_at). По трафику/сроку (приходят из кеша флита) серверной сортировки не делаем (вариант «а» из плана). Материализацию флита и ADR не вводим.
• Заголовки подписки support-url / profile-web-page-url / announce — без изменений по плану.