shturman/docs/dev-environment.md

Среда разработки

Как вести разработку Штурмана корректно и изолированно — не выходя с Mac, ничего не ломая, со спокойным тестированием подсистем без реального железа.

Статус: v1 (на ревью). Связано с: architecture.md · principles.md (#13) · 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(shell/smithay)
    (Lima, vz,      ← интегрированный стек; сервисы = systemd-юниты + bubblewrap (как в проде)
     ARM64)
        │
L3  Симуляция       Vehicle Simulator (vcan) · моки LLM/STT/TTS · фейк-GPS · мок-сеть · fake-камера/аудио/BT · plugin-host-харнесс · нав-сим · мок-облако/OTA
        │
L4  Реальный RK3588  (позже) сборка образа → флеш → путь «VM → железка»

Стек инструментов

Задача	Инструмент	Зачем
Linux dev-VM	Lima (vz-backend)	нативная ARM64-виртуализация, open-source, scriptable YAML
Итерация UI	нативный Slint на macOS + shell-композитор (smithay), вложенно в 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, just plugin-dev-run/sideload…)
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).
• Камеры — fake V4L2/PipeWire-источник (тест-паттерн / реплей / no-signal; реверс-стаб; Stage 0-мок TTFF) — J §11.
• Аудио — синтетический медиа-поток, мок BT-A2DP / нав-промпта / TTS / звонка (матрица ducking) — H §12.
• BT / телефон — фейковый BT-стек (паринг + сбой, HFP/A2DP/PBAP, мульти-устройство, SCO-loss), мок-контакты — G §12.
• Plugin-host — тест-харнесс: поднять плагин в bubblewrap + прокси из манифеста (sideload), итерация без полного стека — F.
• Навигация — нав-сим: тест-регион (малый PMTiles + Valhalla-тайлы) + мок-маршрут (rerouting / maneuver-тайминг / nav_guidance-ducking) поверх fake-GPS-трека и мок-сети; краевые: дрейф в каньоне при валидном фиксе → не reroute, назначение вне региона, no-route, stale-промпт под звонком — I §16.
• Облако / OTA — мок-облако/OTA-сервер (подписанные / битые / downgrade-бандлы → тест верификации + anti-rollback и отказа по размеру/хэшу), фейковый companion-peer (паринг/синк/конфликты/мульти-peer), мок-телеметрия-sink (opt-in-гейт: по умолчанию нулевой egress; дроп буфера на отзыв/reset); поверх мок-сети G (включая portal/невалидное-время) — L §12.

---

Воспроизводимость

• Lima-шаблон (lima.yaml): Ubuntu ARM64, модули (vcan), пакеты (systemd, dbus, pipewire, weston (вложенный композитор для dev), 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.
• Тестируемость-без-машины как принцип — principles.md #13.
• Путь «VM → железка», флеш, board support — contracts/hardware.md.
• Vehicle Simulator кормит домен — domains/ (E: Vehicle-Data).

Журнал решений (dev-environment)

Решение	Выбор	Дата
Linux-окружение	Lima (vz-backend), ARM64, нативная виртуализация	2026-06-16
Итерация UI	гибрид: нативный Slint на macOS + shell-композитор (smithay, вложенно в weston) в VM; cage — только bring-up одного апа	2026-06-16
Изоляция сервисов в dev	systemd-юниты + bubblewrap (зеркало прода)	2026-06-16
Воспроизводимость	Lima-шаблон + provisioning + justfile (Nix — позже)	2026-06-16
CI	GitHub Actions, ARM64-Linux	2026-06-16