Встроенная отчетность об ошибках: как мы создали универсальную систему отчетности об ошибках

Каждый продукт в конечном итоге сталкивается с одной и той же проблемой: пользователи находят ошибки, но не знают, как их сообщить. Электронное письмо на 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 — боковая панель с формой отчета. Если пользователь не аутентифицирован, он увидит запрос на вход. Если форма была заполнена и пользователь пытается закрыть боковую панель, система показывает подтверждение отмены.

Форма отчета

Форма содержит следующие поля:

1. Заголовок (необязательно, до 120 символов) — краткое описание проблемы
2. Что произошло (обязательно, 10–5,000 символов) — подробное описание ошибки
3. Ожидаемое поведение (обязательно, 5–3,000 символов) — что должно было произойти
4. Шаги для воспроизведения (необязательно, до 3,000 символов) — пошаговые инструкции
5. Видимость — частный или публичный отчет
6. Вложения — до 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-процесс, который выполняет несколько шагов:

1. Нормализация — структурирование текста, исправление очевидных опечаток, извлечение ключевых данных
2. Triage — автоматическое определение серьезности (уровня воздействия), категории и приоритета
3. Обнаружение дубликатов — сравнение с существующими открытыми отчетами
4. Валидация — фильтрация спама, недействительных или пустых отчетов

Каждый шаг фиксирует использование токенов (запрос, завершение, всего), что позволяет контролировать затраты на обработку AI. Данные о использовании токенов видны администраторам в представлении деталей отчета — с разбивкой по шагам.

Видимость и конфиденциальность