From 01119a4ccf5528ec65296f3e5f49a289a1c8f825 Mon Sep 17 00:00:00 2001 From: Alexander Date: Sat, 20 Jun 2026 20:29:07 +0300 Subject: [PATCH] =?UTF-8?q?docs(domain=20E):=20Vehicle-Data=20=E2=80=94=20?= =?UTF-8?q?=D1=81=D0=BF=D0=B5=D0=BA=D0=B0=20+=20=D1=80=D0=B5=D0=B2=D1=8C?= =?UTF-8?q?=D1=8E-=D1=84=D0=B8=D0=BA=D1=81=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - спека домена E по шаблону: назначение/границы, функции (MVP/later), данные/интерфейсы, зависимости, открытые вопросы, журнал решений - MVP-ядро killer-фичи: MIL-статус (PID 01) + чтение DTC (Mode 03), универсально - ревью: покрытие OBD-протоколов (не-CAN старые авто → ELM327 мульти-протокол), OBD-порт ≠ все шины, коалесцированный опрос, объём DTC-базы, ELM327-клоны, staleness Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/domains/e-vehicle-data.md | 99 ++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/domains/e-vehicle-data.md diff --git a/docs/domains/e-vehicle-data.md b/docs/domains/e-vehicle-data.md new file mode 100644 index 0000000..c0f93d5 --- /dev/null +++ b/docs/domains/e-vehicle-data.md @@ -0,0 +1,99 @@ +# Домен E — Vehicle-Data (OBD/CAN, read-only) + +> Привилегированный core-сервис: **единственный владелец доступа к CAN/OBD**. Читает +> данные машины, публикует сигналы на шину, читает DTC. Сердце killer-фичи. + +Статус: **v1 (на ревью).** +Связано с: [ipc.md](../contracts/ipc.md) (`VehicleData`) · [data-model.md](../contracts/data-model.md) · [hardware.md](../contracts/hardware.md) (CAN) · [security-privacy.md](../contracts/security-privacy.md) · [principles.md](../principles.md) (#2) · домен D (Assistant) + +--- + +## 1. Назначение и границы + +- **Что делает:** читает OBD-II (PID/DTC) и/или broadcast-кадры (native CAN + DBC), + перемалывает в digested-сигналы ([data-model](../contracts/data-model.md)), + публикует через `ru.shturman.VehicleData` ([ipc](../contracts/ipc.md) §3). +- **Единственный, кто трогает CAN** → архитектурно держит red-line (принцип #2). +- **Границы (точный red-line):** только диагностические **read-запросы** + пассивное + чтение; **никаких** управляющих/actuator/write/Mode-04. Человеческую расшифровку + НЕ делает (это LLM/ассистент) — отдаёт код + стандартное описание. + +## 2. Функции + +| функция | MVP/later | зависит от | фаза | +|---------|-----------|------------|------| +| Live-сигналы (стандартные PID) | **MVP** | data-model, hardware(CAN) | v2 | +| **MIL-статус + DTC count** (PID 01) | **MVP** | — | v2 | +| Чтение DTC (Mode 03) + расшифровка по базе | **MVP** | dtc-база | v2 | +| Пробинг поддерживаемых PID | **MVP** | — | v2 | +| Состояние машины (`off`/`acc`/`running`) | **MVP** | — | v2 | +| Подписка с rate-cap (~10–20 Гц) | **MVP** | ipc | v2 | +| Pending/permanent DTC (Mode 07/0A) | later | — | v2+ | +| Производные (расход / trip) | later | trip-стейт, storage | v2/v3 | +| Топливные коррекции (fuel trim 06–09) — «вырос расход» | later | — | later | +| VIN (Mode 09) | later | — | later | +| Пассивный сниффинг broadcast (DBC) | later | native CAN, DBC | later | +| Vendor DTC (`P1xxx`) через vendor-базу | later | vendor DB | later | +| Лог поездок | later | storage | later | + +## 3. Данные и интерфейсы + +- **Публикует:** `ru.shturman.VehicleData` (методы/сигналы/properties — [ipc](../contracts/ipc.md) §3). +- **Сигналы** — по каталогу [data-model](../contracts/data-model.md); транспорт-агностичны. +- **Источник:** ELM327 (serial/BT) и нативный **SocketCAN** (крейт `socketcan`). +- **Покрытие протоколов (важно для старых авто):** OBD-II ходит поверх разных нижних + протоколов. **Native SocketCAN — только CAN-based OBD** (авто ~2008+). Старые не-CAN + (K-line ISO 9141/KWP2000, J1850) — через **ELM327** (мульти-протокольный). Поэтому + ELM327-путь держим живым, не только «на старте» — это охват простых Lada/ретрофита. +- **Опрос коалесцируется:** один PID опрашивается раз на максимальной запрошенной + частоте, результат раздаётся всем подписчикам (не per-subscriber). +- **DTC-база** (статическая, `vehicle/dtc/`) — живёт в этом домене. + +## 4. Приоритизация под простые авто *(резолв routed-вопроса)* + +- **MVP killer-фичи опирается на универсальное:** `mil_on` (PID 01) + DTC (Mode 03) — + поддержано почти везде, даже на простых Lada. +- Богатые PID — **best-effort** по результату пробинга. +- **ELM327 медленный** (несколько PID/сек) → на старте опрашиваем малый приоритетный + набор + DTC; native CAN быстрее. + +## 5. DTC-расшифровка + +- **Структура кода информативна сама по себе** (буква = подсистема, см. [data-model](../contracts/data-model.md) §6) + — даёт базовую категоризацию даже для незнакомого кода. +- **Статическая база:** не обязательно ВСЕ тысячи generic-кодов сразу — стартуем с + частых + алгоритмический разбор структуры, пополняем. RU-описания, `vehicle/dtc/`. +- **LLM (ассистент)** даёт человеческое объяснение (модели знают стандартные коды); + **офлайн-режиму нужна статическая база** — для надёжности и против галлюцинаций кода. +- 🟡 *Выбор:* своя **RU-база из открытых списков** generic-кодов (рек.) vs готовая. + Vendor-коды (`P1xxx`) — later, через vendor-базы. + +## 6. Зависимости + +- **Вниз:** hardware (CAN-транспорт, listen-only/polling), data-model (каталог), + ipc (контракт сервиса), principles #2 (red-line), security-privacy (привилегированное + ядро, единственный владелец CAN). +- **Потребители:** Assistant (D) — контекст в промпт; Shell (C) — датчики/виджеты; + плагины — `vehicle_read`. + +## 7. Открытые вопросы + +- 🟡 **DTC-база:** своя RU из открытых списков (рек.) vs готовая. +- ◻️ **Точность производного расхода** (зависит от типа топлива) — см. [data-model](../contracts/data-model.md) §5. +- ◻️ **«Вырос расход»:** набор диагностических сигналов (fuel trim, O2) — later. +- ◻️ **Vendor DBC/коды** — порт под конкретное авто (HAL/BSP, [data-model](../contracts/data-model.md) §7). +- ◻️ **OBD-порт ≠ все шины.** Powertrain-шина на порту; кузов/комфорт/кнопки руля — + на других CAN-шинах, нужен тап конкретной шины. → [hardware.md](../contracts/hardware.md) + data-model §7. +- ◻️ **ELM327-клоны** капризны (баги прошивки, тайминги) — симулятор должен эмулировать их причуды. → [dev-environment.md](../dev-environment.md). +- ◻️ **Runtime-staleness:** таймаут ответа / двигатель заглушен → помечать сигнал `stale`/`unavailable`, не висеть. + +--- + +## Журнал решений (домен E) + +| Решение | Выбор | Дата | +|---------|-------|------| +| Транспорт | ELM327 (старт) → нативный SocketCAN; транспорт-агностичные сигналы | 2026-06-16 | +| MVP-ядро | `mil_on` (PID 01) + DTC (Mode 03) — универсально; богатые PID best-effort | 2026-06-16 | +| DTC-база | своя RU из открытых generic-списков (🟡); vendor-коды later | 2026-06-16 | +| Расшифровка | статическая база (код→описание) + LLM (человеческое объяснение) | 2026-06-16 |