Merge pull request #407 from RabotaRu/v3.4.0

v3.4.0
RabotaRu · Oct 17, 2023 · 70e9e1b · 70e9e1b
2 parents 6bc311b + ee2390b
commit 70e9e1b
Show file tree

Hide file tree

Showing 29 changed files with 363 additions and 247 deletions.
diff --git a/distrib/idea/IDEAPlugin-3.6.0.zip → distrib/idea/IDEAPlugin-3.6.3.zip b/distrib/idea/IDEAPlugin-3.6.0.zip → distrib/idea/IDEAPlugin-3.6.3.zip
diff --git a/distrib/vscode/dochub-0.0.27.vsix b/distrib/vscode/dochub-0.0.27.vsix
diff --git a/public/documentation/arch/components/examples/root.yaml b/public/documentation/arch/components/examples/root.yaml
@@ -4,6 +4,7 @@
 components:
   dochub.examples:
     title: Примеры
+    entity: component
 imports:
   - order.yaml
   - payment.yaml

diff --git a/public/documentation/arch/root.yaml b/public/documentation/arch/root.yaml
@@ -10,3 +10,4 @@ imports:  # Подключение манифестов
 components:
   dochub: # Корневой компонент (домен)
     title: DocHub
+    entity: component
diff --git a/public/documentation/docs/manual/docs/docs.md b/public/documentation/docs/manual/docs/docs.md
@@ -1,5 +1,7 @@
 # Документы (docs)
 
+## Доступные документы
+
 Документ - многофункциональная сущность. Поддерживаются форматы:
 * **[SmartAnts](/docs/dochub.smartants)** - продвинутый инструмент презентации архитектуры в виде диаграмм с широкими возможностями.
 * **[PlantUML](/docs/dochub.plantuml)** - позволяет создавать диаграммы из обычного текстового языка. [Подробнее](https://plantuml.com/ru/).
@@ -10,14 +12,19 @@
 * **[Table](/docs/dochub.tables)** - документ для представления данных в табличной форме;
 * **[Network](/docs/dochub.network)** - сетевые диаграммы.
 
-Перечень документов можно самостоятельно расширять за счет создания [плагинов](/docs/dochub.plugins.intro). 
+Перечень доступных документов можно самостоятельно расширять за счет создания [плагинов](/docs/dochub.plugins.intro). 
+
+## Использование
 
 Описание документов в манифесте:
 ```yaml
 docs:                                 # Документы
     dochub.manual:                    # Идентификатор документа
         icon: lightbulb_outline       # Иконка, которы будет отображаться в дереве навигации
-        location: DocHub/Руководство  # Размещение документа в дереве навигации (если требуется отражать)
+        location: DocHub/Руководство  # Размещение документа в меню (если требуется отражать)
+                                      # Если в начале строки указывается "/" документ будет размещен от корня,
+                                      # в противном случае, он разместится в определенном конфигурацией пункте меню.
+                                      # Подробнее ниже.
         description: Пользовательское руководство DocHub  # Краткое описание сути документа (опиционально)
         type: markdown                # Тип документа (OpenAPI / markdown / PlantUML / Table)
         subjects:                     # К какому архитектурному объекту документ имеет отношение
@@ -27,14 +34,33 @@ docs:                                 # Документы
         origin: ...                   # Исходные данные (см. таблицы)
 ```
 
+## Разметка документов на объекты
+
 Документы могут иметь связи с архитектурными объектами. Для этого в секции "subjects" необходимо перечислить их
 идентификаторы. Если объект связан с документом, в его карточке он будет отображаться. Например, для объекта
 **dochub.front** карточка выглядит так:
 
+
 ![Карточка компонента](@component/dochub.front)
 
 В разделе "Документы" можно найти ссылки на связанные с объектом документы.
 
+## Конфигурирование
+
+Поведение документов можно конфигурировать через их сущность. Для этого необходимо переопределить 
+параметры по умолчанию.
+
+```yaml
+...
+entities:                             # Обращаемся к сущностям  
+  docs:                               # К документам
+    config:                           # Здесь хранится конфигурация по умолчанию
+      root_menu: Документы            # Корневой элемент меню для документов по умолчанию
+                                      # Значение может определять структуру через "/". В конце символ "/" не допускается.
+                                      # Например: Аналитика/Документация
+...
+```
+
 Для лучшего понимания возможностей документов разберем отдельно каждый тип:
 
 [Далее](/docs/dochub.plantuml)

diff --git a/public/documentation/docs/manual/docs/mermaid.md b/public/documentation/docs/manual/docs/mermaid.md
@@ -2,7 +2,7 @@
 
 Представляет собой исходные код на языке [Mermaid](https://mermaid-js.github.io/mermaid/#/).
 
-```Mermaid
+```
 C4Context
 title System Context diagram for Internet Banking System
 

diff --git a/public/documentation/docs/manual/entities/entities.md b/public/documentation/docs/manual/entities/entities.md
@@ -115,9 +115,6 @@ entities:
         # Сообщаем, что перечисленные поля обязательны
         required:
           - title
-          - triggers
-          - results
-          - steps
 ```
 
 Теперь DocHub знает как должна быть описана структура в секции "interactions" и может подсказывать при вводе кода 
@@ -164,7 +161,7 @@ entities:
           # Источник данных для представления
           source: >       # Источник данных для рендера шаблона. Возвращает объект "interactions" по идентификатору переданному в параметрах.
               (
-                  $lookup(interactions, $params.id)
+                  $lookup(interactions, $params.id) ~> | steps | {"from": $lookup($$.components, from).title, "to": $lookup($$.components, to).title}|
               )
       ...
 ```
@@ -663,14 +660,14 @@ interactions:
     results:
       - Переход в репозиторий
     steps:
-      - from: Хабр
-        to: Клиент
+      - from: habr
+        to: dochub.customer
         value: Анализ новых статей
-      - from: Клиент
-        to: Хабр
+      - from: dochub.customer
+        to: habr
         value: Чтение статьи о DocHub
-      - from: Клиент
-        to: Репозиторий
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Переход в репозиторий
   ...
 ```
@@ -687,18 +684,18 @@ interactions:
     results:
       - Потенциальный клиент (лид)
     steps:
-      - from: Клиент
-        to: Статьи
+      - from: dochub.customer
+        to: habr.articles
         value: Получение информации о DocHub
-        sub-interactions: dochub.customer.promotion.article # Здесь ссылка на взаимодействие пользователя со статьями на Хабр
-      - from: Клиент
-        to: Репозиторий
+        sub-interactions: dochub.customer.promotion.article # Здесь ссылка на взаимодействие пользователя со статьями
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Изучение инструкции
-      - from: Клиент
-        to: Репозиторий
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Развертывание
-      - from: Клиент
-        to: DocHub
+      - from: dochub.customer
+        to: dochub
         value: Первый опыт
   ...
 ```

diff --git a/public/documentation/docs/manual/plugins/introduction.md b/public/documentation/docs/manual/plugins/introduction.md
@@ -228,7 +228,8 @@ docs:
 
 Содержимое файла "examples/example.html":
 
-```html
+```
+
 <H1>Привет!</H1>
 <P>Это простейший пример HTML-документа, который выводится с использованием плагина DocHub.</P>
 ```
@@ -241,13 +242,13 @@ docs:
 
 Для встраивания объектов DocHub в представления используйте специальный VUE компонент "dochub-object":
 
-```html
+```
 <dochub-object src="@document/dochub.example.swgr" />
 ```
 
 Параметры для встраиваемого объекта передаются как GET параметры URL в поле "src". Например:
 
-```html
+```
 <dochub-object src="@entity/interactions/blank?id=dochub.user.research" />
 ```
 

diff --git a/public/documentation/entities/interactions/entity.yaml b/public/documentation/entities/interactions/entity.yaml
@@ -84,7 +84,7 @@ entities: # Сущности расширенной матемодели
                   - id
               source: >                   # Источник данных для рендера шаблона. Возвращает объект "interactions" по идентификатору переданному в параметрах.
                   (
-                      $lookup(interactions, $params.id)
+                      $lookup(interactions, $params.id) ~> | steps | {"from": $lookup($$.components, from).title, "to": $lookup($$.components, to).title}|
                   )
             export:                       # Экспорт взаимодействия в BPMN диаграмму
               type: upload                # Специальный тип документа, который выгружает результат генерации документа
@@ -213,9 +213,6 @@ entities: # Сущности расширенной матемодели
                                 minLength: 5
                     required:
                         - title
-                        - triggers
-                        - results
-                        - steps
         objects:                    # Декларирование объектов сущности
           interaction:              # Объектом сущности является взаимодействие - "interaction"
             route: "/"              # Путь к массиву объектов в Data Lake относительно пути /interactions
@@ -249,11 +246,11 @@ interactions:
     triggers:
       - Просмотр архитектуры
     steps:
-      - from: User
-        to: DocHub
+      - from: dochub.user
+        to: dochub
         value: Вход на портал
-      - from: DocHub
-        to: User
+      - from: dochub
+        to: dochub.user
         value: Представление архитектурных артефактов
     results:
       - Информация о существующей архитектуре
@@ -262,17 +259,17 @@ interactions:
     triggers:
       - Просмотр архитектуры
     steps:
-      - from: User
-        to: DocHub
+      - from: dochub.user
+        to: dochub
         value: Выбор раздела Проблемы
-      - from: DocHub
-        to: User
+      - from: dochub
+        to: dochub.user
         value: Генерация дерева со статусами
-      - from: User
-        to: DocHub
+      - from: dochub.user
+        to: dochub
         value: Выбор отклонения
-      - from: DocHub
-        to: User
+      - from: dochub
+        to: dochub.user
         value: Карточка отклонения
     results:
       - Информация об отклонениях
@@ -281,11 +278,11 @@ interactions:
     triggers:
       - Просмотр документов
     steps:
-      - from: User
-        to: DocHub
+      - from: dochub.user
+        to: dochub
         value: Выбор раздела Документы
-      - from: DocHub
-        to: User
+      - from: dochub
+        to: dochub.user
         value: Представление
     results:
       - Актуальная информация из документов
@@ -302,14 +299,14 @@ interactions:
     results:
       - Переход в репозиторий
     steps:
-      - from: Хабр
-        to: Клиент
+      - from: habr
+        to: dochub.customer
         value: Анализ новых статей
-      - from: Клиент
-        to: Хабр
+      - from: dochub.customer
+        to: habr
         value: Чтение статьи о DocHub
-      - from: Клиент
-        to: Репозиторий
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Переход в репозиторий
 
   dochub.customer.deployment:
@@ -319,17 +316,27 @@ interactions:
     results:
       - Потенциальный клиент (лид)
     steps:
-      - from: Клиент
-        to: Статьи
+      - from: dochub.customer
+        to: habr.articles
         value: Получение информации о DocHub
         sub-interactions: dochub.customer.promotion.article # Здесь ссылка на взаимодействие пользователя со статьями
-      - from: Клиент
-        to: Репозиторий
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Изучение инструкции
-      - from: Клиент
-        to: Репозиторий
+      - from: dochub.customer
+        to: dochub.gitlab.repository
         value: Развертывание
-      - from: Клиент
-        to: DocHub
+      - from: dochub.customer
+        to: dochub
         value: Первый опыт
-
+
+components:
+  dochub.customer:
+    title: Клиент
+    entity: actor
+  habr:
+    title: Хабр
+    entity: component
+  habr.articles:
+    title: Статьи
+    entity: component
diff --git a/public/metamodel/dochub/entities/aspects/base.yaml b/public/metamodel/dochub/entities/aspects/base.yaml
@@ -2,6 +2,9 @@
 entities:
   aspects:
     title: Аспекты
+    # Параметры использования аспектов
+    config:
+      root_menu: Архитектура/Аспекты    # Размещение аспектов в меню
     description: >
       Архитектурные аспекты.
     schema:
@@ -44,20 +47,21 @@ entities:
     menu: >
       (
         $aspects := aspects;
+        $config := entities.aspects.config;
         $makeLocation := function($id) {(
             $arrleft := function($arr ,$count) {
                 $map($arr, function($v, $i) {
                   $i <= $count ? $v
                 })
             };
             $domains := $split($id, ".");
-            "Архитектура/Аспекты/" & $join($map($domains, function($domain, $index) {(
+            $config.root_menu & "/" & $join($map($domains, function($domain, $index) {(
                 $lookup($aspects, $join($arrleft($domains, $index), ".")).title
             )}), "/");
         )};
         [$append([{
             "link": "/entities/aspects/tree", /* Ссылка на форму представления аспектов в виде дерева */
-            "location": "Архитектура/Аспекты" /* Расположение в меню */
+            "location": $config.root_menu     /* Расположение в меню */
           }],
           [$aspects.$spread().{
               "link": "/entities/aspects/blank?dh-aspect-id=" & $keys()[0],     /* Формируем ссылку на карточку */

diff --git a/public/metamodel/dochub/entities/components/base.yaml b/public/metamodel/dochub/entities/components/base.yaml
@@ -2,6 +2,8 @@
 entities:
   components:
     title: Компоненты
+    config:
+      root_menu: Архитектура  # Корневое меню представления компонентов
     description: >
       Архитектурные компоненты.
     schema:
@@ -89,7 +91,7 @@ entities:
         [
           {
             "link": "/entities/components/tree",
-            "location": "Архитектура"
+            "location": entities.components.config.root_menu
           }
         ]
       )