From 9e685edd028b6d4f99b0d53eaded208b06506dd1 Mon Sep 17 00:00:00 2001 From: Alexander Date: Sat, 20 Jun 2026 19:28:16 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=BB=D0=BE=D0=B6=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D1=83=D0=BD=D0=B4=D0=B0=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B8=D1=80=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D0=B8=D1=8F=20=D0=A8=D1=82=D1=83=D1=80=D0=BC?= =?UTF-8?q?=D0=B0=D0=BD=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Каркас документации + содержательный фундамент (фаза проектирования, реализация отложена): - vision: видение, позиционирование, границы (вариант B, 2 красные линии) - principles: 13 сквозных принципов (red lines, offline-first, power-safe…) - architecture: тонкое ядро + SDK, planes, lifecycle, песочница, хостинг UI, карта связей + журнал из 6 решений - dev-environment: разработка с Mac (Lima/ARM64, vcan, Vehicle Simulator) - индексы contracts/ и domains/ (+ единый шаблон домена, заделы по камерам) - заготовки glossary, capability-catalog, roadmap Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 20 ++++ docs/README.md | 37 +++++++ docs/architecture.md | 218 +++++++++++++++++++++++++++++++++++++ docs/capability-catalog.md | 12 ++ docs/contracts/README.md | 17 +++ docs/dev-environment.md | 132 ++++++++++++++++++++++ docs/domains/README.md | 47 ++++++++ docs/glossary.md | 27 +++++ docs/principles.md | 75 +++++++++++++ docs/roadmap.md | 18 +++ docs/vision.md | 168 ++++++++++++++++++++++++++++ 11 files changed, 771 insertions(+) create mode 100644 .gitignore create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/capability-catalog.md create mode 100644 docs/contracts/README.md create mode 100644 docs/dev-environment.md create mode 100644 docs/domains/README.md create mode 100644 docs/glossary.md create mode 100644 docs/principles.md create mode 100644 docs/roadmap.md create mode 100644 docs/vision.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2a71a95 --- /dev/null +++ b/.gitignore @@ -0,0 +1,20 @@ +# macOS +.DS_Store + +# Rust +/target/ +**/target/ + +# Python (dev-инструменты / Vehicle Simulator / скрипты) +__pycache__/ +*.py[cod] +.venv/ +venv/ + +# Редакторы +.idea/ +.vscode/ +*.swp + +# Локальные dev-артефакты +*.log diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3dadd20 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Штурман — документация проекта + +> Открытый русскоязычный программный слой («ОС поверх Linux») для автомобиля: +> быстрый красивый бортовой интерфейс + голосовой ассистент на русском, который +> видит данные машины и объясняет их по-человечески. Только чтение CAN, никогда +> не safety-critical. Лицензия **MIT**. + +**Статус: фаза проектирования.** Реализация сознательно отложена — сначала +проектируем всё от и до, связно и детально. Этот каталог `docs/` — единственный +источник правды по дизайну. + +## Карта документации + +### Tier 0 — фундамент +- [vision.md](vision.md) — зачем, что, чем НЕ является, моат, стратегия, границы. +- [glossary.md](glossary.md) — единый словарь терминов. +- [principles.md](principles.md) — сквозные принципы и ограничения (правила для всех доменов). +- [architecture.md](architecture.md) — слои, процессы, шина, **карта связей**. + +### Tier 1 — сквозные контракты (соединительная ткань) +- [contracts/](contracts/README.md) — IPC, модель данных, plugin-SDK, безопасность, железо. + +### Инфраструктура разработки +- [dev-environment.md](dev-environment.md) — как вести разработку изолированно, с Mac. + +### Tier 2 — домены +- [domains/](domains/README.md) — детальные спеки подсистем (A–L) по единому шаблону. + +### Tier 3 — планирование +- [capability-catalog.md](capability-catalog.md) — мастер-индекс всех функций (MVP/later + фаза). +- [roadmap.md](roadmap.md) — фазы реализации с зависимостями. + +## Как мы работаем + +Сверху вниз, по одному документу за раз: **предложение → правки → фиксация → +следующий.** Каждый домен потом получит отдельный цикл «спека → план → реализация» +(но реализация — позже, не сейчас). diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..35cc3b6 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,218 @@ +# Архитектура системы + +> Как устроен Штурман: слои, процессы, шина IPC, изоляция — и **карта связей** +> между компонентами. Это верхнеуровневый документ: домены (Tier 2) и контракты +> (Tier 1) ссылаются сюда. Все 6 базовых решений приняты — см. «Журнал решений». + +Статус: **v1 (на ревью).** +Связано с: [principles.md](principles.md) · [contracts/](contracts/README.md) · [domains/](domains/README.md) · [dev-environment.md](dev-environment.md) + +--- + +## 1. Главный принцип: тонкое ядро + всё на SDK + +Доверенное **ядро минимально** — только инфраструктура, безопасность и данные. +Всё прикладное (shell, ассистент, медиа, навигация, телефон) — отдельные процессы +на **том же SDK**, что и сторонние плагины (first-party получают расширенные +capabilities). Это делает открытый API не лозунгом, а основой: им пользуемся мы +сами. + +Ключевое следствие для безопасности: к «опасным» ресурсам (CAN, питание) +прикасается ровно один привилегированный сервис каждый. **Read-only CAN — не +правило, а физический факт:** к шине машины прикасается только Vehicle-Data, и в +нём нет write-кода. + +--- + +## 2. Слои + +``` +HARDWARE RK3588 · экран · CAN/OBD · GPS · mic-массив · power-path · камеры + │ +LINUX BASE read-only rootfs + overlay · Wayland · systemd · hardware watchdog + │ +TRUSTED CORE Power/Lifecycle · Vehicle-Data (CAN read-only) · Settings/State +(привилегии) Security/Perm-Broker · Plugin/App-Host · Connectivity + │ ──────────────── control plane: D-Bus ──────────────── +SDK единый API: D-Bus + биндинги (Rust, Python…) + манифест/capabilities + │ +FIRST-PARTY Shell/UX-host · Assistant (Py) · Media · Nav · Phone ← расш. права +APPS (на SDK) + │ +PLUGINS (3rd) плагин · плагин · … ← узкие права +``` + +Высокополосные данные (аудио/видео/графика) идут **не** через D-Bus, а через +data-plane — см. §4. + +--- + +## 3. Компоненты и процессная модель + +Каждый компонент — **отдельный процесс**. Падение одного не роняет остальные +(изоляция). Раздача привилегий — через Perm-Broker (§7). + +### Доверенное ядро (привилегированное, минимум) + +| Компонент | Роль | Почему в ядре | +|-----------|------|---------------| +| **Power/Lifecycle** | ACC-детект, graceful shutdown, sleep/wake, watchdog | владеет power-GPIO; критично для защиты от corruption | +| **Vehicle-Data** | читает CAN/OBD, публикует сигналы (VSS-like) на шину | единственный владелец железа CAN → гарантирует read-only | +| **Settings/State** | центральная конфигурация и состояние, пишет в `/data` | общий источник правды; единственный писатель в `/data`-конфиг | +| **Security/Perm-Broker** | выдаёт/режет capabilities по манифесту | привратник всех привилегий | +| **Plugin/App-Host** | запуск, супервизия, песочница апов и плагинов | посредник доступа к шине; владеет sandbox-механизмом | +| **Connectivity** | обёртка ModemManager/NetworkManager, статус сети | управляет сетевым железом | + +### First-party апы (отдельные процессы на SDK, расширенные права) + +| Ап | Кратко | Особое | +|----|--------|--------| +| **Shell/UX-host** | лаунчер, экраны, тема, driver-distraction | ещё и Wayland-**хост** UI остальных (§8) | +| **Assistant** | wake→STT→LLM→TTS, контекст машины, память о водителе (`.md`) | на Python; провайдер-агностик LLM | +| **Media** | аудио, BT A2DP/AVRCP, радио, стриминг | владеет аудио-политикой (с PipeWire) | +| **Nav** | офлайн-карты, роутинг | богатые поверхности (карта) | +| **Phone** | BT HFP, контакты, звонки | аудио через PipeWire | + +### Сторонние плагины + +Тот же SDK, **узкие** capabilities, запускаются и песочатся App-Host'ом, доступ к +привилегиям — только через Perm-Broker. API расширения — [contracts/plugin-sdk.md](contracts/plugin-sdk.md); +рантайм/дистрибуция/sandbox — домен F (`domains/f-plugin-host.md`). + +--- + +## 4. IPC: control plane vs data plane + +Принцип: **D-Bus — для управления и событий, не для медиа-потоков.** + +| Plane | Транспорт | Что несёт | +|-------|-----------|-----------| +| **Control** | **D-Bus** | методы, сигналы, свойства: команды, состояние, события, сигналы машины (VSS), интенты ассистента, настройки, выдача capabilities | +| **Audio/video** | **PipeWire** (+ WirePlumber) | микрофон ассистента, TTS-выход, медиа, BT-аудио, маршрутизация на усилитель | +| **Graphics** | **Wayland** | поверхности апов, сводимые shell-композитором (Panfrost/Mesa) | +| **Camera** | **PipeWire / V4L2 (DMABUF)** | видео-источники; самые латентные (задняя камера) — почти прямой путь | + +Нюанс: Vehicle-Data перемалывает сырой высокочастотный CAN **внутри себя** и +публикует на шину уже digested-сигналы в разумном темпе — шина остаётся лёгкой. + +Камеры спроектированы как **динамический набор 0..N источников** (задняя, +dashcam-фронтальная, surround), расширяемый плагинами — см. задел в +[domains/README.md](domains/README.md). + +--- + +## 5. Карта связей (кто с кем говорит) + +| От | К | Plane | Зачем | +|----|---|-------|-------| +| любой ап/плагин | Perm-Broker | D-Bus | проверка capabilities на каждую привилегию | +| App-Host | апы/плагины | процессы | запуск, супервизия, песочница, рестарт | +| Assistant | Vehicle-Data | D-Bus | live-контекст машины в промпт | +| Assistant | Connectivity → сеть | D-Bus/сеть | онлайн RU-LLM (GigaChat/YandexGPT) | +| Assistant, Media, Phone | PipeWire | audio | микрофон, TTS, музыка, BT-аудио | +| Nav, Shell | Vehicle-Data | D-Bus | скорость/положение для карты и виджетов | +| Nav, Media, камеры-виды | Wayland | graphics | богатые поверхности в слот shell | +| Shell | все апы | D-Bus + Wayland | хостинг UI: декларативные вклады + поверхности | +| все апы | Settings/State | D-Bus | чтение/запись настроек | +| Vehicle-Data | CAN/OBD | драйвер | **только чтение** | +| Power/Lifecycle | все | D-Bus сигналы | ACC-on/off, shutdown, sleep | + +```mermaid +graph TD + Apps["Апы и плагины (SDK, песочница)"] + Broker["Perm-Broker"] + AppHost["App-Host"] + Vehicle["Vehicle-Data (read-only)"] + Power["Power / Lifecycle"] + Settings["Settings / State"] + Conn["Connectivity"] + PW["PipeWire (audio/video)"] + WL["Wayland (в Shell)"] + CAN[("CAN / OBD")] + Net(("Сеть / RU-LLM")) + + Apps -->|"capabilities"| Broker + AppHost -.->|"запуск/супервизия"| Apps + Apps -->|"read сигналы"| Vehicle + Apps -->|"конфиг"| Settings + Apps -->|"аудио"| PW + Apps -->|"поверхности"| WL + Apps -->|"онлайн"| Conn + Conn --> Net + Vehicle ==>|"READ-ONLY"| CAN + Power -.->|"lifecycle"| AppHost +``` + +--- + +## 6. Жизненный цикл и загрузка + +**Кто кого супервизит:** +- **systemd** — доверенные системные сервисы ядра (+ App-Host и Shell). Рестарт при падении, watchdog. +- **App-Host** — динамические апы и сторонние плагины (жизненный цикл по манифесту, песочница, своя политика рестарта). + +**Быстрый boot фазами (цель — < 10 c до интерактива):** +- **Stage 0 (мгновенно):** загрузчик → splash. Низколатентный путь задней камеры/парктроника, если включена задняя. +- **Stage 1 (~3–5 c):** ядро-минимум (шина + Power + Settings) → **Shell с первым кадром** (home-тайлы кликабельны). +- **Stage 2 (фоном):** Vehicle-Data, Assistant, Media, Nav прогреваются после того, как UI интерактивен. + +**Завершение:** ACC-off → Power/Lifecycle инициирует graceful shutdown (systemd-таргет): апам сигнал «сохранись», Settings флашится в `/data`, размонтирование, снятие питания через supercap/MCU-копилот. Вместе с read-only rootfs это защита от corruption. + +**Устойчивость:** hardware watchdog + systemd-watchdog; зависший сервис ядра перезапускается, зависшая система — ребутается watchdog'ом. + +--- + +## 7. Изоляция и разрешения + +Песочница — **defense-in-depth** поверх архитектурных гарантий (даже сбежавший +плагин не запишет в CAN — write-пути нет). + +- **Механизм:** апы/плагины — в **bubblewrap**-песочнице (namespaces, seccomp, минимальный FS); ядро — **systemd-hardening**. WASM — опциональный тир для лёгких логических плагинов позже. +- **Модель разрешений:** манифест декларирует capabilities (`vehicle_read:[…]`, `assistant_intents`, `ui_tiles`, `network`, `storage`…). **Perm-Broker — единственная дверь** к привилегиям (модель «порталов» как у Flatpak): плагин не трогает ресурсы напрямую, а просит брокера. +- **Грант:** first-party — авто; сторонние — показываем запрашиваемые capabilities при установке, пользователь подтверждает. + +Детали модели разрешений и приватности — [contracts/security-privacy.md](contracts/security-privacy.md). + +--- + +## 8. Хостинг UI в shell (гибрид / слоты) + +Shell — Wayland-хост; апы/плагины — отдельные песочные процессы. Их UI попадает на +экран двумя путями: + +- **Декларативные вклады** (данные/описание, **не код**) для частого/лёгкого: + home-тайлы, настройки, простые экраны плагинов, карточки ассистента. Рендерит + **сам shell** своими Slint-компонентами → единый стиль, безопасность (чужой код + в процесс shell не пускаем). +- **Wayland-поверхности** для богатых апов: нав-карта, медиа, камеры, GPU-тяжёлое. + Ап рисует у себя и отдаёт shell готовую поверхность. + +**Модель слотов:** shell задаёт слоты (грид home, полноэкранная зона, оверлей, +статус-бар); ап вкладывает либо декларативный элемент, либо поверхность. Так +консистентность UX (наш дифференциатор) сочетается с мощью и ложится на песочницу. + +--- + +## 9. Что вынесено в другие документы (связи) + +- **Интерфейсы шины** (имена сервисов, методы, схемы) → [contracts/ipc.md](contracts/ipc.md). +- **Модель сигналов машины** (VSS-таксономия) → [contracts/data-model.md](contracts/data-model.md). +- **API расширения** (манифест, capability-модель, точки расширения) → [contracts/plugin-sdk.md](contracts/plugin-sdk.md). +- **Разрешения и приватность** (детали брокера, 152-ФЗ) → [contracts/security-privacy.md](contracts/security-privacy.md). +- **Железо и HAL/board-support** (питание, периферия, портирование) → [contracts/hardware.md](contracts/hardware.md). +- **Камеры как 0..N источников, dashcam/surround; парктроники** → [domains/README.md](domains/README.md) (заделы) → домены J/K. +- **Аудио-арбитраж (ducking/приоритеты)** → домены Media/Assistant (политика поверх PipeWire). +- **Ранний путь задней камеры (Stage 0)** → роадмап (объём работ) + домен J. + +--- + +## Журнал решений (architecture) + +| # | Решение | Выбор | Дата | +|---|---------|-------|------| +| 1 | Граница ядра | **Тонкое ядро + всё на SDK** | 2026-06-16 | +| 2 | Состав компонентов | Мин. доверенное ядро (6 сервисов) + first-party апы на SDK + плагины; Connectivity в ядре | 2026-06-16 | +| 3 | Control vs data plane | D-Bus (control) + PipeWire (audio/video) + Wayland (graphics) + V4L2/DMABUF (камеры) | 2026-06-16 | +| 4 | Lifecycle/boot | systemd (ядро) ↔ App-Host (апы/плагины); фазовый boot; graceful shutdown по ACC | 2026-06-16 | +| 5 | Песочница | bubblewrap + Perm-Broker (порталы), systemd-hardening ядра; WASM — тир позже | 2026-06-16 | +| 6 | Хостинг UI | Гибрид/слоты: декларативные вклады (shell рендерит) + Wayland-поверхности | 2026-06-16 | diff --git a/docs/capability-catalog.md b/docs/capability-catalog.md new file mode 100644 index 0000000..598250b --- /dev/null +++ b/docs/capability-catalog.md @@ -0,0 +1,12 @@ +# Каталог возможностей (мастер-индекс) + +> Единый список **всех** функций платформы со сквозными тегами. Заполняется по +> мере проработки доменов (Tier 2); служит источником для [roadmap.md](roadmap.md). + +Статус: **заготовка**. Колонки фиксированы: + +| ID | Функция | Домен | MVP / later | Фаза | Зависит от | Статус проработки | +|----|---------|-------|-------------|------|------------|-------------------| +| — | _TODO: наполняется по ходу проработки доменов_ | — | — | — | — | — | + +> Каждая строка домена-спеки должна иметь соответствие здесь — это сводный реестр. diff --git a/docs/contracts/README.md b/docs/contracts/README.md new file mode 100644 index 0000000..8b8572d --- /dev/null +++ b/docs/contracts/README.md @@ -0,0 +1,17 @@ +# Контракты (Tier 1) — соединительная ткань + +> Сквозные интерфейсы, которыми домены связаны друг с другом. **«Связи» проекта +> живут здесь.** Каждый контракт — отдельный документ; создаём по мере наполнения. + +Статус: **индекс**. Документы наполняем после фундамента (architecture + principles). + +| Документ | Назначение | +|----------|------------| +| `ipc.md` | D-Bus сервисы, интерфейсы, схемы сообщений: кто что публикует/слушает. | +| `data-model.md` | VSS-подобная таксономия сигналов машины + общие типы данных. | +| `plugin-sdk.md` | API расширения: манифест, capability-модель, точки расширения (экраны, тайлы, интенты, доступ к данным). *Рантайм плагинов — домен F.* | +| `security-privacy.md` | Sandboxing плагинов, модель разрешений, обработка данных, 152-ФЗ. | +| `hardware.md` | Целевой таргет (RK3588), топология питания, периферия + **HAL/board-support API** для портирования на другое железо/авто. | + +> Важный нюанс: **plugin-SDK** (API, тут) и **домен F «Plugin host»** (рантайм, +> sandbox, дистрибуция — в [domains/](../domains/README.md)) — разные вещи, ссылаются друг на друга. diff --git a/docs/dev-environment.md b/docs/dev-environment.md new file mode 100644 index 0000000..6af60ef --- /dev/null +++ b/docs/dev-environment.md @@ -0,0 +1,132 @@ +# Среда разработки + +> Как вести разработку Штурмана корректно и изолированно — не выходя с Mac, +> ничего не ломая, со спокойным тестированием подсистем без реального железа. + +Статус: **v1 (на ревью).** +Связано с: [architecture.md](architecture.md) · [principles.md](principles.md) (#13) · [contracts/hardware.md](contracts/hardware.md) + +--- + +## Цель + +- Вся разработка и тестирование с текущего **Mac**. +- **Изоляция:** эксперименты не трогают хост. +- **Безопасное тестирование** подсистем без машины. + +## Хост и что это даёт + +**Apple M4 (ARM64), 10 ядер, 16 ГБ, macOS 26.5.** + +- **ARM64-хост ↔ ARM64-таргет (RK3588).** Linux в ARM64-VM крутится нативно-быстро + через Apple Virtualization (без эмуляции). Бинари, собранные в VM, уже целевой + архитектуры. +- **QEMU-эмуляция** нужна только если захотим эмулировать сами периферии RK3588 — + редкий случай, не базовый поток. +- **16 ГБ RAM — единственное ограничение.** VM держим лёгкой; локальную офлайн-LLM + по умолчанию **мокаем**, реальную квантованную модель гоняем точечно (закрыв + лишнее) или уже на железке. + +## Изоляция «ничего не сломать» — бесплатно + +Весь Linux / CAN / systemd живёт **в VM**. Хост-Mac держит только редактор, +нативный Slint и менеджер VM. Сломал что-то в стеке — **сбросил VM, хост цел**. + +--- + +## Четыре слоя + +``` +L1 Mac host редактор · git · Rust-тулчейн · НАТИВНЫЙ Slint (быстрый UI) · justfile · Lima + │ +L2 Linux dev-VM systemd · D-Bus · SocketCAN(vcan) · PipeWire · Wayland(cage) + (Lima, vz, ← интегрированный стек; сервисы = systemd-юниты + bubblewrap (как в проде) + ARM64) + │ +L3 Симуляция Vehicle Simulator (vcan) · моки LLM/STT/TTS · фейк-GPS · мок-сеть + │ +L4 Реальный RK3588 (позже) сборка образа → флеш → путь «VM → железка» +``` + +## Стек инструментов + +| Задача | Инструмент | Зачем | +|--------|-----------|-------| +| Linux dev-VM | **Lima** (vz-backend) | нативная ARM64-виртуализация, open-source, scriptable YAML | +| Итерация UI | **нативный Slint на macOS** + `cage`/`weston` в VM | гибрид: быстрый дизайн-цикл + проверка реального Wayland | +| Виртуальный CAN | **SocketCAN `vcan`** (в VM) | тест Vehicle-Data без железа | +| Симуляция OBD | **ELM327-emulator** + `python-can` + `can-utils` | OBD-II PID и DTC без авто | +| Сборка Rust | **в VM** (та же арка) + кросс `aarch64-unknown-linux-gnu` с хоста | target-arch бинари | +| Аудио | **PipeWire** в VM | тест аудио-пайплайна | +| Изоляция сервисов | **systemd-юниты + bubblewrap** | dev зеркалит прод, а не Docker-огород | +| Оркестрация | **`justfile`** | единые dev-команды (`just vm-up`, `just sim`, `just test`…) | +| CI | **GitHub Actions, ARM64-Linux** | совпадает с таргетом | +| License-check | **`cargo-deny`** | принцип #12 (без AGPL-заразы) | + +--- + +## Vehicle Simulator (first-class актив) + +«Виртуальная машина» — то, чем тестируется killer-фича без авто. Реализует +принцип #13. Умеет: + +- писать реалистичные кадры в **vcan**; +- отвечать на **OBD-II PID-запросы** (ELM327-стиль и raw CAN); +- **инжектить/чистить DTC** (set/clear) — для теста расшифровки и объяснения; +- проигрывать реальные **CAN-дампы** (`candump` → `canplayer`); +- гонять сценарии: холостой / езда / неисправность. + +Строим тонко поверх `can-utils` (`cangen`/`candump`/`canplayer`), `python-can`, +ELM327-emulator. **Эталонный тест killer-фичи:** симулятор инжектит `P0420` → +ассистент через Vehicle-Data → контекст → объясняет по-русски. + +## Моки + +- **LLM** — заглушка (canned-ответы/echo) или крошечная локальная модель. +- **STT** — обход голоса вводом текста; **TTS** — тихий/лог-режим. +- **GPS** — NMEA-реплей; **модем/сеть** — управляемые состояния (для теста offline-first). + +--- + +## Воспроизводимость + +- **Lima-шаблон** (`lima.yaml`): Ubuntu ARM64, модули (`vcan`), пакеты (systemd, + dbus, pipewire, cage, can-utils, rust, python). +- **Provisioning-скрипт** + **`justfile`** с целями для подъёма/симуляции/тестов. +- Минимальный порог входа для контрибьюторов. +- **Nix** — опция *позже* для эталонно-пиннутого тулчейна (power-users), не сейчас. + +## CI + +GitHub Actions на ARM64-Linux-раннерах: +- **lint** (clippy + rustfmt), **unit**, **интеграция** (vcan + симулятор + моки, + сервисы на шине), **license** (`cargo-deny`), позже — **сборка образа**. +- *Если ARM64-раннеры вне бесплатного тира — фолбэк: x86 + кросс или self-hosted.* + +## Пирамида тестов + +- **Unit** — на хосте/в VM, по крейтам/модулям. +- **Интеграция** — сервисы на шине против Vehicle Simulator и моков. Здесь + тестируется контекст машины без авто. +- **E2E** — полный стек в VM: boot < 10 c, graceful shutdown по ACC, реверс→камера, + поток «почему горит чек» (`P0420`), офлайн-фолбэк при выключенной мок-сети. +- **HW-in-the-loop** — на реальном RK3588 (позже). + +--- + +## Связи + +- Процессная модель и planes, которые здесь воспроизводим, — [architecture.md](architecture.md). +- Тестируемость-без-машины как принцип — [principles.md](principles.md) #13. +- Путь «VM → железка», флеш, board support — [contracts/hardware.md](contracts/hardware.md). +- Vehicle Simulator кормит домен — [domains/](domains/README.md) (E: Vehicle-Data). + +## Журнал решений (dev-environment) + +| Решение | Выбор | Дата | +|---------|-------|------| +| Linux-окружение | Lima (vz-backend), ARM64, нативная виртуализация | 2026-06-16 | +| Итерация UI | гибрид: нативный Slint на macOS + `cage` в VM | 2026-06-16 | +| Изоляция сервисов в dev | systemd-юниты + bubblewrap (зеркало прода) | 2026-06-16 | +| Воспроизводимость | Lima-шаблон + provisioning + `justfile` (Nix — позже) | 2026-06-16 | +| CI | GitHub Actions, ARM64-Linux | 2026-06-16 | diff --git a/docs/domains/README.md b/docs/domains/README.md new file mode 100644 index 0000000..2dce8c1 --- /dev/null +++ b/docs/domains/README.md @@ -0,0 +1,47 @@ +# Домены (Tier 2) + +> Детальные спеки подсистем. Каждый домен — отдельный документ по **единому +> шаблону** (ниже). Файлы создаём по мере наполнения; здесь — карта и план. + +Статус: **индекс + шаблон**. Содержательные файлы доменов появляются по ходу работы. + +## Единый шаблон домена + +1. **Назначение и границы** — что делает, чего НЕ делает. +2. **Функции** — таблица: `функция | MVP / later | зависит от | фаза`. +3. **Данные и интерфейсы** — что домен публикует/потребляет на шине (ссылки на `../contracts/`). +4. **Зависимости** — ссылки на другие домены и контракты (← здесь «связи»). +5. **Открытые вопросы / решения.** + +## Карта доменов + +| # | Домен | Файл | Кратко | +|---|-------|------|--------| +| A | Базовая система / OS | `a-base-system.md` | образ, read-only rootfs, boot, watchdog, OTA, board support | +| B | Питание и жизненный цикл | `b-power-lifecycle.md` | ACC, graceful shutdown, sleep, защита eMMC | +| C | Shell / UX / лаунчер | `c-shell-ux.md` | тайлы, темы день/ночь, профили, driver-distraction, ввод с **мультируля**, мультидисплей | +| D | Голосовой ассистент | `d-assistant.md` | wake→STT→LLM→TTS, vehicle-context, **память о водителе (`.md`)**, офлайн-фолбэк, провайдер-агностик | +| E | Vehicle Data (OBD/CAN, read-only) | `e-vehicle-data.md` | PIDs, DTC + расшифровка, поездки, расход, VSS-модель | +| F | Plugin host & экосистема | `f-plugin-host.md` | загрузка/sandbox/lifecycle плагинов, дистрибуция, dev-tools (API — в `../contracts/plugin-sdk.md`) | +| G | Связь / телефон | `g-connectivity-phone.md` | BT HFP, модем/LTE, WiFi/hotspot, проекция телефона | +| H | Медиа / аудио | `h-media-audio.md` | **вся стандартная мультимедиа**: локальное аудио, BT A2DP/AVRCP, радио, стриминг | +| I | Навигация | `i-navigation.md` | офлайн-карты OSM, роутинг, POI, связка с ассистентом | +| J | Камеры / видео | `j-cameras-video.md` | задняя камера, парктроник-оверлей, dashcam | +| K | Датчики / периферия | `k-sensors-peripherals.md` | GPS, IMU, кнопки руля (чтение), TPMS, климат-дисплей (чтение) | +| L | Облако / компаньон | `l-cloud-companion.md` | мобильное приложение, синхронизация, бэкап, OTA-канал, телеметрия (opt-in) | + +> Порядок наполнения определим в [roadmap.md](../roadmap.md); технически — после контрактов. + +## Заделы (сиды для будущих доменов) + +Идеи на будущее, пойманные по ходу проектирования; раскрываются при наполнении домена. + +- **J (Камеры).** Камеры — **динамический набор 0..N источников видео**, не одна задняя. + Задел: подключение доп. камер — фронтальная для **видеорегистратора (dashcam)**, + камеры **кругового обзора (360°/surround)** и т.п. Набор источников и «виды» + (например surround-композит) — расширяемые, плагин может добавить источник/вид. +- **K (Датчики).** **Парктроники** и подобные датчики ближнего действия — как источник + *данных* (чтение с CAN через Vehicle-Data или отдельный датчик) для оверлеев/ + предупреждений поверх видео-вида. +- **Архитектурная связь:** видео-источники идут через data-plane (PipeWire/V4L2); + задняя/парктроник-вид требуют низколатентного раннего пути (см. Решение №3 и lifecycle). diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..b73b6b7 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,27 @@ +# Глоссарий + +> Единый словарь Штурмана: один термин — одна строка. Пополняем по мере того как +> термины появляются в других документах, чтобы говорить на одном языке. + +Статус: **заготовка** (TODO наполнить определения). + +| Термин | Определение | +|--------|-------------| +| OBD-II | TODO | +| PID | TODO | +| DTC | TODO | +| CAN / SocketCAN / vcan | TODO | +| ELM327 | TODO | +| VSS (Vehicle Signal Specification) | TODO | +| ECU | TODO | +| AUTOSAR | TODO | +| AGL (Automotive Grade Linux) | TODO | +| D-Bus | TODO | +| Capability (манифест плагина) | TODO | +| Intent (ассистента) | TODO | +| Wake-word / VAD / STT / TTS | TODO | +| Driver memory (`.md` контекст водителя) | TODO | +| ACC (сигнал зажигания) | TODO | +| HAL / board support | TODO | + +> TODO: дополнить список и заполнить определения по ходу проработки документов. diff --git a/docs/principles.md b/docs/principles.md new file mode 100644 index 0000000..5d0a18e --- /dev/null +++ b/docs/principles.md @@ -0,0 +1,75 @@ +# Принципы и сквозные ограничения + +> Правила, которым подчиняется **каждый** домен. Если домен их нарушает — это баг +> дизайна, а не исключение. Спеки доменов ссылаются сюда. + +Статус: **v1 (на ревью).** +Связано с: [architecture.md](architecture.md) · [dev-environment.md](dev-environment.md) · [contracts/security-privacy.md](contracts/security-privacy.md) + +Формат: **принцип → почему → как держим/проверяем.** + +--- + +## Красные линии (нерушимы) + +### 1. Никогда не safety-critical +- **Почему:** безопасность людей, юридическая ответственность, сертификационная яма функциональной безопасности. +- **Как держим:** нет интеграций с управляющими ECU; в системе нет actuator-путей; каждая фича проходит ревью «не управляет ли узлом». + +### 2. CAN только на чтение +- **Почему:** тот же риск + юридическая чистота. Это то, что делает проект подъёмным для малой команды. +- **Как держим:** в Vehicle-Data нет write-кода; он единственный владелец CAN; на шине D-Bus нет метода записи в CAN; в SDK нет capability вида `can_write` — её просто не существует. + +--- + +## Сквозные принципы + +### 3. Offline-first +- **Почему:** салон часто без сети (тоннели, глушь); ассистент не должен умолкать, навигация — теряться. +- **Как держим:** STT/TTS локальны; у ассистента офлайн-LLM фолбэк; карты офлайн; ключевые функции **деградируют, а не падают** без сети. + +### 4. Изоляция и graceful degradation +- **Почему:** устойчивость; падение одного компонента не должно ронять систему. +- **Как держим:** процесс-на-компонент; App-Host рестартит упавшее; ап переживает недоступность зависимости (показывает «нет данных», а не крэшит). + +### 5. Power-safe by design +- **Почему:** машина рубит питание резко → corruption памяти (так умирают одноплатники). +- **Как держим:** read-only rootfs + overlay **с дня 1**; graceful shutdown по ACC; запись только в журналируемый `/data`. + +### 6. Driver-distraction discipline +- **Почему:** безопасность вождения (и потенциальная регуляторика). +- **Как держим:** на скорости выше порога — упрощённый UI, приоритет голосу, блокировка сложных взаимодействий; правило едино для всех апов через shell/SDK. Конкретика — в домене Shell. + +### 7. Приватность / 152-ФЗ +- **Почему:** закон + доверие пользователя. +- **Как держим:** обработка локальна по умолчанию (голос → текст локально); в облако уходит **только текст запроса** при онлайн-LLM; RU-провайдеры, данные в РФ; телеметрия **opt-in**, по умолчанию выключена; память о водителе (`.md`) — локальная, не уходит в облако без явного согласия. + +### 8. Provider-agnostic +- **Почему:** не привязываемся к одному вендору; ИИ — коммодити; устойчивость к отвалу провайдера. +- **Как держим:** LLM за единым интерфейсом-бэкендом с авто-fallback; то же для STT/TTS/карт, где разумно. + +### 9. Расширяемость через API, не через правку ядра +- **Почему:** суть платформы; даже свои апы — на SDK. +- **Как держим:** ядро тонкое; новая функция = ап/плагин. Если «для фичи нужно лезть в ядро» — это сигнал, что **API недостаточен**: чиним API, а не хардкодим в ядро. + +### 10. RU-first, i18n-ready +- **Почему:** русский — наш моат и приоритет №1; но платформа (и автопроизводители) не должны быть заперты в одном языке. +- **Как держим:** русский — первоклассный и дефолтный; **строки и локаль не хардкодим** — инфраструктура i18n заложена изначально. +- ⚠️ *На подтверждение: оставляем i18n-ready, а не строго RU-only?* + +### 11. Отзывчивость (no-lag) — требование, не пожелание +- **Почему:** медленный лагучий UI — главный изъян китайских блоков и наш ключевой дифференциатор. +- **Как держим:** бюджет на отклик (цель: мгновенный UI, boot < 10 c до интерактива); тяжёлое — фоном/лениво; не блокируем UI-поток. Регрессии производительности — это баги, а не «потом». + +### 12. Лицензионная гигиена (MIT) +- **Почему:** adoption, без AGPL-боли. +- **Как держим:** зависимости — MIT/Apache/BSD-совместимые; заражающий дистрибуцию copyleft (GPL/AGPL) избегаем или изолируем как отдельный процесс; проверка лицензий в CI. + +### 13. Разрабатываемо и тестируемо без машины +- **Почему:** итерации малой командой с Mac; нельзя зависеть от наличия авто под рукой. +- **Как держим:** симуляция CAN/OBD (vcan + дампы), моки LLM/STT/TTS; **каждый домен поставляет симулятор/мок**. Детали — [dev-environment.md](dev-environment.md). + +--- + +> Изменения этого списка — осознанные: принцип влияет на все домены, поэтому +> правка здесь = ревизия их всех. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..2f050f0 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,18 @@ +# Роадмапа + +> Фазы реализации лестницей: каждая ступень — законченный, демонстрируемый +> артефакт. Порядок диктуется зависимостями из [architecture.md](architecture.md) +> и [capability-catalog.md](capability-catalog.md). + +Статус: **заготовка** (наполняем в конце, когда домены и связи ясны). + +## Черновая лестница (из vision — уточним и развернём) + +- **v0 — Shell.** Быстрый красивый лаунчер на RK3588, день/ночь, быстрый boot. +- **v1 — Ассистент онлайн.** wake-word → STT → RU-LLM (GigaChat/YandexGPT) → TTS. +- **v2 — OBD read-only + контекст машины.** «Прочитай ошибки / что значит лампочка». **Killer-демо.** +- **v3 — Офлайн-фолбэк + Plugin API.** Локальная модель без сети + расширяемость. +- **v4 — Навигация (OSM) + образ + документированный ретрофит.** Первый «продукт». + +> TODO: развернуть каждую фазу в задачи с явными зависимостями после проработки +> доменов. Учесть, что dev-environment проектируется рано (до v0-реализации). diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 0000000..64e2307 --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,168 @@ +# Штурман — видение и позиционирование + +> Статус: черновик v0.2 (на ревью). Канонический рассказ о смысле проекта. +> Технические решения — в [architecture.md](architecture.md) и доменах; здесь — зачем и что. + +## В одном абзаце + +Штурман — открытый (MIT) русскоязычный программный слой для автомобиля. Он +превращает дешёвый головной блок или одноплатник в быстрый, красивый и +расширяемый бортовой интерфейс с голосовым ассистентом на русском — ассистентом, +который не просто болтает, а **видит данные твоей машины и объясняет их +по-человечески** (общение в духе Grok в Tesla). По смыслу имени штурман — +со-пилот, который ведёт по маршруту и держит руку на пульсе машины: проект делает +ровно это. По сути это **операционная система для автомобиля на базе Linux** (экран, +мультируль и т.д.) со всей стандартной мультимедией и потенциалом расширений. +Ничего, что управляет двигателем, тормозами или другими критичными узлами. + +## Проблема, из которой всё растёт + +- **Фрагментация «мозгов».** Софт и электроника машин различаются чуть ли не под + каждый рестайлинг даже у одного производителя. Боль OEM, владельцев и особенно + механиков. +- **Афтемаркет.** Миллионы машин без нормального экрана или с дешёвым китайским + Android-блоком: медленным, лагучим, уродливым, без кастомизации, с языковым + барьером и плохой поддержкой. +- **Взрыв голосовых ИИ в машинах.** Mercedes (ChatGPT → Gemini-агент), Tesla + (Grok), VW (IDA на ChatGPT), Hyundai (Naver), BMW в Китае (Alibaba/DeepSeek), + китайцы агрессивнее всех. Но всё — проприетарное, западное или китайское. + **Ни одного — ни в российском авто, ни в открытом коде.** +- **Российский контекст.** После 2022 АвтоВАЗ потерял западных поставщиков и + просел по электронике (ЭБУ двигателя, ABS, ESP, приборки). Латается китайским + и отечественным, но язык, цена и поддержка китайских решений — заноза. Нужна + локализованная, поддерживаемая альтернатива — её нет. + +## Пустая клетка + +Наложив всё друг на друга, видим незанятое место: **открытый, русскоязычный, +поддерживаемый, кастомизируемый** слой для авто. Пусто не случайно, а структурно: +на уровне OEM всё закрыто стандартами (AUTOSAR — 20-летний отраслевой стандарт +для ECU с сотнями компаний-членов); полноценные открытые автомобильные ОС +существуют, но тяжёлые и заточены под автопроизводителей (Automotive Grade Linux); +а safety-critical упирается в сертификацию функциональной безопасности и +ответственность. Клетка пуста не потому что её легко занять, а потому что +**некому — кроме того, кто сидит ровно на этом пересечении.** + +## Что Штурман делает на самом деле + +1. **Интерфейс.** Быстрый, красивый, не-лагучий головной экран: навигация, медиа, + телефон, ассистент, экран машины, настройки. Прямой ответ на главный изъян + китайских блоков. Дифференциация — в качестве опыта, не в наличии экрана. +2. **Голосовой ассистент на русском.** Лаконично интегрирован в интерфейс (как в + Tesla). Пайплайн гибридный: распознавание и синтез речи — локально (Vosk, + Silero); «мозг» — через сменный бэкенд. Онлайн — российские LLM (GigaChat, + YandexGPT; работают в РФ, 152-ФЗ, данные в России). Офлайн — небольшая + локальная модель на устройстве, чтобы ассистент не умолкал в тоннеле или без + сети. Бэкенд провайдер-независим: один отвалился — автоматически переключились + на другой. Ассистент **запоминает информацию о водителе в контекстные `.md` + файлы** — персонализация со временем. +3. **Контекст машины (главное).** Через OBD-II/CAN (**строго на чтение**) Штурман + видит реальные данные: скорость, обороты, температуры, напряжение бортсети, + активные ошибки — и подаёт их ассистенту в контекст. На «почему горит чек?» он + читает реальный код ошибки из ЭТОЙ машины и объясняет простым русским. Этого + нет ни у кого в связке «открытое + русское» — мост к боли механиков и + владельцев. + +Поверх всего — **открытый расширяемый API**: сообщество и интеграторы добавляют +плагины, экраны, интенты ассистента, не трогая ядро. + +## Чем Штурман сознательно НЕ является (и почему) + +Границы держат проект жизнеспособным и юридически чистым. + +- **Никогда не пишет в шину и не управляет критичными узлами. Только чтение.** + Архитектурная гарантия, не настройка: write-пути в системе просто нет. Так + снимается вся сертификационная и юридическая яма функциональной безопасности — + единственное, что делает проект подъёмным для маленькой команды. +- **Не строит свою ОС** — живёт поверх обычного Linux. Ядро решено; ценность — в + слое опыта и локализации над ним. +- **Не претендует на индустриальный стандарт** — это место AUTOSAR; ценность + стандарта определяется принятием, которым владеют консорциумы, а не разработчик. +- **Не обещает работать на любом заводском железе.** Универсальность — ловушка + масштаба AGL (тачскрины, тюнеры, камеры, питание у всех свои). Вместо этого — + **один хорошо выбранный таргет, доведённый до конца.** НО заложен грамотный + **API для автопроизводителей/автолюбителей**, чтобы адаптировать всё под + конкретное железо/авто. Портируемость — через API силами других, а не + «универсально из коробки». Это разница между соло-проектом, который заканчивается, + и платформой, которая не заканчивается. + +## Где настоящий моат + +ИИ сам по себе — **не** преимущество: ассистенты коммодитизируются, китайские +блоки получат их быстро. Защищённость — в трудноповторимом сочетании: **русская +локализация** (язык + RU-LLM-провайдеры + 152-ФЗ) + **открытость** (MIT, без +AGPL-боли) + **трюк с контекстом машины** + **по-настоящему хороший UX** + **фокус +на нише афтемаркета/ретрофита**. Западное проприетарное не зайдёт на этот рынок, +китайское не станет локализовать и открывать, OEM строят закрыто. + +## Как это устроено технически (кратко; детали — в [architecture.md](architecture.md)) + +Голый Linux на одноплатнике класса RK3588 (хватает на красивый UI и локальную +небольшую модель, приличная mainline-поддержка). Независимые процессы общаются +через шину **D-Bus**: интерфейс, ассистент, сервис данных машины, питание, связь. +Падение ассистента не роняет UI; плагины цепляются к той же шине. Два решения — +**с первого дня**: (1) read-only rootfs с записью только в отдельный раздел +(резкое обесточивание корраптит память — так умирают одноплатники от forced +power-off); (2) управляемое питание и graceful shutdown по сигналу зажигания. Без +них красивый интерфейс однажды просто не загрузится. Навигация, медиа, телефон — +наращиваются слоями. + +## Стратегия: открытость как фундамент, продажа как апсайд + +Проект **открыт в любом случае**; его ценность не зависит от продажи. Открытый +Штурман сам по себе — актив: репутация, доверие, сообщество, портфолио, «построил +настоящее и довёл до конца». Коммерция — апсайд сверху, а не точка, без которой +проект мёртв: сервис интеграции/локализации/поддержки для афтемаркета или Tier-1; +демо для АвтоВАЗа строго на несейфти-companion-слое; своя «коробка» для ретрофита. +Не выйдет продать — остаётся сильный открытый проект; выйдет — ещё и бизнес. +**Проигрышного исхода нет.** + +## Для кого + +- **Энтузиаст-ретрофитчик** — красивый, быстрый, кастомный блок вместо китайского. +- **Механик / владелец** — ассистент впервые объясняет ошибки и поведение машины + по-русски на основе её реальных данных. +- **(Апсайд) OEM / Tier-1 / афтемаркет-интеграторы и автопроизводители в РФ** — + локализованная открытая альтернатива без зависимости от китайцев и без языкового + барьера. + +## Как проект растёт (лестница; детали — в [roadmap.md](roadmap.md)) + +Каждая ступень — законченная, демонстрируемая вещь: интерфейс → ассистент онлайн → +контекст машины (**killer-демо**) → офлайн + Plugin API (маховик сообщества) → +навигация + образ + документированный ретрофит (первый «продукт»). Остановиться +можно на любой ступени — каждая самоценна. + +## Суть + +Поставить флаг там, где пусто: первый открытый, русскоязычный, по-настоящему +хороший бортовой companion. Глубокий настолько, чтобы его уважали инженеры +(Linux-bring-up, голосовой пайплайн, работа с CAN, архитектура из независимых +сервисов), красивый и осязаемый настолько, чтобы хотелось показывать, и +ограниченный в скоупе настолько, чтобы реально закончить. А повезёт — фундамент +для бизнеса. + +--- + +## Рамки — решено (2026-06-15) + +Выбран **вариант B**: Штурман — это полноценная расширяемая платформа («ОС +поверх Linux» в широком смысле), и мы сознательно шире, чем §2 спеки. При этом +две красные линии остаются абсолютными. + +**Нерушимые красные линии (не обсуждаются — безопасность + 152-ФЗ/юр. чистота):** +- **Никогда не safety-critical** — не управляем двигателем, тормозами, ABS/ESP, + рулём, подушками. +- **CAN только на чтение** — никакой записи в шину, никаких actuator-команд. + Write-пути нет в системе в принципе (архитектурная гарантия). + +**Открыто к пересмотру (закладываем в каталог как возможное; решаем по фазам):** +- **Несколько HW-таргетов.** Спека требовала один (RK3588). Для платформенной + амбиции мульти-железо допустимо — но не ценой bring-up-боли на старте: первый + таргет всё равно один, остальное — позже (через HAL/board-support API). +- **Глубже стокового Linux.** Допускаем собственный образ/ядро/дистрибутив и + более глубокую системную интеграцию, если это реально нужно платформе. Не + самоцель — каждое углубление обосновывается потребностью. + +> §2 исходной спеки (жёсткие «НЕ полноценная ОС» и «один таргет») этим решением +> переопределяется. Две safety/legal-линии из §2 остаются в силе.