Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (63 loc) · 5.64 KB

CLAUDE.md

File metadata and controls

80 lines (63 loc) · 5.64 KB
Raw

CLAUDE.md

Блюпринт Home Assistant для нежной зарядки EV. Управляет силовым оборудованием: ошибка в логике ограничения тока — вопрос безопасности проводки, а не косметики.

Язык

Документация, комментарии в блюпринте и общение с пользователем — на русском. Имена переменных, тестов и код — на английском. Docstring'и тестов — на английском.

Где что лежит

Путь Что это
blueprints/automation/ev_smart_charging/ev_smart_charging.yaml весь продукт, ~2300 строк
tests/ha_sim.py офлайн-эмулятор шаблонов HA, на нём работают тесты
tests/differential_against_home_assistant.py сверяет эмулятор с настоящим HA; единственное, что ловит его дрейф
tests/test_mutations.py ломает блюпринт по одному месту и проверяет, что набор это ловит
tools/trace_report.py разбор скачанных трассировок; держит совместимость с Python 3.9
docs/ сайт MkDocs; CHANGELOG/CONTRIBUTING/SECURITY лежат в корне и подключены сниппетами

Команды

pytest -m "not slow"     # ~20 с, обычная проверка
pytest -m slow -n auto   # мутации, несколько минут, перед крупными правками
ruff check tests/ tools/
yamllint -c .yamllint.yaml blueprints/ .github/ .yamllint.yaml mkdocs.yml
mkdocs build --strict    # сайт; битая ссылка = падение сборки

# требуют `pip install homeassistant`, обе информационные в CI
python tests/validate_with_home_assistant.py        # схема: входы и селекторы
python tests/differential_against_home_assistant.py # правили ha_sim.py — прогнать

Правила правки блюпринта

Логика живёт в variables:, блок actions: намеренно тонкий — только исполняет принятые решения. Это разделение и делает блюпринт тестируемым, держитесь его.

  1. Порядок объявления переменных значим. HA рендерит variables: сверху вниз; ссылка на переменную, объявленную ниже, молча даёт пустое значение.
  2. Каждый вызов службы — с continue_on_error: true.
  3. Никаких блокирующих delay перед командами. Режим restart: любой триггер обрывает паузу вместе со всем, что шло после неё. Интервалы выдерживаются проверкой (как gap_elapsed), а не ожиданием.
  4. Новая переменная — новый тест, плюс мутация в test_mutations.py, если поведение значимое.
  5. Новая функция шаблонов — реализовать в tests/ha_sim.py строго как в настоящем HA, включая отказы. Движок мягче настоящего HA опаснее отсутствующего: тесты зеленеют, в проде ломается. Затем добавить её вызовы в tests/differential_against_home_assistant.py и прогнать его — иначе у новой реализации не будет эталона, с которым её сверяют.

Грабли, на которые уже наступали

  • HA считает результат шаблона числом только если текст похож на число по его правилу. 4.9e-05 остаётся строкой → TypeError в арифметике ниже. Отсюда | round(4) в needed_kwh.
  • | float / | int без аргумента по умолчанию в HA бросают исключение, а не возвращают 0.
  • last_changed обновляется и при уходе сущности в unavailable: секундный обрыв связи «омолаживает» выключатель до нуля.
  • Недоступная сущность ≠ выключенная. Разрушительный вывод («выключили», «чужая», «сломалась») делается только по подтверждённому состоянию.
  • Запись того же значения не порождает state_changed — триггеры состояния не сработают.

Версии и релизы

Версия живёт в одном месте — в описании блюпринта (Версия X.Y.Z). CI-джоба packaging сверяет её с CHANGELOG.md и с git-тегом. Теги без префикса v: 1.3.0.

Чего не делать

  • Не переименовывать и не удалять входы (input:) без мажорной версии — это сбрасывает настройку у всех, кто уже пользуется блюпринтом.
  • Не называть конкретные марки машин и станций в описаниях входов.