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 |