md_to_gost/docs/schemes.md

Схемы и диаграммы

В отчёте блок кода с языком диаграммы превращается в Рисунок (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki), локальный Mermaid (браузер / QuickJS), локальный IDEF0 (Pillow) или DFD через data-flow-diagram (вшитый / системный Graphviz или Kroki).

Синтаксис в markdown

%usecase1 Диаграмма прецедентов +listing

```uml
@startuml
actor Student
Student --> (Login)
@enduml
```

Широкая схема:

%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): вшитый Graphviz / PATH / Kroki

Встроенные схемы

Файл шаблона: 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.

Полные шпаргалки — поля docs и ai-prompt в JSON; в GUI: Шаблоны UML и кнопки схем в Справка → Промпт для ИИ.

IDEF0 (FIPS 183)

Оградка ```idef0 (то же: ```uml-idef0). Текст — не XML: шапка формы, боксы, стрелки ICOM (Input слева, Control сверху, Output справа, Mechanism снизу). Контекст A-0 — один бокс; декомпозиция — несколько боксов «лесенкой» и связи между ними. Рендер локальный (Pillow), без Java и Kroki.

%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 на рамке):

%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 (ставится с 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

%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.

Декомпозиция (уровень 0):

%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.

Файл схем: поля

{
  "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 компилирует 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 делает это сама при сохранении изменённой встроенной схемы).