diff --git a/10-systems/automations/smart-home-control-playbook.md b/10-systems/automations/smart-home-control-playbook.md new file mode 100644 index 0000000..b1a6cd8 --- /dev/null +++ b/10-systems/automations/smart-home-control-playbook.md @@ -0,0 +1,99 @@ +--- +owner: gmikcon +status: active +last_reviewed: 2026-09-04 +review_interval: 90d +confidence: high +source_of_truth: ssh-host-verified +--- + +# Smart Home Control Playbook + +Канонические пути управления умным домом для AI-агентов и внешней автоматизации. Цель — всегда действовать по готовому проверенному пути: без импровизации, без прямого управления устройствами без необходимости. + +## Политика управления (правило владельца, 2026-09-04) + +1. **По умолчанию НЕ управлять устройствами напрямую** (прямые POST/GET к ESP-устройствам) — только по явной просьбе владельца или острой необходимости (авария, сервер умного дома недоступен). +2. **Дефолтный паттерн:** временный экшин/скрипт на сервере умного дома → запуск через штатный механизм → удаление временного артефакта после выполнения. +3. Это совпадает с архитектурной политикой платформы (inventory `smart-home-platform`): «ControlScripts are the only intended place for device-control business logic»; устройства и веб-клиенты не должны управлять устройствами напрямую через внешние REST API. +4. После любого прямого управления (если оно было оправдано) — отчёт владельцу. + +## Иерархия путей + +| # | Путь | Когда применять | Требует | +| --- | --- | --- | --- | +| 1 | Существующий экшин через CLI (SSH) | Дефолт: готовый алиас есть | SSH-доступ | +| 2 | Существующий экшин через HTTP API | Есть GAuth-сессия/Bearer | GAuth `scripts.run` | +| 3 | Временный скрипт на сервере | Готового алиаса нет | SSH-доступ | +| 4 | Прямой device API | Только по просьбе/острой нужде | device Bearer | + +## Path 1 — существующий экшин через CLI (предпочтительный) + +Самый быстрый путь, GAuth не нужен. + +- SSH: `shome@192.168.1.101`, порт 22; пароль — gnexus-creds secret `smart-home-server-creds` (в отчёты не выводить). +- Паттерн: PHP-скрипт с bootstrap `fury_init("SHServ")` (образец: `/home/shome/smart-home-server/server/enable_global_scenes.php`), вызов `\SHServ\Middleware\ControlScripts::run_action_script('', [])`. +- Живые алиасы (25, verified 2026-09-04): `10-systems/automations/smart-home-overview.md` → «Current live actions». Включая сцены Tier 1: `all_lights_off`, `goodnight`, `movie_mode`, `away_toggle`, `night_mode`, `guest_mode`, `hatch_status`. +- Мёртвые алиасы возвращают null — не использовать (overview → «Dead aliases»). + +## Path 2 — существующий экшин через HTTP API + +``` +POST http://192.168.1.101/api/v1/scripts/actions/run +Content-Type: application/json +{"alias": "", "params": {}} +``` + +- Требует GAuth permission `scripts.run` (session или Bearer из `shserv_sessions`). +- Ответ: JSON со `status: true` и `return`-значением скрипта. +- Детали: `10-systems/servers/smart-home-server.md`. + +## Path 3 — временный экшин/скрипт (когда готового нет) + +Проверенный паттерн (так деплоился Tier 1): + +1. SSH на сервер (креды как в Path 1). +2. Создать временный PHP-скрипт в `/home/shome/smart-home-server/server/` (например `tmp_.php`): bootstrap `fury_init("SHServ")`; внутри — серверные классы (`ControlScripts`, `SHServ\Tools\DeviceAPI\Relay` и т.п.), НЕ прямые HTTP-вызовы к устройствам. +3. Выполнить `php tmp_.php`, верифицировать результат (статус через серверные классы или read-only пути ниже). +4. Удалить временный файл (или перенести в `/home/shome/backups/`). + +- Перед изменениями кода — бэкап в `/home/shome/backups/`. +- Если экшин должен стать постоянным: регистрация в scope + `Scripts::set_script_state("action", alias, true)`; нюансы в overview («Registration vs DB», «Scope gate» — новый scope требует двух CLI-проходов). + +## Path 4 — прямой device API (ограниченный) + +Только по явной просьбе владельца или острой необходимости. Полный wire-формат: overview → «Device API Auth». + +- `GET http:///status` — `Authorization: Bearer ` (токен: DB `shome.device_auth`, `device_id`, `status='active'`). +- `POST http:///action` — `{"action":"set_channel_state","channel":N,"state":"on"|"off"}` / `{"action":"set_state","state":"on"|"off"}` / `{"action":"toggle_channel","channel":N}`. Поле `action` обязательно, иначе 400 `IllegalActionOrParams`. + +## Read-only статус (разрешён свободнее) + +Чтение статуса не меняет состояние — допустимо для диагностики без спецразрешения, предпочтительно через сервер: + +- Сервер: `GET http://192.168.1.101/api/v1/devices/id/{id}/status` (GAuth Bearer). +- Устройство: `GET http:///status` (device Bearer), `GET /about` (без auth). + +## Обязательные правила безопасности + +- Перед toggle — проверить текущее состояние (не гасить горящий свет); после действия — верифицировать ответом устройства/сервера. +- `fisrt_floor_big_relay` — `inverted=true` (логический off = физически замкнуто). +- Не трогать каналы с неподтверждённым назначением: `fisrt_floor_big_relay:6` и `:2`. +- `hatch_open`/`hatch_close` — `dangerous`: люк не двигать без явной просьбы. +- Пароли/токены не хранить и не выводить в документах и отчётах — только ссылки на gnexus-creds (`smart-home-server-creds`). + +## Шпаргалка + +| Задача | Путь | Что нужно | +| --- | --- | --- | +| Свет/сцены/режимы по алиасу | Path 1 (CLI) | SSH + алиас из overview | +| То же из внешней системы | Path 2 (HTTP) | GAuth Bearer | +| Нестандартное разовое действие | Path 3 (временный скрипт) | SSH | +| Прямая команда устройству | Path 4 | явная просьба / острая нужда | +| Узнать статус устройства | Read-only | GAuth или device Bearer | + +## Связанные документы + +- `10-systems/automations/smart-home-overview.md` — живые алиасы, режимы, устройства, wire-форматы +- `10-systems/servers/smart-home-server.md` — SSH-доступ, HTTP API, GAuth +- `10-systems/automations/light_control_procedures.md` — образец безопасной процедуры toggle diff --git a/90-maintenance/pending-changes/20260904190029-9dc56129.json b/90-maintenance/pending-changes/20260904190029-9dc56129.json new file mode 100644 index 0000000..cce7813 --- /dev/null +++ b/90-maintenance/pending-changes/20260904190029-9dc56129.json @@ -0,0 +1,19 @@ +{ + "id": "20260904190029-9dc56129", + "kind": "doc", + "target": "10-systems/automations/smart-home-control-playbook.md", + "summary": "Add smart-home control playbook: owner rule (no direct device control by default), 4-path hierarchy (CLI action, HTTP API, temp script, restricted device API), safety rules, quick reference.", + "reason": "Владелец 2026-09-04 ввёл правило «не управлять устройствами напрямую, дефолт — временные экшины» и попросил описать готовые пути управления. Документ собирает проверенные в этом сеансе факты: 25 живых алиасов, CLI/HTTP пути, паттерн временных скриптов Tier 1, ограниченный device API, правила безопасности.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-09-04\nreview_interval: 90d\nconfidence: high\nsource_of_truth: ssh-host-verified\n---\n\n# Smart Home Control Playbook\n\nКанонические пути управления умным домом для AI-агентов и внешней автоматизации. Цель — всегда действовать по готовому проверенному пути: без импровизации, без прямого управления устройствами без необходимости.\n\n## Политика управления (правило владельца, 2026-09-04)\n\n1. **По умолчанию НЕ управлять устройствами напрямую** (прямые POST/GET к ESP-устройствам) — только по явной просьбе владельца или острой необходимости (авария, сервер умного дома недоступен).\n2. **Дефолтный паттерн:** временный экшин/скрипт на сервере умного дома → запуск через штатный механизм → удаление временного артефакта после выполнения.\n3. Это совпадает с архитектурной политикой платформы (inventory `smart-home-platform`): «ControlScripts are the only intended place for device-control business logic»; устройства и веб-клиенты не должны управлять устройствами напрямую через внешние REST API.\n4. После любого прямого управления (если оно было оправдано) — отчёт владельцу.\n\n## Иерархия путей\n\n| # | Путь | Когда применять | Требует |\n| --- | --- | --- | --- |\n| 1 | Существующий экшин через CLI (SSH) | Дефолт: готовый алиас есть | SSH-доступ |\n| 2 | Существующий экшин через HTTP API | Есть GAuth-сессия/Bearer | GAuth `scripts.run` |\n| 3 | Временный скрипт на сервере | Готового алиаса нет | SSH-доступ |\n| 4 | Прямой device API | Только по просьбе/острой нужде | device Bearer |\n\n## Path 1 — существующий экшин через CLI (предпочтительный)\n\nСамый быстрый путь, GAuth не нужен.\n\n- SSH: `shome@192.168.1.101`, порт 22; пароль — gnexus-creds secret `smart-home-server-creds` (в отчёты не выводить).\n- Паттерн: PHP-скрипт с bootstrap `fury_init(\"SHServ\")` (образец: `/home/shome/smart-home-server/server/enable_global_scenes.php`), вызов `\\SHServ\\Middleware\\ControlScripts::run_action_script('', [])`.\n- Живые алиасы (25, verified 2026-09-04): `10-systems/automations/smart-home-overview.md` → «Current live actions». Включая сцены Tier 1: `all_lights_off`, `goodnight`, `movie_mode`, `away_toggle`, `night_mode`, `guest_mode`, `hatch_status`.\n- Мёртвые алиасы возвращают null — не использовать (overview → «Dead aliases»).\n\n## Path 2 — существующий экшин через HTTP API\n\n```\nPOST http://192.168.1.101/api/v1/scripts/actions/run\nContent-Type: application/json\n{\"alias\": \"\", \"params\": {}}\n```\n\n- Требует GAuth permission `scripts.run` (session или Bearer из `shserv_sessions`).\n- Ответ: JSON со `status: true` и `return`-значением скрипта.\n- Детали: `10-systems/servers/smart-home-server.md`.\n\n## Path 3 — временный экшин/скрипт (когда готового нет)\n\nПроверенный паттерн (так деплоился Tier 1):\n\n1. SSH на сервер (креды как в Path 1).\n2. Создать временный PHP-скрипт в `/home/shome/smart-home-server/server/` (например `tmp_.php`): bootstrap `fury_init(\"SHServ\")`; внутри — серверные классы (`ControlScripts`, `SHServ\\Tools\\DeviceAPI\\Relay` и т.п.), НЕ прямые HTTP-вызовы к устройствам.\n3. Выполнить `php tmp_.php`, верифицировать результат (статус через серверные классы или read-only пути ниже).\n4. Удалить временный файл (или перенести в `/home/shome/backups/`).\n\n- Перед изменениями кода — бэкап в `/home/shome/backups/`.\n- Если экшин должен стать постоянным: регистрация в scope + `Scripts::set_script_state(\"action\", alias, true)`; нюансы в overview («Registration vs DB», «Scope gate» — новый scope требует двух CLI-проходов).\n\n## Path 4 — прямой device API (ограниченный)\n\nТолько по явной просьбе владельца или острой необходимости. Полный wire-формат: overview → «Device API Auth».\n\n- `GET http:///status` — `Authorization: Bearer ` (токен: DB `shome.device_auth`, `device_id`, `status='active'`).\n- `POST http:///action` — `{\"action\":\"set_channel_state\",\"channel\":N,\"state\":\"on\"|\"off\"}` / `{\"action\":\"set_state\",\"state\":\"on\"|\"off\"}` / `{\"action\":\"toggle_channel\",\"channel\":N}`. Поле `action` обязательно, иначе 400 `IllegalActionOrParams`.\n\n## Read-only статус (разрешён свободнее)\n\nЧтение статуса не меняет состояние — допустимо для диагностики без спецразрешения, предпочтительно через сервер:\n\n- Сервер: `GET http://192.168.1.101/api/v1/devices/id/{id}/status` (GAuth Bearer).\n- Устройство: `GET http:///status` (device Bearer), `GET /about` (без auth).\n\n## Обязательные правила безопасности\n\n- Перед toggle — проверить текущее состояние (не гасить горящий свет); после действия — верифицировать ответом устройства/сервера.\n- `fisrt_floor_big_relay` — `inverted=true` (логический off = физически замкнуто).\n- Не трогать каналы с неподтверждённым назначением: `fisrt_floor_big_relay:6` и `:2`.\n- `hatch_open`/`hatch_close` — `dangerous`: люк не двигать без явной просьбы.\n- Пароли/токены не хранить и не выводить в документах и отчётах — только ссылки на gnexus-creds (`smart-home-server-creds`).\n\n## Шпаргалка\n\n| Задача | Путь | Что нужно |\n| --- | --- | --- |\n| Свет/сцены/режимы по алиасу | Path 1 (CLI) | SSH + алиас из overview |\n| То же из внешней системы | Path 2 (HTTP) | GAuth Bearer |\n| Нестандартное разовое действие | Path 3 (временный скрипт) | SSH |\n| Прямая команда устройству | Path 4 | явная просьба / острая нужда |\n| Узнать статус устройства | Read-only | GAuth или device Bearer |\n\n## Связанные документы\n\n- `10-systems/automations/smart-home-overview.md` — живые алиасы, режимы, устройства, wire-форматы\n- `10-systems/servers/smart-home-server.md` — SSH-доступ, HTTP API, GAuth\n- `10-systems/automations/light_control_procedures.md` — образец безопасной процедуры toggle" + }, + "status": "applied", + "created_at": "2026-09-04T19:00:29Z", + "updated_at": "2026-09-04T19:00:30Z", + "applied_at": "2026-09-04T19:00:30Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}