EvoBGP/docs/README.md

# Документация EvoBGP

Структурированные материалы по проекту на русском языке. Детальный перечень полей и ответов HTTP API — в [openapi.yaml](openapi.yaml) (OpenAPI 3.1).

## По роли читателя

- **ИИ-агент / ассистент в репозитории** — [../AGENTS.md](../AGENTS.md): с чего начать чтение, карта `internal/` и `cmd/`, что не тащить в контекст. **Инженерные правила:** [../.cursor/rules/engineering.mdc](../.cursor/rules/engineering.mdc) (общие), [../.cursor/rules/web-shadcn.mdc](../.cursor/rules/web-shadcn.mdc) (Web UI), [../.cursor/rules/networking-bird.mdc](../.cursor/rules/networking-bird.mdc) (BIRD2/BGP/IP).
- **Оператор / DevOps** — [quickstart.md](quickstart.md), [architecture.md](architecture.md), [access.md](access.md), [deploy/compose/docker-compose.yaml](../deploy/compose/docker-compose.yaml).
- **Разработчик бэкенда или интегратор API** — [api.md](api.md), [access.md](access.md), [openapi.yaml](openapi.yaml), исходники маршрутов в `internal/httpapi/`.
- **Разработчик фронтенда** — [quickstart.md](quickstart.md) (раздел про `apps/web/` и CORS), [api.md](api.md), [ui-design-contract.md](ui-design-contract.md), [../apps/web/](../apps/web/).

## Оглавление

| Раздел | Описание |
|--------|----------|
| [overview.md](overview.md) | Ключевые возможности системы |
| [quickstart.md](quickstart.md) | Быстрый запуск: готовые образы из `git.shx.one`, Docker Compose, локальный Go, веб |
| [architecture.md](architecture.md) | Компоненты, потоки данных, пакеты |
| [backend-improvement-plan.md](backend-improvement-plan.md) | План улучшения backend, статистики и Docker; статус выполнения |
| [backend-baseline.md](backend-baseline.md) | Этап 0: ресурсные snapshots и воспроизведение дефектов |
| [backend-compatibility.md](backend-compatibility.md) | Проверяемые legacy-контракты и оставшиеся проверки старых speakers |
| [bundle-limits.md](bundle-limits.md) | Пределы загрузки/распаковки бандлов и безопасные пути файлов |
| [outbound-policy-decision.md](outbound-policy-decision.md) | Разрешённые внутренние DoH/RIPE, отдельная защита CDN и пределы внешних ответов |
| [metrics-semantics.md](metrics-semantics.md) | Исторические, inventory и live-метрики; совместимость имён и ошибки сбора |
| [docker-resources.md](docker-resources.md) | Optional NATS, retention и перенос истории Prometheus, границы проверки Docker |
| [manual.md](manual.md) | Подробное руководство по модулям, процессам и API |
| [api.md](api.md) | REST: префикс `/v1`, публичные маршруты, ссылки на OpenAPI |
| [router-lists-ui-integration.md](router-lists-ui-integration.md) | Интеграция `router-lists-ui` с EvoBGP API (`DOMAINS/IP_RANGES/AS_PREFIXES/communities`) |
| [access.md](access.md) | Выдача доступа: API-ключи, роли, нода, CORS |
| [remote-speakers.md](remote-speakers.md) | Удалённые BGP-реплики: Traefik, agent sync, compose |
| [releasing.md](releasing.md) | Автоматические релизы, Conventional Commits, CI |
| [ui-design-contract.md](ui-design-contract.md) | UI SoT: ReUI Frame, kit, KPI hybrid |
| [kpi-cross-app-sync.md](kpi-cross-app-sync.md) | Синхронизация KPI/QuickActions DNA с sibling-apps |
| [adr/](adr/) | Architecture Decision Records |
| [openapi.yaml](openapi.yaml) | Источник правды по контракту API |
| [OPENAPI-GITEA.md](OPENAPI-GITEA.md) | Как открыть HTML-документацию API (в т.ч. из Gitea) |
| [evobgp-api-sketches.md](evobgp-api-sketches.md) | Ранний черновик идей API (контекст, не замена OpenAPI) |

## Инженерные правила (Cursor / разработка)

| Файл | Область |
|------|---------|
| [../.cursor/rules/engineering.mdc](../.cursor/rules/engineering.mdc) | Go, API, migrations, security, enforcement |
| [../.cursor/rules/web-shadcn.mdc](../.cursor/rules/web-shadcn.mdc) | React + TanStack + shadcn/ui + ReUI (`apps/web`, `packages/ui`) |
| [../.cursor/rules/reui-mcp.mdc](../.cursor/rules/reui-mcp.mdc) | ReUI PRO MCP workflow, surface `frame` |
| [../.cursor/rules/networking-bird.mdc](../.cursor/rules/networking-bird.mdc) | BIRD2, BGP policy, IP/CIDR |
| [../.cursor/rules/conventional-commits.mdc](../.cursor/rules/conventional-commits.mdc) | Conventional Commits (заголовок EN, тело RU) |

### Сообщения коммитов (Cursor)

После `git add`:

| Способ | Skill + rule + `staged-context.ps1` |
|--------|-------------------------------------|
| Agent → **`/commit-message`** или «сгенерируй коммит по staged» | **Да** |
| Кнопка **✨ Generate commit message** в Source Control | **Нет** (только diff + история; [ограничение Cursor](https://forum.cursor.com/t/how-to-set-prompt-for-generate-commit-message/148606)) |

Рекомендуемый workflow: Agent Chat → **`/commit-message`** ([команда](../.cursor/commands/commit-message.md), [скилл](../.cursor/skills/commit-message/SKILL.md), [правило](../.cursor/rules/conventional-commits.mdc)). Агент **обязан первым делом** запустить `scripts/commit/staged-context.ps1` (заголовок EN, тело RU, auto-split).

Просмотр групп вручную: `powershell -NoProfile -File scripts/commit/staged-context.ps1 | ConvertFrom-Json`.

## Репозиторий и CI

- [../.gitea/README.md](../.gitea/README.md) — Gitea Actions, runner, сборка образов и push в Container Registry.
- [releasing.md](releasing.md) — semantic-release, commit conventions, теги образов.