From 3ea7fc66d5e78b5545991a85cd6bd3f76bf41b29 Mon Sep 17 00:00:00 2001 From: Repinoid Date: Fri, 10 Jul 2026 12:58:09 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20STRUCTURE.md=20=E2=80=94=20=D0=BE=D0=BF?= =?UTF-8?q?=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=B2=D1=81=D0=B5=D1=85?= =?UTF-8?q?=20=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2=20=D0=B8=20=D0=BF=D0=B0?= =?UTF-8?q?=D0=BF=D0=BE=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- STRUCTURE.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 STRUCTURE.md diff --git a/STRUCTURE.md b/STRUCTURE.md new file mode 100644 index 0000000..1967b9f --- /dev/null +++ b/STRUCTURE.md @@ -0,0 +1,181 @@ +# Структура репозитория 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 июля | +