AutoKey — расшифровщик ошибок китайских EV и гибридов

Обзор проекта

AutoKey — веб-сервис, который переводит непонятный код или символ на приборной панели китайского электромобиля/гибрида в человекочитаемое описание: что это, насколько опасно и что делать прямо сейчас.

В отличие от универсальных баз OBD-II, сервис специализируется на китайских электрифицированных авто (BYD, Geely, Zeekr, Li Auto, Voyah, Changan, Avatr), где многие ошибки — заводские, не гуглятся одной строкой и приходят в машинном переводе низкого качества.

Быстрая карта решений

Ключевые решения

Зафиксированы принятые решения и — главное — почему. Это защита от повторного обсуждения одного и того же в будущих итерациях.

1. Ядро MVP: ручной ввод кода, а не фото и не OBD

Три способа ввода из идеи — это три независимых проекта:

• Фото → распознавание значка — полноценный ML-проект (нужна размеченная выборка изображений, которой нет).
• Прямое подключение OBD по BLE — требует нативного мобильного приложения; вдобавок многие китайские EV не отдают полезные данные по generic OBD-II. Это техническое ограничение платформы.
• Ручной ввод кода — минимум зависимостей, полностью легально, ядро ценности продукта.

Решение: MVP = только ручной ввод. Остальное — отдельные фазы.

2. Главная проблема — данные и право, а не код

Инженерная часть проста. Весь риск и вся ценность — в том, откуда легально взять базу расшифровок. Пять источников из исходной идеи в трезвой оценке:

Решение: база = открытый OBD-II + ручные карточки из официальных руководств + модерируемый краудсорсинг «своими словами». Партнёрства — бизнес-трек будущего, не инженерия MVP.

3. Бэкенд: Laravel + Filament (а не FastAPI)

По сути продукт — курируемый каталог + модерация краудсорсинга, а не «сервис с логикой». 80% работы — админка наполнения и очередь модерации.

• Laravel + Filament даёт продакшн-админку (CRUD, роли, модерация, аудит), зрелые auth и биллинг почти даром.
• FastAPI пришлось бы дополнять рукописной админкой (SQLAdmin/starlette-admin слабее Filament).
• Аргумент «будущий ML на Python» слабый: CV-часть в любом случае выносится в отдельный микросервис.

Решение: Laravel 11 + Filament 3. CV-сервис (Фаза 3) — отдельный Python-сервис.

4. Публичный фронт: SSR (Blade + Livewire), а не Vue-SPA

Поиск по коду — SEO-продукт. Серверный рендеринг даёт индексируемый HTML из коробки и минимум стека. Vue-SPA потребовал бы SSR-обвязки ради того же результата.

Решение: Blade + Livewire + Alpine + Tailwind. Vue — точечно, если появится тяжёлый интерактив.

5. Монетизация: freemium soft-gate

Платить за расшифровку пустой базы никто не будет, а жёсткий paywall убивает SEO-трафик.

Решение: публичный поиск бесплатен и индексируется; за подпиской — подробное руководство, полный список причин, история. Без клоакинга.

6. Домен

autokey.rosveb.ru — пока под документацию (этот файл). При запуске продукта домен может уехать под приложение, а доки — на поддомен.

Границы и фазы

Пользователи

• Основной: владелец BYD / Geely / Zeekr / Li Auto / Voyah / Changan / Avatr с непонятной ошибкой. Приходит из поиска по запросу вида «BYD Han ошибка P1C85».
• Вторичный (будущее): небольшие СТО и таксопарки — пакетный доступ к базе (Фаза 2+).
• Внутренний: авто-эксперт и модератор, наполняющие базу через админку.

Что входит в MVP (Фаза 1)

• Публичный поиск: бренд + модель + код → карточка расшифровки.
• Курируемая база (все 4 группы брендов в модели; наполнение приоритетно с BYD).
• SEO-страницы под каждый (бренд, модель, код) с SSR и sitemap.xml.
• Аккаунты пользователей.
• Soft-gate: бесплатная краткая часть индексируется; подробное руководство — за подпиской (платёж — Фаза 1.5).
• Filament-админка: наполнение, курирование, роли, аудит.
• Захват промахов: каждый запрос «код не найден» пишется в очередь (бренд, модель, код, счётчик) — одновременно сигнал спроса и приоритет курирования (см. Технические риски).
• Ревью-гейт критичности: severity проставляется только вручную экспертом, никогда из крауда/машинного перевода; неизвестно → консервативный «жёлтый».

Что НЕ входит в MVP

• Фото-распознавание значков (Фаза 3).
• Прямое подключение OBD по BLE (Фаза 4).
• Приём платежей (Фаза 1.5).
• Краудсорсинг и очередь модерации (Фаза 2).
• Мобильное приложение.

Дорожная карта

Критерии успеха MVP

• Поиск по коду отдаёт корректную карточку для наполненных брендов < 1 с.
• Каждая карточка (бренд, модель, код) доступна по SSR-URL и индексируется.
• Авто-эксперт заводит новую карточку через админку без разработчика.
• Есть измеримый органический трафик из поиска.

Архитектура и стек

                    ┌────────────────────────────┐
   Google/Яндекс ──▶│  Caddy (reverse proxy, TLS) │
      Гость ───────▶│  80 / 443, автосертификаты  │
                    └──────────────┬─────────────┘
                                   │ Host-роутинг
                 ┌─────────────────┼──────────────────┐
                 ▼                                     ▼
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │  Laravel 11 (PHP 8.3)     │          │  Статика (этот HTML)      │
   │  ── публичный SSR-сайт    │          │  autokey.rosveb.ru        │
   │     Blade + Livewire      │          │  (эта документация)       │
   │  ── REST (внутр.)         │          └──────────────────────────┘
   │  ── Filament 3 (админка)  │
   └───────┬───────────┬──────┘
           │           │
           ▼           ▼
   ┌────────────┐  ┌────────────┐
   │ PostgreSQL │  │   Redis    │
   │ данные+FTS │  │ кэш/очереди│
   └────────────┘  └────────────┘

Компоненты

Ядро — Laravel 11 (PHP 8.3). Одно приложение обслуживает публичный сайт (SSR на Blade + Livewire + Alpine + Tailwind), внутренний REST и админку Filament 3. Filament сам построен на Livewire — единый фронт-стек на весь проект.

Разделение ответственности: app/Models/ (Eloquent), app/Services/ (бизнес-логика: нормализация кода, поиск/фоллбэк, гейтинг — не в контроллерах), app/Livewire/ (публичные компоненты), app/Filament/ (ресурсы админки), app/Http/Controllers/ (тонкие контроллеры SSR + sitemap).

БД — PostgreSQL (уже развёрнута; помним про OOM-настройки: shared_buffers=4GB, work_mem=64MB). Поиск и нормализация — встроенный full-text + расширение pg_trgm (фаззи). Отдельный движок на MVP не нужен; при росте — Meilisearch.

Кэш и очереди — Redis: горячие карточки, результаты поиска; очереди (нотификации модерации, регенерация sitemap) — Фаза 2+.

Стек (сводка)

Развёртывание

• Всё в Docker, за общей сетью proxy; публикацию домена делает только Caddy (порты 80/443 хоста заняты им).
• Прямой dev-доступ — через свободный порт из PORTS.md.
• Публикация продакшн-домена — через proxy add.

Модель данных

Это моат продукта. Модель сразу проектируется под все фазы (краудсорсинг, модерация, доверие к источнику), но заполняется только тем, что нужно Фазе 1.

brands — марки

models — модели

codes — идентичность и скоуп кода

Один и тот же code у разных брендов — разные строки. Уникальность — (code, brand_id, model_id).

decodings — человекочитаемое содержимое

Разделение codes и decodings нужно для Фазы 2: на один код может прийти несколько кандидатных расшифровок из краудсорсинга, модерируемых независимо.

Нормализация и поиск

1. Нормализация ввода: trim, upper, унификация hex-форматов (0x1234 / BMS_0x1234 / BMS 1234 → канон BMS_0X1234).
2. Точный поиск published-расшифровки для (код, brand_id пользователя).
3. Фоллбэк: если производитель-специфичной нет, а код похож на OBD-II — отдаём generic с пометкой «общий код, значение может отличаться».
4. Фаззи (pg_trgm): при опечатке предлагаем ближайшие коды.

Публичный поиск и SEO

Публичный поиск — не только фича, а главный канал привлечения. Каждая расшифровка должна существовать как отдельная индексируемая страница.

Макет карточки

[ Марка: BYD ▾ ] [ Модель: Han ▾ ]
[ Код ошибки: P1C85_______ ]  [ Расшифровать ]
──────────────────────────────────────────────
⚠  Ошибка датчика темп. батареи, модуль №3
Критичность: 🟡 жёлтая — можно ехать, снизьте скорость
Причины: перегрев / обрыв датчика
Действие: дать остыть; если горит постоянно — в сервис
──────────────────────────────────────────────
🔒 Подробное руководство и полный список причин — по подписке

Светофор критичности

URL и индексация

• Каноничный URL расшифровки: /byd/han/p1c85 — тысячи long-tail страниц, каждая SSR и индексируема.
• Страницы бренда/модели (/byd, /byd/han) — хабы со списком кодов.
• Автогенерируемый sitemap.xml; разметка schema.org для сниппетов; canonical на каждой странице.

Производительность: горячие карточки в Redis; цель отклика < 1 с; фаззи-поиск через GIN-индекс pg_trgm по нормализованному коду.

Админка (Filament)

Админка — рабочее место наполнения базы. Именно здесь создаётся моат, поэтому она должна позволять авто-эксперту заводить карточки без участия разработчика.

Ресурсы и роли

Процесс наполнения (Фаза 1)

1. Эксперт заводит модель (если её ещё нет).
2. Создаёт код с корректным скоупом.
3. Пишет расшифровку: title_ru, severity, causes, short_action, deep_guide; указывает source и confidence.
4. Переводит в published — запись доступна публичному поиску и попадает в sitemap.

Источник данных на этом шаге — только официальные руководства производителя и собственные снятые логи. Все изменения расшифровок логируются (аудит).

Монетизация (soft-gate / freemium)

Что бесплатно (и индексируется)

• Название ошибки (title_ru), светофор (severity), краткая причина и быстрое действие (short_action).

Что за гейтом

• Подробное руководство (deep_guide), полный список причин, история запросов; (будущее) прогноз износа батареи, пакеты для СТО.

Тарифы (ориентир)

Реализация: Фаза 1 — аккаунты (Fortify) + гейтинг deep_guide за авторизацией, платёж ещё не подключён. Фаза 1.5 — эквайринг YooKassa/CloudPayments за интерфейсом app/Services/Billing/. Требует юрлица/самозанятости.

Юридическая граница данных

Самый важный раздел ТЗ. Ценность продукта — в базе расшифровок, а главный риск — нелегальный источник этой базы. Граница фиксируется жёстко и не размывается ради скорости наполнения.

✅ Разрешённые источники

• Стандарт OBD-II (P0xxx, U0xxx) — открытый отраслевой стандарт.
• Официальные руководства производителя — карты кодов, которые производитель сам публикует; заводятся вручную.
• Собственные снятые логи — расшифровки с реальных авто, верифицированные экспертом.
• Краудсорсинг «своими словами» — пользователь описывает наблюдаемый симптом; проходит модерацию (Фаза 2).

❌ Запрещённые источники

• Скрапинг и перепродажа autohome.com.cn, dongchedi.com, dtc.cheari.com и подобных.
• Данные дилерских порталов OEM для редистрибуции — ToS запрещают перепродажу.
• Проприетарные расшифровки Launch/Autel из логов как источник наполнения — риск редистрибуции. Краудсорсинг принимает симптом и слова пользователя, не копипаст текста платного сканера.
• Лицензирование community-профилей (Car Scanner) — права размыты.

Партнёрства — отдельный бизнес-трек

B2B-API Launch/Thinkcar и подписки на официальные OEM-порталы могут дать полноту данных легально, но это переговоры и договоры, а не разработка; не входят в MVP и не блокируют его. При заключении интегрируются как ещё один source без изменения архитектуры.

Технические риски и добыча данных

Оценка чисто технической осуществимости — механизмы, без юридической плоскости. Здесь сконцентрирован реальный риск проекта.

Каналы добычи — техническая осуществимость

Недооценённые проблемные вопросы

Что меняем в MVP (следствия)

• Петля захвата промахов — в Фазе 1: каждый «не найдено» пишется в очередь (бренд, модель, код, счётчик), курируем по реальному спросу. Лечит cold-start и задаёт приоритет наполнения.
• Ревью-гейт критичности — severity никогда не из крауда/MT, только ручная экспертная простановка; неизвестно → «жёлтый / осторожно».
• Идентичность кода — в модели хранить (ECU, DTC-номер, subtype), строка code — производное для отображения/поиска.
• Ожидания по OBD (Фаза 4) — зафиксировать: дешёвый ELM327 у BEV видит мало; ценность OBD-фазы под вопросом до проверки на реальных авто.
• Приоритет — data-пайплайн, а не ширина фич: ETL из руководств + краудсорсинг-экспорты + верификация важнее веб-функционала.

Открытые вопросы

Решённые

• ✅ Ядро MVP — ручной ввод кода → расшифровка.
• ✅ Бэкенд — Laravel 11 + Filament 3.
• ✅ Публичный фронт — Blade + Livewire + Alpine + Tailwind (SSR).
• ✅ Монетизация — freemium soft-gate.
• ✅ Старт наполнения — BYD → Geely/Zeekr → Li Auto → Voyah/Changan/Avatr.
• ✅ Домен — autokey.rosveb.ru пока под документацию.

Открытые

1. Домен продукта vs домен доков. При запуске продукт займёт autokey.rosveb.ru, а доки уедут на поддомен — или продукт на отдельном домене. Решить к деплою MVP.
2. Эквайринг и юрлицо. YooKassa или CloudPayments? Есть ли юрлицо/самозанятость под приём платежей? Без этого Фаза 1.5 не стартует.
3. Кто пишет экспертные карточки. Реальное узкое место — не код, а наполнение: сам разработчик / наёмный авто-эксперт / комбинированно. От ответа зависит скорость выхода на полезный объём базы.
4. Скоуп кода по поколению/году. В v1 достаточно (бренд, модель) или нужен ещё (поколение/год)? Задел в модели уже есть.
5. Язык. RU-only на старте или сразу закладывать мультиязычность? Ретрофит позже дороже.
6. Объём стартового наполнения. Сколько карточек на бренд считаем «минимально полезным» для запуска и SEO-эффекта?