Newer
Older
gnexus-book / 90-maintenance / pending-changes / 20260904190029-9dc56129.json
{
  "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('<alias>', [])`.\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\": \"<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_<task>.php`): bootstrap `fury_init(\"SHServ\")`; внутри — серверные классы (`ControlScripts`, `SHServ\\Tools\\DeviceAPI\\Relay` и т.п.), НЕ прямые HTTP-вызовы к устройствам.\n3. Выполнить `php tmp_<task>.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://<device_ip>/status` — `Authorization: Bearer <device_token>` (токен: DB `shome.device_auth`, `device_id`, `status='active'`).\n- `POST http://<device_ip>/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://<device_ip>/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": []
  }
}