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

В отчёте блок кода с языком диаграммы превращается в **Рисунок** (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 делает это сама при сохранении изменённой встроенной схемы).