Public release from ruodoo-project: 19.0 - 2026-07-26 21:17:35 UTC

mklab_base_indicators_report/TECHNICAL.md

@@ -0,0 +1,133 @@
+# Техническая документация: mklab_base_indicators_report
+
+**name:** `mklab_base_indicators_report`  
+**version:** 19.0.2025.11.24  
+**author:** MK.Lab
+**depends:** `base`, `mklab_base_indicators_extended`  
+**Внешние Python-пакеты:** `networkx`, `matplotlib`
+
+---
+
+## Архитектура
+
+Модуль не вводит новых моделей данных. Состоит из трёх компонентов: расширения существующей модели `hg.index`, HTTP-контроллера и визарда.
+
+```
+mklab_base_indicators_report
+├── hg.index (расширение)        — метод generate_graph_image()
+├── NodeMetricsReportController  — HTTP-контроллер /node_metrics/report/<id>
+└── node_report_wizard           — визард выбора показателя и запуска отчёта
+```
+
+---
+
+## Компоненты
+
+### `hg.index` — расширение
+
+**Файл:** `models/hg_index.py`
+
+Добавляет метод `generate_graph_image()` к существующей модели `hg.index`.
+
+#### Метод `generate_graph_image()`
+
+Строит направленный граф зависимостей для текущего показателя и возвращает PNG-изображение в виде base64-строки. Последовательность шагов:
+
+**1. Сбор данных**
+
+- Находит все `hg.link` где `source_id` равен вершине текущего показателя (`self.node_id`)
+- Находит все `hg.index` с тем же `internal_code_id` что у текущего показателя
+
+**2. Построение графа (`networkx.DiGraph`)**
+
+Для каждой связи `hg.link`:
+
+- Добавляет вершину-источник (`source_id.name`) с меткой — суммой `current_value` всех показателей по коду
+- Для каждой вершины-приёмника (`target_ids`): добавляет вершину с меткой — суммой `current_value` показателей по коду, отфильтрованных по данному узлу
+- Добавляет направленное ребро от источника к приёмнику
+
+**3. Рендеринг**
+
+| Параметр | Значение |
+|---|---|
+| Расположение вершин | `spring_layout`, `seed=1` (фиксированный, воспроизводимый) |
+| Размер холста | 10 × 8 дюймов |
+| Размер вершины | 3000 |
+| Цвет вершины | `lightblue` |
+| Метка вершины | `"название\nZZZZ.ZZ"` (название + числовое значение с двумя знаками) |
+
+**4. Вывод**
+
+Сохраняет изображение в `BytesIO` в формате PNG, кодирует в base64 и возвращает строку.
+
+---
+
+### `NodeMetricsReportController` — HTTP-контроллер
+
+**Файл:** `report/index_report.py`
+
+| Параметр | Значение |
+|---|---|
+| Маршрут | `/node_metrics/report/<int:index_id>` |
+| Тип | `http` |
+| Авторизация | `user` (требует входа в систему) |
+
+Получает `index_id`, загружает запись `hg.index`, вызывает `generate_graph_image()` и возвращает HTML-страницу с тегом `<img>` где изображение встроено как base64.
+
+При отсутствии записи с указанным `index_id` возвращает строку `"Record not found"`.
+
+---
+
+### `node_report_wizard` — Визард
+
+**Файл:** `wizard/report_wizard.py`  
+**Тип:** `models.TransientModel`
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `index_id` | Many2one → `hg.index` | Выбранный показатель для построения графа |
+
+#### Метод `action_generate_report()`
+
+Читает `web.base.url` из системных параметров, формирует URL вида:
+```
+{web.base.url}/node_metrics/report/{index_id}
+```
+Возвращает `ir.actions.act_url` с `target='new'` — отчёт открывается в новой вкладке браузера.
+
+---
+
+## Представления и меню
+
+**Файл:** `wizard/report_wizard.xml`
+
+Форма визарда с полем `index_id` и кнопками «Показать отчёт» / «Отмена». Пункт меню добавляется в раздел отчётов модуля `mklab_base_indicators_extended`:
+
+```
+Слои показателей → Отчёты → Отчет показателей по узлам
+```
+
+---
+
+## Права доступа
+
+**Файл:** `security/ir.model.access.csv`
+
+| Модель | Группа | Права |
+|---|---|---|
+| `node_report_wizard` | `group_indicators_admin` | CRUD |
+
+---
+
+## Тесты
+
+**Файл:** `tests/test_report_wizard.py`
+
+| Класс | Метод | Что проверяет |
+|---|---|---|
+| `TestReportWizard` | `test_wizard_create` | Создание визарда с `index_id` |
+| `TestReportWizard` | `test_action_generate_report_returns_url_action` | Тип `ir.actions.act_url`, наличие `index_id` в URL, `target='new'` |
+| `TestReportWizard` | `test_action_url_contains_base_url` | URL содержит значение `web.base.url` |
+| `TestHgIndexGraphImage` | `test_generate_graph_image_returns_base64` | Метод возвращает base64-строку |
+
+---