# elmAI — полное описание проекта для AI-агентов

> Последнее обновление: 2026-07-10 | Версия app: 1.18.0-dev | Версия raw: 0.4.1-dev

---

## 1. ЧТО ЭТО

elmAI — OBD2-диагностика автомобиля через ELM327-адаптер + LLM (DeepSeek).

Телефон подключается к ELM327 по Bluetooth, собирает данные с ЭБУ, отправляет на сервер, сервер анализирует через LLM и возвращает диагноз.

---

## 2. РЕПОЗИТОРИИ

| Репо | URL | Ветка | Что внутри |
|------|-----|-------|-----------|
| **Сервер** | `gitea.services.ngcloud.ru/Nail/elmer` | `dynamic-tests` | Python Flask + elmAI бэкенд |
| **Android** | `github.com/Repinoid/elmer-android` | `opus-fixes` | Kotlin Android-приложение |

**ВАЖНО**: Android-репо лежит ВНУТРИ серверного: `/home/naeel/elmer/android/`. Это отдельный git-репо со своим remote. Коммитить и пушить надо ИЗНУТРИ `android/`.

---

## 3. СЕРВЕР (obdai.ru, 5.172.178.213)

```
elmer/
├── api/           # Flask API
│   ├── routes.py  # Основные эндпоинты (script, upload, chat, probe, sessions)
│   ├── raw_elm.py # Командная очередь для raw-реле (SQLite table command_queue)
│   ├── db.py      # SQLite (sessions, device_profiles, command_queue)
│   ├── scripts.py # Сборка диагностических скриптов L0/L1/L2 + dynamic
│   ├── parser.py  # Парсинг ответов ELM327 (PID, DTC, VIN)
│   ├── dtc.py     # Эндпоинты DTC
│   ├── ping.py    # Эндпоинты ping/ping-llm
│   └── config.py  # Загрузка config.yaml
├── brain/         # LLM-клиент
│   ├── client.py  # Diagnoser — HTTP к DeepSeek
│   └── prompts.py # Промпты для диагностики
├── obd/           # ELM327 протокол (Python)
│   ├── protocol.py # Стейт-машина AndrOBD (ElmProt.java)
│   ├── connection.py, commands.py, classifier.py, probe.py, state.py, timing.py
├── web/           # Flask web
│   ├── app.py     # Точка входа, регистрация blueprints
│   ├── templates/index.html  # Страница загрузки APK
│   └── static/    # APK-файлы
├── doc/           # ВСЯ документация
├── config.yaml    # API-ключи, порты
└── deploy.sh      # Скрипт деплоя
```

**Стек**: Python 3, Flask, gunicorn (4 воркера, порт 8000), nginx (:443 → :8000), SQLite.

**Сервис**: `sudo systemctl restart elmer`

---

## 4. ANDROID

### 4.1. Основное приложение (`app/`) — прямая диагностика

**Пакет**: `ru.elmer.client` | **Версия**: 1.18.0-dev (versionCode 38)

```
app/src/main/java/ru/elmer/client/
├── Config.kt              # Константы: HOST, SCRIPT_URL, defaultScript(), client()
├── db/SessionDb.kt        # SQLite: sessions, responses
├── elm/
│   ├── ElmProtocol.kt     # Стейт-машина AndrOBD (1:1 с ElmProt.java)
│   ├── ElmChecker.kt      # Проверка ELM: checkDevice(), checkEcu(), scanDtc(), sendRaw()
│   └── ObdDecoder.kt      # Декодер PID/DTC/VIN (object-синглтон)
├── script/
│   └── DynamicCollector.kt # Циклический опрос PID с интервалом
├── server/
│   └── ServerClient.kt    # HTTP к серверу (OkHttp): ping, pingLlm, chat, getSessions, uploadSession, downloadScript
└── ui/
    └── MainActivity.kt    # UI: индикаторы, кнопка-трансформер, чат, диагностика, динамический тест
```

**8 классов**. Зависимости: OkHttp 4.12.0, AndroidX, org.json. БЕЗ Room, Coroutines, DI.

**Поток диагностики**: MainActivity → ElmChecker → ElmProtocol → команды → ObdDecoder → SessionDb → ServerClient.uploadSession() → ответ от LLM.

### 4.2. Raw-реле (`raw/`) — ретранслятор команд

**Пакет**: `ru.elmer.raw` | **Версия**: 0.4.1-dev (versionCode 18)

```
raw/src/main/java/ru/elmer/raw/
├── ElmProtocol.kt     # 1:1 копия app/ElmProtocol.kt
├── ElmActor.kt        # Single-thread executor вокруг ElmProtocol
├── RawRelayService.kt # Foreground-сервис: BT→init→поллинг команд→ответ
├── RelayClient.kt     # HTTP к /api/v1/elm/raw/* (OkHttp, БЕЗ X-Api-Key)
└── MainActivity.kt    # Минимальный UI (выбор BT, статус, счётчики)
```

**5 классов**. Отдельный APK (`applicationId: ru.elmer.raw`).

**Поток**: RawRelayService → connectBt → ElmProtocol.init() → hello → цикл: pollCommand → sendCommand → postResponse.

**Назначение**: тупой ретранслятор. Сервер диктует команды, телефон передаёт в ELM и возвращает ответы. Используется для интерактивной диагностики через Copilot и тестов 3 мин / 5 мин.

---

## 5. ANDROID — ЧТО СДЕЛАНО (рефакторинг 2026-07-10)

Ветка `opus-fixes`, 8 коммитов:

1. **Config.kt** — единый источник хоста (`https://obdai.ru`), замена всех хардкодов
2. **default_script.json** → `assets/`, DEFAULT_SCRIPT из кода удалён
3. **ServerClient** — добавлены `chat()` и `getSessions()`, весь HTTP через OkHttp + X-Api-Key
4. **HttpURLConnection** выпилен из MainActivity
5. **ElmChecker.sendRaw()** — инкапсуляция ElmProtocol, `getElm()` удалён
6. **FQN → import** — все полные имена заменены на нормальные import'ы
7. **Удалён мёртвый код**: ScriptRunnerService, ScriptEngine, UploadProgress + FOREGROUND_SERVICE permissions

**Результат**: 8 классов (было 10), 0 HttpURLConnection, 0 FQN, 0 getElm(), 0 obdai.ru вне Config, весь HTTP аутентифицирован.

---

## 6. ANDROID — ЧТО НЕ СДЕЛАНО (TODO)

### app/
- Разбить MainActivity (~750 строк) — вынести логику из UI
- Разбить ElmChecker (372 строки) — отделить BT от ELM-команд
- v1.5 клоны: деградация после 10-12 команд (ограничение железа)

### raw/
- **deviceId** генерится заново при каждом создании RelayClient — сохранить в SharedPreferences
- **Нет аутентификации** — BuildConfig.API_KEY есть, но RelayClient его не шлёт
- **Нет retry** при ошибках HTTP
- **SERVER_URL** захардкожен в build.gradle.kts и дублируется в Intent extra
- **drainInput() в write()** — потенциальный сдвиг буфера (Неудача #5 из failures-journal.md)

### Сервер
- Script Engine для режимов «3 мин на месте» / «5 мин в движении» — НЕ РЕАЛИЗОВАН
- Дублирование: routes.py и script_endpoint.py (script_endpoint.py — мёртвый)

---

## 7. РЕЖИМЫ ДИАГНОСТИКИ

### Режим 1: Прямая диагностика (app/)
Однократный сбор данных: скрипт → батч ответов → сервер → LLM → диагноз.

### Режим 2: Динамический тест (app/)
Циклический опрос PID. Кнопка СТАРТ/СТОП. Сервер подбирает тайминги через `/api/v1/test/next`.

### Режим 3: Raw-реле (raw/)
Сервер управляет потоком команд. Телефон — тупой ретранслятор.

### Режим 4: Прогрев на месте (raw/, 3 минуты)
3 PID (RPM, темп, дроссель) каждые 2 секунды × 90 циклов = 270 запросов. Оценка прогрева, холостых, реакции на газ.

### Режим 5: В движении (raw/, 5 минут)
Те же 3 PID каждые 2 секунды × 150 циклов = 450 запросов. Нагрузочный тест, динамика разгона.

*Режимы 4 и 5 требует реализации Script Engine на сервере.*

---

## 8. API ЭНДПОИНТЫ

### Основные (app/)

| Метод | Путь | Назначение |
|-------|------|-----------|
| GET | `/api/v1/ping` | Проверка сервера |
| GET | `/api/v1/ping-llm` | Проверка LLM |
| GET | `/api/v1/script?mode=test` | Скрипт диагностики |
| POST | `/api/v1/session/upload` | Загрузка батча + LLM-анализ |
| POST | `/api/v1/chat` | Чат с LLM |
| GET | `/api/v1/sessions` | Список сессий |
| POST | `/api/v1/test/next` | Следующий шаг динамического теста |
| GET/PUT | `/api/v1/elm/profile/<mac>` | Профиль скорости ELM |

### Raw-реле (raw/)

| Метод | Путь | Назначение |
|-------|------|-----------|
| POST | `/api/v1/elm/raw/hello` | Android: «я готов» (чистит старые команды) |
| POST | `/api/v1/elm/raw/cmd` | Copilot/сервер: поставить команду в очередь |
| GET | `/api/v1/elm/raw/cmd?device_id=X` | Android: забрать pending команду |
| POST | `/api/v1/elm/raw/response` | Android: вернуть ответ |
| GET | `/api/v1/elm/raw/response?device_id=X&seq=N` | Copilot: прочитать ответ |
| GET | `/api/v1/elm/raw/status` | Статус устройства |

---

## 9. ДЕПЛОЙ

### 9.1. Сервер

```bash
cd /home/naeel/elmer
git add -A && git commit -m "..." && git push origin dynamic-tests

ssh -i ~/.ssh/naeel_vm_id_ed25519 naeel@5.172.178.213 "
  cd /opt/elmer && git checkout dynamic-tests && git pull origin dynamic-tests
  pip install -r requirements.txt
  sudo systemctl restart elmer
"
```

### 9.2. Android APK (app)

```bash
# 1. Bump версии в app/build.gradle.kts (versionCode и versionName)
cd /home/naeel/elmer/android
sed -i 's/versionCode = XX/versionCode = YY/' app/build.gradle.kts
sed -i 's/versionName = "X.Y.Z-dev"/versionName = "X.Y+1.Z-dev"/' app/build.gradle.kts

# 2. Закоммитить + запушить
git add -A && git commit -m "bump vX.Y+1.Z-dev" && git push origin opus-fixes

# 3. Залить исходники на сервер и собрать APK
cd /home/naeel/elmer
tar czf /tmp/android-src.tar.gz --exclude='.git' --exclude='build' --exclude='.gradle' android/
scp -i ~/.ssh/naeel_vm_id_ed25519 /tmp/android-src.tar.gz naeel@5.172.178.213:/tmp/

ssh -i ~/.ssh/naeel_vm_id_ed25519 naeel@5.172.178.213 "
  rm -rf /opt/elmer/android && tar xzf /tmp/android-src.tar.gz -C /opt/elmer/
  cd /opt/elmer/android && gradle wrapper --gradle-version 8.7
  export ANDROID_SDK_ROOT=\$HOME/android-sdk
  ./gradlew :app:clean :app:assembleDebug
  cp app/build/outputs/apk/debug/app-debug.apk /opt/elmer/web/static/
"
# 4. Обновить версию в /opt/elmer/web/templates/index.html и /opt/elmer/templates/index.html
```

### 9.3. Raw APK

```bash
# Аналогично app, но:
# - bump версии в raw/build.gradle.kts
# - сборка: ./gradlew :raw:assembleDebug
# - копия: cp raw/build/outputs/apk/debug/raw-debug.apk /opt/elmer/web/static/elm-raw-v022.apk
```

---

## 10. ПРАВИЛА (НЕ НАРУШАТЬ)

1. **НИЧЕГО не делать без прямого указания пользователя.** Даже если видишь проблему — только сказать.
2. **На вопрос — только ответ.** Не продолжать «а ещё могу...», не предлагать помощь.
3. **После выполнения команды — сказать «готово» и ЖДАТЬ.**
4. **Коммит + push после КАЖДОЙ правки.** Один коммит = одна правка. Формат: `fix:`, `feat:`, `refactor:`, `bump:`, `docs:`, `style:`, `chore:`.
5. **При деплое — всегда bump версии.** Инкрементировать патч (Z в X.Y.Z-dev).
6. **ELM327 — только как AndrOBD (ElmProt.java).** Никакой самодеятельности в протоколе. Init: ATSP0→ATAT1→ATS0→ATL0→ATE0. Никакого drainInput() перед write().
7. **Не материться.** Пользователь матерится — ты нет.
8. **Не гадать.** Если не уверен — проверить факты чтением кода.
9. **Код правит ТОЛЬКО пользователь или Copilot по команде.** Не исполнять советы Opus по ELM-командам — Opus специалист по архитектуре кода, а не по ELM327.

---

## 11. КЛЮЧЕВЫЕ ДОКУМЕНТЫ

| Файл | Содержание |
|------|-----------|
| `AGENTS.md` | Этот файл — полное описание проекта |
| `doc/architecture.md` | Архитектура сервера и Android |
| `doc/diagnostic-logic.md` | 5 режимов диагностики |
| `doc/failures-journal.md` | 12 провалов при разработке raw-реле |
| `doc/SETUP.md` | Настройка окружения |
| `STRUCTURE.md` | Полное дерево файлов |
| `resume.txt` | Краткое резюме для нового чата |
| `.github/copilot-instructions.md` | Правила для Copilot |
| `android/doc/opus-arch-questions-2026-07-10.md` | Вопросы Opus по архитектуре |
| `android/doc/opus-refactor-plan-2026-07-10.md` | План рефакторинга от Opus |

---

## 12. КОНТАКТЫ / ДОСТУП

- **Сервер**: 5.172.178.213, SSH: `naeel@5.172.178.213`, ключ: `~/.ssh/naeel_vm_id_ed25519`
- **Домен**: obdai.ru (SSL через certbot)
- **Gitea**: gitea.services.ngcloud.ru/Nail/elmer
- **GitHub**: github.com/Repinoid/elmer-android