gendesign/docs/MVP_Goals_Python.md

# Цели Discovery MVP — Python-стек

**Версия:** 2.2
**Дата:** апрель 2026
**Статус:** Discovery MVP, месяцы 1–3
**Изменение vs v2.1:** переход с .NET на Python для backend, TypeScript для frontend

---

## 1. North Star Metric

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

Этот критерий не зависит от стека и остаётся неизменным.

---

## 2. Технический стек MVP

### Backend
- **Язык:** Python 3.12
- **Web-фреймворк:** FastAPI 0.115+
- **ORM:** SQLAlchemy 2.0 + GeoAlchemy2 (для PostGIS)
- **Миграции:** Alembic
- **Валидация:** Pydantic v2
- **Background tasks:** Celery + Redis (или RQ для простоты)
- **HTTP-клиент:** httpx (async)

### Геометрия и геоданные
- **Shapely 2.0** — основная геометрия (полигоны, отступы, пересечения)
- **GeoPandas 1.0** — работа с табличными геоданными
- **Pyproj** — преобразования систем координат (WGS84 ↔ UTM ↔ МСК-66 для Свердловской обл.)
- **Rasterio** — если будем работать с растровыми данными (DEM, спутник)

### ML
- **XGBoost** — основной алгоритм скоринга участков
- **scikit-learn** — препроцессинг, метрики, простые модели
- **pandas** — обработка табличных данных
- **NumPy** — численные расчёты

### Экспорт документов
- **ReportLab** или **WeasyPrint** — PDF-отчёты (WeasyPrint удобнее для HTML-вёрстки)
- **ezdxf** — экспорт в DXF для архитекторов
- **openpyxl** — экспорт в Excel

### База данных
- **PostgreSQL 16** + **PostGIS 3.4** — основная БД
- **Redis 7** — кэш и очереди

### Frontend
- **Next.js 15** + **React 19** + **TypeScript 5**
- **Tailwind CSS 4** — стили
- **shadcn/ui** — базовые компоненты
- **TanStack Query** — работа с API
- **Mapbox GL JS** или **Leaflet + OSM** — карты

### Инфраструктура
- **Yandex Cloud** или **VK Cloud** (российские)
- **Docker + Docker Compose** для разработки
- **GitHub Actions** для CI/CD
- **Sentry** для мониторинга ошибок

### Dev tools
- **uv** или **poetry** — менеджер зависимостей (uv быстрее)
- **ruff** — линтер + форматтер (заменяет black + flake8 + isort)
- **mypy** — статическая типизация
- **pytest** — тесты

---

## 3. Цели по модулю A: Site Finder

### Функциональные цели (Discovery MVP)

**Загрузка данных**
- Парсер Росреестра ПКК для Свердловской области
- Сохранение ≥ 1000 участков в PostgreSQL/PostGIS
- Атрибуты: кадастровый номер, ВРИ, площадь, границы (геометрия), адрес
- Скрипт ежесуточной синхронизации (Celery beat)

**Фильтрация**
- 3 базовых фильтра: ВРИ, площадь (от-до), регион/город
- Геопространственный фильтр: участки внутри произвольно нарисованного полигона
- Текстовый поиск по адресу/кадастровому номеру

**Скоринг**
- 3 критерия в Discovery: расстояние до центра города, наличие инфраструктуры в радиусе 1 км (POI из OSM), средняя цена жилья в районе (ДОМ.РФ)
- Веса критериев настраиваемые пользователем
- Итоговый рейтинг 0–100 с разбивкой по компонентам

**Отображение**
- Карта (Mapbox/Leaflet) с участками-полигонами
- Цветовая градация по рейтингу
- Табличный список с сортировкой по любому параметру
- Детальная карточка участка с обоснованием рейтинга

**Интеграция с Generative Design**
- Кнопка «Обсчитать концепцию» в детальной карточке
- Передача геометрии участка через внутренний API в модуль B
- Возврат результатов в карточку

### Что НЕ делаем в Discovery MVP
- API ЕГРН с собственниками (требует платежей и юридического оформления — отложено на Фазу 1)
- Изохроны Яндекс.Карт (хорошо бы иметь, но не критично — Фаза 1)
- Скоринг по 15+ параметрам — Фаза 1
- Множественные регионы (только Свердловская обл.) — Фаза 1
- Алертинг на новые подходящие участки — Фаза 2

---

## 4. Цели по модулю B: Generative Design (пятно застройки)

### Функциональные цели (Discovery MVP)

**Вход**
- Полигон участка (ручная отрисовка на карте или передача из Site Finder)
- Параметры пользователя: класс жилья (эконом/комфорт/бизнес), целевая этажность, тип застройки (точечная/средне-этажная/многоэтажная)
- Региональные нормативы (для Discovery — Свердловская обл., ПЗЗ Екатеринбурга)

**Алгоритм генерации**
- Расчёт нормативных отступов от границ участка (через Shapely buffer)
- Размещение прямоугольных корпусов МКД методом «жадного заполнения»: подбор сетки положений, проверка отступов между корпусами и от границ
- 3 варианта: «максимум площади», «максимум инсоляции дворов», «оптимальный микс»
- Время генерации одного варианта ≤ 10 секунд

**Расчёт ТЭП**
- Площадь застройки, общая площадь корпусов
- Жилая площадь по типам квартир (1/2/3-комн в задаваемых пропорциях)
- Количество квартир, средняя площадь
- КЭП (коэффициент использования территории), плотность застройки
- Площадь придомовой территории, парковка (упрощённо: норматив × количество квартир)

**Финансовая модель**
- Выручка: жилая площадь × средняя цена м² по району (из ДОМ.РФ)
- Себестоимость: квадратный метр × норматив (из ФАУ «Главгосэкспертиза»)
- Стоимость земли (вход параметром)
- Валовая маржа, чистая прибыль (упрощённая модель без налогов)
- Базовый IRR (без дисконтирования cash flow по периодам — это в Фазе 1)

**Экспорт**
- PDF-отчёт с тремя вариантами, графиками, ТЭП и финмоделью (WeasyPrint)
- Excel с расчётами (openpyxl)
- DXF упрощённой схемы участка (ezdxf) — для передачи архитектору

### Что НЕ делаем в Discovery MVP
- Расчёт инсоляции по СП 52.13330 — Фаза 1, месяцы 7–9
- Произвольная форма корпусов (только прямоугольники) — Фаза 1
- Парковка по детальному нормативу — Фаза 1
- УДС (улично-дорожная сеть) — Фаза 1
- Социнфраструктура (школы, сады, поликлиники) — Фаза 1
- 3D-визуализация (Three.js) — Фаза 2 (год 2)
- Квартирография (планировки квартир внутри корпусов) — Фаза 2
- Фотореалистичный рендер — Год 2+

---

## 5. Цели по продажам и валидации

### Месяц 1
- 50 целевых клиентов в CRM (можно использовать Notion/AmoCRM/HubSpot Free)
- 5 cold-outreach писем отправлено
- 3 встречи назначено
- ООО зарегистрировано, расчётный счёт открыт
- Прототип Site Finder работает локально с 1000 участков

### Месяц 2
- 15 встреч кумулятивно проведено
- 2 LOI (Letters of Intent) подписано
- 1 платящий пилот подписан (≥ 30 тыс. ₽/мес)
- Демо прототипа на реальных участках клиентов
- Первая статья в профильном медиа (DigitalDeveloper, vc.ru, Bisnow Russia)

### Месяц 3
- 20+ встреч кумулятивно
- 3 платящих пилота
- 7+ LOI
- 1 региональная администрация в активных переговорах
- Заявка в реестр российского ПО подана
- Подготовлен инвестиционный deck для Раунда А (12 слайдов)
- Финансовая модель в Excel на 5 лет
- Data room для инвесторов

---

## 6. Технические цели MVP

### Качество кода
- Все публичные API эндпоинты типизированы (Pydantic)
- Покрытие тестами ключевой бизнес-логики ≥ 60%
- Линтер ruff проходит без ошибок
- mypy --strict проходит для core-модулей

### Производительность
- Time to First Value ≤ 10 минут (от регистрации до первого обсчёта)
- Загрузка участков по фильтру ≤ 2 секунд
- Генерация одного варианта концепции ≤ 10 секунд
- Генерация PDF-отчёта ≤ 5 секунд

### Надёжность
- 99% uptime в рабочие часы (для демо клиентам)
- Все ошибки в Sentry
- Бэкап БД ежедневно
- Recovery time ≤ 2 часов

### Безопасность
- Все данные пользователей шифруются at rest (PostgreSQL TDE или приложением)
- HTTPS обязательно
- API Rate limiting
- JWT-авторизация с refresh-токенами
- Логирование всех доступов к чувствительным данным (требование под реестр ПО)

---

## 7. Структура репозитория (предлагаемая)

```
project-root/
├── backend/
│   ├── app/
│   │   ├── main.py                 # FastAPI entrypoint
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── parcels.py      # Site Finder endpoints
│   │   │   │   ├── concepts.py     # Generative Design endpoints
│   │   │   │   └── auth.py
│   │   ├── core/
│   │   │   ├── config.py           # Pydantic Settings
│   │   │   ├── security.py         # JWT, hashing
│   │   │   └── db.py               # SQLAlchemy session
│   │   ├── models/                 # SQLAlchemy ORM
│   │   ├── schemas/                # Pydantic schemas
│   │   ├── services/
│   │   │   ├── site_finder/
│   │   │   │   ├── parser.py       # Росреестр, ФИАС
│   │   │   │   ├── scorer.py       # XGBoost скоринг
│   │   │   │   └── filters.py
│   │   │   ├── generative/
│   │   │   │   ├── geometry.py     # Shapely алгоритмы
│   │   │   │   ├── teap.py         # Расчёт ТЭП
│   │   │   │   └── financial.py    # Финмодель
│   │   │   └── exporters/
│   │   │       ├── pdf.py          # WeasyPrint
│   │   │       ├── excel.py        # openpyxl
│   │   │       └── dxf.py          # ezdxf
│   │   └── workers/                # Celery tasks
│   ├── tests/
│   ├── alembic/                    # миграции
│   ├── pyproject.toml              # uv/poetry
│   └── Dockerfile
├── frontend/
│   ├── app/                        # Next.js 15 App Router
│   ├── components/
│   ├── lib/
│   └── package.json
├── docker-compose.yml              # dev окружение
├── .github/workflows/              # CI/CD
└── README.md
```

---

## 8. План на первый месяц (под Python)

### Неделя 1
- Установить **uv** (`pip install uv`)
- Создать проект: `uv init project-root && uv add fastapi sqlalchemy geoalchemy2 shapely pydantic`
- Поднять PostgreSQL + PostGIS в Docker (`postgis/postgis:16-3.4`)
- Первый эндпоинт `GET /parcels` возвращает заглушку
- Зарегистрировать ИТ-ООО (УСН 6%, ESOP пул в устав)

### Неделя 2
- Парсер Росреестра ПКК на httpx (асинхронный)
- Загрузка 1000 участков Екатеринбурга в БД
- Базовая модель `Parcel` в SQLAlchemy с PostGIS-геометрией
- Первый фильтр по площади и ВРИ
- Дизайнер-фрилансер делает 7 экранов в Figma

### Неделя 3
- Frontend Next.js: страница «Site Finder» с картой Leaflet
- API endpoint `POST /parcels/search` с фильтрами
- 5 cold-outreach писем целевым клиентам
- 3 встречи назначены

### Неделя 4
- Базовый скоринг (расстояние до центра + цена района)
- Первый прототип задеплоен в Yandex Cloud
- 5 встреч проведено
- Лендинг опубликован
- Первая статья в DigitalDeveloper или vc.ru опубликована

---

## 9. Что меняется в Custom Instructions проекта

В системный промпт проекта в Claude добавьте:

```
ТЕХНИЧЕСКИЙ СТЕК (актуальный с v2.2)
- Backend: Python 3.12 + FastAPI + SQLAlchemy 2.0 + Pydantic v2
- Геометрия: Shapely 2.0 + GeoPandas + GeoAlchemy2
- ML: XGBoost + scikit-learn + pandas
- БД: PostgreSQL 16 + PostGIS 3.4
- Очереди: Redis + Celery
- Frontend: Next.js 15 + React 19 + TypeScript + Tailwind + shadcn/ui
- Карты: Mapbox GL JS или Leaflet
- Экспорт: WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel)
- Облако: Yandex Cloud
- Dev: uv (зависимости), ruff (линт+формат), mypy (типы), pytest

КОММЕНТАРИЙ
Я перешёл с .NET на Python для MVP, потому что геометрия и ML
в Python-экосистеме намного сильнее. Опыт в C#/.NET 6 лет —
это база, на Python переключаюсь сейчас. При написании кода
учитывай, что я понимаю backend архитектуру отлично, но
синтаксис и идиомы Python ещё догоняю — давай явный type-hints
и комментарии к pythonic-конструкциям, которые могут быть
непривычны после C#.
```

---

## 10. Cost of switching: что реально потратите

### Время на «вкатывание»
- Неделя 1: 60% производительности vs привычный .NET
- Недели 2–3: 80%
- С недели 4: 100% и быстрее, чем на .NET (за счёт экосистемы)

### Что почитать в первую очередь
- **«Python for C# Developers»** (бесплатные статьи на Real Python)
- Документация **FastAPI** — отличная, начать с tutorial
- **Shapely manual** — для понимания геометрии
- **SQLAlchemy 2.0 docs** — async раздел

### Что НЕ читать сразу
- Книги «Python для начинающих» — вы не начинающий программист
- Гайды по Django — вам нужен FastAPI
- Старые туториалы (Python 3.8 и ниже) — слишком много изменилось

### Полезные привычки от .NET, которые работают и в Python
- Dependency Injection (FastAPI поддерживает через Depends)
- Strong typing (Pydantic + mypy)
- Repository pattern (через SQLAlchemy)
- Async/await (есть и работает)

### Что отучиться
- `Dictionary<string, object>` → используй Pydantic-модели
- LINQ → list comprehensions + библиотека `more_itertools`
- async всегда — в Python async только когда нужно (I/O bound)
- Heavy interfaces — Python предпочитает duck typing и Protocol

---

## 11. Acceptance Criteria для MVP

К концу месяца 3 продукт считается готовым к Раунду А, если:

**Функционально:**
- [ ] Site Finder загружает и показывает 1000+ участков Свердловской обл.
- [ ] Фильтр работает по 3 параметрам
- [ ] Скоринг по 3 критериям с настраиваемыми весами
- [ ] Generative Design генерирует 3 варианта за ≤ 10 секунд
- [ ] Расчёт ТЭП и базовая финмодель работают
- [ ] PDF/Excel/DXF экспорт работает
- [ ] Связь модулей (передача участка) работает

**Бизнесово:**
- [ ] 3 платящих пилота
- [ ] 7+ LOI
- [ ] Заявка в реестр ПО подана
- [ ] 1 администрация в переговорах
- [ ] Инвестиционный deck готов
- [ ] Финмодель на 5 лет готова

**Технически:**
- [ ] 60%+ покрытие тестами core-логики
- [ ] mypy --strict проходит
- [ ] Деплой в Yandex Cloud работает
- [ ] Sentry подключен
- [ ] Бэкапы БД ежедневно

Если все три блока выполнены — идём в Раунд А. Если выполнены 2 из 3 (например, технически + функционально, но только 2 пилота) — возможно продление Фазы 0 на 1–2 месяца за счёт собственных средств. Если выполнен только 1 блок или меньше — стоп проекта.

---

**Документ создан в апреле 2026. Версия 2.2 (Python-стек).**