---
title: "Отчёты и документы"
id: "1337"
type: "page"
slug: "reports"
published_at: "2026-08-15T23:32:26+00:00"
modified_at: "2026-11-06T09:29:17+00:00"
url: "https://pastukhov.com/agents/analytics/docs/reports/"
markdown_url: "https://pastukhov.com/agents/analytics/docs/reports.md"
excerpt: "Документ — это отчёт или панель: сетка блоков с графиками, таблицами, метриками и текстом. Документы…"
---

# Отчёты и документы

[https://pastukhov.com/agents/analytics/docs/reports/.md](https://pastukhov.com/agents/analytics/docs/reports/.md)

Документ — это отчёт или панель: сетка блоков с графиками, таблицами, метриками и текстом. Документы образуют дерево папок, хранятся как обычные 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) и высота. К блоку можно добавить короткое пояснение: в режиме просмотра рядом с кнопкой обращения к агенту появится значок «Справка», по клику всплывёт подсказка о том, как читать этот график и на что смотреть. В шаблонах такие пояснения есть у каждого блока, а у плиток с метриками — обязательно: отчёт объясняет себя сам, и пересказывать его коллегам словами не нужно.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Мгновенный reload

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

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

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

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

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

[← Оглавление документации](/agents/analytics/docs)