Встроенная отчетность об ошибках: как мы создали универсальную систему отчетности об ошибках
Узнайте, как Reliable Communications разработала универсальную систему отчетности об ошибках для AvatarMatch, улучшая пользовательский опыт и отслеживание ошибок.
Каждый продукт в конечном итоге сталкивается с одной и той же проблемой: пользователи находят ошибки, но не знают, как их сообщить. Электронное письмо на support@? Скриншот в мессенджере? Пост в социальных сетях? Чем сложнее путь от обнаружения проблемы до ее исправления, тем больше ошибок остается незафиксированными.
В Reliable Communications s.r.o. мы системно решили эту проблему и создали встроенную платформу для отчетности об ошибках, которая работает непосредственно внутри приложения. Она уже функционирует в AvatarMatch, но разработана как универсальный модуль, подходящий для любого веб-продукта.
В этой статье мы подробно рассмотрим архитектуру, процесс обработки и возможности системы.
Проблема: почему внешние трекеры не работают для конечных пользователей
Jira, Linear, GitHub Issues — все это отличные инструменты для команд разработчиков. Но попробуйте попросить обычного пользователя создать задачу в GitHub. Результат предсказуем: 95% ошибок просто не будут зафиксированы.
Классический подход «напишите нам на электронную почту» также имеет свои недостатки:
- Пользователь не укажет URL, где произошла ошибка
- Не включит версию браузера и ОС
- Не опишет шаги воспроизведения
- Служба поддержки потратит время на уточняющие вопросы
- Ошибка потеряется в цепочке электронных писем
Вам нужен инструмент, который встроен в продукт, автоматически собирает контекст и предоставляет пользователю простую, понятную форму.
Архитектура системы
Компоненты
Система состоит из нескольких слоев:
| Слой | Технология | Назначение |
|---|---|---|
| Floating Action Button (FAB) | React + Lucide Icons | Точка входа — видна на каждой странице |
| Drawer with form | React | Собирает описание, ожидаемое поведение, шаги, вложения |
| Attachment uploader | React + Firebase Storage | Изображения (PNG, JPEG, WebP) и видео (MP4, WebM) |
| Auto-context collection | Client-side JS | URL, браузер, ОС, устройство, размер окна, локаль, часовой пояс, версия приложения |
| REST API | Astro SSR endpoints | Создание, список, фильтрация, модерация |
| Storage | Firestore | Документы об ошибках, события в таймлайне, счетчики |
| Bug portal | Astro + React | Просмотр всех/моих отчетов, подробная карточка отчета |
| AI triage | Server pipeline | Автоматическая валидация, нормализация, классификация |
| GitHub integration | Admin API | Ссылка на задачи, синхронизация статусов |
| Analytics | Custom Events | Отслеживание действий пользователей на всем пути |
Плавающая кнопка — точка входа
На каждой странице приложения (кроме страниц аутентификации: /login, /register, /forgot-password, /auth/*, /wizard) отображается плавающая кнопка с иконкой ошибки. Список исключений настраивается через переменную окружения PUBLIC_BUG_REPORT_EXCLUDE_PREFIXES.
При нажатии на нее открывается Drawer — боковая панель с формой отчета. Если пользователь не аутентифицирован, он увидит запрос на вход. Если форма была заполнена и пользователь пытается закрыть боковую панель, система показывает подтверждение отмены.
Форма отчета
Форма содержит следующие поля:
- Заголовок (необязательно, до 120 символов) — краткое описание проблемы
- Что произошло (обязательно, 10–5,000 символов) — подробное описание ошибки
- Ожидаемое поведение (обязательно, 5–3,000 символов) — что должно было произойти
- Шаги для воспроизведения (необязательно, до 3,000 символов) — пошаговые инструкции
- Видимость — частный или публичный отчет
- Вложения — до 5 файлов: изображения до 10 МБ, видео до 100 МБ (до 90 секунд длиной)
Валидация происходит как на стороне клиента (мгновенные подсказки), так и на стороне сервера (повторная проверка всех ограничений).
Автоматический сбор контекста
Одной из ключевых особенностей системы является автоматический сбор технического контекста в момент подачи отчета. Пользователю не нужно ничего знать о своем браузере — система все определяет автоматически:
- URL страницы и имя маршрута
- Название страницы
- Браузер и версия (Chrome, Safari, Firefox, Edge)
- Операционная система (Windows, macOS, Android, iOS, Linux)
- Тип устройства (настольный, мобильный, планшет)
- Размер окна и разрешение экрана
- Локаль и часовой пояс
- Версия приложения
- ID сессии (генерируется на стороне клиента, хранится в sessionStorage)
Этот контекст отправляется на сервер вместе с формой и сохраняется в документе об ошибке. При просмотре отчета в портале разработчик видит полную картину окружения, в котором произошла ошибка.
Жизненный цикл ошибки: от PendingCheck до Resolved
Каждый отчет об ошибке проходит через формализованный статусный процесс:
PendingCheck → Normalizing → Triaging → RepoChecking → Confirmed → InProcess → Open → Resolved
↘ Closed
↗ Cancelled
↗ Duplicate
↗ Rejected
Разделение статусов
| Статус | Значение |
|---|---|
| PendingCheck | Отчет только что создан, ожидает первоначального обзора |
| Normalizing | AI нормализует текст: исправляет форматирование, извлекает структуру |
| Triaging | AI определяет приоритет, категорию и потенциальный уровень воздействия |
| RepoChecking | Проверка на дубликаты среди существующих отчетов |
| Confirmed | Ошибка подтверждена, ожидает назначения |
| InProcess | Исправление находится в процессе работы |
| Open | Ошибка открыта и зарегистрирована в трекере |
| Resolved | Исправление завершено |
| Closed | Отчет закрыт (вручную или автоматически) |
| Cancelled | Отменен автором или модератором |
| Duplicate | Обозначен как дубликат существующего отчета |
| Rejected | Отклонен (не ошибка, не воспроизводится, вне области действия) |
Терминальные статусы — Cancelled, Closed, Duplicate, Rejected, Resolved — блокируют дальнейшее редактирование содержимого и отмену публичных отчетов автором.
AI Triage: Автоматическая обработка отчетов
После создания отчет проходит через серверный AI-процесс, который выполняет несколько шагов:
- Нормализация — структурирование текста, исправление очевидных опечаток, извлечение ключевых данных
- Triage — автоматическое определение серьезности (уровня воздействия), категории и приоритета
- Обнаружение дубликатов — сравнение с существующими открытыми отчетами
- Валидация — фильтрация спама, недействительных или пустых отчетов
Каждый шаг фиксирует использование токенов (запрос, завершение, всего), что позволяет контролировать затраты на обработку AI. Данные о использовании токенов видны администраторам в представлении деталей отчета — с разбивкой по шагам.