60 lines
4.1 KiB
Markdown
60 lines
4.1 KiB
Markdown
# 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`).
|
||
|
||
Команда запуска:
|
||
```bash
|
||
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.
|