shturman/docs/dev-environment.md

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

> Как вести разработку Штурмана корректно и изолированно — не выходя с 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(shell/smithay)
    (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** + 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`…) |
| 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 |