lekss361/gendesign
1
0
Fork 0
Code Issues 57 Pull requests Projects Releases Packages Wiki Activity Actions
gendesign/docs/MVP_Goals_Python.md

20 KiB
Raw Blame History

Цели 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-стек).