Igor20264
273 lines
13 KiB
Markdown
273 lines
13 KiB
Markdown
# Схемы и диаграммы
|
||
|
||
В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki), локальный Mermaid (браузер / QuickJS), локальный IDEF0 (Pillow) или DFD через [data-flow-diagram](https://github.com/pbauermeister/dfd) (вшитый / системный Graphviz или Kroki).
|
||
|
||
## Синтаксис в markdown
|
||
|
||
````markdown
|
||
%usecase1 Диаграмма прецедентов +listing
|
||
|
||
```uml
|
||
@startuml
|
||
actor Student
|
||
Student --> (Login)
|
||
@enduml
|
||
```
|
||
````
|
||
|
||
Широкая схема:
|
||
|
||
````markdown
|
||
%arch1 Архитектура +landscape
|
||
|
||
```uml-c4
|
||
Person(user, "Студент")
|
||
System(app, "Портал")
|
||
Rel(user, app, "логин")
|
||
```
|
||
````
|
||
|
||
| Оградка | Что происходит |
|
||
|---------|----------------|
|
||
| `` ```uml `` / `` ```plantuml `` | Сырой PlantUML (`@startuml`…`@enduml`) |
|
||
| `` ```uml-<id> `` / `` ```<id> `` | Схема из `md2gost.schemes.json` (обёртка и `!include` добавляются сами) |
|
||
| `` ```mermaid `` / `` ```mmd `` | Mermaid: браузер / QuickJS / Kroki |
|
||
| `` ```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` рядом с приложением. При каждом запуске встроенные схемы (`author: md2gost`) синхронизируются с шаблоном: новые id добавляются, устаревшие (например удалённый `bpmn`) убираются, содержимое обновляется. Схемы с пустым или другим `author` не трогаются. Если правите встроенную в GUI и сохраняете — `author` сбрасывается, чтобы миграция не затёрла правки.
|
||
|
||
| id | Название | Оградка |
|
||
|----|----------|---------|
|
||
| `c4` | C4 Container | `` ```uml-c4 `` / `` ```c4 `` |
|
||
| `c4context` | C4 Context | `` ```uml-c4context `` |
|
||
| `c4component` | C4 Component | `` ```uml-c4component `` |
|
||
| `usecase` | Прецеденты | `` ```uml-usecase `` / `` ```usecase `` |
|
||
| `archimate` | ArchiMate 3.2 | `` ```uml-archimate `` / `` ```archimate `` |
|
||
|
||
Для схем в теле пишите **только макросы** (Person, Rel, actor, Business_Actor, …) — без `@startuml` и без `!include`, если схема сама их добавляет.
|
||
|
||
### C4 (пример макросов)
|
||
|
||
`Person`, `System`, `System_Ext`, `Container`, `ContainerDb`, `Rel` / `Rel_R`…
|
||
|
||
### Use Case
|
||
|
||
`actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>`.
|
||
|
||
### ArchiMate 3.2
|
||
|
||
`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
|
||
{
|
||
"c4": {
|
||
"title": "C4 Container",
|
||
"docs": "…макросы…",
|
||
"ai-prompt": "…инструкция для ИИ…",
|
||
"includes": ["https://…/C4_Container.puml"],
|
||
"prefix": "@startuml\n",
|
||
"postfix": "\nLAYOUT_WITH_LEGEND()\n@enduml"
|
||
}
|
||
}
|
||
```
|
||
|
||
| Поле | Назначение |
|
||
|------|------------|
|
||
| `title` | Подпись в GUI |
|
||
| `docs` | Шпаргалка макросов |
|
||
| `ai-prompt` | Фрагмент для промпта ИИ |
|
||
| `includes` | Локальные `.puml` или URL |
|
||
| `prefix` / `postfix` | Обёртка вокруг тела |
|
||
| `theme` | опционально `!theme …` |
|
||
|
||
id схемы: латиница, цифры, `_`; начинается с буквы.
|
||
|
||
## Слои загрузки (позже побеждает)
|
||
|
||
1. Встроенный шаблон `md2gost/diagrams/schemes.json`
|
||
2. Пользовательский файл рядом с приложением (`md2gost.schemes.json`)
|
||
3. `md2gost.schemes.json` рядом с `.md`
|
||
4. Явный путь `--schemes path.json`
|
||
|
||
## Рендер
|
||
|
||
**UML / схемы:**
|
||
|
||
1. Java + `plantuml.jar` (вшитый / `%LOCALAPPDATA%\md2gost\` / `--plantuml-jar`)
|
||
2. Локальный Kroki (`KROKI_URL` / `--kroki-url`, по умолчанию `http://localhost:8000`)
|
||
3. `https://kroki.io` при `--diagram-fallback remote` (по умолчанию)
|
||
|
||
**Mermaid:**
|
||
|
||
1. Системный Chrome / Edge (через Playwright, ничего не качаем)
|
||
2. Playwright Chromium в `%LOCALAPPDATA%\md2gost\ms-playwright` — кнопка «Скачать headless Chromium» или `md2gost --install-chromium`
|
||
3. QuickJS + mermaid.js (`mermaidx`) — офлайн без браузера
|
||
4. Локальный Kroki → `https://kroki.io` (если `--diagram-fallback remote`)
|
||
|
||
**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).
|
||
|
||
## Свои схемы
|
||
|
||
1. Меню **Шаблоны UML** — добавить / править / сохранить.
|
||
2. Или править `md2gost.schemes.json` вручную («Открыть JSON»).
|
||
3. CLI: `--schemes путь.json`.
|
||
|
||
Чтобы правка встроенной схемы не сбрасывалась при обновлении приложения, оставьте пустой `author` (GUI делает это сама при сохранении изменённой встроенной схемы).
|