docs: заложить фундамент проектирования Штурмана
Каркас документации + содержательный фундамент (фаза проектирования, реализация отложена): - 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) <noreply@anthropic.com>
This commit is contained in:
@@ -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 |
|
||||
Reference in New Issue
Block a user