auto-sync: 2026-05-15 02:10:01

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 <container>`
+- Нет 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/<path>/`. 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/<plane-i
 |----|-------|---------------|-----|
 | QG-0 | Постановка → Анализ | title + description заполнены | Orchestrator (webhook) |
 | QG-1 | Анализ → Архитектура | ТЗ/BRD/AC есть + :approved: от Славы | Orchestrator (файл + Plane API) |
-| QG-2 | Архитектура → Разработка | ADR есть, req-coverage, диаграммы рендерятся | Orchestrator (lint-adr.sh) |
+| QG-2 | Архитектура → Разработка | ADR есть, `07-infra-requirements.md` :approved:, req-coverage, диаграммы рендерятся | Orchestrator (lint-adr.sh + Plane reaction check) |
 | QG-4 | Разработка → Review | CI зелёный (lint + test + build) | Gitea Actions → webhook |
 | QG-5 | Review → Тестирование | Review approve + 0 unresolved | Orchestrator (Gitea API) |
 | QG-6 | Тестирование → Внедрение | Все тесты зелёные, test-report создан | Orchestrator |