From 76596408e1bc253f6cb2728ec24db2c926a37477 Mon Sep 17 00:00:00 2001 From: Alexander Date: Sun, 21 Jun 2026 00:51:10 +0300 Subject: [PATCH] =?UTF-8?q?docs(data-model):=20=D1=80=D0=B5=D1=82=D1=80?= =?UTF-8?q?=D0=BE-=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=20(5=20=D0=BD=D0=B0=D1=85?= =?UTF-8?q?=D0=BE=D0=B4=D0=BE=D0=BA)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dtc_count диапазон 0..255 → 0..127 (поле 7-битное) - добавлено runtime-поле quality (valid/stale/unavailable) + max_age, ортогонально статической availability (синхрон с ipc GetSignal/SignalChanged) - §3: детект Mode 03/07/0A через trial-read (нет support-bitmask); пустой PID 0x00 не каскадит «всё Unavailable»; MVP (mil_on + Mode 03) не зависит от пробинга - убран ложный ярлык «SI» (km/h, rpm, °C — не СИ) → «канонический набор единиц» - module_voltage: отметка, что property в ipc = ModuleVoltage Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/contracts/data-model.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/contracts/data-model.md b/docs/contracts/data-model.md index 269600b..c1f320c 100644 --- a/docs/contracts/data-model.md +++ b/docs/contracts/data-model.md @@ -26,18 +26,20 @@ | `id` | канонический VSS-стиль путь (напр. `Vehicle.Speed`) | | `alias` | короткое имя для эргономики (`speed`) | | `type` | `float` / `int` / `bool` / `enum` | -| `unit` | каноническая единица (**SI-стиль**: km/h, rpm, °C, V, %, g/s, kPa) | +| `unit` | каноническая единица (**фиксированный набор**, метрические/авто-конвенциональные — часть не-СИ: km/h, rpm, °C, V, %, g/s, kPa) | | `range` | допустимый диапазон | | `source` | откуда читается: OBD-PID / native-CAN(DBC) / **computed** | -| `availability` | поддерживается ли данной машиной (динамически) | -| `ts` | метка времени значения (для свежести) | +| `availability` | **статически**: поддерживается ли PID данной машиной (пробинг на старте) | +| `quality` | **рантайм-валидность значения**: `valid` / `stale` / `unavailable` (таймаут, двигатель заглушен) — ортогонально `availability` | +| `max_age` | порог свежести (per-signal): старше → `quality=stale` | +| `ts` | метка времени значения | **Транспорт-агностичность (важно):** сигнал каноничен, а **источник — это per-vehicle маппинг.** Один и тот же `Vehicle.Speed` может читаться через ELM327 (OBD-PID `0x0D`) или нативный SocketCAN (сигнал из DBC). Это и есть мост «ELM327 на старте → SocketCAN в проде» и основа портирования под разные авто (см. [hardware.md](hardware.md)). -**Единицы и локаль:** в модели — каноническая SI; отображение (km vs miles) — +**Единицы и локаль:** в модели — канонический набор единиц; отображение (km vs miles) — дело shell/настроек, конвертация на презентации, не в модели. ## 3. Доступность сигналов (per-vehicle) @@ -47,6 +49,16 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд сигнал `Unavailable`, если его нет. Консьюмеры (ассистент, UI) обязаны это учитывать — «нет данных», а не падение (принцип #4). +**Сервисные функции (Mode 03/07/0A DTC) — детектятся отдельно:** support-bitmask у +них нет, feature-detection = trial-read (валидный ответ → есть; NACK/timeout → нет). + +**Если пробинг (PID 0x00) пуст/недоступен — НЕ каскадим «всё Unavailable»:** fallback +на best-effort прямой опрос приоритетного набора PID + trial Mode 03. **MVP killer-фичи** +(`mil_on` PID 01 + DTC Mode 03) **не зависит от bitmask-пробинга** — доступность +определяется прямым чтением этих PID/сервисов. + +> Рантайм-устаревание (≠ статической доступности) несёт поле `quality` (§2), синхрон с ipc. + ## 4. Каталог стартовых сигналов (OBD-II Mode 01) > `id` — наш канонический путь (≈ VSS, **точные VSS-листы сверяем со спецификацией @@ -54,7 +66,7 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд > > **`mil_on` (PID 0x01) — ключевой для killer-фичи** «почему горит чек»: это сам > факт горящей лампы + число ошибок, отдельно от их чтения (Mode 03). -> `module_voltage` (0x42) — напряжение питания ЭБУ ≈ бортсеть (близко, но не ровно клеммы АКБ). +> `module_voltage` (0x42) — напряжение питания ЭБУ ≈ бортсеть (близко, но не ровно клеммы АКБ); property в ipc — `ModuleVoltage`. | alias | id (≈ VSS) | PID | type | unit | range | |-------|-----------|-----|------|------|-------| @@ -73,7 +85,7 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд | `fuel_rate` | `…CombustionEngine.FuelRate` | 0x5E | float | L/h | 0..3212 | | `run_time` | `…CombustionEngine.RunTime` | 0x1F | int | s | 0..65535 | | `mil_on` | `Vehicle.OBD.IsMILOn` | 0x01 | bool | — | вкл/выкл | -| `dtc_count` | `Vehicle.OBD.DTCCount` | 0x01 | int | шт | 0..255 | +| `dtc_count` | `Vehicle.OBD.DTCCount` | 0x01 | int | шт | 0..127 (7-бит) | | `distance_mil` | `Vehicle.OBD.DistanceWithMIL` | 0x21 | int | km | 0..65535 | ## 5. Производные (computed) сигналы @@ -131,5 +143,6 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд |---------|-------|------| | Глубина VSS | лёгкий VSS-aligned каталог (🟡 на подтверждение) | 2026-06-16 | | Источник сигнала | транспорт-агностичен: канон + per-vehicle маппинг (PID / DBC / computed) | 2026-06-16 | -| Единицы | каноническая SI в модели; конвертация на презентации | 2026-06-16 | +| Единицы | канонический набор единиц (метрич./авто-конвенц., часть не-СИ); конвертация на презентации | 2026-06-16 | +| Валидность значения | runtime-поле `quality` (valid/stale/unavailable) + `max_age`, ортогонально `availability` | 2026-06-16 | | DTC | чтение Modes 03/07/0A; сброс (04) запрещён; расшифровка база + LLM | 2026-06-16 |