hleb/md_to_gost
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8223e0ac14a01cc7c27016e0a0faf06f05d3d8da
md_to_gost/AI-Docs_WriteHuman/context/diagrams.md
T
Igor20264 8223e0ac14
Example document / build (push) Has been cancelled
Details
Python application / build (push) Has been cancelled
Details
v0.6.0 BigUpdate
2026-10-20 11:38:06 +03:00

24 KiB
Raw Blame History

Диаграммы в 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
```dfd-gs, ```gane-sarson DSL потоков данных (Гейн–Сарсон) локальный рендер (Pillow)

Правило про обёртку: в ```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     уведомление
```

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

Гейн–Сарсон

Оградка ```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.

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

%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 — ошибка. Стрелки не используются.

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

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

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

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

10. Свои схемы

Файл 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.

Reference in New Issue View Git Blame Copy Permalink