# Диаграммы в md2gost — справочник нотаций

Конвертер сам отрисовывает исходники диаграмм и вставляет их как Рисунок. Экспортировать схему в PNG вручную не нужно и вредно: картинка не пересобирается при правке.

---

## 1. Общие правила

```markdown
Диаграмма прецедентов приведена на @Рисунок:uc_main.

%uc_main Диаграмма прецедентов
```
…и сразу после — fenced-блок с исходником.

| Элемент | Правило |
|---------|---------|
| Метка и подпись | строка `%id Подпись` **перед** блоком |
| Ссылка в тексте | `@Рисунок:id` в предложении **до** блока |
| `id` | латиница, цифры, `_`; начинается с буквы; без дефисов |
| `+listing` в подписи | дополнительно выводит исходник схемы как Листинг со своим номером |
| `+landscape` в подписи | размещает рисунок на альбомной странице |

Подпись не должна содержать самостоятельных слов `listing` и `landscape` — они будут вырезаны как флаги.

Внутри блоков диаграмм типографская автозамена **не** работает, поэтому двойные кавычки и дефисы в синтаксисе схем сохраняются как есть. Это единственные защищённые блоки: в блоках кода кавычки заменяются.

---

## 2. Таблица оградок

| Оградка | Тело | Движок |
|---------|------|--------|
| ` ```uml `, ` ```plantuml ` | полный PlantUML с `@startuml` … `@enduml` | PlantUML |
| ` ```uml-c4 `, ` ```c4 ` | макросы C4 Container, без обёртки | PlantUML + stdlib C4 |
| ` ```uml-c4context ` | макросы C4 System Context | PlantUML + stdlib C4 |
| ` ```uml-c4component ` | макросы C4 Component | PlantUML + stdlib C4 |
| ` ```usecase `, ` ```uml-usecase ` | `actor`, `usecase`, связи, без обёртки | PlantUML |
| ` ```archimate `, ` ```uml-archimate ` | макросы ArchiMate 3.2, без обёртки | PlantUML + stdlib ArchiMate |
| ` ```mermaid `, ` ```mmd ` | синтаксис Mermaid | локальный Mermaid или Kroki |
| ` ```idef0 `, ` ```uml-idef0 ` | DSL IDEF0 | локальный рендер (Pillow) |
| ` ```dfd `, ` ```uml-dfd `, ` ```data-flow-diagram `, ` ```yourdon ` | DSL потоков данных (Йордон) | Graphviz или Kroki |
| ` ```dfd-gs `, ` ```gane-sarson ` | DSL потоков данных (Гейн–Сарсон) | локальный рендер (Pillow) |

Правило про обёртку: в ` ```uml ` пишешь `@startuml` … `@enduml` **обязательно**; в схемах (`c4`, `usecase`, `archimate` и любых из `md2gost.schemes.json`) — **никогда**, схема подставит обёртку и `!include` сама.

---

## 3. PlantUML: готовые каркасы

### Диаграмма прецедентов

~~~markdown
%uc_main Диаграмма прецедентов системы

```uml
@startuml
left to right direction
skinparam packageStyle rectangle

actor "Студент" as student
actor "Преподаватель" as teacher
actor "Администратор" as admin

rectangle "Портал заявок" {
  usecase "Подать заявку" as UC1
  usecase "Проверить статус" as UC2
  usecase "Согласовать заявку" as UC3
  usecase "Аутентифицироваться" as UC4
  usecase "Управлять справочниками" as UC5
}

student --> UC1
student --> UC2
teacher --> UC3
admin --> UC5
UC1 ..> UC4 : <<include>>
UC3 ..> UC4 : <<include>>
@enduml
```
~~~

### Диаграмма классов

~~~markdown
%class_domain Диаграмма классов предметной области

```uml
@startuml
skinparam classAttributeIconSize 0

class Request {
  - id: int
  - createdAt: datetime
  - status: Status
  + submit(): void
  + cancel(): void
}

class Client {
  - id: int
  - name: str
  - inn: str
}

enum Status {
  NEW
  IN_PROGRESS
  DONE
}

class RequestService {
  + create(client: Client): Request
  + close(request: Request): void
}

Client "1" *-- "0..*" Request
Request --> Status
RequestService ..> Request
@enduml
```
~~~

### Диаграмма последовательности

~~~markdown
%seq_submit Последовательность обработки заявки

```uml
@startuml
autonumber
actor Студент as s
participant "Веб-клиент" as web
participant "Сервис заявок" as api
database "PostgreSQL" as db

s -> web : заполняет форму
web -> api : POST /requests
api -> db : INSERT request
db --> api : id
api --> web : 201 Created
web --> s : номер заявки
@enduml
```
~~~

### Диаграмма деятельности

~~~markdown
%act_flow Алгоритм обработки заявки

```uml
@startuml
start
:Принять заявку;
if (Данные полные?) then (да)
  :Зарегистрировать;
  :Назначить исполнителя;
else (нет)
  :Вернуть на доработку;
  stop
endif
:Исполнить заявку;
:Уведомить клиента;
stop
@enduml
```
~~~

### Диаграмма состояний

~~~markdown
%state_req Состояния заявки

```uml
@startuml
[*] --> Новая
Новая --> ВРаботе : назначен исполнитель
ВРаботе --> Исполнена : работы завершены
ВРаботе --> Отклонена : отказ
Исполнена --> [*]
Отклонена --> [*]
@enduml
```
~~~

### ER-диаграмма

~~~markdown
%erd_main Логическая модель данных

```uml
@startuml
hide circle
skinparam linetype ortho

entity "Клиент" as client {
  * id : bigint <<PK>>
  --
  * name : varchar(255)
  inn : varchar(12)
}

entity "Заявка" as request {
  * id : bigint <<PK>>
  --
  * client_id : bigint <<FK>>
  * created_at : timestamp
  * status : varchar(32)
}

entity "Позиция заявки" as item {
  * id : bigint <<PK>>
  --
  * request_id : bigint <<FK>>
  * product : varchar(255)
  * qty : int
}

client ||--o{ request
request ||--o{ item
@enduml
```
~~~

### Диаграмма компонентов и развёртывания

~~~markdown
%deploy_prod Схема развёртывания

```uml
@startuml
node "Сервер приложений" {
  component "API заявок" as api
  component "Планировщик" as sched
}
node "Сервер БД" {
  database "PostgreSQL" as db
}
node "Рабочее место" {
  component "Браузер" as browser
}

browser --> api : HTTPS
api --> db : SQL
sched --> db : SQL
@enduml
```
~~~

---

## 4. C4

Три уровня — три оградки. В теле только макросы; обёртка и `!include` добавляются схемой.

### Уровень 1: контекст

~~~markdown
%c4ctx Диаграмма контекста системы

```uml-c4context
Person(student, "Студент", "Подаёт заявки и отслеживает статус")
Person(staff, "Сотрудник деканата", "Обрабатывает заявки")
System(portal, "Портал заявок", "Приём и обработка заявок студентов")
System_Ext(sso, "Корпоративный SSO", "Единая аутентификация")
System_Ext(mail, "Почтовый сервис", "Уведомления")

Rel(student, portal, "Подаёт заявку", "HTTPS")
Rel(staff, portal, "Обрабатывает заявки", "HTTPS")
Rel(portal, sso, "Аутентифицирует пользователей", "OIDC")
Rel(portal, mail, "Отправляет уведомления", "SMTP")
```
~~~

### Уровень 2: контейнеры

~~~markdown
%c4cont Диаграмма контейнеров +landscape

```uml-c4
Person(student, "Студент", "Подаёт заявки")
System_Boundary(portal, "Портал заявок") {
  Container(spa, "Веб-приложение", "React", "Интерфейс пользователя")
  Container(api, "Сервис заявок", "FastAPI", "Бизнес-логика и валидация")
  Container(worker, "Обработчик очереди", "Python", "Асинхронные задачи")
  ContainerDb(db, "Основная БД", "PostgreSQL", "Заявки, клиенты, история")
  ContainerDb(queue, "Очередь", "RabbitMQ", "Задачи на обработку")
}
System_Ext(sso, "Корпоративный SSO", "Аутентификация")

Rel(student, spa, "Работает с заявками", "HTTPS")
Rel(spa, api, "Вызывает методы", "REST/JSON")
Rel(api, db, "Читает и пишет", "SQL")
Rel(api, queue, "Публикует задачи", "AMQP")
Rel(worker, queue, "Читает задачи", "AMQP")
Rel(worker, db, "Обновляет статусы", "SQL")
Rel(spa, sso, "Аутентифицируется", "OIDC")
```
~~~

### Уровень 3: компоненты

~~~markdown
%c4comp Компоненты сервиса заявок

```uml-c4component
Container_Boundary(api, "Сервис заявок") {
  Component(ctrl, "Контроллер заявок", "FastAPI Router", "Обработка HTTP-запросов")
  Component(svc, "Служба заявок", "Python", "Правила обработки и переходы статусов")
  Component(repo, "Репозиторий заявок", "SQLAlchemy", "Доступ к данным")
  Component(auth, "Модуль авторизации", "Python", "Проверка прав по роли")
}
ContainerDb(db, "Основная БД", "PostgreSQL", "Заявки и клиенты")

Rel(ctrl, auth, "Проверяет права")
Rel(ctrl, svc, "Вызывает")
Rel(svc, repo, "Читает и пишет")
Rel(repo, db, "SQL-запросы")
```
~~~

### Основные макросы C4

| Макрос | Назначение |
|--------|------------|
| `Person(alias, "Имя", "Описание")` | пользователь-человек |
| `Person_Ext(...)` | внешний пользователь |
| `System(alias, "Имя", "Описание")` | система целиком |
| `System_Ext(...)` | внешняя система |
| `System_Boundary(alias, "Имя") { … }` | граница системы |
| `Container(alias, "Имя", "Технология", "Описание")` | контейнер |
| `ContainerDb(...)`, `ContainerQueue(...)` | база данных, очередь |
| `Container_Boundary(alias, "Имя") { … }` | граница контейнера |
| `Component(alias, "Имя", "Технология", "Описание")` | компонент |
| `Rel(from, to, "Действие", "Технология")` | связь |
| `Rel_U/D/L/R(...)` | связь с направлением раскладки |
| `LAYOUT_WITH_LEGEND()`, `LAYOUT_TOP_DOWN()`, `LAYOUT_LEFT_RIGHT()` | раскладка |

Правила качества: описания на русском, технологии — как принято (`PostgreSQL`, `React`); один уровень абстракции на диаграмму; 6–15 элементов; связи подписаны действием, а не «использует».

---

## 5. Mermaid

Идёт через локальный рендер (системный Chrome/Edge, Playwright Chromium или QuickJS) либо через Kroki.

~~~markdown
%mmd_flow Схема процесса согласования

```mermaid
flowchart TD
    A[Заявка поступила] --> B{Данные полные?}
    B -- да --> C[Регистрация]
    B -- нет --> D[Возврат на доработку]
    C --> E[Назначение исполнителя]
    E --> F[Исполнение]
    F --> G[Уведомление клиента]
    D --> A
```
~~~

Поддерживаются `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `gantt`, `journey`, `pie`. Для отчёта по ГОСТ надёжнее PlantUML: Mermaid требует браузера или сети.

---

## 6. IDEF0 (FIPS 183)

Оградка ` ```idef0 `. Тело — не XML и не PlantUML, а собственный DSL. Рендер локальный, Java и сеть не нужны.

### Шапка формы

| Ключ | Значение |
|------|----------|
| `title` | название диаграммы |
| `node` | узел: `A-0`, `A0`, `A1` |
| `number` | номер листа |
| `author`, `project`, `date`, `rev` | поля NIST-формы |
| `status` | `WORKING`, `DRAFT`, `RECOMMENDED`, `PUBLICATION` |
| `context` | `TOP` для контекстной A-0, иначе родительский узел |
| `purpose`, `viewpoint` | цель и точка зрения модели |
| `used_at`, `reader`, `reader_date`, `notes`, `page` | необязательные поля формы |
| `form` | `kit` (по умолчанию, с рамкой) или `plain` |

### Боксы и стрелки

| Запись | Смысл |
|--------|-------|
| `[A0] Имя функции` или `box A0 Имя` | бокс функции |
| `<- Название` или `in` | вход (слева) |
| `^ Название` или `control` | управление (сверху) |
| `-> Название` или `out` | выход (справа) |
| `v Название` или `mech` | механизм (снизу) |
| `A1 <- Заявка [I1]` | явное указание бокса и код ICOM |
| `A1 -> A2 : план закупок` | внутренняя связь между боксами |
| `A1 -> A2.C : график` | связь в конкретный порт (`.I`, `.C`, `.O`, `.M`) |
| `A1, A2, A3 ^ Регламент [C1]` | одна стрелка в несколько боксов |
| `(in Секрет` | туннель на границе листа |
| `in) Локальный` | туннель у бокса |
| `call ИмяМодели` | вызов другой модели |

Стрелки без явного бокса относятся к последнему объявленному боксу.

### Контекстная диаграмма A-0

~~~markdown
%idef_a0 Контекстная диаграмма A-0

```idef0
title Распорядиться товаром
node A-0
number 1
author Иванов И. И.
project Модель торгового предприятия
date 08.02.2026
status PUBLICATION
context TOP

[A0] Распорядиться товаром
<- Спрос
^ Нормативная документация
-> Товар
v Персонал
```
~~~

### Декомпозиция A0

~~~markdown
%idef_a0d Декомпозиция A0

```idef0
title Распорядиться товаром
node A0
number 2
author Иванов И. И.
project Модель торгового предприятия
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]
```
~~~

Правила нотации: контекстная диаграмма — ровно один бокс; в декомпозиции 3–6 боксов «лесенкой» слева-сверху вниз-вправо; подписи стрелок — существительные; управление приходит сверху, механизм снизу.

---

## 7. DFD (диаграммы потоков данных)

Оградка ` ```dfd `. Синтаксис пакета `data-flow-diagram`. Рендер через Graphviz (вшитый, из `PATH` или скачанный) либо Kroki.

### Узлы и потоки

| Ключевое слово | Смысл |
|----------------|-------|
| `process Имя Подпись` | процесс |
| `entity Имя Подпись` | внешняя сущность |
| `store Имя Подпись` | хранилище данных |
| `control Имя Подпись` | элемент управления |
| `channel Имя Подпись` | канал |
| `style context` | оформление контекстной диаграммы |

| Поток | Смысл |
|-------|-------|
| `A --> B подпись` | поток данных |
| `A ->> B подпись` | двойной поток |
| `A <-> B подпись` | двунаправленный |
| `A ::> B подпись` | сигнал |

### Контекстная диаграмма

~~~markdown
%dfd_ctx Контекстная диаграмма потоков данных

```dfd
style context

entity   Client     Клиент
entity   Warehouse  Склад
process  System     Система учёта заявок

Client  -->  System     заявка
System  -->  Client     статус заявки
System  -->  Warehouse  накладная
```
~~~

### Диаграмма нулевого уровня

~~~markdown
%dfd_l0 Диаграмма потоков данных нулевого уровня

```dfd
entity   Client     Клиент
entity   Warehouse  Склад
process  Accept     Принять заявку
process  Register   Зарегистрировать заявку
process  Ship       Сформировать накладную
store    Orders     Заявки
store    Log        Журнал операций

Client    -->  Accept     заявка
Accept    -->  Orders     новая заявка
Orders    -->  Register   данные заявки
Register  -->  Log        запись об изменении
Register  -->  Ship       подтверждённая заявка
Ship      -->  Warehouse  накладная
Ship      -->  Client     уведомление
```
~~~

Правила нотации: на контекстной диаграмме один процесс; хранилища не соединяются напрямую с внешними сущностями; каждый процесс имеет и вход, и выход.

### Гейн–Сарсон

Оградка ` ```dfd-gs ` (то же: ` ```gane-sarson `, ` ```uml-dfd-gs `). Те же `entity` / `process` / `store` и `A --> B подпись`, но фигуры другие: сущность — прямоугольник с тенью и номером, процесс — скруглённый прямоугольник с номером внизу справа, хранилище — прямоугольник с полосой и кодом `D1`. Рендер локальный, Graphviz не нужен.

Номер процесса — сам id, если это `1` или `3.1`, иначе порядок объявления. Код хранилища — id вида `D2`, иначе `D1`, `D2`, … по порядку. У сущности номер в углу — порядок объявления.

Шапка листа, как у Ramus: `title`, `node`, `number`, `author`, `project`, `date`, `rev`, `status`, `used_at`. `form kit` (по умолчанию, со штампом) или `form plain`.

Раскладка сама: сущности слева, процессы в центре, хранилища справа. Стрелка между соседними колонками идёт по зазору. Координат в тексте нет.

~~~markdown
%dfd_gs Приёмка работы

```dfd-gs
title Зафиксировать решение приёмки
node A44
number 1
author Иванов И. И.
project ИС ArtFreelance

entity Artist Художник
process 1 Принять файлы результата
store D2 Файлы работ

Artist --> 1 файлы работы
1 --> D2 превью и хеш
```
~~~

---

## 8. Что нужно для отрисовки

| Нотация | Требования | Запасной вариант |
|---------|------------|------------------|
| PlantUML, C4, ArchiMate, Use Case | Java и `plantuml.jar` (вшит в exe-сборку) | локальный Kroki, затем `kroki.io` при `--diagram-fallback remote` |
| Mermaid | системный Chrome или Edge; либо скачанный Chromium; либо QuickJS | Kroki |
| IDEF0 | ничего, локальный рендер | не требуется |
| DFD (Йордон, ` ```dfd `) | Graphviz (вшитый, из `PATH` или кнопка «Скачать Graphviz») | Kroki |
| DFD Гейна–Сарсона (` ```dfd-gs `) | ничего, локальный рендер | не требуется |

Ключи: `--plantuml-jar`, `--kroki-url`, `--diagram-fallback local|remote|off`, `--diagram-format png|svg`, `--diagram-scale N` (по умолчанию 2 — качество растра).

Кэш готовых картинок — каталог `.md2gost-cache` рядом с `.md`; при правке исходника схемы картинка пересобирается автоматически.

---

## 9. Иерархическая оргсхема и читаемость

Рисунок, который нельзя прочитать при масштабе 100 % в Word, при проверке равен отсутствию рисунка. Широкие схемы помечай `+landscape`. Кегль подписей после вставки на лист — не меньше 10–11 пт. Если встроенный PlantUML или Mermaid даёт мелкую схему, сдавай PNG высокого разрешения.

На оргмодели из одного узла выходит **одна** связь, затем развязка на подчинённых (горизонтальная шина). Пачка независимых линий `ceo -- a`, `ceo -- b`, `ceo -- c` — ошибка. Стрелки не используются.

У каждого показанного отдела есть руководитель и специалисты операционного уровня. Нельзя оставлять бокс направления с одним специалистом или без людей. Должности обезличены.

Каркас развязки:

```text
            [Родитель]
                 |
        ---------+---------
        |        |        |
     [Доч.1]  [Доч.2]  [Доч.3]
```

Карта процессов верхнего уровня — группы без стрелок последовательности.

## 10. Свои схемы

Файл `md2gost.schemes.json` (рядом с приложением, рядом с `.md` или путь в `--schemes`) задаёт новые оградки:

```json
{
  "bpmn_like": {
    "title": "Процессная схема",
    "docs": "Шпаргалка макросов для подсказки в интерфейсе",
    "ai-prompt": "Фрагмент, который дописывается в промпт для ИИ",
    "includes": ["https://example.org/macros.puml"],
    "prefix": "@startuml\n",
    "postfix": "\n@enduml",
    "theme": ""
  }
}
```

`id` схемы: строчная латиница, цифры, `_`, начинается с буквы. После добавления доступны оградки ` ```bpmn_like ` и ` ```uml-bpmn_like `; в теле пишутся только макросы.

Слои загрузки, где каждый следующий сильнее: встроенный шаблон → файл рядом с приложением → файл рядом с `.md` → `--schemes`.