Igor20264
+158
-12
@@ -1,6 +1,6 @@
|
||||
# Схемы и диаграммы
|
||||
|
||||
В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki) или локальный Mermaid (браузер / QuickJS), иначе Kroki.
|
||||
В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki), локальный Mermaid (браузер / QuickJS), локальный IDEF0 (Pillow) или DFD через [data-flow-diagram](https://github.com/pbauermeister/dfd) (вшитый / системный Graphviz или Kroki).
|
||||
|
||||
## Синтаксис в markdown
|
||||
|
||||
@@ -32,13 +32,12 @@ Rel(user, app, "логин")
|
||||
| `` ```uml `` / `` ```plantuml `` | Сырой PlantUML (`@startuml`…`@enduml`) |
|
||||
| `` ```uml-<id> `` / `` ```<id> `` | Схема из `md2gost.schemes.json` (обёртка и `!include` добавляются сами) |
|
||||
| `` ```mermaid `` / `` ```mmd `` | Mermaid: браузер / QuickJS / Kroki |
|
||||
| `` ```bpmn `` / `` ```uml-bpmn `` | BPMN 2.0 (макросы библиотеки md2gost) |
|
||||
|
||||
**IDEF0 / DFD** конвертер не рисует — вставляйте готовый PNG как обычный Рисунок.
|
||||
| `` ```idef0 `` / `` ```uml-idef0 `` | IDEF0 (FIPS 183): локальный рендер, без PlantUML / Kroki |
|
||||
| `` ```dfd `` / `` ```uml-dfd `` / `` ```data-flow-diagram `` | DFD ([pbauermeister/dfd](https://github.com/pbauermeister/dfd)): вшитый Graphviz / PATH / Kroki |
|
||||
|
||||
## Встроенные схемы
|
||||
|
||||
Файл шаблона: [`md2gost/diagrams/schemes.json`](../md2gost/diagrams/schemes.json). При первом запуске копируется в `md2gost.schemes.json` рядом с приложением (существующий файл не перезаписывается).
|
||||
Файл шаблона: [`md2gost/diagrams/schemes.json`](../md2gost/diagrams/schemes.json). При первом запуске копируется в `md2gost.schemes.json` рядом с приложением. При каждом запуске встроенные схемы (`author: md2gost`) синхронизируются с шаблоном: новые id добавляются, устаревшие (например удалённый `bpmn`) убираются, содержимое обновляется. Схемы с пустым или другим `author` не трогаются. Если правите встроенную в GUI и сохраняете — `author` сбрасывается, чтобы миграция не затёрла правки.
|
||||
|
||||
| id | Название | Оградка |
|
||||
|----|----------|---------|
|
||||
@@ -46,9 +45,9 @@ Rel(user, app, "логин")
|
||||
| `c4context` | C4 Context | `` ```uml-c4context `` |
|
||||
| `c4component` | C4 Component | `` ```uml-c4component `` |
|
||||
| `usecase` | Прецеденты | `` ```uml-usecase `` / `` ```usecase `` |
|
||||
| `bpmn` | BPMN 2.0 | `` ```bpmn `` / `` ```uml-bpmn `` |
|
||||
| `archimate` | ArchiMate 3.2 | `` ```uml-archimate `` / `` ```archimate `` |
|
||||
|
||||
Для схем в теле пишите **только макросы** (Person, Start, XOR, …) — без `@startuml` и без `!include`, если схема сама их добавляет.
|
||||
Для схем в теле пишите **только макросы** (Person, Rel, actor, Business_Actor, …) — без `@startuml` и без `!include`, если схема сама их добавляет.
|
||||
|
||||
### C4 (пример макросов)
|
||||
|
||||
@@ -58,14 +57,151 @@ Rel(user, app, "логин")
|
||||
|
||||
`actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>`.
|
||||
|
||||
### BPMN
|
||||
### ArchiMate 3.2
|
||||
|
||||
`Pool` / `Lane`, `Start` / `StartMessage` / `End`, `UserTask` / `ServiceTask`, `XOR` / `AND` / `OR`, `Flow` / `CondFlow` / `DefaultFlow` / `MessageFlow`, …
|
||||
|
||||
Sequence Flow только внутри пула; между пулами — `MessageFlow`.
|
||||
`Business_Actor`, `Application_Service`, `Technology_Node`, `Rel_Serving` / `Rel_Realization` / `Rel_Assignment`, …
|
||||
Подробно: [archimate.md](archimate.md).
|
||||
|
||||
Полные шпаргалки — поля `docs` и `ai-prompt` в JSON; в GUI: **Шаблоны UML** и кнопки схем в **Справка → Промпт для ИИ**.
|
||||
|
||||
## IDEF0 (FIPS 183)
|
||||
|
||||
Оградка `` ```idef0 `` (то же: `` ```uml-idef0 ``). Текст — не XML: шапка формы, боксы, стрелки ICOM (Input слева, Control сверху, Output справа, Mechanism снизу). Контекст A-0 — один бокс; декомпозиция — несколько боксов «лесенкой» и связи между ними. Рендер локальный (Pillow), без Java и Kroki.
|
||||
|
||||
````markdown
|
||||
%a0 Контекстная диаграмма A-0
|
||||
|
||||
```idef0
|
||||
title Распорядиться товаром
|
||||
node A-0
|
||||
number 1
|
||||
author Кинзябулатов Рамиль
|
||||
project Разработка универсальной модели торгового предприятия
|
||||
date 08.02.2022
|
||||
rev 31.03.2022
|
||||
status PUBLICATION
|
||||
context TOP
|
||||
|
||||
[A0] Распорядиться товаром
|
||||
<- Спрос
|
||||
^ Нормативная документация
|
||||
-> Товар
|
||||
v Персонал
|
||||
```
|
||||
````
|
||||
|
||||
Шапка/подвал NIST-формы (необязательные поля): `title`, `node`, `number`, `author`, `project`, `date`, `rev`, `status` (`WORKING` / `DRAFT` / `RECOMMENDED` / `PUBLICATION`), `context` (для A-0 — `TOP`), `used_at`, `reader`, `reader_date`, `notes`, `purpose`, `viewpoint`, `page`, `form` (`kit` по умолчанию, `plain` — без рамки).
|
||||
|
||||
Бокс: `[A0] Имя` или `box A0 Имя`. Стрелки к последнему боксу: `<-` / `in` вход, `^` / `control` управление, `->` / `out` выход, `v` / `mech` механизм. Явно: `A0 <- Спрос`.
|
||||
|
||||
Декомпозиция A0 (3 бокса, развилка, O→C, ICOM на рамке):
|
||||
|
||||
````markdown
|
||||
%a0 Декомпозиция A0
|
||||
|
||||
```idef0
|
||||
title Распорядиться товаром
|
||||
node A0
|
||||
number 2
|
||||
author Кинзябулатов Рамиль
|
||||
project Разработка универсальной модели торгового предприятия
|
||||
date 08.02.2022
|
||||
rev 31.03.2022
|
||||
status PUBLICATION
|
||||
context A-0
|
||||
purpose Обеспечить наличие товара и его отпуск покупателю
|
||||
viewpoint Руководитель торгового предприятия
|
||||
|
||||
[A1] Принять и оценить спрос
|
||||
[A2] Закупить и хранить
|
||||
[A3] Отгрузить товар
|
||||
|
||||
A1 <- Спрос [I1]
|
||||
A2 <- Предложения поставщиков [I2]
|
||||
A1, A2, A3 ^ Нормативная документация [C1]
|
||||
A1 ^ Ассортиментная политика [C2]
|
||||
A3 ^ Условия поставки [C3]
|
||||
A1 -> A2 : план закупок
|
||||
A1 -> A2.C : график поставок
|
||||
A2 -> A3 : товар к отгрузке
|
||||
A3 -> Товар [O1]
|
||||
A3 -> Акт отгрузки [O2]
|
||||
A1, A2, A3 v Персонал [M1]
|
||||
A2 v Склад [M2]
|
||||
```
|
||||
````
|
||||
|
||||
Подписи к стрелкам — существительные рядом со стволом, не на линии; если связь не очевидна, рисуется squiggle (FIPS 183). Длинные фразы переносятся на 2–3 строки.
|
||||
|
||||
Короткий каркас:
|
||||
|
||||
```
|
||||
[A1] Принять заказ
|
||||
[A2] Отгрузить
|
||||
A1 <- Заявка [I1]
|
||||
A1 ^ Правила [C1]
|
||||
A1 -> A2 : заказ
|
||||
A1 -> A2, A3 : данные
|
||||
A1, A2 -> A3 : сводка
|
||||
A2 -> Товар [O1]
|
||||
A2 v Склад [M1]
|
||||
```
|
||||
|
||||
Туннель (скобки IDEF0): `(in Секрет` — на границе листа, `in) Локальный` — у бокса. Вызов другой модели: `call ИмяМодели`. Сторона порта: `A1.O -> A2.C : условие`.
|
||||
|
||||
## DFD (data-flow-diagram / SA/RT)
|
||||
|
||||
Оградка `` ```dfd `` (то же: `` ```uml-dfd ``, `` ```data-flow-diagram ``, `` ```yourdon ``). Синтаксис — пакет [pbauermeister/dfd](https://github.com/pbauermeister/dfd) (ставится с md2gost, Python 3.11+). Рендер: Graphviz (`dot` / `neato`) или Kroki (`graphviz`), не Pillow.
|
||||
|
||||
Порядок поиска Graphviz (как у `plantuml.jar`):
|
||||
|
||||
1. Вшитый `md2gost/vendor/graphviz` (exe-сборка / `python scripts/fetch_graphviz.py`)
|
||||
2. Кэш `%LOCALAPPDATA%\md2gost\graphviz` (GUI: **Настройки → Диаграммы → «Скачать Graphviz»**)
|
||||
3. `dot` / `neato` в `PATH`
|
||||
4. Локальный Kroki → `https://kroki.io` при `--diagram-fallback remote`
|
||||
|
||||
````markdown
|
||||
%dfd0 Контекстная DFD
|
||||
|
||||
```dfd
|
||||
style context
|
||||
|
||||
entity Client Клиент
|
||||
entity Warehouse Склад
|
||||
process System Система учёта заявок
|
||||
|
||||
Client --> System заявка
|
||||
System --> Client статус
|
||||
System --> Warehouse накладная
|
||||
```
|
||||
````
|
||||
|
||||
Ключевые слова узлов: `process`, `entity`, `store`, `control`, `channel`. Потоки: `-->`, `->>`, `<->`, сигналы `::>` / `<::`. Контекст: `style context`. Полный синтаксис — [документация Upstream](https://github.com/pbauermeister/dfd/blob/main/doc/README.md).
|
||||
|
||||
Декомпозиция (уровень 0):
|
||||
|
||||
````markdown
|
||||
%dfd1 DFD уровня 0
|
||||
|
||||
```dfd
|
||||
entity Client Клиент
|
||||
entity Warehouse Склад
|
||||
process Accept Принять заявку
|
||||
process Register Зарегистрировать
|
||||
process Ship Сформировать накладную
|
||||
store Orders Заявки
|
||||
|
||||
Client --> Accept заявка
|
||||
Accept --> Orders новая заявка
|
||||
Orders --> Register данные заявки
|
||||
Register --> Ship подтверждённая заявка
|
||||
Ship --> Warehouse накладная
|
||||
Ship --> Client уведомление
|
||||
```
|
||||
````
|
||||
|
||||
Зависимости: `data-flow-diagram` идёт с md2gost (Python ≥3.11). Без Graphviz офлайн DFD не нарисуется — либо кнопка «Скачать Graphviz» / `scripts/fetch_graphviz.py`, либо `--diagram-fallback remote` → kroki.io.
|
||||
|
||||
## Файл схем: поля
|
||||
|
||||
```json
|
||||
@@ -114,7 +250,15 @@ id схемы: латиница, цифры, `_`; начинается с бук
|
||||
3. QuickJS + mermaid.js (`mermaidx`) — офлайн без браузера
|
||||
4. Локальный Kroki → `https://kroki.io` (если `--diagram-fallback remote`)
|
||||
|
||||
Формат: `--diagram-format png` (по умолчанию) или `svg`. Масштаб растра PlantUML / локального Mermaid: `--diagram-scale` (по умолчанию 2 — качество, размер на странице как при 1).
|
||||
**IDEF0:** сразу Pillow (PNG, при `--diagram-format svg` ещё SVG). Java/Kroki не используются.
|
||||
|
||||
**DFD:**
|
||||
|
||||
1. [data-flow-diagram](https://github.com/pbauermeister/dfd) компилирует DSL → DOT
|
||||
2. Вшитый / кэш / PATH Graphviz (`dot`, для `style context` — `neato`)
|
||||
3. Локальный Kroki → `https://kroki.io` при `--diagram-fallback remote`
|
||||
|
||||
Формат: `--diagram-format png` (по умолчанию) или `svg`. Масштаб растра PlantUML / локального Mermaid / IDEF0: `--diagram-scale` (по умолчанию 2 — качество, размер на странице как при 1).
|
||||
|
||||
Кэш картинок: `{каталог_md}/.md2gost-cache/`.
|
||||
Кэш includes: `md2gost.include-cache.json` + папка `include-cache/` (сброс в GUI: Настройки → Диаграммы / Шаблоны UML).
|
||||
@@ -124,3 +268,5 @@ id схемы: латиница, цифры, `_`; начинается с бук
|
||||
1. Меню **Шаблоны UML** — добавить / править / сохранить.
|
||||
2. Или править `md2gost.schemes.json` вручную («Открыть JSON»).
|
||||
3. CLI: `--schemes путь.json`.
|
||||
|
||||
Чтобы правка встроенной схемы не сбрасывалась при обновлении приложения, оставьте пустой `author` (GUI делает это сама при сохранении изменённой встроенной схемы).
|
||||
|
||||
Reference in New Issue
Block a user