@seafteam/seaf-archtool-core-plugin-suite 2026.31.0 → 2026.32.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/documentation/docs/manual/backend/api.yaml +49 -0
- package/documentation/docs/manual/docs/editable_table/step_3_headers/template.md +33 -0
- package/documentation/docs/manual/docs/gigachat/agents/aigena/menu.yaml +1 -1
- package/documentation/docs/manual/docs/gigachat/agents/root.yaml +0 -1
- package/documentation/docs/manual/docs/gigachat/agents/template.md +0 -5
- package/documentation/docs/manual/docs/gigachat/template.md +1 -1
- package/documentation/docs/manual/docs/seaf2drawio/examples/diff.yaml +0 -96
- package/documentation/docs/manual/docs/seaf2drawio/seaf2drawio.md +125 -7
- package/documentation/docs/manual/plugins/introduction.md +53 -8
- package/documentation/docs/manual/root-cluster-import.md +117 -0
- package/package.json +1 -1
- package/plugin.html +4 -2039
- package/documentation/docs/manual/docs/gigachat/agents/react/gigachat.yaml +0 -59
- package/documentation/docs/manual/docs/gigachat/agents/react/menu.yaml +0 -5
- package/documentation/docs/manual/docs/gigachat/agents/react/root.yaml +0 -3
- package/documentation/docs/manual/docs/gigachat/agents/react/template.md +0 -138
|
@@ -66,6 +66,55 @@ tags:
|
|
|
66
66
|
- name: HealthInfo
|
|
67
67
|
description: "API для получения расширенной служебной информации о состоянии портала. ⚠️ Данный метод доступен только при работе SEAF.ArchTool в кластерном режиме."
|
|
68
68
|
paths:
|
|
69
|
+
/seaf-core/api/core/storage/jsonata/{query}:
|
|
70
|
+
get:
|
|
71
|
+
tags:
|
|
72
|
+
- DataLake
|
|
73
|
+
summary: Выполняет произвольный запрос JSONata к данным архитектуры
|
|
74
|
+
description: >
|
|
75
|
+
Устаревший GET-контракт (до ERA-2872). Сохранён для обратной совместимости.
|
|
76
|
+
Предпочтительный способ — POST /seaf-core/api/core/storage/jsonata.
|
|
77
|
+
parameters:
|
|
78
|
+
- in: path
|
|
79
|
+
name: query
|
|
80
|
+
description: JSONata запрос в скобках "([запрос])" или идентификатор DataSet без скобок
|
|
81
|
+
required: true
|
|
82
|
+
schema:
|
|
83
|
+
$ref: '#/components/schemas/JSONataQuery'
|
|
84
|
+
example: >
|
|
85
|
+
({"id": $params.id, "limit": $params.limit, "type": $self.type, "template": $self.template})
|
|
86
|
+
- in: query
|
|
87
|
+
name: params
|
|
88
|
+
description: >
|
|
89
|
+
JSON структура с параметрами передающаяся в запрос.
|
|
90
|
+
Будет доступна в переменной $params.
|
|
91
|
+
required: false
|
|
92
|
+
schema:
|
|
93
|
+
type: string
|
|
94
|
+
example: '{"id":"sber.rdwsoft","limit":8}'
|
|
95
|
+
- in: query
|
|
96
|
+
name: subject
|
|
97
|
+
description: >
|
|
98
|
+
JSON структура с профилем объекта, который выполняет запрос.
|
|
99
|
+
Будет доступна в переменной $self.
|
|
100
|
+
required: false
|
|
101
|
+
schema:
|
|
102
|
+
type: string
|
|
103
|
+
example: '{"type":"markdown","template":"template.md"}'
|
|
104
|
+
- in: query
|
|
105
|
+
name: envelope
|
|
106
|
+
description: Если "true", ответ упаковывается в envelope-формат
|
|
107
|
+
required: false
|
|
108
|
+
schema:
|
|
109
|
+
type: string
|
|
110
|
+
enum: ["true", "false"]
|
|
111
|
+
responses:
|
|
112
|
+
"200":
|
|
113
|
+
description: "Результат выполнения запроса"
|
|
114
|
+
content:
|
|
115
|
+
application/json:
|
|
116
|
+
schema:
|
|
117
|
+
$ref: '#/components/schemas/JSONataResult'
|
|
69
118
|
/seaf-core/api/core/storage/jsonata:
|
|
70
119
|
post:
|
|
71
120
|
tags:
|
|
@@ -26,6 +26,37 @@
|
|
|
26
26
|
- false
|
|
27
27
|
- Прочие приводимые значения
|
|
28
28
|
|
|
29
|
+
# Markdown в текстовых ячейках
|
|
30
|
+
|
|
31
|
+
Текстовую колонку можно показывать как Markdown, не меняя сохраняемое значение.
|
|
32
|
+
Возможность включается только для заголовка с `type: text`:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
headers:
|
|
36
|
+
- value: evidence
|
|
37
|
+
text: Обоснование
|
|
38
|
+
type: text
|
|
39
|
+
render: markdown
|
|
40
|
+
editable: true
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Без `render: markdown` Markdown-синтаксис отображается как обычный текст. Поддерживаются
|
|
44
|
+
обычное форматирование и ссылки, таблицы, изображения, а также fenced-блоки `mermaid`
|
|
45
|
+
и `plantuml`. Произвольный HTML не исполняется.
|
|
46
|
+
|
|
47
|
+
Markdown хранится в ячейке как обычная строка и сохраняется тем же способом, что и
|
|
48
|
+
обычный `text`; проверенный save payload сохраняет и соседнее поле строки. Относительные пути изображений вычисляются от файла презентации
|
|
49
|
+
editable-table; они не зависят от `save.path` конкретной колонки. Mermaid строится в
|
|
50
|
+
браузере, а PlantUML требует настроенный сервер или обработчик IDEA-плагина.
|
|
51
|
+
|
|
52
|
+
Режим исходного текста открывается кнопкой редактирования, двойным кликом, `Enter` или
|
|
53
|
+
`F2` на выбранной ячейке. `Escape`, `Ctrl/Cmd+Enter` или переход фокуса завершают
|
|
54
|
+
редактирование и возвращают предпросмотр.
|
|
55
|
+
|
|
56
|
+
SVG, в которых подписи находятся внутри `foreignObject` (например, экспортированные из
|
|
57
|
+
draw.io или Excalidraw), браузер может показать без текста: такие изображения выводятся
|
|
58
|
+
в `<img>`.
|
|
59
|
+
|
|
29
60
|
# link
|
|
30
61
|
|
|
31
62
|
## Описание
|
|
@@ -161,6 +192,8 @@ headers:
|
|
|
161
192
|
# type - Тип вывода ячеек для указанной колонки
|
|
162
193
|
# Дефолтное значение: text
|
|
163
194
|
# Допустимые значения: text / select / multiple-select / checkbox / link / fn
|
|
195
|
+
# render - дополнительный режим отображения текстовой ячейки
|
|
196
|
+
# Допустимое значение: markdown (только вместе с type: text)
|
|
164
197
|
|
|
165
198
|
- value: name
|
|
166
199
|
text: Имя
|
|
@@ -51,11 +51,6 @@ archtool.plugins.gigachat.example:
|
|
|
51
51
|
Взаимодействует c API GigaChat.
|
|
52
52
|
Позволяет описать промпт и добавить в него результат выполнения JSONata-выражения в качестве контекста.
|
|
53
53
|
|
|
54
|
-
## [`react`](/entities/docs/blank?dh-doc-id=archtool.plugins.gigachat.agents.react.menu)
|
|
55
|
-
|
|
56
|
-
Взаимодействует c API GigaChat.
|
|
57
|
-
Позволяет использовать тулы (function-calling инструменты) для предоставления ответа.
|
|
58
|
-
|
|
59
54
|
## [`aigena`](/entities/docs/blank?dh-doc-id=archtool.plugins.gigachat.agents.aigena.menu)
|
|
60
55
|
|
|
61
56
|
Взаимодействует с API AiGenA.
|
|
@@ -1,78 +1,5 @@
|
|
|
1
1
|
flix.office.hq_page: []
|
|
2
2
|
flix.dc.01_page:
|
|
3
|
-
- id: flix.network.dc.ngfw.cntxt2
|
|
4
|
-
diff:
|
|
5
|
-
geometry_attr_key:
|
|
6
|
-
x:
|
|
7
|
-
new: "275"
|
|
8
|
-
old: "130"
|
|
9
|
-
y:
|
|
10
|
-
new: "170"
|
|
11
|
-
old: "90"
|
|
12
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.01_flix.lan.dc.dmz.vpn
|
|
13
|
-
diff:
|
|
14
|
-
geometry_attr_key:
|
|
15
|
-
pointsArray:
|
|
16
|
-
- - "820"
|
|
17
|
-
- "450"
|
|
18
|
-
- - "820"
|
|
19
|
-
- "1110"
|
|
20
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.02_flix.lan.dc.dmz.prod
|
|
21
|
-
diff:
|
|
22
|
-
geometry_attr_key:
|
|
23
|
-
pointsArray:
|
|
24
|
-
- - "790"
|
|
25
|
-
- "380"
|
|
26
|
-
- - "790"
|
|
27
|
-
- "810"
|
|
28
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.02_flix.lan.dc.dmz.vpn
|
|
29
|
-
diff:
|
|
30
|
-
geometry_attr_key:
|
|
31
|
-
pointsArray:
|
|
32
|
-
- - "810"
|
|
33
|
-
- "380"
|
|
34
|
-
- - "810"
|
|
35
|
-
- "1110"
|
|
36
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.03_flix.lan.dc.dmz.vpn
|
|
37
|
-
diff:
|
|
38
|
-
geometry_attr_key:
|
|
39
|
-
pointsArray:
|
|
40
|
-
- - "755"
|
|
41
|
-
- "1120"
|
|
42
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.04_flix.lan.dc.dmz.prod
|
|
43
|
-
diff:
|
|
44
|
-
geometry_attr_key:
|
|
45
|
-
pointsArray:
|
|
46
|
-
- - "880"
|
|
47
|
-
- "820"
|
|
48
|
-
- - "880"
|
|
49
|
-
- "820"
|
|
50
|
-
- id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.04_flix.lan.dc.dmz.vpn
|
|
51
|
-
diff:
|
|
52
|
-
geometry_attr_key:
|
|
53
|
-
pointsArray:
|
|
54
|
-
- - "755"
|
|
55
|
-
- "850"
|
|
56
|
-
- - "850"
|
|
57
|
-
- "850"
|
|
58
|
-
- id: link_id:Sber Cloud
|
|
59
|
-
DC:generic:flix.network.dc.ngfw.cntxt1_flix.lan.dc.dmz.prod
|
|
60
|
-
diff:
|
|
61
|
-
geometry_attr_key:
|
|
62
|
-
pointsArray:
|
|
63
|
-
- - "985"
|
|
64
|
-
- "670"
|
|
65
|
-
- - "935"
|
|
66
|
-
- "670"
|
|
67
|
-
- id: link_id:Sber Cloud
|
|
68
|
-
DC:generic:flix.network.dc.ngfw.cntxt2_flix.lan.dc.int.prod
|
|
69
|
-
diff:
|
|
70
|
-
geometry_attr_key:
|
|
71
|
-
pointsArray:
|
|
72
|
-
- - "1630"
|
|
73
|
-
- "257"
|
|
74
|
-
- - "1630"
|
|
75
|
-
- "257"
|
|
76
3
|
- id: link_id:Sber Cloud DC:generic:flix.kb.fpsu_1_flix.lan.dc.dmz.vpn
|
|
77
4
|
diff:
|
|
78
5
|
geometry_attr_key:
|
|
@@ -83,35 +10,12 @@ flix.dc.01_page:
|
|
|
83
10
|
- "420"
|
|
84
11
|
- - "830"
|
|
85
12
|
- "1100"
|
|
86
|
-
- id: link_id:Sber Cloud DC:generic:flix.kb.4_flix.lan.dc.int.prod
|
|
87
|
-
diff:
|
|
88
|
-
label:
|
|
89
|
-
new: s
|
|
90
|
-
old: FW
|
|
91
|
-
geometry_attr_key:
|
|
92
|
-
pointsArray:
|
|
93
|
-
- - "1235"
|
|
94
|
-
- "960"
|
|
95
|
-
- - "1510"
|
|
96
|
-
- "960"
|
|
97
|
-
- - "1510"
|
|
98
|
-
- "230"
|
|
99
|
-
- - "1580"
|
|
100
|
-
- "230"
|
|
101
13
|
- id: link_id:Sber Cloud DC:generic:flix.kb.5_flix.lan.dc.int.security
|
|
102
14
|
diff:
|
|
103
15
|
geometry_attr_key:
|
|
104
16
|
pointsArray:
|
|
105
17
|
- - "1795"
|
|
106
18
|
- "510"
|
|
107
|
-
- id: link_id:Sber Cloud DC:generic:flix.cluster.vdi_flix.lan.dc.dmz.vdi
|
|
108
|
-
diff:
|
|
109
|
-
geometry_attr_key:
|
|
110
|
-
pointsArray:
|
|
111
|
-
- - "1040"
|
|
112
|
-
- "1204"
|
|
113
|
-
- - "1040"
|
|
114
|
-
- "510"
|
|
115
19
|
- id: link_id:Sber Cloud
|
|
116
20
|
DC:generic:flix.backup.cyberbackup_flix.lan.dc.int.it.services
|
|
117
21
|
diff:
|
|
@@ -25,18 +25,89 @@
|
|
|
25
25
|
- **dataset** Обязательный, содержит описание объектов архитектуры.
|
|
26
26
|
- **templates** Необязательный, содержит пользовательские шаблоны для объектов или переопределения встроенных шаблонов.
|
|
27
27
|
- **diff** Необязательный, содержит трансформации для отображаемой диаграммы.
|
|
28
|
+
- **diff_path** Необязательный, содержит путь к файлу `.yaml` или `.json` с трансформациями. При наличии имеет приоритет над `diff`.
|
|
28
29
|
- **layout_settings** Необязательный, содержит настройки алгоритмов компоновки и отрисовки связей. Может задаваться на уровне YAML-профиля документа или возвращаться из `source`; настройки из `source` переопределяют одноимённые поля профиля.
|
|
29
30
|
|
|
30
31
|
Параметры iframe Draw.io для seaf2drawio настраиваются так же, как у документа `drawio`:
|
|
31
32
|
переменные `VUE_APP_DOCHUB_PLUGIN_DRAWIO_SERVER_URI` / `VUE_APP_DOCHUB_PLUGIN_DRAWIO_URL_PARAMS`
|
|
32
33
|
и поле профиля `drawio_url_params` (см. [документацию drawio](/docs/archtool.plugins.drawio)).
|
|
33
34
|
|
|
35
|
+
### Автоматическая компоновка технической архитектуры
|
|
36
|
+
|
|
37
|
+
На общей и детальных схемах `Internet` и `Транспортная сеть` отображаются как самостоятельные контейнеры. Провайдеры и явно отнесённые к ним объекты остаются внутри соответствующего контейнера. На страницах офиса и ЦОД внутренние зоны располагаются слева направо: `INET-EDGE` (под ним `EXT-WAN-EDGE`), `DMZ` (под ним `INT-WAN-EDGE`), `INT-NET`, затем `INT-SECURITY-NET`.
|
|
38
|
+
|
|
39
|
+
Размеры зон и групп рассчитываются по фактическому содержимому. При добавлении сетей, устройств или сервисов контейнеры расширяются, а соседние зоны сдвигаются с безопасным интервалом. Поэтому итоговый размер и координаты схемы могут отличаться от исходного шаблона: генератор отдаёт приоритет отсутствию наложений и читаемости подписей. Сохранённые пользователем geometry diff имеют приоритет над автоматическим stacking; для остальных объектов применяется адаптивная компоновка.
|
|
40
|
+
|
|
41
|
+
На детальных страницах сервисы и пользовательские устройства без явно заданного `segment`, чьи `network_connection` относятся только к `INTERNET` или `TRANSPORT-WAN`, выводятся слева от `Internet` в визуальном контейнере **«Внешние сервисы»**. Внутренние группы при этом сохраняют штатные слои сервисов КБ и технических сервисов. Это только визуальная компоновка: связи и принадлежность объектов в архитектурной модели не изменяются. Явно заданный `segment`, смешанные внутренние и внешние подключения либо неразрешённая ссылка имеют приоритет и не переносятся в этот контейнер автоматически.
|
|
42
|
+
|
|
43
|
+
Компоненты сети с `is_part_of` отображаются в составе единого `network_service`; для размещения такого агрегата требуется разрешимый `segment` самого сервиса, его участников или связанной через `network_connection` сети.
|
|
44
|
+
|
|
45
|
+
### Перестроение схемы с ИИ (бета)
|
|
46
|
+
|
|
47
|
+
Для документа можно явно включить экспериментальный диалог перестроения схемы по текстовому запросу. По умолчанию функция выключена. При включении пользователь видит кнопку **Перестроить с ИИ** и предупреждение о передаче запроса и выбранного контекста в настроенный в ArchTool GigaChat через общий `chatService`.
|
|
48
|
+
|
|
49
|
+
```yaml
|
|
50
|
+
docs:
|
|
51
|
+
something.seaf2drawio_ai_r41:
|
|
52
|
+
type: seaf2drawio
|
|
53
|
+
ai_assistant:
|
|
54
|
+
enabled: true
|
|
55
|
+
max_attempts: 3
|
|
56
|
+
context_mode: compact
|
|
57
|
+
response_mode: selection
|
|
58
|
+
scenario:
|
|
59
|
+
type: gigachat
|
|
60
|
+
temperature: 0.1
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Параметры `ai_assistant`:
|
|
64
|
+
|
|
65
|
+
- **enabled** включает функцию только для данного документа. При отсутствии `enabled: true` интерфейс и генерация схемы работают как раньше; флаг берётся из профиля документа.
|
|
66
|
+
- **max_attempts** задаёт ограничение числа обращений к LLM, включая первичную попытку. Продуктовый предел — три попытки.
|
|
67
|
+
- **context_mode: compact** передаёт модели ограниченный срез исходного датасета, выбранный по запросу, вместо полного содержимого хранилища.
|
|
68
|
+
- **response_mode: selection** требует от модели только существующие OID, после чего связный датасет детерминированно собирается из исходных объектов.
|
|
69
|
+
- **scenario** задаёт сценарий LLM через общий `chatService` ArchTool; `system_prompt` внутри сценария позволяет заменить системную инструкцию, а `history: false` отключает сохранение истории сессии.
|
|
70
|
+
|
|
71
|
+
Параметры, возвращённые `source`, дополняют настройки профиля документа; флаг `enabled` принимается только из профиля.
|
|
72
|
+
|
|
73
|
+
Если `context_mode` и `response_mode` не заданы, используются безопасные значения `compact` и `selection`. Другие значения не подменяются значениями по умолчанию: диалог показывает ошибку конфигурации и не отправляет запрос в LLM. В `compact` передаётся ограниченный срез датасета; в `selection` модель возвращает только существующие OID, а итоговый датасет собирается Core. Для одного запроса действует предел 200 объектов вместе с зависимостями.
|
|
74
|
+
|
|
75
|
+
Перед отправкой запроса диалог сообщает пользователю, что текст запроса и отобранный контекст архитектурных данных передаются в настроенный GigaChat через общий `chatService`. В запрос нельзя включать секреты, персональные или иные данные, не разрешённые к обработке выбранным сервисом.
|
|
76
|
+
|
|
77
|
+
Ответ модели проходит синтаксическую, структурную, ссылочную и Draw.io-проверку. При ошибке модель получает ограниченную диагностику и может исправить ответ в пределах `max_attempts`. Успешный результат показывается только как предпросмотр. Кнопка **Использовать в этой сессии** не записывает файлы и не изменяет исходный архитектурный датасет. После применения в текущей сессии используется компактный AI-датасет, поэтому экспорт и сохранение заблокированы до успешного обновления исходных данных.
|
|
78
|
+
|
|
79
|
+
В AI-предпросмотре технологии КБ без специализированного шаблона, например IdM, IdP, PAM, DLP, политики Kubernetes и Registry, рисуются общим значком и могут визуально отличаться от обычной R41-схемы; обычный рендер R41 не меняется.
|
|
80
|
+
|
|
81
|
+
#### Поддерживаемые формулировки
|
|
82
|
+
|
|
83
|
+
Запрос можно писать обычным языком. Распознаются команды `покажи`, `нарисуй`, `отрисуй`, `отобрази`, `выведи`, `визуализируй`, `сформируй` и `оставь`, а также вежливые формы: `можешь показать`, `покажи, пожалуйста`, `давай отобразим`, `хочу увидеть` и `мне нужны`.
|
|
84
|
+
|
|
85
|
+
Нормализатор понимает категории, которые рисуют текущие шаблоны SEAF2DrawIO: регионы и зоны доступности, ЦОД и офисы, сетевые сегменты, сети, сетевые и пользовательские устройства, вычислительные сервисы, кластеры виртуализации, Kubernetes, резервное копирование, мониторинг, средства КБ и logical links. Для часто используемых категорий поддерживаются варианты `monitoring`/`мониторинг`/`маниторинг`, `Kubernetes`/`K8s`/`кубернетес`, `КБ`/`УКБ`/`ЭКБ`/`ИБ`/`кибербезопасность`, `backup`/`бекап`/`бэкап`/`резервное копирование`. Конкретный объект можно указать точным `title` или OID, например `ELK`, `Zabbix` или `jupiter.monitoring.elk`.
|
|
86
|
+
|
|
87
|
+
Примеры:
|
|
88
|
+
|
|
89
|
+
| Запрос | Результат |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `Покажи мониторинг` | Все существующие сервисы мониторинга и зависимости их размещения |
|
|
92
|
+
| `Нарисуй ELK и Zabbix` | Только названные сервисы и существующие связи между ними |
|
|
93
|
+
| `Покажи мониторинг и все связи` | Все сервисы мониторинга, все смежные logical links и их конечные объекты |
|
|
94
|
+
| `Покажи исходящие связи ELK` | ELK, его исходящие logical links с учётом `direction` и все конечные объекты этих связей |
|
|
95
|
+
| `Покажи ELK и Zabbix без связей` | Названные сервисы без logical links |
|
|
96
|
+
| `Покажи monitoring, K8s и средства ИБ` | Все объекты трёх категорий и необходимые зависимости размещения |
|
|
97
|
+
| `Покажи внешние подключения` | WAN/INTERNET/INET-EDGE/EXT-WAN-EDGE/TRANSPORT-WAN, подключённые сетевые устройства и сети |
|
|
98
|
+
|
|
99
|
+
Если пользователь перечислил только объекты, Core добавляет существующие logical links между выбранными объектами. Формы `все связи`, `со связями`, `входящие связи` и `исходящие связи` расширяют выборку смежными связями и вторыми концами. Форма `без связей` полностью исключает logical links. Связь с `topology: star` или `topology: chain` сохраняется как единая сущность вместе со всеми её конечными объектами.
|
|
100
|
+
|
|
101
|
+
Однозначно распознанные категории и явно названные объекты добавляются детерминированно в режиме `compact` + `selection`: результат не зависит от того, перечислила ли модель каждый обязательный OID. Служебные объекты, которые сами не рисуются, используются только как зависимости. Каждый новый запрос строится от исходного датасета документа и выполняется в новой AI-сессии; применённый ранее предпросмотр не ограничивает следующую выборку.
|
|
102
|
+
|
|
103
|
+
Нормализатор не является универсальным морфологическим анализатором. Для неизвестного синонима или неоднозначного названия следует использовать термин из списка выше, точный `title` либо OID. Выборка вместе с зависимостями ограничена 200 объектами; при превышении лимита интерфейс попросит сузить запрос.
|
|
104
|
+
|
|
34
105
|
### Вычисляемые logical links
|
|
35
106
|
По умолчанию logical links рисуются напрямую по полям `source`, `target` и `topology`. Чтобы включить поиск сетевого маршрута, нужно одновременно включить режим в документе и пометить конкретную logical link.
|
|
36
107
|
|
|
37
108
|
``` yaml
|
|
38
109
|
docs:
|
|
39
|
-
|
|
110
|
+
something.seaf2drawio_schema_r41:
|
|
40
111
|
description: Схема Р41 (seaf2drawio, raw TA dataset)
|
|
41
112
|
type: seaf2drawio
|
|
42
113
|
source: seaf.company.ds.ta.schema_r41
|
|
@@ -115,7 +186,7 @@ datasets:
|
|
|
115
186
|
<mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{width}}" height="{{height}}" as="geometry" />
|
|
116
187
|
</mxCell>
|
|
117
188
|
</object>
|
|
118
|
-
schema: seaf.ta.components.
|
|
189
|
+
schema: seaf.company.ta.components.networks
|
|
119
190
|
parent_id: segment
|
|
120
191
|
type: type:Маршрутизатор
|
|
121
192
|
algo: Y+
|
|
@@ -133,7 +204,7 @@ datasets:
|
|
|
133
204
|
<mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{height}}" height="{{width}}" as="geometry" />
|
|
134
205
|
</mxCell>
|
|
135
206
|
</object>
|
|
136
|
-
schema: seaf.ta.services.
|
|
207
|
+
schema: seaf.company.ta.services.networks
|
|
137
208
|
parent_id: segment
|
|
138
209
|
type: type:LAN
|
|
139
210
|
algo: Y+
|
|
@@ -145,14 +216,61 @@ datasets:
|
|
|
145
216
|
h: 220
|
|
146
217
|
```
|
|
147
218
|
## Трансформации
|
|
148
|
-
Изменения, которые пользователь внёс на построенную
|
|
219
|
+
Изменения, которые пользователь внёс на построенную диаграмму, можно сохранить в виде набора трансформаций. Без `diff_path` кнопка **Export transformations** скачивает YAML. С `diff_path` она называется **Save transformations** и записывает файл проекта.
|
|
149
220
|
|
|
150
221
|
Трансформации предназначены для сохранения визуальных изменений (положение объектов, положение стрелок, и т.п.) и не предназначены для изменений иерархии или архитектурных данных (перенос сервисов в другие подсети, изменения описаний и т.п.).
|
|
151
222
|
|
|
152
|
-
|
|
223
|
+
Чтобы сохранять трансформации сразу в файл проекта, укажите `diff_path` в результате
|
|
224
|
+
`source`. При открытии документа `seaf2drawio` загрузит файл `.yaml` или `.json`, а кнопка
|
|
225
|
+
`Save transformations` запишет его через механизм хранения ArchTool. Путь задаётся
|
|
226
|
+
относительно YAML документа; разрешены сегменты `..`, в том числе для перехода в другую
|
|
227
|
+
папку проекта. В Portal лишние `..` нормализуются к корню репозитория. В IDE путь
|
|
228
|
+
нормализуется к каталогу корневого манифеста; если он расположен не в корне репозитория,
|
|
229
|
+
получившийся путь может отличаться от Portal.
|
|
153
230
|
|
|
154
|
-
|
|
155
|
-
|
|
231
|
+
Поддерживаются файлы `.yaml` и `.json`. В Portal сохранение доступно только для
|
|
232
|
+
репозитория, подключённого к манифесту, и каждое успешное сохранение создаёт коммит через
|
|
233
|
+
механизм хранения ArchTool. Перед записью файл перечитывается: трансформации элементов,
|
|
234
|
+
которых нет на текущей схеме, сохраняются из свежего содержимого файла. Для элементов
|
|
235
|
+
текущей схемы побеждает последнее сохранение. Между чтением и записью остаётся окно для
|
|
236
|
+
конкурентного изменения; в IntelliJ запись `pushFile` выполняется с задержкой, поэтому
|
|
237
|
+
быстрое повторное сохранение может прочитать прежнее содержимое. Если файл не удалось
|
|
238
|
+
прочитать, схема откроется без его трансформаций, но сохранение останется заблокированным
|
|
239
|
+
до обновления документа.
|
|
240
|
+
|
|
241
|
+
Трансформации отсутствующих элементов не удаляются автоматически и могут сохраняться в
|
|
242
|
+
файле бессрочно. Если элемент удалён из архитектуры окончательно, удалите его запись из
|
|
243
|
+
файла трансформаций вручную; иначе она будет переноситься при последующих сохранениях.
|
|
244
|
+
Пример `examples/diff.yaml` содержит только записи, которые соответствуют текущей
|
|
245
|
+
схеме.
|
|
246
|
+
|
|
247
|
+
Если `diff_path` не задан, кнопка продолжит скачивать `diff*.yaml` в браузере (или
|
|
248
|
+
предложит выбрать файл в IDE-плагине). При отсутствии файла создание возможно только
|
|
249
|
+
когда среда возвращает явный ответ 404; в VS Code и Portal с
|
|
250
|
+
`VUE_APP_SEAF_ENVELOPED_REQUESTS=true` файл
|
|
251
|
+
нужно создать заранее, иначе документ покажет ошибку чтения и заблокирует сохранение.
|
|
252
|
+
|
|
253
|
+
Пример документа с сохранением трансформаций на диск:
|
|
254
|
+
|
|
255
|
+
```yaml
|
|
256
|
+
docs:
|
|
257
|
+
archtool.plugins.example.seaf2drawio.save_transformations:
|
|
258
|
+
type: seaf2drawio
|
|
259
|
+
location: SEAF.ArchTool/Руководство/Документы/SEAF2Draw.io/Примеры/Трансформации
|
|
260
|
+
origin:
|
|
261
|
+
dataset: archtool.plugins.example.seaf2drawio.data
|
|
262
|
+
source: >
|
|
263
|
+
({
|
|
264
|
+
"title": "Применение трансформаций",
|
|
265
|
+
"dataset": dataset,
|
|
266
|
+
"diff_path": "./diff.yaml"
|
|
267
|
+
})
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Для совместимости трансформации по-прежнему можно передать готовым объектом в
|
|
271
|
+
параметре `diff`. В этом варианте сохранённый файл следует подключить как датасет:
|
|
272
|
+
|
|
273
|
+
```yaml
|
|
156
274
|
docs:
|
|
157
275
|
archtool.plugins.example.seaf2drawio.transformations:
|
|
158
276
|
type: seaf2drawio
|
|
@@ -4,8 +4,7 @@
|
|
|
4
4
|
Мы будем стараться сохранять совместимость при его развитии, но следует учитывать эту информацию
|
|
5
5
|
при принятии решения об его использовании.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
данный функционал пока не поддерживается. Но обязательно будет.
|
|
7
|
+
Плагины, включённые в сборку, доступны в портале и в IDE. В IDE они всегда подключаются сразу, без lazy loading.
|
|
9
8
|
|
|
10
9
|
## Введение
|
|
11
10
|
|
|
@@ -166,18 +165,64 @@ DocHub.documents.register('html', doc);
|
|
|
166
165
|
|
|
167
166
|
## Сборка
|
|
168
167
|
|
|
169
|
-
Плагин
|
|
168
|
+
Плагин собирается в контексте проекта SEAF.ArchTool. В `plugins.json` задаётся массив descriptors:
|
|
170
169
|
|
|
171
170
|
```json
|
|
171
|
+
[
|
|
172
172
|
{
|
|
173
|
-
"
|
|
174
|
-
|
|
175
|
-
|
|
173
|
+
"id": "html",
|
|
174
|
+
"documents": ["html"],
|
|
175
|
+
"source": {
|
|
176
|
+
"type": "local",
|
|
177
|
+
"location": "plugins/html"
|
|
178
|
+
}
|
|
176
179
|
}
|
|
180
|
+
]
|
|
177
181
|
```
|
|
178
182
|
|
|
179
|
-
|
|
180
|
-
|
|
183
|
+
### Поля descriptor
|
|
184
|
+
|
|
185
|
+
| Поле | Обязательное | Описание |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| `id` | Да | Уникальный ID плагина: строчные латинские буквы, цифры и дефисы; первый символ — буква или цифра (`^[a-z0-9][a-z0-9-]*$`). |
|
|
188
|
+
| `documents` | Да | Непустой массив типов, точно соответствующих `DocHub.documents.register(...)`. Каждый тип имеет одного владельца; повторы внутри массива тоже запрещены. |
|
|
189
|
+
| `source.type` | Да | `local` — каталог внутри core; `package` — установленный npm-пакет. |
|
|
190
|
+
| `source.location` | Да | Для `local` — путь к каталогу с `package.json` относительно корня core. Путь нормализуется; абсолютные пути и выход за корень запрещены. Для `package` — имя установленного пакета, не путь к `.tgz`. |
|
|
191
|
+
| `lazy` | Нет | Boolean override режима загрузки: `true` — lazy, `false` — eager. Без поля наследуется общий env-флаг. В IDE всегда eager. |
|
|
192
|
+
|
|
193
|
+
Entry определяется через `package.json.main`, по умолчанию — `index.js`. Для источника `package` файл `package.json` должен быть доступен через `require.resolve('<имя-пакета>/package.json')`; если пакет использует `exports`, он должен разрешать этот путь.
|
|
194
|
+
|
|
195
|
+
При стандартном каталоге сборки JS-артефакт package-плагина располагается в `dist/plugins/packages/<id>.js`. Для local используется `dist/plugins/<нормализованный location>.js`, например `dist/plugins/plugins/html.js`. Пути JS/CSS lazy-плагинов записываются в `lazy-plugins.json`.
|
|
196
|
+
|
|
197
|
+
### Миграция со старого формата
|
|
198
|
+
|
|
199
|
+
Объект `{ "inbuilt": ["plugins/html", ...] }` больше не поддерживается и приводит к ошибке сборки. Для каждого пути создайте элемент массива по примеру выше: задайте уникальный `id`, перечислите фактически регистрируемые `documents`, укажите `source.type: "local"` и перенесите путь в `source.location`. Поле `lazy` можно не задавать — сохранится общий режим загрузки.
|
|
200
|
+
|
|
201
|
+
Старое поле `external` и загрузка JS из `manifest.json.plugins` больше не поддерживаются. Внешний плагин нужно установить как package и включить в `plugins.json` перед сборкой. Источник `remote` пока не реализован. Сам PWA-файл `manifest.json` продолжает генерироваться.
|
|
202
|
+
|
|
203
|
+
В IDE package-плагины также включаются в сборку. Legacy-ответ `fetchPlugins` / `pluginList` содержит только пути local-плагинов и не управляет их загрузкой.
|
|
204
|
+
|
|
205
|
+
### Lazy loading
|
|
206
|
+
|
|
207
|
+
Без lazy loading все включённые в сборку плагины загружаются при запуске ArchTool, даже если пользователь ими не пользуется.
|
|
208
|
+
|
|
209
|
+
Lazy loading позволяет отложить загрузку плагина до первого открытия документа соответствующего типа. Это уменьшает объём ресурсов, необходимых для запуска приложения. При повторном открытии документа уже загруженный плагин используется снова.
|
|
210
|
+
|
|
211
|
+
Текущая реализация меняет только момент загрузки: плагин по-прежнему должен быть указан до сборки ArchTool.
|
|
212
|
+
|
|
213
|
+
`VUE_APP_DOCHUB_PLUGINS_LAZY_LOADING` задаёт режим по умолчанию при сборке: `Y` — lazy, `N` или отсутствие настройки — eager. Необязательное поле `lazy` в descriptor переопределяет этот режим для конкретного плагина:
|
|
214
|
+
|
|
215
|
+
| Поле `lazy` | Поведение |
|
|
216
|
+
|---|---|
|
|
217
|
+
| Отсутствует | Наследует общий env-флаг |
|
|
218
|
+
| `true` | Загружается при открытии документа своего типа, даже при общем `N` |
|
|
219
|
+
| `false` | Подключается через HTML при запуске, даже при общем `Y` |
|
|
220
|
+
|
|
221
|
+
Например, чтобы всегда подключать HTML-плагин сразу, добавьте `"lazy": false` рядом с `id`, `documents` и `source`. Допустимы только boolean-значения, не строки `"Y"`/`"N"` и не `null`.
|
|
222
|
+
|
|
223
|
+
Настройка одинакова для источников `local` и `package` и применяется ко всем типам из `documents` одного плагина. Все плагины включаются в сборку; режим меняет только момент загрузки JS/CSS браузером. В `lazy-plugins.json` попадают только lazy-плагины; если их нет, файл не создаётся и frontend его не запрашивает.
|
|
224
|
+
|
|
225
|
+
В IDE (`VUE_APP_DOCHUB_MODE=plugin`) все плагины остаются eager независимо от env и `lazy` в descriptor. Изменение режима требует пересборки приложения.
|
|
181
226
|
|
|
182
227
|
Теперь можно собрать проект SEAF.ArchTool в нескольких режимах:
|
|
183
228
|
|