platform: modularize api/gui, add docs-tests-web foundation, and refresh root config

docs/phase-b/B2_RESOLVER_DIFF_AND_IMPROVEMENT_PLAN.md

@@ -0,0 +1,76 @@
+# B2 Resolver: разница ролей и план улучшения
+
+Дата: 2026-03-07  
+Статус: planned  
+Владелец: Engineering
+
+## 1) Цель
+- Зафиксировать, чем отличается текущий системный resolver selective-vpn от DNS-модуля `sing-box`.
+- Зафиксировать roadmap доработки нашего resolver, чтобы он оставался основой для `selective`-маршрутизации.
+
+## 2) Роли компонентов
+- `System resolver` (Go + SmartDNS + nftset):
+  - источник истины для PBR (`routes/update`, nft sets, wildcard/static fallback),
+  - системный контроль резолва для selective-режима.
+- `SingBox DNS`:
+  - DNS-часть transport-профиля `sing-box`,
+  - управляет резолвом внутри конкретного engine/profile.
+
+Правило слоя:
+- В текущей архитектуре authoritative для маршрутизации остаётся системный resolver.
+- `SingBox DNS` используется как transport-level capability и не заменяет системный PBR resolver.
+
+## 3) Матрица различий
+
+| Область | System resolver (текущий) | SingBox DNS |
+| --- | --- | --- |
+| Основная роль | Системная selective-маршрутизация | DNS внутри transport engine |
+| Связь с nft/PBR | Прямая (`agvpn4/agvpn_dyn4`, `routes/update`) | Непрямая, через поведение engine |
+| Wildcard runtime | Да (SmartDNS nftset + merge в `routes/update`) | Нет прямого контроля системных nft sets |
+| Static fallback | Да (`static-ips.txt`, policy merge) | Через raw/typed config профиля |
+| Единая картина для всех клиентов | Да, через Go state/API | Нет, scoped к конкретному профилю |
+| Риск рассинхрона | Низкий при single source of truth | Высокий, если использовать как отдельный source of truth |
+
+## 4) Основные gap-ы текущего resolver
+- Недостаточная наблюдаемость по качеству резолва (latency/error-rate/NX/servfail per upstream).
+- Нет отдельного endpoint'а с полным health snapshot resolver pipeline.
+- Нужна более строгая TTL/refresh-стратегия для mixed источников (cache + wildcard runtime + static).
+- Нужен формализованный negative caching и rate-limit на проблемные домены при деградации upstream.
+- Нужна формализация owner-map для доменов в multi-client сценариях (без дублей и гонок).
+
+## 5) План улучшения resolver (приоритеты)
+
+### R1 Надёжность и консистентность
+- Ввести unified resolver state snapshot (`updated_at`, `stale`, `refresh_in_progress`, `last_error`, `next_retry_at`, counters).
+- Усилить single-flight на expensive refresh-path и добавить доменный backoff.
+- Нормализовать merge-порядок источников: `static fallback -> wildcard runtime -> resolver cache`.
+
+### R2 Качество резолва
+- Добавить adaptive upstream scoring (latency/success/NX/timeout/servfail).
+- Добавить sticky-preferred upstream с безопасным failover.
+- Ввести отдельную политику negative cache TTL для NXDOMAIN/SERVFAIL.
+
+### R3 Наблюдаемость и API
+- Добавить API snapshot для resolver health:
+  - `GET /api/v1/resolver/status` (target),
+  - `POST /api/v1/resolver/refresh` (target trigger),
+  - `GET /api/v1/resolver/upstreams` (target metrics).
+- Добавить SSE-события:
+  - `resolver_status_changed`,
+  - `resolver_upstream_degraded`,
+  - `resolver_refresh_completed`.
+
+### R4 Multi-client безопасность
+- Ввести `domain_owner_map` и conflict-detection до применения policy.
+- Гарантировать, что один domain-selector не получает двух владельцев без explicit override.
+- Синхронизировать resolver ownership с transport policy revision.
+
+## 6) Критерии готовности B2
+- Есть документированная и реализуемая разница ролей `system resolver` vs `sing-box DNS`.
+- Resolver имеет прозрачный health/status API и наблюдаемость по upstream.
+- При деградации upstream UI получает stale-safe состояние, а не "пустой провал".
+- В multi-client режиме домены не уходят в двойное владение без подтверждённого override.
+
+## 7) Ограничения этапа
+- В этом этапе не переводим управление маршрутизацией на `SingBox DNS`.
+- `DNSTT/Phoenix` DNS-аспекты не расширяются в UI до завершения `SingBox` API/GUI трека.