docs: STRUCTURE.md — описание всех файлов и папок

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 июля |
+