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
API хранения плана (/api/plan.php)
План живёт на сервере, а не только в браузере. Отдельного бэкенда нет: PHP-файлы в public/api/ (общий код в public/api/_lib.php, общие функции установки — создание хранилища, запись config.php и закрывающих .htaccess — в public/api/_install.php, их используют мастер setup.php и загрузчик Docker-образа) собираются в dist/api/ и заливаются scripts/deploy.sh. Нужен PHP 8.1+ (код совместим и с 7.4, но устаревшие версии не проверяются) с curl (для корзины Петровича); для закрытия статики — Apache или LiteSpeed с mod_rewrite. Формат самого плана описан в docs/plan-format.md; сервер проверяет только, что это JSON-объект с site (объект), walls и openings (массивы), остальное — дело zod-схемы клиента.
Хранилище. Папка storage/, которую создаёт мастер установки api/setup.php. Ищется по порядку: путь из переменной окружения HOUSE_STORAGE, <корень сайта>/../storage (вне webroot, предпочтительно), <корень сайта>/storage (внутри сайта, закрыта .htaccess с Require all denied). Рабочей считается первая папка, где есть config.php. Там config.php — хеш пароля, токен куки входа и настройки (пример — storage.example/config.example.php, в репозиторий настоящий не попадает), current.json — текущий план, versions/<YYYYMMDDTHHMMSSZ>-<rev>.json — каждая записанная версия (хранятся все), versions.jsonl — индекс версий построчно, .lock — файл блокировки. Если current.json нет, первый же запрос засевает его из файла seed в конфиге (по умолчанию plans/demo.json в корне сайта) как rev 1 с автором seed. Пока хранилища нет, любой запрос к API отвечает 503 not_installed.
Неизменяемые данные участка (необязательно). Если положить в хранилище site-fixed.json вида { "site": { boundary, street, geo, zones } } (пример — storage.example/site-fixed.example.json), сервер накладывает эти поля поверх плана при каждой отдаче (GET, ?rev=N, план в ответе 409) и при каждой записи. boundary, street и geo всегда берутся из файла, что бы ни прислал клиент. Зоны из файла с locked: true идут первыми в site.zones; присланные клиентом зоны с locked: true или с тем же id отбрасываются, остальные зоны клиента сохраняются как есть. site.imagery (поправка спутниковой подложки) не фиксируется. Так юридическую границу участка нельзя случайно сдвинуть из приложения или через plan-push.sh — только правкой файла на сервере. Если файла нет, наложение не делается.
Служебные поля плана. Сервер дописывает в сохранённый план три поля верхнего уровня: rev (целое, растёт на 1 с каждой записью), updatedAt (ISO 8601 UTC с миллисекундами) и author (метка автора). Присланные клиентом значения этих полей игнорируются и перезаписываются. Zod-схема клиента лишние поля пропускает.
Доступ. Каждый запрос должен нести куку hauth — её ставит POST /api/login.php (см. ниже). Значение куки — случайный токен из storage/config.php, сверка через hash_equals. Без неё или с неверной — 401. Запросы на запись дополнительно требуют непустой заголовок X-Requested-With (клиент шлёт XMLHttpRequest), иначе 403 — это защита от CSRF через обычную форму. В public/api/.htaccess стоит RewriteEngine On: он отключает для /api/ возможные правила переадресации из корневого .htaccess, так что API всегда отвечает 401 в JSON, а не 302. Прямой запрос к файлам с подчёркиванием в начале (_lib.php, _install.php) — 403. Все ответы идут с Cache-Control: no-store и Content-Type: application/json.
Закрытые данные. Статика с данными дома тоже закрыта кукой: мастер установки пишет data/.htaccess и plans/.htaccess, которые сверяют hauth с тем же токеном через RewriteCond %{HTTP_COOKIE} и без куки отвечают 401. В репозитории этих файлов нет, scripts/deploy.sh их на сервере не трогает. Это /data/house.json, /data/catalog.json, /data/parcel.geojson и /plans/*.json. Засев хранилища читает план с диска, а не по HTTP, поэтому закрытие на него не влияет. На nginx без Apache .htaccess не работает — закройте /storage, /data и /plans в конфигурации сервера.
Методы
| запрос | ответ |
|---|---|
GET /api/plan.php |
200, тело — текущий план целиком, заголовки ETag: "<rev>" и X-Plan-Rev: <rev> |
GET /api/plan.php?versions |
200, { "rev": <текущий>, "versions": [ { rev, updatedAt, author, walls, openings, bytes, file }, … ] }, новые сверху; walls/openings — число стен и проёмов |
GET /api/plan.php?rev=N |
200, план версии N с её ETag; нет такой — 404 |
PUT или POST /api/plan.php |
тело — JSON плана, заголовки If-Match: <rev> (можно "<rev>"), X-Requested-With, необязательный X-Plan-Author: <метка> (по умолчанию web, до 40 символов, буквы, цифры, пробел, .@_-). Успех — 200, { "rev": <новый>, "updatedAt": "…" } и новый ETag |
Версия клиента. Каждый PUT/POST должен нести заголовок X-Client-Version: <целое>. Если его нет или он меньше минимальной версии (константа MIN_CLIENT_VERSION в public/api/_lib.php, сейчас 2; можно переопределить ключом min_client_version в storage/config.php), сервер ничего не пишет и отвечает 426 { "error": "client_outdated", "message": "…", "minClientVersion": 2 }. Клиент на 426 перезагружает страницу. Это защита от старых открытых вкладок, которые не знают новых полей плана (например, site.zones) и затирали бы их при сохранении. Когда формат плана расширяется, версию в клиенте и MIN_CLIENT_VERSION поднимают вместе. plan-push.sh шлёт X-Client-Version из константы CLIENT_VERSION в src/model/schema.ts.
Запись: If-Match сравнивается с rev текущего плана под эксклюзивным flock на storage/.lock. Совпало — план получает rev+1, пишется файл версии, затем current.json (оба через временный файл и rename, т. е. атомарно), затем строка в versions.jsonl. Не совпало — ничего не пишется, ответ 409:
{ "error": "conflict", "message": "план уже изменён: rev 7, прислан 5", "rev": 7, "updatedAt": "…", "plan": { …текущий план… } }
Клиент в этом случае должен показать расхождение и переложить свои правки поверх plan, а потом писать с If-Match: 7. Молча перезаписывать нельзя: в тот же файл могут писать другая вкладка или plan-push.sh.
Именованные снимки
Все ревизии и так хранятся в versions/, снимок — это ревизия с человеческим именем, чтобы откатиться «к версии от 30.09», не выискивая номер. Снимки лежат в storage/snapshots/<дата>-<slug>.json (дата в часовом поясе timezone из конфига, slug — имя транслитом, при совпадении добавляется -2, -3), журнал — storage/snapshots.jsonl. Автоматически снимки не удаляются никогда.
POST /api/plan.php?snapshot с телом { "name": "30.09.2026 — дом из блоков" } копирует текущий current.json в снимок и отвечает 201 { id, name, rev, createdAt, author, walls, openings }. Доступ как у записи плана: кука hauth, X-Requested-With, X-Client-Version; автор берётся из X-Plan-Author (по умолчанию web). Пустое имя или длиннее 200 символов — 422 invalid_name. If-Match не нужен: снимок ничего не меняет в плане.
GET /api/plan.php?snapshots — { "snapshots": [ … ] }, новые сверху. GET /api/plan.php?snapshot=<id> — сам план снимка (с наложением неизменяемых данных участка) и ETag его ревизии; нет такого — 404.
Восстановление — обычный PUT плана из снимка поверх текущего с If-Match: <текущий rev> (не rev снимка) и X-Plan-Author: restore:<id>. Получается новая ревизия, история и сам снимок остаются.
Вход и выход
Вход встроен в приложение: без куки клиент получает 401 от plan.php и показывает свою форму пароля.
POST /api/login.php с телом { "password": "…" } и заголовком X-Requested-With. Сервер проверяет пароль через password_verify по хешу из storage/config.php. Совпало — 200 { "ok": true } и Set-Cookie: hauth=<токен>; Max-Age=31536000; Path=/; HttpOnly; SameSite=Lax (плюс Secure, если запрос пришёл по HTTPS). Не совпало (или пароль пуст, или тело не JSON) — пауза 1 с против перебора и 401 { "error": "wrong_password" }. Без X-Requested-With — 403 csrf, другой метод — 405.
POST /api/logout.php с X-Requested-With стирает куку (hauth=; Max-Age=0) и отвечает 200 { "ok": true }. Кука HttpOnly, из JS её не видно, поэтому признак входа для клиента — статус ответа GET /api/plan.php.
Корзина Петровича (/api/petrovich-cart.php)
Собирает корзину на petrovich.ru и возвращает ссылку на смету, которую кто угодно открывает без входа и одной кнопкой переносит позиции в свою корзину.
POST /api/petrovich-cart.php с телом { "city": "spb" | "vbg", "items": [ { "code": "128015", "qty": 2, "name": "…" } ] }. Доступ как у записи плана: кука hauth, X-Requested-With, X-Client-Version (иначе 401, 403, 426). code — код товара Петровича (цифры из petrovich.ru/product/<code>/), qty — количество в единицах продажи, дробное округляется вверх, повторяющиеся коды складываются, name необязателен. Не больше 150 разных позиций, иначе 413 too_many_items.
Порядок работы: свежая анонимная сессия (страница товара → init.js → куки), GUID товаров пачками по 50 кодов через catalog/v5/search-d в выбранном городе, коды, которых нет в выдаче, добираются по одному через catalog/v5/products/{code}. Товары с is_not_in_stock в городе пропускаются. Остальные добавляются по одной POST /cart/v2/products/{guid} с паузой 300–500 мс, потом GET /cart/v2/link даёт ссылку, корзина очищается DELETE /cart/v2/items. Весь запрос ограничен 120 с. Одновременно идёт один запрос: второй получает 429 busy.
Ответ 200:
{ "url": "https://petrovich.ru/estimate/000000000/", "city": "spb",
"added": [ { "code": "128015", "qty": 2, "name": "Коробка установочная …", "price": 21 } ],
"missing": [ { "code": "999999999", "reason": "not_found" } ],
"total": 94 }
reason в missing: not_found — такого кода нет, no_stock — нет в наличии в городе, add_failed — Петрович не принял позицию (в detail его ответ). price — розничная цена Петровича в городе за единицу, total — сумма price × qty по добавленным, без скидок корзины. Если не добавилось ничего — 422 nothing_added с тем же missing, ссылки нет. Капча Qrator, 403 или 429 от Петровича — 502 petrovich_blocked; прочие сбои Петровича — 502 petrovich_unavailable | petrovich_bad_reply | petrovich_no_link; не уложились в 120 с — 504 timeout. Ошибки входа: 400 bad_json, 422 invalid_city | invalid_items. Каждый вызов создаёт новую смету у Петровича, удалить её анонимно нельзя, поэтому ручку не дёргать в цикле.
Демо-режим
Включается ключом 'demo' => true в storage/config.php или переменной окружения HOUSE_DEMO=1 (в Docker — docker run -e HOUSE_DEMO=1). Код — public/api/_demo.php. Отличия от обычного режима:
Признак для клиента. Каждый JSON-ответ API в демо несёт заголовок X-House-Demo: 1; тело плана не меняется. Клиент читает заголовок из GET /api/plan.php и показывает плашку со ссылкой на репозиторий, кнопку корзины Петровича выключает. В обычном режиме заголовка нет.
Без входа. Кука hauth не проверяется ни в plan.php, ни в других ручках, 401 не бывает, экран входа не показывается. POST /api/login.php сразу отвечает 200 { "ok": true, "demo": true } без проверки пароля. data/ и plans/ открыты: при сбросе (и при старте Docker-контейнера) их .htaccess переписываются на открытый вариант. setup.php ведёт себя как обычно: после установки 403.
Сброс. План раз в час возвращается к plans/demo.json в корне сайта: новая ревизия rev+1 с автором demo-reset (номер ревизии не откатывается, открытые вкладки получат 409 и перечитают план). Заодно удаляются версии и снимки старше часа и старые счётчики лимита. Время последнего сброса — mtime файла storage/.demo-reset. Сброс делает cron-скрипт php scripts/demo-reset.php --webroot=<корень сайта> (от пользователя веб-сервера; без --webroot берётся public/ рядом со скриптом), а если cron нет — ленивый сброс: первый запрос к plan.php после того, как с прошлого сброса прошло больше 60 минут, сначала сбрасывает план, потом обрабатывается. В Docker работает только ленивый сброс.
Ограничения. План не больше 1 МБ (413 too_large). Не больше 30 записей (PUT/POST плана и снимков) в минуту с одного IP (REMOTE_ADDR, за обратным прокси — адрес прокси), счётчик — файлы storage/ratelimit/<sha256 IP>.json; превышение — 429 rate_limited с Retry-After и полем retryAfter в секундах. Снимков не больше 20 (403 demo_limit), лишние уходят при часовом сбросе. Корзина Петровича отключена: POST /api/petrovich-cart.php — 403 demo_disabled. Константы — в начале _demo.php.
Коды ошибок
Тело любой ошибки — { "error": "<код>", "message": "<по-русски>" }.
| HTTP | error |
когда |
|---|---|---|
| 400 | bad_json |
тело не парсится как JSON |
| 401 | unauthorized |
нет куки hauth или она неверна |
| 401 | wrong_password |
login.php: неверный пароль |
| 403 | csrf |
запись, вход или выход без X-Requested-With |
| 403 | demo_disabled |
демо: корзина Петровича отключена |
| 403 | demo_limit |
демо: уже 20 снимков |
| 404 | not_found |
?rev=N без такой версии |
| 405 | method_not_allowed |
метод не GET/HEAD/PUT/POST |
| 409 | conflict |
If-Match не равен текущему rev; в теле rev и plan |
| 413 | too_large |
тело больше 2 МБ (в демо — 1 МБ) |
| 422 | invalid_plan |
не объект или нет site/walls/openings нужного типа |
| 426 | client_outdated |
запись без X-Client-Version или с версией меньше минимальной |
| 428 | if_match_required |
запись без If-Match |
| 429 | rate_limited |
демо: больше 30 записей в минуту с одного IP; есть Retry-After |
| 503 | not_installed |
хранилище не найдено — откройте api/setup.php |
| 500 | no_seed, lock_failed, write_failed, corrupt |
проблема на сервере |
Пример клиента
const res = await fetch('/api/plan.php', { credentials: 'same-origin', cache: 'no-store' });
const plan = await res.json();
const rev = Number(res.headers.get('X-Plan-Rev'));
const put = await fetch('/api/plan.php', {
method: 'PUT',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'XMLHttpRequest', 'If-Match': String(rev) },
body: JSON.stringify(plan),
});
if (put.status === 409) { const { rev: serverRev, plan: serverPlan } = await put.json(); }
Установка
api/setup.php открывается один раз после первой заливки. Он показывает, куда можно положить хранилище (вне корня сайта, если есть права, иначе внутри с запретом .htaccess), принимает пароль (не короче 8 символов), создаёт папку storage/, пишет config.php с password_hash и случайным токеном куки, а также data/.htaccess и plans/.htaccess с этим токеном. После этого setup.php отвечает 403. Если задана переменная окружения HOUSE_SETUP_KEY, мастер дополнительно спрашивает этот ключ — так установку не перехватит посторонний между заливкой и первым входом. Сменить пароль: удалить config.php в хранилище и снова открыть setup.php; план и версии остаются, старые куки перестают действовать.
Docker. В образе хранилище — том house-data, смонтированный в /var/lib/house-planner (HOUSE_STORAGE). При каждом старте контейнера загрузчик (docker/house-boot.php, на тех же функциях из _install.php) переписывает data/.htaccess и plans/.htaccess под токен из config.php. Если config.php ещё нет и задана переменная HOUSE_PASSWORD (не короче 8 символов), он выполняет установку сам, без мастера; если пароля нет — закрывает data/ и plans/ полностью и ждёт мастера api/setup.php. После установки HOUSE_PASSWORD больше ни на что не влияет. С HOUSE_DEMO=1 загрузчик ставит планировщик без HOUSE_PASSWORD (пароль случайный, он не нужен) и вместо закрывающих .htaccess пишет открытые — см. «Демо-режим».
Скрипты
scripts/plan-pull.sh входит через POST /api/login.php и забирает текущий план (GET /api/plan.php) в plans/server.json в корне проекта, печатает rev, время, автора и число стен. --rev N берёт конкретную версию, --out <файл> пишет в другой файл. Адрес и пароль — переменные HOUSE_URL (по умолчанию DEPLOY_URL) и HOUSE_PASSWORD, из окружения или .env.deploy.
scripts/plan-push.sh [файл] заливает файл (по умолчанию plans/server.json) как новую версию через тот же PUT /api/plan.php, так что проверка rev, блокировка, атомарная запись и версия работают одинаково для браузера и для скрипта. Базовый rev берётся из поля rev в файле (его туда кладёт pull) или из --rev N; метка автора — cli, меняется через --author. X-Client-Version берётся из CLIENT_VERSION в src/model/schema.ts. При успехе печатает новый rev и, если отправлялся plans/server.json, перетягивает его с сервера. При конфликте кладёт серверный план рядом как <файл>.conflict.json и выходит с кодом 2; тогда правки надо перенести на него и отправить снова.
node scripts/plan-validate.mts <файл> проверяет план той же zod-схемой, что и клиент (npm run plan:validate — для демо-плана).
Обычный цикл правки плана вне браузера: scripts/plan-pull.sh, правка plans/server.json, scripts/plan-validate.mts plans/server.json, scripts/plan-push.sh.