Отчёты и документы — Макс Пастухов

Документ — это отчёт или панель: сетка блоков с графиками, таблицами, метриками и текстом. Документы образуют дерево папок, хранятся как обычные JSON-файлы и обновляются на экране в реальном времени.

Структура документа

Каждый документ описывается JSON-файлом document.json: заголовок, массив блоков, переменные, права доступа и метаданные.

{
  "title": "Название документа",
  "blocks": [],
  "variables": {},
  "permissions": { "access": "admin-only" },
  "settings": {
    "rangeSelector": false,
    "timeframeSelector": false
  },
  "metadata": {
    "created": "ISO8601",
    "modified": "ISO8601",
    "version": 1,
    "tags": ["тег1"],
    "icon": "filename.svg"
  }
}

Картинки и файлы в тексте отчёта

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

картинки (png, jpg, gif, webp, avif, svg) показываются на месте, а всё остальное — PDF, таблицы, архивы — скачивается;
ссылку на файл приложение подписывает и выдаёт читателю временно: адрес действует 12 часов и обновляется при каждом открытии отчёта — постоянной открытой ссылки на файл не остаётся;
через этот адрес доступен только текст документов: достать по нему чужие файлы или папки нельзя;
внешние ссылки, ссылки-якоря внутри отчёта, ссылки на другие документы и всё, что написано внутри блока с кодом, остаются как написаны;
если файл удалить или переименовать, ссылка перестанет работать — переносите папку отчёта целиком, вместе с файлами.

Справка по блоку

Блок — это название, тип содержимого, ширина в колонках сетки (от 1 до 24) и высота. К блоку можно добавить короткое пояснение: в режиме просмотра рядом с кнопкой обращения к агенту появится значок «Справка», по клику всплывёт подсказка о том, как читать этот график и на что смотреть. В шаблонах такие пояснения есть у каждого блока, а у плиток с метриками — обязательно: отчёт объясняет себя сам, и пересказывать его коллегам словами не нужно.

Вложенность и навигация

документы образуют дерево папок — вложенность не ограничена;
навигация по дереву — через хлебные крошки;
пути документов могут содержать переменные — один шаблон порождает семейство отчётов (подробнее — Переменные и шаблоны);
перемещение и удаление документов выполняются прямо в интерфейсе.

Новые документы и действия в боковой панели

Боковая панель подсказывает, что появилось или изменилось: название такого документа выделено, пока его не откроют. Изменённым документ считается только по содержимому — если файл просто скопировали на место, тронули дату или поменяли права, выделения не будет, а переписанное содержимое выделится, даже когда дата файла не изменилась. Изменения, сделанные при выключенном приложении, тоже находятся при следующем запуске.

у каждой строки — и у документа, и у папки, и у корневой строки «Документы» — при наведении появляется кнопка с тремя точками; то же меню открывается правым щелчком по строке;
«Отметить прочитанным» снимает выделение: у документа — с него, у папки — с неё и со всех документов внутри, у корневой строки — сразу со всего дерева;
«Обновить значок» открывает поиск по библиотеке значков и ставит выбранный значок этому документу; значок хранится в метаданных, и у корневого документа — домашней страницы раздела — тоже может быть свой;
выделение общее для всех открытых экранов: отметили прочитанным в одной вкладке — пропало во всех.

Фильтры и параметры отчёта

Читателю отчёта можно дать рычаги — не правку файла, а обычные элементы управления в шапке:

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

Погружение, связанные блоки и вкладки

Отчёт отвечает на уточняющий вопрос, не уводя читателя на другую страницу:

Погружение по клику — клик по столбцу, точке, сектору, ячейке или региону на карте задаёт значение фильтра: отчёт пересчитывается по этому значению, а в шапке появляется плашка с выбранным значением и крестиком. Крестик снимает выбор — и всё возвращается. Так «продажи упали» разворачивается в «упали в этом канале на этих товарах»;
Связанные блоки — графики и таблицы одного отчёта можно связать: наведение на неделю, точку или строку подсвечивает то же значение в соседних блоках. Запросы при этом не выполняются — это только подсветка, отчёт не перерисовывается заново;
Вкладки по аудиториям — один отчёт может показывать разным читателям разное: например, вкладку «Итог для руководителя» с главными числами и вкладку «Расчёты аналитика» с деталями. Общие блоки видны на всех вкладках, а данные загружаются один раз — переключение мгновенное;
Состояние оповещений — блок можно привязать к правилу оповещений, и на отчёте будет видно, спокойно правило или срабатывает (подробнее — в разделе Оповещения).

Отчёты из шаблонов

Готовый отчёт из библиотеки шаблонов лежит прямо в папке шаблона — без вложенных папок с отчётами. Рядом с ним идут демонстрационные данные, скрипты подготовки и два текстовых блока в конце отчёта: «Быстрый старт» — как читать отчёт и что нажимать, и «Пояснение» — подробное описание. Читают их по порядку: «Быстрый старт» первым, «Пояснение» — в самом конце.

Агент адаптирует шаблон под ваши данные и устанавливает готовый отчёт в раздел «Документы» — дальше он живёт как обычный документ.

Хранение: JSON-файлы

Документы хранятся в /project/apps/analytics/documents/ как JSON-файлы. Это значит: версионирование в Git, ручное редактирование в любом редакторе, перенос между экземплярами простым копированием папки.

Мгновенный reload

file watcher на inotify отслеживает изменения файлов документов;
список документов обновляется на ходу — новые и изменённые отчёты появляются сразу;
правки ИИ или ручные правки JSON видны на экране без перезагрузки;
обновления блоков транслируются клиентам через SignalR/WebSocket.

Права доступа

admin-only — документ виден только администратору;
authenticated — всем вошедшим пользователям;
public — публичные отчёты можно показывать без входа: удобно для внешних панелей.

Метаданные, поиск, импорт и экспорт

метаданные: версия, теги, иконка, даты создания и изменения;
поиск по документам и по библиотеке шаблонов — по мере ввода, из боковой панели;
экспорт отчёта: готовый PDF для отправки или ZIP-архив всей папки документа — для переноса на другой экземпляр;
импорт из архива: при переносе чужого отчёта имена его источников данных можно сразу заменить на свои;
«Лучшие документы» и «Недавние документы» на главном экране.

← Оглавление документации