bb28f77f66
- Применена миграция 63_schema_nspd_runs.sql вручную через MCP
(тянут init-скрипты только при первичной инициализации БД).
Чинит 500 на /api/v1/admin/scrape/nspd/{runs,logs,coverage}.
- README: 724→148 строк. Выкинута операционная история апреля,
443-sweep инструкции (теперь через admin UI), таблица 43 таблиц
(есть в графе памяти), step-by-step onboarding (есть в #11).
- 5 новых issues по аналитике: #17 velocity-anomaly, #18 ekb_districts
median refresh (bug), #19 competitor-360, #20 mortgage-rate
sensitivity, #21 cad_buildings фильтры в Site Finder.
- Закрыт #4 (Sentry release tracking — реализовано в 25b7303).
148 lines
11 KiB
Markdown
148 lines
11 KiB
Markdown
# Generative Design + Site Finder
|
||
|
||
Две продуктовые линии в одной воронке: **Site Finder** (AI-подбор инвестиционных земельных участков) + **Generative Design** (автоматическая генерация концепций застройки) для девелоперов РФ. Целевой регион Discovery — Свердловская обл. (ЕКБ, ПЗЗ, МСК-66).
|
||
|
||
## North Star
|
||
|
||
К концу месяца 3: **3 платящих пилота** (≥30 тыс. ₽/мес каждый) + заявка в реестр российского ПО → право на Раунд А (20–25 млн ₽).
|
||
|
||
---
|
||
|
||
## Текущий статус (апрель 2026)
|
||
|
||
**Live:** [https://gendsgn.ru/](https://gendsgn.ru/) — HTTP/2+HTTP/3, валидный TLS, [/health](https://gendsgn.ru/health) `{"status":"ok"}`. Полный CI/CD: GitHub Actions → GHCR → SSH-deploy на Beget VPS. Sentry активен (release tracking привязан к git-sha).
|
||
|
||
| Слой | Статус |
|
||
|---|---|
|
||
| Аналитический калькулятор `/analytics/recommend` (Tier 3 per-bucket эластичность, кадастр vs рынок) | ✅ |
|
||
| DOM.РФ kn-API скрейпер (442 строящихся ЖК Свердл, sale_graph + infra + photos) | ✅ Celery beat + admin UI |
|
||
| Rosreestr CSV-сделки 2024Q1—2026Q1 (9 квартирных партиций, 7M строк) | ✅ |
|
||
| NSPD кадастровые кварталы + здания (709 cad-кварталов, 10 590 cad_buildings ЕКБ) | ✅ Celery beat + admin UI |
|
||
| OSM ekb_districts_geom (PostGIS-полигоны 8 районов ЕКБ) | ✅ |
|
||
| Concept page (`/concept`) — Stage 1 Generative | 🟡 skeleton |
|
||
| Site Finder (`/site-finder`) — Stage 2 | 🔴 заглушка |
|
||
|
||
**Подробности и текущий backlog** — [Issues](https://github.com/lekss361/-gendesign/issues), milestones по этапам.
|
||
|
||
---
|
||
|
||
## Quick start (локально)
|
||
|
||
**Требования:** Docker Desktop, Node.js 20+, [uv](https://docs.astral.sh/uv/) для backend dev.
|
||
|
||
```bash
|
||
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), workers (Celery)
|
||
frontend/ Next.js app router (analytics, admin, concept, site-finder)
|
||
data/sql/ ETL артефакты — миграции схемы, загрузчики rosreestr/anton/nspd
|
||
ops/ backup.sh + deploy скрипты
|
||
docs/ стратегия (снимок) — актуальное состояние в графе памяти
|
||
memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph)
|
||
.github/workflows/ deploy.yml (build → GHCR → SSH-deploy)
|
||
```
|
||
|
||
---
|
||
|
||
## Аналитика — что доступно
|
||
|
||
В прод-БД ~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 — в графе памяти, сущности `Analytics_Dashboard_Apr27`, `DomRF_Lazy_Loaded_Apr27_2026`, `Anton_Imported_Apr27_2026`, `NSPD_Scrape_Complete_Apr30`. См. также `data/sql/*.sql` (DDL артефакты).
|
||
|
||
---
|
||
|
||
## Production хостинг
|
||
|
||
**Beget Cloud, Москва, 2 vCPU / 4 GB / 40 GB NVMe.** Стоимость ~1 140 ₽/мес сервер + ~17 ₽/мес домен.
|
||
|
||
5 контейнеров через `docker-compose.prod.yml`: `postgres` + `redis` + `backend` (FastAPI) + `worker` + `beat` (Celery, Chromium только в worker) + `frontend` + `caddy` (auto-TLS Let's Encrypt). Backend/frontend bind на `127.0.0.1` — наружу только Caddy.
|
||
|
||
**SSH-only по ключу к non-root пользователю `gendesign`**, fail2ban активен. UFW: 22/80/443.
|
||
|
||
**GitHub Actions deploy** ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml)):
|
||
1. Build обоих образов (backend lean + worker-with-chromium + frontend)
|
||
2. Push в приватный GHCR
|
||
3. SSH `git pull`, пишет `SENTRY_RELEASE=$IMAGE_TAG` в `backend/.env.runtime`, `compose pull && up -d`, `caddy reload`, `curl /health`
|
||
|
||
**GitHub Secrets:** `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_PORT`. Сервер авторизуется в GHCR однократно через PAT с `read:packages`.
|
||
|
||
**Триггеры миграции на 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`.
|
||
|
||
---
|
||
|
||
## Roadmap (12 недель)
|
||
|
||
| Stage | Сроки | Что | Acceptance |
|
||
|---|---|---|---|
|
||
| **0** ✅ | нед. 1 | Скелет монорепо, CI, прод | curl /health = ok |
|
||
| **Sprint 1** ✅ | конец апр 2026 | NSPD-скрейпер + per-bucket эластичность + кадастр cross-check + Sentry release tracking | recommend_mix Tier 3 в проде |
|
||
| **1a** | нед. 2–3 | Shapely-сервис, отступы, API-контракт `/concept` ([#5](https://github.com/lekss361/-gendesign/issues/5)) | GeoJSON → 3 заглушки |
|
||
| **1b** | нед. 4–5 | Greedy-алгоритм, 3 стратегии, STRtree ([#12](https://github.com/lekss361/-gendesign/issues/12)) | 3 варианта ≤15с на 1 га |
|
||
| **1c** | нед. 6–7 | ТЭП + финмодель + PDF/Excel/DXF ([#6](https://github.com/lekss361/-gendesign/issues/6)) | Продаваемый артефакт |
|
||
| **2a** | нед. 8–9 | ПКК-парсер + sales_tracker ([#7](https://github.com/lekss361/-gendesign/issues/7)) | ≥1000 участков ЕКБ |
|
||
| **2b** | нед. 10–11 | Скоринг + API + UI Site Finder ([#8](https://github.com/lekss361/-gendesign/issues/8)) | Карта с цветовой градацией |
|
||
| **2c** | нед. 12 | Site Finder ↔ Generative + реестр ПО ([#9](https://github.com/lekss361/-gendesign/issues/9)) | 3 платящих пилота |
|
||
|
||
Аналитический backlog: [#17](https://github.com/lekss361/-gendesign/issues/17) velocity-anomaly, [#18](https://github.com/lekss361/-gendesign/issues/18) ekb_districts median refresh, [#19](https://github.com/lekss361/-gendesign/issues/19) competitor-360, [#20](https://github.com/lekss361/-gendesign/issues/20) mortgage-rate sensitivity, [#21](https://github.com/lekss361/-gendesign/issues/21) cad_buildings filters в Site Finder.
|
||
|
||
---
|
||
|
||
## Команда и память проекта
|
||
|
||
**2 фуллстек-разработчика, part-time 20 ч/нед**, ритм: 1 синк/нед, daily-async в Telegram, PR-review обязательный, trunk-based. Codegen TS-типов из Pydantic — `npm run codegen`.
|
||
|
||
Все решения, факты, KPI, протоколы валидации хранятся в **графе памяти** (`memory/memory-gendesign.jsonl`, hardlink на `C:\mcp\.aim\memory-gendesign.jsonl`), не в .md-документах. Правило (`Feedback_MemoryFirst`): источник правды = граф, документы = снимки. Синхронизация между коллегами — через git pull/push.
|
||
|
||
**Подключение коллеги к knowledge-graph** ([#11](https://github.com/lekss361/-gendesign/issues/11)) — пошаговая инструкция в issue.
|
||
|
||
---
|
||
|
||
## Полезные ссылки
|
||
|
||
| | |
|
||
|---|---|
|
||
| 🌐 Production | https://gendsgn.ru/ |
|
||
| 🩺 Health | https://gendsgn.ru/health |
|
||
| 📚 OpenAPI | https://gendsgn.ru/openapi.json · [Swagger UI](https://gendsgn.ru/docs) |
|
||
| Backlog | [Issues](https://github.com/lekss361/-gendesign/issues) · [Milestones](https://github.com/lekss361/-gendesign/milestones) |
|
||
| Деплой | [GitHub Actions](https://github.com/lekss361/-gendesign/actions) · [GHCR пакеты](https://github.com/lekss361?tab=packages) |
|
||
| Мониторинг | [Sentry](https://qqq-5y.sentry.io/insights/projects/gendesign-backend/) |
|
||
| Инфра | Beget VPS [`cp.beget.com/cloud/...`](https://cp.beget.com/cloud/servers/jolly-yakov-3) · [DNS](https://cp.beget.com/dns/14193206) |
|
||
|
||
**Стратегические документы (снимки):** [`docs/MVP_Goals_Python.md`](docs/MVP_Goals_Python.md), [`docs/Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md`](docs/). При расхождении с графом — доверяем графу.
|