md_to_gost/ai/context/diagrams.md

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

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

---

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

Диаграмма прецедентов приведена на @Рисунок: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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

ER-диаграмма

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

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

%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: контекст

%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: контейнеры

%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: компоненты

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

%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

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

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

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

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

%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 подпись	сигнал

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

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

```dfd
style context

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

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

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

%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     уведомление
```

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

---

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

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

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

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

---

9. Свои схемы

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

{
  "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.