docs: корректировки планов — монорепо, слои ayla/aircon, конверсии, приёмка

- PLAN_CORE: монорепозиторий (CMakeLists в корне; components/fglair,
  custom_components/fglair, include/fgl-aircon, src/{ayla,aircon},
  src/ayla/platform); логическое разделение ay­la (протокол+цикл) /
  aircon (конверсии+шаблоны+API); тесты зеркалят слои (tests/{ayla,aircon});
  конверсии: шаблон / линейные коэффициенты / функция-указатель
  (лямбды ESPHome); оценка httpd/json (jsmn вендор, свой мини-httpd на
  BSD-сокетах, conan не нужен); README библиотеки в M4.
- PLAN_ESPHOME: host вместо ip_address (DNS + Ayla-mDNS :10276),
  секреты в примерах, кастомные конверсии через !lambda, advanced-пример
  (триггеры режимов + LVGL с пропусками), README-план, скрипт приёмки
  (aioesphomeapi + HA REST).
- PLAN_HOME_ASSISTANT: шаг config flow с превью рассчитанных значений
  шаблона (через cffi в C-ядро, без дублей), README с HACS-инструкцией
  и заглушками под скриншоты с описаниями, приёмка (long-lived token).
- Убраны реальные dsn/ip/lanip_key/key_id из примеров; probe_mdns.py
  принимает DSN аргументом.

docs/PLAN_CORE_LIBRARY.md

@@ -1,79 +1,92 @@
-# План: кросс-платформенная библиотека `fglair-core` (C++20, Linux + ESP-IDF)
+# План: базовая библиотека `fgl-aircon` (C++20, Linux + ESP-IDF) в монорепозитории
 
-Целевая аудитория документа — агенты-реализаторы. Протокольные детали — в
-`PROTOCOL.md` (ссылки вида «§N», факты помечены [ПРОВЕРЕНО НА ПРИБОРЕ]).
+Целевая аудитория — агенты-реализаторы. Протокольные детали — в
+`PROTOCOL.md` (ссылки вида «§N»; факты помечены [ПРОВЕРЕНО НА ПРИБОРЕ]).
 Причины проектных решений — `LEGACY_ANALYSIS.md`.
 
-## 1. Цели и не-цели
+## 0. Монорепозиторий
+
+Все три компонента живут в одном репозитории:
+
+```
+/                             # CMakeLists.txt базовой библиотеки — в корне
+  include/fgl-aircon/         # публичный API (уровень aircon)
+  src/
+    ayla/                     # реализация протокола + главный цикл сообщений
+      platform/
+        posix/                # сокеты/std::thread/timerfd/getrandom
+        esp-idf/              # lwip-сокеты/esp_timer/esp_random
+    aircon/                   # конверсии, шаблоны, реализация публичного API
+  third_party/jsmn/           # вендоренный JSON-парсер (MIT)
+  components/fglair/          # ESPHome external component (см. PLAN_ESPHOME)
+  custom_components/fglair/   # HA custom component (см. PLAN_HOME_ASSISTANT)
+  tests/
+    ayla/                     # тесты протокола (KDF, envelope, http, сессия+mock)
+    aircon/                   # тесты конверсий и шаблонов
+    acceptance/               # скрипты приёмки ESPHome<->HA (см. §11)
+  tools/                      # probe_reference.py, probe_mdns.py, fglair-discover
+  docs/
+```
+
+Подключение к сборке:
+* **ESP-IDF**: корень репозитория регистрируется как компонент
+  (`idf_component.yml`/`CMakeLists.txt` с `idf_component_register`); ESPHome-
+  компонент (`components/fglair`) подключает его через `EXTRA_COMPONENT_DIRS`
+  / relative path.
+* **POSIX**: `cmake -S . -B build && cmake --build build` — статическая
+  библиотека `fgl-aircon` + цели тестов.
+
+## 1. Слои библиотеки (логическое разделение, сборка — одна)
+
+```
+приложение (HA / ESPHome / fglctl)
+   │  include/fgl-aircon/*.hpp      — публичный API
+   ▼
+src/aircon   — свойства и их семантика: таблицы шаблонов A/B/F,
+               конверсии (шаблонные/линейные/функцией), кэш значений,
+               адаптация к публичному API. Не знает про сеть.
+   │  src/ayla/session.hpp (внутренний интерфейс)
+   ▼
+src/ayla     — протокол Ayla LAN: crypto/KDF, envelope, HTTP-сервер/клиент
+               (mini-httpd/httpc), очередь команд с coalescing и pacing,
+               главный цикл сообщений (один поток/задача), re-key, слоты,
+               keep-alive. Не знает про свойства кондиционера.
+   │
+   ▼
+src/ayla/platform/*  — сокеты, таймеры, CSPRNG, лог (posix | esp-idf)
+```
+
+Правила слоёв:
+* `aircon` → `ayla` → `platform`, зависимости только вниз.
+* `ayla` оперирует «непрозрачными» именами свойств (строки) и целыми —
+  вся семантика (°C, режимы, флаги, битмаски) — в `aircon`.
+* Публичный API — только `include/fgl-aircon/`; внутренние заголовки лежат
+  рядом с реализациями (`src/ayla/*.hpp`, `src/aircon/*.hpp`).
+
+## 2. Цели и не-цели
 
 Цели:
-1. Реализовать LAN-протокол FGLair/Ayla (сторона «приложения») по спецификации
-   `PROTOCOL.md` с поведением, максимально близким к официальному APK и
-   подтверждённому живыми тестами прибора.
-2. Портативность: сборка как C++20-библиотека (Linux, CMake) и как компонент
-   ESP-IDF (esp32/esp32s3/esp32c3 — везде ESP-IDF, Arduino-фреймворк не
-   поддерживаем и не тестируем).
-3. Малый footprint и детерминированное использование памяти: без heap после
-   инициализации (все буферы — члены/статические), никаких исключений наружу
-   (внутри — `expected`/коды), логирование через callback.
-4. Интеграция «как у climate-модулей ESPHome»: простой асинхронный API
-   (set/get свойства, колбэки обновлений, статус сессии).
-5. Устойчивость: переживать re-key (модуль сам ротирует ключи каждые ≈44–60 с),
-   перезагрузку модуля, конфликт слотов (503), режим «KE без активации»;
-   жёсткий rate-control, чтобы не «завалить» модуль.
+1. Реализовать LAN-протокол FGLair/Ayla (сторона «приложения») по
+   `PROTOCOL.md`, поведение — как у APK и подтверждено живыми тестами.
+2. Портативность: ESP-IDF (esp32/esp32s3/esp32c3, только IDF-фреймворк) и
+   POSIX (Linux) из одной кодовой базы.
+3. Малый footprint: без heap после `init()`, без исключений/RTTI наружу,
+   логирование через callback, статические буферы.
+4. Интеграция «как у climate-модулей ESPHome»: асинхронный API, колбэки.
+5. Устойчивость: re-key (модуль ротирует ключи каждые ≈44–60 с), перезагрузка
+   модуля, слоты/503, режим «KE без активации»; жёсткий rate-control.
 
 Не-цели (первая версия):
-* Облако внутри C++-библиотеки. **lanip_key считается статичным, зашитым в
-  модуль** (5 лет эксплуатации без ротаций). Провижининг — отдельный Python
-  CLI (`fglair-discover`), см. §8. При несовпадении `key_id` библиотека
-  переходит в устойчивое состояние ошибки и ждёт смены конфига вручную.
-* Узловые устройства (`node/*`), setup-режим (RSA `sec`), OTA.
-* Hisense-свойства (`t_power` и пр.) — только FGLair-шаблоны A/B/F.
+* Облако в рантайме. `lanip_key` статичен (зашит в модуль, 5 лет без ротаций);
+  провижининг — Python CLI `tools/fglair-discover`. Несовпадение `key_id` →
+  устойчивое состояние ошибки до правки конфига вручную.
+* Узловые устройства, setup-режим (RSA), OTA.
+* Hisense-свойства (`t_power` и пр.) — только шаблоны A/B/F.
 
-## 2. Архитектура
-
-```
-┌────────────────────────────────────────────────────────────┐
-│  Приложение: HA-интеграция / ESPHome-компонент / CLI       │
-└───────────────▲────────────────────────────────────────────┘
-                │ include/fgl/*.h — публичный API
-                │   C++-классы + тонкий extern "C"-шейм (для cffi/HA)
-┌───────────────┴────────────────────────────────────────────┐
-│ core (портативный C++20, без исключений/RTTI/heap):         │
-│  session   — машина состояний, re-key, keep-alive, слоты    │
-│  crypto    — KDF, AES-256-CBC (цепочка!), HMAC-SHA256       │
-│  envelope  — pack/unpack {"enc","sign"}, seq_no, паддинг    │
-│  property  — таблицы свойств шаблонов A/B/F, конверсии      │
-│  cmdq      — очередь команд с coalescing + pacing           │
-│  json      — минимальный streaming JSON reader/writer       │
-│  httpd     — минимальный HTTP/1.1 server (роутинг по IP)    │
-│  httpc     — клиент local_reg                               │
-├────────────────────────────────────────────────────────────┤
-│ platform layer (интерфейс fgl/platform.h, 2 реализации):    │
-│  posix  : sockets, std::thread, timerfd, getrandom          │
-│  esp-idf: lwip sockets, esp_timer/FreeRTOS, esp_random      │
-├────────────────────────────────────────────────────────────┤
-│ crypto backend: mbedtls (в ESP-IDF встроен; на Linux —      │
-│ системный или vendored)                                     │
-└────────────────────────────────────────────────────────────┘
-```
-
-Правила:
-* Ядро не знает про ОС: сокеты/таймеры/логи/случайность — через тонкие
-  платформенные заголовки, реализуемые слоем ниже.
-* Ядро однопоточное: один внутренний поток/задача владеет сессией и шифрами
-  (CBC-цепочка требует строгой сериализации). Вызовы API извне — через
-  потокобезопасный mailbox (lock-free SPSC или мьютекс). Все колбэки
-  исполняются из этого потока.
-* C++20 разрешён и приветствуется (enum class, span, chrono, concepts),
-  но: без исключений, RTTI, виртуальных иерархий в горячем пути и heap после
-  `init()`. `std::function` в API не использовать (функция+user-data).
-* Запрет на `printf`; логирование через injectable `fgl_log_fn`.
-
-## 3. Публичный API (эскиз, `include/fgl/`)
+## 3. Публичный API (эскиз `include/fgl-aircon/`)
 
 ```cpp
-// fgl/types.h
+// types.hpp
 enum class fgl_state { idle, registering, online, recovering, offline, key_error };
 enum class fgl_prop { operation_mode, fan_speed, adjust_temperature,
                       display_temperature, af_vertical_direction, af_vertical_swing,
@@ -81,19 +94,37 @@ enum class fgl_prop { operation_mode, fan_speed, adjust_temperature,
                       powerful_mode, coil_dry_mode, min_heat, outdoor_low_noise,
                       indoor_fan_control, human_det_auto_save, wifi_led_enable,
                       op_status, error_code, device_capabilities, demand_control,
-                      get_prop, device_name, building_name, /* ...по PROTOCOL.md §8.2 */ };
+                      get_prop, device_name, building_name /* ...PROTOCOL §8.2 */ };
+enum class fgl_template { A, B, F };
 struct fgl_value { enum kind { boolean, integer, string } type;
-                   union { bool b; int32_t i; }; const char* s; };
+                   bool b; int32_t i; const char* s; };
+
+// --- конверсии: шаблон по умолчанию, коэффициенты или функция (см. §4) ---
+enum class fgl_conv_kind { template_default, linear, custom_fn };
+struct fgl_linear { int32_t num, den, offset; };     // disp = raw*num/den + offset
+struct fgl_conversion {
+  fgl_conv_kind kind = fgl_conv_kind::template_default;
+  fgl_linear linear{};                               // при kind == linear
+  int32_t (*fn)(int32_t raw, void* ctx) = nullptr;   // при kind == custom_fn
+  void* ctx = nullptr;
+};
+struct fgl_prop_override {           // точечная настройка одного свойства
+  fgl_prop prop;
+  bool has_range = false; int32_t min = 0, max = 0;
+  fgl_conversion to_display{};       // raw -> инженерные единицы
+  fgl_conversion from_input{};       // ввод -> raw
+};
 
 struct fgl_config {
-  const char* device_ip;      // "192.0.2.3"
-  const char* dsn;            // "AC000W00REDACTED"
+  const char* host;           // DNS-имя или IP ("ac.local" / "192.168.0.42")
+  const char* dsn;            // "AC000W00XXXXXXX"
   const char* lanip_key;      // base64-строка как есть
-  uint32_t    lanip_key_id;   // 62888
-  fgl_template template_;     // A / B / F
+  uint32_t    lanip_key_id;
+  fgl_template template_;
   uint16_t    listen_port;    // 0 => 10275
-  uint32_t    keepalive_ms;   // 0 => 15000 (рекомендация; APK: 10с)
+  uint32_t    keepalive_ms;   // 0 => 15000
   uint8_t     max_queue;      // 0 => 16
+  const fgl_prop_override* overrides = nullptr;   // nullptr-terminated
 };
 struct fgl_callbacks {
   void (*on_state)(void* user, fgl_state st, int err);
@@ -102,172 +133,188 @@ struct fgl_callbacks {
   void* user;
 };
 
-// fgl/session.h (C++-класс; в fgl/c_api.h — extern "C" шейм для cffi)
+// session.hpp (C++-классы; c_api.h — extern "C" шейм для cffi/HA)
 class FglSession {
  public:
   static FglSession* create(const fgl_config&, const fgl_callbacks&);
-  int start(); int stop();          // stop() шлёт delete_session, ждёт ≤2с
+  int start(); int stop();          // stop() шлёт delete_session (≤2с)
   fgl_state state() const;
-  // Управление (ставится в очередь с coalescing):
   int set_bool(fgl_prop, bool); int set_int(fgl_prop, int32_t);
-  int get_prop(fgl_prop);           // запросить refresh
-  int batch_begin(); int batch_commit();   // атомарный пакет команд
+  int get_prop(fgl_prop);
+  int batch_begin(); int batch_commit();
   bool cached(fgl_prop, fgl_value* out) const;
 };
+
+// templates.hpp — интроспекция шаблонов (для превью в HA, тестов, CLI):
+//   список свойств шаблона, base_type, RO, диапазоны, примеры конверсии
+const fgl_template_info* fgl_template_info_get(fgl_template);
+int32_t fgl_convert_to_display(fgl_template, fgl_prop, int32_t raw,
+                               const fgl_prop_override* ov);
+int32_t fgl_convert_from_input(fgl_template, fgl_prop, int32_t disp,
+                               const fgl_prop_override* ov);
 ```
 
-Таблица свойств — `const` массивы в rodata по шаблонам (имя, base_type,
-read-only, диапазоны), см. PROTOCOL.md §8.
+## 4. Конверсии (требование: задаются руками при необходимости)
 
-## 4. Поведенческие требования (обязательны к точной реализации)
+Каждое числовое свойство имеет конверсию по умолчанию из таблицы шаблона
+(`adjust_temperature`: ×0.1 °C; `display_temperature`: (v−5000)/100;
+направления: 0..N−1; перечисления — словари). Конфиг сессии может переопределить
+её для любого свойства одним из способов:
 
-Ссылки на PROTOCOL.md; всё, что ниже, согласовано с живыми тестами прибора.
+1. **Коэффициенты** `fgl_linear {num, den, offset}` — для линейных величин
+   (температуры, проценты). Без кода, доступно из HA UI и YAML.
+2. **Функция-указатель** `int32_t (*)(int32_t raw, void* ctx)` — произвольная
+   логика; `ctx` для захваченных данных. ESPHome-лямбды компилируются в
+   функции и передаются напрямую (пример — PLAN_ESPHOME §2); HA ограничен
+   коэффициентами (и выбором шаблона).
+3. Диапазоны (`min/max`) переопределяются независимо от конверсии.
 
-### 4.1. Установка сессии
-1. `start()`: HTTP-сервер слушает `listen_port` (по умолчанию 10275).
-2. Отправить `POST /local_reg.json?dsn=<DSN>` с `notify=0` (§4.1). Ответы:
-   202 — ок; **503 — нет свободных слотов** (2 заняты, например телефоном и
-   другим сервером) → состояние `offline` с ошибкой `FGL_E_NO_SLOT`, повтор
-   с backoff 30–60 с; таймаут/отказ соединения → `offline`, backoff 1→60 с.
-3. Дождаться `POST /local_lan/key_exchange.json` (обычно <1 с). Проверить
-   `ver==1, proto==1, sec пустой` (иначе 426/400), сверить `key_id`
-   (несовпадение → **412** + состояние `key_error` до смены конфига вручную;
-   облако НЕ дёргается — ключ статичен). Сгенерировать `random_2` (16 симв.
-   `[A-Za-z0-9]`), `time_2` (любое int64, напр. наносекунды аптайма),
-   вывести ключи (§3.2), ответить 200 `{"random_2":...,"time_2":...}`.
-4. После ответа модуль в течение ~0.5 с делает «пустой» опрос commands.json —
-   это сигнал активации. **Если в течение 5 с опроса нет — сессия не
-   активировалась** (наблюдавшийся режим зависания модуля): закрыть серверную
-   сторону молча, уйти в `recovering` с паузой 30–60 с (НЕ долбить
-   повторными local_reg — ухудшает состояние модуля).
-5. После активации: поставить пакет GET-команд нужных свойств (подписанное
-   подмножество таблицы, по умолчанию — все состояния + capabilities) и
-   отправить ОДИН `local_reg` с `notify=1`. Значения придут push'ами.
+Конверсия применяется в `src/aircon` на границе API: наружу — «инженерные»
+единицы (0.1 °C уже умножено? — НЕТ: наружу отдаётся значение в единицах
+конверсии, см. ниже), в протокол — raw. Договорённость о единицах наружу
+фиксируется в README: наружу отдаётся результат `to_display` (для шаблона A
+температуры — °C×1 float-friendly int? — принимаем: наружу int32 в
+«инженерных» единицах, кратность задаёт конверсия; для HA cffi этого
+достаточно, ESPHome при желании делит сам через лямбду).
 
-### 4.2. Keep-alive и re-key (ядро надёжности)
-* Таймер `keepalive_ms` (по умолчанию **15000**). По истечении — `PUT local_reg`
-  с `notify = (очередь непуста)`.
-* **Модуль сам ротирует ключи**: очередной `local_reg` при возрасте сессии
-  ≥ ~44 с приходит вместе с новым key exchange. Обработать его как обычный
-  KE (перегенерация шифров, цепочки сбрасываются), НЕ пересоздавая сессию;
-  seq_no приложения продолжает глобальный счётчик. После re-key НЕ нужна
-  повторная начальная синхронизация (значения уже в кэше).
-* Каждый обслуженный `GET /commands.json` перезапускает таймер keep-alive
-  (APK-поведение). Анти-спам: не более одного `local_reg` в ~1 с; notify=1
-  отправляется один раз на пакет команд.
-* Модель времени: хранить `last_ke_time`; при `local_reg` предсказывать,
-  будет ли re-key (age ≥ 44 c) — для телеметрии/диагностики.
+## 5. Поведенческие требования (обязательны к точной реализации)
 
-### 4.3. Очередь команд и pacing
-* Ограничение очереди `max_queue` (16). Coalescing: новый write того же
-  свойства замещает предыдущий незабранный; GET-дубликаты отбрасываются.
-* `commands.json`: отдать **одну** команду из головы; 206, если очередь
-  непуста, иначе 200. Шифрование строго последовательно (CBC-цепочка),
-  паддинг — Java-вариант (≥1 NUL).
-* Записи не эхируются (проверено): после выдачи write обновить кэш
-  оптимистично; опционально (по конфигу) подтвердить GET-ом через 1–2 с.
+### 5.1. Установка сессии
+1. `start()`: HTTP-сервер слушает `listen_port` (10275). Разрешение `host`:
+   `getaddrinfo` (lwip DNS); для `*.local` — Ayla-mDNS запрос A-записи на
+   `224.0.0.251:10276` (модуль НЕ отвечает на :5353 — проверено). Ретраи
+   разрешения при недоступности.
+2. `POST /local_reg.json?dsn=<DSN>` с `notify=0` (PROTOCOL §4.1). Ответы:
+   202 — ок; **503 — нет слотов** (2 заняты) → `offline`/`FGL_E_NO_SLOT`,
+   повтор 30–60 с; отказ соединения → `offline`, backoff 1→60 с.
+3. Дождаться key exchange (<1 с): `ver/proto==1, sec==""` (иначе 426),
+   сверка `key_id` (несовпадение → **412** + `key_error` до правки конфига).
+   `random_2` — 16 симв. `[A-Za-z0-9]`, `time_2` — наносекунды аптайма;
+   вывести ключи (§3.2 PROTOCOL), ответить 200.
+4. Активация = «пустой» опрос commands.json в течение ~0.5 с. **Нет опроса
+   5 с → сессия не активировалась** (известный режим зависания модуля):
+   тишина + `recovering` с паузой 30–60 с (НЕ долбить local_reg).
+5. После активации — пакет GET-команд свойств + ОДИН `local_reg notify=1`.
 
-### 4.4. Обработка сообщений модуля
-* Datapoint push: расшифровать, проверить подпись; **seq_no не проверять**.
-  Парсить query `?cmd_id=N&status=200` для сопоставления с ожиданиями GET.
-  При ошибке расшифровки ответить **401** (APK-совместимость; модуль это
-  игнорирует, но таковы интерфейсные контракты) и пометить сессию
-  `recovering` — ждать ближайшего re-key по keep-alive (≤15 с).
-* Повторный key exchange на живой сессии — штатное событие (§4.2), не ошибка.
+### 5.2. Keep-alive и re-key
+* Таймер `keepalive_ms` (default **15000**); по истечении — `PUT local_reg`
+  c `notify=(очередь непуста)`. Каждый `commands.json` перезапускает таймер.
+* Re-key (очередной local_reg при возрасте сессии ≥ ~44 с) — штатное
+  событие: перегенерация шифров/цепочек, сессия не пересоздаётся, начальная
+  синхронизация не повторяется; seq_no приложения продолжает глобальный счётчик.
+* Анти-спам: ≤1 local_reg/с; notify=1 — один на пакет команд.
 
-### 4.5. Завершение
-* `stop()`: поставить команду DELETE `local_reg.json`/`delete_session`,
-  дождаться выдачи (≤2 с), закрыть сервер. Освобождает слот немедленно
-  (проверено) — важно из-за лимита в 2 сессии.
+### 5.3. Очередь команд
+* Лимит `max_queue` (16); coalescing (write замещает write, GET-дубликаты
+  отбрасываются). `commands.json`: одна команда из головы; 206/200;
+  шифрование строго последовательно; паддинг Java-вариант (≥1 NUL).
+* Записи не эхируются (проверено): оптимистичное обновление кэша;
+  опционально GET-подтверждение через 1–2 с.
 
-### 4.6. HTTP-сервер
-* Минимальный HTTP/1.1: GET/POST, `Content-Length`, keep-alive, query-параметры.
-  Один поток, последовательная обработка, RST-обрывы от модуля — норма.
-* Роутинг на сессию по IP клиента (как `deviceWithLanIP` в APK). Мульти-сессии
-  (несколько устройств) — через `FglHub` (M6).
+### 5.4. Входящие сообщения
+* Datapoint push: расшифровка, подпись; **seq_no не проверяется**. Query
+  `?cmd_id=N&status=200` — сопоставление GET-ожиданий. Ошибка расшифровки →
+  **401** (APK-совместимость) + `recovering` (самолечение — ближайший
+  keep-alive/re-key, ≤15 с).
+* Ответы на GET также доставляются через datapoint push (в `ayla` они
+  прозрачны наверх как обновления свойства).
 
-## 5. Криптография
+### 5.5. Завершение
+* `stop()`: DELETE `local_reg.json`/`delete_session`, выдача ≤2 с, закрыть
+  сервер. Слот освобождается немедленно (проверено).
 
-* mbedtls: AES-256-CBC c сохранением IV-состояния между сообщениями
-  (mbedtls_aes_crypt_cbc обновляет iv-буфер на месте — использовать его же
-  как персистентное состояние), HMAC-SHA256 через `mbedtls_md`.
-* KDF по §3.2 PROTOCOL. Тестовые векторы — эталон `tools/probe_reference.py`
-  (проверен на приборе) + генератор векторов на Python.
-* `random_2`/`id` — из CSPRNG платформы. `time_2` — наносекунды аптайма.
+## 6. Криптография
 
-## 6. Таблица свойств
+mbedtls (в ESP-IDF встроен; POSIX — системный или FetchContent):
+AES-256-CBC с персистентным IV-состоянием между сообщениями
+(`mbedtls_aes_crypt_cbc` обновляет iv-буфер на месте — использовать его как
+состояние цепочки), HMAC-SHA256 через `mbedtls_md`. KDF — PROTOCOL §3.2;
+тестовые векторы — эталон `tools/probe_reference.py` (проверен на приборе).
 
-`src/property.cpp` + `include/fgl/props.def`: на каждый шаблон — `constexpr`
-массив `{enum, имя, base_type, RO, min/max}`; конверсии `adjust_temperature`
-(×0.1 °C), `display_temperature` ((v−5000)/100), направления 0..num_dir−1;
-битовые декодеры `op_status` / `device_capabilities` (§8.4–8.5).
+## 7. HTTP и JSON: оценка готовых библиотек (решение)
 
-## 7. Структура репозитория
+Требования: no-heap после init, один код для ESP-IDF и POSIX, точный
+контроль поведения (keep-alive/RST-quirks модуля измерены на приборе),
+малый footprint.
 
-```
-fglair-core/
-  include/fgl/            # публичные заголовки (C++20 + c_api.h extern "C")
-  src/                    # ядро (портативное)
-  platform/posix/         # sockets/std::thread/timerfd/getrandom
-  platform/esp-idf/       # lwip/esp_timer/esp_random (+ idf_component CMakeLists)
-  test/unit/              # KDF, envelope, json, property, cmdq (doctest/catch2)
-  test/integration/       # python mock-модуль (эталон probe_reference.py) + runner
-  tools/probe_reference.py# эталонный клиент, проверенный на приборе
-  tools/fglair-discover   # CLI: облачный discovery -> печать/сохранение конфига
-  examples/cli/           # fglctl (linux): status/set/monitor
-  CMakeLists.txt          # linux build + tests
-  README.md
-```
+**JSON (парсер):**
+| Кандидат | Оценка |
+|----------|--------|
+| ESP-IDF `cJSON`/`esp_json` | DOM + malloc на узлы → конфликтует с no-heap; IDF-only |
+| ArduinoJson (есть в ESPHome) | v7 лишился zero-alloc-режима (StaticJsonDocument удалён); тянет зависимость ESPHome |
+| RapidJSON (SAX + custom allocator) | Подходит технически, но тяжеловат (~10k строк) для наших 5 форматов сообщений |
+| **jsmn (MIT, 2 файла, ~300 строк)** | **Принято**: токеновый парсер без аллокаций, стандарт де-факто embedded, раньше входил в ESP-IDF. Вендорим в `third_party/jsmn/` — единый код для обеих платформ |
 
-Зависимости: mbedtls (IDF встроен; Linux — системный или FetchContent 3.x),
-Python 3 (тесты/инструменты). Оценка ресурсов (ESP32, IDF): RAM < 20 КБ на
-сессию, код ядра ~35–50 КБ + mbedtls.
+Writer — собственный, с фиксированным буфером (~100 строк; наши данные не
+требуют сложного экранирования).
 
-## 8. Провижининг (вне библиотеки)
+**HTTP-сервер (входящие от модуля) и HTTP-клиент (local_reg):**
+| Кандидат | Оценка |
+|----------|--------|
+| ESP-IDF `esp_http_server` | Есть, но: IDF-only (нужна вторая реализация для POSIX); роутинг по IP клиента — хак (`httpd_req_to_sockfd` + getpeername); меньше контроля над keep-alive/RK-quirks |
+| cpp-httplib (POSIX) | Удобен, но heap + вторая ветка кода; LGPL/MIT ок |
+| mongoose / civetweb / libmicrohttpd | Лицензии/вес избыточны |
 
-* `fglair-discover` (Python): вход e-mail/пароль/регион → облачные endpoints
-  (PROTOCOL.md §7) → печать `dsn, ip, oem_model, lanip_key, lanip_key_id` и
-  сохранение json-конфига (формат `config_kata.json`). Тот же код кладётся в
-  HA-интеграцию (config flow) и используется standalone для ESPHome-пользователей.
-* Рантайм-обновления ключа НЕТ. Несовпадение `key_id` = `key_error`,
-  лечение — редактирование конфига вручную (для HA — repair-флоу с повторным
-  облаком; для ESPHome — копирование ключа из диагностики HA или повторный
-  запуск CLI).
+**Решение:** собственный мини-httpd + мини-httpc в `src/ayla` (~300+100
+строк) поверх BSD-сокетов — lwip на ESP32 и glibc дают идентичный API, одна
+реализация, полный контроль. `esp_http_server`/третьилицевые httpd НЕ
+используем. HTTP-клиент (один POST/PUT с Content-Length) — тривиален.
 
-## 9. Тестирование
+**Conan:** не нужен — единственная внешняя зависимость (jsmn) вендорится.
+Если позже появятся POSIX-only зависимости (например, TLS для облачного
+инструмента) — подключить conan только для POSIX-ветки.
 
-1. **Unit**: KDF-векторы; envelope roundtrip (оба варианта паддинга); CBC-
-   цепочка (3 сообщения подряд); JSON writer/reader fuzz; coalescing; таблицы.
-2. **Mock-модуль** (`test/integration/mock_ac.py`, развитие probe_reference.py):
-   сценарии: обычная сессия; re-key по возрасту 44 с (ускоренный таймер);
-   503-слоты; «KE без poll»; потеря сообщения → 401 → восстановление на
-   следующем keep-alive; delete_session.
-3. **On-device** (чек-лист, фактически повторяет проведённые пробы):
-   старт/активация ≤5 с; GET всех свойств; запись + оптимистичное обновление;
-   24 ч uptime с keep-alive 15 с (лог: re-key каждые 45–60 с, 0 потерь);
-   параллельно телефон; перезапуск прибора питанием.
-4. CI: gcc+clang -Wall -Werror, asan/ubsan (unit+mock), idf-сборка esp32.
+## 8. Таблицы свойств и конверсии (src/aircon)
 
-## 10. Этапы (milestones)
+`constexpr`-массивы на шаблон: `{enum, имя, base_type, RO, диапазон raw,
+конверсия по умолчанию, словари перечислений}`. Битовые декодеры
+`op_status`/`device_capabilities` (PROTOCOL §8.4–8.5). Точка расширения —
+`fgl_prop_override` (§4). Интроспекция `fgl_template_info_get` используется
+HA-превью (PLAN_HOME_ASSISTANT §4) и тестами.
+
+## 9. Тесты (разделение как у src)
+
+* `tests/ayla/` — протокол: KDF-векторы; envelope roundtrip (оба паддинга);
+  CBC-цепочка (3 сообщения); мини-httpd/httpc (запросы модуля, keep-alive,
+  RST); очередь/coalescing/pacing; машина состояний с mock-модулем
+  (`tests/ayla/mock_ac.py` — развитие probe_reference.py): обычная сессия,
+  re-key по возрасту, 503-слоты, «KE без poll», потеря сообщения → 401 →
+  восстановление, delete_session.
+* `tests/aircon/` — конверсии и шаблоны: все свойства всех шаблонов;
+  линейные/функциональные override; диапазоны; битмаски; согласованность
+  таблиц с PROTOCOL §8 (значения из APK).
+* CI: gcc+clang `-Wall -Werror`, asan/ubsan, ctest; idf-сборка esp32.
+
+## 10. Этапы
 
 | # | Содержимое | Критерии приёмки |
 |---|------------|------------------|
-| M0 | Каркас, платслой, логирование, CMake+IDF, CI | Собирается на linux и esp-idf; пустой HTTP-сервер отвечает 404 |
-| M1 | Крипто: KDF + envelope + векторы | Векторы зелёные; совместимость с probe_reference.py |
-| M2 | Сессия с mock-модулем: local_reg→KE→активация (poll)→GET→push; keep-alive | Mock-сценарий «обычная сессия»; на приборе: активация ≤5 с, свойства читаются |
-| M3 | Очередь с coalescing, 206/200, batch, записи+оптимистичный кэш | На приборе: batch из 5 команд = 1 local_reg notify; значения применяются |
-| M4 | re-key по возрасту, 401-обработка, 503/слоты, режим «KE без poll» (backoff), delete_session | Mock-сценарии + 2 ч на приборе без рассинхрона; stop() освобождает слот |
-| M5 | Таблицы A/B/F + конверсии; fglctl; fglair-discover; probe_reference.py в tools/ | 24 ч на приборе: 0 рассинхронов, re-key каждые 45–60 с |
-| M6 | (Опционально) mDNS-обнаружение (запрос на :10276), FglHub на N устройств | Устройство найдено без статического IP |
+| M0 | Монорепо-каркас: CMake (корень) + IDF-подключение, платслой, лог, CI | Собирается linux+esp-idf; пустой httpd отвечает 404 |
+| M1 | `src/ayla`: crypto+envelope, мини-httpd/httpc, jsmn-вендор | Векторы зелёные; httpd-тесты; совместимость с probe_reference.py |
+| M2 | `src/ayla`: сессия (установка/активация/keep-alive/re-key/слоты/503/delete) с mock-модулем | Все сценарии mock; на приборе: активация ≤5 с, re-key каждые 45–60 с |
+| M3 | `src/aircon`: шаблоны, конверсии+override, публичный API, batch | `tests/aircon` зелёные; на приборе: чтение всех свойств, batch=1 notify |
+| M4 | fglctl-пример, `tools/fglair-discover` (в т.ч. `--format esphome-secrets`), README библиотеки (сборка IDF/POSIX, тесты) | 24 ч на приборе: 0 рассинхронов; README готов |
+| M5 | (Опция) `FglHub` N устройств; mDNS-резолвер как опция host-разрешения | Два устройства одновременно |
 
-## 11. Риски и открытые вопросы
+README.md библиотеки (после M4, для людей): сборка в ESP-IDF (как
+компонент), сборка POSIX (cmake), запуск тестов (ctest + mock), краткий
+пример API. Максимально коротко.
 
-* Режим «KE без poll» (PROTOCOL.md §4.4 п.6) — причина не идентифицирована;
-  стратегия (пауза 30–60 с) подобрана эмпирически; заложить телеметрию для
-  уточнения.
-* `display_temperature` → °C: формула (v−5000)/100 c округлением к 0.25;
-  расхождение с таблицей приложения ≤ 0.25 °C.
-* Порог re-key ≈44 с измерен в границах 39–44 с — для надёжности опираться
-  не на точное значение, а на факт «KE может прийти с любым local_reg».
-* В ESPHome/Arduino-сборках esp_http_server может быть занят портом 80 —
-  ядро использует собственный мини-httpd на lwip-сокетах, конфликтов нет.
+## 11. Приёмка ESPHome↔HA (скрипт в `tests/acceptance/`)
+
+Полуавтоматизированный тест сквозной согласованности двух интеграций,
+работающих с одним кондиционером (занимают оба слота модуля — скрипт сам
+третью сессию НЕ открывает). Детали и авторизация — PLAN_ESPHOME §8 /
+PLAN_HOME_ASSISTANT §7 (HA long-lived access token + REST API — проверено,
+стандартный механизм; ESPHome — официальный `aioesphomeapi`).
+Режимы: `quick` (матрица изменений burst/не-burst, обе стороны, с
+возвратом) и `--long` (24 ч, раз в час одно изменение с проверкой и
+возвратом; CSV-отчёт). Запускается вручную; входит в чек-лист релиза.
+
+## 12. Риски
+
+* Режим «KE без poll» (PROTOCOL §4.4 п.6) — причина не идентифицирована;
+  стратегия (пауза 30–60 с) эмпирическая; заложить телеметрию.
+* Порог re-key ≈44 с (границы 39–44 с) — не опираться на точное значение.
+* Конверсии через `int32_t num/den` — следить за переполнением (int64
+  промежуточно).