diff --git a/tasks/multi-agent/BRD.md b/tasks/multi-agent/BRD.md index a8b9b3a..0d77055 100644 --- a/tasks/multi-agent/BRD.md +++ b/tasks/multi-agent/BRD.md @@ -154,6 +154,111 @@ related: Пропущен на пилоте: Дизайн (UI-макеты пока ручные). +## 5.0. Архитектурные принципы и инфраструктурное окружение + +Этот раздел описывает рамки, в которых работает Architect-агент. Он не придумывает инфраструктуру с нуля — он работает внутри уже существующего окружения и следует принципам ниже. + +### Инфраструктурное окружение (что уже есть) + +**Сервер:** +- Один физический VPS — `mva154` (82.22.50.71) +- Ubuntu 22.04 LTS, x86_64, 4 CPU / 16 GB RAM / 200 GB SSD +- Docker + Docker Compose — основной способ запуска всего +- Всё живёт на одной машине: Gitea, Plane, OpenClaw, приложения + +**Сеть и доступ:** +- Домен: `*.mva154.duckdns.org` (DuckDNS, динамический IP) +- HTTPS: Let's Encrypt через reverse proxy +- Reverse proxy: Nginx (проксирует по path: `/enduro/`, `/noisemap/`, `/snowbike/` и т.д.) +- Внутренняя Docker-сеть: контейнеры общаются по именам (`openclaw-gateway`, `claude-cli-proxy`, `gitea`) +- Внешний доступ: только через Nginx (порты не торчат наружу, кроме 80/443/2222) + +**Хранение данных:** +- SQLite — для мелких сервисов и прототипов (быстро, без зависимостей) +- PostgreSQL — для Plane, для продакшен-сервисов когда нужны транзакции/конкурентность +- Файловая система — для тайлов, статики, данных (GeoTIFF, MBTiles) +- Git (Gitea) — source of truth для кода и документации + +**CI/CD:** +- Gitea Actions (совместимы с GitHub Actions) +- Runner — на том же mva154 (self-hosted) +- Деплой: `docker compose up -d` или `docker cp` + restart +- Нет Kubernetes, нет облака, нет multi-node + +**Мониторинг:** +- Пока минимальный: Docker healthchecks + ручные проверки +- Логи: `docker logs ` +- Нет Prometheus/Grafana (можно добавить в v2) + +### Архитектурные принципы + +**1. Всё в Docker.** +Каждый сервис — контейнер. Никаких `apt install` на хосте для runtime-зависимостей. Исключение: Node.js и Claude Code CLI (нужны на хосте для агентов). + +**2. Один основной сервер, но не единственный.** +mva154 — основной хост. Но проект может использовать другие машины (например, `fr24` — отдельная VM). Какие машины задействованы — фиксируется в артефакте «Инфраструктура» на этапе Архитектуры и требует approve от Славы. Нет load balancer, нет service mesh, нет multi-region. Если сервисы на одном хосте — Docker-сеть, обращаются по имени контейнера. + +**3. Polyrepo.** +Каждый проект — отдельный репозиторий в Gitea. Нет monorepo. Каждый репо самодостаточен: свой Dockerfile, свой CI, свой CLAUDE.md, свои тесты. Общие библиотеки — через пакеты (pip/npm), не через симлинки. + +**3. Stateless сервисы, state в хранилище.** +Приложение не хранит состояние в памяти между запросами. Состояние — в БД (SQLite/PostgreSQL) или на файловой системе. Контейнер можно убить и поднять заново без потери данных. + +**4. SQLite по умолчанию, PostgreSQL когда нужно.** +Для нового сервиса — начинать с SQLite (проще, нет зависимости). Переходить на PostgreSQL когда: конкурентная запись, сложные запросы, >1 GB данных, или нужны транзакции с изоляцией. + +**5. Простой деплой.** +`docker compose up -d` — и сервис работает. Никаких Helm-чартов, Terraform, Ansible. Конфигурация — через `.env` файлы и docker-compose.yml. + +**6. Reverse proxy — Nginx.** +Все сервисы доступны через `https://openclaw.mva154.duckdns.org//`. Nginx проксирует по path prefix. Новый сервис = новый `location` блок в Nginx. + +**7. Данные рядом с кодом.** +Тяжёлые данные (тайлы, GeoTIFF, дампы) — на файловой системе хоста, монтируются в контейнер через volumes. Не в Git (слишком большие), не в S3 (нет облака). + +**8. Минимум зависимостей.** +Не тащить фреймворк ради одной функции. FastAPI > Django (для API). SQLite > PostgreSQL (для прототипа). Vanilla JS > React (для простого фронта). Добавлять зависимость только когда она реально экономит время. + +**9. Conventional commits + trunk-based.** +Одна ветка `main` (стабильная). Короткоживущие feature-ветки. Conventional commits (`feat:`, `fix:`, `docs:`). Squash merge. + +**10. Безопасность: минимальная поверхность атаки.** +Порты не торчат наружу без необходимости. Секреты в `.env`, не в коде. Docker-контейнеры без `--privileged`. Service account `claude-bot` без admin-прав. + +### Стек пилотного проекта (Enduro Trails) + +| Слой | Технология | Почему | +|------|-----------|--------| +| Frontend | MapLibre GL JS + vanilla JS | Карта, без фреймворка — проще, быстрее | +| Backend | FastAPI + uvicorn | Лёгкий, async, Python-экосистема для гео | +| БД | SQLite (Spatialite) → PostGIS | Прототип на SQLite, продакшен на PostGIS | +| Роутинг | OSRM (кастомный профиль) | Быстрый, офлайн, настраиваемый | +| Тайлы | Self-hosted MVT (FastAPI) | Без внешних зависимостей | +| Контейнеризация | Docker Compose | Один файл — весь стек | +| CI | Gitea Actions | lint (ruff) + test (pytest) + build (docker) | +| Деплой | docker compose up -d | Простой, предсказуемый | + +### Что Architect НЕ должен делать + +- ❌ Предлагать Kubernetes, Helm, Terraform +- ❌ Проектировать для multi-node / multi-region +- ❌ Добавлять message queue (RabbitMQ, Kafka) без явной необходимости +- ❌ Предлагать облачные сервисы (AWS, GCP) — всё on-premise +- ❌ Менять reverse proxy (Nginx → Traefik/Caddy) без согласования +- ❌ Добавлять ORM (SQLAlchemy) если хватает raw SQL +- ❌ Проектировать микросервисы — предпочитать monolith-first + +### Что Architect ДОЛЖЕН делать + +- ✅ Фиксировать решения в ADR (Architecture Decision Records) +- ✅ Создавать артефакт «Инфраструктура» (`07-infra-requirements.md`) — обязательный, требует :approved: от Славы +- ✅ Рисовать C4-диаграммы (Mermaid) для контекста и компонентов +- ✅ Описывать API-контракты (OpenAPI / JSON Schema) +- ✅ Указывать требования к данным (схема БД, миграции) +- ✅ Оценивать риски и trade-offs +- ✅ Учитывать существующую инфру (не изобретать заново) +- ✅ Проверять req-coverage (каждое требование из ТЗ покрыто решением) + ## 5.1. Структура репозитория (канон) ``` @@ -301,7 +406,7 @@ claude -p "Прочитай CLAUDE.md. Прочитай docs/work-items/