182 lines
14 KiB
Markdown
182 lines
14 KiB
Markdown
# Структура репозитория elmAI
|
||
|
||
> **elmAI** — сервис OBD2-диагностики автомобилей через ELM327 + LLM (DeepSeek).
|
||
> Android-приложение + Python-сервер. Анализ ошибок ЭБУ, live-параметры, диагноз через ИИ.
|
||
|
||
---
|
||
|
||
## Корневые файлы
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `run.py` | Главная точка входа (CLI). Подключается к ELM327 по Bluetooth, читает VIN/DTC/PID, сохраняет в SQLite, отправляет в LLM. Запуск: `python run.py [--no-llm] [--port]` |
|
||
| `config.yaml` | Конфигурация: LLM (API key, модель), ELM327 (порт, baudrate), список PID для чтения |
|
||
| `requirements.txt` | Зависимости Python: pyserial, pyyaml, requests, flask, flask-cors |
|
||
| `deploy.sh` | Скрипт деплоя на сервер obdai.ru: обновление репо, venv, systemd-сервис (gunicorn), nginx, SSL (certbot) |
|
||
| `legacy-deploy.sh` | Устаревшая версия деплоя (ветка fat-client, GPT-OSS модель) |
|
||
| `analysis.md` | Анализ и план проекта от 2025-05-25: железо, ЦА, требования, компоненты, протокол, риски |
|
||
| `idea.md` | Концепция сервиса: OBD2 + AI диагностика, три компонента (сервер, Android, десктоп) |
|
||
| `morda.md` | Макет UI (морда) v2: иконки-светофоры, кнопка-трансформер, поле вывода, поле ввода |
|
||
| `QUICKSTART.md` | Быстрый старт: тест с mock ELM327, тест в машине, веб-интерфейс |
|
||
| `resume.txt` | Резюме проекта для нового чата: версия v0.77.0-dev, инструкции по деплою |
|
||
| `legacy-resume.txt` | Устаревшее резюме (v0.48.0, ветка master) |
|
||
| `CHANGELOG.md` | Полное описание проекта: архитектура, модули, эндпоинты, БД, стейт-машина (актуально v0.95.0-dev) |
|
||
| `token.txt` | Токены и ключи: gitea, DeepSeek API, SSH-ключ VM |
|
||
| `STRUCTURE.md` | **Этот файл** — описание структуры репозитория |
|
||
|
||
---
|
||
|
||
## `api/` — Flask REST API + БД + парсинг
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `__init__.py` | Пустой (пакет) |
|
||
| `config.py` | Загрузка `config.yaml` с подстановкой `${VAR}` из переменных окружения. Кэш через `@lru_cache` |
|
||
| `db.py` | SQLite-база данных (WAL mode). Таблицы: `sessions`, `cars`, `diagnostic_tokens`, `llm_messages`, `ecu_parameters`, `dtc_codes`, `command_queue`. Класс `Database` |
|
||
| `routes.py` | Основные эндпоинты: `GET /api/v1/script`, `POST /api/v1/session/upload`, `POST /api/v1/chat`, `POST /api/v1/elm/probe`. Проверка X-Api-Key, сборка промпта для LLM |
|
||
| `dtc.py` | DTC-эндпоинты: `POST /api/v1/dtc/decode` (расшифровка кодов из справочника), `POST /api/v1/dtc/upload`. Справочник из `doc/dtc_codes.txt` |
|
||
| `ping.py` | Эндпоинты проверки: `GET /api/v1/ping` (доступность), `GET /api/v1/ping-llm` (проверка LLM с адаптивным кэшем 60с/7с) |
|
||
| `parser.py` | Парсинг батча ELM-ответов: VIN (из decoded и raw HEX), DTC stored/pending (mode 03/07), PID-параметры (mode 01) |
|
||
| `scripts.py` | Сборка диагностических скриптов трёх уровней: L0 (5 PID + stored DTC), L1 (8 PID + VIN + stored/pending), L2 (14 PID + калибровки). + динамические скрипты |
|
||
| `raw_elm.py` | Сырое взаимодействие с ELM327: локальный режим (прямое подключение) и удалённый (через Android-реле). HTTP-очередь команд |
|
||
|
||
---
|
||
|
||
## `brain/` — LLM-клиент и промпты
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `__init__.py` | Пустой (пакет) |
|
||
| `client.py` | `Diagnoser` — HTTP-клиент к OpenAI-совместимому API (api.aillm.ru). Модели: `gpt-oss-120b`, `qwen3-6-27b-fp8`. Обработка ошибок: Timeout, 429, 5xx, 4xx |
|
||
| `prompts.py` | `SYSTEM_PROMPT` (10 правил для диагноза: расшифровка, отклонения, степени уверенности), `DYNAMIC_PROMPT` (для динамических тестов), `build_user_prompt()` |
|
||
|
||
---
|
||
|
||
## `obd/` — ELM327-протокол (Python, порт AndrOBD)
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `__init__.py` | Пустой (пакет) |
|
||
| `connection.py` | `SerialTransport` — транспортный слой: открыть serial/Bluetooth порт, побайтовое чтение до `>`, запись + flush |
|
||
| `protocol.py` | `AndrOBD` — стейт-машина ELM327 (порт ElmProt.java). Состояния: UNDEFINED → INITIALIZING → READY → BUSY → ERROR. Канонический init, обработка BUS ERROR |
|
||
| `state.py` | `State` (enum состояний) и `Rsp` (классификация ответов: PROMPT, OK, SEARCHING, ERROR, BUS_ERROR, NODATA и т.д.) |
|
||
| `timing.py` | `AdaptiveTiming` — адаптивный таймаут (50..2000мс). Увеличивается при таймаутах, уменьшается при быстрых ответах, сброс при BUS ERROR |
|
||
| `commands.py` | Каталог AT-команд ELM327 с метаданными: name, desc, level (0/1/2), safe. L0 (универсальные), L1 (ATAT), L2 (CAF/CFC) |
|
||
| `classifier.py` | Классификация сырых ответов ELM327 и определение уровня устройства по ответам на пробинг |
|
||
| `probe.py` | Пробинг ELM327: трехуровневый каскад (L0→L1→L2), каждая команда с таймаутом 500мс, без ретраев |
|
||
| `raw_console.py` | `RawELM` — сырой слой без стейт-машины: только send/read/drain/available. Для изучения поведения ELM327 |
|
||
|
||
---
|
||
|
||
## `web/` — Веб-интерфейс (Flask)
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `app.py` | Точка входа Flask: регистрация эндпоинтов, режим RAW (блокировка всех, кроме `/elm/raw/*`), раздача APK, главная страница |
|
||
| `script_builder.py` | Сборка диагностических скриптов (устаревшая версия — дублирует `api/scripts.py`) |
|
||
| `script_endpoint.py` | Эндпоинты скриптов (устаревшая версия — дублирует `api/routes.py`) |
|
||
| `script_parser.py` | Парсинг батча (устаревшая версия — дублирует `api/parser.py`) |
|
||
| `templates/index.html` | Главная HTML-страница: скачивание APK, десктоп-диагностика, отображение результатов |
|
||
| `static/style.css` | Стили: тёмная тема, оранжевый акцент, карточки, спиннеры, DTC-бейджи |
|
||
|
||
---
|
||
|
||
## `android/` — Android-приложение (Kotlin)
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `build.gradle.kts` | Корневой build-файл Gradle: плагины Android + Kotlin |
|
||
| `settings.gradle.kts` | Настройки Gradle-проекта |
|
||
| `gradle.properties` | Свойства Gradle |
|
||
| `gradlew` | Gradle Wrapper (исполняемый) |
|
||
| `app/build.gradle.kts` | Модуль app: minSdk 24, OkHttp 4.12.0, зависимости |
|
||
| `app/src/` | Исходники Android-приложения (Kotlin) — основной клиент + raw-реле |
|
||
| `raw/build.gradle.kts` | Модуль raw — ретранслятор ELM327 через HTTP |
|
||
| `doc/opus-review-android.md` | Рецензия кода Android-приложения |
|
||
| `doc/opus-questions-android.md` | Вопросы по Android после рецензии |
|
||
| `gradle/wrapper/` | Gradle Wrapper JAR и настройки |
|
||
|
||
---
|
||
|
||
## `tools/` — Вспомогательные утилиты
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `mock_elm327.py` | Эмулятор ELM327 v1.5 через TCP (порт 35000). Отвечает на AT-команды, PID, DTC, VIN. Для тестирования без реального сканера |
|
||
| `mock_elm327_v2.py` | Улучшенный мок: поддержка `>` как разделителя, ATST, случайные ошибки (BUS BUSY, UNABLE), побайтовая отправка |
|
||
| `elm_console.py` | Интерактивная консоль ELM327 (сырой режим). Команды: ATZ, 0105, !drain, !timeout, !log. Для изучения поведения ELM |
|
||
| `elm_relay.py` | Интерактивная консоль удалённого управления ELM327 через Android-реле. HTTP-команды: `!status`, `!history`, `!mode` |
|
||
| `test_androbd.py` | Тест AndrOBD-протокола против Mock ELM327 v2: проверка что ответы не перемешаны (VIN → DTC → RPM → coolant) |
|
||
| `analyze_sessions.py` | Анализ сессий из SQLite: статистика команд, ошибок, пустых ответов |
|
||
|
||
---
|
||
|
||
## `scripts/` — Скрипты развёртывания
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `setup-bt.sh` | Настройка Bluetooth-сопряжения с ELM327: поиск, pairing, rfcomm bind на /dev/rfcomm0 |
|
||
|
||
---
|
||
|
||
## `tests/` — Автотесты
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `test_all.py` | Сквозные тесты (без LLM): сборка скриптов, парсер ELM-ответов (VIN из decoded/raw, DTC, PID), работа с БД, идемпотентность, эндпоинты |
|
||
|
||
---
|
||
|
||
## `doc/` — Документация и исследования
|
||
|
||
| Файл | Назначение |
|
||
|------|-----------|
|
||
| `architecture.md` | Полная архитектура проекта: два режима (app/raw), схема, эндпоинты, модули |
|
||
| `roadmap.md` | План развития проекта |
|
||
| `research.md` | Исследования и заметки |
|
||
| `competitors.md` | Анализ конкурентов |
|
||
| `diagnostic-logic.md` | Логика диагностики |
|
||
| `dynamic-diagnostics-analysis-2026-06-14.md` | Анализ динамической диагностики |
|
||
| `dynamic-tests.md` | Динамические тесты |
|
||
| `dtc_codes.txt` | Справочник DTC-кодов (формат: `P0301=Пропуски зажигания цилиндр 1`) |
|
||
| `elm-reference.md` | Справочник по ELM327 |
|
||
| `elm-raw-relay-plan.md` | План raw-реле |
|
||
| `failures-journal.md` | Журнал отказов |
|
||
| `field-test-2026-06-07.md` | Полевой тест |
|
||
| `git-guide.md` | Гайд по Git |
|
||
| `morda-v2.md` | Макет UI v2 |
|
||
| `mpscholar-automotive-sensing-actuators.md` | Обучающий материал |
|
||
| `opinion-dynamic-diagnostics-2026-06-14.md` | Мнение по динамической диагностике |
|
||
| `relay-mistakes-2026-07-04.md` | Ошибки реле |
|
||
| `test-cases.md` | Тест-кейсы |
|
||
| `SETUP.md` | Инструкция по установке |
|
||
| `audit-2026-06-07.md` | Аудит проекта |
|
||
| `audit-prompt.md` | Промпт для аудита |
|
||
| `opus-review.md` | Рецензия кода (Opus) |
|
||
| `opus-fix-plan.md` | План исправлений по рецензии |
|
||
| `opus-questions.md` | Вопросы к Opus |
|
||
| `opus-questions-post-tests-2026-06-29.md` | Вопросы после тестов |
|
||
| `opus-recheck-request-2026-06-28.md` | Запрос на перепроверку |
|
||
| `opus-review-android.md` | Рецензия Android-кода |
|
||
| `sonnet-apk-cache-questions-2026-06-28.md` | Вопросы по кэшу APK |
|
||
| `android-bugs-2026-05-25.md` | Баги Android |
|
||
| `claude-analysis-elm.md` / `claude-analysis-elm-v2.md` | Анализ ELM от Claude |
|
||
| `claude-request-elm.md` / `claude-request-elm-v2.md` | Запросы к Claude по ELM |
|
||
| `session-*.md` | Логи сессий разработки по датам |
|
||
| `session-resume-2026-06-14.md` | Резюме сессии |
|
||
| `history/` | Архив старых заметок, логов сессий и результатов тестов по датам |
|
||
| `history/2026-05-31.md` | Лог сессии 31 мая |
|
||
| `history/2026-06-03.md` | Лог сессии 3 июня |
|
||
| `history/2026-06-05.md` | Лог сессии 5 июня |
|
||
| `history/2026-06-06.md` | Лог сессии 6 июня |
|
||
| `history/2026-06-07.md` | Лог сессии 7 июня |
|
||
| `history/2026-06-07-plans.md` | Планы на 7 июня |
|
||
| `history/2026-06-10.md` | Лог сессии 10 июня |
|
||
| `history/opus-recheck-analysis-2026-06-28.md` | Анализ перепроверки Opus |
|
||
| `history/opus-sonnet-comparison-2026-06-29.md` | Сравнение Opus vs Sonnet |
|
||
| `history/session-summary-2026-06-28.md` | Сводка сессии 28 июня |
|
||
| `history/sonnet-response-post-tests-2026-06-29.md` | Ответ Sonnet после тестов |
|
||
| `history/test-results-2026-06-28.md` | Результаты тестов 28 июня |
|
||
| `history/test-results-2026-07-04.md` | Результаты тестов 4 июля |
|
||
|