FastReport — Настройка и решение проблем¶
Назначение: ответы на типовые обращения клиентов по настройке FastReport и работе с отчётами Связан с: backend.md, admin.md
1. Архитектура отчётов¶
Пользователь → Веб-интерфейс → API (reports/view/{id}) → FastReport Engine → SQL Server / PG → Готовый отчёт
↑
Reports.ContentXml (шаблон)
1Ф поддерживает два способа создания отчётов через FastReport: - Win-дизайнер (десктопное приложение) — полный функционал, требует установки - Онлайн-дизайнер (в браузере) — ограниченный функционал, не требует установки
2. Предварительные требования для Win-дизайнера¶
На компьютере пользователя¶
- FastReport Designer — поставляется в ZIP-архиве из категории «Репозиторий версий приложения» (не скачивается из интерфейса)
- .NET Framework 4.7.1 или выше — скачать
- Сетевой доступ к SQL Server — дизайнер подключается напрямую к БД
Сетевые доступы (что запросить у ИТ)¶
| Ресурс | Порт | Зачем |
|---|---|---|
| SQL Server 1Ф | 1433 (TCP) | Дизайнер подключается к БД для получения данных |
| Сервер 1Ф (web) | 443/80 | Для сохранения шаблона обратно в 1Ф |
Учётная запись SQL Server¶
Дизайнер использует connection string из 1Ф. Два варианта:
- Windows Authentication — учётная запись Windows пользователя должна иметь доступ к БД 1Ф (
db_datareaderминимум) - SQL Authentication — логин/пароль SQL Server (задаётся в connection string отчёта)
Важно: учётная запись дизайнера должна иметь:
- SELECT на таблицы, которые используются в отчётах
- EXECUTE на хранимые процедуры, если отчёт их вызывает
- Рекомендуемая роль: db_datareader + точечные EXECUTE на нужные SP
3. Настройка в 1Ф (пошагово)¶
3.1 Создание отчёта¶
Администрирование → Отчёты → Создать отчёт
| Поле | Описание |
|---|---|
| Название | Отображаемое имя отчёта |
| Режим | FastReports (для FastReport-шаблонов) |
| Контекст | Откуда доступен: Задача, Категория, Раздел, Пользователь, Группа |
| Блок | Группировка в UI |
| Скрытый | Если true — не показывается пользователям |
3.2 Настройка прав доступа¶
Администрирование → Отчёты → [отчёт] → Права
Права настраиваются по группам:
| Право | Описание |
|---|---|
| Просмотр | Кто видит отчёт в списке и может генерировать |
| Аннотация | Кто может редактировать описание |
| Специальные | Полный доступ (администратор отчёта) |
Если права не назначены — отчёт виден только администраторам.
3.3 Контекст отчёта¶
Контекст определяет, какие параметры автоматически доступны в шаблоне:
| Контекст | Автопараметр | Где отображается |
|---|---|---|
| Задача | taskId |
В карточке задачи |
| Категория | categoryId |
В гриде категории |
| Раздел | — | В разделе |
| Пользователь | userId |
В профиле пользователя |
| Группа | groupId |
В настройках группы |
Параметр CurrentUserId доступен всегда — ID текущего пользователя.
3.4 Фильтры отчёта¶
Фильтры позволяют пользователю задавать параметры перед генерацией. Настраиваются в Администрирование → Отчёты → [отчёт] → Фильтр.
4. Работа с Win-дизайнером¶
4.1 Запуск¶
- Распаковать ZIP-архив дизайнера
- Запустить
TCReportDesigner.exe - В списке отчётов выбрать нужный → «Win-дизайнер»
- Дизайнер скачает шаблон и откроется
4.2 Источники данных¶
В дизайнере доступны:
- Таблицы БД — прямой доступ к таблицам 1Ф
- SQL-запросы — произвольные SELECT
- Хранимые процедуры — с параметрами
- Несколько Connection — можно подключить дополнительные БД
Connection string подставляется автоматически из настроек 1Ф. Таймаут SQL-команд: 120 секунд (настройка FastReportCommandTimeoutSeconds).
4.3 Сохранение¶
При сохранении дизайнер отправляет XML-шаблон обратно в 1Ф через endpoint ~/MVC/ReportDesigner/Save. Шаблон записывается в Reports.ContentXml.
5. Онлайн-дизайнер¶
Доступен из интерфейса: Отчёты → [отчёт] → Онлайн-дизайнер.
Требует права администратора в 1Ф.
Ограничения по сравнению с Win-дизайнером: - Нет полного набора компонентов - Нет прямого доступа к connection strings - Не все форматы экспорта доступны
6. Форматы экспорта¶
| Формат | Расширение | Особенности |
|---|---|---|
| Основной формат. Встраивание шрифтов, сжатие | ||
| Word | .docx | Несколько режимов: WYSIWYG, постраничный, абзацный |
| Excel | .xlsx | Режимы: постраничный, бесшовный, только данные |
| PowerPoint | .pptx | Изображения в PNG или JPEG |
| RTF | .rtf | С разрывами страниц |
| HTML, CSV, XML, TXT, DBF, ODS, ODT | — | Дополнительные форматы |
7. Типичные проблемы и решения¶
7.1 «Не могу подключить дизайнер к БД»¶
Симптом: при открытии Win-дизайнера ошибка подключения к SQL Server.
Проверить:
1. Сеть: с компьютера пользователя telnet sql-server 1433 — порт должен быть открыт
2. Учётная запись: если Windows Auth — пользователь должен быть в домене и иметь доступ к БД. Если SQL Auth — проверить логин/пароль
3. Firewall: SQL Server может слушать на нестандартном порту или блокировать внешние подключения
4. Named Pipes vs TCP/IP: проверить что TCP/IP включен в SQL Server Configuration Manager
7.2 «Отчёт не отображается у пользователя»¶
Проверить:
1. Reports.IsHidden — не скрыт ли отчёт?
2. Права — назначены ли группе пользователя права на просмотр?
3. Контекст — если отчёт привязан к контексту (задача/категория), он отображается только в этом контексте
7.3 «Отчёт генерируется медленно или с ошибкой таймаут໶
Проверить:
1. SQL-запросы в шаблоне — оптимизировать (добавить индексы, упростить)
2. Таймаут — по умолчанию 120 секунд. Увеличить FastReportCommandTimeoutSeconds в конфигурации
3. Объём данных — при большом объёме использовать фильтры для ограничения выборки
7.4 «Нет кнопки Win-дизайнер»¶
- Win-дизайнер доступен только для отчётов с
Mode = FastReports - Требуется роль администратора
7.5 «Где скачать дизайнер?»¶
Дизайнер поставляется в ZIP-архиве из категории «Репозиторий версий приложения» в 1Ф. Ссылка для скачивания из интерфейса убрана.
8. Таблицы БД¶
Основная таблица: dbo.Reports¶
| Поле | Тип | Описание |
|---|---|---|
id |
int | PK |
Description |
varchar(500) | Название отчёта |
ContentXml |
varchar(max) | XML-шаблон FastReport |
Context |
int | Тип контекста (0=Task, 1=Subcat, 2=Category, 3=User, 4=Group) |
Mode |
int | Режим (0=ExtForms, 2=FastReports) |
IsHidden |
bit | Скрытый |
IsSystemReport |
bit | Системный |
ExternalObjectId |
uniqueidentifier | FK на ExternalObjects (права) |
UserID |
int | Владелец |
Block |
varchar(200) | Группа в UI |
ExportSettings |
nvarchar(max) | JSON настроек экспорта |
GUID |
uniqueidentifier | Уникальный ID |
Связанные таблицы¶
| Таблица | Описание |
|---|---|
ReportContextObjects |
Привязка отчёта к контексту (категория, задача и т.д.) |
ReportFilterLinks |
Привязка фильтров к отчёту |
ExternalObjects + ExternalObjectsViewRights |
Права доступа к отчёту |
9. Диагностические SQL-запросы¶
set transaction isolation level read uncommitted;
-- Все FastReport-отчёты
select
r.id,
r.Description,
r.Context,
r.IsHidden,
r.IsSystemReport,
r.UserID,
u.FullName as Владелец,
len(r.ContentXml) as ШаблонSize
from dbo.Reports r with (nolock)
left join dbo.Users u with (nolock)
on u.UserID = r.UserID
where r.Mode = 2
order by r.Description;
-- Права на отчёт
select
r.Description as Отчёт,
g.Name as Группа,
eovr.RightType
from dbo.Reports r with (nolock)
join dbo.ExternalObjects eo with (nolock)
on eo.GUID = r.ExternalObjectId
join dbo.ExternalObjectsViewRights eovr with (nolock)
on eovr.ExternalObjectId = eo.Id
join dbo.Groups g with (nolock)
on g.GroupID = eovr.GroupID
where r.id = @ReportId
order by g.Name;
-- Контекст отчёта
select
r.Description as Отчёт,
rco.ContextObjectType,
rco.ContextObjectId
from dbo.Reports r with (nolock)
join dbo.ReportContextObjects rco with (nolock)
on rco.ReportId = r.id
where r.id = @ReportId;
10. API endpoints¶
| Endpoint | Метод | Описание |
|---|---|---|
reports/view/{id} |
GET/POST | Генерация отчёта |
reportdesigner/{id} |
GET | Открытие Win-дизайнера |
api/admin/reports |
GET | Список отчётов (админ) |
api/admin/reports |
POST | Создание отчёта (админ) |
api/admin/reports/{id} |
POST | Обновление отчёта (админ) |
api/admin/reports/{id} |
DELETE | Удаление отчёта (админ) |
api/admin/reports/{id}/copy |
POST | Копирование отчёта (админ) |
11. Экспорт в XLSX — настройки и типичные проблемы¶
Режимы XLSX-экспорта¶
FastReport поддерживает 4 режима экспорта в Excel, настраиваемые через ExportSettings отчёта (API: PUT /app/v1.1/api/reports/{id}/exportSettings):
| Режим | Поле DTO | Поведение |
|---|---|---|
| Wysiwyg | Wysiwyg: true |
Точное визуальное воспроизведение. FR воссоздаёт позиции элементов через merge cells. Дефолт |
| DataOnly | DataOnly: true |
Только данные без форматирования. Без merge cells. Подходит для дальнейшей обработки |
| Seamless | Seamless: true |
Без разрывов страниц, непрерывная таблица |
| PrintOptimized | PrintOptimized: true |
Оптимизация для печати (отступы, масштаб) |
Почему XLSX объединяет ячейки (merge cells)¶
Причина: режим Wysiwyg (по умолчанию). FastReport позиционирует каждый элемент шаблона абсолютно (X, Y, Width, Height). При экспорте в XLSX координаты конвертируются в ячейки сетки. Если элементы не выровнены по единой сетке — FR создаёт дополнительные колонки/строки и объединяет ячейки для сохранения визуального расположения.
Решения:
- DataOnly=true — убирает все merge cells. Подходит если нужны только данные
- Выравнивание элементов в шаблоне — в FR Designer включить snap-to-grid, выровнять все элементы по одной сетке колонок. Чем меньше уникальных X-координат — тем меньше merge cells
- Table-объект вместо свободных Band-элементов — Table в FR не создаёт лишних колонок
- SplitPages=false — если merge cells появляются на границах страниц
DTO ExportSettings¶
{
"xlsxExportSettings": {
"wysiwyg": true,
"pageBreaks": false,
"splitPages": false,
"dataOnly": false,
"seamless": false,
"printOptimized": false
}
}
Таблица БД: Reports.ExportSettings (NVARCHAR MAX, JSON). Миграция v2.178.