technologies

Сущность "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 со следующим содержимым:

   imports:
     - technologies/root.yaml

1. Подключение расширения

После развертывания файлов подключите расширение к вашей метамодели. Добавьте в корневой файл метамодели:

imports:
  - ta/root.yaml

2. Создание файла манифеста

Создайте файл technologies.yaml в корне вашей метамодели для описания технологий. Этот файл будет содержать секции и элементы технологий.

3. Добавление новой технологии

В файле манифеста technologies.yaml добавьте технологию в секцию technologies.items:

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:

technologies:
  sections:
    backend:
      title: "Backend технологии"

5. Использование в компонентах

В описании компонентов укажите используемые технологии через алиасы:

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 - разрешает свободное использование, модификацию и распространение программного обеспечения при условии сохранения текста лицензии и указания авторства.