mirror of
https://github.com/Matysh/houseplan-card
synced 2026-07-31 16:38:31 +00:00
feat v1.11.0: full English translation + en/ru UI localization
- All card UI strings moved to src/i18n.ts (en/ru); language follows the HA profile automatically, new 'language: en|ru' card option forces it; GUI editor localized and got the language dropdown; generated device names localized via BuildCtx.loc. - English-only codebase: comments, docstrings, test names, backend error messages and logs. Russian remains only in the ru dictionary, ru.json, iconFor regexes matching Russian device names (+their fixtures) and README.ru.md. - Docs English-first: README (EN) + README.ru.md, ARCHITECTURE/DEVELOPMENT/ ROADMAP/CHANGELOG fully translated; translations/en.json had Russian - fixed. - Removed obsolete RELEASE_NOTES_v1.9.3.md and scripts_publish.sh.
This commit is contained in:
+53
-53
@@ -1,77 +1,77 @@
|
||||
# Разработка и деплой
|
||||
# Development and deployment
|
||||
|
||||
## Окружение (cowork-сессии)
|
||||
## Environment (cowork sessions)
|
||||
|
||||
- Эталон кода — **git-репозиторий** (в сессии живёт в `/tmp/hpc`, восстанавливается из
|
||||
`houseplan-card.git.bundle`: `git clone houseplan-card.git.bundle hpc`).
|
||||
- Папка пользователя `houseplan/houseplan-card/` — зеркало репо (rsync после каждого коммита)
|
||||
+ актуальный `houseplan-card.git.bundle`.
|
||||
- The source of truth for the code is the **git repository** (lives in `/tmp/hpc` during a session,
|
||||
restored from `houseplan-card.git.bundle`: `git clone houseplan-card.git.bundle hpc`).
|
||||
- The user's folder `houseplan/houseplan-card/` is a mirror of the repo (rsync after every commit)
|
||||
+ an up-to-date `houseplan-card.git.bundle`.
|
||||
|
||||
### ⚠️ Грабли файловой синхронизации (критично)
|
||||
1. Сетевой mount иногда отдаёт файлы **обрезанными/перемешанными** — правки через Edit-tool
|
||||
с Windows-стороны ненадёжны. Правило: **править python-патчами по чистой копии в /tmp,
|
||||
писать через bash**, assert на count(old)==1.
|
||||
2. **Сборку rollup вести ТОЛЬКО в /tmp/hpc** (`npm ci` уже сделан). Сборка на mount однажды
|
||||
дала синтаксически валидный, но битый бандл («wi is not defined»), который валил рендер
|
||||
ВСЕХ дашбордов HA (карточка грузится как extra_module на каждой странице!).
|
||||
3. `.git` на mount не создаётся («Operation not permitted» на dot-каталогах) — поэтому bundle.
|
||||
### ⚠️ File-sync pitfalls (critical)
|
||||
1. The network mount sometimes serves files **truncated/scrambled** — edits via the Edit tool
|
||||
from the Windows side are unreliable. Rule: **apply python patches against a clean copy in /tmp,
|
||||
write via bash**, with an assert that count(old)==1.
|
||||
2. **Run the rollup build ONLY in /tmp/hpc** (`npm ci` is already done). A build on the mount once
|
||||
produced a syntactically valid but broken bundle ("wi is not defined") that crashed the rendering
|
||||
of ALL HA dashboards (the card is loaded as an extra_module on every page!).
|
||||
3. `.git` cannot be created on the mount ("Operation not permitted" on dot-directories) — hence the bundle.
|
||||
|
||||
## Тесты
|
||||
## Tests
|
||||
|
||||
- Фронт: `npm test` — компилит src/logic.ts+rules.ts (tsconfig.test.json) и гоняет node:test
|
||||
(test/*.test.mjs). Строгая типизация: `npm run typecheck` (tsc --noEmit, входит в `npm run build`).
|
||||
- Бэк: `python -m pytest tests_backend/` — чистая валидация custom_components/houseplan/validation.py
|
||||
(грузится по пути, без импорта HA-пакета).
|
||||
- ВАЖНО (аудит-урок): rollup-плагин typescript выдаёт синтаксическую ошибку как WARNING и всё равно
|
||||
собирает бандл — обрезанный файл может «пройти». Поэтому в сборке первым идёт `tsc --noEmit`,
|
||||
который падает на таких ошибках. Всегда собирать `npm run build`, не голый `rollup -c`.
|
||||
- Frontend: `npm test` — compiles src/logic.ts+rules.ts (tsconfig.test.json) and runs node:test
|
||||
(test/*.test.mjs). Strict typing: `npm run typecheck` (tsc --noEmit, part of `npm run build`).
|
||||
- Backend: `python -m pytest tests_backend/` — pure validation of custom_components/houseplan/validation.py
|
||||
(loaded by path, without importing the HA package).
|
||||
- IMPORTANT (audit lesson): the rollup typescript plugin reports a syntax error as a WARNING and still
|
||||
builds the bundle — a truncated file can "pass". That is why the build starts with `tsc --noEmit`,
|
||||
which fails on such errors. Always build with `npm run build`, never bare `rollup -c`.
|
||||
|
||||
## Сборка
|
||||
## Build
|
||||
|
||||
```bash
|
||||
cd /tmp/hpc && npm ci # один раз
|
||||
cd /tmp/hpc && npm ci # once
|
||||
npx rollup -c # → dist/houseplan-card.js
|
||||
node --check dist/houseplan-card.js
|
||||
cp dist/houseplan-card.js custom_components/houseplan/frontend/
|
||||
```
|
||||
|
||||
## Деплой на дачу (ha.jbstudio.pro)
|
||||
## Deployment to the dacha (ha.jbstudio.pro)
|
||||
|
||||
- SSH: порт **323**, root, ключ `ha_jb` (пользователь загружает в чат; в песочнице /tmp/ha_jb, chmod 600).
|
||||
- SSH: port **323**, root, key `ha_jb` (the user uploads it to the chat; in the sandbox /tmp/ha_jb, chmod 600).
|
||||
- JS: `scp -P 323 -i /tmp/ha_jb dist/houseplan-card.js root@ha.jbstudio.pro:/config/custom_components/houseplan/frontend/`
|
||||
- Интеграция целиком: tar c custom_components/houseplan (--exclude __pycache__) → tar x на сервере.
|
||||
- **Проверка обязательна**: `md5sum` локально == на сервере == `curl http://homeassistant:8123/houseplan_files/houseplan-card.js | md5sum`
|
||||
(внутри SSH-аддона `localhost` — НЕ HA, использовать хост `homeassistant`).
|
||||
- Изменения Python требуют рестарта HA (`ha core restart`, держит соединение до конца, HTTP
|
||||
поднимается через 1–3 мин). Изменения JS — только обновление страницы (static path отдаётся
|
||||
с no-cache).
|
||||
- После деплоя JS — проверить в браузере (Ctrl+F5) и console (не должно быть ошибок из
|
||||
houseplan-card.js; битый бандл роняет все дашборды).
|
||||
- The whole integration: tar c custom_components/houseplan (--exclude __pycache__) → tar x on the server.
|
||||
- **Verification is mandatory**: `md5sum` locally == on the server == `curl http://homeassistant:8123/houseplan_files/houseplan-card.js | md5sum`
|
||||
(inside the SSH add-on `localhost` is NOT HA, use the host `homeassistant`).
|
||||
- Python changes require an HA restart (`ha core restart`, holds the connection until it finishes, HTTP
|
||||
comes back up in 1–3 min). JS changes — just a page refresh (the static path is served
|
||||
with no-cache).
|
||||
- After deploying JS — check in the browser (Ctrl+F5) and the console (there must be no errors from
|
||||
houseplan-card.js; a broken bundle takes down all dashboards).
|
||||
|
||||
## Кэш фронтенда и «пустой вид»
|
||||
## Frontend cache and the "empty view"
|
||||
|
||||
- URL модуля карточки содержит `?v=<VERSION из const.py>`. Браузеры держат ES-модуль в
|
||||
memory-cache: после деплоя нового JS **бампните VERSION в const.py и рестартуйте HA**,
|
||||
иначе обычный F5 оставит старую версию.
|
||||
- После reload страницы HA-фронтенд (с kiosk-mode) иногда оставляет вид пустым
|
||||
(«InvalidStateError: Transition was aborted», hui-view не создаётся 1–2 мин).
|
||||
Лечится повторной SPA-навигацией: pushState + событие location-changed, или подождать.
|
||||
- The card module URL contains `?v=<VERSION from const.py>`. Browsers keep the ES module in
|
||||
memory cache: after deploying new JS **bump VERSION in const.py and restart HA**,
|
||||
otherwise a plain F5 will keep the old version.
|
||||
- After a page reload the HA frontend (with kiosk-mode) sometimes leaves the view empty
|
||||
("InvalidStateError: Transition was aborted", hui-view is not created for 1–2 min).
|
||||
Cured by repeating the SPA navigation: pushState + a location-changed event, or just waiting.
|
||||
|
||||
## Релиз
|
||||
## Release
|
||||
|
||||
Тег `vX.Y.Z` + GitHub Release → workflow `.github/workflows/release.yml` собирает и прикладывает
|
||||
`houseplan-card.js`. Версию бампать синхронно: `src/houseplan-card.ts` (CARD_VERSION),
|
||||
Tag `vX.Y.Z` + GitHub Release → the workflow `.github/workflows/release.yml` builds and attaches
|
||||
`houseplan-card.js`. Bump the version everywhere in sync: `src/houseplan-card.ts` (CARD_VERSION),
|
||||
`package.json`, `custom_components/houseplan/manifest.json`, `custom_components/houseplan/const.py`.
|
||||
|
||||
## Воспроизводимые скрипты (данные)
|
||||
## Reproducible scripts (data)
|
||||
|
||||
- Извлечение геометрии/подложек из прототипа и генерация `src/data/*` — см. историю коммитов
|
||||
и docs/ARCHITECTURE.md (трансформации SVG→базовое пространство: f1 0.647/(490,27), f2 0.896/(351,21)).
|
||||
- Подгонка комнат: рендер плана с прямоугольниками поверх (cv2) → снап к стенам → ручная доводка.
|
||||
- Extracting the geometry/backgrounds from the prototype and generating `src/data/*` — see the commit
|
||||
history and docs/ARCHITECTURE.md (SVG→base-space transforms: f1 0.647/(490,27), f2 0.896/(351,21)).
|
||||
- Room fitting: render the plan with rectangles overlaid (cv2) → snap to walls → manual fine-tuning.
|
||||
|
||||
## Прод-объекты в HA (дача)
|
||||
## Production objects in HA (the dacha)
|
||||
|
||||
- Дашборд `plan-doma`, панельный вид, карточка `custom:houseplan-card` (icon_size 2.5).
|
||||
- Интеграция houseplan: entry загружен, `.storage/houseplan.layout` — раскладка (сервер).
|
||||
- Старый прототип `/config/www/houseplan/` (iframe) сохранён как запасной, не трогать.
|
||||
- Бэкапы configuration.yaml: `.bak-avgtemp` (до правки среднего датчика).
|
||||
- Dashboard `plan-doma`, panel view, card `custom:houseplan-card` (icon_size 2.5).
|
||||
- The houseplan integration: entry loaded, `.storage/houseplan.layout` — the layout (server-side).
|
||||
- The old prototype `/config/www/houseplan/` (iframe) is kept as a fallback, do not touch.
|
||||
- configuration.yaml backups: `.bak-avgtemp` (before the average-temperature sensor edit).
|
||||
|
||||
Reference in New Issue
Block a user