docs: трёхфазный флоу с жалобами водителя — полный план

2026-05-26 21:46:04 +03:00
parent fa51ec8295
commit 8d25ae7972
1 changed files with 124 additions and 0 deletions
@@ -406,3 +406,127 @@ python web/app.py
 - Настроить `DEEPSEEK_API_KEY` и прогнать LLM на реальных данных
 - Исправить парсер: фильтровать 7F, не путать mode 47 в PID-ответах с DTC pending
 - В скрипте: пропускать 0902 если ЭБУ не поддерживает (VIN не критичен)
+
+---
+
+## 21:30 — План: трёхфазный флоу с жалобами водителя
+
+### Концепция
+
+Текущая проблема: водитель подключает ELM → молча сканирует → загружает → ждёт LLM.
+Нет контекста от водителя (он лучше всех знает машину). Нет понимания холодный/горячий двигатель.
+
+**Философия:** мы не конкурируем с Torque/OBD Fusion за расшифровку кодов. 
+У водителя уже есть эти программы. Наша задача — собрать контекст (ошибки + параметры + **жалобы водителя**) 
+и дать AI-диагноз, который учитывает человеческий фактор.
+
+### Трёхфазный флоу (Android)
+
+```
+ФАЗА 1 — БЫСТРЫЙ ОПРОС (без интернета, ~5 сек)
+  Инициализация: ATZ→ATE0→ATL0→ATSP0→ATH0
+  Чтение: 03 (stored DTC) → 07 (pending DTC) → 0105 (ОЖ) → 010C (RPM)
+  
+  ↓ Показываем МИНИМАЛЬНУЮ карточку:
+  
+  ┌─────────────────────────────┐
+  │ 🔌 ELM327 подключён         │
+  │                             │
+  │ 🌡 Двигатель: ХОЛОДНЫЙ 32°C │
+  │ ⚠️ Ошибок: 2                │
+  │ 🔄 Обороты: 0 (заглушен)    │
+  │                             │
+  │ 📝 Опишите жалобы:          │
+  │ ┌─────────────────────────┐ │
+  │ │ (свободный ввод)        │ │
+  │ └─────────────────────────┘ │
+  │                             │
+  │   [ПРОПУСТИТЬ]  [ДАЛЕЕ ➤]  │
+  └─────────────────────────────┘
+
+ФАЗА 2 — ОСНОВНОЙ СКАН (завёл двигатель, ~15-20 сек)
+  0902 (VIN) → 0104 (нагрузка) → 0106 (STFT) → 0107 (LTFT) 
+  → 010B (MAP) → 010D (скорость) → 010F (IAT) → 0111 (дроссель) → 011F (время работы)
+
+ФАЗА 3 — ОТПРАВКА + LLM (нужен интернет)
+  POST /api/v1/session/upload
+  {
+    "responses": [...],
+    "driver_complaint": "троит на холодную, стук при разгоне",
+    "engine_state": {
+      "temp_c": 32,
+      "status": "cold",        // "cold" (<40°C) | "warming" (40-80°C) | "hot" (>80°C)
+      "rpm": 0,
+      "running": false
+    }
+  }
+```
+
+### Что меняется на сервере (elmer)
+
+1. **`build_default_script()`** — новый порядок шагов:
+   - Фаза 1: ATZ→ATE0→ATL0→ATSP0→ATH0→03→07→0105→010C
+   - Спец-шаг: `show_summary` (триггер для Android показать карточку + спросить жалобы)
+   - Спец-шаг: `driver_complaint` (текстовый ввод, можно пропустить)
+   - Спец-шаг: `prompt_engine` (завести двигатель)
+   - Фаза 2: 0902→0104→0106→0107→010B→010D→010F→0111→011F
+
+2. **`upload_session()`** — принимает `driver_complaint` и `engine_state` из тела запроса
+
+3. **`_build_diagnosis_prompt()`** — включает жалобы водителя и состояние двигателя:
+   ```
+   ## Данные диагностики
+   **VIN:** ...
+   **Состояние двигателя:** ХОЛОДНЫЙ (32°C), заглушен
+   **Сохранённые ошибки:** P0301, P0303
+   **Жалобы водителя:** "троит на холодную, стук при разгоне"
+   ...
+   ```
+
+4. **SYSTEM_PROMPT** — дополнен инструкцией учитывать жалобы водителя:
+   - Жалобы водителя — ПРИОРИТЕТНАЯ информация
+   - Сопоставлять жалобы с кодами ошибок и параметрами
+   - Если жалоба не объясняется кодами — предлагать что проверить дополнительно
+
+### Что меняется на Android (elmer-android)
+
+1. **`ScriptRunnerService.kt`:**
+   - Новый тип шага: `show_summary` — после фазы 1 декодирует результаты, отправляет broadcast `ACTION_SHOW_SUMMARY` с данными:
+     ```json
+     {
+       "temp_c": 32, "temp_status": "cold",
+       "dtc_stored_count": 2, "dtc_pending_count": 1,
+       "rpm": 0, "running": false
+     }
+     ```
+   - Новый тип шага: `driver_complaint` — отправляет broadcast `ACTION_PROMPT_COMPLAINT`, ждёт текстовый ввод
+   - При upload добавляет поля `driver_complaint` и `engine_state` в JSON
+
+2. **`MainActivity.kt`:**
+   - Приёмник `ACTION_SHOW_SUMMARY` — показывает карточку с ОЖ, ошибками, RPM
+   - Приёмник `ACTION_PROMPT_COMPLAINT` — показывает поле ввода + кнопки ПРОПУСТИТЬ / ДАЛЕЕ
+   - Отправляет результат обратно в сервис через broadcast
+
+3. **`activity_main.xml`:**
+   - Новый overlay `layout_complaint`: карточка + EditText + кнопки
+
+### Почему клиент НЕ хранит базу DTC
+
+- Полная база: ~10 000+ кодов, ~100+ КБ в JSON → клиент становится «слоном»
+- У водителя уже есть Torque/OBD Fusion для расшифровки
+- Наша задача — не расшифровка, а AI-диагноз с контекстом
+- Клиент показывает только **количество** ошибок и **состояние** двигателя
+- LLM на сервере сам знает что значит P0301 и P0047
+
+### Приоритет жалоб водителя для LLM
+
+Правило: **жалоба водителя > коды ошибок > параметры**
+
+Пример: 
+- Коды: P0301, P0303 (пропуски зажигания)
+- Параметры: STFT=0%, O₂=0.32V (бедная смесь)
+- Жалоба: «троит ТОЛЬКО на холодную, после прогрева всё нормально»
+
+Без жалобы LLM скажет: «топливная система, форсунки, MAP/MAF»
+С жалобой LLM скажет: «свечи/катушки — на холодную зазор меньше, искра слабее; 
+после прогрева металл расширяется и контакт восстанавливается»