Merge pull request #12 from ValentinKozlov/main

Пример структуры репозитория для управления архитектурой

Author: rpiontik

README.md

@@ -19,6 +19,8 @@
 6. [Встраивание виджетов в представления стандартных сущностей](src/widgets)
 7. [Управление процессом развертывания систем в кластерах](src/deployment_units_management)
 8. [Примеры запросов JSONata](src/jsonata_query_examples)
+9. [Пример структуры репозитория для управления архитектурой](src/repository_structure_example)
+
 
 ## Разворачивание
 

dochub.yaml

@@ -14,4 +14,6 @@ imports:
 # 7. Пример управления процессом развертывания систем в кластерах
 #  - src/deployment_units_management/dochub.yaml
 # 8. Примеры запросов JSONata
-  - src/jsonata_query_examples/dochub.yaml
+#  - src/jsonata_query_examples/dochub.yaml
+# 9. Пример структуры репозитория для управления архитектурой
+  - src/repository_structure_example/dochub.yaml

src/deployment_units_management/images/Модель технической архитектуры L1 в DocHub v0.7-Процесс.jpg

@@ -1,4 +1,5 @@
 imports:    
   - systems/_root.yaml
   - docs.yaml
+  - functions.yaml
 

src/jsonata_query_examples/_root.yaml

@@ -0,0 +1,28 @@
+functions:  
+  # Описание 
+  # Функция формирует строку ресурсов для вывода в карточке развертывания системы. На вход принимает 3 парметра:
+  # context - сюда мы передаем значения ресурсов
+  # mult - мулитипликатор, т.е. у каждой среды есть мультиплкатор на который мы увеличиваем ресурсы, если не нужно увеличивать, то передаем 1
+  # output_type - вид возвращаемой строк: short - короткий варинат без типов ресурсов, full - полный вариант
+  
+  # Примеры
+  # $eval($functions.get_resources,{"context": $, "mult": multiplier, "output_type": "short"})
+  # $eval($functions.get_resources,{"context": $, "mult": 1, "output_type": "full"})
+  get_resources: >
+    (
+      $context := $.context;
+      $mult := $.mult;
+      $output_type := $.output_type;
+      $output_type = "short"
+      ? "RAM: " & $context.ram * $mult & "Gb" & "\n"            
+        & "CPU: " & $context.cpu * $mult & "Core" & "\n"        
+        & ($context.storage_size > 0
+        ? "Storage: " & $context.storage_size * $mult & "Gb")
+      : "RAM: " & $context.ram * $mult & "Gb" & "\n"
+        & "CPU type: " & $context.cpu_type & "\n"
+        & "CPU: " & $context.cpu * $mult & "Core" & "\n"
+        & ($context.storage_size > 0 
+          ? "Storage type: " & $context.storage_type & "\n"
+          & "Storage: " & $context.storage_size * $mult & "Gb" : "")
+    )
+  

src/jsonata_query_examples/functions.yaml

@@ -286,4 +286,44 @@ components:
         ?  $append($account, $); 
     ));
 )
-```
+```
+## Как переиспользовать код
+
+В классическом понимании, функции в JSONata работают только внутри одного алгоритма, т.е. если вам нужно внутри одного алгоритма переиспользовать какой-то кусок кода, то вы можете выделить его в функцию. При этом нет такого понятия как объявить глобальную функцию и использовать её везде где нам нужно. Детально об использовании функций можно почитать в документации по JSONata в разделе ["Функциональное программирование"](http://docs.jsonata.org/programming).
+
+Что же делать если нам нужно переиспользовать один кусок кода для разных алгоритмов?
+Есть альтернативное решение - это объявить переиспользуемый кусок кода и импортировать его в общее хранилище данных DocHub. После этого вы сможете выполнять описанный кусок вашего кода через специальную функцию $eval(), при этом функция $eval(expr [, context]) в качестве второго параметра может принимать контекст, что по факту можно использовать как параметры функции.
+
+Так как  не специалист в JSONata, то моё объяснение может кому-то показаться колхозным, поэтому если у вас есть более правильное объяснение, то делайте MR.
+
+Давайте рассмотрим пример:
+1. Создадим yaml файл где у нас будут храниться куски кода, которые мы хотим переиспользовать в разных алгоритмах. Например, у нас этот файл хранится по следующему пути: `./functions.yaml`
+2. Объявим и опишем код
+```yaml
+functions:
+  get_resources: >
+    (
+      $context := $.context;
+      $mult := $.mult;
+      $output_type := $.output_type;
+      $output_type = "short"
+      ? "RAM: " & $context.ram * $mult & "Gb" & "\n"            
+        & "CPU: " & $context.cpu * $mult & "Core" & "\n"        
+        & ($context.storage_size > 0
+        ? "Storage: " & $context.storage_size * $mult & "Gb")
+      : "RAM: " & $context.ram * $mult & "Gb" & "\n"
+        & "CPU type: " & $context.cpu_type & "\n"
+        & "CPU: " & $context.cpu * $mult & "Core" & "\n"
+        & ($context.storage_size > 0 
+          ? "Storage type: " & $context.storage_type & "\n"
+          & "Storage: " & $context.storage_size * $mult & "Gb" : "")
+    )
+```
+3. Вызовем кусок нашего кода с разными параметрами в редакторе JSONata
+```yaml
+(
+    $functions := functions;
+    $eval($functions.get_resources,{"context": {"ram": 2, "cpu": 8, "storage_size": 5}, "mult": 4, "output_type": "short"});
+    $eval($functions.get_resources,{"context": {"ram": 2, "cpu_type": "standart", "cpu": 8, "storage_type": "standart", "storage_size": 5}, "mult": 1, "output_type": "full"});
+)
+  ```

src/jsonata_query_examples/jsonata_query_example.md

@@ -0,0 +1,60 @@
+# Пример структуры репозитория для описания архитектуры
+
+**Цель примера:** Снизить порог вхождения в DocHub за счет внедрения типовых шаблонов структуры репозитория и меню DocHub для управления корпоративной архитектурой.
+
+# Суть примера
+Существует множество различных подходов к описанию архитектуры компании. В нашей компании была выбрана методология TOGAF. При этом мы не пытаемся внедрить классическую методологию TOGAF, мы используем комбинированный подход, выбирая только те инструменты, которые закрывают наиболее критичные риски компании.
+
+Согласно методологии TOGAF архитектура предприятия делится на 4 домена:
+
+1. Бизнес-архитектура - описание бизнес-процессов компании
+2. Информационная архитектура - описание архитектуры данных
+3. Прикладная архитектура - описание архитектуры программных продуктов (системы, сервисы, приложения и т.д.)
+4. Технологическая архитектура - описание архитектуры инфраструктуры
+
+![TOGAF](./images/arch_approach.png)
+
+Вся структура примера разработана под выбранную методологию с учетом нашего видения. В общем случае в данном репозитории мы ведем прикладную архитектур ровня ПА-L1, но если у системы нет своего репозитория, либо у архитектора несколько систем, то он может управлять в этом репозитории и уровнем ПА-L2.
+
+## Файловая структура примера
+* **application_arch** - в этой папке хранятся все данные, связанные с прикладной архитектурой, кроме контекстов. Контексты мы вынесли в отдельную папку artefacts. Детально про artefacts можно почитать ниже.
+    * **systems** - в этой папке хранятся данные по системам. Каждую систему мы описываем в своём файле и имя файла всегда соответствует имени системы. Идентификатор системы в общем случае представляет из себя доменное имя в виде: `<имя компании>.<имя бизнес-юнита>.<имя системы>`. Если вдруг у системы нет своего репозитория, то в этом файле мы также описываем runtime компоненты этой системы, что позволяет хранить всю информацию по системе в одном месте.
+* **artefacts** - в этой папке мы храним все артефакты по системам, например контексты мы храним в такой структуре: `./artefacts/<имя бизнес-юнита>/<имя контекста>`. Также здесь мы храним различные схемы по системам.
+* **business_arch** - в этой папке хранятся все данные, связанные с бизнес-архитектурой. На текущий момент мы не ведем в DocHub бизнес-архитектуру. Возможно, суда будем класть архитектурные скетчи, когда Рома закончит встраивать в DocHub https://excalidraw.com/
+* **dictionaries** - вспомогательная папка для хранения справочной информации. Например, при заполнении системы встал вопрос по её статусе, и чтобы не дублировать каждый раз всю информацию по статусу мы сделали справочник статусов и в системе используем только идентификатор, а если нам нужна полная информация, то получаем её при помощи функции $lookup внутри запроса.
+* **enterprise_arch** - это папка корпоративных архитекторов, сюда мы помещаем всю информацию, которая связана с развитием архитектуры в компании.
+    * **adr** - в этой папке мы храним реестр архитектурных решений
+    * **processes** - в этой папке мы храним документацию по различным архитектурным процессам
+    * **tools** - в этой папке мы храним документацию по инструментам архитектуры
+        * **dochub** - в этой папке мы храним документацию по DocHub
+    * **welcome** - в этой папке мы храним документацию, которая выводится при открытии DocHub (welcome page) 
+* **images** - картинки для настоящей документации
+* **information_arch** - в этой папке хранятся все данные, связанные с информационной архитектурой. На текущий момент мы в начале пути и сделали пока только прототип по управлению бизнес-сущностями на логическом уровне.
+* **settings** - здесь мы храним всякие настройки
+    * **datasets** - здесь у нас общие запросы
+    * **jsonata** - здесь у нас общие функции. Пример использования можно посмотреть [здесь](https://github.com/rpiontik/DocHubExamples/blob/main/src/jsonata_query_examples/jsonata_query_example.md).
+    * **validators** - здесь мы описываем валидаторы, которые нужно выводить в общее меню проблем. Пример использования можно посмотреть [здесь](https://github.com/rpiontik/DocHubExamples/tree/main/src/validator_example) 
+* **standards** - это одна из ключевых папок, где мы храним архитектурные принципы и стандарты, которые обязательны к выполнению всеми командами
+    * **arch_principles** - здесь у нас описаны архитектурные принципы и принципы информационной безопасности
+    * **it_platforms** - здесь мы храним архитектурные стандарты по платформам, а также принятые нотации по кодированию
+    * **patterns** - здесь мы описываем различные паттерны, которые могут использовать наши команды. В примере есть пример реализации одного из таких паттернов.
+* **tech_arch** - в этой папке хранятся все данные, связанные с технологической архитектурой. Сейчас мы пока реализовали процесс управления развертыванием систем. Пример использования можно посмотреть [здесь](https://github.com/rpiontik/DocHubExamples/tree/main/src/deployment_units_management)
+* **_root.yaml** - корневой файл для импорта
+* **dochub.yaml** - корневой файл DocHub
+* **README.md** - текущая документация
+
+## Правила импорта yaml файлов
+Импорт всех файлов делается только через `_root.yaml`. Это означает что при создании любой папки всегда нужно сначала добавлять `_root.yaml`, а уже внутри подключать файлы.
+Такой подход позволяет очень быстро переструктурировать папки репозитория, а также избегать множественного импорта при подключении репозитория как подмодуль.
+
+## Пример целевого меню
+Мы не дождались пока Рома сделает кастомный вариант меню, поэтому в web версии переделали его по себя. Ниже наша версия такого меню:
+
+![Menu](./images/menu_example.jpg)
+
+Найти реализованный пример на базе entity можно здесь:
+![Menu](./images/menu_dochub.jpg)
+
+
+## Использование
+Скачайте себе пример и "потыкайте" каждый пункт меню, думаю найдете что-нибудь интересное :-).

src/repository_structure_example/README.md

@@ -0,0 +1,10 @@
+imports:
+  - business_arch/_root.yaml
+  - information_arch/_root.yaml
+  - application_arch/_root.yaml
+  - tech_arch/_root.yaml
+  - artefacts/_root.yaml
+  - dictionaries/_root.yaml
+  - enterprise_arch/_root.yaml
+  - settings/_root.yaml  
+  - standards/_root.yaml

src/repository_structure_example/_root.yaml

@@ -0,0 +1,3 @@
+imports:
+  - systems/_root.yaml
+  - docs.yaml

src/repository_structure_example/application_arch/_root.yaml

@@ -0,0 +1 @@
+# Прикладная архитектура находится в разработке