GenDesign — Site Finder + Trade-In «Мера»

Несколько продуктовых линий для девелоперов и риелторов РФ в одном монорепо:

• Site Finder v2 «Foresight» — AI-подбор инвестиционных земельных участков + прогноз продуктовой стратегии («GG-форсайт»: спрос/предложение, сценарии, что строить, gate-вердикт по ПЗЗ/ЗОУИТ/ОКН).
• Trade-In «Мера» — оценка выкупной стоимости вторичного жилья (адрес → оценка по аналогам и реальным сделкам, PDF-отчёт, white-label). tradein-mvp/, отдельный пайплайн.
• Generative Design — автоматическая генерация концепций застройки (на ранней стадии).

Целевой регион Discovery — Свердловская обл. (ЕКБ, ПЗЗ, МСК-66).

North Star

К концу месяца 3: 3 платящих пилота (≥30 тыс. ₽/мес каждый) + заявка в реестр российского ПО → право на Раунд А (20–25 млн ₽).

---

Текущий статус (июнь 2026)

Live: https://gendsgn.ru/ — HTTP/2+HTTP/3, валидный TLS, /health {"status":"ok"}. Полный CI/CD: Forgejo Actions (git.gendsgn.ru) → GHCR → SSH-deploy на Beget VPS (миграция с GitHub Actions 16 мая 2026). Sentry/GlitchTip активен (release tracking привязан к git-sha).

Слой	Статус
Site Finder v2 «Foresight» (/site-finder) — анализ участка по cad_num, карта by-bbox, forecast-движок	✅ live
↳ Forecast-движок (/parcels/{cad}/forecast + /analyze): спрос/предложение, сценарии, confidence, affordability, rate-sensitivity, продуктовое ТЗ	✅ (backend/app/services/forecasting/*, фронт Section6Forecast + ScenariosBlock + ForecastConfidenceBlock)
↳ Gate-вердикт ПЗЗ/ЗОУИТ/ОКН (gate_verdict) + ИРД-overlay/analyze	✅ backend (gate_verdict.py, ird_overlay_lookup.py, ird_analyze.py); фронт GateVerdictBanner
↳ Конкуренты / best-layouts / изохроны (/parcels/{cad}/competitors, /best-layouts, /isochrones)	✅ live
Trade-In «Мера» (/trade-in) — оценка вторички по аналогам + реальным сделкам, PDF, white-label	✅ live (tradein-mvp/, отдельный стек/пайплайн)
↳ Скрейперы аналогов: Avito / Cian / Domclick / Yandex.Realty (+ детальные парсеры, browser-fetcher)	✅
↳ SberIndex time-adjust (city-level вторичный индекс цен) + Rosreestr ДКП-сделки + ДаДата/геокодер	✅
Аналитический калькулятор /analytics/recommend (Tier 3 per-bucket эластичность, кадастр vs рынок)	✅
DOM.РФ kn-API скрейпер (строящиеся ЖК Свердл, sale_graph + infra + photos)	✅ Celery beat + admin UI
NSPD geo bulk-fetcher (rosreestr2coord lite, без Playwright)	✅ admin UI с per-target логами
Rosreestr CSV-сделки (квартирные партиции, ~7M строк, 27 мес истории)	✅
NSPD кадастровые кварталы + здания ЕКБ	✅ Celery beat + admin UI
OSM ekb_districts_geom (PostGIS-полигоны районов ЕКБ)	✅
Objective ETL (Anton SQLite → PG, ports на psycopg v3)	✅ admin UI
Uptime Kuma мониторинг (status.gendsgn.ru, отдельный стек)	✅
Obsidian Self-hosted LiveSync vault на obsidian.gendsgn.ru	✅ multi-device sync
Concept page (/concept) — Generative Design	🟡 skeleton

Backlog: Forgejo Issues (трекаемые задачи с PR-связью) + Obsidian vault (планы, ADR, research — см. ниже про разделение).

---

Quick start (локально)

Требования: Docker Desktop, Node.js 20+, uv для backend dev.

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
docker compose up -d --build
curl http://localhost:8000/health   # → {"status":"ok","environment":"dev"}
# Frontend:  http://localhost:3000
# Swagger:   http://localhost:8000/docs

Полезные make-таргеты: logs, backend-shell, migrate, test, lint, typecheck, codegen (TS-типы из OpenAPI).

---

Архитектура

Backend: Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2, Celery + Redis, httpx, Shapely 2, scikit-learn. БД: PostgreSQL 16 + PostGIS 3.4 (партиционированные rosreestr_deals, GIST на geom-полях, ~50 предметных таблиц). Frontend: Next.js 15, React 19, TypeScript 5, Tailwind 4, TanStack Query, Leaflet/Mapbox, ECharts. Экспорт: WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel). Dev: uv lockfile, ruff, mypy strict (на core + generative), pytest, pre-commit hooks.

Структура монорепо:

backend/                 FastAPI app, services (analytics_queries, scrapers, generative, site_finder, forecasting), workers (Celery)
frontend/                Next.js app router (analytics, admin, concept, site-finder + forecast/scenarios компоненты)
tradein-mvp/             Trade-In «Мера» — standalone стек (FastAPI + Next.js + Postgres + Caddy), скрейперы вторички, PDF-оценка
site-finder/             standalone pipeline-скрипты SF v1 (01–12_*.py загрузка/скоринг) + server.py (Leaflet UI на SQLite-кэше)
auth/                    roles.yaml — RBAC (single source of truth, bind-mount в main + tradein backend)
caddy/                   users.caddy.snippet — basic-auth snippet для Caddy
preview/                 статичные HTML-макеты (analytics / landing / monitoring / site-finder)
data/sql/                ETL артефакты — миграции схемы, загрузчики rosreestr/anton/nspd
ops/                     backup.sh + deploy скрипты
scripts/                 утилиты (migrate_kg_to_obsidian.py, setup-couchdb.sh, cleanup_ghosts.py)
docs/                    стратегические снапшоты (актуальное knowledge — в Obsidian vault)
memory/                  legacy JSONL knowledge graph (deprecated, не обновляется — данные в Obsidian)
docker-compose.prod.yml  main стек (backend, frontend, postgres, redis, worker, beat, caddy)
docker-compose.obsidian.yml  obsidian-стек (CouchDB) — деплоится отдельно
docker-compose.uptime.yml    Uptime Kuma мониторинг (status.gendsgn.ru) — отдельный стек, запуск вручную
.forgejo/workflows/        (Forgejo Actions — основной CI/CD после миграции 16.05.2026)
  ├── ci.yml              lint (ruff) + mypy + pytest на PR
  ├── deploy.yml          main → пересборка backend/frontend образов + auto-apply data/sql/*.sql + SSH deploy
  ├── deploy-tradein.yml  tradein-mvp стек (отдельный пайплайн + свой _schema_migrations)
  └── stale-claims.yml    авто-снятие протухших claim-меток в bot-пайплайне
.github/workflows/         (остаточные — только obsidian-стек на GitHub)
  └── deploy-obsidian.yml obsidian-стек (CouchDB compose changes + bootstrap)

---

Аналитика — что доступно

В прод-БД ~50 предметных таблиц:

• domrf_kn_* — DOM.РФ объекты, квартиры, sale_graph, infrastructure, photos (1500+ ЖК Свердл).
• rosreestr_deals — партиционированные ДДУ/ДКП-сделки 2024Q1—2026Q1, ~7M строк, 27 мес истории.
• cad_quarters_geom + cad_buildings — NSPD кадастровые кварталы и здания (cost_value, year_built, floors, geom).
• ekb_districts_geom — PostGIS-полигоны OSM для spatial-join.
• cbr_mortgage_series, yandex_realty_zk, domrf_realization, sber_ddf_metrics — макро/cross-validation.

Калькулятор /analytics/recommend считает квартирографию (5 size-бакетов) с per-bucket эластичностью через регрессию sale_graph, нормировкой на район/класс/конкурентов, кадастр-vs-рынок cross-check, и инверсным режимом «требуемая цена для срока X мес».

Подробное описание схемы БД, helper-views, FK и 27.04 history — в Obsidian vault: domains/analytics/Analytics_Dashboard_Apr27, domains/domrf/events/DomRF_Lazy_Loaded_Apr27_2026, events/Anton_Imported_Apr27_2026, domains/cadastre/Cad_Quarter_Backfill_Apr30. См. также data/sql/*.sql (DDL артефакты).

---

Site Finder v2 «Foresight» — что доступно

Анализ инвестиционного участка по кадастровому номеру: карта (/parcels/by-bbox), запуск анализа (POST /parcels/{cad}/analyze), прогнозный движок (GET /parcels/{cad}/forecast + экспорт). Бизнес-логика — backend/app/services/site_finder/* и backend/app/services/forecasting/*.

• Forecast-движок (forecasting/orchestrator.py): прогноз спроса/предложения (demand_supply_forecast), сценарии (scenarios), оценка уверенности (confidence_engine), доступность (affordability), чувствительность к ставке (rate_sensitivity), продуктовый скоринг и «что строить» (product_scoring, what_to_build). Фронт: Section6Forecast, ScenariosBlock, ForecastChart, ForecastConfidenceBlock, ForecastHorizonsBlock, ForecastProductTzBlock.
• Gate-вердикт: проверка регуляторных ограничений ПЗЗ/ЗОУИТ/ОКН (gate_verdict.py, pzz_loader, zone_regulation, okn_lookup) → баннер вердикта на фронте (GateVerdictBanner).
• ИРД (исходно-разрешительная документация): overlay-lookup + анализ на backend (ird_overlay_lookup.py, ird_analyze.py).
• Соседство/контекст: конкуренты (POST /parcels/{cad}/competitors), лучшие планировки (/best-layouts + PDF), изохроны (/isochrones), POI-скоринг, КРТ/резервирование/network-обременения.

site-finder/ (отдельная папка) — это standalone-пайплайн SF v1: скрипты 01_…12_*.py (загрузка участков, fetch POI, скоринг v1/v2, отчёты) + server.py (Leaflet-UI поверх SQLite-кэша POI). Это исследовательский прекурсор прод-движка в backend/, не путать с прод-API.

---

Trade-In «Мера» — оценка вторички

Отдельный продукт в tradein-mvp/ (standalone стек: FastAPI + Next.js 15 + Postgres + Caddy, свой deploy-tradein.yml). Дефолтный бренд переименован «Trade-In» → «Мера» (white-label-бренды клиентов резолвятся по slug из таблицы brands; URL-пути /trade-in/* и code-идентификаторы сохранены).

Поток: адрес → геокодер (ДаДата) → подбор аналогов в радиусе (PostGIS ST_DWithin) → оценка → PDF-отчёт (WeasyPrint, layout по референсу «Брусника.Обмен»).

• Источники аналогов: скрейперы Avito / Cian / Domclick / Yandex.Realty (backend/app/services/scrapers/*, с детальными парсерами и browser_fetcher).
• Реальные сделки: Rosreestr ДКП-поллинг (rosreestr_poll.py).
• Time-adjust: SberIndex city-level вторичный индекс цен (sber_index.py) — приведение разновременных аналогов/сделок к текущему месяцу.
• Оценка (estimator.py): SQL-агрегация поверх listings + deals, Tukey-фильтр выбросов (1.5×IQR), медиана/Q1/Q3 + confidence; больше не mock.
• API: POST /api/v1/trade-in/estimate, GET …/estimate/{id}, GET …/estimate/{id}/pdf. Multi-tenant: /api/v1/brand/{slug}, RBAC через auth/roles.yaml.

Подробнее — tradein-mvp/README.md и tradein-mvp/DEPLOY.md.

---

Production хостинг

Beget Cloud, Москва, 2 vCPU / 4 GB / 40 GB NVMe. Стоимость ~1 140 ₽/мес сервер + ~17 ₽/мес домен.

Два изолированных стека через docker compose, общая Docker network gendesign_shared:

1. Main стек (docker-compose.prod.yml, project gendesign): postgres + redis + backend (FastAPI) + worker + beat (Celery, Chromium только в worker) + frontend + caddy (auto-TLS Let's Encrypt). Backend/frontend bind на 127.0.0.1 — наружу только Caddy.

2. Obsidian стек (docker-compose.obsidian.yml, project gendesign-obsidian): couchdb:3 — Self-hosted LiveSync remote для multi-device sync vault'а на obsidian.gendsgn.ru. Caddy в main-стеке маршрутизирует через gendesign_shared network.

Split deploy — изменения в main НЕ перезагружают obsidian (и наоборот). Каждый стек со своим workflow.

SSH-only по ключу к non-root пользователю gendesign, fail2ban активен. UFW: 22/80/443.

Forgejo Actions deploys (self-hosted git.gendsgn.ru, мигрировано с GitHub Actions 16.05.2026):

• .forgejo/workflows/ci.yml — на PR: ruff lint + mypy (selective strict) + pytest. Блокирует merge при провале.
• .forgejo/workflows/deploy.yml — main: триггер на backend/**, frontend/**, Caddyfile, docker-compose.prod.yml, data/sql/**. Build backend lean + worker-with-chromium + frontend → push в приватный GHCR → SSH git reset --hard, auto-apply pending data/sql/NN_*.sql через _schema_migrations (idempotent, см. ниже про миграции), sed SENTRY_RELEASE=$IMAGE_TAG в backend/.env.runtime, compose pull && up -d, caddy reload, curl /health.
• .forgejo/workflows/deploy-tradein.yml — tradein-mvp стек (отдельный пайплайн).
• .forgejo/workflows/deploy-obsidian.yml — obsidian: триггер на docker-compose.obsidian.yml, scripts/setup-couchdb.sh, docs/obsidian-livesync.md. Без сборки образов (couchdb:3 с DockerHub), SSH compose up -d + idempotent bootstrap (CORS, DB, лимиты). (до 2026-07-05 ошибочно лежал в .github/workflows/ — там ни разу не исполнился, см. issue #2416; контейнер держался вручную.)

Forgejo Secrets / Variables: DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY, DEPLOY_PORT. Сервер авторизуется в GHCR однократно через PAT с read:packages. COUCHDB_USER/COUCHDB_PASSWORD — в backend/.env.runtime на VPS (не в репе).

Миграции БД — _schema_migrations, не Alembic

Схема развивается через идемпотентные data/sql/NN_*.sql (CREATE … IF NOT EXISTS, guarded DO-блоки). deploy.yml перед compose up прогоняет файлы в лексикографическом порядке, отмечая применённые в таблице-трекере _schema_migrations (применяется ровно один раз каждый). Каталог backend/alembic/versions/ пуст — Alembic в проде не используется. Подробности и граница «raw SQL vs ORM» — docs/Schema_Migrations_vs_Alembic.md.

Триггеры миграции на Yandex Cloud: 3-й платящий пилот / Раунд А / госзаказ (нужен реестр ПО) / БД >10 GB / >50 RPS. На YC ~10–15 тыс ₽/мес.

Операционные грабли

• docker compose restart НЕ перечитывает env_file: — после правки .env всегда up -d --force-recreate --no-deps backend.
• deploy.yml использует git reset --hard origin/main — ручные правки в /opt/gendesign будут стёрты при следующем деплое (.env-файлы переживут — в .gitignore).
• На проде всегда указывать -f docker-compose.prod.yml (без него поднимет dev compose без Caddy).
• caddy reload не сбрасывает retry-queue для ACME. При смене hostname с битым cert-state: docker volume rm gendesign_caddy_data && up -d caddy.

---

Текущий фокус (июнь 2026)

Исходный 12-недельный roadmap (Stage 0 → 2c, апрель–июнь) пройден: скелет/CI/прод, NSPD-скрейпер + per-bucket эластичность, ПКК-данные и скоринг участков — всё ✅. Site Finder вышел из стадии «заглушка» в боевой v2-движок, параллельно запущен Trade-In. Активные направления:

• Site Finder v2 «Foresight» (#944 GG-форсайт) — ИИ-прогноз продуктовой стратегии девелопера: спрос/предложение, сценарии, confidence, продуктовое ТЗ. Движок и фронт-секции отгружены, продолжается доведение точности и покрытия.
• ИРД (#1067) — исходно-разрешительная документация: overlay + analyze на участке.
• Trade-In «Мера» — оценка вторички на реальных данных (скрейперы Avito/Cian/Domclick/Yandex + Rosreestr ДКП + SberIndex), расширение покрытия аналогов и detail-парсинга.
• Generative Design (/concept) — на ранней стадии (skeleton), доводится после стабилизации SF/Trade-In.

Трекаемый backlog и приоритеты — Forgejo Issues с лейблами scope/*, вторичка, status/*. North Star — см. секцию выше.

---

Команда и память проекта

2 фуллстек-разработчика, part-time 20 ч/нед, ритм: 1 синк/нед, daily-async в Telegram, PR-review обязательный, trunk-based. Codegen TS-типов из Pydantic — npm run codegen.

Knowledge base — Obsidian vault

Источник правды — Obsidian vault на obsidian.gendsgn.ru (Self-hosted LiveSync + CouchDB). Markdown-файлы с [[wiki-links]], MOC-страницами, Graph View и тегами. Multi-device sync: desktop / laptop / iPhone / Android. 268 entities мигрированы из исторического JSONL knowledge graph (scripts/migrate_kg_to_obsidian.py), который теперь deprecated.

Структура vault:

• meta/ — гайды, credentials, project meta (Project_GenDesign, TechStack, NorthStar)
• domains/{domrf,cadastre,rosreestr,analytics,ui,api,geo,infra}/ — knowledge по бизнес-доменам
• code/{modules,schemas,patterns,hooks,tasks}/ — code-level entities
• decisions/ — ADR / планы / политики
• fixes/ — bug-журналы
• sessions/, sprints/, events/ — chronological logs
• research/, sources/, feedback/, github/, limitations/ — прочее
• old/ — архив legacy paths (redirect-stubs)

Подключение коллеги — гайды в самом vault'е:

• meta/01_connect_devices.md — установка Obsidian + LiveSync на любую платформу (через Setup URI или 4 поля)
• meta/03_obsidian_plugins.md — какие плагины ставить (Local REST API, Templater, Dataview)
• meta/04_mcp_obsidian_setup.md — подключение Claude к vault через MCP

Legacy: старый knowledge graph JSONL (memory/memory-gendesign.jsonl) — снапшот на момент 2026-05-11, не обновляется. Все новые факты пишутся в Obsidian.

Где вести задачи — Forgejo Issues vs Obsidian

Используем оба, но с чёткой ролью (трекер мигрирован с GitHub на self-hosted Forgejo 16.05.2026):

	Forgejo Issues (git.gendsgn.ru)	Obsidian vault
Что сюда	Bug + Feature + Refactor — всё с связью с кодом / PR	Knowledge: research, ADR, planning, draft-ideas
Lifecycle	Open → Assigned → PR → Merged → Closed	Append-only журнал решений и контекста
Уведомления	Forgejo email/webhook	Никаких (читаешь когда сам пришёл)
Поиск	Forgejo search + labels + milestones	BM25 + tags + Graph + MOC
Видимость	Команде в reviewer'ах	Всем у кого есть vault password
Сроки	Milestones (12-week roadmap)	Frontmatter date:, status:, due:

Правило перехода: Obsidian fixes/Bug_X.md со status: OPEN → когда требует PR — создаём Forgejo Issue, ссылку прописываем во frontmatter .md (issue: 42). Bug-исследование живёт в vault'е, action item — в Issues.

Что куда:

• Bug_* (vault) + Forgejo Issue с тегом bug → обнаружен баг, фикс через PR
• decisions/* (vault) — ADR, не нужен Issue
• research/* (vault) — анализ источников, конкуренты, метрики
• sessions/* (vault) — журналы рабочих сессий
• Forgejo Issues feat/* — фичи + PR на 1+ files, видимые в milestones

Claude Code subagents (.claude/agents/)

Разработка ведётся через Claude Code с 6 кастомными subagent'ами (path-scoped, со своими MCP-«учётками»: прод-PostgreSQL, Obsidian vault, Forgejo, GlitchTip). Полные правила — .claude/rules/ + корневой CLAUDE.md.

Agent	Scope / зона ответственности
tech-analyst	Нечёткая / cross-domain задача → план перед кодом
backend-engineer	backend/app/** — FastAPI, Celery, scrapers, services
frontend-engineer	frontend/src/** — Next.js 15, React 19, hooks
database-expert	data/sql/**.sql, схема, EXPLAIN ANALYZE, прод-БД через MCP
devops-engineer	docker-compose*.yml, Caddyfile, .forgejo/workflows/**
code-reviewer	Pre-push lint: security, correctness, conventions

Workflow: тривиально (typo, 1-line) → main session; single-domain → профильный worker; cross-domain → tech-analyst сначала. Worker → code-reviewer → коммит → push → PR в Forgejo. Branch + PR обязательны, никаких direct push в main.

Автономный bot-loop. Помимо ручных subagent'ов есть набор автономных персон (.claude/agents/auto-*.md, status draft), которые крутятся каждая в отдельном Claude Code-окне на /loop и двигают задачи через лейблы status/* (ready → wip → review → qa → done):

• auto-analyst — декомпозирует work-items из vault/feedback в actionable Forgejo issues.
• auto-backend / auto-frontend — claim issue scope/* → ветка + код + push + PR (Refs #N, не Closes).
• auto-code-reviewer — читает diff, выносит verdict, мерджит при APPROVE (merge-authority).
• auto-qa-tester — Playwright golden-path по status/qa, закрывает issue на status/done.
• auto-resolver — снимает блокеры needs-human, используя capabilities, которых нет у headless-ботов (dev-IP, куки, SSH на прод, прямой доступ к БД).

stale-claims.yml авто-снимает протухшие claim-метки. Контракт claim/state-transition — .claude/agents/_autonomous_pickup.md.

---

Полезные ссылки

🌐 Production	https://gendsgn.ru/
🩺 Health	https://gendsgn.ru/health
📚 OpenAPI	Swagger UI · https://gendsgn.ru/openapi.json (за Caddy basic_auth)
🗂 Knowledge vault	https://obsidian.gendsgn.ru (требуется Obsidian + Self-hosted LiveSync, см. vault meta/01_connect_devices.md)
🧰 Git / CI	git.gendsgn.ru (Forgejo) · CLAUDE.md — правила разработки
Backlog	Issues · Milestones
Деплой	Forgejo Actions · GHCR пакеты
Мониторинг	Sentry
Инфра	Beget VPS cp.beget.com/cloud/... · DNS

Стратегические документы (снимки): docs/MVP_Goals_Python.md, docs/Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md, docs/obsidian-livesync.md. При расхождении с vault'ом — доверяем vault'у.