v0.5.3

- Мелкие исправления увеличивающие работу конвертера

ai/context/diagrams.md

@@ -0,0 +1,567 @@
+# Диаграммы в 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 |
+
+Правило про обёртку: в ` ```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     уведомление
+```
+~~~
+
+Правила нотации: на контекстной диаграмме один процесс; хранилища не соединяются напрямую с внешними сущностями; каждый процесс имеет и вход, и выход.
+
+---
+
+## 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`) задаёт новые оградки:
+
+```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`.