Skru-ART

AI House Designer

Веб-платформа для проектирования частных домов онлайн с помощью искусственного интеллекта.

Пользователь описывает пожелания, ИИ-архитектор помогает с планировкой, материалами и бюджетом, а встроенный 2D-редактор и 3D-визуализатор позволяют довести проект до рабочего состояния.

Общая архитектура

┌─────────────────────────────────────┐
│           Browser (User)            │
└──────────────┬──────────────────────┘
               │ HTTPS
┌──────────────▼──────────────────────┐
│  Next.js 16 (Frontend)              │
│  - Auth pages                       │
│  - 2D floor plan editor (SVG)       │
│  - 3D viewer (React Three Fiber)    │
│  - AI chat panel                    │
│  - Cost estimate panel            │
└──────────────┬──────────────────────┘
               │ JSON / REST
┌──────────────▼──────────────────────┐
│  FastAPI (Backend)                  │
│  - JWT auth                         │
│  - Project CRUD                     │
│  - AI chat & plan generation        │
│  - Cost estimation                  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────┐  ┌─────────▼──────────┐
│  SQLite (projects, users)│  │  OpenAI API        │
└─────────────────────────┘  └────────────────────┘

Стек технологий

Слой	Технология
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS v4
2D/3D	SVG, React Three Fiber, Three.js
Backend	Python 3.9+, FastAPI, SQLAlchemy 2.0, Pydantic v2
База данных	SQLite (в перспективе PostgreSQL)
AI	OpenAI API (gpt-4o-mini)
Auth	JWT (python-jose) + bcrypt

Текущие возможности

MVP (реализовано)

В планах

PDF-экспорт планировки и сметы
DXF/SVG экспорт чертежей
Больше параметров генерации (этажность, материалы, региональные нормы)
Визуализация крыши, лестниц, мебели
Коллаборативное редактирование
PostgreSQL для продакшена
CI/CD и тесты

Структура проекта

house-designer-ai/
├── backend/                 # Python FastAPI backend
│   ├── main.py              # Точка входа, endpoints
│   ├── models.py            # SQLAlchemy модели
│   ├── schemas.py           # Pydantic схемы
│   ├── database.py          # Подключение к БД и сессии
│   ├── ai_service.py        # OpenAI: чат и генерация планировки
│   ├── floor_plan_generator.py  # Резервная/rule-based генерация планов
│   ├── cost_estimator.py    # Расчёт сметы
│   ├── requirements.txt
│   └── .env.example
├── frontend/                # Next.js frontend
│   ├── app/
│   │   ├── page.tsx         # Главная: авторизация, список проектов
│   │   ├── layout.tsx       # Корневой layout
│   │   └── project/
│   │       └── [id]/
│   │           └── page.tsx # Страница редактора проекта
│   ├── components/
│   │   ├── FloorPlanEditor.tsx      # 2D-редактор
│   │   ├── House3DViewer.tsx         # 3D-визуализатор
│   │   ├── AIChatPanel.tsx           # Панель чата с ИИ
│   │   └── CostEstimatePanel.tsx     # Панель сметы
│   ├── lib/
│   │   ├── api.ts           # HTTP-клиент (axios) и API-методы
│   │   └── types.ts         # TypeScript типы
│   ├── package.json
│   └── next.config.ts
└── README.md

Модели данных

`User`

Поле	Тип	Описание
id	int	Первичный ключ
email	string	Уникальный email
hashed_password	string	Хеш пароля (bcrypt)
full_name	string	Полное имя (опционально)
created_at	datetime	Дата регистрации

`Project`

Поле	Тип	Описание
id	int	Первичный ключ
title	string	Название проекта
description	text	Описание
parameters	JSON	Введённые пользователем параметры
floor_plan	JSON	Планировка (rooms, walls, doors, windows)
materials_estimate	JSON	Смета
owner_id	int	Владелец (FK → users)
created_at	datetime	Дата создания
updated_at	datetime	Дата обновления

`FloorPlan` (JSON)

{
  "rooms": [
    {
      "id": 1,
      "name": "Гостиная",
      "type": "living",
      "x": 0,
      "y": 0,
      "width": 5,
      "height": 5
    }
  ],
  "walls": [
    { "x1": 0, "y1": 0, "x2": 5, "y2": 0, "thickness": 0.2 }
  ],
  "doors": [
    { "x": 2, "y": 0, "width": 0.9, "orientation": "horizontal", "room_id": 1 }
  ],
  "windows": [
    { "x": 3, "y": 0, "width": 1.2, "orientation": "horizontal", "room_id": 1 }
  ]
}

Координаты в метрах. Начало координат — левый нижний угол дома.

API

Базовый URL: http://localhost:8000

Auth

Метод	Endpoint	Описание	Auth
POST	`/auth/register`	Регистрация	—
POST	`/auth/login`	Вход, получение JWT	—
GET	`/auth/me`	Текущий пользователь	Bearer

Projects

Метод	Endpoint	Описание	Auth
GET	`/projects`	Список проектов пользователя	Bearer
POST	`/projects`	Создать проект	Bearer
GET	`/projects/{id}`	Получить проект	Bearer
PATCH	`/projects/{id}`	Обновить проект	Bearer
DELETE	`/projects/{id}`	Удалить проект	Bearer
POST	`/projects/{id}/photo`	Загрузить фото участка	Bearer
GET	`/projects/{id}/photo`	Получить фото участка	Bearer
POST	`/projects/{id}/share`	Включить публичный доступ	Bearer
POST	`/projects/{id}/unshare`	Отключить публичный доступ	Bearer
GET	`/public/{token}`	Публичный проект по ссылке	—
POST	`/projects/{id}/versions`	Сохранить версию	Bearer
GET	`/projects/{id}/versions`	Список версий	Bearer
POST	`/projects/{id}/versions/{idx}/restore`	Восстановить версию	Bearer

Feedback

Метод	Endpoint	Описание	Auth
POST	`/feedback`	Отправить обратную связь	—

AI

Метод	Endpoint	Описание	Auth
POST	`/ai/chat`	Чат с ИИ-архитектором	—
POST	`/ai/generate-plan`	Сгенерировать планировку по запросу	—
POST	`/ai/generate-plan-variants`	Сгенерировать несколько вариантов	—
POST	`/ai/materials`	Рекомендации по материалам от ИИ	—
POST	`/ai/energy`	Оценка энергоэффективности	—
POST	`/ai/estimate`	Рассчитать смету	—

Export

Метод	Endpoint	Описание	Auth
POST	`/export/pdf`	Экспорт планировки в PDF	—
POST	`/export/svg`	Экспорт планировки в SVG	—
POST	`/export/dxf`	Экспорт планировки в DXF	—
POST	`/export/report`	Текстовый отчёт с характеристиками	—
POST	`/export/exec-docs`	Комплект исполнительной документации (PDF)	—

Примеры запросов

Регистрация

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123","full_name":"Иван Иванов"}'

Вход

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=secret123"

Создание проекта

curl -X POST http://localhost:8000/projects \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Мой дом","description":"Двухэтажный коттедж"}'

Генерация планировки

curl -X POST http://localhost:8000/ai/generate-plan \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Современный одноэтажный дом для семьи из 4 человек",
    "area": 120,
    "floors": 1,
    "style": "минимализм",
    "rooms": ["Гостиная", "Кухня", "Спальня", "Детская", "Ванная"]
  }'

Расчёт сметы

curl -X POST http://localhost:8000/ai/estimate \
  -H "Content-Type: application/json" \
  -d '{"floor_plan": {<plan>}, "region_factor": 1.0}'

Компоненты frontend

`FloorPlanEditor`

SVG-холст с сеткой.
Комнаты — кликабельные и перетаскиваемые с привязкой к сетке 0.5 м.
Масштабирование колёсиком мыши и кнопками.
Панорамирование холста перетаскиванием.
Кнопка «По размеру окна» для возврата к масштабу, вмещающему весь план.
История изменений с undo/redo (Ctrl+Z / Ctrl+Shift+Z).
Добавление и удаление комнат.
Панель редактирования выбранной комнаты: название, ширина, глубина, тип.
Отрисовка стен, дверей (оранжевые) и окон (голубые).

`House3DViewer`

React Three Fiber сцена.
Показывает полы комнат и несущие стены.
Управление: ЛКМ — вращение, скролл — зум.

`AIChatPanel`

История сообщений.
Отправка запроса к /ai/chat с контекстом проекта.
Кнопка «Сгенерировать планировку ИИ» вызывает /ai/generate-plan и обновляет редактор.
Кнопка «Сгенерировать варианты» вызывает /ai/generate-plan-variants и показывает 2–3 варианта на выбор.
Кнопка «Рекомендации по материалам» вызывает /ai/materials и выводит в чат предложения по материалам с ориентировочной стоимостью.
Кнопка «Оценка энергоэффективности» вызывает /ai/energy и показывает класс, теплопотери, расходы и рекомендации.

`CostEstimatePanel`

Региональный коэффициент.
Запрос к /ai/estimate.
Таблица расходов по статьям и итоговая сумма.

Быстрый старт

1. Клонирование и подготовка

git clone https://github.com/Skurzhansky/Skru-ART.git
cd Skru-ART

2. Backend

cd backend
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

Создайте файл backend/.env:

DATABASE_URL=sqlite:///./house_designer.db
OPENAI_API_KEY=sk-your-openai-key-here
SECRET_KEY=your-secret-key-for-jwt
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

Запуск:

python main.py

Сервер запустится на http://localhost:8000.

3. Frontend

cd frontend
npm install

Создайте файл frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Запуск:

npm run dev

Frontend откроется на http://localhost:3000.

Переменные окружения

Backend (`.env`)

Переменная	Описание	По умолчанию
`DATABASE_URL`	URL базы данных SQLAlchemy	`sqlite:///./house_designer.db`
`OPENAI_API_KEY`	API-ключ OpenAI	— (обязательно для ИИ)
`SECRET_KEY`	Секретный ключ для подписи JWT	—
`ALGORITHM`	Алгоритм подписи JWT	`HS256`
`ACCESS_TOKEN_EXPIRE_MINUTES`	Время жизни токена в минутах	`60`

Frontend (`.env.local`)

Переменная	Описание	По умолчанию
`NEXT_PUBLIC_API_URL`	URL backend API	`http://localhost:8000`

Рабочий процесс разработки

Перед изменениями — обсудить фичу/баг в README/Roadmap.
Backend — добавить endpoint/модель/сервис, обновить schemas.py.
Frontend — добавить компонент/метод в lib/api.ts, использовать в app/.
Типизация — обновить lib/types.ts при изменении JSON-моделей.
Сборка — запустить npm run build в frontend и python main.py в backend.
Коммит — краткое сообщение на русском или английском, описывающее зачем сделано изменение.

Правила по стеку

Backend: пишем на Python 3.9+, используем type hints, SQLAlchemy 2.0 синтаксис.
Frontend: React-компоненты клиентские помечаем "use client"; серверные страницы — по умолчанию.
Используем Tailwind CSS для стилей, избегаем кастомных CSS-файлов без необходимости.
Никогда не коммитим секреты, .env, venv/ и node_modules/.

Деплой

Docker Compose (рекомендуется)

docker-compose up --build

Поднимает три сервиса:

backend — FastAPI на http://localhost:8000
frontend — Next.js на http://localhost:3000
db — PostgreSQL 16

Перед запуском создай .env в корне:

OPENAI_API_KEY=sk-your-real-key
SECRET_KEY=your-strong-secret

Пошаговый деплой на VPS (рекомендуется)

Для полного соответствия законам РФ и независимости от зарубежных хостингов рекомендуется VPS у российского провайдера.

Вариант A: Timeweb / Selectel / Reg.ru (простой VPS)

Арендуй VPS/VDS (минимум 2 CPU, 4 GB RAM) с Ubuntu 22.04
Установи Docker и Docker Compose:

ssh root@твой-сервер
apt update && apt install -y docker.io docker-compose-plugin

Скопируй проект на сервер:

git clone https://github.com/Skurzhansky/Skru-ART.git
cd Skru-ART

Создай .env в корне:

OPENAI_API_KEY=sk-ваш-ключ
SECRET_KEY=ваш-секретный-ключ

Запусти:

docker compose up -d

Открой http://ip-вашего-сервера — сайт доступен по IP-адресу

Вариант B: Yandex Cloud (управляемые сервисы)

Backend: Yandex Cloud Container Instances или Compute Cloud + Docker
Frontend: Object Storage + CDN для статики, или Compute Cloud
База: Managed PostgreSQL в Yandex Cloud
Домен: подключи домен через DNS

Вариант C: Локальный сервер / домашний сервер

Если есть статический IP или возможность пробросить порты:

docker compose up -d

И открой порт 80/443 наружу.

Настройка HTTPS (для VPS)

Установи Nginx и Certbot:

apt install -y nginx certbot python3-certbot-nginx
certbot --nginx -d твой-домен.ru

Пример nginx.conf для проксирования:

server {
    listen 80;
    server_name твой-домен.ru;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
    }
}

Или используй CORS_ORIGINS в backend для разрешения домена frontend.

Тестирование

Backend

cd backend
source venv/bin/activate
pytest

Пока тесты не написаны — это следующий шаг в roadmap.

Frontend

cd frontend
npm run build
npm run lint

Ручное тестирование

Зарегистрироваться на главной.
Создать проект.
Открыть редактор.
Сгенерировать планировку через ИИ (нужен OPENAI_API_KEY).
Отредактировать комнаты в 2D.
Переключиться в 3D.
Рассчитать смету.
Сохранить и экспортировать проект (JSON, PDF, SVG, DXF, отчёт).

Деплой

Backend

Подходит любой хостинг с поддержкой Docker или Python + ASGI:

VPS в РФ: Timeweb, Selectel, Reg.ru, VDSina
Yandex Cloud: Compute Cloud, Container Instances
VK Cloud: Cloud Containers

Пример для VPS (Ubuntu + Docker):

Build command: docker build -f backend/Dockerfile -t house-backend ./backend
Start command: docker run -p 8000:8000 -e DATABASE_URL=... house-backend
Или через docker compose up -d из корня проекта

Frontend

Для соответствия законам РФ деплоить на:

VPS в РФ: Next.js production build (npm run build && npm start)
Yandex Cloud Object Storage + CDN: для статического экспорта (если адаптировать под static export)
Selectel: хостинг с Node.js

CORS

При деплое установи CORS_ORIGINS в backend с доменом frontend.

Roadmap

v0.2 — Улучшение редактора

Привязка комнат к сетке и стенам
Добавление/удаление комнат в редакторе
Отмена/повтор действий
Масштабирование и панорамирование холста

v0.3 — AI и параметры

Промпт с выбором этажности, площади, стиля, бюджета и комнат
Генерация нескольких вариантов планировки
Рекомендации по материалам от ИИ
Оценка энергоэффективности

v0.4 — Экспорт и документация

PDF-экспорт плана и сметы
DXF/SVG экспорт
Печать технических характеристик дома
Исполнительная документация (титульный лист, ведомость ИД, теххарактеристики, исполнительная схема, ведомость материалов, акт скрытых работ, журнал работ)

v0.5 — Платформа

PostgreSQL (через DATABASE_URL, psycopg[binary])
Загрузка фото участка
Совместный доступ к проекту (публичная ссылка)
Платежи и тарифы
Docker и docker-compose для деплоя

v0.6 — Подготовка к бете

Лицензия

Проект разрабатывается как приватный прототип. Лицензия будет добавлена позже.

Skru-ART

AI House Designer

Содержание

Общая архитектура

Стек технологий

Текущие возможности

MVP (реализовано)

В планах

Структура проекта

Модели данных

User

Project

FloorPlan (JSON)

API

Auth

Projects

Feedback

AI

Export

Примеры запросов

Регистрация

Вход

Создание проекта

Генерация планировки

Расчёт сметы

Компоненты frontend

FloorPlanEditor

House3DViewer

AIChatPanel

CostEstimatePanel

Быстрый старт

1. Клонирование и подготовка

2. Backend

3. Frontend

Переменные окружения

Backend (.env)

Frontend (.env.local)

Рабочий процесс разработки

Правила по стеку

Деплой

Docker Compose (рекомендуется)

Пошаговый деплой на VPS (рекомендуется)

Вариант A: Timeweb / Selectel / Reg.ru (простой VPS)

Вариант B: Yandex Cloud (управляемые сервисы)

Вариант C: Локальный сервер / домашний сервер

Настройка HTTPS (для VPS)

Тестирование

Backend

Frontend

Ручное тестирование

Деплой

Backend

Frontend

CORS

Roadmap

v0.2 — Улучшение редактора

v0.3 — AI и параметры

v0.4 — Экспорт и документация

v0.5 — Платформа

v0.6 — Подготовка к бете

Лицензия

`User`

`Project`

`FloorPlan` (JSON)

`FloorPlanEditor`

`House3DViewer`

`AIChatPanel`

`CostEstimatePanel`

Backend (`.env`)

Frontend (`.env.local`)