Экспорт отчёта и передача «Событий»

«События» теперь имеют контракт, исходный и логический слои, счётчики, воронку, когорты, агрегаты и примеры срока хранения. Последний шаг — передать результат редактору через понятный отчёт. Экспорт должен сохранять определения метрик, а договор проекта — объяснять, как обновляются данные и какие возможности ещё отсутствуют.

В рамках серии ClickHouse не запускался, файлы не загружались в базу, запросы не выполнялись и dashboard не подключался к работающему серверу. Архив содержит исходники и отдельно обозначенные ожидаемые примеры вывода. example_execution: not_run сохраняется для всего комплекта; вымышленные числа нельзя представить как измеренную посещаемость сайта.

Таблица для редактора

Минимальный отчёт содержит материал, просмотры, завершения и закладки за явно выбранный период. Для внешнего интерфейса не нужен список anon_id. Сначала агрегируем серверным запросом, затем передаём только результат. Это уменьшает объём индивидуальной истории, доступной клиенту dashboard.

Полный SQL-экспорт использует уже известный логический слой и формат CSV с именами колонок. Он не отправляет файл по сети сам по себе; способ сохранения результата зависит от используемого клиента.

SELECT lesson_id,
  countIf(event_name = 'lesson_view') AS views,
  countIf(event_name = 'lesson_complete') AS completions,
  countIf(event_name = 'bookmark') AS bookmarks
FROM events_lab.logical_events
WHERE occurred_at >= toDateTime64('2026-10-01 00:00:00', 3, 'UTC')
  AND occurred_at < toDateTime64('2026-10-05 00:00:00', 3, 'UTC')
GROUP BY lesson_id
ORDER BY lesson_id
FORMAT CSVWithNames;

Ожидаемое содержимое для полного набора можно прочитать как небольшую таблицу. Это файл expected/lesson-report.csv архива, вручную выведенный из фикстуры, а не фактически сохранённый вывод ClickHouse.

lesson_id,views,completions,bookmarks
css-layout,2,2,1
html-start,4,3,2
js-events,1,0,0

Документация форматов ClickHouse описывает доступные представления ответа. Предметные имена, период и правило дедупликации определены нами. При подключении клиента нужно согласовать обработку кавычек, кодировку и отображение отсутствующих строк, а не полагаться на визуальное совпадение маленького примера.

Метаданные рядом с числом

Dashboard должен показывать период действия, временную зону и время получения среза. Позднее событие может изменить первый октябрь пятого числа, поэтому надпись «обновлено» имеет смысл отдельно от даты показателя. Если слой является снимком, нужна ещё дата его пересчёта.

Воронка подписывается «просмотр и последующее завершение в течение суток, пара браузер–урок». Удержание подписывается «просмотр на следующий календарный день UTC, первый наблюдаемый просмотр». Эти формулировки длиннее слова «конверсия», но предотвращают неверное сопоставление с другим инструментом.

Пустой результат за период должен быть отличим от ошибки запроса. При нуле событий интерфейс может показать нули или отсутствие материалов по определённому договору. При отказе базы он сообщает, что данные недоступны, и сохраняет время последнего успешного среза, если такой срез действительно существует. Не создавайте фиктивный свежий отчёт из пустого массива в catch.

Чтение с ограниченными правами

Клиентский dashboard не должен содержать пароль ClickHouse. Серверный endpoint читает разрешённый агрегат и отдаёт безопасную форму. Его учётная запись получает только необходимые права, а параметры периода и материала проверяются до запроса. Произвольный SQL из браузера не является фильтром отчёта.

Для локального CSV такой endpoint пока не нужен: редактор может открыть экспорт вручную. Внешнее размещение, аутентификация панели и контроль доступа требуют отдельного проекта. Архив содержит спецификацию ответа, но не заявляет, что готовая панель уже работает на ProfessorWeb.

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

Исходники и порядок применения

Скачать комплект «Событий». В нём находятся CONTRACT.md, JSONL, SQL-файлы, ожидаемые таблицы и HANDOFF.md. README описывает два согласованных сценария: простой логический набор без view и вариант, где materialized view создаётся до загрузки доставок. Не смешивайте повторные вставки из разных уроков без понимания физического слоя.

DDL и запросы сохранены как исходники, а не исполняемый отчёт. Их будущий запуск требует выбранного релиза ClickHouse, учётной записи, базы и согласованной среды. Версия сервера, настройки, точное время выполнения и фактический вывод должны попасть в отдельный журнал после выполнения. Пока этот журнал отсутствует, статус остаётся not_run.

Промышленный приёмник событий не включён. Он должен проверять контракт, минимизацию, размер пакета, время, допустимые уроки и правила повторной доставки. Браузерное отправление напрямую в ClickHouse не заменяет этот слой. Основное приложение по-прежнему хранит текущий прогресс независимо от аналитики.

Что нужно решить до внешнего использования

Владелец должен выбрать стабильные правила lesson_view, источник UUID, срок браузерного идентификатора и условия прекращения измерения. Затем определить допустимую задержку и финальность периода, стратегию пересчёта снимка и срок каждого слоя. Без этих правил отчёт способен меняться корректно технически и неожиданно для редактора.

Отдельные решения нужны для очереди доставки, отказов сборщика, резервных копий и выгрузок. Сохранение события основного приложения и приём аналитики не имеют здесь общего транзакционного механизма. Если потеря даже малого числа действий неприемлема, требуется более строгий путь передачи и его фактическая проверка.

Следующий владелец может начать с ручного сопоставления шестнадцати доставок и пятнадцати логических событий, затем проверить позднее завершение, повторный пакет, воронку, зрелость когорт и действие TTL. Эти сценарии описаны как ожидания и не были выполнены при написании серии.

Связь с общим учебным маршрутом

Оглавление серии входит в прикладной продуктовый маршрут. Кабинет читателя и аналитический поток можно изучать вместе, однако их состояние различается: кабинет хранит текущие отметки, аналитика сохраняет оговорённые факты действий. Внешняя интеграция между ними здесь не выполнялась.

При следующей редакционной правке меняйте определение показателя вместе с запросом, ожидаемым выводом и договором. Один исправленный SQL без обновлённой подписи оставит редактора с прежним пониманием числа. Сохранение источников и конкретных границ помогает продолжать проект так же последовательно, как он был построен в уроках.

Законченный учебный результат — прозрачная цепочка от действия до числа. Контракт определяет смысл строки, таблица хранит доставки, логический слой устраняет оговорённые повторы, SQL задаёт единицу наблюдения, а dashboard сохраняет период и время среза. Такая цепочка позволяет обсуждать аналитическое решение предметно, не подменяя собственное хранилище готовой аналитикой, рабочим репозиторием аккаунтов или диагностикой запросов.

Оглавление серии