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

В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki) или Kroki для Mermaid.

## Синтаксис в 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 через Kroki |
| `` ```bpmn `` / `` ```uml-bpmn `` | BPMN 2.0 (макросы библиотеки md2gost) |

**IDEF0 / DFD** конвертер не рисует — вставляйте готовый PNG как обычный Рисунок.

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

Файл шаблона: [`md2gost/diagrams/schemes.json`](../md2gost/diagrams/schemes.json). При первом запуске копируется в `md2gost.schemes.json` рядом с приложением (существующий файл не перезаписывается).

| id | Название | Оградка |
|----|----------|---------|
| `c4` | C4 Container | `` ```uml-c4 `` / `` ```c4 `` |
| `c4context` | C4 Context | `` ```uml-c4context `` |
| `c4component` | C4 Component | `` ```uml-c4component `` |
| `usecase` | Прецеденты | `` ```uml-usecase `` / `` ```usecase `` |
| `bpmn` | BPMN 2.0 | `` ```bpmn `` / `` ```uml-bpmn `` |

Для схем в теле пишите **только макросы** (Person, Start, XOR, …) — без `@startuml` и без `!include`, если схема сама их добавляет.

### C4 (пример макросов)

`Person`, `System`, `System_Ext`, `Container`, `ContainerDb`, `Rel` / `Rel_R`…

### Use Case

`actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>`.

### BPMN

`Pool` / `Lane`, `Start` / `StartMessage` / `End`, `UserTask` / `ServiceTask`, `XOR` / `AND` / `OR`, `Flow` / `CondFlow` / `DefaultFlow` / `MessageFlow`, …

Sequence Flow только внутри пула; между пулами — `MessageFlow`.

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

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

```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** — только Kroki (шаги 2–3).

Формат: `--diagram-format png` (по умолчанию) или `svg`. Масштаб рендера PlantUML: `--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`.