elmprodvpn/docs/phase-e/E5_2_SINGBOX_DESKTOP_DASHBOARD_SPEC.md

E5.2 SingBox Desktop Dashboard Spec

Дата: 2026-03-07
Статус: in-progress (foundation implemented)
Владелец: Engineering

1) Цель

• Зафиксировать дизайн вкладки SingBox для desktop, чтобы не смешивать runtime-управление и конфигурацию профилей.
• Подготовить структуру, которую позже можно переиспользовать в web/mobile.

2) Структура вкладки (fixed)

• Визуальная модель: card-based dashboard (верхние metric cards + grid profile cards + control panels).

A. Connection card (runtime)

• Показывает только текущее состояние подключения:
  • runtime status,
  • active profile,
  • protocol/transport,
  • routing/dns/kill-switch effective state,
  • last update timestamp.
• Быстрые действия:
  • Prepare,
  • Connect/Switch,
  • Disconnect,
  • Restart,
  • Rollback policy.

B. Profile settings (per profile)

• Настройки конкретного профиля:
  • Routing mode,
  • DNS mode,
  • Kill-switch.
• Для каждого блока поддерживается Use global ... (наследование).
• Действия профиля:
  • Save draft,
  • Validate profile,
  • Apply profile.

Примечание этапа:

• Validate/Apply profile через /api/v1/transport/singbox/profiles/* будут полноценно подключены на шагах E5.2/E5.3.
• На foundation-этапе эти кнопки логируют намерение и не ломают runtime-flow.

C. Global defaults

• Общие дефолты для всех профилей:
  • default routing mode,
  • default DNS mode,
  • default kill-switch.
• Сохранение настроек и применение в effective-резолюции профиля.

3) Правило приоритета (обязательное)

• Profile override > Global default.
• Если в профиле включено Use global ..., используется глобальное значение.
• Runtime card всегда показывает итоговое effective состояние.

4) Границы ответственности

• Вкладка SingBox управляет только SingBox профилями/engine.
• DNSTT/Phoenix в этом этапе не добавляются во вкладку (backend-ready трек отдельно).
• Routing policy ownership/anti-conflict остаётся в Go API pipeline validate -> confirm -> apply.

5) Что уже реализовано в GUI foundation

• Перестроена вкладка на 3 секции: runtime card, profile settings, global defaults.
• Добавлен card-based UI слой:
  • верхний ряд compact metric cards,
  • кликабельный grid connection profile cards (выбор карточки синхронизирован с active engine selector).
• Реализован compact-mode для настроек:
  • Runtime details, Profile settings, Global defaults, Activity log открываются кнопками, по умолчанию скрыты.
• Добавлены Use global переключатели и effective summary.
• Добавлено локальное сохранение настроек (QSettings) для global/profile режимов.
• Сохранены рабочие runtime-кнопки Prepare/Connect-Switch/Disconnect/Restart/Rollback.

6) Следующий технический шаг

• Подключить профильные кнопки Validate/Apply к реальному Go API:
  • POST /api/v1/transport/singbox/profiles/{id}/validate,
  • POST /api/v1/transport/singbox/profiles/{id}/apply,
  • с обработкой base_revision, ошибок и rollback-подсказок в UI.