docs(data-model): ретро-ревью (5 находок)

- 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) <noreply@anthropic.com>
This commit is contained in:
2026-06-21 00:51:10 +03:00
parent 2a9f9925cc
commit 76596408e1
+20 -7
View File
@@ -26,18 +26,20 @@
| `id` | канонический VSS-стиль путь (напр. `Vehicle.Speed`) | | `id` | канонический VSS-стиль путь (напр. `Vehicle.Speed`) |
| `alias` | короткое имя для эргономики (`speed`) | | `alias` | короткое имя для эргономики (`speed`) |
| `type` | `float` / `int` / `bool` / `enum` | | `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` | допустимый диапазон | | `range` | допустимый диапазон |
| `source` | откуда читается: OBD-PID / native-CAN(DBC) / **computed** | | `source` | откуда читается: OBD-PID / native-CAN(DBC) / **computed** |
| `availability` | поддерживается ли данной машиной (динамически) | | `availability` | **статически**: поддерживается ли PID данной машиной (пробинг на старте) |
| `ts` | метка времени значения (для свежести) | | `quality` | **рантайм-валидность значения**: `valid` / `stale` / `unavailable` (таймаут, двигатель заглушен) — ортогонально `availability` |
| `max_age` | порог свежести (per-signal): старше → `quality=stale` |
| `ts` | метка времени значения |
**Транспорт-агностичность (важно):** сигнал каноничен, а **источник — это **Транспорт-агностичность (важно):** сигнал каноничен, а **источник — это
per-vehicle маппинг.** Один и тот же `Vehicle.Speed` может читаться через ELM327 per-vehicle маппинг.** Один и тот же `Vehicle.Speed` может читаться через ELM327
(OBD-PID `0x0D`) или нативный SocketCAN (сигнал из DBC). Это и есть мост «ELM327 на (OBD-PID `0x0D`) или нативный SocketCAN (сигнал из DBC). Это и есть мост «ELM327 на
старте → SocketCAN в проде» и основа портирования под разные авто (см. [hardware.md](hardware.md)). старте → SocketCAN в проде» и основа портирования под разные авто (см. [hardware.md](hardware.md)).
**Единицы и локаль:** в модели — каноническая SI; отображение (km vs miles) — **Единицы и локаль:** в модели — канонический набор единиц; отображение (km vs miles) —
дело shell/настроек, конвертация на презентации, не в модели. дело shell/настроек, конвертация на презентации, не в модели.
## 3. Доступность сигналов (per-vehicle) ## 3. Доступность сигналов (per-vehicle)
@@ -47,6 +49,16 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд
сигнал `Unavailable`, если его нет. Консьюмеры (ассистент, UI) обязаны это сигнал `Unavailable`, если его нет. Консьюмеры (ассистент, UI) обязаны это
учитывать — «нет данных», а не падение (принцип #4). учитывать — «нет данных», а не падение (принцип #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) ## 4. Каталог стартовых сигналов (OBD-II Mode 01)
> `id` — наш канонический путь (≈ VSS, **точные VSS-листы сверяем со спецификацией > `id` — наш канонический путь (≈ VSS, **точные VSS-листы сверяем со спецификацией
@@ -54,7 +66,7 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд
> >
> **`mil_on` (PID 0x01) — ключевой для killer-фичи** «почему горит чек»: это сам > **`mil_on` (PID 0x01) — ключевой для killer-фичи** «почему горит чек»: это сам
> факт горящей лампы + число ошибок, отдельно от их чтения (Mode 03). > факт горящей лампы + число ошибок, отдельно от их чтения (Mode 03).
> `module_voltage` (0x42) — напряжение питания ЭБУ ≈ бортсеть (близко, но не ровно клеммы АКБ). > `module_voltage` (0x42) — напряжение питания ЭБУ ≈ бортсеть (близко, но не ровно клеммы АКБ); property в ipc — `ModuleVoltage`.
| alias | id (≈ VSS) | PID | type | unit | range | | 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 | | `fuel_rate` | `…CombustionEngine.FuelRate` | 0x5E | float | L/h | 0..3212 |
| `run_time` | `…CombustionEngine.RunTime` | 0x1F | int | s | 0..65535 | | `run_time` | `…CombustionEngine.RunTime` | 0x1F | int | s | 0..65535 |
| `mil_on` | `Vehicle.OBD.IsMILOn` | 0x01 | bool | — | вкл/выкл | | `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 | | `distance_mil` | `Vehicle.OBD.DistanceWithMIL` | 0x21 | int | km | 0..65535 |
## 5. Производные (computed) сигналы ## 5. Производные (computed) сигналы
@@ -131,5 +143,6 @@ PID** (Mode 01, PID `0x00/0x20/0x40/…` — битовые маски подд
|---------|-------|------| |---------|-------|------|
| Глубина VSS | лёгкий VSS-aligned каталог (🟡 на подтверждение) | 2026-06-16 | | Глубина VSS | лёгкий VSS-aligned каталог (🟡 на подтверждение) | 2026-06-16 |
| Источник сигнала | транспорт-агностичен: канон + per-vehicle маппинг (PID / DBC / computed) | 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 | | DTC | чтение Modes 03/07/0A; сброс (04) запрещён; расшифровка база + LLM | 2026-06-16 |