---
title: "Отчёты и документы"
id: "1337"
type: "page"
slug: "reports"
published_at: "2026-08-15T23:32:26+00:00"
modified_at: "2026-10-04T01:35: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"
  }
}
```

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

Блок — это название, тип содержимого, ширина в колонках сетки (от 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)