elmprodvpn/docs/phase-d/D4_PLATFORM_COMPATIBILITY_MATRIX.md

D4.3 Матрица совместимости (Web + iOS + Android)

Дата: 2026-03-07
Статус: done
Владелец: Engineering

1) Цель

• Зафиксировать единый контракт, чтобы web, iOS, Android переиспользовали одно Go-ядро (/api/v1) без платформенных форков бизнес-логики.
• Явно обозначить ограничения transport-runtime и ожидания к клиентам.

2) Инвариант архитектуры

• Все transport-клиенты (singbox, dnstt, phoenix) запускаются на стороне хоста с selective-vpn-api через backend-адаптеры.
• web/iOS/Android являются control-plane клиентами: вызывают API, читают состояние, запускают validate/apply flow.
• Платформы не должны управлять локальными systemd/бинарями напрямую.

3) Платформенная матрица API-контракта

Контур	Web (Vite + React + TS)	iOS	Android
Базовый API	GET/POST /api/v1/*	GET/POST /api/v1/*	GET/POST /api/v1/*
Realtime	SSE (/api/v1/events/stream) в foreground	SSE в foreground, polling fallback в background	SSE в foreground, polling fallback в background
Transport capabilities	GET /api/v1/transport/capabilities	тот же endpoint	тот же endpoint
Policy flow	GET /policies, POST /validate, POST /apply, POST /rollback	тот же flow	тот же flow
Auth/TLS	gateway/proxy + token	gateway/proxy + token + secure storage	gateway/proxy + token + secure storage
Error contract	ok/code/message/exitCode/stderr	идентично	идентично

4) Матрица transport backend vs платформы

Transport backend (в Go-ядре)	Web UI	iOS UI	Android UI	Ограничения
singbox	Поддержан через API	Поддержан через API	Поддержан через API	runtime на сервере, не в мобильном UI
dnstt (+ ssh_overlay)	Поддержан через API	Поддержан через API	Поддержан через API	SSH overlay оркестрируется backend-ом
phoenix -> slipstream	Поддержан через API	Поддержан через API	Поддержан через API	подключение/health/metrics только через backend

5) Runtime/packaging ограничения

• Поддерживаемый runtime mode на текущем этапе: exec=true.
• embedded=false, sidecar=false (зарезервировано, без silent fallback).
• Packaging profiles: system=true, bundled=true.
• Практический вывод для платформ:
  • UI показывает capabilities и ограничения из backend.
  • UI не должен предполагать поддержку embedded/sidecar до явного включения в capabilities.

6) Проверка совместимости (smoke)

• Скрипт: tests/transport_platform_compatibility_smoke.py.
• Проверяет:
  • наличие singbox/dnstt/phoenix в /transport/capabilities,
  • runtime_modes.exec=true,
  • packaging_profiles.system=true, packaging_profiles.bundled=true,
  • рабочий policy-контракт (/transport/policies, /validate, /conflicts).

Команда запуска:

API_URL=http://127.0.0.1:8080 ./tests/transport_platform_compatibility_smoke.py

7) Итог D4.3

• Совместимость web + iOS + Android зафиксирована как единый API-контракт control-plane.
• Все transport-runtime различия остаются в Go-ядре.
• Это позволяет продолжать backend-first реализацию и затем переиспользовать ту же логику в desktop/web/mobile UI.