EvoBGP/docs/manual.md

# Полное руководство по EvoBGP

Этот документ объединяет эксплуатационное и разработческое описание системы: что делает каждый процесс, как двигаются данные, какие API использовать и где искать причины инцидентов.

## 1. Назначение системы

EvoBGP управляет генерацией и применением BGP-конфигураций на основе модулей источников префиксов (`AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS`, `IP_RANGES`).

Система разделена на:
- **control plane**: API, БД, jobs, рендер ревизий, публикация и подписание бандлов;
- **data plane**: BIRD и связанный агент/нода для применения ревизий.

## 2. Компоненты и роли бинарников (`cmd/*`)

### `evobgp-api`
- Основной HTTP API.
- Поднимает маршруты из `internal/httpapi`.
- Работает с `store`/`repository`, jobs и аутентификацией.

### `evobgp-all`
- Монолитный режим: API + scheduler + ingest + render + deploy в одном процессе.
- Удобен для компактных окружений (`microvps`).

### `evobgp-scheduler`
- Периодически запускает `module_refresh` по расписанию/интервалам.
- В reference-профиле может стучаться в API и/или работать через store.

### `evobgp-ingest`
- Периодически делает prefetch внешних CDN-источников (ETag/доступность).

### `evobgp-render`
- Ведёт рендер-цикл; в режиме autopublish может назначать последнюю ревизию на спикеры.

### `evobgp-deploy`
- Диагностирует drift: различия между опубликованной и применённой ревизией.

### `evobgp-node`
- CLI-нода для edge: загрузка бандла, верификация подписи, применение.

### `evobgp-agent`
- Локальный агент рядом с BIRD (наблюдение и служебные операции).

## 3. Карта внутренних модулей (`internal/*`)

### API и доступ
- `internal/httpapi`: маршруты, auth, CORS, problem+json, CRUD, jobs endpoints.

### Данные
- `internal/store`: бизнес-контракты бэкенда.
- `internal/repository`: PostgreSQL-реализация.
- `internal/db`: коннект и миграции.

### Jobs/pipeline
- `internal/jobs`: очередь задач и worker.
- `internal/pipeline`: `module_refresh`, сбор источников, материализация, рендер-превью.
- `internal/scheduler`, `internal/ingest`, `internal/render`, `internal/deploy`: фоновые циклы.

### BIRD и бандлы
- `internal/birdfmt`: генерация конфигурации BIRD.
- `internal/birddeploy`: применение конфигурации и интеграция с `birdc`.
- `internal/bundle`, `internal/signing`: упаковка и криптографическая проверка.

### Наблюдаемость и служебные
- `internal/observability`: метрики/middleware.
- `internal/asnresolve`: внешние резолвы ASN.
- `internal/broker`: задел под внешний брокер.
- `internal/config`, `internal/platform`: параметры среды и платформенные адаптеры.

## 4. Сквозной поток данных

1. Оператор меняет данные модуля (CRUD источников, peers/speakers, настройки).
2. Включённый модуль триггерит `module_refresh`.
3. `jobs.Worker` вызывает `pipeline.RefreshModule`.
4. Pipeline собирает префиксы всех enabled-модулей tenant, строит materialized snapshot.
5. Создаётся ревизия и BIRD preview.
6. По операциям deploy/apply ревизия применяется на спикере.
7. Нода получает бандл, проверяет подпись, применяет локально.

## 5. API: ключевые группы и сценарии

Источник истины контракта: `docs/openapi.yaml`.

### Основные группы endpoint-ов
- `Modules`: модули и их общие параметры.
- `AS Entries`, `CDN Sources`, `Domain Entries`, `IP Range Entries`: источники префиксов.
- `Peers`, `Speakers`: сетевая топология применения.
- `Revisions`, `Deploy`, `Jobs`: жизненный цикл ревизий и фоновых задач.
- `Settings`: глобальные KV-настройки.
- `Node`: edge-флоу бандлов/enrollment.

### Типовой сценарий оператора
1. Создать/обновить модуль и его источники.
2. Дождаться или инициировать refresh.
3. Проверить ревизию и diff.
4. Выполнить apply на целевой спикер.
5. Проверить health/monitoring/jobs.

## 6. Настройки и доступ

### Аутентификация/роли
- Роли и правила доступа: `docs/access.md`.
- Для мутаций критичных сущностей требуется `editor`/`operator`.

### Настройки (`/v1/settings`)
- KV c ключами BIRD и дополнительными feature flags.
- Ключевые параметры BIRD: `bird_router_id`, `bird_local_ipv4`, `bird_local_ipv6`, `bird_local_asn`, `bird_bgp_source_ipv4`, `bird_bgp_source_ipv6`.

## 7. Эксплуатация и runbook

### Что проверять при инцидентах
1. Статус API и БД.
2. Состояние jobs (`module_refresh`, `deploy_apply`), ошибки в job meta.
3. Состояние внешних источников (CDN/DoH/ASN).
4. Состояние BIRD и применённой ревизии на спикере.

### Частые причины проблем
- Невалидные данные источников (непарсящийся JSON/plaintext для CDN).
- Неполные настройки BIRD.
- Ошибки внешних upstream (RIPEstat/DoH/CDN).
- Расхождение published/applied ревизии.

## 8. Разработка и расширение

### Где вносить изменения
- Новый endpoint: `internal/httpapi` + обновление `docs/openapi.yaml`.
- Новая логика источника: `internal/pipeline` + соответствующие CRUD/store/repository.
- Новая операция UI: `web/src/routes/*` и `web/src/lib/components/*`.

### Рекомендации по качеству
- Для изменений API всегда обновлять `docs/openapi.yaml`.
- Для изменений UI держаться единого набора компонентов shadcn-svelte и Lucide.
- Для pipeline-изменений добавлять метрики стадии и явные trigger-метки job.

## 9. Индекс исходников (быстрый вход)

- Архитектура: `docs/architecture.md`
- API обзор: `docs/api.md`
- Контракт API: `docs/openapi.yaml`
- Доступ/роли: `docs/access.md`
- Web запуск: `web/README.md`
- Compose: `deploy/compose/docker-compose.yaml`