Self-hosted house planner: true-scale 2D floor plan, 3D, satellite map overlay, sewer, electrical, water and underfloor heating with calculations, priced bill of materials. React + PHP, no database. By the team behind homedesignsai.pro
Правка плана через JSON и с ИИ-ассистентом
English | Русский
Весь проект — участок, стены, проёмы, мебель, сети, смета — это один JSON-документ в целых миллиметрах. Всё, что делается в редакторе, можно сделать правкой этого файла руками или с ИИ-ассистентом. Для массовых и точных правок так часто быстрее: «сдвинь все внутренние стены на 50 мм», «розетки через каждые 2 м по стенам гостиной», «замени материал стен везде».
Два способа получить файл
Из браузера. «⋯» → «Экспорт JSON» скачивает текущий план; «Импорт JSON» проверяет файл и сохраняет его новой ревизией. Подходит для разовых правок.
Скриптами. scripts/plan-pull.sh и scripts/plan-push.sh ходят в тот же API, что и браузер, поэтому версии и проверка конфликтов работают так же. Подходит для регулярных правок и для ассистентов, которые умеют запускать команды (Claude Code, Codex CLI, Aider и подобные).
Настройка скриптов
Нужны bash, curl и python3. Создайте .env.deploy в корне репозитория (он в .gitignore) или задайте переменные окружения:
HOUSE_URL=https://plan.example.com
HOUSE_PASSWORD=пароль-планировщика
Если HOUSE_URL не задан, берётся DEPLOY_URL из настроек заливки. Для локального Docker — http://localhost:8080.
Цикл правки
scripts/plan-pull.sh # → plans/server.json
# правка plans/server.json
node scripts/plan-validate.mts plans/server.json # та же zod-схема, что в приложении
scripts/plan-push.sh # → новая ревизия на сервере
plan-pull.sh печатает ревизию, время, автора, число стен и проёмов. --rev N забирает старую ревизию, --out файл пишет в другой файл. Папка plans/ в корне репозитория в .gitignore.
plan-push.sh [файл] отправляет файл с If-Match: <rev>; rev берётся из самого файла (его туда кладёт pull) или из --rev N. Метка автора по умолчанию cli, задаётся --author, например --author assistant — так правки ассистента видны в «Версиях».
Конфликты. Если после pull план на сервере изменился, ничего не перезаписывается: скрипт сохраняет серверную копию в plans/server.conflict.json и выходит с кодом 2. Перенесите правки на эту копию (или сделайте pull и повторите их) и отправьте снова.
Открытые вкладки подхватывают новую ревизию; если в какой-то шла правка, она повторяется поверх вашей версии.
Работа с ассистентом
Дайте ассистенту три вещи:
- Формат: docs/plan-format.md и для точных типов — src/model/schema.ts.
- Текущий план,
plans/server.json. - Правила ниже.
Системный промпт, который хорошо работает:
Ты правишь план дома в JSON (формат — docs/plan-format.md, схема — src/model/schema.ts).
Правила:
- Все координаты и размеры — целые миллиметры. Ось X — вдоль стороны участка 0–1, ось Y — вниз по экрану.
- Стена — осевая линия a→b; углы сходятся, только если концы совпадают точно.
- Проём ссылается на стену через wallId; offset — от точки a стены; offset + width не больше длины стены.
- Все id уникальны в своём массиве; materialId и id материалов сетей должны существовать.
- Не трогай rev, updatedAt, author: их ведёт сервер; rev — базовая ревизия для If-Match.
- Меняй только то, о чём просили. Незнакомые поля оставляй как есть.
После правки запусти node scripts/plan-validate.mts plans/server.json, исправь ошибки, затем scripts/plan-push.sh --author assistant.
Если ассистент умеет запускать команды, пусть проходит цикл целиком: pull, правка, проверка, push и отчёт с новой ревизией. Если не умеет — вставьте JSON (или нужную часть) в чат, заберите результат, проверьте и отправьте сами.
Типовые правки
| Просьба | Что меняется в JSON |
|---|---|
| «Добавь стену 5 м из угла дома на восток» | новая запись в walls: a — в углу (координаты из конца существующей стены), b = a + (5000, 0) |
| «Окно 1200 по центру стены w2» | новая запись в openings: wallId: "w2", type: "window", offset = (длина w2 − 1200) / 2, width: 1200, height, sill |
| «Пусть дверь в спальню открывается в другую сторону» | поменять side (left ↔ right) или hinge (start ↔ end) у этой двери |
| «Добавь материал по ссылке» | новая запись в materials: name, kind, thickness, price, pricePer, url, checkedAt; затем materialId у нужных стен |
| «Подпиши комнату в юго-западном углу как кухню» | новая запись в rooms: точка внутри комнаты, kind: "kitchen" |
| «Отметь СИП-панели купленными по 5400» | estimate.purchases["auto:wall:sip-174"] = { "done": true, "actualPrice": 5400 } |
Длина стены не хранится, она равна √((b.x − a.x)² + (b.y − a.y)²).
Подводные камни
- Невалидный план приложение не загрузит, а
plan-validate.mtsне пропустит — проверяйте перед отправкой. - Удаление стены в JSON не удаляет её проёмы: уберите их тоже, иначе проверка упадёт на несуществующем
wallId. - Если на сервере лежит
site-fixed.json, граница, сторона улицы, геопривязка и закреплённые зоны берутся из него, правки этих полей в JSON молча заменяются. См. docs/api.md. - Большой план помещается в чат, но для мелких правок дешевле передавать только нужные массивы и вливать ответ обратно.
- Каждый push — новая ревизия, которая хранится всегда; неудачную отправку откатывают восстановлением прошлой ревизии в «Версиях».