update 0.4.4

- update документация - промт для ии полу конфигурируемый
2026-09-06 11:04:01 +03:00
parent 638fd38d7f
commit 818a044aa1
26 changed files with 1987 additions and 457 deletions
@@ -0,0 +1,121 @@
+# Схемы и диаграммы
+
+В отчёте блок кода с языком диаграммы превращается в **Рисунок** (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`.