القائمة
Написание и изменение кода интеграции Voyah для Home Assistant — добавление сенсоров, бинарных сенсоров, кнопок, платформ, работа с API-клиентом, координаторами и config flow. Использовать при любых изменениях в custom_components/voyah/.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Документация и переводы интеграции Voyah — обновление README.md (двуязычный: русский + английский), strings.json и translations/en.json, ru.json. Использовать при добавлении сущностей, изменении config flow или возможностей интеграции.
Написание и запуск тестов интеграции Voyah — юнит-тесты сущностей, координаторов, API-клиента и config flow на pytest-homeassistant-custom-component. Использовать при добавлении/изменении тестов в tests/ или когда новый код требует покрытия.
| name | ha-code |
| description | Написание и изменение кода интеграции Voyah для Home Assistant — добавление сенсоров, бинарных сенсоров, кнопок, платформ, работа с API-клиентом, координаторами и config flow. Использовать при любых изменениях в custom_components/voyah/. |
Прочитай AGENTS.md (архитектура, команды) и файл, который собираешься менять.
Все изменения должны проходить ruff check ., ruff format --check . и pytest
(весь репозиторий отформатирован — держим это инвариантом).
Самый частый случай: API уже возвращает значение в sensorsData, нужно завести сенсор.
coolantTemp). Где взять реальный ответ:
VoyahApiClient логирует ключи ответа);tmp/app.voyahassist.ru_*.har. Каталог tmp/ в .gitignore,
поэтому файлов может не быть. В этом случае предложи разработчику снять HAR
со своей реальной сессии: открыть https://app.voyahassist.ru в браузере,
DevTools → вкладка Network → выполнить нужные действия в приложении →
экспортировать HAR (кнопка «Export HAR» / «Save all as HAR»; инструкция:
https://developer.chrome.com/docs/devtools/network/reference#save-as-har) —
и положить файл в tmp/. HAR содержит токены авторизации — коммитить его
нельзя, потому каталог и находится в .gitignore.SENSOR_DESCRIPTIONS в const.py:SensorEntityDescription(
key="coolantTemp", # точное имя ключа из API
translation_key="coolant_temperature", # snake_case
native_unit_of_measurement=UnitOfTemperature.CELSIUS,
device_class=SensorDeviceClass.TEMPERATURE, # если подходит стандартный
state_class=SensorStateClass.MEASUREMENT, # TOTAL_INCREASING для одометров
# icon="mdi:..." — только если нет device_class с подходящей иконкой
)
strings.json → entity.sensor.<translation_key>.name, продублируй
в translations/en.json, переведи в translations/ru.json./ha-tests, /ha-docs).Больше ничего не нужно: sensor.py создаст сущность автоматически, если ключ
присутствует в данных (if description.key in sensors_data).
Бинарный сенсор — то же самое через BINARY_SENSOR_DESCRIPTIONS и binary_sensor.py
(значение приводится к bool, в API это 0/1).
Образцы: VoyahChargingEndTimeSensor, VoyahLastPingSensor в sensor.py.
CoordinatorEntity[VoyahDataUpdateCoordinator], SensorEntity._attr_has_entity_name = True, _attr_translation_key,
_attr_unique_id = f"{car_id}_<suffix>", _attr_device_info с
identifiers={(DOMAIN, car_id)} — скопируй конструктор из существующего класса.native_value) —
переопредели _handle_coordinator_update с декоратором @callback и в конце
вызови super()._handle_coordinator_update()._pct_history в сенсоре зарядки);
HA может перезапуститься — инициализируй из первого снимка координатора.async_setup_entry платформы, с проверкой наличия
нужных ключей в данных.Образец: VoyahStartHeatingButton в button.py.
VoyahApiClient (api.py) через self._request(...) — он сам
обрабатывает 401 и рефреш токенов. Существующая команда обогрева использует
POST /car-service/tbox/{car_id}/heating, но не предполагай, что остальные
команды живут по тому же шаблону: точный метод и путь сверь с реальным
запросом приложения (HAR-файл, см. Рецепт 1).button.py: в async_press вызови метод клиента, затем
await self.coordinator.async_request_refresh() — чтобы состояние обновилось.HomeAssistantError с текстом).strings.json, en, ru) и README.VoyahApiClient._request:
он добавляет заголовки (Bearer, x-app: web), повторяет запрос после
рефреша токена при 401 и оборачивает сетевые ошибки в VoyahApiConnectionError._parse), чтобы
сущности получали уже нормализованный словарь, а не сырой ответ API.VoyahCarInfoCoordinator,
телеметрия — в основной VoyahDataUpdateCoordinator. Не добавляй третий
координатор без необходимости.| Где | Что бросать | Что произойдёт |
|---|---|---|
api.py | VoyahApiAuthError / VoyahApiConnectionError / VoyahApiError | — |
| координатор | ConfigEntryAuthFailed (из auth) / UpdateFailed (остальное) | reauth flow / сущности unavailable |
config_flow.py | ловить исключения API, возвращать errors["base"] = "<ключ из strings.json>" | сообщение в форме |
| кнопки/команды | HomeAssistantError("текст") | уведомление пользователю |
Никогда не глотай исключения молча; except Exception допустим только в
config flow с _LOGGER.exception(...) и errors["base"] = "unknown".
from __future__ import annotations в каждом модуле; полные тип-аннотации._LOGGER.debug с ленивой подстановкой (%s, не f-строки) — правило ruff G.hass.async_add_executor_job.const.py; локальные пороги алгоритмов (как
RATE_WINDOW_POINTS) можно держать в модуле платформы.