# 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.