247 lines
13 KiB
Markdown
247 lines
13 KiB
Markdown
# Generative Design + Site Finder
|
||
|
||
Две продуктовые линии в одной воронке: **Site Finder** (AI-подбор инвестиционных земельных участков) + **Generative Design** (автоматическая генерация концепций застройки) для девелоперов РФ.
|
||
|
||
## North Star
|
||
|
||
К концу месяца 3: **3 платящих пилота** (≥30 тыс. ₽/мес каждый) + заявка в реестр российского ПО → право на Раунд А (20–25 млн ₽).
|
||
|
||
Acceptance criteria разбиты на 3 блока (функционально / бизнесово / технически). Правило перехода: 3/3 → Раунд А; 2/3 → продление Фазы 0 на 1–2 мес.; 1/3 или меньше → стоп проекта.
|
||
|
||
---
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
gendesign/
|
||
├── backend/ # Python 3.12 / FastAPI / PostGIS
|
||
│ ├── pyproject.toml # uv-проект, ruff/mypy/pytest конфиги
|
||
│ ├── Dockerfile # с системными deps под Geo + WeasyPrint
|
||
│ ├── .env.example
|
||
│ ├── app/
|
||
│ │ ├── main.py # FastAPI + Sentry + /health
|
||
│ │ ├── core/ # config (Pydantic Settings), db (SQLAlchemy)
|
||
│ │ ├── api/v1/ # concepts.py, parcels.py
|
||
│ │ ├── schemas/ # Pydantic-контракты для openapi-typescript
|
||
│ │ ├── services/
|
||
│ │ │ ├── generative/ # Stage 1: geometry, teap, financial
|
||
│ │ │ ├── site_finder/ # Stage 2: parser, scorer, filters
|
||
│ │ │ └── exporters/ # Stage 1c: pdf, excel, dxf
|
||
│ │ ├── models/parcel.py # GeoAlchemy2 + PostGIS
|
||
│ │ └── workers/celery_app.py # Stage 2a: daily PKK sync
|
||
│ └── tests/
|
||
├── frontend/ # Next.js 15 / React 19 / TypeScript / Leaflet
|
||
│ ├── package.json # включая `npm run codegen` → openapi-typescript
|
||
│ ├── Dockerfile # multi-stage, output: standalone
|
||
│ └── src/app/
|
||
│ ├── page.tsx # / — главная
|
||
│ ├── concept/page.tsx # /concept — Generative Design
|
||
│ └── site-finder/page.tsx # /site-finder — Site Finder
|
||
├── memory/
|
||
│ └── memory-gendesign.jsonl # хард-линк на C:\mcp\.aim — общий граф памяти
|
||
├── docs/ # стратегические документы (бизнес-план, цели MVP)
|
||
├── docker-compose.yml # dev: Postgres + Redis + backend + frontend
|
||
├── docker-compose.prod.yml # prod: образы из реестра + Caddy reverse-proxy
|
||
├── Caddyfile # авто-TLS Let's Encrypt
|
||
├── Makefile # make up / down / test / codegen / migrate
|
||
└── .github/workflows/
|
||
├── ci.yml # ruff + mypy(core) + pytest + frontend build
|
||
└── deploy.yml # build → push в реестр → ssh deploy на VM
|
||
```
|
||
|
||
---
|
||
|
||
## Технический стек (v2.2)
|
||
|
||
**Backend:** Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2, Alembic, Celery + Redis, httpx
|
||
**Geo:** Shapely 2.0, GeoPandas, Pyproj (WGS84 ↔ МСК-66 для Свердловской обл.)
|
||
**ML:** scikit-learn (XGBoost — отложен на Фазу 1, в Discovery эвристики)
|
||
**БД:** PostgreSQL 16 + PostGIS 3.4, Redis 7
|
||
**Frontend:** Next.js 15, React 19, TypeScript 5, Tailwind 4, TanStack Query, Leaflet (Mapbox в Stage 2b)
|
||
**Экспорт:** WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel)
|
||
**Dev:** uv, ruff, mypy (strict только на core), pytest
|
||
|
||
---
|
||
|
||
## Команда и порядок работы
|
||
|
||
**2 фуллстек-разработчика, оба part-time 20 ч/нед** — итого ~40 person-hours/нед, эффективных с координацией ~33.
|
||
|
||
**Ритм:**
|
||
- 1 синк/нед (30 мин, понедельник)
|
||
- daily-async в Telegram
|
||
- PR review обязательный
|
||
- Trunk-based: feature ветки ≤ 3 дней
|
||
- Codegen TS-типов из Pydantic (`npm run codegen`) — без этого 2 фуллстека плодят расхождения в API-контракте
|
||
|
||
**Порядок:** строго последовательный — Generative полностью, потом Site Finder.
|
||
|
||
---
|
||
|
||
## Этапы MVP (12 недель)
|
||
|
||
### Stage 0 — Скелет (нед. 1)
|
||
Монорепо backend+frontend, Docker с PostGIS+Redis, FastAPI hello, Next.js hello, openapi-typescript codegen, GitHub Actions CI, ruff + mypy(core) + pytest. Без JWT (single-tenant + `X-Demo-User` до Раунда А).
|
||
|
||
### Stage 1 — Generative MVP (нед. 2–7)
|
||
- **1a (нед. 2–3):** геометрия + API-контракт. Shapely-сервис (отступы, сетка), Pydantic-схемы, `POST /api/v1/concepts` с заглушкой. Фронт: страница `/concept`, Leaflet, импорт GeoJSON, форма параметров, 3 варианта в табах.
|
||
- **1b (нед. 4–5):** алгоритм размещения. Жадное заполнение, 3 стратегии (max площадь / max инсоляция / balanced), STRtree для коллизий. Цель ≤10 сек, fallback 15 сек.
|
||
- **1c (нед. 6–7):** ТЭП + финмодель + экспорты. WeasyPrint PDF, ezdxf, openpyxl. UI кнопок скачивания.
|
||
|
||
**Acceptance Stage 1 (конец нед. 7):** полигон → 3 варианта → ТЭП + финмодель → PDF/Excel/DXF. Это уже **продаваемый артефакт** — можно показывать на встречах с месяца 2.
|
||
|
||
### Stage 2 — Site Finder MVP (нед. 8–12)
|
||
- **2a (нед. 8–9):** data pipeline. Парсер ПКК Rosreestr (httpx async, retries), модель `Parcel` с GeoAlchemy2, ≥1000 участков Екатеринбурга. Overpass API для POI, ДОМ.РФ/ЦИАН для цен м², кеш в Redis.
|
||
- **2b (нед. 10–11):** скоринг + API + UI. 3 критерия (расстояние до центра, плотность POI в 1 км, цена района), `POST /api/v1/parcels/search`. Карта с градацией по рейтингу, фильтры, карточка.
|
||
- **2c (нед. 12):** интеграция + полировка. Кнопка «Обсчитать концепцию», демо-наполнение 50 участков, бэкапы БД, подача в реестр ПО.
|
||
|
||
### Что урезано из v2.2 из-за part-time × 2
|
||
- XGBoost-скоринг → Фаза 1 (с реальными данными от пилотов)
|
||
- JWT-auth с refresh → перед Раундом А
|
||
- mypy --strict — только на core (`generative/*`, `site_finder/scorer.py`)
|
||
- Время генерации ≤ 15 сек как fallback (а не 10 сек)
|
||
|
||
---
|
||
|
||
## Quick start (локально)
|
||
|
||
**Требования:** Docker Desktop, Node.js 20+, [uv](https://docs.astral.sh/uv/) (для backend dev вне Docker).
|
||
|
||
```bash
|
||
# 1. Скопировать env-файлы
|
||
cp backend/.env.example backend/.env
|
||
cp frontend/.env.example frontend/.env
|
||
|
||
# 2. Запустить всё
|
||
docker compose up -d --build
|
||
# или: make up
|
||
|
||
# 3. Проверить
|
||
curl http://localhost:8000/health
|
||
# → {"status":"ok","environment":"dev"}
|
||
|
||
# Frontend → http://localhost:3000
|
||
# Swagger docs → http://localhost:8000/docs
|
||
```
|
||
|
||
**Полезное:**
|
||
```bash
|
||
make logs # tail логов всех сервисов
|
||
make backend-shell # bash внутри backend контейнера
|
||
make migrate # alembic upgrade head
|
||
make test # pytest
|
||
make lint # ruff check
|
||
make typecheck # mypy на core
|
||
make codegen # обновить TS-типы из OpenAPI
|
||
```
|
||
|
||
---
|
||
|
||
## Хостинг (production)
|
||
|
||
### Discovery MVP (мес. 1–3): минимальный режим
|
||
|
||
**1× VPS** на Selectel / Timeweb / Beget (2 vCPU / 4 GB / 60 GB SSD), всё в Docker Compose:
|
||
|
||
| Компонент | Сервис |
|
||
|---|---|
|
||
| App | backend + frontend (образы из GHCR) |
|
||
| БД | Postgres 16 + PostGIS 3.4 (в том же compose) |
|
||
| Кэш/очереди | Redis 7 |
|
||
| TLS | Caddy с Let's Encrypt автоматически |
|
||
| Бэкапы | cron pg_dump → Yandex Object Storage (free tier 1 GB) |
|
||
|
||
**Стоимость:** ~1300–2000 ₽/мес (VPS) + ~17 ₽/мес (домен .ru) = **~1500–2000 ₽/мес**.
|
||
|
||
⚠️ **Критично:** настроить ежесуточный pg_dump в первую неделю. Без бэкапа = смерть проекта при первом сбое VM.
|
||
|
||
### Триггеры миграции на Yandex Cloud
|
||
|
||
Переезжаем на YC Managed PostgreSQL + Compute + Container Registry, когда:
|
||
- Подписан 3-й платящий пилот (~ конец мес. 3)
|
||
- Закрылся Раунд А
|
||
- Идёт переговор с госзаказчиком (нужен реестр ПО + солидная инфра)
|
||
- БД > 10 GB или появилось > 50 RPS
|
||
|
||
Стоимость production на YC: ~10–15 тыс ₽/мес.
|
||
|
||
### GitHub Actions deploy
|
||
|
||
Workflow `.github/workflows/deploy.yml` собирает образы и через SSH деплоит на VM:
|
||
1. Build backend + frontend Docker образов
|
||
2. Push в реестр (GHCR для Discovery, YCR после миграции)
|
||
3. SSH на VM → `docker compose pull && up -d`
|
||
|
||
**Secrets** (GitHub → Settings → Secrets and variables → Actions):
|
||
- `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_PORT` (опц.)
|
||
- Для GHCR — `GITHUB_TOKEN` встроенный, отдельный secret не нужен
|
||
- Для YC (после миграции) — `YC_SA_JSON_CREDENTIALS`, `YC_REGISTRY_ID`
|
||
|
||
---
|
||
|
||
## Память проекта (knowledge graph)
|
||
|
||
Все решения, факты, риски, KPI, протоколы валидации хранятся **только в графе памяти**, не в .md-документах. Это решает проблему расхождения версий между документами.
|
||
|
||
**Как устроено:**
|
||
- MCP-сервер `mcp-knowledge-graph` пишет в `C:\mcp\.aim\memory-gendesign.jsonl`
|
||
- Этот файл — **хард-линк** на `<repo>/memory/memory-gendesign.jsonl`
|
||
- Изменения попадают в git автоматически
|
||
- Синхронизация между коллегами — через `git pull` / `git push`
|
||
|
||
**Правило проекта (`Feedback_MemoryFirst`):**
|
||
- Все факты и решения сохраняем в граф (`context: "gendesign"`)
|
||
- `.md` / `.docx` / `.pdf` Claude **не создаёт сам** — только по явному запросу
|
||
- Источник правды = граф, документы = производные срезы
|
||
|
||
**Рабочий цикл:**
|
||
```bash
|
||
git pull # перед началом работы
|
||
# ... сессия с Claude ...
|
||
git add memory/memory-gendesign.jsonl
|
||
git commit -m "Memory: <что добавили>"
|
||
git push
|
||
```
|
||
|
||
Конфликты в `.jsonl` обычно простые (файл построчный): `git pull --rebase`, оставить **обе** стороны, `git rebase --continue`.
|
||
|
||
### Подключение коллеги
|
||
|
||
Краткая инструкция для нового участника команды (полная версия — у владельца репо):
|
||
|
||
1. Установить Claude Desktop, Node.js 20+, Git
|
||
2. Клонировать репо в `C:\Users\<имя>\source\repos\gendesign`
|
||
3. `mkdir C:\mcp\.aim`
|
||
4. Создать хард-линк:
|
||
```powershell
|
||
New-Item -ItemType HardLink `
|
||
-Path C:\mcp\.aim\memory-gendesign.jsonl `
|
||
-Value $PWD\memory\memory-gendesign.jsonl
|
||
```
|
||
5. Добавить в `%APPDATA%\Claude\claude_desktop_config.json`:
|
||
```json
|
||
"knowledge-graph": {
|
||
"command": "npx",
|
||
"args": ["-y", "mcp-knowledge-graph", "--memory-path", "C:\\mcp\\.aim"]
|
||
}
|
||
```
|
||
6. Перезапустить Claude Desktop полностью (через трей)
|
||
7. Проверить: «Покажи память контекста gendesign»
|
||
|
||
---
|
||
|
||
## Документы стратегии
|
||
|
||
В `docs/`:
|
||
- `MVP_Goals_Python.md` — цели Discovery MVP, Python-стек (v2.2, апрель 2026)
|
||
- `Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md` — бизнес-план
|
||
|
||
⚠️ Эти документы — **снимок состояния на момент написания**. Свежее состояние стратегии — в графе памяти. При расхождении доверяем графу.
|
||
|
||
---
|
||
|
||
## Полезные ссылки
|
||
|
||
- **Репо:** https://github.com/lekss361/-gendesign
|
||
- **Целевой регион Discovery:** Свердловская обл. (Екатеринбург, ПЗЗ, МСК-66)
|
||
- **Конкуренты:** rTIM (только концепт-стадия, нет site-selection), TestFit (нет РФ-данных)
|