shturman/docs/principles.md

Принципы и сквозные ограничения

Правила, которым подчиняется каждый домен. Если домен их нарушает — это баг дизайна, а не исключение. Спеки доменов ссылаются сюда.

Статус: v1 (на ревью). Связано с: architecture.md · dev-environment.md · contracts/security-privacy.md

Формат: принцип → почему → как держим/проверяем.

---

Красные линии (нерушимы)

1. Никогда не safety-critical

• Почему: безопасность людей, юридическая ответственность, сертификационная яма функциональной безопасности.
• Как держим: нет интеграций с управляющими ECU; в системе нет actuator-путей; каждая фича проходит ревью «не управляет ли узлом».

2. CAN — только чтение (без управляющих команд)

• Почему: безопасность + юридическая чистота. Это то, что делает проект подъёмным для малой команды.
• Точный смысл «чтения»: мы НИКОГДА не шлём управляющих/actuator-команд, не пишем в память ECU, не делаем сброс DTC (Mode 04) и UDS-write — никаких state-changing передач. При этом стандартные диагностические read-запросы OBD-II — любой read-сервис без state-changing (напр. Mode 01/03/07/09/0A) допустимы и необходимы: протокол физически отправляет кадр-запрос, иначе DTC не прочитать. Пассивный сниффинг (listen-only) не передаёт ничего.
• Как держим: в Vehicle-Data нет кода управляющих/write-команд; он единственный владелец CAN; на D-Bus и в SDK нет метода/capability записи или actuator-вызова — их не существует; нативный CAN в пассивном режиме — listen-only. См. contracts/hardware.md §4.

---

Сквозные принципы

3. Offline-first

• Почему: салон часто без сети (тоннели, глушь); ассистент не должен умолкать, навигация — теряться.
• Как держим: STT/TTS локальны; у ассистента офлайн-LLM фолбэк; карты офлайн; ключевые функции деградируют, а не падают без сети. (Фазировка: STT/TTS-офлайн + локальные интенты держат принцип с v1; офлайн-диалог LLM — v3, см. домен D §5.)

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.

---

Изменения этого списка — осознанные: принцип влияет на все домены, поэтому правка здесь = ревизия их всех.