Отчёты Excel

Возможности

• Каталог из 36 отчётов в четырёх группах: «Результаты расчёта» (8), «Исходные данные» (17), «Система теплоснабжения» (1), «Сводные ведомости» (10). Поиск — по названию, группе, листам и имени файла десктопа.
• Отчёты десктопа gid6 (меню «Excel», файлы excel2/*.lst): шаблон, шапка и порядок колонок как в десктопе. Под названием отчёта показан источник в gid6, ниже — листы книги.
• Для отчётов десктопа выбираются фрагмент и расчёт: «Последний расчёт фрагмента» или один из 50 последних расчётов этого фрагмента с результатами. Значок калькулятора в списке — отчёту нужны результаты расчёта.
• «Сводные ведомости» веба: участки, задвижки, реестр задвижек и арматуры, байпасы, насосные агрегаты, потребители, технические условия, «Свод ТУ баланс» (с необязательным годом), сезоны и источники теплопотерь.
• «Не перенесены из десктопа (5)» — какие запросы gid6 не перенесены и почему.

Как это работает

Отчёт десктопа. Сервер берёт шаблон .xlsx (переведён из .xls gid6 один к одному) и для каждого листа выполняет запрос из sql/reports, подставляя фрагмент и расчёт. Строки пишутся под шапку шаблона с колонки A, как CCxema::Excel2List десктопа. В ячейки шапки листов результатов подставляются режим, дата и время расчёта и температура наружного воздуха.

• Фрагмент отбирается по правилу десктопа: начальный узел участка в этом фрагменте, оба конца — в одном фрагменте. Поэтому отчёт «Участки» по фрагменту 74 копии Алматы содержит 1818 строк, а сводная ведомость «Участки теплопроводов» того же фрагмента — 4018 (она отбирает участок по его собственному фрагменту).
• Расчёт по умолчанию — последний расчёт фрагмента (наибольший номер). Если у фрагмента нет расчёта, листы результатов остаются с одной шапкой; под выбором расчёта появляется «У фрагмента нет расчёта: листы результатов будут только с шапкой.»
• На лист выводится не больше 100 000 строк; все запросы отчёта идут в одной транзакции только для чтения с пределом 60 с на запрос.
• Имя файла — «‹название отчёта› ф‹фрагмент›.xlsx», например «Участки теплопроводов ф74.xlsx».
• «Система теплоснабжения» берёт справочник организаций целиком, без отбора по фрагменту (лист «Вх.Организации_владельцы»). Имена владельцев-людей на этом листе не маскируются.

Сводная ведомость. Книга строится сервером по своим колонкам (как шаблоны G_UT, G_ZD десктопа), с листом «Примечание». В этом окне ведомость всегда выгружается по всей сети — выбора фрагмента у неё нет; по выбранным на карте фрагментам те же ведомости выгружает меню «Выгрузка» в шапке. По всей сети в ведомость попадает до 200 000 строк, лишнее отмечается на листе «Примечание». Имя файла — report_‹код›.xlsx (с годом — report_tu-balance_2025.xlsx). В ведомости технических условий заполнены «Дата», «Организация», «Источник» и «Район» — из реестра ТУ.

Как идёт выгрузка. Файл строится фоновой задачей: «Задача в очереди…», «Формирование файла…». Если фоновые задачи недоступны или воркер не взял задачу, окно само переходит на прямой запрос: «Формирование файла на сервере (синхронно)…». После скачивания под кнопкой — «Скачан ‹имя файла›».

Что нужно для работы

• Право «Выгрузки и отчёты»: без него инструмента «Отчёты Excel» в списке инструментов нет. Сервер это право при скачивании отчётов не проверяет — ограничение только в интерфейсе.
• Для отчётов десктопа — фрагмент; для листов результатов — выполненный расчёт этого фрагмента.
• Для фоновой выгрузки — Redis и воркер Celery; без них выгрузка идёт прямым запросом.

Шаги

1. Откройте «Инструменты» и наберите в поиске «Отчёты Excel» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

3. Выберите отчёт — справа появятся фрагмент, расчёт (по умолчанию последний расчёт фрагмента) и, для некоторых отчётов, год. «Скачать Excel» формирует книгу с шаблоном и шапкой как в gid6. Если у фрагмента нет расчёта, листы результатов будут только с шапкой.

   

Примеры

Копия Алматы, фрагмент 74, отчёт «Участки теплопроводов» из группы «Результаты расчёта». Книга из четырёх листов: «Вх.Участки» — 1818 строк, «Гидравлика», «ТеплоГидравлика», «Отключенные» — только шапка: у фрагмента 74 на этой копии нет ни одного расчёта.

Копия Алматы, фрагмент 74, отчёт «Система теплоснабжения». Листы «Вх.СистемаТеплоснабжения» — 1 строка, «Вх.РасчетныеСхемы» — 18, «Вх.Организации_владельцы» — 16 579: это весь справочник организаций города, а не только фрагмента.

Если не получается

• «Не удалось загрузить каталог отчётов» — API недоступен или устарел.
• «Нет отчёта ‹код›» — веб и API разных версий: в каталоге окна есть отчёт, которого нет на сервере.
• «Расчёт N не относится к фрагменту M» — выбран расчёт другого фрагмента; выберите расчёт заново после смены фрагмента.
• «Отчёт не уложился в таймаут запроса» — запрос листа шёл дольше 60 с; повторите позже, когда сервер свободнее.
• «Не удалось сформировать ведомость» — ошибка на сервере при построении сводной ведомости; подробности — в журнале API.
• Нет инструмента «Отчёты Excel» — у роли нет права «Выгрузки и отчёты».

Для администратора

• Шаблоны — report_templates/excel2/*.xlsx, запросы — sql/reports/*.sql (параметры только $1 — фрагмент, $2 — расчёт).
• Фоновые файлы: REDIS_ADDR, REDIS_DB, REDIS_PASSWORD, FILE_JOBS_QUEUE, FILE_JOBS_TTL, хранилище FILE_STORAGE (FILE_STORAGE_DIR, FILE_S3_ENDPOINT, FILE_S3_BUCKET).
• Право «Выгрузки и отчёты» (export) скрывает инструмент только в вебе: /api/reports/catalog/*/excel, /api/reports/excel/* и фоновые задачи файлов сервер отдаёт любому вошедшему.
• Excel-файлы не проходят маскирование персональных данных (в том числе лист организаций «Системы теплоснабжения» и ведомость ТУ): оно работает только для ответов JSON.

Для разработчика

• API: GET /api/reports/catalog (отчёты десктопа и сводные ведомости, список not_ported), GET /api/reports/catalog/{report_id}/excel?fragment_id=&calculation_id= (заголовки X-Report-Rows по листам, X-Report-Calculation), GET /api/reports/excel/{doc_type}?year=&fragments=, GET /api/reports/excel-types; фоновые задачи POST /api/v1/file-jobs (catalog_report, report_excel), GET /api/v1/file-jobs/{task_id}, GET /api/v1/file-jobs/{task_id}/download.
• Код API: routers/reports.py, database/excel_reports.py (каталог REPORTS, MAX_ROWS, STATEMENT_TIMEOUT_MS, NOT_PORTED), reports_generator.py (EXCEL_SHEETS, MAX_NETWORK_REPORT_ROWS), database/file_jobs.py.
• Веб: components/ExcelReportsDialog.vue (ключ excelReports, requiresPerm: 'export'), utils/reportsCatalog.ts, services/api/reports.ts (getReportsCatalog, downloadCatalogReport, downloadExcelReport), services/api/http.ts (runFileJob).
• Тесты: веб — tests/utils/reportsCatalog.spec.ts, tests/services/fileJobs.spec.ts; API — tests/test_excel_reports.py, tests/test_reports_router.py, tests/test_excel_fast_writer.py, tests/test_file_jobs.py; e2e — «окно «Отчёты Excel»: отчёт «Участки теплопроводов» скачивается» в e2e/functions/equipment-registries.spec.ts.