From 3e41399cb8cd6e99b5200298a2b1b8392e47ece3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=BE=D0=B7=D0=BB=D0=BE=D0=B2=20=D0=92=D0=B0=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B8=D0=BD=20=D0=90=D0=BB=D0=B5=D0=BA=D1=81?= =?UTF-8?q?=D0=B0=D0=BD=D0=B4=D1=80=D0=BE=D0=B2=D0=B8=D1=87?= Date: Wed, 13 Aug 2025 16:49:01 +0300 Subject: [PATCH 1/3] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D0=BB?= =?UTF-8?q?=20=D1=80=D0=B0=D1=81=D1=88=D0=B8=D1=80=D0=B5=D0=BD=D0=B8=D0=B5?= =?UTF-8?q?=20=D1=82=D0=B8=D0=BF=D0=BE=D0=B2=D0=BE=D0=B9=20=D0=BC=D0=B5?= =?UTF-8?q?=D1=82=D0=B0=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D0=B8=20=D0=BF=D0=BE?= =?UTF-8?q?=20=D1=83=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B8=D1=8F?= =?UTF-8?q?=20=D1=82=D0=B5=D1=85=D0=BD=D0=BE=D0=BB=D0=BE=D0=B3=D0=B8=D1=8F?= =?UTF-8?q?=D0=BC=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/technologies/README.md | 157 +++++++++++++++ src/technologies/base.yaml | 70 +++++++ src/technologies/datasets.yaml | 79 ++++++++ src/technologies/presentations.yaml | 180 ++++++++++++++++++ src/technologies/root.yaml | 4 + .../templates/systems_tech_list.md | 3 + .../templates/technologies_list.md | 3 + 7 files changed, 496 insertions(+) create mode 100644 src/technologies/README.md create mode 100644 src/technologies/base.yaml create mode 100644 src/technologies/datasets.yaml create mode 100644 src/technologies/presentations.yaml create mode 100644 src/technologies/root.yaml create mode 100644 src/technologies/templates/systems_tech_list.md create mode 100644 src/technologies/templates/technologies_list.md diff --git a/src/technologies/README.md b/src/technologies/README.md new file mode 100644 index 0000000..acf191f --- /dev/null +++ b/src/technologies/README.md @@ -0,0 +1,157 @@ +# Сущность "Technologies" для DocHub + +## Наименование +**Technologies** - сущность для описания и управления технологическим стеком в рамках технологического домена архитектуры (Technology Architecture domain по TOGAF). + +## Цель создания сущности +Сущность создана для: +- Переноса функциональности управления технологиями из DocHub IDE в FOSS версию DocHub +- Создания структурированного каталога технологий с группировкой по секциям +- Валидации корректности описания технологий в системах и компонентах +- Анализа использования технологий через алиасы с выявлением неописанных технологий +- Предоставления навигационных связей между технологиями и компонентами системы +- Автоматического формирования меню для доступа к аналитическим представлениям + +## История создания +В FOSS версии DocHub сущность "Technologies" не выделена и технологический радар является частью ядра. При этом в DocHub IDE сущность "Technologies" выделена и технологический радар является частью сущности. Данное решение реализует эту идею в FOSS версии DocHub для возможности управления технологиями. + +## Краткое описание функциональности +Сущность предоставляет следующие возможности: + +### 1. Управление каталогом технологий +- **Секции радара**: Группировка технологий по логическим категориям +- **Описание технологий**: Хранение метаданных (название, ссылка, секция, статус, алиасы) +- **Валидация данных**: Проверка обязательных полей и корректности ссылок + +### 2. Анализ использования технологий +- **Общий каталог**: Полный список всех описанных технологий с возможностью сортировки +- **Анализ по системам**: Определение, где и как используются конкретные технологии +- **Валидация корректности**: Выявление неописанных технологий и показ ошибок +- **Навигационные связи**: Переходы между технологиями и компонентами системы + +### 3. Представления и интерфейс +- **Табличные представления**: Структурированный вывод с сортировкой и фильтрацией +- **Автоматическое меню**: Формирование навигационного меню "Архитектура/Технологическая" +- **Детальный анализ**: Фильтрованные представления по конкретным технологиям +- **Обработка ошибок**: Индикация проблем с описанием технологий + +## Краткое описание структуры папок и файлов + +### Структура расширения: +``` +technologies/ +├── README.md # Данная документация +├── root.yaml # Точка входа - импорт всех компонентов +├── base.yaml # Базовая схема сущности и конфигурация +├── presentations.yaml # Определение представлений данных +├── datasets.yaml # Источники данных и запросы +└── templates/ # Шаблоны для отображения + ├── technologies_list.md # Шаблон общего списка технологий + └── systems_tech_list.md # Шаблон списка по системам +``` + +### Описание файлов: + +- **`base.yaml`**: Содержит схему данных, конфигурацию меню и основные настройки сущности +- **`presentations.yaml`**: Определяет различные способы отображения данных (таблицы, списки) +- **`datasets.yaml`**: Содержит JSONata-запросы для получения и обработки данных +- **`templates/`**: Markdown-шаблоны для формирования пользовательского интерфейса +- **`technologies.yaml`**: Файл манифеста с описанием технологий (создается в корне метамодели) + +## Как использовать + +### 0. Развертывание расширения +Для использования сущности Technologies необходимо: + +1. **Создать папку `ta`** в корне вашей метамодели +2. **Скопировать папку `technologies`** со всеми файлами в созданную папку `ta` +3. **Создать файл `ta/root.yaml`** со следующим содержимым: + ```yaml + imports: + - technologies/root.yaml + ``` + +### 1. Подключение расширения +После развертывания файлов подключите расширение к вашей метамодели. Добавьте в корневой файл метамодели: + +```yaml +imports: + - ta/root.yaml +``` + +### 2. Создание файла манифеста +Создайте файл `technologies.yaml` в корне вашей метамодели для описания технологий. Этот файл будет содержать секции и элементы технологий. + +### 3. Добавление новой технологии +В файле манифеста `technologies.yaml` добавьте технологию в секцию `technologies.items`: + +```yaml +technologies: + items: + my_tech: + title: "Название технологии" + link: "https://example.com" + section: "backend" # Должна соответствовать секции из sections + status: "adopt" # adopt, trial, assess, hold + aliases: ["alias1", "alias2"] +``` + +### 4. Создание новой секции +В файле манифеста `technologies.yaml` добавьте секцию в `technologies.sections`: + +```yaml +technologies: + sections: + backend: + title: "Backend технологии" +``` + +### 5. Использование в компонентах +В описании компонентов укажите используемые технологии через алиасы: + +```yaml +components: + my_component: + title: "Мой компонент" + technologies: ["alias1", "alias2"] +``` + +### 6. Доступ к данным +Сущность предоставляет следующие представления: +- `/entities/technologies/technologies_list` - общий список технологий +- `/entities/technologies/systems_tech_list` - анализ по системам +- Фильтрованный анализ: `/entities/technologies/systems_tech_table_list.filtered?sys_alias_id=alias1` + +### 7. Расширение функциональности +Для добавления новых представлений: +1. Добавьте dataset в `datasets.yaml` +2. Создайте presentation в `presentations.yaml` +3. При необходимости добавьте шаблон в папку `templates/` + +## Особенности реализации + +- **JSONata**: Для обработки данных используются JSONata-запросы с функциями $spread, $sift, $filter +- **Алиасы технологий**: Технологии могут иметь несколько названий для гибкости интеграции с компонентами +- **Валидация через алиасы**: Автоматическая проверка корректности ссылок между технологиями и компонентами +- **Автоматическое меню**: Формирование навигационного меню через JSONata-выражения +- **Обработка ошибок**: Индикация неописанных технологий с помощью эмодзи (✅/❌) и текстовых сообщений +- **Фильтрация данных**: Параметризованные представления для детального анализа конкретных технологий + +## Связи с другими сущностями + +Сущность Technologies интегрируется с: +- **Components**: Отслеживает использование технологий в системах и компонентах +- **Core DocHub**: Расширяет базовую функциональность технологического радара + +## Совместимость + +Данное решение является расширением стандартной модели DocHub и может быть использовано в любой организации, использующей DocHub. Оно не заменяет стандартную функциональность, а дополняет её дополнительными возможностями анализа и представления данных. + +## Разработчик + +**Valentin Kozlov** +Email: i_frog@mail.ru + +## Лицензия + +**MIT License** - разрешает свободное использование, модификацию и распространение программного обеспечения при условии сохранения текста лицензии и указания авторства. diff --git a/src/technologies/base.yaml b/src/technologies/base.yaml new file mode 100644 index 0000000..2c4d681 --- /dev/null +++ b/src/technologies/base.yaml @@ -0,0 +1,70 @@ +# Базовое описание сущности "Technologies". Нужно учитывать, что сам Техрадар является частью ядра DocHub и формально не содержится в этой сущности. В новой версии DocHub IDE техрадар вынесен в отдельный документ "tech-radar" +entities: + technologies: + title: Технологии + config: + root_menu: Архитектура/Технологическая # Корневое меню представления компонентов + schema: + type: object + properties: + sections: + title: Секции радара + type: object + patternProperties: + "^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9][a-zA-Z0-9_-]*)*$": + type: object + properties: + title: + title: Название секции + type: string + required: + - title + additionalProperties: false + items: + title: Технологии + type: object + patternProperties: + "^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9][a-zA-Z0-9_-]*)*$": + title: Описание технологии + type: object + properties: + title: + title: Название технологии + type: string + link: + title: URL ссылка на технологию + type: string + section: + title: Секция в которой расположена технология + type: string + status: + title: Статус в котором находится технология + type: string + aliases: + title: Альтернативные названия технологии + type: array + items: + type: string + required: + - title + - section + - status + additionalProperties: false + required: + - sections + - items + additionalProperties: true + menu: > + ( + $config := entities.technologies.config; + [ + { + "location": $config.root_menu& "/" & "1. Список используемых технологий", + "link": "entities/technologies/systems_tech_list" + }, + { + "location": $config.root_menu& "/" & "2. Общий список технологий", + "link": "entities/technologies/technologies_list" + } + ] + ) \ No newline at end of file diff --git a/src/technologies/datasets.yaml b/src/technologies/datasets.yaml new file mode 100644 index 0000000..e5760c5 --- /dev/null +++ b/src/technologies/datasets.yaml @@ -0,0 +1,79 @@ +datasets: + # Получаем общий список описанных в DocHub технологий + dataset.technologies.tech_list: + source: > + ( + $manifest := $; + $tech_items := $manifest.technologies.items; + $tech_sections := $manifest.technologies.sections; + $tech_items.$spread().( + $tech_id := $keys()[0]; + $tech := $.*; + { + "tech_id": $tech_id, + "tech_title": $tech.title, + "tech_link": $tech.link, + "tech_section": $lookup($tech_sections, $tech.section).title, + "tech_status": $tech.status, + "tech_aliases": $join($tech.aliases, ", "), + "tech_description": $tech.description ? $tech.description : "" + } + ) + ) + # Данный запрос формирует список всех технологий, используемых в системах и компонентах, с их описанием, + # статусом, секцией, алиасами и списком систем, где они применяются. Если технология не найдена в справочнике, + # выводится сообщение об ошибке. + dataset.technologies.systems_tech_list: + source: > + ( + $manifest := $; + $components := $manifest.components; + $tech_items := $manifest.technologies.items; + $tech_sections := $manifest.technologies.sections; + /*В системах и компонентах указаны алиасы*/ + $tech_aliases := $distinct($components.*.technologies); + $tech_aliases.$spread().( + $tech_alias_id := $; + /*Получаем из алиаса технологии идентификатор технологии*/ + $tech_id := $map($tech_alias_id, function($tech, $i, $a){ + $filter($tech_items.$spread(), function($v, $i, $a) {$tech in $v.*.aliases}).($keys()[0])} + ); + $tech := $lookup($tech_items, $tech_id); + $tech_found := $tech != null; + /*Получаем информацию к какой секции относится технология*/ + $tech_section := $tech_found ? $lookup($tech_sections, $tech.section).title : ""; + /*Находим все системы и компоненты где указан алиас технологий $tech_alias_id*/ + $systems_using_tech := $components.$sift(function($v, $k) { + $tech_alias_id in $v.technologies + }); + + /*В цикле перебираем все системы и компоненты где указан алиас технологий $tech_alias_id*/ + $systems_using_tech.$spread().( + $component_id := $keys()[0]; + $component := $.*; + /*Если это не система, то для читаемости показываем к какой системе относится выбранный компонент*/ + $component_name := $component.entity = "system" ? $component.title + : ( + $system_id := $split($component_id, ".", 2) ~> $join('.'); + $system := $lookup($components, $system_id); + $system.title & "." & $component.title + ); + { + /*Собираем массив данных, со всеми нужными нам полями*/ + "tech_id": $tech_id, + "tech_title": $tech_found ? $tech.title : "", + "tech_link": $tech_found ? $tech.link : "", + "tech_section": $tech_section, + "tech_status": $tech_found ? $tech.status : "", + "tech_aliases": $tech_found ? $join($tech.aliases, ", ") : "", + "component_id": $component_id, + "link_to_component": "/architect/components/" & $component_id, + "component": $component_name, + "component_entity": $component.entity, + "sys_alias_id": $tech_alias_id, + "link_to_sys_and_comp": "/entities/technologies/systems_tech_table_list.filtered?sys_alias_id=" & $tech_alias_id, + "error": $tech_found ? "" : "Технология не описана" + } + )^(tech_id); + ); + ) \ No newline at end of file diff --git a/src/technologies/presentations.yaml b/src/technologies/presentations.yaml new file mode 100644 index 0000000..bb8a076 --- /dev/null +++ b/src/technologies/presentations.yaml @@ -0,0 +1,180 @@ +# В FOSS версии DocHub сущность "Technologies" не выделена и технологический радар является частью ядра. +# При этом в DocHub IDE сущность "Technologies" выделена и технологический радар является частью сущности. +# Я взял эту идею и реализовал в FOSS версии DocHub для возможности управления технологиями. +entities: + technologies: + presentations: + # Получаем полный список технологий описанных в DocHub + technologies_table_list: + type: table + headers: + - value: tech_id + text: ID технологии + sortable: true + align: left + width: 15% + + - value: tech_title + text: Название + sortable: true + align: left + width: 20% + link: tech_link + + - value: tech_section + text: Секция + sortable: true + align: left + width: 15% + + - value: tech_status + text: Статус + sortable: true + align: left + width: 10% + + - value: tech_aliases + text: Алиасы + sortable: true + align: left + width: 25% + + - value: tech_description + text: Описание + sortable: false + align: left + width: 15% + source: dataset.technologies.tech_list + + # Выводим список технологий описанных в DocHub (работает в связке с technologies_table_list) + technologies_list: + type: markdown + title: Таблица технологий описанных в DocHub + source: templates/technologies_list.md + + # Получаем список используемых в системах и компонентах технологий + systems_tech_table_list: + type: table + title: Таблица систем и компонент по всем технологиям + headers: + - value: tech_id + text: ID технологии + sortable: true + align: left + width: 10% + link: tech_link + + - value: tech_title + text: Технологии + sortable: true + align: left + width: 10% + + - value: sys_and_comp + text: "Системы и компоненты" + align: center + width: 10% + link: link_to_sys_and_comp + + - value: tech_section + text: Секция + sortable: true + align: left + width: 15% + + - value: tech_status + text: Статус + sortable: true + align: left + width: 5% + + - value: tech_aliases + text: Алиасы + align: left + width: 20% + + - value: error + text: Ошибка + align: left + width: 15% + origin: dataset.technologies.systems_tech_list # Базовый источник данных + source: > + ( + /* Приводим сырые данные к виду для вывода в таблицу */ + $distinct($.{ + "tech_id": tech_id ? "✅ " & tech_id : "❌ " & sys_alias_id, + "tech_title": tech_title, + "tech_link": tech_link, + "tech_section": tech_section, + "tech_status": tech_status, + "tech_aliases": tech_aliases, + "sys_and_comp": "🔗", + "link_to_sys_and_comp": link_to_sys_and_comp, + "error": error + }); + ) + + # Выводим список используемых в системах и компонентах технологий в DocHub (работает в связке с systems_tech_table_list) + systems_tech_list: + type: markdown + title: Список используемых в системах и компонентах технологий + source: templates/systems_tech_list.md + + # Получаем список систем и компонент для конкретной технологии + systems_tech_table_list.filtered: + type: table + title: Таблица систем и компонент для конкретной технологии + params: + type: object + properties: + sys_alias_id: + type: string + required: + - sys_alias_id + headers: + - value: tech_id + text: ID технологии + sortable: true + align: left + width: 10% + link: tech_link + + - value: sys_alias_id + text: Алиас технологии + sortable: true + align: left + width: 10% + + - value: component + text: "Системы и компоненты" + sortable: true + align: left + width: 20% + link: link_to_component + + - value: component_entity + text: "Тип компонента" + sortable: true + align: left + width: 10% + + - value: error + text: Ошибка + align: left + width: 15% + origin: dataset.technologies.systems_tech_list # Базовый источник данных + source: > + ( + /* Приводим сырые данные к виду для вывода в таблицу */ + $.{ + "tech_id": tech_id ? "✅ " & tech_id : "❌ " & sys_alias_id, + "tech_title": tech_title, + "tech_link": tech_link, + "sys_alias_id": sys_alias_id, + "component": component, + "link_to_component": link_to_component, + "component_entity": component_entity, + "error": error + }[sys_alias_id=$params.sys_alias_id]; + ) + \ No newline at end of file diff --git a/src/technologies/root.yaml b/src/technologies/root.yaml new file mode 100644 index 0000000..92b6876 --- /dev/null +++ b/src/technologies/root.yaml @@ -0,0 +1,4 @@ +imports: + - base.yaml + - presentations.yaml + - datasets.yaml diff --git a/src/technologies/templates/systems_tech_list.md b/src/technologies/templates/systems_tech_list.md new file mode 100644 index 0000000..c4cac4b --- /dev/null +++ b/src/technologies/templates/systems_tech_list.md @@ -0,0 +1,3 @@ +# Список технологий используемых в системах Трайба B2B + +![Получаем список технологий](@entity/technologies/systems_tech_table_list) diff --git a/src/technologies/templates/technologies_list.md b/src/technologies/templates/technologies_list.md new file mode 100644 index 0000000..604d7cd --- /dev/null +++ b/src/technologies/templates/technologies_list.md @@ -0,0 +1,3 @@ +# Справочник технологий Трайба B2B + +![Общий список технологий](@entity/technologies/technologies_table_list) \ No newline at end of file From c089c5fc47dccf07f2305de77be2971c265d614c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=BE=D0=B7=D0=BB=D0=BE=D0=B2=20=D0=92=D0=B0=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B8=D0=BD=20=D0=90=D0=BB=D0=B5=D0=BA=D1=81?= =?UTF-8?q?=D0=B0=D0=BD=D0=B4=D1=80=D0=BE=D0=B2=D0=B8=D1=87?= Date: Wed, 13 Aug 2025 16:51:16 +0300 Subject: [PATCH 2/3] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D0=BB?= =?UTF-8?q?=20=D1=80=D0=B0=D1=81=D1=88=D0=B8=D1=80=D0=B5=D0=BD=D0=B8=D0=B5?= =?UTF-8?q?=20=D0=BF=D0=BE=20=D1=82=D0=B5=D1=85=D0=BD=D0=BE=D0=BB=D0=BE?= =?UTF-8?q?=D0=B3=D0=B8=D1=8F=D0=BC=20=D0=B2=20=D0=BC=D0=B5=D0=BD=D1=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 79eeadd..3374ea0 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ 14. [Entity Relationship диаграммы и диаграммы классов](src/DynamicEntityRelationshipDiagrams) 15. [Динамическое изменение группировки компонент в представлении контекста](src/DynamicChangeOfContextGrouping) 16. [Репозиторий чатбота корпоративного ИИ](src/aichatbot) +17. [Расширение для управления технологиями](src/technologies) ## Разворачивание From 479053cf7e2a4bd23e2a8a1cbab491c6034a43c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=BE=D0=B7=D0=BB=D0=BE=D0=B2=20=D0=92=D0=B0=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B8=D0=BD=20=D0=90=D0=BB=D0=B5=D0=BA=D1=81?= =?UTF-8?q?=D0=B0=D0=BD=D0=B4=D1=80=D0=BE=D0=B2=D0=B8=D1=87?= Date: Wed, 13 Aug 2025 16:54:56 +0300 Subject: [PATCH 3/3] =?UTF-8?q?=D0=A3=D0=B1=D1=80=D0=B0=D0=BB=20=D0=BB?= =?UTF-8?q?=D0=B8=D1=88=D0=BD=D1=8E=D1=8E=20=D0=B8=D0=BD=D1=84=D0=BE=D1=80?= =?UTF-8?q?=D0=BC=D0=B0=D1=86=D0=B8=D1=8E=20=D0=B8=D0=B7=20=D1=88=D0=B0?= =?UTF-8?q?=D0=B1=D0=BB=D0=BE=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/technologies/templates/systems_tech_list.md | 2 +- src/technologies/templates/technologies_list.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/technologies/templates/systems_tech_list.md b/src/technologies/templates/systems_tech_list.md index c4cac4b..c743aee 100644 --- a/src/technologies/templates/systems_tech_list.md +++ b/src/technologies/templates/systems_tech_list.md @@ -1,3 +1,3 @@ -# Список технологий используемых в системах Трайба B2B +# Список технологий используемых в системах ![Получаем список технологий](@entity/technologies/systems_tech_table_list) diff --git a/src/technologies/templates/technologies_list.md b/src/technologies/templates/technologies_list.md index 604d7cd..1424e3b 100644 --- a/src/technologies/templates/technologies_list.md +++ b/src/technologies/templates/technologies_list.md @@ -1,3 +1,3 @@ -# Справочник технологий Трайба B2B +# Справочник технологий ![Общий список технологий](@entity/technologies/technologies_table_list) \ No newline at end of file