Skip to content

Commit 3ee2ff4

Browse files
rpiontikrpiontik
authored
Merge pull request #3 from biakaveron/main
Добавил пример с entities
2 parents d47b97b + ed4392c commit 3ee2ff4

17 files changed

Lines changed: 535 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
1. [Пример создания пользовательской метамодели C4 Model](src/C4Model)
1515
2. [Простой пример валидации сущностей в DocHub с выводом информации в меню](src/validator_example)
1616
3. [Пример управления бизнес-сущностями](src/business_entity_management)
17+
4. [Пример сущности для бизнес-процессов](src/sequences_entity_example)
1718

1819

1920
## Разворачивание

‎dochub.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
imports:
22
# Пример создания метамодели для описания в нотации C4 Model
33
- src/C4Model/dochub.yaml
4+
# - src/validator_example/dochub.yaml
5+
# - src/business_entity_management/dochub.yaml
6+
# - src/sequences_entity_example/dochub.yaml

‎src/sequences_entity_example/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Пример сущности для бизнес-процессов
2+
3+
**Цель примера:** Показать возможности связки Dochub+plantuml для генерации диаграмм последовательности
4+
(например, описание бизнес-процессов) в контексте имеющегося описания архитектуры предприятия.
5+
6+
Пример является доработанной версией сущности interactions из [официальной документации](https://dochub.info/docs/dochub.entities), опубликованной на одном из воркшопов по Dochub.
7+
Добавлена автоматическая линковка компонентов в качестве участников, а также поддержка ссылок в шагах. Это могут быть ссылки на другие диаграммы, swagger-контракты и тд.
8+
9+
## Суть примера
10+
11+
Показать, как с помощью сущностей можно "затащить" в dochub бизнес-документацию и связать ее с архитектурой компании. Как простой пример последовательности была выбрана сказка "Колобок".
12+
13+
В результате аналитики и технические писатели получают возможность описать с помощью текста (а значит - и положить в git) бизнес-процессы:
14+
15+
```yaml
16+
sequences:
17+
story.pigs:
18+
title: Сказка "колобок"
19+
location: Документы/Колобок/Диаграмма
20+
icon: swap_horiz
21+
groups:
22+
- title: Рождение колобка
23+
triggers:
24+
- Жили-были дед и баба
25+
steps:
26+
- from: grandpa
27+
to: grandma
28+
value: Испеки, старуха, колобок!
29+
- from: grandma
30+
to: grandma
31+
value: Поскрести по сусекам
32+
- from: grandma
33+
to: kolobok
34+
value: Испекла баба колобок
35+
contract: kolobok.receipt
36+
results:
37+
- Колобок полежал—полежал, да вдруг и покатился
38+
...
39+
```
40+
41+
Dochub сам превратит найденные упоминания компонентов из полей from/to в ссылки на их профили и подтянет названия, а поле contract позволит обеспечить перелинковку с другими документами, в том числе внешними.
42+
43+
## Файловая структура примера
44+
* components - данные архитектуры для рендеринга
45+
* heroes.yaml - компоненты-участники сказки
46+
* root.yaml - корневой манифест данных архитектуры
47+
* docs - документы в формате markdown для демонстрации возможностей линковки через contract
48+
* entities - метамодель;
49+
* templates - шаблоны, используемые для рендеринга диаграмм
50+
* tree.puml - Plantuml-шаблон для вывода всех диаграмм в виде дерева
51+
* blank.puml - Plantuml-шаблон для просмотра конкретной диаграммы
52+
* manifest.yaml - манифест пользовательских сущностей (там определена сущность sequences)
53+
* sequences.yaml - пример сущности
54+
* root.yaml - корневой манифест метамодели
55+
* dochub.yaml - корневой манифест примера
56+
57+
## Валидация
58+
59+
Dochub имеет встроенные механизмы контроля корректности заполнения описания. Чтобы его активировать, для создаваемых сущностей мы описываем правила валидации:
60+
61+
"Из коробки" это позволяет проверять соответствие сущностей при работе в IDE через плагин Dochub. Чтобы валидация выполнялась также в приложении Dochub, а ошибки выводились в блоке "Проблемы", необходимо добавить вызов валидатора:
62+
63+
```yaml
64+
rules:
65+
validators:
66+
sequences:
67+
title: Валидатор последовательностей
68+
source: >
69+
(
70+
$validator := $jsonschema($.entities.sequences.schema.patternProperties.*); /* Передаем схему в части отдельного объекта, а не всех sequences */
71+
([([
72+
$.sequences.$spread().( /* Сканируем все последовательности */
73+
$ID := $keys()[0];
74+
{
75+
"id": $ID, /* Запоминаем идентификатор компонента */
76+
"isvalid": $validator($.*) /* Валидируем компонент по схеме */
77+
}
78+
)
79+
][isvalid != true]).isvalid.{ /* Генерируем отклонения по выявленным нарушениям */
80+
"uid": $.params.*[0] & "-sequence-" & %.id, /* Уникальный идентификатор выявленной ошибки */
81+
"location": "/entities/sequences/blank?id=" & %.id, /* Ссылка на расположение объекта ошибки */
82+
"correction": "Исправьте ошибку",
83+
"description": $.message
84+
}])
85+
86+
)
87+
```
88+
89+
## Задания для практики
90+
91+
* Реализуйте документ со списком диаграмм и задействованных в них компонентов
92+
* Добавьте поддержку [активации/деактивации](https://plantuml.com/ru/sequence-diagram#5cc0040514e70f7b) участников через дополнительный атрибут сущности

‎src/sequences_entity_example/components/heroes.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
components:
2+
grandma:
3+
entity: actor
4+
title: Баба
5+
grandpa:
6+
entity: actor
7+
title: Дед
8+
kolobok:
9+
entity: entity # Для демонстрации автоопределения entity
10+
title: Колобок
11+
animals.hair:
12+
entity: actor
13+
title: Заяц
14+
animals.wolf:
15+
entity: actor
16+
title: Волк
17+
animals.bear:
18+
entity: actor
19+
title: Медведь
20+
animals.fox:
21+
entity: actor
22+
title: Лиса

‎src/sequences_entity_example/components/root.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
imports:
2+
- heroes.yaml

‎src/sequences_entity_example/dochub.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
imports:
2+
- components/root.yaml
3+
- entities/root.yaml
4+
- docs/root.yaml

‎src/sequences_entity_example/docs/receipt.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Рецепт колобка
2+
3+
Взяла старуха крылышко, по коробу поскребла, по сусеку помела, и набралось муки пригоршни с две. Замесила на сметане, изжарила в масле и положила на окошечко постудить.

‎src/sequences_entity_example/docs/root.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
docs:
2+
kolobok.receipt:
3+
type: markdown
4+
location: Колобок/Рецепт
5+
source: receipt.md
6+
kolobok.song4hair:
7+
type: markdown
8+
location: Колобок/Песня для зайца
9+
source: song4hair.md
10+
kolobok.song4wolf:
11+
type: markdown
12+
location: Колобок/Песня для волка
13+
source: song4wolf.md
14+
kolobok.song4bear:
15+
type: markdown
16+
location: Колобок/Песня для медведя
17+
source: song4bear.md
18+
kolobok.song4fox:
19+
type: markdown
20+
location: Колобок/Песня для лисы
21+
source: song4fox.md

‎src/sequences_entity_example/docs/song4bear.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Песня колобка для медведя
2+
3+
Я Колобок, Колобок!
4+
Я по коробу скребен,
5+
По сусеку метен,
6+
На сметане мешон,
7+
Да в масле пряжон,
8+
На окошке стужон;
9+
Я от дедушки ушел,
10+
Я от бабушки ушел,
11+
Я от зайца ушел,
12+
Я от волка ушел,
13+
И от тебя, медведь, не хитро уйти!

‎src/sequences_entity_example/docs/song4fox.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Песня колобка для лисы
2+
3+
Я Колобок, Колобок!
4+
Я по коробу скребен,
5+
По сусеку метен,
6+
На сметане мешон,
7+
Да в масле пряжон,
8+
На окошке стужон;
9+
Я от дедушки ушел,
10+
Я от бабушки ушел,
11+
Я от зайца ушел,
12+
Я от волка ушел,
13+
И от медведя ушел,
14+
А от тебя, лиса, и подавно уйду!

0 commit comments

Comments
 (0)