elmprodvpn/docs/README.md

Selective VPN Dashboard — Документация

О проекте

• Go-ядро (selective-vpn-api/) управляет nftables, policy routing, DNS, SmartDNS, VPN и trace. Всё взаимодействие идет через локальный REST/SSE сервер (127.0.0.1:8080).
• GUI (selective-vpn-gui/) использует api_client.py и dashboard_controller.py, не дублируя бизнес-логику.
• Задача текущего этапа — проверить ядро, задокументировать API и подготовить почву для будущего веб-прототипа.
• Архитектурный ориентир: один API-контракт для всех клиентов (web + iOS + Android) без развилки бизнес-логики в ядре.
• Принятое направление web prototype: Vite + React + TypeScript (SPA); Next.js не используется на MVP-этапе.
• Фокус текущего desktop-этапа: SingBox вкладка + SingBox Go API (profiles/validate/render/apply); DNSTT/Phoenix остаются backend-ready треком без UI-расширения на этом шаге.

Структура фаз

• Phase A — аудит API, реестр маршрутов и подтверждение, что все операции раскрыты в Go.
• Phase B — проверка внешних зависимостей (nftables, systemd, cgroup, SmartDNS) и фиксация требований к привилегиям/состоянию.
• Phase C — анализ готовности к веб-доступу (binding, SSE, авторизация, CORS, long-running команды).
• Phase D — документирование результатов (матрицы, чеклистов, критериев готовности) и запуск multi-client подхода.
• Phase E — дизайн multi-client PBR: удобное управление несколькими transport-клиентами, изоляция маршрутов и anti-conflict защита.
• Integration Track — подключение внешних transport-клиентов (sing-box, dnstt-client, phoenix->slipstream) через единый API-контракт ядра.

Быстрый доступ к артефактам

• docs/phase-a/A1_API_AUDIT.md — цели и критерии фазы A.
• docs/phase-b/B1_CORE_VERIFICATION.md — набор задач по ядру и зависимостям.
• docs/phase-b/B2_RESOLVER_DIFF_AND_IMPROVEMENT_PLAN.md — различия system resolver vs sing-box DNS и roadmap улучшений нашего resolver.
• docs/phase-b/B4_RUNTIME_DEPENDENCIES_AND_PREFLIGHT.md — разделение go.mod зависимостей и runtime/bin/service зависимостей + preflight-check скрипт.
• docs/phase-b/B5_SINGBOX_TEMPLATE_MIGRATION_ROLLBACK_RUNBOOK.md — runbook миграции legacy singbox-*.service -> singbox@<id>.service и аварийного rollback-плана.
• docs/phase-c/C1_WEB_READINESS.md — возможности и ограничения REST/SSE доступа.
• docs/phase-c/C2_WEB_STACK_DECISION.md — зафиксированное решение по веб-стеку (Vite + React + TypeScript) и условия для возможного перехода на Next.js.
• docs/phase-d/D1_GO_READINESS_DOCS.md — матрицы, чеклисты и тревоги перед веб-прототипом.
• docs/phase-d/D4_PLATFORM_COMPATIBILITY_MATRIX.md — совместимость transport-контракта для web + iOS + Android и платформенные ограничения runtime.
• docs/phase-d/D5_NETNS_RUNTIME_CASE.md — готовый netns-case для SingBox (runtime-check, exec-mode, refactor map GUI/API).
• docs/phase-e/E1_MULTI_CLIENT_PBR_DESIGN.md — целевая архитектура multi-client маршрутизации, mark/table allocator, conflict-guardrails и UX-поток.
• docs/phase-e/E2_TRANSPORT_API_CONTRACT.md — контракт /api/v1/transport/* с DTO, примерами запросов/ответов и workflow validate -> apply.
• docs/phase-e/E4_VALIDATE_CONFIRM_APPLY_UX.md — UX-сценарии предупреждений и подтверждения для конфликтного apply.
• docs/phase-e/E5_SINGBOX_PROTOCOLS_REQUIREMENTS.md — требования к вкладке протоколов SingBox и target Go API для singbox profiles.
• docs/phase-e/E5_2_SINGBOX_DESKTOP_DASHBOARD_SPEC.md — зафиксированный desktop-дизайн вкладки SingBox: runtime card + profile settings + global defaults.
• docs/phase-f/F1_REFACTOR_MODULARITY_PLAN.md — план декомпозиции крупных файлов GUI/API/Go без изменения поведения.
• docs/EXECUTION_TRACKER.md — статус фаз и текущие шаги.
• tests/ — smoke-скрипты для API (sanity, SSE, VPN login, trace append) + общий запуск через tests/run_all.sh.
• selective-vpn-api/cmd/ — явные Go entrypoints (selective-vpn-api, selective-vpn-routes-update, selective-vpn-routes-clear, selective-vpn-autoloop), legacy root main.go сохранён для совместимости.
• selective-vpn-api/app/cli/ и selective-vpn-api/app/bootstrap/ — вынесенные runtime-раннеры (CLI и HTTP bootstrap) при сохранении фасадов Run* в app.
• selective-vpn-api/app/transporttoken/ — вынесенный confirm-token store для transport policy apply/force-override lifecycle.
• selective-vpn-gui/api/ — пакетизированный API-клиент GUI (base client.py + domain mixin-модули status/routes/traffic/dns/domains/vpn/trace/transport_*) с сохранением legacy-фасада api_client.py.
• selective-vpn-gui/controllers/ — пакетизированный слой DashboardController (domain mixin-модули + views.py), при этом dashboard_controller.py сохранён как facade для совместимости импорта в UI.
• selective-vpn-gui/main_window/ — модульные части GUI-окна (constants, workers, ui_shell_mixin, ui_tabs_*, ui_tabs_singbox_{layout,editor}, runtime_actions_mixin, runtime_{state,refresh,auth,ops}) и подпакет main_window/singbox/* (editor/cards/links/runtime + split links_*/runtime_*) при сохранении vpn_dashboard_qt.py как thin-bootstrap/wiring слоя.
• scripts/transport_runbook.py — операционный helper для lifecycle transport-клиентов через API (create/provision/start/health/metrics/restart/stop/delete).
• scripts/transport_recovery_runbook.py — runbook восстановления transport-клиента (health -> restart -> provision/start fallback -> diagnostics).
• scripts/check_runtime_dependencies.sh — preflight-check runtime зависимостей среды (required/optional, --strict режим).
• scripts/transport-packaging/ — manual+pinned updater (update.sh), opt-in scheduler (auto_update.sh) и rollback (rollback.sh) для companion-бинарей (runtime_mode=exec), включая manifest.production.json и source_policy.production.json.
• selective-vpn-web/ — web foundation (Vite + React + TypeScript) для будущего control-plane UI.

Как использовать план

1. Следите за статусом фаз в docs/EXECUTION_TRACKER.md.
2. Обновляйте соответствующие phase-* документы результатами проверок (замены [~] на [x]).
3. После окончания фаз A–D приступить к прототипу веб-интерфейса, опираясь на собранную матрицу endpoint → handler.
4. Интеграционный трек выполнять параллельно с завершением ядра: новые клиенты подключаются через backend-адаптеры, UI остаётся тонким слоем вызовов API.