@seafteam/seaf-archtool-core-plugin-suite 2026.30.0 → 2026.32.0-rc.1
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 +240 -41
- package/documentation/docs/manual/docs/docs.md +1 -0
- package/documentation/docs/manual/docs/drawio_intro.md +29 -8
- package/documentation/docs/manual/docs/editable_table/step_0_base/table.yaml +11 -3
- package/documentation/docs/manual/docs/editable_table/step_0_base/template.md +11 -2
- package/documentation/docs/manual/docs/editable_table/step_3_headers/template.md +33 -0
- package/documentation/docs/manual/docs/examples/wizard.yaml +18 -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/markaper.md +6 -0
- package/documentation/docs/manual/docs/root.yaml +12 -0
- package/documentation/docs/manual/docs/seaf2drawio/examples/diff.yaml +0 -96
- package/documentation/docs/manual/docs/seaf2drawio/seaf2drawio.md +129 -7
- package/documentation/docs/manual/docs/wizard.md +34 -0
- 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 -1953
- 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
|
@@ -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,14 +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
|
|
|
31
|
+
Параметры iframe Draw.io для seaf2drawio настраиваются так же, как у документа `drawio`:
|
|
32
|
+
переменные `VUE_APP_DOCHUB_PLUGIN_DRAWIO_SERVER_URI` / `VUE_APP_DOCHUB_PLUGIN_DRAWIO_URL_PARAMS`
|
|
33
|
+
и поле профиля `drawio_url_params` (см. [документацию drawio](/docs/archtool.plugins.drawio)).
|
|
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
|
+
|
|
30
105
|
### Вычисляемые logical links
|
|
31
106
|
По умолчанию logical links рисуются напрямую по полям `source`, `target` и `topology`. Чтобы включить поиск сетевого маршрута, нужно одновременно включить режим в документе и пометить конкретную logical link.
|
|
32
107
|
|
|
33
108
|
``` yaml
|
|
34
109
|
docs:
|
|
35
|
-
|
|
110
|
+
something.seaf2drawio_schema_r41:
|
|
36
111
|
description: Схема Р41 (seaf2drawio, raw TA dataset)
|
|
37
112
|
type: seaf2drawio
|
|
38
113
|
source: seaf.company.ds.ta.schema_r41
|
|
@@ -111,7 +186,7 @@ datasets:
|
|
|
111
186
|
<mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{width}}" height="{{height}}" as="geometry" />
|
|
112
187
|
</mxCell>
|
|
113
188
|
</object>
|
|
114
|
-
schema: seaf.ta.components.
|
|
189
|
+
schema: seaf.company.ta.components.networks
|
|
115
190
|
parent_id: segment
|
|
116
191
|
type: type:Маршрутизатор
|
|
117
192
|
algo: Y+
|
|
@@ -129,7 +204,7 @@ datasets:
|
|
|
129
204
|
<mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{height}}" height="{{width}}" as="geometry" />
|
|
130
205
|
</mxCell>
|
|
131
206
|
</object>
|
|
132
|
-
schema: seaf.ta.services.
|
|
207
|
+
schema: seaf.company.ta.services.networks
|
|
133
208
|
parent_id: segment
|
|
134
209
|
type: type:LAN
|
|
135
210
|
algo: Y+
|
|
@@ -141,14 +216,61 @@ datasets:
|
|
|
141
216
|
h: 220
|
|
142
217
|
```
|
|
143
218
|
## Трансформации
|
|
144
|
-
Изменения, которые пользователь внёс на построенную
|
|
219
|
+
Изменения, которые пользователь внёс на построенную диаграмму, можно сохранить в виде набора трансформаций. Без `diff_path` кнопка **Export transformations** скачивает YAML. С `diff_path` она называется **Save transformations** и записывает файл проекта.
|
|
145
220
|
|
|
146
221
|
Трансформации предназначены для сохранения визуальных изменений (положение объектов, положение стрелок, и т.п.) и не предназначены для изменений иерархии или архитектурных данных (перенос сервисов в другие подсети, изменения описаний и т.п.).
|
|
147
222
|
|
|
148
|
-
|
|
223
|
+
Чтобы сохранять трансформации сразу в файл проекта, укажите `diff_path` в результате
|
|
224
|
+
`source`. При открытии документа `seaf2drawio` загрузит файл `.yaml` или `.json`, а кнопка
|
|
225
|
+
`Save transformations` запишет его через механизм хранения ArchTool. Путь задаётся
|
|
226
|
+
относительно YAML документа; разрешены сегменты `..`, в том числе для перехода в другую
|
|
227
|
+
папку проекта. В Portal лишние `..` нормализуются к корню репозитория. В IDE путь
|
|
228
|
+
нормализуется к каталогу корневого манифеста; если он расположен не в корне репозитория,
|
|
229
|
+
получившийся путь может отличаться от Portal.
|
|
149
230
|
|
|
150
|
-
|
|
151
|
-
|
|
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
|
|
152
274
|
docs:
|
|
153
275
|
archtool.plugins.example.seaf2drawio.transformations:
|
|
154
276
|
type: seaf2drawio
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Мастер (wizard)
|
|
2
|
+
|
|
3
|
+
Документ показывает вложенные документы по шагам. На экране — текущий шаг, индикатор прогресса и кнопки **Назад** / **Далее**. Переход только кнопками: клик по индикатору ничего не делает. Одновременно рендерится только текущий шаг.
|
|
4
|
+
|
|
5
|
+
## Профиль
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
docs:
|
|
9
|
+
archtool.example.wizard:
|
|
10
|
+
type: wizard
|
|
11
|
+
title: Пример мастера # Заголовок. По умолчанию Wizard
|
|
12
|
+
wizardConfig:
|
|
13
|
+
showProgress: true # Индикатор шагов. По умолчанию true
|
|
14
|
+
navigationRules:
|
|
15
|
+
restricted: true # См. ниже. По умолчанию true
|
|
16
|
+
source: # Массив шагов (как у таблиц — inline, файл или JSONata)
|
|
17
|
+
- id: table # Идентификатор шага
|
|
18
|
+
title: Таблица # Подпись на индикаторе
|
|
19
|
+
src: "@document/archtool.table.preset"
|
|
20
|
+
- id: mermaid
|
|
21
|
+
title: Mermaid
|
|
22
|
+
src: "@document/archtool.example.mermaid"
|
|
23
|
+
- id: plantuml
|
|
24
|
+
title: PlantUML
|
|
25
|
+
src: "@document/archtool.example.pml"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`src` — ссылка на объект (`@document/...`, `@entity/...`) или обычный URL (откроется в iframe). Параметры вложенного документа, если нужны, указываются в самой ссылке: `@document/foo?bar=1`.
|
|
29
|
+
|
|
30
|
+
`restricted: true` — **Далее** можно заблокировать из вложенного документа. Например, редактируемая таблица не пускает дальше, пока есть несохранённые изменения. `false` — кнопка смотрит только на то, не последний ли это шаг.
|
|
31
|
+
|
|
32
|
+
## Пример
|
|
33
|
+
|
|
34
|
+

|
|
@@ -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
|
|
|
@@ -75,6 +75,123 @@ imports:
|
|
|
75
75
|
Выбранная архитектура привязана к вкладке (в разных вкладках можно открыть разные архитектуры). В Url проставляется параметр выбранной архитектуры, что позволяет ей делиться.
|
|
76
76
|
|
|
77
77
|
|
|
78
|
+
## Общий манифест (common)
|
|
79
|
+
|
|
80
|
+
Кроме списка `imports`, root манифест может объявить общий манифест — содержимое, которое подмешивается
|
|
81
|
+
к манифесту **каждой** архитектуры на путях чтения (расчёт датасетов, меню, валидаторы). Пути записи в
|
|
82
|
+
него не ведут: сохранение через put-content всегда уходит в манифест конкретной архитектуры.
|
|
83
|
+
|
|
84
|
+
Общий манифест загружается под зарезервированными `alias: common` и `permission: __common` — использовать
|
|
85
|
+
эти значения в `imports` нельзя, root манифест с ними будет отклонён.
|
|
86
|
+
|
|
87
|
+
### Форма 1: просто путь
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
common: master_permissions/common.yaml
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Форма 2: объект с архитектурными пакетами
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
common:
|
|
97
|
+
root: master_permissions/common.yaml
|
|
98
|
+
packages:
|
|
99
|
+
- root: seaf-common/package.yaml
|
|
100
|
+
id: seaf-common
|
|
101
|
+
version: "1.11.0"
|
|
102
|
+
- root: eco_facades/package.yaml
|
|
103
|
+
id: eco_facades
|
|
104
|
+
version: ">=1.0.0 <2.0.0"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
| Название | Обязательность | Описание |
|
|
108
|
+
|--------------------|----------------|-----------------------------------------------------------------------------------------------------------------------|
|
|
109
|
+
| root | Нет | Путь к файлу общего манифеста — произвольное содержимое, как в форме 1 |
|
|
110
|
+
| packages | Нет | Список архитектурных пакетов, из которых собирается общий манифест |
|
|
111
|
+
| packages[].root | Да | Путь к манифесту пакета |
|
|
112
|
+
| packages[].id | Да | Идентификатор пакета — должен совпадать с идентификатором в разделе `$package` этого пакета |
|
|
113
|
+
| packages[].version | Да | Ожидаемая версия пакета: диапазон semver. **Всегда пишите в кавычках** — см. ниже |
|
|
114
|
+
|
|
115
|
+
`root` и `packages` не исключают друг друга: общий манифест собирается из всех перечисленных корней —
|
|
116
|
+
сначала `root`, затем пакеты в порядке объявления. Порядок значим: при совпадении путей выигрывает
|
|
117
|
+
источник, объявленный позже, то есть пакет перекрывает `root`.
|
|
118
|
+
|
|
119
|
+
Дубли между корнями не отсеиваются: если один и тот же файл достижим из нескольких корней, он
|
|
120
|
+
загружается заново на каждый из них и мёржится по тому же правилу — выигрывает корень, объявленный
|
|
121
|
+
позже. На результат это обычно не влияет, потому что содержимое одинаковое, но лишние загрузки
|
|
122
|
+
стоят времени, поэтому общие для нескольких пакетов файлы лучше выносить в отдельный пакет и
|
|
123
|
+
подключать один раз.
|
|
124
|
+
|
|
125
|
+
### Версии пакетов пишутся в кавычках
|
|
126
|
+
|
|
127
|
+
**Рекомендация: всегда пишите `version` в кавычках** — даже там, где YAML и без них разберёт значение
|
|
128
|
+
как строку. Тогда не нужно помнить, в каких случаях незакавыченная версия превратится в число и root
|
|
129
|
+
манифест не загрузится.
|
|
130
|
+
|
|
131
|
+
`version` обязана быть строкой. Кавычки сами по себе не проверяются — проверяется, чем значение
|
|
132
|
+
оказалось после разбора YAML. Если YAML разобрал его как число, root манифест будет отклонён:
|
|
133
|
+
|
|
134
|
+
```yaml
|
|
135
|
+
version: "1.11.0" # правильно
|
|
136
|
+
version: ">=1.0.0 <2.0.0"
|
|
137
|
+
version: 1.11.0 # загрузится (три части YAML разбирает как строку), но не рекомендуется
|
|
138
|
+
version: 1.10 # ошибка: число, root манифест не загрузится
|
|
139
|
+
version: 1 # ошибка: число, root манифест не загрузится
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Причина в YAML: незакавыченную версию из одной или двух частей он разбирает как число, а число
|
|
143
|
+
`1.10` — это то же самое, что `1.1`. Для semver это разные требования: диапазон `1.1` не покрывает
|
|
144
|
+
версию `1.10.0`, а `1.10` не покрывает `1.1.0`. Молча подставить одно вместо другого хуже, чем
|
|
145
|
+
отвергнуть манифест, поэтому нестроковая `version` считается ошибкой:
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
Error in root manifest: common.packages[0] must have a non-empty 'version' property (quoted string, e.g. '1.11.0')
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Версия из трёх частей (`1.11.0`) и диапазоны вида `^1.10`, `~1.10`, `1.x` числом быть не могут, поэтому
|
|
152
|
+
и без кавычек остаются строкой и принимаются. Это не повод опускать кавычки: запись без них легко
|
|
153
|
+
по ошибке сократить до `1.10` или `1`, и root манифест перестанет загружаться.
|
|
154
|
+
|
|
155
|
+
### Общий манифест можно не объявлять
|
|
156
|
+
|
|
157
|
+
Все перечисленные записи равнозначны друг другу и означают, что общего манифеста нет — архитектуры
|
|
158
|
+
грузятся сами по себе:
|
|
159
|
+
|
|
160
|
+
- атрибута `common` в root манифесте нет вовсе;
|
|
161
|
+
- `common:` без значения;
|
|
162
|
+
- `common: {}` — пустой объект;
|
|
163
|
+
- `common:` с пустым списком `packages` и без `root`.
|
|
164
|
+
|
|
165
|
+
Ошибкой ни одна из них не считается.
|
|
166
|
+
|
|
167
|
+
### Общий манифест и ролевая модель
|
|
168
|
+
|
|
169
|
+
Общий манифест доступен только при включённой ролевой модели v2 (`VUE_APP_DOCHUB_ROLES_MODEL_V2=Y`).
|
|
170
|
+
Если она выключена, архитектура в root манифесте и так одна и доступна всем — подмешивать общий
|
|
171
|
+
манифест не к чему.
|
|
172
|
+
|
|
173
|
+
Объявленный при выключенной ролевой модели `common` не игнорируется — загрузка прерывается с ошибкой:
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
If the role model is disabled, the root manifest cannot declare a common manifest.
|
|
177
|
+
Value of VUE_APP_DOCHUB_ROLES_MODEL_V2=N
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Вырожденные записи из раздела выше под это правило не попадают: они равнозначны отсутствию `common`,
|
|
181
|
+
поэтому при выключенной ролевой модели ошибки не дают.
|
|
182
|
+
|
|
183
|
+
### Проверка версий пакетов
|
|
184
|
+
|
|
185
|
+
Если объявлены `packages`, то после сборки общего манифеста ожидаемые версии сверяются с фактическими —
|
|
186
|
+
теми, что указаны в разделе `$package` самих пакетов (см. «Пакеты» в руководстве).
|
|
187
|
+
|
|
188
|
+
Несовпадение **не прерывает** загрузку: расхождения попадают в отклонения и видны в
|
|
189
|
+
`GET seaf-core/api/core/storage/problems` и в `GET /health/info`. Сверка различает три случая:
|
|
190
|
+
|
|
191
|
+
- пакет не найден в собранном общем манифесте;
|
|
192
|
+
- версия не удовлетворяет ожидаемому диапазону;
|
|
193
|
+
- сам диапазон задан некорректно (опечатка в root манифесте).
|
|
194
|
+
|
|
78
195
|
## Переменные окружения для управления ролевой моделью:
|
|
79
196
|
|
|
80
197
|
| Название | Дефолт | Описание |
|