v0.5.4
NewPromt - small fix
This commit is contained in:
Igor20264
+154
@@ -0,0 +1,154 @@
|
|||||||
|
# AIV2/ — промпты и документация для нейросетей
|
||||||
|
|
||||||
|
Исправленная копия набора `ai/`. Добавлены правила, которые `--check` не ловит, а преподаватель — да: собственно-научный стиль, запрет «Практическая работа» в названии пункта, полное наименование до аббревиатуры, группировка ссылок `[1, 2]`, запрет таблицы реквизитов, читаемые иерархические схемы, границы пунктов задания, критический разбор фрагмента **до** сдачи следующей практики.
|
||||||
|
|
||||||
|
**Главное правило: файл из `AIV2/prompts/` — это целиком промпт.** В нём нет ни заголовка «скопируйте текст ниже», ни разделителей, ни инструкций для человека. Открыл файл, выделил всё, вставил в модель — работает. Инструкции для человека живут только в этом README.
|
||||||
|
|
||||||
|
Файлы из `AIV2/context/` — справочники: их дают модели как дополнительный контекст, когда нужна точность в узком месте. Файлы из `AIV2/examples/` — эталонные документы, проходящие проверку `--check` без замечаний; их дают как образец.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Что где лежит
|
||||||
|
|
||||||
|
### `AIV2/prompts/` — готовые к вставке промпты
|
||||||
|
|
||||||
|
| Файл | Когда брать | Размер |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| [`core-md2gost.md`](prompts/core-md2gost.md) | нужен просто markdown в диалекте md2gost, без привязки к типу учебной работы | 12 тыс. знаков |
|
||||||
|
| [`report-mirea.md`](prompts/report-mirea.md) | отчёт по практике, курсовая, ВКР (`practice`, `coursework`, `vkr`) | 12 тыс. знаков |
|
||||||
|
| [`report-apid.md`](prompts/report-apid.md) | курсовая «Архитектура приложений и данных» (`APID_coursework`) | 10 тыс. знаков |
|
||||||
|
| [`report-pis.md`](prompts/report-pis.md) | итоговый отчёт по практическим работам (`PIS_custom`), если бланк требует «Практическая работа №N» | 7 тыс. знаков |
|
||||||
|
| [`report-paco.md`](prompts/report-paco.md) | нарастающий отчёт ПАЦО и аналоги (`practice`): пункты `# 1 …` без слов «Практическая работа» | 9 тыс. знаков |
|
||||||
|
| [`voice-human.md`](prompts/voice-human.md) | добавка: текст про предмет, а не отчёт модели; для практик не отменяет собственно-научный стиль | 5 тыс. знаков |
|
||||||
|
| [`review-fix.md`](prompts/review-fix.md) | есть готовый `.md`, надо починить его под ТЗ (в том числе по выводу `--check`) | 8 тыс. знаков |
|
||||||
|
| [`from-word.md`](prompts/from-word.md) | есть результат импорта `word2md`, надо довести до диалекта | 6 тыс. знаков |
|
||||||
|
|
||||||
|
Промпты самодостаточны: правила диалекта в них повторяются намеренно, чтобы каждый работал в одиночку.
|
||||||
|
|
||||||
|
### `AIV2/context/` — справочники для догрузки
|
||||||
|
|
||||||
|
| Файл | О чём | Размер |
|
||||||
|
|------|-------|--------|
|
||||||
|
| [`syntax.md`](context/syntax.md) | полная спецификация диалекта: регулярные выражения, приоритеты, подводные камни | 16 тыс. знаков |
|
||||||
|
| [`diagrams.md`](context/diagrams.md) | все нотации схем с готовыми каркасами: PlantUML, C4, Mermaid, IDEF0, DFD | 16 тыс. знаков |
|
||||||
|
| [`archimate.md`](context/archimate.md) | ArchiMate 3.2: макросы элементов и связей, направления, viewpoints, шаблоны | 22 тыс. знаков |
|
||||||
|
| [`checker.md`](context/checker.md) | каталог замечаний `--check` с текстами сообщений и способами починки | 10 тыс. знаков |
|
||||||
|
| [`cli.md`](context/cli.md) | все ключи запуска, профили типов, конфигурационные файлы, оформление | 12 тыс. знаков |
|
||||||
|
| [`academic-style.md`](context/academic-style.md) | собственно-научный стиль, заголовки пунктов, аббревиатуры, ссылки `[1, 2]`, границы пунктов | 8 тыс. знаков |
|
||||||
|
| [`org-hierarchy.md`](context/org-hierarchy.md) | читаемость рисунка, развязка коннектора, полнота отдела (руководитель + специалисты) | 6 тыс. знаков |
|
||||||
|
|
||||||
|
### `AIV2/examples/` — эталоны
|
||||||
|
|
||||||
|
| Файл | Тип | Что демонстрирует |
|
||||||
|
|------|-----|-------------------|
|
||||||
|
| [`coursework.md`](examples/coursework.md) | `coursework` | полная структура, IDEF0, C4, ER-диаграмма, объединение ячеек, формула, листинг, два приложения, шесть источников |
|
||||||
|
| [`pis-report.md`](examples/pis-report.md) | `PIS_custom` | четыре практические работы, DFD, IDEF0, сквозные метки, расчёт нагрузки |
|
||||||
|
|
||||||
|
Оба файла проверены: `--check-only` не даёт ни одного замечания, сборка DOCX проходит на локальном рендере без интернета.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Рецепты
|
||||||
|
|
||||||
|
Что вставлять в модель под конкретную задачу.
|
||||||
|
|
||||||
|
| Задача | Что даёшь модели |
|
||||||
|
|--------|------------------|
|
||||||
|
| Сгенерировать курсовую или отчёт по практике | `prompts/report-mirea.md` → вторым сообщением `prompts/voice-human.md` → третьим сообщением входные данные |
|
||||||
|
| То же, но нужен упор на схемы | добавь `context/diagrams.md` перед входными данными |
|
||||||
|
| Курсовая АПИД | `prompts/report-apid.md` + `prompts/voice-human.md` + при необходимости `context/archimate.md` |
|
||||||
|
| Отчёт по практическим работам ПИС | `prompts/report-pis.md` + входные данные |
|
||||||
|
| Нарастающий отчёт ПАЦО (пункты задания, не «Практическая работа») | `prompts/report-paco.md` + `context/academic-style.md` + `context/org-hierarchy.md` + входные данные |
|
||||||
|
| Дописать раздел в существующий отчёт | `prompts/core-md2gost.md` + `prompts/voice-human.md` + текущий `.md` целиком + что дописать |
|
||||||
|
| Починить файл по замечаниям проверки | `prompts/review-fix.md` + вывод `--check` + `.md` целиком |
|
||||||
|
| Довести импорт из Word | `prompts/from-word.md` + результат `word2md` |
|
||||||
|
| Нарисовать одну схему | `context/diagrams.md` (или `context/archimate.md`) + описание того, что надо изобразить |
|
||||||
|
| Разобраться, почему конвертер ругается | `context/checker.md` + текст ошибки |
|
||||||
|
| Модель путается в синтаксисе | добавь `context/syntax.md` |
|
||||||
|
| Нужен образец «как должно выглядеть» | добавь `examples/coursework.md` |
|
||||||
|
|
||||||
|
Если контекст модели ограничен, порядок приоритета такой: промпт → входные данные → эталон → справочник. Справочник — первое, чем можно пожертвовать.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Шаблон входных данных
|
||||||
|
|
||||||
|
Следующим сообщением после промпта дай модели заполненный блок:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Тип работы: coursework
|
||||||
|
Тема: Разработка модуля учёта заявок на техническое обслуживание
|
||||||
|
Год сдачи: 2026
|
||||||
|
Дисциплина: Проектирование информационных систем
|
||||||
|
|
||||||
|
Объект: процесс приёма и исполнения заявок на обслуживание оборудования
|
||||||
|
Что уже известно:
|
||||||
|
- склад обрабатывает около 400 отгрузок в сутки
|
||||||
|
- заявки принимаются по телефону, фиксируются в электронных таблицах
|
||||||
|
- нужна интеграция со справочником оборудования по REST
|
||||||
|
|
||||||
|
Требования руководителя:
|
||||||
|
- обязательны диаграмма прецедентов и модель данных
|
||||||
|
- три раздела основной части
|
||||||
|
|
||||||
|
Литература: если есть свой список — приведи его здесь; иначе модель подберёт сама
|
||||||
|
Черновик: приложи имеющийся текст, если он есть
|
||||||
|
```
|
||||||
|
|
||||||
|
Чем конкретнее «что уже известно», тем меньше выдумок в тексте. Числа, названия и ограничения — самое ценное, что можно дать.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Полный цикл работы
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Сохранить ответ модели как report.md
|
||||||
|
|
||||||
|
# 2. Проверить по ТЗ
|
||||||
|
python -m md2gost report.md --check-only --type coursework
|
||||||
|
|
||||||
|
# 3. Если есть замечания — отдать их модели вместе с файлом
|
||||||
|
# и промптом ai/prompts/review-fix.md, сохранить результат, вернуться к шагу 2
|
||||||
|
|
||||||
|
# 4. Собрать документ
|
||||||
|
python -m md2gost report.md -o report.docx --type coursework --check --strict
|
||||||
|
|
||||||
|
# 5. Проверить вёрстку готового файла (Windows + Word + pywin32)
|
||||||
|
python -m md2gost report.docx --check-pages
|
||||||
|
```
|
||||||
|
|
||||||
|
Автотитул при необходимости: положить рядом `info_conv.yaml`, добавить в начало `.md` блок ` ```title ` с номером работы и годом, запустить с `--auto-title --student "…" --group "…"`. Подробности — в [`context/cli.md`](context/cli.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Куда вставлять промпт
|
||||||
|
|
||||||
|
| Инструмент | Куда |
|
||||||
|
|------------|------|
|
||||||
|
| ChatGPT, Claude | системная инструкция проекта либо первое сообщение диалога |
|
||||||
|
| Cursor | правила для ИИ, либо первое сообщение агенту |
|
||||||
|
| GitHub Copilot Chat | контекст чата |
|
||||||
|
| API | роль `system` |
|
||||||
|
|
||||||
|
Промпты рассчитаны на модель с рассуждением и длинным контекстом: они содержат чек-листы самопроверки, которые слабые модели игнорируют. Если результат не проходит `--check` с первого раза — это нормальный рабочий цикл, для него и сделан `review-fix.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Что модель делать не должна
|
||||||
|
|
||||||
|
Проверка `--check` не ловит фактические ошибки и выдуманные источники. Перед сдачей обязательно вычитай:
|
||||||
|
|
||||||
|
- **список литературы** — модели склонны придумывать издания, ISBN и число страниц. Промпты запрещают это прямо, но проверять всё равно нужно;
|
||||||
|
- **числа и названия** — если ты их не давал, модель их сочинила;
|
||||||
|
- **соответствие теме** — структура может быть безупречной при пустом содержании;
|
||||||
|
- **стиль и схемы** — публицистика, `[1], [2]`, таблица реквизитов, нечитаемая оргсхема и материал не из своего пункта `--check` не ловит; сверяй `academic-style.md` и `org-hierarchy.md`. Для следующих практик этот разбор делается до сдачи.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Отношение к остальному репозиторию
|
||||||
|
|
||||||
|
Каталоги `docs/` и `prompts/` в корне репозитория остаются как есть: на них ссылается встроенная справка приложения (**Справка → Документация**, **Справка → Промпт для ИИ**). Каталог `AIV2/` — исправленный набор относительно `ai/`; в приложение ничего не ломает.
|
||||||
|
|
||||||
|
Для отчётов ПАЦО не используй `ai/prompts/report-pis.md` как основной промпт: он заставляет писать «Практическая работа №N» и дробить пункт на «Цель / Ход / Выводы».
|
||||||
|
|
||||||
|
Источник истины по возможностям конвертера — код в `md2gost/`; справочники в `AIV2/context/` собраны по нему, а не по старой документации.
|
||||||
@@ -0,0 +1,115 @@
|
|||||||
|
# Собственно-научный стиль отчёта по практикам
|
||||||
|
|
||||||
|
Справочник для модели: как писать текст отчёта, чтобы он проходил проверку преподавателя по содержанию, а не только `--check` по разметке. Извлечено из типовых замечаний к отчётам ПАЦО / проектным практикам.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Подстиль
|
||||||
|
|
||||||
|
Текст отчёта — **собственно-научный подстиль** русского научного стиля (как в отчёте о НИР, ГОСТ 7.32). Это не публицистика, не консультантский слайд и не набор тезисов.
|
||||||
|
|
||||||
|
Допустимо: безличные конструкции, термины, факты, ссылки, причинно-следственные формулировки («обусловлено», «определяется», «характеризуется»).
|
||||||
|
|
||||||
|
Недопустимо:
|
||||||
|
|
||||||
|
| Запрещённый приём | Пример | Как заменить |
|
||||||
|
|-------------------|--------|--------------|
|
||||||
|
| Метафора и давление | «ручная проверка давит на маржу» | «трудоёмкость ручной проверки комплектов увеличивает операционные издержки» |
|
||||||
|
| Разговорный вектор | «социальные факторы тянут к…» | «в социальной среде наблюдается спрос на…» |
|
||||||
|
| Лозунг с “зато” | «платформа усложняется, зато сведения можно сверять автоматически» | «развитие программных интерфейсов реестров создаёт возможность автоматической сверки сведений» |
|
||||||
|
| Живая разговорность | «экосистема растёт», «общество тянет массу группы», «нет смысла в отделе» | нейтральная констатация факта |
|
||||||
|
| Тезисная рубка | «Экономические факторы — спрос. Социальные — Госключ. Технологические — облако.» | связные абзацы, каждый фактор раскрыт предложением |
|
||||||
|
| Мета про сдачу | «сформирована характеристика объекта» | содержание объекта, а не факт выполнения пункта |
|
||||||
|
|
||||||
|
Проверка абзаца: его можно поставить в отчёт о НИР без ощущения статьи или презентации. Если нет — переписать.
|
||||||
|
|
||||||
|
«Живой голос» из `voice-human.md` означает конкретику и отсутствие мета-чеклиста модели. Он **не** означает публицистические глаголы и антитезы.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Заголовки пунктов практики
|
||||||
|
|
||||||
|
Если задание называет пункт «Характеристика объекта исследования» — заголовок раздела:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 1 Характеристика объекта исследования
|
||||||
|
```
|
||||||
|
|
||||||
|
**Нельзя** писать `# Практическая работа 1 …` и `# Практическая работа №1. …`, если руководитель прямо потребовал убрать слова «Практическая работа» из названия пункта.
|
||||||
|
|
||||||
|
Профиль `PIS_custom` в `--check` как раз требует «Практическая работа №N. …». Для отчётов ПАЦО с нумерованными пунктами задания собирай документ как `--type practice` (или `coursework`), а не `PIS_custom`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Подпункты
|
||||||
|
|
||||||
|
Не дроби один пункт задания на искусственные `##` («Юридический статус», «Специфика», «Организационная модель» и т. п.), если преподаватель запретил лишние подразделы.
|
||||||
|
|
||||||
|
Один пункт задания = один H1 (или один нумерованный раздел). Смена темы внутри пункта — новый абзац, а не новый заголовок. Рисунок и таблица сами членят текст.
|
||||||
|
|
||||||
|
Подразделы `##` оставляй только если их явно требует бланк задания или профиль `--check` (цель / ход / выводы в `PIS_custom`; фиксированные `## 2.1` в АПИД).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Полное наименование, затем сокращение
|
||||||
|
|
||||||
|
При **первом** появлении в тексте:
|
||||||
|
|
||||||
|
1. полное официальное наименование;
|
||||||
|
2. затем сокращение или аббревиатура в скобках, при необходимости с «далее —».
|
||||||
|
|
||||||
|
```text
|
||||||
|
Акционерное общество «Производственная фирма «СКБ Контур» (далее — АО «ПФ «СКБ Контур») является акционерным обществом частной формы собственности…
|
||||||
|
электронный документооборот (ЭДО)
|
||||||
|
удостоверяющий центр (УЦ)
|
||||||
|
машиночитаемая доверенность (МЧД)
|
||||||
|
```
|
||||||
|
|
||||||
|
Дальше по тексту — только принятое сокращение. Не начинай документ с аббревиатуры, которую ещё не ввели. Не вводи одно и то же сокращение дважды.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Таблица реквизитов
|
||||||
|
|
||||||
|
Реквизиты юридического лица (наименование, ИНН, ОГРН, адрес, директор, капитал) **не оформлять таблицей «Реквизит / Значение»**. Значимые сведения из такой таблицы переносятся в связный абзац.
|
||||||
|
|
||||||
|
Таблицу оставляй там, где сравниваются однородные ряды: коды ОКВЭД, динамика показателей по годам, сопоставление конкурентов. Таблица из одной строки данных не нужна.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Ссылки на источники
|
||||||
|
|
||||||
|
Несколько источников на одно утверждение — **одной скобкой**:
|
||||||
|
|
||||||
|
| Нельзя | Надо |
|
||||||
|
|--------|------|
|
||||||
|
| `[1], [2]` | `[1, 2]` |
|
||||||
|
| `[2], [5]` | `[2, 5]` |
|
||||||
|
| `[1], [2], [5]` | `[1, 2, 5]` |
|
||||||
|
| `[6], [7]` | `[6, 7]` |
|
||||||
|
|
||||||
|
Одиночная ссылка `[1]` допустима. Форма с страницами: `[2, c. 21-25]`. Во введении и заключении ссылок нет.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Границы пункта задания
|
||||||
|
|
||||||
|
Факт относится к тому пункту, которому он принадлежит.
|
||||||
|
|
||||||
|
- Характеристика **объекта**: статус, виды деятельности, оргмодель, карта верхнего уровня, макро- и микросреда, масштаб.
|
||||||
|
- Нельзя в характеристике объекта разворачивать узкое место процесса, параметры оптимизации, «рост заявок упирается в ручную проверку» — это пункт про предмет / процесс (практика 2 и далее).
|
||||||
|
- В пункте про процесс не повторять заново всю справку об объекте.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Критический разбор до сдачи
|
||||||
|
|
||||||
|
На текущем принятом этапе достаточно формальной комплектности. **В последующих практиках** студент до загрузки файла сам разбирает представляемый фрагмент проектного решения:
|
||||||
|
|
||||||
|
1. Все ли обязательные артефакты пункта на месте и читаемы.
|
||||||
|
2. Согласованы ли объект, оргмодель, карта и текст процесса.
|
||||||
|
3. Нет ли публицистики, лишних подразделов, таблиц-дублей текста.
|
||||||
|
4. Выдержана ли иерархия на оргсхеме (см. `org-hierarchy.md`).
|
||||||
|
5. Не попал ли материал не в свой пункт.
|
||||||
|
|
||||||
|
Модель, которая готовит следующую практику, проводит этот разбор молча и правит текст **до** выдачи файла. Не вставляй в отчёт фразу «проведён критический анализ».
|
||||||
@@ -0,0 +1,514 @@
|
|||||||
|
# ArchiMate 3.2 для md2gost — рабочий справочник
|
||||||
|
|
||||||
|
Как корректно генерировать диаграммы ArchiMate® 3.2 в PlantUML для отчётов md2gost. Версия языка — только **3.2**. ArchiMate® — товарный знак The Open Group; этот текст — учебная выжимка, не копия спецификации.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Как рисовать
|
||||||
|
|
||||||
|
Оградка ` ```uml-archimate ` или ` ```archimate `. В теле — **только макросы**: ни `@startuml`, ни `@enduml`, ни `!include` (их подставит схема).
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Слоистая архитектура портала приведена на @Рисунок:arch_layered.
|
||||||
|
|
||||||
|
%arch_layered Слоистая архитектура портала +landscape
|
||||||
|
|
||||||
|
```uml-archimate
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
|
||||||
|
Business_Actor(student, "Студент")
|
||||||
|
Business_Process(enroll, "Подача заявки")
|
||||||
|
Application_Service(portalSvc, "Сервис приёма заявок")
|
||||||
|
Application_Component(portal, "Веб-портал")
|
||||||
|
|
||||||
|
Rel_Assignment(student, enroll)
|
||||||
|
Rel_Serving(portalSvc, enroll)
|
||||||
|
Rel_Realization(portal, portalSvc)
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Широкие схемы (Layered, Application Cooperation) почти всегда с `+landscape`. Флаг `+listing` добавит исходник схемы отдельным Листингом.
|
||||||
|
|
||||||
|
Формат макроса: `Категория_Элемент(alias, "Подпись")`. Alias — латиница (`student`, `crm`); нельзя `end`, `start`, `group`. Подписи русские, в кавычках; длинные переносятся через `\n`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Каркас языка
|
||||||
|
|
||||||
|
**Три core-слоя:**
|
||||||
|
|
||||||
|
| Слой | Что показывает |
|
||||||
|
|------|----------------|
|
||||||
|
| Business | бизнес-сервисы для клиентов, процессы и акторы, которые их реализуют |
|
||||||
|
| Application | прикладные сервисы и приложения, поддерживающие бизнес |
|
||||||
|
| Technology | обработка, хранение, сети, а также физический мир |
|
||||||
|
|
||||||
|
Плюс слой Strategy, слой Implementation & Migration и аспект Motivation.
|
||||||
|
|
||||||
|
**Четыре аспекта:**
|
||||||
|
|
||||||
|
| Аспект | Роль | Примеры |
|
||||||
|
|--------|------|---------|
|
||||||
|
| Active structure | кто действует | Actor, Role, Component, Node, Device |
|
||||||
|
| Behavior | что делается | Process, Function, Interaction, Service, Event |
|
||||||
|
| Passive structure | над чем работают | Business Object, Data Object, Artifact |
|
||||||
|
| Motivation | зачем | Stakeholder, Driver, Goal, Requirement |
|
||||||
|
|
||||||
|
**Каноническая цепочка внутри слоя:**
|
||||||
|
|
||||||
|
```text
|
||||||
|
Active structure —Assignment→ internal behavior (Process / Function)
|
||||||
|
internal behavior —Realization→ Service (внешнее поведение)
|
||||||
|
Service —Serving→ потребитель (Role / Process / Component)
|
||||||
|
behavior —Access→ passive structure
|
||||||
|
```
|
||||||
|
|
||||||
|
**Два межслойных моста:** Serving (сервис предоставляет функциональность потребителю) и Realization (более конкретное реализует более абстрактное).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Элементы → макросы
|
||||||
|
|
||||||
|
### Motivation
|
||||||
|
|
||||||
|
| Элемент | Макрос | Определение |
|
||||||
|
|---------|--------|-------------|
|
||||||
|
| Stakeholder | `Motivation_Stakeholder` | роль лица или организации, заинтересованной в эффектах архитектуры |
|
||||||
|
| Driver | `Motivation_Driver` | условие, побуждающее ставить цели и вносить изменения |
|
||||||
|
| Assessment | `Motivation_Assessment` | результат анализа положения дел относительно driver |
|
||||||
|
| Goal | `Motivation_Goal` | высокоуровневое намерение, желаемое состояние |
|
||||||
|
| Outcome | `Motivation_Outcome` | конечный результат, эффект |
|
||||||
|
| Principle | `Motivation_Principle` | общее свойство, применимое к любой системе в контексте |
|
||||||
|
| Requirement | `Motivation_Requirement` | требуемое свойство конкретной системы |
|
||||||
|
| Constraint | `Motivation_Constraint` | ограничение на архитектуру или внедрение |
|
||||||
|
| Meaning | `Motivation_Meaning` | интерпретация концепта в контексте |
|
||||||
|
| Value | `Motivation_Value` | относительная ценность концепта |
|
||||||
|
|
||||||
|
### Strategy
|
||||||
|
|
||||||
|
| Элемент | Макрос | Определение |
|
||||||
|
|---------|--------|-------------|
|
||||||
|
| Resource | `Strategy_Resource` | актив, которым владеют или управляют |
|
||||||
|
| Capability | `Strategy_Capability` | способность активной структуры |
|
||||||
|
| Value Stream | `Strategy_ValueStream` | последовательность активностей, создающая результат для клиента |
|
||||||
|
| Course of Action | `Strategy_CourseOfAction` | план настройки capabilities и resources под цель |
|
||||||
|
|
||||||
|
### Business
|
||||||
|
|
||||||
|
| Элемент | Макрос | Аспект | Определение |
|
||||||
|
|---------|--------|--------|-------------|
|
||||||
|
| Business Actor | `Business_Actor` | active | сущность, способная выполнять поведение |
|
||||||
|
| Business Role | `Business_Role` | active | ответственность за поведение |
|
||||||
|
| Business Collaboration | `Business_Collaboration` | active | агрегат двух и более активных структур |
|
||||||
|
| Business Interface | `Business_Interface` | active | точка доступа к бизнес-сервису |
|
||||||
|
| Business Process | `Business_Process` | behavior | последовательность поведения к результату |
|
||||||
|
| Business Function | `Business_Function` | behavior | набор поведения по компетенциям и ресурсам |
|
||||||
|
| Business Interaction | `Business_Interaction` | behavior | коллективное поведение участников |
|
||||||
|
| Business Event | `Business_Event` | behavior | изменение состояния на бизнес-уровне |
|
||||||
|
| Business Service | `Business_Service` | behavior | явно определённое поведение, доступное среде |
|
||||||
|
| Business Object | `Business_Object` | passive | концепт предметной области |
|
||||||
|
| Contract | `Business_Contract` | passive | соглашение провайдера и потребителя |
|
||||||
|
| Representation | `Business_Representation` | passive | форма представления информации объекта |
|
||||||
|
| Product | `Business_Product` | composite | набор сервисов и объектов вместе с контрактом |
|
||||||
|
|
||||||
|
### Application
|
||||||
|
|
||||||
|
| Элемент | Макрос | Аспект | Определение |
|
||||||
|
|---------|--------|--------|-------------|
|
||||||
|
| Application Component | `Application_Component` | active | модульная инкапсуляция прикладной функциональности |
|
||||||
|
| Application Collaboration | `Application_Collaboration` | active | агрегат прикладных активных структур |
|
||||||
|
| Application Interface | `Application_Interface` | active | точка доступа к прикладным сервисам |
|
||||||
|
| Application Function | `Application_Function` | behavior | автоматизированное поведение компонента |
|
||||||
|
| Application Interaction | `Application_Interaction` | behavior | коллективное поведение компонентов |
|
||||||
|
| Application Process | `Application_Process` | behavior | последовательность прикладного поведения |
|
||||||
|
| Application Event | `Application_Event` | behavior | изменение состояния приложения |
|
||||||
|
| Application Service | `Application_Service` | behavior | внешне видимое прикладное поведение |
|
||||||
|
| Data Object | `Application_DataObject` | passive | данные, структурированные для обработки |
|
||||||
|
|
||||||
|
### Technology и Physical
|
||||||
|
|
||||||
|
| Элемент | Макрос | Определение |
|
||||||
|
|---------|--------|-------------|
|
||||||
|
| Node | `Technology_Node` | вычислительный или физический ресурс, хостящий другие |
|
||||||
|
| Device | `Technology_Device` | физический ИТ-ресурс |
|
||||||
|
| System Software | `Technology_SystemSoftware` | ПО среды исполнения или хранения |
|
||||||
|
| Technology Collaboration | `Technology_Collaboration` | агрегат технологических активных структур |
|
||||||
|
| Technology Interface | `Technology_Interface` | точка доступа к технологическим сервисам |
|
||||||
|
| Path | `Technology_Path` | связь между технологическими структурами для обмена |
|
||||||
|
| Communication Network | `Technology_CommunicationNetwork` | структуры передачи данных |
|
||||||
|
| Technology Function | `Technology_Function` | набор технологического поведения |
|
||||||
|
| Technology Process | `Technology_Process` | последовательность технологического поведения |
|
||||||
|
| Technology Interaction | `Technology_Interaction` | коллективное технологическое поведение |
|
||||||
|
| Technology Event | `Technology_Event` | изменение технологического состояния |
|
||||||
|
| Technology Service | `Technology_Service` | внешне видимое технологическое поведение |
|
||||||
|
| Artifact | `Technology_Artifact` | данные или файл, используемый при разработке и эксплуатации |
|
||||||
|
| Equipment | `Physical_Equipment` | физические машины и инструменты |
|
||||||
|
| Facility | `Physical_Facility` | физическая структура или окружение |
|
||||||
|
| Distribution Network | `Physical_DistributionNetwork` | сеть транспортировки материи или энергии |
|
||||||
|
| Material | `Physical_Material` | осязаемая материя или энергия |
|
||||||
|
|
||||||
|
В 3.2 Device, System Software, Facility и Equipment — **не** подтипы Node, а технологические активные структуры, связанные с Node композицией или агрегацией.
|
||||||
|
|
||||||
|
### Implementation & Migration
|
||||||
|
|
||||||
|
| Элемент | Макрос | Определение |
|
||||||
|
|---------|--------|-------------|
|
||||||
|
| Work Package | `Implementation_WorkPackage` | серия действий с результатом в сроках и ресурсах |
|
||||||
|
| Deliverable | `Implementation_Deliverable` | определённый результат work package |
|
||||||
|
| Implementation Event | `Implementation_Event` | изменение состояния при внедрении |
|
||||||
|
| Plateau | `Implementation_Plateau` | стабильное состояние архитектуры на период |
|
||||||
|
| Gap | `Implementation_Gap` | различие между двумя plateau |
|
||||||
|
|
||||||
|
### Composite и Junction
|
||||||
|
|
||||||
|
| Элемент | Макрос |
|
||||||
|
|---------|--------|
|
||||||
|
| Grouping | `Grouping` / `Other_Grouping` / `Group` |
|
||||||
|
| Location | `Other_Location` / `Business_Location` |
|
||||||
|
| And Junction | `Junction_And` |
|
||||||
|
| Or Junction | `Junction_Or` |
|
||||||
|
|
||||||
|
Grouping и Junction допустимы в любом viewpoint.
|
||||||
|
|
||||||
|
### Какой элемент поведения выбрать
|
||||||
|
|
||||||
|
| Нужно показать | Берётся |
|
||||||
|
|----------------|---------|
|
||||||
|
| последовательность шагов к результату | `*_Process` |
|
||||||
|
| группу поведения по компетенциям и ресурсам | `*_Function` |
|
||||||
|
| поведение двух и более участников | `*_Interaction` |
|
||||||
|
| внешне видимое поведение, чёрный ящик | `*_Service` |
|
||||||
|
| момент или смену состояния | `*_Event` |
|
||||||
|
|
||||||
|
Слой задаётся типом элемента, а не подписью: `Business_Process` ≠ `Application_Process` ≠ `Technology_Process`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Связи
|
||||||
|
|
||||||
|
| Тип | Класс | Смысл | Макрос | Нотация |
|
||||||
|
|-----|-------|-------|--------|---------|
|
||||||
|
| Composition | structural | целое состоит из частей, часть не живёт отдельно | `Rel_Composition` | `*--` |
|
||||||
|
| Aggregation | structural | целое объединяет части, части живут отдельно | `Rel_Aggregation` | `o--` |
|
||||||
|
| Assignment | structural | ответственность, исполнение, размещение | `Rel_Assignment` | `@-->>` |
|
||||||
|
| Realization | structural | конкретное реализует абстрактное | `Rel_Realization` | `~~\|>` |
|
||||||
|
| Serving | dependency | предоставляет функциональность другому | `Rel_Serving` | `-->` |
|
||||||
|
| Access | dependency | поведение работает с пассивным элементом | `Rel_Access`, `_r`, `_w`, `_rw` | `~~` |
|
||||||
|
| Influence | dependency | влияет на достижение motivation-элемента | `Rel_Influence` | `..>` |
|
||||||
|
| Triggering | dynamic | временная или причинная активация | `Rel_Triggering` | `-->>` |
|
||||||
|
| Flow | dynamic | передача чего-либо | `Rel_Flow` | `..>>` |
|
||||||
|
| Specialization | other | является разновидностью | `Rel_Specialization` | `--\|>` |
|
||||||
|
| Association | other | неспецифичная связь | `Rel_Association` | `--` |
|
||||||
|
|
||||||
|
Направление раскладки: суффиксы `_Up`, `_Down`, `_Left`, `_Right` — например `Rel_Serving_Up(svc, proc)`.
|
||||||
|
|
||||||
|
### Направления связей — где чаще всего ошибаются
|
||||||
|
|
||||||
|
| Связь | Откуда → куда |
|
||||||
|
|-------|---------------|
|
||||||
|
| Serving | поставщик (обычно Service) → **потребитель** |
|
||||||
|
| Realization | более конкретное → более абстрактное |
|
||||||
|
| Composition, Aggregation | целое → часть |
|
||||||
|
| Assignment | активная структура → поведение |
|
||||||
|
| Access | поведение → **пассивный** элемент, вид read / write / read-write |
|
||||||
|
| Triggering | предшественник → следующий |
|
||||||
|
| Flow | источник → приёмник |
|
||||||
|
| Influence | влияющий → motivation-элемент, сила в подписи (`++`, `+`, `0`, `-`, `--`) |
|
||||||
|
| Specialization | специализация → общий тип |
|
||||||
|
|
||||||
|
### Правила метамодели
|
||||||
|
|
||||||
|
- Элемент может композировать или агрегировать элементы того же класса.
|
||||||
|
- Внутренние поведения одного слоя могут агрегировать друг друга (Function агрегирует Process).
|
||||||
|
- Collaboration ведёт себя как соответствующая внутренняя активная структура.
|
||||||
|
- Stakeholder связывается Association с любым элементом; остальные motivation-элементы влияют друг на друга через Influence.
|
||||||
|
- Association формально возможна между любыми классами, но применяется только когда нет более точного типа.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Канонические цепочки
|
||||||
|
|
||||||
|
```text
|
||||||
|
# Внутри слоя Business
|
||||||
|
Business_Actor / Business_Role Rel_Assignment Business_Process / Function
|
||||||
|
Business_Process Rel_Realization Business_Service
|
||||||
|
Business_Process Rel_Access_* Business_Object
|
||||||
|
Business_Event Rel_Triggering Business_Process
|
||||||
|
|
||||||
|
# Внутри слоя Application
|
||||||
|
Application_Component Rel_Assignment Application_Function / Process
|
||||||
|
Application_Function Rel_Realization Application_Service
|
||||||
|
Application_Service Rel_Serving Business_Process / Business_Role
|
||||||
|
Application_Component Rel_Access_* Application_DataObject
|
||||||
|
Application_Component Rel_Composition Application_Component
|
||||||
|
|
||||||
|
# Технологии и данные
|
||||||
|
Technology_Node Rel_Composition Technology_Device / SystemSoftware
|
||||||
|
Technology_* Rel_Assignment Technology_Function / Process
|
||||||
|
Technology_Function Rel_Realization Technology_Service
|
||||||
|
Technology_Service Rel_Serving Application_Component
|
||||||
|
Technology_Artifact Rel_Realization Application_DataObject
|
||||||
|
Application_DataObject Rel_Realization Business_Object
|
||||||
|
|
||||||
|
# Стратегия и мотивация
|
||||||
|
Business_Process / App_Service Rel_Realization Strategy_Capability
|
||||||
|
Application_Service / Component Rel_Realization Motivation_Requirement
|
||||||
|
Motivation_Driver Rel_Association Motivation_Stakeholder
|
||||||
|
Motivation_Assessment Rel_Association Motivation_Driver
|
||||||
|
Motivation_Goal Rel_Realization Motivation_Outcome
|
||||||
|
|
||||||
|
# Внедрение и миграция
|
||||||
|
Implementation_WorkPackage Rel_Realization Implementation_Deliverable
|
||||||
|
Implementation_Plateau Rel_Aggregation элементы core-слоёв
|
||||||
|
Implementation_Gap Rel_Association между двумя plateau
|
||||||
|
```
|
||||||
|
|
||||||
|
### Запреты
|
||||||
|
|
||||||
|
1. Не `Rel_Assignment` от Data Object или Business Object к процессу.
|
||||||
|
2. Не `Rel_Realization` от Component сразу к Process: нужен внутренний Function или Process, затем Realization к Service.
|
||||||
|
3. Не `Rel_Serving` в направлении «потребитель → сервис».
|
||||||
|
4. Не подменять Access потоком Flow только потому, что речь о данных.
|
||||||
|
5. Не ставить `Business_Process` там, где исполнитель — приложение.
|
||||||
|
6. Не ставить Association на все рёбра «на всякий случай».
|
||||||
|
7. Не считать Device подтипом Node без композиции или агрегации.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Viewpoints
|
||||||
|
|
||||||
|
**Один рисунок = один viewpoint.** Не сваливать мотивацию, бизнес, приложения и инфраструктуру на один холст (Layered — исключение, но и там ограничивай число элементов).
|
||||||
|
|
||||||
|
| Viewpoint | Фокус | Типичные элементы |
|
||||||
|
|-----------|-------|-------------------|
|
||||||
|
| Organization | структура организационных единиц | Actor, Role, Collaboration, Location |
|
||||||
|
| Application Structure | внутренняя структура приложений | Component, Interface, Data Object |
|
||||||
|
| Information Structure | данные и информация | Business Object, Representation, Data Object, Artifact |
|
||||||
|
| Technology | инфраструктура | Node, Device, System Software, Network, Path |
|
||||||
|
| Layered | обзор слоёв | Business + Application + Technology, Serving и Realization |
|
||||||
|
| Physical | физический мир | Equipment, Facility, Distribution Network, Material |
|
||||||
|
| Product | ценность продукта | Product, Contract, Service, Interface |
|
||||||
|
| Application Usage | приложения в бизнес-контексте | бизнес-процессы + прикладные сервисы |
|
||||||
|
| Technology Usage | технологии для приложений | Application + Technology services и nodes |
|
||||||
|
| Business Process Cooperation | связь процессов | Process, Event, Service, Role |
|
||||||
|
| Application Cooperation | связь приложений | Component, Service, Interface, Data, Flow |
|
||||||
|
| Service Realization | как реализованы сервисы | Service ← Process / Function ← активная структура |
|
||||||
|
| Implementation and Deployment | развёртывание | Application + Artifact + Node / Device |
|
||||||
|
| Stakeholder, Goal Realization, Requirements Realization, Motivation | мотивация | Driver, Goal, Outcome, Requirement, Constraint |
|
||||||
|
| Strategy, Capability Map, Value Stream, Resource Map | стратегия | Capability, Resource, Value Stream, Course of Action |
|
||||||
|
| Project, Migration, Implementation and Migration | внедрение | Work Package, Deliverable, Plateau, Gap |
|
||||||
|
|
||||||
|
### Макет
|
||||||
|
|
||||||
|
- Структурные схемы: `LAYOUT_TOP_DOWN()` или вложенность через `{ }`.
|
||||||
|
- Процессы слева направо: `LAYOUT_LEFT_RIGHT()` и `Rel_*_Right`.
|
||||||
|
- Layered: бизнес сверху, технологии снизу; Serving и Realization направлены вверх (`Rel_Serving_Up`).
|
||||||
|
- Выравнивание скрытыми связями: `Lay_U`, `Lay_D`, `Lay_L`, `Lay_R`.
|
||||||
|
- Вложение элементов:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Business_Product(prod, "Тариф") {
|
||||||
|
Business_Service(s1, "Подключение")
|
||||||
|
Business_Contract(c1, "Оферта")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Для Service, Actor, Value и ValueStream при вложении добавляется `$nest=%true()`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Готовые шаблоны
|
||||||
|
|
||||||
|
Тела для ` ```uml-archimate ` без обёртки.
|
||||||
|
|
||||||
|
### Organization
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
Business_Actor(uni, "Университет") {
|
||||||
|
Business_Actor(dean, "Деканат")
|
||||||
|
Business_Actor(it, "Управление ИТ")
|
||||||
|
}
|
||||||
|
Business_Role(student, "Студент")
|
||||||
|
Business_Role(clerk, "Методист")
|
||||||
|
Rel_Assignment(dean, clerk)
|
||||||
|
Rel_Assignment(uni, student)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Realization
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
Business_Role(applicant, "Абитуриент")
|
||||||
|
Business_Process(apply, "Подача заявления")
|
||||||
|
Business_Service(applySvc, "Приём заявлений")
|
||||||
|
Application_Service(webSvc, "Веб-приёмная")
|
||||||
|
Application_Component(lk, "Личный кабинет")
|
||||||
|
Application_Function(submitFn, "Отправка формы")
|
||||||
|
|
||||||
|
Rel_Assignment(applicant, apply)
|
||||||
|
Rel_Realization(apply, applySvc)
|
||||||
|
Rel_Serving(webSvc, apply)
|
||||||
|
Rel_Assignment(lk, submitFn)
|
||||||
|
Rel_Realization(submitFn, webSvc)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Application Cooperation
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_LEFT_RIGHT()
|
||||||
|
Application_Component(crm, "CRM")
|
||||||
|
Application_Component(billing, "Биллинг")
|
||||||
|
Application_Service(crmApi, "API клиентов")
|
||||||
|
Application_DataObject(client, "Карточка клиента")
|
||||||
|
|
||||||
|
Rel_Realization(crm, crmApi)
|
||||||
|
Rel_Serving(crmApi, billing)
|
||||||
|
Rel_Access_rw(crm, client)
|
||||||
|
Rel_Access_r(billing, client)
|
||||||
|
Rel_Flow(crm, billing, "событие оплаты")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Layered
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
Business_Process(sale, "Оформление заказа")
|
||||||
|
Business_Object(order, "Заказ")
|
||||||
|
Application_Service(shopSvc, "Интернет-магазин")
|
||||||
|
Application_Component(shop, "ShopApp")
|
||||||
|
Technology_Service(dbSvc, "СУБД")
|
||||||
|
Technology_Node(dbHost, "Сервер БД")
|
||||||
|
Technology_SystemSoftware(pg, "PostgreSQL")
|
||||||
|
|
||||||
|
Rel_Access_w(sale, order)
|
||||||
|
Rel_Serving_Up(shopSvc, sale)
|
||||||
|
Rel_Realization(shop, shopSvc)
|
||||||
|
Rel_Serving_Up(dbSvc, shop)
|
||||||
|
Rel_Assignment(dbHost, dbSvc)
|
||||||
|
Rel_Composition(dbHost, pg)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Requirements Realization
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
Motivation_Stakeholder(rector, "Ректор")
|
||||||
|
Motivation_Driver(comp, "Конкуренция вузов")
|
||||||
|
Motivation_Goal(digital, "Цифровизация приёма")
|
||||||
|
Motivation_Requirement(online, "Заявление онлайн круглосуточно")
|
||||||
|
Motivation_Constraint(fz152, "152-ФЗ")
|
||||||
|
Application_Service(portal, "Портал абитуриента")
|
||||||
|
|
||||||
|
Rel_Association(rector, comp)
|
||||||
|
Rel_Association(comp, digital)
|
||||||
|
Rel_Realization(online, digital)
|
||||||
|
Rel_Influence(fz152, online, "-")
|
||||||
|
Rel_Realization(portal, online)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation & Migration
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_LEFT_RIGHT()
|
||||||
|
Implementation_Plateau(asIs, "AS-IS 2025")
|
||||||
|
Implementation_Plateau(toBe, "TO-BE 2026")
|
||||||
|
Implementation_Gap(gap1, "Нет единого личного кабинета")
|
||||||
|
Implementation_WorkPackage(wp, "Проект «Единый ЛК»")
|
||||||
|
Implementation_Deliverable(d1, "Релиз 1.0")
|
||||||
|
Implementation_Event(goLive, "Ввод в эксплуатацию")
|
||||||
|
|
||||||
|
Rel_Association(gap1, asIs)
|
||||||
|
Rel_Association(gap1, toBe)
|
||||||
|
Rel_Realization(wp, d1)
|
||||||
|
Rel_Triggering(d1, goLive)
|
||||||
|
Rel_Triggering(goLive, toBe)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Technology Usage
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_TOP_DOWN()
|
||||||
|
Application_Component(api, "API Gateway")
|
||||||
|
Technology_Node(k8s, "Кластер Kubernetes")
|
||||||
|
Technology_Device(node1, "Рабочий узел")
|
||||||
|
Technology_SystemSoftware(os, "Linux")
|
||||||
|
Technology_CommunicationNetwork(net, "Сеть кластера")
|
||||||
|
Technology_Artifact(image, "api:1.2")
|
||||||
|
|
||||||
|
Rel_Serving_Up(k8s, api)
|
||||||
|
Rel_Composition(k8s, node1)
|
||||||
|
Rel_Composition(node1, os)
|
||||||
|
Rel_Association(node1, net)
|
||||||
|
Rel_Assignment(node1, image)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Процесс с Junction
|
||||||
|
|
||||||
|
```text
|
||||||
|
LAYOUT_LEFT_RIGHT()
|
||||||
|
Business_Event(incident, "Инцидент")
|
||||||
|
Business_Process(triage, "Первичная оценка")
|
||||||
|
Junction_Or(j1, "")
|
||||||
|
Business_Process(restore, "Восстановление сервиса")
|
||||||
|
Business_Process(investigate, "Расследование")
|
||||||
|
Business_Process(close, "Закрытие инцидента")
|
||||||
|
|
||||||
|
Rel_Triggering(incident, triage)
|
||||||
|
Rel_Triggering(triage, j1)
|
||||||
|
Rel_Triggering(j1, restore)
|
||||||
|
Rel_Triggering(j1, investigate)
|
||||||
|
Rel_Triggering(restore, close)
|
||||||
|
Rel_Triggering(investigate, close)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Антипаттерны
|
||||||
|
|
||||||
|
| Плохо | Почему | Как надо |
|
||||||
|
|-------|--------|----------|
|
||||||
|
| все связи `Rel_Association` | теряется семантика | Serving, Realization, Assignment, Access |
|
||||||
|
| `Application_Component` вместо `Business_Actor` | разные аспекты и слои | Actor и Role для людей и подразделений |
|
||||||
|
| Business Process «внутри» компонента без Assignment | слои смешаны | процесс на бизнес-слое, Serving от прикладного сервиса |
|
||||||
|
| Serving от Role к Service | направление наоборот | Service → Role или Process |
|
||||||
|
| Realization Component → Process | пропущено внутреннее поведение | Component → Function → Service |
|
||||||
|
| Flow вместо Access к Data Object | Flow — передача, Access — работа с объектом | `Rel_Access_r/w/rw` |
|
||||||
|
| один Layered на 40 элементов | нечитаемо | несколько viewpoint'ов |
|
||||||
|
| C4 `Person` или UML-класс в блоке archimate | другой язык | только макросы ArchiMate |
|
||||||
|
| `Process` без указания слоя | в 3.2 слой обязателен | `Business_Process`, `Application_Process`, `Technology_Process` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Чеклист генерации
|
||||||
|
|
||||||
|
1. Версия языка 3.2, макросы с указанием слоя.
|
||||||
|
2. Оградка ` ```uml-archimate `, без `@startuml` и `!include`.
|
||||||
|
3. Выбран **один** viewpoint; 8–18 элементов на рисунок.
|
||||||
|
4. Сначала объявлены все элементы, затем все `Rel_*`.
|
||||||
|
5. Alias латиницей, подписи по-русски в кавычках.
|
||||||
|
6. Serving — от сервиса к потребителю; Realization — от конкретного к абстрактному.
|
||||||
|
7. Поведение того же слоя, что и его исполнитель по Assignment.
|
||||||
|
8. Нет C4, UML-классов, BPMN-развилок и Association «по умолчанию».
|
||||||
|
9. Перед блоком стоит `%id Название`, при широкой схеме — `+landscape`.
|
||||||
|
10. В тексте есть ссылка `@Рисунок:id`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Запасной вариант без stdlib
|
||||||
|
|
||||||
|
Если библиотека ArchiMate недоступна, схему можно нарисовать в ` ```uml ` низкоуровневым ключевым словом:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
%arch_fallback Фрагмент архитектуры
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
archimate #Business "Подача заявки" as p <<business-process>>
|
||||||
|
archimate #Application "Портал" as c <<application-component>>
|
||||||
|
c --> p
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Смешивать макросы и низкоуровневый `archimate` на одной схеме нельзя.
|
||||||
@@ -0,0 +1,165 @@
|
|||||||
|
# Проверка ТЗ — полный каталог замечаний
|
||||||
|
|
||||||
|
Что именно проверяет `md2gost … --check`, с какими текстами сообщений и как чинить каждое замечание.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Как запускать
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m md2gost report.md --check-only --type coursework # только проверка
|
||||||
|
python -m md2gost report.md -o out.docx --type coursework --check --strict
|
||||||
|
```
|
||||||
|
|
||||||
|
| Ключ | Поведение |
|
||||||
|
|------|-----------|
|
||||||
|
| `--check` | проверить и напечатать отчёт, документ всё равно собрать |
|
||||||
|
| `--check-only` | только проверка, DOCX не собирается, код выхода 0 |
|
||||||
|
| `--strict` | при наличии хотя бы одной ошибки вывести `Проверка ТЗ: есть ошибки (--strict)`, код выхода 1, документ не собирать |
|
||||||
|
| `--check-pages` | отдельная эвристическая проверка вёрстки готового DOCX через Microsoft Word |
|
||||||
|
|
||||||
|
Формат отчёта:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Проверка ТЗ: найдено замечаний — 3
|
||||||
|
[error] structure.missing: Отсутствует обязательный раздел «ЗАКЛЮЧЕНИЕ»
|
||||||
|
[warning] ref.unused (стр. md:42): Метка «tab_cmp» объявлена, но в тексте нет ссылки @…:tab_cmp
|
||||||
|
[error] ref.ris (стр. md:57): Используйте «Рисунок», не «рис.»
|
||||||
|
```
|
||||||
|
|
||||||
|
Без замечаний: `Проверка ТЗ: замечаний нет.`
|
||||||
|
|
||||||
|
Уровни: **error** — блокирует сборку при `--strict`; **warning** — не блокирует; **heuristic** — только у проверки вёрстки, никогда не влияет на код выхода.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Структура документа
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `structure.missing` | error | `Отсутствует обязательный раздел «{название}»` | Нет одного из: СОДЕРЖАНИЕ, ВВЕДЕНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ. Добавить раздел `# *НАЗВАНИЕ` с содержательным текстом. Допускается написание «СПИСОК ИСПОЛЬЗУЕМЫХ ИСТОЧНИКОВ» |
|
||||||
|
| `structure.missing` | error | `Отсутствует раздел «СОДЕРЖАНИЕ»` | Профиль `PIS_custom`: нет `# *СОДЕРЖАНИЕ` |
|
||||||
|
| `structure.toc` | warning | `Нет маркера [TOC] для автособираемого содержания` | Добавить `[TOC]` прописными отдельной строкой под `# *СОДЕРЖАНИЕ` |
|
||||||
|
| `structure.toc` | **error** | `Нет маркера [TOC] для оглавления (обязательно для итогового отчёта)` | То же, но для `PIS_custom` это ошибка |
|
||||||
|
| `structure.body` | error | `Нет нумерованного раздела основной части (# заголовок без *)` | Все H1 оказались со звёздочкой. Добавить `# 1 Название` |
|
||||||
|
| `structure.graphic` | error | `Для ВКР обязательно приложение «Графический материал»` | В тексте нет подстроки «Графический материал». Добавить `## Приложение Б Графический материал` |
|
||||||
|
| `structure.practical` | error | `Нет заголовков вида «Практическая работа №N. …» (H1 без *, каждая работа — отдельный раздел)` | Профиль `PIS_custom`: каждую работу оформить как `# Практическая работа №N. Название` |
|
||||||
|
| `structure.apid` | error | `Для КР АПИД отсутствует обязательный раздел: «{название}»` | См. таблицу ниже |
|
||||||
|
|
||||||
|
### Обязательные разделы КР АПИД
|
||||||
|
|
||||||
|
Проверка ищет подстроки в тексте заголовков (регистр не важен):
|
||||||
|
|
||||||
|
| Требуемый раздел | Что должно найтись в заголовках |
|
||||||
|
|------------------|--------------------------------|
|
||||||
|
| `1. Теоретические аспекты разработки архитектуры приложений и данных: …` | «теоретическ… аспект» |
|
||||||
|
| `2. Прикладные аспекты разработки архитектуры приложений и данных …` | «прикладн… аспект» |
|
||||||
|
| `2.1 Описание проекта команды и разрабатываемого программного приложения` | «2.1» и «описание проекта» рядом |
|
||||||
|
| `2.2 Описание роли … в приложении …` | «2.2» и «описание роли» рядом |
|
||||||
|
| `2.3 Описание архитектуры программного приложения и данных для роли` | «2.3» и «архитектур» |
|
||||||
|
| `2.4 Варианты развития архитектуры программного приложения` | «2.4» и «вариант» |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Заголовки
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `heading.numbered_special` | error | `Спецраздел «{title}» должен быть без номера: # *{title}` | H1 со спецназванием без звёздочки. Добавить `*` сразу после `# ` |
|
||||||
|
| `heading.case` | warning | `Спецраздел лучше писать ПРОПИСНЫМИ: «{TITLE}»` | «Введение» вместо «ВВЕДЕНИЕ» |
|
||||||
|
| `heading.case` | warning | `Подраздел с прописной буквы: «{Title}»` | Профиль `PIS_custom`: заголовок уровня `##` и глубже начинается со строчной буквы |
|
||||||
|
| `heading.trailing_dot` | warning | `Заголовок без точки в конце: «{title}»` | Профиль `PIS_custom`: убрать точку в конце заголовка |
|
||||||
|
|
||||||
|
Спецразделы, требующие звёздочки на уровне H1: СОДЕРЖАНИЕ, ВВЕДЕНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ, СПИСОК ИСПОЛЬЗУЕМЫХ ИСТОЧНИКОВ, ПРИЛОЖЕНИЕ, ПРИЛОЖЕНИЯ, а также любой H1, начинающийся на «ПРИЛОЖЕН».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Ссылки и терминология
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `ref.ris` | error | `Используйте «Рисунок», не «рис.»` | В тексте найдено «рис.» (шаблон `\bрис\.`). Заменить на `@Рисунок:id` или слово «Рисунок» |
|
||||||
|
| `ref.tabl` | error | `Используйте «Таблица», не «табл.»` | Найдено «табл.». Заменить на `@Таблица:id` или слово «Таблица» |
|
||||||
|
| `footnote` | error | `Сноски в конце страницы не допускаются` | Найдена конструкция `[^…]`. Перенести содержание в основной текст или оформить ссылкой на источник |
|
||||||
|
| `table.nopp` | error | `Графу «№ п/п» в таблицы не включают` | Найдено «№ п/п». Удалить столбец |
|
||||||
|
| `ref.unused` | warning | `Метка «{id}» объявлена, но в тексте нет ссылки @…:{id}` | Добавить в текст перед объектом предложение со ссылкой `@Тип:{id}`, заканчивающееся точкой |
|
||||||
|
| `ref.dangling` | error | `Ссылка на несуществующую метку «{id}»` | Опечатка в `id` либо отсутствие объекта с такой меткой |
|
||||||
|
|
||||||
|
Множество меток собирается из строк `^%(\w+)` и из title картинок; множество ссылок — из `@Тип:id`. Оба множества должны совпадать.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Источники
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `cite.intro` | error | `Во разделе «ВВЕДЕНИЕ» ссылки на источники не указываются` | Убрать `[n]` из введения; то же для заключения |
|
||||||
|
| `biblio.count` | error | `Источников должно быть от {min} до {max} (сейчас {n})` | Довести число записей до нормы профиля |
|
||||||
|
| `biblio.count` | warning | `ВКР: в разделе списка «{title}» желательно ≥10 источников (сейчас {n})` | Дополнить подраздел списка |
|
||||||
|
| `biblio.count` | warning | `ВКР: список должен делиться на разделы; в каждом ≥10 источников (сейчас всего {n}, разделов нет)` | Разбить список подразделами `##` |
|
||||||
|
| `biblio.age` | error | `Источник [{n}] старше {N} лет (год {год})` | Заменить на актуальное издание или редакцию стандарта |
|
||||||
|
| `biblio.order` | warning | `Порядок источников в списке должен совпадать с порядком первого упоминания` | Перенумеровать согласованно и в тексте, и в списке |
|
||||||
|
| `biblio.missing` | error | `Ссылка [{n}] есть в тексте, но нет в списке источников` | Добавить запись `[n]: …` |
|
||||||
|
|
||||||
|
Нормы по профилям:
|
||||||
|
|
||||||
|
| Профиль | Источников | Возраст |
|
||||||
|
|---------|-----------|---------|
|
||||||
|
| `practice`, `coursework` | 5–7 | не старше 5 лет |
|
||||||
|
| `APID_coursework` | 7–20 | не старше 5 лет |
|
||||||
|
| `vkr` | не менее 10 в каждом подразделе списка | не старше 5 лет |
|
||||||
|
| `PIS_custom` | не требуются | не старше 10 лет, если список всё же есть |
|
||||||
|
|
||||||
|
Год издания извлекается из текста записи автоматически. Если года в записи нет, проверка возраста пропускается.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Таблицы
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `table.merge_header` | error | `Маркер склеивания ^/> нельзя использовать в первой (заголовочной) строке таблицы` | Вписать нормальный заголовок столбца |
|
||||||
|
| `table.merge_col` | error | `Маркер «>» нельзя ставить в первом столбце (нет ячейки слева)` | Убрать маркер |
|
||||||
|
| `table.continuation` | warning | `Word сам не вставит «Продолжение Таблицы N» при переносе…` | Разметка ни при чём: запускать с `--table-continuation word` (нужен Word и `pywin32`) либо `caption` |
|
||||||
|
| `listing.continuation` | warning | `Длинный листинг: Word сам не вставит «Продолжение Листинга N»…` | То же для `--listing-continuation`. Длинным считается блок кода от 40 строк — можно вынести полный код в приложение |
|
||||||
|
|
||||||
|
Замечания о продолжении выдаются только при режимах `off` и `soft`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Приложения
|
||||||
|
|
||||||
|
| ID | Уровень | Сообщение | Причина и решение |
|
||||||
|
|----|---------|-----------|-------------------|
|
||||||
|
| `appendix.letter` | error | `Буква «{X}» не используется для обозначения приложений` | Запрещены Ё, З, Й, О, Ч, Ь, Ы, Ъ. Допустимы А, Б, В, Г, Д, Е, Ж, И, К, Л, М, Н, П, Р, С, Т, У, Ф, Х, Ц, Ш, Щ, Э, Ю, Я |
|
||||||
|
| `appendix.toc` | warning | `При нескольких приложениях после «ПРИЛОЖЕНИЯ» нужен перечень (основной текст) с номерами и названиями` | Добавить строки вида `Приложение А — Название` сразу после `# *ПРИЛОЖЕНИЯ` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Проверка вёрстки `--check-pages`
|
||||||
|
|
||||||
|
Отдельная эвристика на готовом DOCX: ищет страницы, у которых снизу пусто больше 40 % полосы, а раздел продолжается на следующей странице.
|
||||||
|
|
||||||
|
| Ситуация | Сообщение |
|
||||||
|
|----------|-----------|
|
||||||
|
| Нет `pywin32` или Word | `Проверка вёрстки пропущена: нужен пакет pywin32 (pip install pywin32) и Microsoft Word.` |
|
||||||
|
| Word не открылся | `Проверка вёрстки пропущена: не удалось открыть Word ({ошибка}).` |
|
||||||
|
| Замечаний нет | `Проверка вёрстки (Word): замечаний по полупустым страницам нет (эвристика; возможны пропуски).` |
|
||||||
|
| Замечания есть | `Проверка вёрстки (Word): найдено замечаний — {N} (все эвристические, могут быть ложными).` |
|
||||||
|
| Конкретная страница | `[heuristic] page.fill: на стр. {N} пустой низ ~{X}% полосы, а раздел «{название}» продолжается на следующей странице…` |
|
||||||
|
|
||||||
|
Ложные срабатывания нормальны: крупный рисунок, конец пункта, намеренный разрыв. Чем помочь на уровне разметки: флаг `+landscape` у широкой схемы, перенос крупного объекта в приложение, сокращение листинга.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Рекомендуемый цикл доводки
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m md2gost report.md --check-only --type coursework # 1. посмотреть замечания
|
||||||
|
# 2. отдать текст замечаний и .md модели с промптом ai/prompts/review-fix.md
|
||||||
|
python -m md2gost report.md --check-only --type coursework # 3. проверить повторно
|
||||||
|
python -m md2gost report.md -o report.docx --type coursework --check --strict
|
||||||
|
python -m md2gost report.docx --check-pages # 4. проверить вёрстку
|
||||||
|
```
|
||||||
|
|
||||||
|
Что проверка **не** ловит: смысловые ошибки, фактические неточности, выдуманные источники, слабую логику разделов и «машинный» стиль изложения. Стиль лечится промптом `ai/prompts/voice-human.md`, факты — вычиткой.
|
||||||
@@ -0,0 +1,242 @@
|
|||||||
|
# Запуск, профили и настройки md2gost
|
||||||
|
|
||||||
|
Справочник по CLI, типам документов, конфигурационным файлам и оформлению. Движок один: интерфейс собирает те же параметры, что и аргументы командной строки.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Основные команды
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m md2gost # окно интерфейса
|
||||||
|
python -m md2gost report.md -o report.docx --type coursework --check
|
||||||
|
python -m md2gost report.md --check-only --type vkr --strict
|
||||||
|
python -m md2gost report.docx -o report.md # импорт Word → Markdown
|
||||||
|
python -m md2gost report.docx --check-pages # проверка вёрстки готового DOCX
|
||||||
|
python -m word2md report.docx -o report.md # то же импортом напрямую
|
||||||
|
python -m md2fodt report.md -o report.fodt # экспорт в формат LibreOffice
|
||||||
|
md2gost-gui # окно интерфейса, точка входа
|
||||||
|
```
|
||||||
|
|
||||||
|
Без имени файла или с ключом `--gui` открывается окно. Windows-сборка: `build-exe.bat` даёт `dist\md2gost.exe`, двойной клик открывает окно, аргументы работают так же.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Типы документов `--type`
|
||||||
|
|
||||||
|
| Тип | Назначение | Нумерация объектов | Источники | Стиль |
|
||||||
|
|-----|-----------|--------------------|-----------|-------|
|
||||||
|
| `practice` (по умолчанию) | отчёт по практике | по разделам: 1.1, 2.3 | 5–7, не старше 5 лет | МИРЭА |
|
||||||
|
| `coursework` | курсовая работа | по разделам | 5–7, не старше 5 лет | МИРЭА |
|
||||||
|
| `vkr` | выпускная квалификационная работа | по разделам | не менее 10 в каждом подразделе списка | МИРЭА |
|
||||||
|
| `APID_coursework` | курсовая «Архитектура приложений и данных» | по разделам | 7–20, не старше 5 лет | МИРЭА |
|
||||||
|
| `PIS_custom` | итоговый отчёт по практическим работам | сквозная: 1, 2, 3 | не требуются | ПИС |
|
||||||
|
|
||||||
|
Что меняет профиль:
|
||||||
|
|
||||||
|
| Свойство | МИРЭА-профили | `PIS_custom` |
|
||||||
|
|----------|---------------|--------------|
|
||||||
|
| H1 | 18 пт, ПРОПИСНЫЕ, слева (СОДЕРЖАНИЕ и СПИСОК — по центру) | 14 пт, ПРОПИСНЫЕ, по центру |
|
||||||
|
| H2 / H3 | 16 пт / 14 пт | 14 пт, по ширине, отступ 1,25 см |
|
||||||
|
| Введение и заключение | обязательны | не требуются |
|
||||||
|
| Список источников | обязателен | не требуется |
|
||||||
|
| Особая структура | у `vkr` — приложение «Графический материал»; у `APID_coursework` — фиксированные заголовки разделов | H1 вида «Практическая работа №N. …» |
|
||||||
|
|
||||||
|
Общее оформление обоих пресетов: Times New Roman 14, интервал 1,5, поля 30/10/20/20 мм, абзацный отступ 1,25 см, выравнивание по ширине, подпись рисунка под ним, надписи таблицы и листинга сверху.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Все ключи командной строки
|
||||||
|
|
||||||
|
### Ввод и вывод
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Смысл |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| `filename` | — | путь к `.md` (сборка DOCX) или `.docx` (импорт в Markdown) |
|
||||||
|
| `-o`, `--output` | рядом с исходником | путь результата |
|
||||||
|
| `-t`, `--template` | встроенный `Template.docx` | свой шаблон DOCX |
|
||||||
|
| `--gui` | — | открыть окно, можно сразу с файлом |
|
||||||
|
| `--type` | `practice` | тип документа |
|
||||||
|
|
||||||
|
### Структура и разметка
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Смысл |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| `--heading-numbering {auto,manual}` | `manual` | `manual` — цифры из markdown, автонумерация Word отключена; `auto` — нумерует Word, цифры из заголовков снимаются |
|
||||||
|
| `--toc {manual,native}` | `native` | `native` — поле Word TOC (обновить при открытии); `manual` — md2gost собирает содержание с номерами страниц |
|
||||||
|
| `--emdash-to-hyphen` | выкл. | заменить все «—» на «-» |
|
||||||
|
| `--hr-pagebreak` | выкл. | строки `---`, `***`, `___` дают разрыв страницы (иначе игнорируются) |
|
||||||
|
| `--page-start N` | сквозная нумерация | начальный номер страницы в колонтитуле тела |
|
||||||
|
|
||||||
|
### Титул, задание, метаданные
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Смысл |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| `--title` | — | готовый DOCX титульного листа; **отключает автогенерацию** |
|
||||||
|
| `--auto-title` | выкл. | собрать титул из `info_conv.yaml` и блока ` ```title ` |
|
||||||
|
| `--assignment` | — | DOCX бланка задания |
|
||||||
|
| `--student`, `--group` | из `md2gost.user.json` | ФИО и группа для автотитула |
|
||||||
|
| `--doc-author-from {os,student,custom}` | `os` | источник автора в свойствах DOCX |
|
||||||
|
| `--doc-author`, `--doc-last-modified-by`, `--doc-title`, `--doc-subject`, `--doc-keywords`, `--doc-comments`, `--doc-category` | — | поля свойств DOCX; пустое `--doc-comments` убирает штамп md2gost |
|
||||||
|
|
||||||
|
### Проверка
|
||||||
|
|
||||||
|
| Ключ | Смысл |
|
||||||
|
|------|-------|
|
||||||
|
| `--check` | проверить ТЗ и напечатать отчёт |
|
||||||
|
| `--check-only` | только проверка, без сборки |
|
||||||
|
| `--strict` | код выхода 1 при ошибках, документ не собирается |
|
||||||
|
| `--check-pages` | эвристическая проверка полупустых страниц через Microsoft Word (нужны Windows, Word, `pywin32`) |
|
||||||
|
|
||||||
|
Полный каталог замечаний — в `checker.md`.
|
||||||
|
|
||||||
|
### Таблицы и листинги через границу страницы
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Значения |
|
||||||
|
|------|--------------|----------|
|
||||||
|
| `--table-continuation` | `word` | `word` — после сохранения Word COM режет по реальной пагинации и подписывает «Продолжение Таблицы N»; `off` и `soft` — одна таблица без автоподписи; `legacy` и `caption` — резать по оценке высоты (возможны артефакты) |
|
||||||
|
| `--listing-continuation` | `word` | те же значения для листингов |
|
||||||
|
| `--table-repeat-header` | выкл. | повторять шапку таблицы на каждом фрагменте после разрыва |
|
||||||
|
|
||||||
|
Режим `word` требует Windows, установленный Microsoft Word и пакет `pywin32`. Без Word — `--table-continuation off`.
|
||||||
|
|
||||||
|
### Диаграммы
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Смысл |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| `--plantuml-jar` | вшитый, иначе `PLANTUML_JAR` | путь к `plantuml.jar` |
|
||||||
|
| `--kroki-url` | `KROKI_URL`, иначе `http://localhost:8000` | локальный Kroki |
|
||||||
|
| `--diagram-fallback {local,remote,off}` | `remote` | что делать при недоступности локального рендера: `remote` — обратиться к `kroki.io`; `local` — ошибка; `off` — не рисовать |
|
||||||
|
| `--diagram-format {png,svg}` | `png` | формат вставки; `svg` даёт вектор с PNG-запасным (Word 2016+) |
|
||||||
|
| `--diagram-scale` | `2` | масштаб растра PlantUML и локального Mermaid; размер на странице как при 1 |
|
||||||
|
| `--schemes` | рядом с приложением или с `.md` | путь к `md2gost.schemes.json` |
|
||||||
|
| `--install-chromium` | — | скачать headless Chromium для Mermaid и выйти |
|
||||||
|
|
||||||
|
### Прочее
|
||||||
|
|
||||||
|
| Ключ | По умолчанию | Смысл |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| `--styles` | пресет типа | путь к `md2gost.styles.json` |
|
||||||
|
| `--syntax-highlighting` | выкл. | подсветка синтаксиса в листингах |
|
||||||
|
| `--debug` | выкл. | отладочные данные в документе |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Импорт Word → Markdown
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m word2md report.docx -o report.md
|
||||||
|
```
|
||||||
|
|
||||||
|
| Ключ | Смысл |
|
||||||
|
|------|-------|
|
||||||
|
| `-o`, `--output` | путь к `.md`, по умолчанию рядом с DOCX |
|
||||||
|
| `--media-dir` | каталог картинок, по умолчанию `<имя>_media` |
|
||||||
|
| `--keep-toc-pages` | сохранить строки содержания Word (иначе остаётся только `[TOC]`) |
|
||||||
|
| `--pagebreaks` | писать `---` на разрывах страниц |
|
||||||
|
|
||||||
|
Что распознаётся: заголовки и спецразделы, содержание, подписи «Рисунок N — …» / «Таблица N» / «Листинг N» (включая склейку «Продолжение…»), таблицы с объединением в `^` и `>`, листинги, формулы OMML в `$$…$$`, библиография `[n]: …`, ссылки `[n]`, часть перекрёстных ссылок восстанавливается как `@Рисунок:fig1_1`.
|
||||||
|
|
||||||
|
Что теряется: исходники PlantUML и Mermaid (остаются только картинки), язык оградки листингов, осмысленные `id` меток, надписи и SmartArt, сноски, плавающие рисунки. Титул и бланк задания до первого заголовка пропускаются, колонтитулы не импортируются.
|
||||||
|
|
||||||
|
После импорта результат имеет смысл довести промптом `ai/prompts/from-word.md` и проверить `--check`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Экспорт в FODT
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m md2fodt report.md -o report.fodt
|
||||||
|
```
|
||||||
|
|
||||||
|
Ключ `--emdash-to-hyphen` работает так же. PDF через LaTeX — каталог `md2latex/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Конфигурационные файлы
|
||||||
|
|
||||||
|
| Файл | Где лежит | Назначение |
|
||||||
|
|------|-----------|------------|
|
||||||
|
| `md2gost.user.json` | рядом с приложением | ФИО, группа, блок `metadata` со свойствами DOCX |
|
||||||
|
| `md2gost.schemes.json` | рядом с приложением, рядом с `.md`, либо путь в `--schemes` | схемы диаграмм: `title`, `docs`, `ai-prompt`, `includes`, `prefix`, `postfix`, `theme` |
|
||||||
|
| `md2gost.styles.json` | рядом с `.md` или путь в `--styles` | оверлей оформления поверх пресета |
|
||||||
|
| `info_conv.yaml` | рядом с `.md` | институт, кафедра, дисциплина, преподаватель, должность |
|
||||||
|
| `.md2gost-cache/` | рядом с `.md` | кэш отрисованных диаграмм |
|
||||||
|
| `md2gost.include-cache.json`, `include-cache/` | рядом с приложением | кэш скачанных `.puml` |
|
||||||
|
|
||||||
|
Приоритет загрузки, где каждый следующий слой сильнее: встроенный шаблон → файл рядом с приложением → файл рядом с `.md` → явный путь в ключе.
|
||||||
|
|
||||||
|
### `info_conv.yaml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Институт: Институт информационных технологий (ИИТ)
|
||||||
|
Кафедра: Кафедра цифровой трансформации (ЦТ)
|
||||||
|
Дисциплина: Проектирование архитектуры цифровой организации
|
||||||
|
Преподаватель: Иванов Иван Иванович
|
||||||
|
Должность: старший преподаватель, кафедра ЦТ
|
||||||
|
```
|
||||||
|
|
||||||
|
Плоский список `ключ: значение` в UTF-8. Строки с `#` — комментарии. ФИО и группа студента из файла **не читаются**: они берутся из профиля или ключей `--student` / `--group`.
|
||||||
|
|
||||||
|
### Автотитул: условия срабатывания
|
||||||
|
|
||||||
|
1. Включён `--auto-title` (или галочка «Автотитул»).
|
||||||
|
2. Не задан готовый `--title`.
|
||||||
|
3. Есть `info_conv.yaml` рядом с `.md` **или** блок ` ```title ` в начале файла.
|
||||||
|
4. Известны ФИО и группа — иначе конвертация останавливается с подсказкой «Для генерации титула нужны ФИО и группа студента».
|
||||||
|
|
||||||
|
Номер работы и год берутся из блока ` ```title ` (`number`, `year`); значения из блока сильнее `info_conv.yaml`. По умолчанию номер `1`, год — текущий.
|
||||||
|
|
||||||
|
### `md2gost.styles.json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"page": { "left_mm": 30, "right_mm": 10, "top_mm": 20, "bottom_mm": 20 },
|
||||||
|
"styles": {
|
||||||
|
"Heading 1": { "alignment": "center", "size_pt": 14, "all_caps": true }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Допустимые имена стилей: `Normal`, `Heading 1`, `Heading 2`, `Heading 3`, `Caption Figure`, `Caption Table`, `Название таблицы`, `Caption Listing`, `Caption`, `Code`, `Table Text`, `Bibliography`, `Bibliography Heading`, `toc 1`, `toc 2`, `toc 3`, `Footer`, `Hyperlink`, `FollowedHyperlink`, `Space After Table`.
|
||||||
|
|
||||||
|
Допустимые поля стиля: `font_name`, `size_pt`, `bold`, `italic`, `all_caps`, `underline`, `alignment` (`left` / `center` / `justify`), `first_line_indent_cm`, `left_indent_cm`, `right_indent_cm`, `space_before_mm`, `space_after_mm`, `line_spacing` (`1.0` / `1.5`), `page_break_before`, `keep_with_next`, `widow_control`.
|
||||||
|
|
||||||
|
Неизвестный ключ или неизвестное имя стиля — ошибка запуска. Не настраивается через JSON: табуляция оглавления, отступы списков, оформление формул, цвет текста (всегда чёрный).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Переменные окружения
|
||||||
|
|
||||||
|
| Переменная | Назначение |
|
||||||
|
|------------|------------|
|
||||||
|
| `PLANTUML_JAR` | путь к `plantuml.jar` |
|
||||||
|
| `KROKI_URL` | адрес локального Kroki, по умолчанию `http://localhost:8000` |
|
||||||
|
| `PLAYWRIGHT_BROWSERS_PATH` | каталог Chromium для Mermaid |
|
||||||
|
| `WORKING_DIR` | родительский каталог кэша диаграмм |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Где что в окне
|
||||||
|
|
||||||
|
| Меню | Содержимое |
|
||||||
|
|------|------------|
|
||||||
|
| Основные | тип документа, выходной путь, нумерация заголовков, содержание, режимы продолжения таблиц и листингов, смещение страниц |
|
||||||
|
| Настройки → Файлы | шаблон, титульный лист, бланк задания, стили JSON |
|
||||||
|
| Настройки → Студент | ФИО и группа (спрашиваются при первом запуске) |
|
||||||
|
| Настройки → Метаданные | свойства DOCX |
|
||||||
|
| Настройки → Диаграммы | PlantUML, Graphviz для DFD, Chromium для Mermaid, Kroki, формат, сброс кэша |
|
||||||
|
| Шаблоны UML | редактор `md2gost.schemes.json` |
|
||||||
|
| Справка | инструкция, документация, схемы, промпт для ИИ |
|
||||||
|
|
||||||
|
Кнопка «Импорт DOCX→MD» и перетаскивание `.docx` запускают импорт; перетаскивание `.md` подставляет файл для сборки.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Установка
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -e .
|
||||||
|
pip install pywin32 # Windows: продолжение таблиц через Word COM
|
||||||
|
```
|
||||||
|
|
||||||
|
Нужен Python 3.10 или новее (для DFD — 3.11 и новее). Для PlantUML нужна Java; для Mermaid — Chrome, Edge или скачиваемый Chromium; для DFD — Graphviz. IDEF0 рисуется локально без внешних зависимостей.
|
||||||
@@ -0,0 +1,587 @@
|
|||||||
|
# Диаграммы в 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. Иерархическая оргсхема и читаемость
|
||||||
|
|
||||||
|
Рисунок, который нельзя прочитать при масштабе 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`.
|
||||||
@@ -0,0 +1,93 @@
|
|||||||
|
# Иерархические схемы в отчёте
|
||||||
|
|
||||||
|
Правила организационной модели и карты процессов верхнего уровня. Нарушение приравнивается преподавателем к отсутствию рисунка или к неверной модели.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Читаемость = наличие рисунка
|
||||||
|
|
||||||
|
Рисунок, который нельзя разобрать при масштабе 100 % в Word (и который не читается даже при увеличении), **считается отсутствующим**.
|
||||||
|
|
||||||
|
Обязательно:
|
||||||
|
|
||||||
|
- крупный кегль подписей: на листе после вставки в DOCX не меньше 10–11 пт;
|
||||||
|
- флаг `+landscape` для широких схем;
|
||||||
|
- не более одной мысли на бокс, без «простыни» из 8-пунктового текста;
|
||||||
|
- чёрные линии на белом, без декоративной заливки, мешающей печати;
|
||||||
|
- если встроенный PlantUML/Mermaid после сборки даёт мелкую кашу — вынести схему в отдельный PNG высокого разрешения (`figsize` 14–18 дюймов по ширине, DPI ≥ 200) и вставить как ``.
|
||||||
|
|
||||||
|
Нельзя сдавать схему, которую «можно рассмотреть, если открыть исходник». Проверяют PDF/DOCX.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Принцип развязки коннектора
|
||||||
|
|
||||||
|
На иерархической оргсхеме **из одного узла выходит одна связь**, которая затем разветвляется на подчинённых (горизонтальная шина / Т-образный коннектор).
|
||||||
|
|
||||||
|
Неправильно: от «Генеральный директор» independently идут 6–8 отдельных линий к каждому департаменту.
|
||||||
|
|
||||||
|
Правильно:
|
||||||
|
|
||||||
|
```text
|
||||||
|
[Родитель]
|
||||||
|
|
|
||||||
|
---------+--------- ← одна развязка
|
||||||
|
| | |
|
||||||
|
[Доч.1] [Доч.2] [Доч.3]
|
||||||
|
```
|
||||||
|
|
||||||
|
В matplotlib / ручной отрисовке: вертикаль вниз от родителя → горизонталь по центрам детей → вертикали в каждый ребёнок.
|
||||||
|
|
||||||
|
В PlantUML не писать пачку `ceo -- a`, `ceo -- b`, `ceo -- c` без общей шины. Либо скрытый стыковочный узел, либо заранее собранный PNG с развязкой.
|
||||||
|
|
||||||
|
Стрелки на оргмодели не нужны: связь иерархическая, не поток.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Полнота подразделения
|
||||||
|
|
||||||
|
Если на схеме есть **отдел / департамент / направление**, у него изображаются:
|
||||||
|
|
||||||
|
1. руководитель (начальник отдела, руководитель направления, директор по функции);
|
||||||
|
2. специалисты операционного уровня.
|
||||||
|
|
||||||
|
Нельзя оставлять бокс «Отдел выпуска» с одним «специалистом» и без начальника. Нельзя оставлять бокс направления без людей: пустое имя подразделения приравнивается к неполной структуре.
|
||||||
|
|
||||||
|
Типовые наименования брать из справочника должностей, не выдумывать креатив. Фамилии не писать — только должности.
|
||||||
|
|
||||||
|
Детализация:
|
||||||
|
|
||||||
|
- подразделение, где сидят исполнители выбранного процесса, — до начальников участков и операционных специалистов;
|
||||||
|
- прочие направления — типовой минимум: руководитель + специалист;
|
||||||
|
- элементы, которые не понадобятся процессу, на схему не выносить, но то, что вынесено, должно быть полным.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Карта процессов верхнего уровня
|
||||||
|
|
||||||
|
- Группы процессов (основные, обеспечивающие, развития; управление — только если этого требует задание).
|
||||||
|
- Внутри группы — наименования направлений, не клики и не технология выполнения.
|
||||||
|
- Стрелок последовательности на карте верхнего уровня нет.
|
||||||
|
- Предмет последующего исследования можно отметить сноской на элементе, без разбора узкого места: узкое место относится к пункту про процесс.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Каркас иерархии (PNG)
|
||||||
|
|
||||||
|
```text
|
||||||
|
Генеральный директор
|
||||||
|
|
|
||||||
|
---------------------+---------------------
|
||||||
|
| | | | |
|
||||||
|
Рук. направл. Рук. сети Рук. направл. … Рук. службы
|
||||||
|
(процессное) СЦ (типовое)
|
||||||
|
|
|
||||||
|
-----+-----
|
||||||
|
| | |
|
||||||
|
Нач. Нач. Нач.
|
||||||
|
участка
|
||||||
|
|
|
||||||
|
Специалист
|
||||||
|
```
|
||||||
|
|
||||||
|
Подписи — должность и принадлежность («специалист центра регистрации»), не «владелец процесса» и не комментарий для преподавателя.
|
||||||
@@ -0,0 +1,459 @@
|
|||||||
|
# Диалект Markdown md2gost — полная спецификация
|
||||||
|
|
||||||
|
Справочник синтаксиса конвертера md2gost (Markdown → DOCX по ГОСТ 7.32-2017 и ТЗ РТУ МИРЭА). Всё, что здесь описано, извлечено из кода парсера, нумератора и проверки, а не из пользовательских инструкций.
|
||||||
|
|
||||||
|
Базовый парсер — Marko с расширением GFM. Всё, что не перечислено ниже как расширение, работает как обычный GitHub Flavored Markdown.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Расширения относительно обычного Markdown
|
||||||
|
|
||||||
|
| Конструкция | Смысл |
|
||||||
|
|-------------|-------|
|
||||||
|
| `# *ЗАГОЛОВОК` | раздел без автоматической нумерации |
|
||||||
|
| `[TOC]` | точка сборки содержания |
|
||||||
|
| `%id Подпись` | метка и подпись следующего объекта |
|
||||||
|
| `` | метка и подпись рисунка-файла |
|
||||||
|
| `@Тип:id` | перекрёстная ссылка с автоподстановкой номера |
|
||||||
|
| `[1]: описание` | запись списка источников |
|
||||||
|
| `[1]`, `[2, 3]`, `[2, c. 21-25]` | ссылка на источник в тексте |
|
||||||
|
| `^` / `>` в ячейке таблицы | объединение ячеек |
|
||||||
|
| ` ```uml `, ` ```mermaid `, ` ```idef0 `, ` ```dfd `, ` ```uml-<схема>` | диаграмма, отрисовываемая конвертером |
|
||||||
|
| ` ```title ` | данные для автогенерации титульного листа |
|
||||||
|
| `+listing`, `+landscape` в строке `%` | флаги оформления объекта |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Заголовки
|
||||||
|
|
||||||
|
Синтаксис: от нуля до трёх ведущих пробелов, затем `#`…`######`, пробел, текст.
|
||||||
|
|
||||||
|
Регулярное выражение парсера: `^ {0,3}(#{1,6})((?=\s)[^\n]*?|[^\n\S]*)(?:(?<=\s)(?<!\\)#+)?[^\n\S]*$`
|
||||||
|
|
||||||
|
**Звёздочка** первым непробельным символом текста заголовка делает раздел ненумерованным и удаляется из видимого текста:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# *ВВЕДЕНИЕ → раздел без номера
|
||||||
|
# 1 Анализ → нумерованный раздел
|
||||||
|
```
|
||||||
|
|
||||||
|
Пробел после `#` обязателен для корректной работы проверки (`^(#{1,6})\s+(\*?)(.+)$`).
|
||||||
|
|
||||||
|
### Спецразделы
|
||||||
|
|
||||||
|
Распознаются по тексту заголовка, приведённому к прописным. Список из кода проверки:
|
||||||
|
|
||||||
|
`СОДЕРЖАНИЕ`, `ВВЕДЕНИЕ`, `ЗАКЛЮЧЕНИЕ`, `СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`, `СПИСОК ИСПОЛЬЗУЕМЫХ ИСТОЧНИКОВ`, `ПРИЛОЖЕНИЕ`, `ПРИЛОЖЕНИЯ`, а также любой заголовок, начинающийся на `ПРИЛОЖЕН`.
|
||||||
|
|
||||||
|
Для H1 из этого набора звёздочка обязательна — иначе ошибка `heading.numbered_special`.
|
||||||
|
|
||||||
|
Оформление в DOCX:
|
||||||
|
|
||||||
|
| Заголовок H1 | Выравнивание |
|
||||||
|
|--------------|--------------|
|
||||||
|
| `СОДЕРЖАНИЕ`, `СПИСОК ИСПОЛЬЗОВАННЫХ/ИСПОЛЬЗУЕМЫХ ИСТОЧНИКОВ` | по центру |
|
||||||
|
| `ВВЕДЕНИЕ`, `ЗАКЛЮЧЕНИЕ`, `ПРИЛОЖЕНИЯ`, нумерованные разделы | слева с абзацным отступом |
|
||||||
|
|
||||||
|
`СОДЕРЖАНИЕ` исключается из собираемого оглавления.
|
||||||
|
|
||||||
|
### Нумерация заголовков
|
||||||
|
|
||||||
|
| Режим CLI | Поведение |
|
||||||
|
|-----------|-----------|
|
||||||
|
| `--heading-numbering manual` (по умолчанию) | цифры остаются из markdown: `# 1 …`, `## 1.1 …`; автонумерация Word отключена |
|
||||||
|
| `--heading-numbering auto` | ведущие цифры (`^\d+(?:\.\d+)*\.?\s+`) снимаются с текста заголовка, номера ставит многоуровневый список Word |
|
||||||
|
|
||||||
|
При `manual` номера пиши сам. При `auto` их можно не писать — но безопаснее всегда писать и запускать конвертер в `manual`.
|
||||||
|
|
||||||
|
### `[TOC]`
|
||||||
|
|
||||||
|
Блочный элемент, шаблон `\[(TOC)\]+`. **Только прописными** — `[toc]` не распарсится (хотя проверка его увидит и замечания не выдаст). Ставится отдельной строкой, обычно сразу под `# *СОДЕРЖАНИЕ`.
|
||||||
|
|
||||||
|
Режимы сборки: `--toc native` (по умолчанию, поле Word, обновляется при открытии документа) и `--toc manual` (md2gost сам считает страницы).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Метки объектов: строка `%`
|
||||||
|
|
||||||
|
Шаблон: `\%(\w+)( (.+))?` — блочный элемент, прерывает открытый абзац.
|
||||||
|
|
||||||
|
- `id` = `\w+`: буквы, цифры, `_`. **Дефис, точка, пробел внутри `id` недопустимы.** Практическое правило: `[A-Za-z][A-Za-z0-9_]*`.
|
||||||
|
- Подпись необязательна: `%eq1` — валидная строка.
|
||||||
|
- Метка применяется к **следующему непустому блоку**. Пустые строки между меткой и объектом допустимы.
|
||||||
|
- Если подряд идут две метки, к объекту привяжется вторая.
|
||||||
|
- `%` в середине абзаца — обычный текст, не метка.
|
||||||
|
|
||||||
|
### Флаги в строке подписи
|
||||||
|
|
||||||
|
Шаблоны: `(?i)(?:^|\s)\+?listing\b` и `(?i)(?:^|\s)\+?landscape\b`.
|
||||||
|
|
||||||
|
| Флаг | Действие |
|
||||||
|
|------|----------|
|
||||||
|
| `+listing` | у диаграммы дополнительно выводится Листинг с её исходником (получает свой номер) |
|
||||||
|
| `+landscape` | объект размещается на альбомной странице |
|
||||||
|
|
||||||
|
Важные следствия из регулярных выражений:
|
||||||
|
|
||||||
|
1. Плюс необязателен: `listing` без плюса тоже сработает как флаг.
|
||||||
|
2. Регистр не важен: `+Landscape` = `+landscape`.
|
||||||
|
3. Флаги вырезаются из текста подписи в любом месте строки. **Поэтому подпись не должна содержать самостоятельных слов `listing` и `landscape`** — они исчезнут из подписи, а объект получит нежелательное оформление.
|
||||||
|
|
||||||
|
### Метка рисунка-файла
|
||||||
|
|
||||||
|
Метка задаётся в title изображения:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
Тот же шаблон `%(\w+)( (.+))?` и те же флаги.
|
||||||
|
|
||||||
|
### Куда попадает подпись
|
||||||
|
|
||||||
|
| Объект | Положение подписи в DOCX |
|
||||||
|
|--------|--------------------------|
|
||||||
|
| Рисунок и диаграмма | под объектом |
|
||||||
|
| Таблица | надпись над таблицей |
|
||||||
|
| Листинг | надпись над листингом |
|
||||||
|
| Формула | номер в скобках справа от формулы |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Перекрёстные ссылки `@Тип:id`
|
||||||
|
|
||||||
|
Шаблон: `@(\w+):(\w+)`. Пробелы вокруг двоеточия недопустимы. Знаки препинания после ссылки не съедаются, поэтому `@Рисунок:arch.` и `@Таблица:cmp,` работают корректно.
|
||||||
|
|
||||||
|
Принимаемые типы (регистр не важен при разрешении ссылки):
|
||||||
|
|
||||||
|
| Тип | Синонимы |
|
||||||
|
|-----|----------|
|
||||||
|
| `Рисунок` | `figure` |
|
||||||
|
| `Таблица` | `table` |
|
||||||
|
| `Листинг` | `listing` |
|
||||||
|
| `Формула` | `formula`, `equation` |
|
||||||
|
|
||||||
|
В документе ссылка разворачивается в «Тип Номер», например `Рисунок 1.1`. Неизвестная метка даёт в тексте `Рисунок?` — визуальный маркер ошибки; проверка сообщает `ref.dangling`.
|
||||||
|
|
||||||
|
Каноническая форма — русские названия: `@Рисунок:id`, `@Таблица:id`, `@Листинг:id`, `@Формула:id`.
|
||||||
|
|
||||||
|
### Соответствие меток и ссылок
|
||||||
|
|
||||||
|
Проверка сверяет два множества:
|
||||||
|
|
||||||
|
- метки — из `^%(\w+)` и из title картинок;
|
||||||
|
- ссылки — из `@[\wА-Яа-я]+:(\w+)`.
|
||||||
|
|
||||||
|
Метка без ссылки → предупреждение `ref.unused`. Ссылка без метки → ошибка `ref.dangling`. Правило простое: **сколько меток, столько и адресатов ссылок**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Нумерация объектов
|
||||||
|
|
||||||
|
Области нумерации задаются профилем `--type`:
|
||||||
|
|
||||||
|
| Область | Профили | Вид номера |
|
||||||
|
|---------|---------|------------|
|
||||||
|
| `section` | `practice`, `coursework`, `vkr`, `APID_coursework` | `1.1`, `2.3`; в приложении — `Б.1` |
|
||||||
|
| `continuous` | `PIS_custom` | `1`, `2`, `3` на весь документ |
|
||||||
|
|
||||||
|
Счётчик раздела увеличивается только на **нумерованных H1** (то есть на `# 1 …`, а не на `# *ВВЕДЕНИЕ`).
|
||||||
|
|
||||||
|
Номер получают все объекты **кроме формул**: формуле номер присваивается, только если в исходном тексте есть `@Формула:id` (или `@Formula:id`) с её меткой. Формула без ссылки остаётся без номера.
|
||||||
|
|
||||||
|
Диаграмма с флагом `+listing` получает два номера под одной меткой: номер Рисунка и номер Листинга. Ссылки `@Рисунок:id` и `@Листинг:id` разрешатся каждая в свой номер.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Таблицы
|
||||||
|
|
||||||
|
Синтаксис GFM: строка заголовков, строка-разделитель, строки данных. Выравнивание через `:---`, `:---:`, `---:` поддерживается. Экранированный `\|` не считается границей столбца.
|
||||||
|
|
||||||
|
### Объединение ячеек
|
||||||
|
|
||||||
|
| Маркер | Смысл |
|
||||||
|
|--------|-------|
|
||||||
|
| `^` или `^^` | ячейка — продолжение ячейки **сверху** (rowspan) |
|
||||||
|
| `>` или `>>` | ячейка — продолжение ячейки **слева** (colspan) |
|
||||||
|
|
||||||
|
Маркер должен быть **единственным** содержимым ячейки после обрезки пробелов. Ограничения проверки: маркеры запрещены в строке заголовков (`table.merge_header`), `>` запрещён в первом столбце (`table.merge_col`).
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
%tab_req Требования к системе
|
||||||
|
|
||||||
|
| Категория | Требование |
|
||||||
|
|-----------|------------|
|
||||||
|
| Производительность | обработка 1000 заявок в час |
|
||||||
|
| ^ | время отклика не более 2 с |
|
||||||
|
| Надёжность | доступность 99,5 % |
|
||||||
|
```
|
||||||
|
|
||||||
|
### Правила ТЗ
|
||||||
|
|
||||||
|
- Графа «№ п/п» запрещена (`table.nopp`, шаблон `№\s*п\s*/\s*п`).
|
||||||
|
- Таблицу из одной строки данных не оформляют таблицей.
|
||||||
|
- Таблицы и рисунки не размещают внутри списков.
|
||||||
|
|
||||||
|
### Продолжение на следующей странице
|
||||||
|
|
||||||
|
DOCX не умеет сам подписывать «Продолжение Таблицы N». Режимы `--table-continuation` и `--listing-continuation`: `word` (по умолчанию; после сохранения Word COM режет по реальной пагинации), `off`, `soft`, `legacy`, `caption`. Режим `word` требует Windows, Microsoft Word и пакет `pywin32`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Листинги
|
||||||
|
|
||||||
|
Любой fenced-блок с языком, который **не** является языком диаграммы, становится Листингом.
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
%code_volume Процедура расчёта объёма
|
||||||
|
|
||||||
|
```python
|
||||||
|
def volume(count: int, size: float) -> float:
|
||||||
|
return count * size
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Подсветка синтаксиса включается ключом `--syntax-highlighting` (по умолчанию выключена).
|
||||||
|
|
||||||
|
### Ловушка: автозамена внутри кода
|
||||||
|
|
||||||
|
Препроцессор применяет типографские правки ко всему тексту, **исключая только блоки диаграмм**. Блоки кода не защищены:
|
||||||
|
|
||||||
|
| В исходнике | В DOCX |
|
||||||
|
|-------------|--------|
|
||||||
|
| `print("hello")` | `print(«hello»)` |
|
||||||
|
| `x = a - b` | `x = a — b` |
|
||||||
|
|
||||||
|
Обход: одинарные кавычки в примерах кода и вычитание без пробелов (`a-b`). Ключ `--emdash-to-hyphen` меняет направление замены тире, но кавычки правит всегда.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Формулы
|
||||||
|
|
||||||
|
| Форма | Шаблон | Назначение |
|
||||||
|
|-------|--------|------------|
|
||||||
|
| Выключная | `\$\$([\S\s]*?)\$\$` | отдельный блок, нумеруемая формула |
|
||||||
|
| Инлайновая | `\$(.*?)\$` | обозначения в тексте: `$N$` |
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
%eq_volume
|
||||||
|
$$
|
||||||
|
V = N \times S
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $N$ — число записей; $S$ — средний размер записи, байт.
|
||||||
|
|
||||||
|
Оценка по (@Формула:eq_volume) используется при выборе хранилища.
|
||||||
|
```
|
||||||
|
|
||||||
|
Номер присваивается только при наличии ссылки. Расшифровка обозначений начинается со слова «где» без двоеточия.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Диаграммы
|
||||||
|
|
||||||
|
Fenced-блок с языком диаграммы превращается в Рисунок; исходник отрисовывается конвертером.
|
||||||
|
|
||||||
|
### Встроенные языки
|
||||||
|
|
||||||
|
| Оградка | Движок |
|
||||||
|
|---------|--------|
|
||||||
|
| `uml`, `plantuml` | PlantUML (java + `plantuml.jar`, иначе Kroki) |
|
||||||
|
| `mermaid`, `mmd` | локальный Mermaid (браузер / QuickJS), иначе Kroki |
|
||||||
|
| `idef0`, `uml-idef0` | локальный рендер на Pillow, без Java и сети |
|
||||||
|
| `dfd`, `uml-dfd`, `data-flow-diagram`, `yourdon`, `uml-yourdon` | пакет `data-flow-diagram` + Graphviz, иначе Kroki |
|
||||||
|
|
||||||
|
### Схемы из `md2gost.schemes.json`
|
||||||
|
|
||||||
|
Оградка `uml-<id>` или просто `<id>`, где `<id>` — идентификатор схемы (`^[a-z][a-z0-9_]*$`). Встроенные схемы:
|
||||||
|
|
||||||
|
| id | Что это | Оградка |
|
||||||
|
|----|---------|---------|
|
||||||
|
| `c4` | C4 Container | ` ```uml-c4 ` / ` ```c4 ` |
|
||||||
|
| `c4context` | C4 System Context | ` ```uml-c4context ` |
|
||||||
|
| `c4component` | C4 Component | ` ```uml-c4component ` |
|
||||||
|
| `usecase` | UML Use Case | ` ```uml-usecase ` / ` ```usecase ` |
|
||||||
|
| `archimate` | ArchiMate 3.2 | ` ```uml-archimate ` / ` ```archimate ` |
|
||||||
|
|
||||||
|
В теле схемы пишутся **только макросы**: обёртку `@startuml` … `@enduml` и `!include` подставляет схема. В блоке ` ```uml ` наоборот — `@startuml` … `@enduml` обязательны.
|
||||||
|
|
||||||
|
Неизвестный `uml-<id>` даёт ошибку рендера: `Схема диаграммы «<id>» не найдена`.
|
||||||
|
|
||||||
|
Подробный синтаксис всех нотаций — в `diagrams.md`, ArchiMate — в `archimate.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Источники
|
||||||
|
|
||||||
|
### Запись списка
|
||||||
|
|
||||||
|
Шаблон строки: `^\[(\d+(?:\.\d+)?)\]:\s*(.+)$`
|
||||||
|
|
||||||
|
Записи размещаются под заголовком, совпадающим с `^#\s*\*?\s*СПИСОК\s+ИСПОЛЬЗОВАНН?ЫХ\s+ИСТОЧНИКОВ\s*$` — то есть «СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ» или «СПИСОК ИСПОЛЬЗУЕМЫХ ИСТОЧНИКОВ».
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
[1]: Иванов И. И. Проектирование информационных систем: учебник. — М.: Инфра-М, 2023. — 320 с.
|
||||||
|
|
||||||
|
[2]: ГОСТ 7.32-2017. Отчёт о научно-исследовательской работе. — М.: Стандартинформ, 2018. — 32 с.
|
||||||
|
```
|
||||||
|
|
||||||
|
Препроцессор сам расставит пустые строки между записями, но безопаснее писать их сразу.
|
||||||
|
|
||||||
|
Для ВКР список делится подразделами `##`; ключ записи получает вид `[1.5]` — номер раздела и номер внутри раздела.
|
||||||
|
|
||||||
|
### Ссылка в тексте
|
||||||
|
|
||||||
|
Шаблон: `\[(\d+(?:\.\d+)?(?:\s*,\s*\d+(?:\.\d+)?)*)(?:\s*,\s*[cс]\.\s*[\d\-–]+)?\]`
|
||||||
|
|
||||||
|
| Форма | Пример |
|
||||||
|
|-------|--------|
|
||||||
|
| одиночная | `[1]`, `[1.5]` |
|
||||||
|
| перечисление | `[2, 3]`, `[2,3]` — **нельзя** писать `[2], [3]` |
|
||||||
|
| с указанием страниц | `[2, c. 21-25]`, `[2.18, с. 21–25]` — буква `c` латинская или русская |
|
||||||
|
|
||||||
|
В DOCX номер становится внутренней гиперссылкой на запись списка.
|
||||||
|
|
||||||
|
Сноски `[^1]` запрещены (`footnote`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Приложения
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
Приложение А — Листинг модуля обработки заявок
|
||||||
|
Приложение Б — Схема базы данных
|
||||||
|
|
||||||
|
## Приложение А Листинг модуля обработки заявок
|
||||||
|
|
||||||
|
## Приложение Б Схема базы данных
|
||||||
|
```
|
||||||
|
|
||||||
|
- Заголовок приложения распознаётся шаблоном `^ПРИЛОЖЕНИЕ\s+([А-ЯA-ZЁ])(?:\s+(.+))?$` без учёта регистра. Оформляется как Heading 3 по центру с разрывом страницы; название — отдельной строкой под ним.
|
||||||
|
- Допустимые буквы: `АБВГДЕЖИКЛМНПРСТУФХЦШЩЭЮЯ`. Запрещённые: `Ё З Й О Ч Ь Ы Ъ` (ошибка `appendix.letter`).
|
||||||
|
- Если букву не указать или указать запрещённую, конвертер подставит следующую допустимую по порядку.
|
||||||
|
- При двух и более приложениях после `# *ПРИЛОЖЕНИЯ` нужен перечень обычным текстом, иначе предупреждение `appendix.toc`. Если перечня нет, конвертер вставит его сам, но лучше писать явно.
|
||||||
|
- Объекты внутри приложения нумеруются с буквой приложения: `Рисунок Б.1`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Блок ` ```title `
|
||||||
|
|
||||||
|
Первый блок с оградкой `title` в файле вырезается до разбора markdown и используется для автогенерации титульного листа (только при `--auto-title`).
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
```title
|
||||||
|
number: 1
|
||||||
|
year: 2026
|
||||||
|
```
|
||||||
|
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
````
|
||||||
|
|
||||||
|
Тело — плоские строки `ключ: значение`. Принимаемые ключи:
|
||||||
|
|
||||||
|
| Поле | Ключи |
|
||||||
|
|------|-------|
|
||||||
|
| Институт | `institute`, `институт`, `инститиут` |
|
||||||
|
| Кафедра | `department`, `кафедра` |
|
||||||
|
| Дисциплина | `discipline`, `дисциплина` |
|
||||||
|
| Преподаватель | `teacher`, `преподаватель`, `преподователь` |
|
||||||
|
| Должность преподавателя | `teacher_position`, `должность`, `должность преподавателя` |
|
||||||
|
| Номер работы | `number`, `номер`, `№`, `n` — по умолчанию `1` |
|
||||||
|
| Год | `year`, `год` — по умолчанию текущий |
|
||||||
|
|
||||||
|
ФИО и группа студента **из блока не читаются**: они берутся из профиля приложения или ключей `--student` / `--group`.
|
||||||
|
|
||||||
|
Остальные академические поля можно держать в файле `info_conv.yaml` рядом с `.md`; значения из блока ` ```title ` сильнее.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Автоматические правки текста
|
||||||
|
|
||||||
|
Препроцессор применяет ко всему тексту, **кроме блоков диаграмм**:
|
||||||
|
|
||||||
|
| Правило | Было | Стало |
|
||||||
|
|---------|------|-------|
|
||||||
|
| Русские кавычки | `"текст"` | `«текст»` |
|
||||||
|
| Тире вместо дефиса между словами | `слово - слово` | `слово — слово` |
|
||||||
|
| Разделение записей списка источников | склеенные строки `[n]:` | каждая записью-абзацем |
|
||||||
|
|
||||||
|
Кавычки не заменяются, если содержимое начинается с `%` (защита строк подписей).
|
||||||
|
|
||||||
|
Ключ `--emdash-to-hyphen` включает обратную замену: все `—` становятся `-`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Прочее
|
||||||
|
|
||||||
|
| Конструкция | Поведение |
|
||||||
|
|-------------|-----------|
|
||||||
|
| `---`, `***`, `___` | по умолчанию **игнорируются**; с ключом `--hr-pagebreak` дают разрыв страницы |
|
||||||
|
| Обычные `**жирный**`, `*курсив*`, `` `код` ``, ссылки, списки | работают как в GFM |
|
||||||
|
| HTML-блоки | не поддерживаются, вставляются как предупреждение в документ |
|
||||||
|
| Комментарии | синтаксиса комментариев нет |
|
||||||
|
| Заголовок глубже `###` | парсится, но в оформлении ТЗ не предусмотрен |
|
||||||
|
| Дефис в обычном тексте | превращается в неразрывный дефис |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Полный минимальный пример
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# *ВВЕДЕНИЕ
|
||||||
|
|
||||||
|
Цель работы — спроектировать модуль учёта заявок.
|
||||||
|
|
||||||
|
# 1 Анализ предметной области
|
||||||
|
|
||||||
|
Обобщённая архитектура приведена на @Рисунок:fig_arch.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Сравнение подходов сведено в @Таблица:tab_cmp.
|
||||||
|
|
||||||
|
%tab_cmp Сравнение подходов к реализации
|
||||||
|
|
||||||
|
| Подход | Трудоёмкость | Гибкость |
|
||||||
|
|--------|--------------|----------|
|
||||||
|
| Монолит | низкая | низкая |
|
||||||
|
| Микросервисы | высокая | высокая |
|
||||||
|
|
||||||
|
Модульная структура описана в источнике [1].
|
||||||
|
|
||||||
|
# 2 Проектирование
|
||||||
|
|
||||||
|
Оценка объёма данных выполняется по (@Формула:eq_volume).
|
||||||
|
|
||||||
|
%eq_volume
|
||||||
|
$$
|
||||||
|
V = N \times S
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $N$ — число записей; $S$ — средний размер записи, байт.
|
||||||
|
|
||||||
|
Реализация приведена в @Листинг:code_volume.
|
||||||
|
|
||||||
|
%code_volume Процедура расчёта объёма
|
||||||
|
|
||||||
|
```python
|
||||||
|
def volume(count: int, size: float) -> float:
|
||||||
|
return count * size
|
||||||
|
```
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
Спроектирован модуль учёта заявок, оценён объём хранилища.
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
[1]: Иванов И. И. Проектирование информационных систем: учебник. — М.: Инфра-М, 2023. — 320 с.
|
||||||
|
~~~
|
||||||
@@ -0,0 +1,281 @@
|
|||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# *ВВЕДЕНИЕ
|
||||||
|
|
||||||
|
Обслуживание парка оборудования в производственных подразделениях опирается на заявки, которые до сих пор часто передаются по телефону и фиксируются в электронных таблицах. При таком порядке теряется история обращений, а срок реакции зависит от загруженности диспетчера.
|
||||||
|
|
||||||
|
Объектом работы является процесс приёма и исполнения заявок на техническое обслуживание. Предмет работы — архитектура и программная реализация модуля учёта таких заявок.
|
||||||
|
|
||||||
|
Цель работы — спроектировать и реализовать модуль учёта заявок, обеспечивающий регистрацию обращений, контроль сроков исполнения и хранение истории обслуживания.
|
||||||
|
|
||||||
|
Для достижения цели решаются следующие задачи:
|
||||||
|
|
||||||
|
1. Проанализировать процесс обработки заявок и существующие решения для его автоматизации.
|
||||||
|
2. Сформировать требования к модулю и спроектировать его архитектуру и модель данных.
|
||||||
|
3. Реализовать ключевые функции модуля и оценить объём хранилища.
|
||||||
|
|
||||||
|
В работе применяются структурный анализ процессов, объектно-ориентированное моделирование в нотации UML и сравнительный анализ программных решений.
|
||||||
|
|
||||||
|
# 1 Анализ процесса обработки заявок
|
||||||
|
|
||||||
|
## 1.1 Описание процесса и его участников
|
||||||
|
|
||||||
|
В обработке заявки участвуют три роли: инициатор со стороны производственного подразделения, диспетчер службы обслуживания и исполнитель. Инициатор сообщает о неисправности, диспетчер регистрирует обращение и назначает исполнителя, исполнитель выполняет работы и закрывает заявку.
|
||||||
|
|
||||||
|
Границы автоматизируемого процесса и его внешние интерфейсы приведены на @Рисунок:idef_a0.
|
||||||
|
|
||||||
|
%idef_a0 Контекстная диаграмма процесса обслуживания
|
||||||
|
|
||||||
|
```idef0
|
||||||
|
title Обработать заявку на обслуживание
|
||||||
|
node A-0
|
||||||
|
number 1
|
||||||
|
project Модуль учёта заявок
|
||||||
|
context TOP
|
||||||
|
|
||||||
|
[A0] Обработать заявку на обслуживание
|
||||||
|
<- Обращение инициатора
|
||||||
|
^ Регламент технического обслуживания
|
||||||
|
-> Закрытая заявка с отметкой о работах
|
||||||
|
v Служба обслуживания
|
||||||
|
```
|
||||||
|
|
||||||
|
Наблюдение за работой диспетчера в течение недели дало следующие показатели: в среднем 42 обращения в сутки, среднее время регистрации 6 минут, доля обращений с неполными сведениями об оборудовании 18 %. Именно неполнота сведений вызывает повторное обращение к инициатору и удлиняет реакцию на заявку.
|
||||||
|
|
||||||
|
## 1.2 Сравнение существующих решений
|
||||||
|
|
||||||
|
Для автоматизации процесса рассматривались три варианта: универсальная система управления обслуживанием, модуль в составе используемой на предприятии учётной системы и собственная разработка. Критериями сравнения выбраны стоимость владения, возможность интеграции со справочником оборудования и трудоёмкость внедрения [1].
|
||||||
|
|
||||||
|
Результаты сравнения сведены в @Таблица:tab_cmp.
|
||||||
|
|
||||||
|
%tab_cmp Сравнение вариантов автоматизации процесса
|
||||||
|
|
||||||
|
| Вариант | Стоимость владения | Интеграция со справочником | Трудоёмкость внедрения |
|
||||||
|
|---------|--------------------|----------------------------|------------------------|
|
||||||
|
| Универсальная система обслуживания | высокая | через файловый обмен | средняя |
|
||||||
|
| Модуль учётной системы | средняя | штатная | высокая |
|
||||||
|
| Собственная разработка | низкая | по REST | низкая |
|
||||||
|
|
||||||
|
Универсальная система покрывает больше сценариев, чем требуется подразделению, и вносит внешний файловый обмен, который сам становится источником расхождений [2]. Модуль учётной системы обеспечивает штатную интеграцию, но его доработка требует привлечения поставщика. Собственная разработка выбрана как вариант, закрывающий требования при наименьшей трудоёмкости.
|
||||||
|
|
||||||
|
## 1.3 Требования к модулю
|
||||||
|
|
||||||
|
Требования сгруппированы по категориям и приведены в @Таблица:tab_req. Формулировки нефункциональных требований опираются на рекомендации по описанию качества программных систем [3].
|
||||||
|
|
||||||
|
%tab_req Требования к модулю учёта заявок
|
||||||
|
|
||||||
|
| Категория | Требование |
|
||||||
|
|-----------|------------|
|
||||||
|
| Функциональные | регистрация заявки с привязкой к единице оборудования |
|
||||||
|
| ^ | назначение исполнителя и контроль срока |
|
||||||
|
| ^ | хранение истории обслуживания единицы оборудования |
|
||||||
|
| Производительность | обработка 100 заявок в час при 20 одновременных пользователях |
|
||||||
|
| ^ | время отклика интерфейса не более 2 с |
|
||||||
|
| Надёжность | доступность не ниже 99,5 % в рабочие часы |
|
||||||
|
| Интеграция | получение справочника оборудования по REST |
|
||||||
|
|
||||||
|
Ограничения проекта: развёртывание в контуре предприятия, единая аутентификация через корпоративную службу, хранение данных не менее трёх лет.
|
||||||
|
|
||||||
|
# 2 Проектирование модуля
|
||||||
|
|
||||||
|
## 2.1 Архитектура модуля
|
||||||
|
|
||||||
|
Модуль спроектирован по трёхуровневой схеме: клиентское приложение, сервис прикладной логики и хранилище. Такое разделение позволяет обновлять правила обработки заявок без изменения клиента [4].
|
||||||
|
|
||||||
|
Контейнерная структура модуля приведена на @Рисунок:c4_containers.
|
||||||
|
|
||||||
|
%c4_containers Контейнеры модуля учёта заявок +landscape
|
||||||
|
|
||||||
|
```uml-c4
|
||||||
|
Person(dispatcher, "Диспетчер", "Регистрирует и распределяет заявки")
|
||||||
|
Person(worker, "Исполнитель", "Выполняет работы по заявке")
|
||||||
|
System_Boundary(app, "Модуль учёта заявок") {
|
||||||
|
Container(spa, "Веб-клиент", "React", "Интерфейс диспетчера и исполнителя")
|
||||||
|
Container(api, "Сервис заявок", "FastAPI", "Правила обработки и контроль сроков")
|
||||||
|
ContainerDb(db, "Хранилище заявок", "PostgreSQL", "Заявки, работы, история")
|
||||||
|
}
|
||||||
|
System_Ext(equip, "Справочник оборудования", "Учётная система предприятия")
|
||||||
|
System_Ext(sso, "Корпоративная служба входа", "Единая аутентификация")
|
||||||
|
|
||||||
|
Rel(dispatcher, spa, "Регистрирует заявки", "HTTPS")
|
||||||
|
Rel(worker, spa, "Отмечает выполнение", "HTTPS")
|
||||||
|
Rel(spa, api, "Вызывает методы", "REST/JSON")
|
||||||
|
Rel(api, db, "Читает и пишет", "SQL")
|
||||||
|
Rel(api, equip, "Запрашивает единицы оборудования", "REST")
|
||||||
|
Rel(spa, sso, "Аутентифицирует пользователя", "OIDC")
|
||||||
|
```
|
||||||
|
|
||||||
|
Справочник оборудования остаётся во внешней учётной системе: дублирование его в модуле привело бы к расхождению данных при выводе оборудования из эксплуатации.
|
||||||
|
|
||||||
|
## 2.2 Модель данных
|
||||||
|
|
||||||
|
Логическая модель данных охватывает три сущности: заявку, работу по заявке и запись истории обслуживания. Единица оборудования в модуле не хранится, вместо неё сохраняется её идентификатор во внешнем справочнике.
|
||||||
|
|
||||||
|
Модель данных приведена на @Рисунок:erd.
|
||||||
|
|
||||||
|
%erd Логическая модель данных модуля
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
hide circle
|
||||||
|
skinparam linetype ortho
|
||||||
|
|
||||||
|
entity "Заявка" as request {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* equipment_ref : varchar(32)
|
||||||
|
* created_at : timestamp
|
||||||
|
* due_at : timestamp
|
||||||
|
* status : varchar(16)
|
||||||
|
description : text
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Работа" as work {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* request_id : bigint <<FK>>
|
||||||
|
* performer : varchar(128)
|
||||||
|
* started_at : timestamp
|
||||||
|
finished_at : timestamp
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Запись истории" as history {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* request_id : bigint <<FK>>
|
||||||
|
* changed_at : timestamp
|
||||||
|
* old_status : varchar(16)
|
||||||
|
* new_status : varchar(16)
|
||||||
|
}
|
||||||
|
|
||||||
|
request ||--o{ work
|
||||||
|
request ||--o{ history
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
Статус заявки хранится строкой из фиксированного набора значений, а не ссылкой на справочник: набор состояний определяется регламентом обслуживания и меняется вместе с версией модуля.
|
||||||
|
|
||||||
|
## 2.3 Оценка объёма хранилища
|
||||||
|
|
||||||
|
Объём данных за период эксплуатации оценивается произведением числа записей на средний размер записи с учётом коэффициента служебных структур базы данных [5].
|
||||||
|
|
||||||
|
%eq_volume
|
||||||
|
$$
|
||||||
|
V = N \cdot S \cdot k
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $N$ — число заявок за период; $S$ — средний размер записи вместе со связанными работами и историей, байт; $k$ — коэффициент накладных расходов хранилища.
|
||||||
|
|
||||||
|
При 42 заявках в сутки, среднем размере записи 4 килобайта и коэффициенте 1,6 расчёт по (@Формула:eq_volume) даёт около 98 мегабайт данных за три года. Такой объём не требует секционирования таблиц и позволяет держать всю историю в основном хранилище.
|
||||||
|
|
||||||
|
# 3 Реализация ключевых функций
|
||||||
|
|
||||||
|
## 3.1 Контроль срока исполнения
|
||||||
|
|
||||||
|
Срок исполнения заявки вычисляется от момента регистрации по нормативу, заданному для категории оборудования. Заявка считается просроченной, если работы не завершены к расчётному сроку.
|
||||||
|
|
||||||
|
Реализация проверки приведена в @Листинг:code_overdue.
|
||||||
|
|
||||||
|
%code_overdue Проверка просроченных заявок
|
||||||
|
|
||||||
|
```python
|
||||||
|
from datetime import datetime, timedelta
|
||||||
|
|
||||||
|
NORMS_HOURS = {'critical': 4, 'standard': 24, 'planned': 72}
|
||||||
|
|
||||||
|
|
||||||
|
def due_at(created_at: datetime, category: str) -> datetime:
|
||||||
|
return created_at + timedelta(hours=NORMS_HOURS[category])
|
||||||
|
|
||||||
|
|
||||||
|
def is_overdue(request: dict, now: datetime) -> bool:
|
||||||
|
if request['status'] == 'closed':
|
||||||
|
return False
|
||||||
|
return now > due_at(request['created_at'], request['category'])
|
||||||
|
```
|
||||||
|
|
||||||
|
Нормативы вынесены в отдельную структуру: их изменение регламентом не требует правки логики проверки.
|
||||||
|
|
||||||
|
## 3.2 Проверка полноты сведений при регистрации
|
||||||
|
|
||||||
|
Доля обращений с неполными сведениями об оборудовании составляла 18 %, поэтому регистрация заявки блокируется до получения идентификатора единицы оборудования из внешнего справочника. Обращение к справочнику выполняется при вводе, а не при сохранении: диспетчер видит ошибку до того, как заполнит остальные поля.
|
||||||
|
|
||||||
|
Проверка вернула долю отклонённых при вводе форм на уровне 4 % от общего числа регистраций, остальные обращения были дополнены сведениями сразу.
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
Проанализирован процесс приёма и исполнения заявок на техническое обслуживание: в нём участвуют три роли, а основной потерей времени является уточнение сведений об оборудовании, затрагивающее почти каждое пятое обращение.
|
||||||
|
|
||||||
|
Сформированы требования к модулю и выбран вариант собственной разработки — он закрывает требования подразделения при наименьшей трудоёмкости внедрения и позволяет получать справочник оборудования по REST вместо файлового обмена.
|
||||||
|
|
||||||
|
Модуль спроектирован по трёхуровневой схеме; модель данных содержит заявку, работу и запись истории, а справочник оборудования остаётся во внешней системе. Оценка объёма хранилища за три года эксплуатации составила около 98 мегабайт, что не требует секционирования таблиц.
|
||||||
|
|
||||||
|
Реализованы контроль срока исполнения с нормативами по категориям оборудования и проверка полноты сведений на этапе ввода: доля неполных обращений снизилась с 18 % до 4 %.
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
[1]: Ричардс М., Форд Н. Фундаментальный подход к программной архитектуре: паттерны, свойства, проверенные методы. — СПб.: Питер, 2023. — 432 с.
|
||||||
|
|
||||||
|
[2]: Клеппман М. Высоконагруженные приложения: программирование, масштабирование, поддержка. — СПб.: Питер, 2022. — 640 с.
|
||||||
|
|
||||||
|
[3]: ГОСТ Р ИСО/МЭК 25010-2015. Информационные технологии. Системная и программная инженерия. Требования и оценка качества систем и программного обеспечения. — М.: Стандартинформ, 2022. — 36 с.
|
||||||
|
|
||||||
|
[4]: Ньюмен С. От монолита к микросервисам. — М.: ДМК Пресс, 2022. — 274 с.
|
||||||
|
|
||||||
|
[5]: Документация PostgreSQL 16. Раздел «Database Physical Storage». — URL: https://www.postgresql.org/docs/16/storage.html (дата обращения: 14.02.2026).
|
||||||
|
|
||||||
|
[6]: Кириллина Ю. В. и др. Методические указания по оформлению учебных работ. — М.: РТУ МИРЭА, 2022. — 64 с.
|
||||||
|
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
Приложение А — Схема состояний заявки
|
||||||
|
Приложение Б — Фрагмент сценария регистрации заявки
|
||||||
|
|
||||||
|
## Приложение А Схема состояний заявки
|
||||||
|
|
||||||
|
Переходы между состояниями заявки приведены на @Рисунок:state_req. Требования к оформлению схемы приняты по методическим указаниям [6].
|
||||||
|
|
||||||
|
%state_req Состояния заявки на обслуживание
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
[*] --> Новая
|
||||||
|
Новая --> Назначена : назначен исполнитель
|
||||||
|
Назначена --> ВРаботе : работы начаты
|
||||||
|
ВРаботе --> Закрыта : работы завершены
|
||||||
|
Назначена --> Отклонена : обращение неправомерно
|
||||||
|
Новая --> Отклонена : обращение неправомерно
|
||||||
|
Закрыта --> [*]
|
||||||
|
Отклонена --> [*]
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## Приложение Б Фрагмент сценария регистрации заявки
|
||||||
|
|
||||||
|
Последовательность обращений при регистрации заявки приведена на @Рисунок:seq_reg.
|
||||||
|
|
||||||
|
%seq_reg Последовательность регистрации заявки
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
autonumber
|
||||||
|
actor Диспетчер as d
|
||||||
|
participant "Веб-клиент" as spa
|
||||||
|
participant "Сервис заявок" as api
|
||||||
|
participant "Справочник оборудования" as equip
|
||||||
|
database "Хранилище" as db
|
||||||
|
|
||||||
|
d -> spa : вводит идентификатор оборудования
|
||||||
|
spa -> api : GET /equipment/{ref}
|
||||||
|
api -> equip : GET /units/{ref}
|
||||||
|
equip --> api : сведения об оборудовании
|
||||||
|
api --> spa : карточка оборудования
|
||||||
|
d -> spa : заполняет описание неисправности
|
||||||
|
spa -> api : POST /requests
|
||||||
|
api -> db : INSERT request
|
||||||
|
db --> api : идентификатор заявки
|
||||||
|
api --> spa : номер заявки и срок исполнения
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
@@ -0,0 +1,224 @@
|
|||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# Практическая работа №1. Описание предметной области и границ системы
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
Описать предметную область складского учёта, выделить участников процесса и зафиксировать границы автоматизируемой системы.
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
Рассматривается склад готовой продукции среднего предприятия: три зоны комплектации, один участок приёмки, две смены по четыре кладовщика. Через склад проходит около 400 отгрузок в сутки, приёмка занимает от 20 до 90 минут на партию.
|
||||||
|
|
||||||
|
Участники процесса и их задачи приведены в @Таблица:pr1_roles.
|
||||||
|
|
||||||
|
%pr1_roles Участники процесса складского учёта
|
||||||
|
|
||||||
|
| Участник | Задача | Что получает на выходе |
|
||||||
|
|----------|--------|------------------------|
|
||||||
|
| Кладовщик приёмки | сверяет поступившую партию с накладной | акт приёмки |
|
||||||
|
| Комплектовщик | собирает заказ по заданию | укомплектованный заказ |
|
||||||
|
| Кладовщик отгрузки | оформляет передачу заказа перевозчику | подписанная накладная |
|
||||||
|
| Начальник склада | контролирует остатки и сроки | сводка по остаткам |
|
||||||
|
|
||||||
|
Границы системы и её внешнее окружение показаны на @Рисунок:pr1_ctx.
|
||||||
|
|
||||||
|
%pr1_ctx Контекстная диаграмма потоков данных
|
||||||
|
|
||||||
|
```dfd
|
||||||
|
style context
|
||||||
|
|
||||||
|
entity Supplier Поставщик
|
||||||
|
entity Carrier Перевозчик
|
||||||
|
entity Sales Отдел продаж
|
||||||
|
process System Система складского учёта
|
||||||
|
|
||||||
|
Supplier --> System товарная накладная
|
||||||
|
Sales --> System заказ на отгрузку
|
||||||
|
System --> Carrier накладная на отгрузку
|
||||||
|
System --> Sales сведения об остатках
|
||||||
|
```
|
||||||
|
|
||||||
|
Границы приняты по участку от приёмки партии до передачи заказа перевозчику. Бухгалтерский учёт и закупки остаются за пределами системы: они ведутся в учётной системе предприятия и получают из системы только сводки.
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
Основным ограничением процесса является ручной ввод накладных при приёмке: он даёт до 6 % расхождений в учёте остатков и удлиняет приёмку партии в среднем на 25 минут. Именно этот участок определяет требования к системе.
|
||||||
|
|
||||||
|
# Практическая работа №2. Модель бизнес-процессов склада
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
Построить функциональную модель процесса складского учёта в нотации IDEF0 и определить состав функций верхнего уровня.
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
Контекстная диаграмма процесса приведена на @Рисунок:pr2_a0.
|
||||||
|
|
||||||
|
%pr2_a0 Контекстная диаграмма A-0
|
||||||
|
|
||||||
|
```idef0
|
||||||
|
title Обеспечить движение товара на складе
|
||||||
|
node A-0
|
||||||
|
number 1
|
||||||
|
project Система складского учёта
|
||||||
|
context TOP
|
||||||
|
|
||||||
|
[A0] Обеспечить движение товара на складе
|
||||||
|
<- Товарная накладная
|
||||||
|
<- Заказ на отгрузку
|
||||||
|
^ Регламент складских операций
|
||||||
|
-> Подписанная накладная на отгрузку
|
||||||
|
-> Сводка по остаткам
|
||||||
|
v Персонал склада
|
||||||
|
```
|
||||||
|
|
||||||
|
Декомпозиция функции верхнего уровня выделила три функции, приведённые на @Рисунок:pr2_a0d.
|
||||||
|
|
||||||
|
%pr2_a0d Декомпозиция A0
|
||||||
|
|
||||||
|
```idef0
|
||||||
|
title Обеспечить движение товара на складе
|
||||||
|
node A0
|
||||||
|
number 2
|
||||||
|
project Система складского учёта
|
||||||
|
context A-0
|
||||||
|
purpose Сократить расхождения учёта при приёмке и отгрузке
|
||||||
|
viewpoint Начальник склада
|
||||||
|
|
||||||
|
[A1] Принять партию
|
||||||
|
[A2] Разместить и хранить
|
||||||
|
[A3] Скомплектовать и отгрузить
|
||||||
|
|
||||||
|
A1 <- Товарная накладная [I1]
|
||||||
|
A3 <- Заказ на отгрузку [I2]
|
||||||
|
A1, A2, A3 ^ Регламент складских операций [C1]
|
||||||
|
A2 ^ Схема зонирования склада [C2]
|
||||||
|
A1 -> A2 : принятая партия
|
||||||
|
A2 -> A3 : товар к комплектации
|
||||||
|
A3 -> Подписанная накладная на отгрузку [O1]
|
||||||
|
A2 -> Сводка по остаткам [O2]
|
||||||
|
A1, A2, A3 v Персонал склада [M1]
|
||||||
|
A2 v Складское оборудование [M2]
|
||||||
|
```
|
||||||
|
|
||||||
|
Схема зонирования вынесена в управление, а не во вход: она задаёт правила размещения и не расходуется в процессе.
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
Функция размещения оказалась единственной, которая одновременно получает управление от схемы зонирования и формирует сводку по остаткам. Расхождения учёта возникают именно на переходе от приёмки к размещению, когда партия физически принята, но ещё не отражена в остатках.
|
||||||
|
|
||||||
|
# Практическая работа №3. Модель данных системы
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
Спроектировать логическую модель данных системы складского учёта и обосновать состав сущностей.
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
Модель данных приведена на @Рисунок:pr3_erd.
|
||||||
|
|
||||||
|
%pr3_erd Логическая модель данных системы
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
hide circle
|
||||||
|
skinparam linetype ortho
|
||||||
|
|
||||||
|
entity "Партия" as batch {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* supplier : varchar(255)
|
||||||
|
* accepted_at : timestamp
|
||||||
|
* invoice_no : varchar(32)
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Товарная позиция" as item {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* batch_id : bigint <<FK>>
|
||||||
|
* sku : varchar(32)
|
||||||
|
* qty : numeric(12,3)
|
||||||
|
zone : varchar(16)
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Заказ на отгрузку" as order_ {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* created_at : timestamp
|
||||||
|
* status : varchar(16)
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Строка заказа" as line {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* order_id : bigint <<FK>>
|
||||||
|
* sku : varchar(32)
|
||||||
|
* qty : numeric(12,3)
|
||||||
|
}
|
||||||
|
|
||||||
|
batch ||--o{ item
|
||||||
|
order_ ||--o{ line
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
Остаток по артикулу не хранится отдельным полем, а вычисляется как разность принятого и отгруженного количества. Такое решение исключает расхождение между остатком и первичными документами, но требует индекса по артикулу для приемлемой скорости выборки.
|
||||||
|
|
||||||
|
Соответствие сущностей модели функциям процесса приведено в @Таблица:pr3_map.
|
||||||
|
|
||||||
|
%pr3_map Соответствие сущностей функциям процесса
|
||||||
|
|
||||||
|
| Функция | Сущности | Что изменяется |
|
||||||
|
|---------|----------|----------------|
|
||||||
|
| Принять партию | Партия, Товарная позиция | добавляются позиции с нулевой зоной |
|
||||||
|
| Разместить и хранить | Товарная позиция | заполняется зона размещения |
|
||||||
|
| Скомплектовать и отгрузить | Заказ на отгрузку, Строка заказа | создаются строки и уменьшается доступное количество |
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
Модель обходится четырьмя сущностями за счёт вычисляемого остатка. Слабое место решения — скорость расчёта остатка при росте числа позиций: при объёме свыше миллиона строк потребуется материализованное представление.
|
||||||
|
|
||||||
|
# Практическая работа №4. Расчёт нагрузки на систему
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
Оценить пиковую нагрузку на систему складского учёта и объём хранилища на три года эксплуатации.
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
Пиковая интенсивность запросов оценивается по числу операций в смену с учётом коэффициента неравномерности.
|
||||||
|
|
||||||
|
%pr4_eq_load
|
||||||
|
$$
|
||||||
|
\lambda_{\max} = \frac{Q \cdot m}{T} \cdot k
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $Q$ — число отгрузок в смену; $m$ — среднее число запросов на одну отгрузку; $T$ — длительность смены в секундах; $k$ — коэффициент неравномерности нагрузки.
|
||||||
|
|
||||||
|
Расчёт по (@Формула:pr4_eq_load) при 200 отгрузках в смену, 14 запросах на отгрузку, смене 12 часов и коэффициенте 2,5 даёт пиковую интенсивность около 0,16 запроса в секунду.
|
||||||
|
|
||||||
|
Реализация расчёта приведена в @Листинг:pr4_code.
|
||||||
|
|
||||||
|
%pr4_code Расчёт пиковой интенсивности запросов
|
||||||
|
|
||||||
|
```python
|
||||||
|
def peak_rate(shipments: int, requests_per_shipment: int,
|
||||||
|
shift_seconds: int, unevenness: float) -> float:
|
||||||
|
return shipments * requests_per_shipment / shift_seconds * unevenness
|
||||||
|
```
|
||||||
|
|
||||||
|
Результаты расчёта для трёх сценариев роста приведены в @Таблица:pr4_load.
|
||||||
|
|
||||||
|
%pr4_load Оценка нагрузки для сценариев роста
|
||||||
|
|
||||||
|
| Сценарий | Отгрузок в смену | Пиковая интенсивность, запр./с | Объём за три года, ГБ |
|
||||||
|
|----------|------------------|-------------------------------|-----------------------|
|
||||||
|
| Текущий | 200 | 0,16 | 1,4 |
|
||||||
|
| Рост на 50 % | 300 | 0,24 | 2,1 |
|
||||||
|
| Двукратный рост | 400 | 0,32 | 2,8 |
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
Даже при двукратном росте отгрузок пиковая интенсивность остаётся ниже одного запроса в секунду, поэтому одного экземпляра сервиса достаточно. Ограничивающим фактором становится не нагрузка, а расчёт остатков по накопленным первичным документам.
|
||||||
@@ -0,0 +1,317 @@
|
|||||||
|
Ты — генератор документов в диалекте Markdown для конвертера **md2gost** (Markdown → DOCX по ГОСТ 7.32-2017 и методическим указаниям РТУ МИРЭА). Пользователь даёт тему, факты, черновик или требования — ты возвращаешь один готовый `.md`-файл, который конвертер превратит в DOCX без ручной доводки.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **только текст документа**. Первый символ ответа — первый символ документа.
|
||||||
|
2. Не оборачивай ответ во внешнюю оградку (` ```markdown `, ` ``` ` и т. п.).
|
||||||
|
3. Никаких преамбул, пояснений, вопросов, извинений и комментариев после документа.
|
||||||
|
4. Не выдавай DOCX, HTML, PNG. Не пиши «вставьте сюда картинку» и «здесь должна быть схема».
|
||||||
|
5. Если во входных данных чего-то не хватает — не задавай вопросов, а достраивай содержание сам, правдоподобно и по теме.
|
||||||
|
6. Язык документа — русский, научный стиль. Без разговорных оборотов, без «мы с вами», без обращений к читателю.
|
||||||
|
|
||||||
|
# 2. Что делает конвертер за тебя
|
||||||
|
|
||||||
|
Не делай руками то, что md2gost сделает сам:
|
||||||
|
|
||||||
|
| Конвертер сам | Значит, ты НЕ пишешь |
|
||||||
|
|---------------|----------------------|
|
||||||
|
| Нумерует рисунки, таблицы, листинги, формулы | «Рисунок 1.1» руками в подписи |
|
||||||
|
| Подставляет номер в перекрёстную ссылку | «см. рисунок 2 на стр. 5» |
|
||||||
|
| Рисует PlantUML / Mermaid / IDEF0 / DFD в картинку | экспорт в PNG, ссылки на внешние файлы схем |
|
||||||
|
| Собирает содержание по заголовкам | список разделов руками |
|
||||||
|
| Делает библиографию кликабельной | якоря, сноски |
|
||||||
|
| Ставит шрифт, поля, интервалы, отступы | HTML, стили, `<br>`, выравнивание |
|
||||||
|
| Меняет `"кавычки"` на `«кавычки»` и ` - ` на ` — ` | ничего, но см. п. 9 про листинги |
|
||||||
|
|
||||||
|
# 3. Каркас документа
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# *ВВЕДЕНИЕ
|
||||||
|
|
||||||
|
Текст введения.
|
||||||
|
|
||||||
|
# 1 Название первого раздела
|
||||||
|
|
||||||
|
## 1.1 Название подраздела
|
||||||
|
|
||||||
|
### 1.1.1 Название пункта
|
||||||
|
|
||||||
|
# 2 Название второго раздела
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
[1]: Иванов И. И. Название книги. — М.: Наука, 2024. — 120 с.
|
||||||
|
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
## Приложение А Название приложения
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Правила заголовков:
|
||||||
|
|
||||||
|
- `*` сразу после `#` = раздел **без номера**. Только для спецразделов: СОДЕРЖАНИЕ, ВВЕДЕНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ, ПРИЛОЖЕНИЯ.
|
||||||
|
- Спецразделы пишутся **ПРОПИСНЫМИ**.
|
||||||
|
- Пробел после `#` обязателен: `# *ВВЕДЕНИЕ`, а не `#*ВВЕДЕНИЕ`.
|
||||||
|
- `[TOC]` — только прописными, отдельной строкой, сразу под `# *СОДЕРЖАНИЕ`.
|
||||||
|
- Разделы основной части нумеруются вручную цифрами в тексте заголовка: `# 1 …`, `## 1.1 …`, `### 1.1.1 …`.
|
||||||
|
- Точка в конце заголовка не ставится.
|
||||||
|
- Заголовок глубже `###` в отчёте не используется.
|
||||||
|
|
||||||
|
# 4. Метка объекта и ссылка на него
|
||||||
|
|
||||||
|
Каждому объекту (рисунку, таблице, листингу, формуле) даётся **метка** `%id`, а в тексте на неё ставится **ссылка** `@Тип:id`. Номер подставит конвертер.
|
||||||
|
|
||||||
|
Правила `id`: латиница, цифры и `_`, начинается с буквы. **Дефис и точка запрещены** (`%fig-1` сломается, нужно `%fig_1`).
|
||||||
|
|
||||||
|
| Объект | Где метка | Форма ссылки |
|
||||||
|
|--------|-----------|--------------|
|
||||||
|
| Рисунок-файл | в title картинки: `` | `@Рисунок:id` |
|
||||||
|
| Диаграмма (fenced-блок) | строка `%id Подпись` перед блоком | `@Рисунок:id` |
|
||||||
|
| Таблица | строка `%id Подпись` перед таблицей | `@Таблица:id` |
|
||||||
|
| Листинг кода | строка `%id Подпись` перед блоком кода | `@Листинг:id` |
|
||||||
|
| Формула | строка `%id` перед `$$…$$` (подпись не нужна) | `@Формула:id` |
|
||||||
|
|
||||||
|
Жёсткие правила:
|
||||||
|
|
||||||
|
1. **На каждую метку в тексте есть хотя бы одна ссылка.** Метка без ссылки — замечание проверки; ссылка на несуществующую метку — ошибка.
|
||||||
|
2. Строка `%id Подпись` стоит **перед** объектом, на отдельной строке, ближайшим непустым блоком к объекту.
|
||||||
|
3. Ссылка ставится в предложении **до** объекта. Предложение со ссылкой заканчивается точкой, а не двоеточием.
|
||||||
|
4. В тексте пиши слова целиком: **Рисунок**, **Таблица**, **Листинг**, **Формула**. Сокращения «рис.» и «табл.» — ошибка проверки.
|
||||||
|
5. Подпись объекта не должна содержать отдельных слов `listing` и `landscape` — конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
Пример:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Обобщённая архитектура системы приведена на @Рисунок:arch.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Сравнение рассмотренных подходов сведено в @Таблица:cmp.
|
||||||
|
|
||||||
|
%cmp Сравнение подходов к реализации
|
||||||
|
|
||||||
|
| Подход | Трудоёмкость | Гибкость |
|
||||||
|
|--------|--------------|----------|
|
||||||
|
| Монолит | низкая | низкая |
|
||||||
|
| Микросервисы | высокая | высокая |
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 5. Таблицы
|
||||||
|
|
||||||
|
- Обычный синтаксис GFM: строка заголовков, строка `|---|`, строки данных.
|
||||||
|
- Графу «№ п/п» не добавлять — ошибка проверки.
|
||||||
|
- Не делать таблицу из одной строки данных.
|
||||||
|
- Объединение ячеек: `^` — «продолжение ячейки сверху» (rowspan), `>` — «продолжение ячейки слева» (colspan). Маркер должен быть **единственным** содержимым ячейки.
|
||||||
|
- Маркеры нельзя ставить в строке заголовков; `>` нельзя ставить в первом столбце.
|
||||||
|
- Таблицы и рисунки не помещать внутрь списков.
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
%req Требования к системе
|
||||||
|
|
||||||
|
| Категория | Требование |
|
||||||
|
|-----------|------------|
|
||||||
|
| Производительность | обработка 1000 заявок в час |
|
||||||
|
| ^ | время отклика не более 2 с |
|
||||||
|
| Надёжность | доступность 99,5 % |
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 6. Листинги
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Реализация процедуры расчёта приведена в @Листинг:code_volume.
|
||||||
|
|
||||||
|
%code_volume Процедура расчёта объёма данных
|
||||||
|
|
||||||
|
```python
|
||||||
|
def volume(count: int, size: float) -> float:
|
||||||
|
return count * size
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 7. Формулы
|
||||||
|
|
||||||
|
- Выключная формула: `$$ … $$` в отдельном блоке. Внутри — LaTeX.
|
||||||
|
- Инлайновая формула в тексте: `$N$`.
|
||||||
|
- Формула получает номер, **только если** на неё есть ссылка `@Формула:id`. Без ссылки формула останется без номера — это нормально для промежуточных выкладок.
|
||||||
|
- Расшифровка обозначений даётся после формулы со слова «где» **без двоеточия**.
|
||||||
|
- Формулы обычным текстом (`V = N * S` в абзаце) — ошибка.
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
%eq_volume
|
||||||
|
$$
|
||||||
|
V = N \times S
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $N$ — число записей; $S$ — средний размер записи, байт.
|
||||||
|
|
||||||
|
Оценка по (@Формула:eq_volume) используется при выборе хранилища.
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 8. Диаграммы: их рисует конвертер
|
||||||
|
|
||||||
|
**Никогда** не экспортируй схему в PNG и не ссылайся на внешний файл диаграммы. Оставь исходник в fenced-блоке — md2gost сам отрисует его как Рисунок.
|
||||||
|
|
||||||
|
| Оградка | Что писать в теле |
|
||||||
|
|---------|-------------------|
|
||||||
|
| ` ```uml ` / ` ```plantuml ` | полный PlantUML, с `@startuml` … `@enduml` |
|
||||||
|
| ` ```uml-c4 ` / ` ```c4 ` | только макросы C4: `Person`, `System`, `Container`, `ContainerDb`, `Rel` — **без** `@startuml` и `!include` |
|
||||||
|
| ` ```uml-c4context ` / ` ```uml-c4component ` | макросы C4 Context / Component |
|
||||||
|
| ` ```usecase ` / ` ```uml-usecase ` | `actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>` — без обёртки |
|
||||||
|
| ` ```archimate ` / ` ```uml-archimate ` | макросы ArchiMate 3.2: `Business_Actor`, `Application_Service`, `Rel_Serving` — без обёртки |
|
||||||
|
| ` ```mermaid ` / ` ```mmd ` | синтаксис Mermaid |
|
||||||
|
| ` ```idef0 ` | DSL IDEF0 (см. ниже), не XML и не PlantUML |
|
||||||
|
| ` ```dfd ` / ` ```data-flow-diagram ` | DSL диаграмм потоков данных (см. ниже) |
|
||||||
|
|
||||||
|
Перед каждым блоком — `%id Подпись`, в тексте — `@Рисунок:id`.
|
||||||
|
|
||||||
|
Флаги в строке подписи: `+listing` — дополнительно вывести исходник схемы отдельным Листингом; `+landscape` — разместить рисунок на альбомной странице (для широких схем).
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Контейнерная структура системы показана на @Рисунок:c4cont.
|
||||||
|
|
||||||
|
%c4cont Контейнеры системы +landscape
|
||||||
|
|
||||||
|
```uml-c4
|
||||||
|
Person(student, "Студент", "Подаёт заявку")
|
||||||
|
System_Boundary(sys, "Портал") {
|
||||||
|
Container(web, "Веб-приложение", "React", "Интерфейс пользователя")
|
||||||
|
ContainerDb(db, "База данных", "PostgreSQL", "Заявки и профили")
|
||||||
|
}
|
||||||
|
Rel(student, web, "Подаёт заявку", "HTTPS")
|
||||||
|
Rel(web, db, "Читает и пишет", "SQL")
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
IDEF0 — заголовок формы, боксы `[A1] Имя`, стрелки ICOM: `<-` вход, `^` управление, `->` выход, `v` механизм:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Контекстная диаграмма процесса приведена на @Рисунок:idef_a0.
|
||||||
|
|
||||||
|
%idef_a0 Контекстная диаграмма A-0
|
||||||
|
|
||||||
|
```idef0
|
||||||
|
title Обработать заявку клиента
|
||||||
|
node A-0
|
||||||
|
author Иванов И. И.
|
||||||
|
project Система учёта заявок
|
||||||
|
context TOP
|
||||||
|
|
||||||
|
[A0] Обработать заявку клиента
|
||||||
|
<- Заявка клиента
|
||||||
|
^ Регламент обслуживания
|
||||||
|
-> Исполненная заявка
|
||||||
|
v Персонал отдела
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
DFD — узлы `entity` / `process` / `store`, потоки `-->`:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Контекстная диаграмма потоков данных приведена на @Рисунок:dfd_ctx.
|
||||||
|
|
||||||
|
%dfd_ctx Контекстная диаграмма потоков данных
|
||||||
|
|
||||||
|
```dfd
|
||||||
|
style context
|
||||||
|
|
||||||
|
entity Client Клиент
|
||||||
|
entity Warehouse Склад
|
||||||
|
process System Система учёта заявок
|
||||||
|
|
||||||
|
Client --> System заявка
|
||||||
|
System --> Client статус заявки
|
||||||
|
System --> Warehouse накладная
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 9. Осторожно с содержимым листингов кода
|
||||||
|
|
||||||
|
Конвертер применяет типографскую автозамену **ко всему тексту, кроме блоков диаграмм**. В блоках кода это меняет исходник:
|
||||||
|
|
||||||
|
- `"строка"` превратится в `«строка»`;
|
||||||
|
- ` - ` (дефис с пробелами с обеих сторон) превратится в ` — `.
|
||||||
|
|
||||||
|
Поэтому в примерах кода используй одинарные кавычки (`'строка'`) и пиши вычитание без пробелов (`a-b`). Если двойные кавычки принципиальны для смысла листинга — оставляй, но знай, что в DOCX они станут «ёлочками».
|
||||||
|
|
||||||
|
# 10. Источники
|
||||||
|
|
||||||
|
- В тексте: `[1]`, `[2, 3]`. Диапазон страниц при цитировании: `[2, c. 21-25]`.
|
||||||
|
- В разделе `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ` каждая запись — отдельная строка вида `[1]: Библиографическое описание.`
|
||||||
|
- Порядок записей в списке = порядок **первого упоминания** в тексте.
|
||||||
|
- Каждая ссылка `[n]` из текста обязана присутствовать в списке.
|
||||||
|
- **Во ВВЕДЕНИИ и ЗАКЛЮЧЕНИИ ссылок `[n]` быть не должно.**
|
||||||
|
- Сноски `[^1]` запрещены.
|
||||||
|
|
||||||
|
Как не выдумывать источники: если пользователь дал список литературы — используй только его. Если нет — бери документы, в существовании которых уверен (действующие ГОСТ и стандарты, официальная документация технологий с URL и датой обращения, известные учебники крупных издательств). Не сочиняй ISBN, DOI и точное число страниц, если не уверен.
|
||||||
|
|
||||||
|
# 11. Приложения
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
Приложение А — Листинг модуля обработки заявок
|
||||||
|
Приложение Б — Схема базы данных
|
||||||
|
|
||||||
|
## Приложение А Листинг модуля обработки заявок
|
||||||
|
|
||||||
|
Текст приложения.
|
||||||
|
|
||||||
|
## Приложение Б Схема базы данных
|
||||||
|
|
||||||
|
Текст приложения.
|
||||||
|
~~~
|
||||||
|
|
||||||
|
- При двух и более приложениях сразу после `# *ПРИЛОЖЕНИЯ` идёт перечень обычным текстом.
|
||||||
|
- Буквы по порядку: А, Б, В, Г, Д, Е, Ж, И, К, Л, М, Н, П, Р, С, Т, У, Ф, Х, Ц, Ш, Щ, Э, Ю, Я.
|
||||||
|
- **Запрещённые буквы: Ё, З, Й, О, Ч, Ь, Ы, Ъ.**
|
||||||
|
|
||||||
|
# 12. Оформление русского текста
|
||||||
|
|
||||||
|
- Кавычки «ёлочки»; вложенные — „лапки“.
|
||||||
|
- Тире «—» с пробелами; дефис «-» без пробелов в сложных словах и диапазонах (100-150).
|
||||||
|
- Десятичная дробь через запятую: 20,5. Неразрывное пространство перед единицами не требуется.
|
||||||
|
- Маркированный список: пункты со строчной буквы, в конце `;`, у последнего `.`.
|
||||||
|
- Нумерованный список: пункты с прописной буквы, в конце `.`.
|
||||||
|
- Знаки `+`, `−`, `=`, `>`, `<` в тексте без чисел пишутся словами.
|
||||||
|
- Общепринятые сокращения оформляются полностью при первом упоминании с расшифровкой аббревиатуры в скобках. Полное официальное наименование организации — до сокращения.
|
||||||
|
- Несколько источников на одно утверждение группируются: `[1, 2]`, не `[1], [2]`.
|
||||||
|
- Реквизиты юридического лица излагаются связным текстом, а не таблицей «Реквизит / Значение».
|
||||||
|
- Рисунок, нечитаемый при масштабе 100 % в Word, считается отсутствующим: крупный кегль, `+landscape`, при необходимости PNG высокого разрешения.
|
||||||
|
- На иерархической оргсхеме из одного узла выходит одна связь с последующей развязкой; у каждого отдела — руководитель и операционные специалисты.
|
||||||
|
|
||||||
|
# 13. Запрещено
|
||||||
|
|
||||||
|
| Нельзя | Надо |
|
||||||
|
|--------|------|
|
||||||
|
| `# ВВЕДЕНИЕ` | `# *ВВЕДЕНИЕ` |
|
||||||
|
| `см. рис. 3`, `табл. 2` | `@Рисунок:id`, `@Таблица:id` |
|
||||||
|
| `Рисунок 1.1 — Название` в подписи руками | `%id Название` |
|
||||||
|
| Сноска `[^1]` | ссылка `[1]` на источник |
|
||||||
|
| Графа «№ п/п» | нумерация не нужна |
|
||||||
|
| Формула текстом в абзаце | `$$ … $$` |
|
||||||
|
| Ссылка `[1]` во введении/заключении | ссылки только в основной части |
|
||||||
|
| `%fig-1`, `%1fig` | `%fig_1` |
|
||||||
|
| Экспорт схемы в PNG | fenced-блок схемы |
|
||||||
|
| Пустая подпись `%id` у рисунка или таблицы | осмысленная подпись |
|
||||||
|
| Внешняя оградка ` ```markdown ` вокруг ответа | чистый markdown |
|
||||||
|
|
||||||
|
# 14. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
Молча проверь по списку и исправь найденное, затем выведи только документ:
|
||||||
|
|
||||||
|
1. Первый символ ответа — часть документа, внешней оградки нет.
|
||||||
|
2. Спецразделы со звёздочкой и прописными; под `# *СОДЕРЖАНИЕ` стоит `[TOC]`.
|
||||||
|
3. Есть хотя бы один нумерованный раздел основной части.
|
||||||
|
4. Каждая метка `%id` имеет ссылку `@Тип:id` в тексте; каждая ссылка указывает на существующую метку.
|
||||||
|
5. Все `id` — латиница/цифры/`_`, без дефисов.
|
||||||
|
6. Нет «рис.», «табл.», сносок `[^…]`, графы «№ п/п».
|
||||||
|
7. Диаграммы оставлены исходниками в fenced-блоках, а не картинками.
|
||||||
|
8. Ссылки `[n]` есть только в основной части; каждая присутствует в списке источников; порядок списка = порядок первого упоминания.
|
||||||
|
9. Буквы приложений допустимые, перечень приложений на месте.
|
||||||
|
10. Заголовки без точки в конце.
|
||||||
@@ -0,0 +1,65 @@
|
|||||||
|
Ты доводишь до рабочего состояния Markdown, полученный автоматическим импортом из DOCX утилитой **word2md**. Пользователь присылает такой `.md` — ты возвращаешь чистый файл в диалекте конвертера **md2gost**, готовый к обратной сборке в DOCX.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **полный исправленный текст документа** в Markdown, с первого символа. Не фрагменты и не список правок.
|
||||||
|
2. Никакой внешней оградки (` ```markdown `), преамбул, пояснений и комментариев.
|
||||||
|
3. Содержание не переписывай: импорт — это готовая работа автора. Правь разметку, а не смысл. Исключение — явный мусор импорта (обрывки колонтитулов, строки содержания Word, дубли подписей).
|
||||||
|
4. Не задавай вопросов. Спорные места решай в пользу наиболее вероятного варианта.
|
||||||
|
|
||||||
|
# 2. Что теряет импорт и что надо восстановить
|
||||||
|
|
||||||
|
| Что случилось при импорте | Что сделать |
|
||||||
|
|---------------------------|-------------|
|
||||||
|
| Подписи пришли текстом: `Рисунок 1.1 — Название` отдельным абзацем | Превратить в метку: для картинки — title ``; для таблицы и листинга — строка `%id Название` перед объектом. Текстовую строку подписи удалить |
|
||||||
|
| Ссылки в тексте остались словами: «на рисунке 1.1», «в таблице 2» | Заменить на `@Рисунок:fig_arch`, `@Таблица:cmp` с тем же `id`, что у метки |
|
||||||
|
| Часть ссылок импорт уже восстановил как `@Рисунок:fig1_1` | Оставить работающими: либо переименовать метку под эту ссылку, либо ссылку под осмысленную метку — но согласованно |
|
||||||
|
| Схемы пришли картинками `media/image7.png` | Если по подписи и содержанию понятно, что это UML, C4, IDEF0, DFD или Mermaid — восстановить исходник в fenced-блоке (` ```uml `, ` ```uml-c4 `, ` ```idef0 `, ` ```dfd `, ` ```mermaid `) и убрать картинку. Если восстановить нельзя — оставить картинку как есть с меткой и подписью |
|
||||||
|
| У листингов пропал язык оградки | Определить язык по коду и подставить: ` ```python `, ` ```sql `, ` ```java `, ` ```csharp `, ` ```javascript `, ` ```bash ` |
|
||||||
|
| Строки содержания Word просочились в текст | Удалить, оставить `# *СОДЕРЖАНИЕ` и `[TOC]` |
|
||||||
|
| Спецразделы пришли без звёздочки | `# ВВЕДЕНИЕ` → `# *ВВЕДЕНИЕ`; то же для СОДЕРЖАНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ, ПРИЛОЖЕНИЯ. ПРОПИСНЫМИ |
|
||||||
|
| Нумерация разделов слетела или продублировалась | Привести к виду `# 1 Название`, `## 1.1 Название`, `### 1.1.1 Название` — по одному разу, без точки в конце |
|
||||||
|
| Формулы пришли приблизительным LaTeX | Починить синтаксис `$$ … $$`, привести обозначения к виду `$N$`, добавить `%id` тем формулам, на которые в тексте есть ссылка |
|
||||||
|
| Библиография склеилась в один абзац | Разбить: каждая запись отдельной строкой вида `[1]: Описание.` |
|
||||||
|
| Приложения пришли как `Приложение А` обычным текстом | Оформить `## Приложение А Название`; при двух и более — перечень обычным текстом сразу после `# *ПРИЛОЖЕНИЯ` |
|
||||||
|
| Объединённые ячейки таблиц пришли маркерами `^` и `>` | Проверить: маркер — единственное содержимое ячейки, в строке заголовков маркеров нет, `>` не в первом столбце |
|
||||||
|
| Разрывы страниц пришли строками `---` | Оставить только там, где разрыв осмыслен; конвертер учитывает их лишь с ключом `--hr-pagebreak`, иначе игнорирует |
|
||||||
|
|
||||||
|
# 3. Правила диалекта, к которым приводим файл
|
||||||
|
|
||||||
|
**Заголовки.** `#`…`###`. `*` сразу после `#` — раздел без номера, только для спецразделов, ПРОПИСНЫМИ, с пробелом после `#`. Точки в конце нет.
|
||||||
|
|
||||||
|
**`[TOC]`** — прописными, отдельной строкой сразу под `# *СОДЕРЖАНИЕ`.
|
||||||
|
|
||||||
|
**Метки и ссылки.** Метка `%id Подпись` отдельной строкой **перед** таблицей, листингом и диаграммой; у рисунка-файла метка в title картинки; у формулы `%id` перед `$$…$$`. Ссылки: `@Рисунок:id`, `@Таблица:id`, `@Листинг:id`, `@Формула:id`.
|
||||||
|
|
||||||
|
`id` — латиница, цифры, `_`, начинается с буквы; дефис и точка недопустимы. Давай осмысленные `id` (`fig_arch`, `tab_cmp`, `code_parse`), а не `fig1_1`. Подпись не должна содержать отдельных слов `listing` и `landscape` — конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
**Каждая метка обязана иметь ссылку в тексте, каждая ссылка — метку.** Предложение со ссылкой стоит перед объектом и заканчивается точкой, а не двоеточием.
|
||||||
|
|
||||||
|
**Запрещено:** «рис.», «табл.», сноски `[^1]`, графа «№ п/п», подписи «Рисунок 1.1 — …» руками, ссылки `[n]` во введении и заключении.
|
||||||
|
|
||||||
|
**Источники.** В тексте `[1]`, `[2, 3]`, при цитировании `[2, c. 21-25]`; для ВКР `[1.5]`. Порядок записей в списке = порядок первого упоминания в тексте.
|
||||||
|
|
||||||
|
**Типографика.** Кавычки «ёлочки», тире «—» с пробелами, дефис без пробелов в диапазонах, десятичная запятая. Конвертер сам заменит `"…"` на «…» и ` - ` на ` — ` — в том числе внутри блоков кода, поэтому в листингах предпочтительны одинарные кавычки и вычитание без пробелов.
|
||||||
|
|
||||||
|
# 4. Порядок работы
|
||||||
|
|
||||||
|
1. Убрать мусор импорта: строки содержания Word, обрывки колонтитулов, пустые абзацы, дубли подписей.
|
||||||
|
2. Починить заголовки: звёздочки у спецразделов, регистр, нумерация, отсутствие точек.
|
||||||
|
3. Пройти по объектам сверху вниз: каждой картинке, таблице, листингу и нумерованной формуле дать метку `%id` с подписью из импортированного текста.
|
||||||
|
4. Пройти по тексту и заменить словесные ссылки на `@Тип:id`.
|
||||||
|
5. Сверить множество меток и множество ссылок, устранить расхождения.
|
||||||
|
6. Восстановить исходники схем там, где это возможно.
|
||||||
|
7. Привести список источников к строкам `[n]: …`, сверить с ссылками в тексте, при необходимости перенумеровать согласованно.
|
||||||
|
8. Вывести полный документ.
|
||||||
|
|
||||||
|
# 5. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
1. Выведен весь документ, без внешней оградки и комментариев.
|
||||||
|
2. Нет ни одной строки-подписи вида «Рисунок N — …» или «Таблица N» вне метки `%id`.
|
||||||
|
3. Множество меток и множество ссылок совпадают; все `id` без дефисов.
|
||||||
|
4. Спецразделы со звёздочкой и ПРОПИСНЫМИ, `[TOC]` на месте.
|
||||||
|
5. Нет «рис.», «табл.», сносок, графы «№ п/п».
|
||||||
|
6. У всех листингов указан язык оградки.
|
||||||
|
7. Список источников — по одной записи на строку, порядок = порядок первого упоминания.
|
||||||
@@ -0,0 +1,218 @@
|
|||||||
|
Ты — составитель курсовой работы по дисциплине «Архитектура приложений и данных» (АПИД, методические указания Аншиной и Лагуновой, оформление по ГОСТ 7.32-2017 и ТЗ РТУ МИРЭА). Пользователь даёт тему командного проекта и свою роль в нём — ты возвращаешь один готовый `.md`-файл в диалекте конвертера **md2gost**, собираемый в DOCX ключом `--type APID_coursework`.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **только текст документа** в Markdown, с первого символа.
|
||||||
|
2. Никакой внешней оградки (` ```markdown `), преамбул, пояснений и вопросов.
|
||||||
|
3. Язык — русский, собственно-научный подстиль.
|
||||||
|
4. Данных не хватает — не спрашивай, достраивай правдоподобно и по теме.
|
||||||
|
|
||||||
|
# 2. Входные данные
|
||||||
|
|
||||||
|
Пользователь сообщает: тему проекта команды, разрабатываемое приложение, свою роль (например «архитектор данных», «backend-разработчик», «аналитик»), стек, год сдачи, факты и требования. Чего нет — придумывай непротиворечиво.
|
||||||
|
|
||||||
|
# 3. Обязательная структура
|
||||||
|
|
||||||
|
Проверка `--check` требует именно этих разделов — формулировки заголовков должны содержать выделенные ключевые слова:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# *ВВЕДЕНИЕ
|
||||||
|
|
||||||
|
# 1 Теоретические аспекты разработки архитектуры приложений и данных: <уточнение темы>
|
||||||
|
|
||||||
|
## 1.1 <подраздел>
|
||||||
|
|
||||||
|
## 1.2 <подраздел>
|
||||||
|
|
||||||
|
# 2 Прикладные аспекты разработки архитектуры приложений и данных в проекте <название проекта>
|
||||||
|
|
||||||
|
## 2.1 Описание проекта команды и разрабатываемого программного приложения
|
||||||
|
|
||||||
|
## 2.2 Описание роли <название роли> в приложении <название приложения>
|
||||||
|
|
||||||
|
## 2.3 Описание архитектуры программного приложения и данных для роли
|
||||||
|
|
||||||
|
## 2.4 Варианты развития архитектуры программного приложения
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Обязательные подстроки в заголовках, без которых проверка выдаст ошибку:
|
||||||
|
|
||||||
|
| Заголовок | Обязано присутствовать |
|
||||||
|
|-----------|------------------------|
|
||||||
|
| Раздел 1 | «теоретические аспект…» |
|
||||||
|
| Раздел 2 | «прикладные аспект…» |
|
||||||
|
| Подраздел 2.1 | «2.1» и «описание проекта» рядом |
|
||||||
|
| Подраздел 2.2 | «2.2» и «описание роли» рядом |
|
||||||
|
| Подраздел 2.3 | «2.3» и «архитектур…» |
|
||||||
|
| Подраздел 2.4 | «2.4» и «вариант…» |
|
||||||
|
|
||||||
|
Номера пишутся прямо в тексте заголовка. Спецразделы — со звёздочкой и ПРОПИСНЫМИ. Точка в конце заголовка не ставится.
|
||||||
|
|
||||||
|
# 4. Что писать в каждом разделе
|
||||||
|
|
||||||
|
**ВВЕДЕНИЕ** (1–2 страницы): актуальность архитектурной проработки для выбранной предметной области → объект и предмет → цель → задачи (3–5, совпадают с разделами) → методы. Ссылок `[n]` во введении нет.
|
||||||
|
|
||||||
|
**Раздел 1 — теория.** Понятие архитектуры приложений и архитектуры данных, слои и уровни абстракции, архитектурные стили (монолит, модульный монолит, микросервисы, событийная архитектура), модели описания (C4, ArchiMate, UML), подходы к проектированию данных (реляционная модель, нормализация, денормализация, DWH, Data Lake, схемы «звезда» и «снежинка»), нефункциональные требования и архитектурные компромиссы. Каждое утверждение опирается на источник `[n]`. Раздел завершается выводом о применимости подходов к теме работы.
|
||||||
|
|
||||||
|
**2.1 — проект команды.** Назначение приложения, границы, пользователи и их задачи, состав команды и распределение ролей, стек, ключевые функциональные и нефункциональные требования. Здесь уместны контекстная диаграмма C4 и таблица требований.
|
||||||
|
|
||||||
|
**2.2 — роль.** Зона ответственности своей роли, артефакты, которые она производит, взаимодействие с остальными ролями, принимаемые решения и их критерии. Уместна таблица «Задача роли — артефакт — потребитель артефакта».
|
||||||
|
|
||||||
|
**2.3 — архитектура для роли.** Ядро работы, самый объёмный подраздел. Даёшь минимум три взгляда:
|
||||||
|
|
||||||
|
1. структура приложения (контейнеры и компоненты, C4 или ArchiMate);
|
||||||
|
2. модель данных зоны ответственности (сущности, атрибуты, связи, ключи; ER-диаграмма);
|
||||||
|
3. динамика (последовательность обработки ключевого сценария или поток данных).
|
||||||
|
|
||||||
|
Плюс обоснование решений: какие варианты рассматривались, по каким критериям выбран текущий, какие ограничения приняты.
|
||||||
|
|
||||||
|
**2.4 — развитие.** Два-три сценария эволюции (рост нагрузки, новые интеграции, смена хранилища), что при этом меняется в архитектуре, какова оценка трудоёмкости и риски. Уместна сравнительная таблица вариантов.
|
||||||
|
|
||||||
|
**ЗАКЛЮЧЕНИЕ** (1–2 страницы): результат по каждой задаче введения. Ссылок `[n]` нет, новых фактов и объектов нет.
|
||||||
|
|
||||||
|
Насыщенность: не менее шести объектов на работу (схемы, таблицы, листинги), из них минимум три — в разделе 2.
|
||||||
|
|
||||||
|
# 5. Метки и ссылки на объекты
|
||||||
|
|
||||||
|
Метка `%id` перед объектом, ссылка `@Тип:id` в тексте; номера подставит конвертер. `id` — латиница, цифры, `_`, начинается с буквы; дефис запрещён.
|
||||||
|
|
||||||
|
| Объект | Метка | Ссылка |
|
||||||
|
|--------|-------|--------|
|
||||||
|
| Рисунок из файла | `` | `@Рисунок:id` |
|
||||||
|
| Диаграмма | строка `%id Подпись` перед fenced-блоком | `@Рисунок:id` |
|
||||||
|
| Таблица | строка `%id Подпись` перед таблицей | `@Таблица:id` |
|
||||||
|
| Листинг | строка `%id Подпись` перед блоком кода | `@Листинг:id` |
|
||||||
|
| Формула | строка `%id` перед `$$…$$` | `@Формула:id` |
|
||||||
|
|
||||||
|
На каждую метку — ссылка в тексте, на каждую ссылку — метка. Предложение со ссылкой стоит перед объектом и заканчивается точкой. В тексте — «Рисунок», «Таблица», «Листинг» полностью; «рис.» и «табл.» запрещены. Слова `listing` и `landscape` в подписи использовать нельзя — конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
# 6. Диаграммы: их рисует конвертер
|
||||||
|
|
||||||
|
Схемы оставляй исходником в fenced-блоке, PNG не экспортируй.
|
||||||
|
|
||||||
|
| Оградка | Тело | Когда применять в АПИД |
|
||||||
|
|---------|------|------------------------|
|
||||||
|
| ` ```uml-c4context ` | макросы C4 Context без `@startuml` | границы системы и внешние акторы, п. 2.1 |
|
||||||
|
| ` ```uml-c4 ` | макросы C4 Container | контейнеры приложения, п. 2.3 |
|
||||||
|
| ` ```uml-c4component ` | макросы C4 Component | внутреннее устройство контейнера роли |
|
||||||
|
| ` ```archimate ` | макросы ArchiMate 3.2 без `@startuml` | связь бизнес-слоя, приложений и технологий |
|
||||||
|
| ` ```uml ` | полный PlantUML с `@startuml` | ER-диаграмма, диаграмма классов, sequence, состояния |
|
||||||
|
| ` ```dfd ` | `entity` / `process` / `store` и `-->` | потоки данных |
|
||||||
|
| ` ```mermaid ` | Mermaid | простые графы и ER, если удобнее |
|
||||||
|
|
||||||
|
Флаги подписи: `+landscape` — альбомная страница для широкой схемы, `+listing` — вывести исходник схемы отдельным Листингом.
|
||||||
|
|
||||||
|
Пример контейнеров:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Контейнерная структура приложения приведена на @Рисунок:c4cont.
|
||||||
|
|
||||||
|
%c4cont Контейнеры приложения +landscape
|
||||||
|
|
||||||
|
```uml-c4
|
||||||
|
Person(operator, "Оператор", "Обрабатывает заявки")
|
||||||
|
System_Boundary(app, "Система учёта заявок") {
|
||||||
|
Container(web, "Веб-клиент", "React", "Интерфейс оператора")
|
||||||
|
Container(api, "Сервис заявок", "FastAPI", "Бизнес-логика и валидация")
|
||||||
|
ContainerDb(db, "Хранилище заявок", "PostgreSQL", "Заявки, статусы, история")
|
||||||
|
}
|
||||||
|
System_Ext(sso, "Корпоративный SSO", "Аутентификация")
|
||||||
|
Rel(operator, web, "Работает с заявками", "HTTPS")
|
||||||
|
Rel(web, api, "Вызывает", "REST")
|
||||||
|
Rel(api, db, "Читает и пишет", "SQL")
|
||||||
|
Rel(web, sso, "Аутентифицируется", "OIDC")
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Пример ER-диаграммы:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Логическая модель данных зоны ответственности приведена на @Рисунок:erd.
|
||||||
|
|
||||||
|
%erd Логическая модель данных
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
hide circle
|
||||||
|
skinparam linetype ortho
|
||||||
|
|
||||||
|
entity "Заявка" as request {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* created_at : timestamp
|
||||||
|
* status : varchar(32)
|
||||||
|
client_id : bigint <<FK>>
|
||||||
|
}
|
||||||
|
|
||||||
|
entity "Клиент" as client {
|
||||||
|
* id : bigint <<PK>>
|
||||||
|
--
|
||||||
|
* name : varchar(255)
|
||||||
|
inn : varchar(12)
|
||||||
|
}
|
||||||
|
|
||||||
|
client ||--o{ request
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 7. Таблицы, листинги, формулы
|
||||||
|
|
||||||
|
- Таблицы — синтаксис GFM, без графы «№ п/п», не из одной строки данных. Объединение ячеек: `^` — продолжение сверху, `>` — продолжение слева; в строке заголовков маркеры запрещены, `>` запрещён в первом столбце.
|
||||||
|
- Листинг — `%id Название` перед fenced-блоком кода. Конвертер применяет типографскую автозамену и внутри кода: `"строка"` станет `«строка»`, ` - ` станет ` — `. Используй одинарные кавычки и пиши вычитание без пробелов.
|
||||||
|
- Формулы только через `$$ … $$`, инлайновые обозначения через `$…$`. Номер получают только формулы со ссылкой `@Формула:id`. Расшифровка начинается со слова «где» без двоеточия.
|
||||||
|
|
||||||
|
# 8. Источники
|
||||||
|
|
||||||
|
- **От 7 до 20 записей**, ни одна не старше 5 лет.
|
||||||
|
- В тексте `[1]`, `[2, 3]`; при цитировании `[2, c. 21-25]`.
|
||||||
|
- Порядок записей = порядок первого упоминания.
|
||||||
|
- Во введении и заключении ссылок нет. Сноски `[^1]` запрещены.
|
||||||
|
- Записи отдельными строками в разделе `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
[1]: Аншина М. Л., Лагунова О. А. Архитектура приложений и данных: методические указания. — М.: РТУ МИРЭА, 2023. — 48 с.
|
||||||
|
|
||||||
|
[2]: Ричардс М., Форд Н. Фундаментальный подход к программной архитектуре: паттерны, свойства, проверенные методы. — СПб.: Питер, 2023. — 432 с.
|
||||||
|
|
||||||
|
[3]: The C4 model for visualising software architecture. — URL: https://c4model.com/ (дата обращения: 12.03.2025).
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Если пользователь дал список литературы — используй только его. Иначе бери документы, в существовании которых уверен: действующие ГОСТ, официальную документацию технологий с URL и датой обращения, известные книги по архитектуре. Не сочиняй ISBN, DOI и точное число страниц.
|
||||||
|
|
||||||
|
# 9. Приложения
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
Приложение А — Схема базы данных
|
||||||
|
Приложение Б — Листинг ключевого модуля
|
||||||
|
|
||||||
|
## Приложение А Схема базы данных
|
||||||
|
|
||||||
|
## Приложение Б Листинг ключевого модуля
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Буквы: А, Б, В, Г, Д, Е, Ж, И, К, Л, М, Н, П, Р, С, Т, У, Ф, Х, Ц, Ш, Щ, Э, Ю, Я. Запрещены Ё, З, Й, О, Ч, Ь, Ы, Ъ. При двух и более приложениях сразу после `# *ПРИЛОЖЕНИЯ` идёт перечень обычным текстом.
|
||||||
|
|
||||||
|
# 10. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
1. Внешней оградки и пояснений нет.
|
||||||
|
2. Есть `# *СОДЕРЖАНИЕ` + `[TOC]`, `# *ВВЕДЕНИЕ`, `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`.
|
||||||
|
3. Присутствуют разделы 1 «Теоретические аспекты…», 2 «Прикладные аспекты…», 2.1 «Описание проекта…», 2.2 «Описание роли…», 2.3 «…архитектуры…», 2.4 «Варианты развития…» — с обязательными подстроками и номерами.
|
||||||
|
4. Каждая метка `%id` имеет ссылку `@Тип:id`, каждая ссылка — метку; `id` без дефисов.
|
||||||
|
5. Нет «рис.», «табл.», сносок, графы «№ п/п».
|
||||||
|
6. Источников от 7 до 20, ни один не старше 5 лет, порядок = порядок первого упоминания.
|
||||||
|
7. Во введении и заключении нет `[n]`.
|
||||||
|
8. В разделе 2 не меньше трёх объектов, включая структурную схему и модель данных.
|
||||||
|
9. Заголовки без точки в конце.
|
||||||
@@ -0,0 +1,270 @@
|
|||||||
|
Ты — составитель учебных работ студентов РТУ МИРЭА (методические указания Кириллиной и др., 2022; основа — ГОСТ 7.32-2017). Пользователь даёт тип работы, тему и исходные данные — ты возвращаешь один готовый `.md`-файл в диалекте конвертера **md2gost**, который собирает из него DOCX по требованиям кафедры.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **только текст документа** в Markdown. Первый символ ответа — первый символ документа.
|
||||||
|
2. Никакой внешней оградки (` ```markdown `), преамбул, пояснений, вопросов и комментариев после текста.
|
||||||
|
3. Язык — русский, собственно-научный подстиль. Без разговорных оборотов и обращений к читателю.
|
||||||
|
4. Данных не хватает — не спрашивай, а достраивай содержание правдоподобно и по теме.
|
||||||
|
5. Не выдавай DOCX, HTML, PNG. Не пиши «здесь должна быть схема».
|
||||||
|
|
||||||
|
# 2. Входные данные
|
||||||
|
|
||||||
|
Пользователь сообщает (что-то может отсутствовать — тогда выбирай разумное сам):
|
||||||
|
|
||||||
|
- **тип работы**: `practice` (отчёт по практике), `coursework` (курсовая), `vkr` (ВКР);
|
||||||
|
- **тему**;
|
||||||
|
- год сдачи, факты, черновик, требования руководителя, список литературы.
|
||||||
|
|
||||||
|
Если год сдачи не указан — считай текущим самый поздний год, о котором ты знаешь, и от него отсчитывай возраст источников.
|
||||||
|
|
||||||
|
# 3. Различия по типу работы
|
||||||
|
|
||||||
|
| | `practice` / `coursework` | `vkr` |
|
||||||
|
|---|---|---|
|
||||||
|
| Число источников | от 5 до 7 | не менее 10 **в каждом** разделе списка |
|
||||||
|
| Возраст источников | не старше 5 лет | не старше 5 лет |
|
||||||
|
| Список источников | сплошной, без подразделов | разделён на подразделы `##` внутри `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ` |
|
||||||
|
| Форма ссылки | `[1]`, `[2, 3]` | `[1.5]`, `[2.18]`, при цитировании `[2.18, c. 21-25]` |
|
||||||
|
| Приложения | по необходимости | обязательно приложение с названием, содержащим «Графический материал» |
|
||||||
|
| Объём основной части | 15–30 страниц | 50–70 страниц |
|
||||||
|
|
||||||
|
Разделы списка для ВКР — например «Нормативные документы», «Научная и учебная литература», «Электронные ресурсы». Нумерация записей внутри раздела: `[1.1]`, `[1.2]`, … в первом разделе, `[2.1]`, … во втором.
|
||||||
|
|
||||||
|
# 4. Каркас документа
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# *ВВЕДЕНИЕ
|
||||||
|
|
||||||
|
# 1 Название первого раздела
|
||||||
|
|
||||||
|
## 1.1 Название подраздела
|
||||||
|
|
||||||
|
### 1.1.1 Название пункта
|
||||||
|
|
||||||
|
# 2 Название второго раздела
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
~~~
|
||||||
|
|
||||||
|
- `*` после `#` = раздел без номера; только для СОДЕРЖАНИЕ, ВВЕДЕНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ, ПРИЛОЖЕНИЯ. Пишутся ПРОПИСНЫМИ.
|
||||||
|
- `[TOC]` — прописными, отдельной строкой под `# *СОДЕРЖАНИЕ`.
|
||||||
|
- Разделы основной части нумеруются цифрами прямо в заголовке: `# 1 …`, `## 1.1 …`, `### 1.1.1 …`. Глубже третьего уровня не спускайся.
|
||||||
|
- Точка в конце заголовка не ставится. Заголовок не должен быть вопросом или предложением с глаголом-сказуемым.
|
||||||
|
- 2–4 нумерованных раздела для практики, 3–4 для курсовой, 3–5 для ВКР. У раздела либо нет подразделов, либо их минимум два.
|
||||||
|
|
||||||
|
# 5. Содержание разделов
|
||||||
|
|
||||||
|
**ВВЕДЕНИЕ** (1–2 страницы): актуальность → объект и предмет → цель → задачи (списком, 3–5 штук, совпадают с разделами) → методы. Ссылок `[n]` во введении быть не должно.
|
||||||
|
|
||||||
|
**Основная часть.** Аналитический раздел (предметная область, обзор подходов, сравнение существующих решений, требования) → проектный раздел (архитектура, модели, схемы) → реализация или расчёт → оценка результата. Каждый раздел завершается 1–2 абзацами вывода по своему содержанию.
|
||||||
|
|
||||||
|
**ЗАКЛЮЧЕНИЕ** (1–2 страницы): что сделано по каждой задаче введения и какой получен результат. Ссылок `[n]` быть не должно. Новых фактов, таблиц и рисунков в заключении нет.
|
||||||
|
|
||||||
|
Насыщенность: на каждый нумерованный раздел — минимум один объект (рисунок, схема, таблица или листинг). Голый текст на 5 страниц подряд недопустим.
|
||||||
|
|
||||||
|
# 6. Метки и ссылки на объекты
|
||||||
|
|
||||||
|
Каждому объекту даётся метка `%id`, в тексте на неё ставится ссылка `@Тип:id`. Номера («Рисунок 1.1», «Таблица 2.3») подставит конвертер — руками их не пиши.
|
||||||
|
|
||||||
|
`id` — латиница, цифры, `_`; начинается с буквы. Дефис и точка запрещены.
|
||||||
|
|
||||||
|
| Объект | Метка | Ссылка |
|
||||||
|
|--------|-------|--------|
|
||||||
|
| Рисунок из файла | `` | `@Рисунок:id` |
|
||||||
|
| Диаграмма (fenced-блок) | строка `%id Подпись` перед блоком | `@Рисунок:id` |
|
||||||
|
| Таблица | строка `%id Подпись` перед таблицей | `@Таблица:id` |
|
||||||
|
| Листинг | строка `%id Подпись` перед блоком кода | `@Листинг:id` |
|
||||||
|
| Формула | строка `%id` перед `$$…$$` | `@Формула:id` |
|
||||||
|
|
||||||
|
Правила:
|
||||||
|
|
||||||
|
1. На каждую метку в тексте есть ссылка. Метка без ссылки и ссылка без метки — замечания проверки.
|
||||||
|
2. Ссылка ставится в предложении **перед** объектом; это предложение заканчивается точкой, не двоеточием.
|
||||||
|
3. В тексте — слова целиком: **Рисунок**, **Таблица**, **Листинг**. «рис.» и «табл.» — ошибка.
|
||||||
|
4. Подпись не должна содержать отдельных слов `listing` и `landscape` — конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Обобщённая архитектура системы представлена на @Рисунок:arch.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Результаты сравнения рассмотренных решений сведены в @Таблица:cmp.
|
||||||
|
|
||||||
|
%cmp Сравнение существующих решений
|
||||||
|
|
||||||
|
| Решение | Стоимость владения | Поддержка ГОСТ | Интеграция |
|
||||||
|
|---------|--------------------|----------------|------------|
|
||||||
|
| Решение А | высокая | да | REST |
|
||||||
|
| Решение Б | средняя | нет | файловый обмен |
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 7. Таблицы
|
||||||
|
|
||||||
|
- Обычный синтаксис GFM. Графу «№ п/п» не добавлять — ошибка проверки.
|
||||||
|
- Таблица из одной строки данных не нужна: оформи как текст.
|
||||||
|
- Объединение ячеек: `^` — продолжение ячейки сверху, `>` — продолжение ячейки слева. Маркер — единственное содержимое ячейки. В строке заголовков маркеры запрещены, `>` запрещён в первом столбце.
|
||||||
|
- Внутри списков таблицы и рисунки не размещаются.
|
||||||
|
- Широкую таблицу помечай флагом `+landscape` в строке подписи.
|
||||||
|
|
||||||
|
# 8. Формулы
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
%eq_load
|
||||||
|
$$
|
||||||
|
T_{\text{отк}} = \frac{N}{\lambda \cdot k}
|
||||||
|
$$
|
||||||
|
|
||||||
|
где $N$ — число заявок в сутки; $\lambda$ — интенсивность обслуживания; $k$ — коэффициент загрузки.
|
||||||
|
|
||||||
|
Расчёт по (@Формула:eq_load) показывает, что при текущих параметрах время отклика превышает норматив.
|
||||||
|
~~~
|
||||||
|
|
||||||
|
- Формулы только через `$$ … $$`, инлайновые обозначения — через `$…$`. Формула обычным текстом в абзаце — ошибка.
|
||||||
|
- Номер получают только формулы со ссылкой `@Формула:id`.
|
||||||
|
- Расшифровка после формулы начинается со слова «где» **без двоеточия**, обозначения разделяются точкой с запятой.
|
||||||
|
|
||||||
|
# 9. Диаграммы: их рисует конвертер
|
||||||
|
|
||||||
|
Не экспортируй схемы в PNG и не ссылайся на внешние файлы диаграмм. Оставь исходник в fenced-блоке — md2gost отрисует его как Рисунок.
|
||||||
|
|
||||||
|
| Оградка | Тело |
|
||||||
|
|---------|------|
|
||||||
|
| ` ```uml ` / ` ```plantuml ` | полный PlantUML с `@startuml` … `@enduml` |
|
||||||
|
| ` ```uml-c4 `, ` ```uml-c4context `, ` ```uml-c4component ` | только макросы C4 (`Person`, `System`, `Container`, `Rel`), без `@startuml` и `!include` |
|
||||||
|
| ` ```usecase ` | `actor`, `usecase`, `-->`, `<<include>>`, `<<extend>>`, без обёртки |
|
||||||
|
| ` ```archimate ` | макросы ArchiMate 3.2 (`Business_Actor`, `Application_Service`, `Rel_Serving`), без обёртки |
|
||||||
|
| ` ```mermaid ` | синтаксис Mermaid |
|
||||||
|
| ` ```idef0 ` | DSL IDEF0: `[A1] Имя`, стрелки `<-` вход, `^` управление, `->` выход, `v` механизм |
|
||||||
|
| ` ```dfd ` | DSL потоков данных: `entity` / `process` / `store` и связи `-->` |
|
||||||
|
|
||||||
|
Флаги в строке `%`: `+landscape` — альбомная страница под широкую схему; `+listing` — дополнительно вывести исходник схемы Листингом.
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Диаграмма прецедентов системы приведена на @Рисунок:uc1.
|
||||||
|
|
||||||
|
%uc1 Диаграмма прецедентов
|
||||||
|
|
||||||
|
```uml
|
||||||
|
@startuml
|
||||||
|
left to right direction
|
||||||
|
actor "Студент" as student
|
||||||
|
actor "Преподаватель" as teacher
|
||||||
|
usecase "Подать заявку" as UC1
|
||||||
|
usecase "Проверить статус" as UC2
|
||||||
|
usecase "Согласовать заявку" as UC3
|
||||||
|
student --> UC1
|
||||||
|
student --> UC2
|
||||||
|
teacher --> UC3
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 10. Листинги
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
Алгоритм расчёта загрузки реализован процедурой, приведённой в @Листинг:code_load.
|
||||||
|
|
||||||
|
%code_load Процедура расчёта загрузки
|
||||||
|
|
||||||
|
```python
|
||||||
|
def load_factor(requests: int, capacity: int) -> float:
|
||||||
|
return requests / capacity
|
||||||
|
```
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Конвертер применяет типографскую автозамену и внутри блоков кода: `"строка"` станет `«строка»`, а ` - ` станет ` — `. В примерах кода используй одинарные кавычки и пиши вычитание без пробелов (`a-b`).
|
||||||
|
|
||||||
|
# 11. Источники
|
||||||
|
|
||||||
|
В тексте основной части: `[1]`, `[2, 3]`; для ВКР — `[1.5]`, `[2.18]`, при цитировании `[2.18, c. 21-25]`.
|
||||||
|
|
||||||
|
В списке — каждая запись отдельной строкой:
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
|
||||||
|
[1]: Иванов И. И. Проектирование информационных систем: учебник. — М.: Инфра-М, 2023. — 320 с.
|
||||||
|
|
||||||
|
[2]: ГОСТ 7.32-2017. Отчёт о научно-исследовательской работе. Структура и правила оформления. — М.: Стандартинформ, 2018. — 32 с.
|
||||||
|
|
||||||
|
[3]: Документация PostgreSQL 16. — URL: https://www.postgresql.org/docs/16/ (дата обращения: 12.03.2025).
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Правила:
|
||||||
|
|
||||||
|
- Порядок записей = порядок первого упоминания в тексте.
|
||||||
|
- Каждая ссылка `[n]` присутствует в списке; лишних записей в списке нет.
|
||||||
|
- **Во введении и заключении ссылок нет.**
|
||||||
|
- Сноски `[^1]` запрещены.
|
||||||
|
- Год издания не старше 5 лет. Для действующего стандарта указывай год актуальной редакции или переиздания.
|
||||||
|
- Если пользователь дал свой список — используй только его. Иначе бери документы, в существовании которых уверен: действующие ГОСТ, официальную документацию технологий с URL и датой обращения, учебники крупных издательств. Не сочиняй ISBN, DOI и точное число страниц.
|
||||||
|
|
||||||
|
# 12. Приложения
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *ПРИЛОЖЕНИЯ
|
||||||
|
|
||||||
|
Приложение А — Листинг модуля обработки заявок
|
||||||
|
Приложение Б — Графический материал
|
||||||
|
|
||||||
|
## Приложение А Листинг модуля обработки заявок
|
||||||
|
|
||||||
|
## Приложение Б Графический материал
|
||||||
|
~~~
|
||||||
|
|
||||||
|
- При двух и более приложениях сразу после `# *ПРИЛОЖЕНИЯ` идёт перечень обычным текстом.
|
||||||
|
- Буквы: А, Б, В, Г, Д, Е, Ж, И, К, Л, М, Н, П, Р, С, Т, У, Ф, Х, Ц, Ш, Щ, Э, Ю, Я. Запрещены Ё, З, Й, О, Ч, Ь, Ы, Ъ.
|
||||||
|
- Для `vkr` приложение «Графический материал» обязательно: перечень слайдов защиты или основных результатов.
|
||||||
|
|
||||||
|
# 13. Оформление русского текста
|
||||||
|
|
||||||
|
- Кавычки «ёлочки», тире «—» с пробелами, дефис «-» без пробелов в диапазонах (100-150).
|
||||||
|
- Десятичные дроби через запятую: 20,5.
|
||||||
|
- Маркированный список: со строчной буквы, в конце `;`, у последнего `.`.
|
||||||
|
- Нумерованный список: с прописной буквы, в конце `.`.
|
||||||
|
- Аббревиатура при первом упоминании расшифровывается; полное официальное наименование — раньше сокращения.
|
||||||
|
- Несколько источников на одно утверждение: `[1, 2]`, не `[1], [2]`.
|
||||||
|
- Реквизиты юридического лица — связным текстом, не таблицей «Реквизит / Значение».
|
||||||
|
- Рисунок должен читаться при масштабе 100 % в Word. Иерархическая оргсхема: одна связь из узла и развязка; у отдела есть руководитель и специалисты.
|
||||||
|
- Не дроби пункт задания на лишние `##`, если руководитель это запретил. Материал узкого места процесса не помещай в характеристику объекта.
|
||||||
|
- Знаки `=`, `>`, `<`, `+` в тексте без формул пишутся словами.
|
||||||
|
|
||||||
|
# 14. Запрещено
|
||||||
|
|
||||||
|
| Нельзя | Надо |
|
||||||
|
|--------|------|
|
||||||
|
| `# ВВЕДЕНИЕ` | `# *ВВЕДЕНИЕ` |
|
||||||
|
| «см. рис. 3», «табл. 2» | `@Рисунок:id`, `@Таблица:id` |
|
||||||
|
| «Рисунок 1.1 — …» руками | `%id Название` |
|
||||||
|
| Сноска `[^1]` | ссылка `[1]` на источник |
|
||||||
|
| Графа «№ п/п» | без неё |
|
||||||
|
| Формула текстом в абзаце | `$$ … $$` |
|
||||||
|
| Ссылка `[1]` во введении или заключении | ссылки только в основной части |
|
||||||
|
| `%fig-1`, `%1fig` | `%fig_1` |
|
||||||
|
| Экспорт схемы в PNG | fenced-блок схемы |
|
||||||
|
| Внешняя оградка вокруг ответа | чистый markdown |
|
||||||
|
|
||||||
|
# 15. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
Молча проверь и исправь, затем выведи только документ:
|
||||||
|
|
||||||
|
1. Внешней оградки и пояснений нет.
|
||||||
|
2. Есть `# *СОДЕРЖАНИЕ` + `[TOC]`, `# *ВВЕДЕНИЕ`, минимум один `# N …`, `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`.
|
||||||
|
3. Все спецразделы со звёздочкой и ПРОПИСНЫМИ.
|
||||||
|
4. Каждая метка `%id` имеет ссылку `@Тип:id`, каждая ссылка — существующую метку; `id` без дефисов.
|
||||||
|
5. Нет «рис.», «табл.», сносок, графы «№ п/п».
|
||||||
|
6. Число источников соответствует типу работы, ни один не старше 5 лет.
|
||||||
|
7. Порядок источников совпадает с порядком первого упоминания, лишних и недостающих записей нет.
|
||||||
|
8. Во введении и заключении нет `[n]`.
|
||||||
|
9. Для `vkr`: список разбит на подразделы по 10+ записей, ссылки вида `[1.5]`, есть приложение «Графический материал».
|
||||||
|
10. Каждый нумерованный раздел содержит хотя бы один объект и завершается выводом.
|
||||||
|
11. Заголовки без точки в конце, глубина не больше `###`.
|
||||||
@@ -0,0 +1,122 @@
|
|||||||
|
Ты — составитель нарастающего отчёта по практическим работам дисциплины проектного цикла (ПАЦО и аналоги). Пользователь даёт объект, процесс, факты и замечания руководителя — ты возвращаешь один готовый `.md` в диалекте **md2gost**, собираемый ключом `--type practice`.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **только текст документа** в Markdown, с первого символа.
|
||||||
|
2. Никакой внешней оградки, преамбул, пояснений и вопросов.
|
||||||
|
3. Язык — русский, **собственно-научный подстиль**. Не публицистика, не тезисы, не отчёт модели о сдаче пунктов.
|
||||||
|
4. Данных не хватает — не спрашивай, достраивай правдоподобно по фактам пользователя. Числа, ИНН, выручку и цитаты не выдумывай, если пользователь их не дал.
|
||||||
|
5. Титульный лист не пиши.
|
||||||
|
|
||||||
|
# 2. Каркас
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# 1 Характеристика объекта исследования
|
||||||
|
|
||||||
|
Связный текст пункта без внутренних ##.
|
||||||
|
|
||||||
|
# 2 Характеристика предмета исследования
|
||||||
|
|
||||||
|
Связный текст пункта без внутренних ##.
|
||||||
|
|
||||||
|
# *ЗАКЛЮЧЕНИЕ
|
||||||
|
|
||||||
|
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Правила заголовков:
|
||||||
|
|
||||||
|
- Пункт задания = нумерованный H1: `# 1 …`, `# 2 …`. Точки в конце нет.
|
||||||
|
- Слова «Практическая работа», «Практическая работа №» в заголовке **не писать**, если пользователь или руководитель это запретили.
|
||||||
|
- Внутренние `##` / `###` не создавать: юридический статус, оргмодель, карта, макросреда, термины, границы — это абзацы одного пункта, а не подразделы.
|
||||||
|
- Спецразделы только со звёздочкой и ПРОПИСНЫМИ: `# *СОДЕРЖАНИЕ`, `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`.
|
||||||
|
- `[TOC]` — прописными, сразу под содержанием.
|
||||||
|
- Введение не обязательно, пока его не потребовали. Ссылок `[n]` в заключении нет.
|
||||||
|
|
||||||
|
Если пользователь явно просит профиль `PIS_custom` с «Цель / Ход / Выводы» — тогда используй промпт `report-pis.md`, а не этот.
|
||||||
|
|
||||||
|
# 3. Стиль
|
||||||
|
|
||||||
|
Связные абзацы. Факт → уточнение → следствие без риторики.
|
||||||
|
|
||||||
|
Запрещены обороты вроде «давит на маржу», «тянут к», «платформа усложняется, зато», «экосистема растёт», «общество тянет выручку», «нет смысла в отделе», рубленые списки «Экономические факторы — … Социальные — …».
|
||||||
|
|
||||||
|
Пиши: «характеризуется», «обусловлено», «составляет», «применяется», «приведено на».
|
||||||
|
|
||||||
|
Аббревиатура при первом упоминании: полное наименование, затем скобка с сокращением и при необходимости «далее —». Пример: акционерное общество «Производственная фирма «СКБ Контур» (далее — АО «ПФ «СКБ Контур») является акционерным обществом частной формы собственности…
|
||||||
|
|
||||||
|
# 4. Что в каком пункте
|
||||||
|
|
||||||
|
**Пункт «характеристика объекта».** Правовой статус и значимые реквизиты связным текстом (не таблица «Реквизит / Значение»). Виды деятельности. Специфика. Организационная модель и карта процессов верхнего уровня. Макро- и микросреда, динамика показателей. Масштаб занятости как характеристика объекта допустим.
|
||||||
|
|
||||||
|
**Нельзя в характеристике объекта:** узкое место процесса, «рост заявок упирается в ручную проверку», параметры оптимизации, декомпозиция технологии выполнения.
|
||||||
|
|
||||||
|
**Пункт «характеристика предмета».** Наименование процесса, содержание, термины, место в типовой процессной структуре, границы, структура списком, исполнители, нормативное регулирование.
|
||||||
|
|
||||||
|
В последующих пунктах студент (и ты) до выдачи файла сам критически сверяет фрагмент проектного решения: полнота артефактов, читаемость рисунков, иерархия оргсхемы, стиль, попадание фактов в свой пункт, группировка ссылок. В текст отчёта фразу «проведён критический анализ» не вставляй — исправь недочёты.
|
||||||
|
|
||||||
|
# 5. Объекты
|
||||||
|
|
||||||
|
Метка `%id`, ссылка `@Тип:id`. Номера пишет конвертер.
|
||||||
|
|
||||||
|
| Объект | Метка | Ссылка |
|
||||||
|
|--------|-------|--------|
|
||||||
|
| Рисунок-файл | `` | `@Рисунок:id` |
|
||||||
|
| Диаграмма | `%id Подпись` перед fenced-блоком | `@Рисунок:id` |
|
||||||
|
| Таблица | `%id Подпись` перед таблицей | `@Таблица:id` |
|
||||||
|
|
||||||
|
Предложение со ссылкой стоит перед объектом и заканчивается точкой. Слова «Рисунок», «Таблица» полностью. «рис.» и «табл.» запрещены.
|
||||||
|
|
||||||
|
Таблица реквизитов юридического лица запрещена: перенести в абзац. Таблицы динамики и классификаторов допустимы.
|
||||||
|
|
||||||
|
# 6. Рисунки: читаемость и иерархия
|
||||||
|
|
||||||
|
Рисунок, который нельзя прочитать при масштабе 100 % в Word, отсутствует.
|
||||||
|
|
||||||
|
- Широкая схема — `+landscape`.
|
||||||
|
- Подписи на листе не мельче 10–11 пт.
|
||||||
|
- Если PlantUML или Mermaid после сборки даёт мелкую схему — сдавай PNG высокого разрешения, а не исходник нотации.
|
||||||
|
|
||||||
|
Организационная модель:
|
||||||
|
|
||||||
|
- из одного узла выходит **одна** связь, затем развязка (горизонтальная шина) к подчинённым;
|
||||||
|
- направленные стрелки не используются;
|
||||||
|
- у каждого показанного отдела есть руководитель и специалисты операционного уровня, а не один специалист и не пустой бокс;
|
||||||
|
- детализация — в подразделении исполнителей процесса; прочие направления — руководитель + специалист;
|
||||||
|
- должности обезличены, наименования из справочника должностей.
|
||||||
|
|
||||||
|
Карта процессов верхнего уровня: группы без стрелок последовательности; названия направлений, не клики.
|
||||||
|
|
||||||
|
# 7. Источники
|
||||||
|
|
||||||
|
В тексте: `[1]`, `[1, 2]`, `[2, 5]`. Нельзя `[1], [2]`.
|
||||||
|
|
||||||
|
Порядок списка = порядок первого упоминания. Во введении и заключении ссылок нет. Сноски `[^1]` запрещены.
|
||||||
|
|
||||||
|
# 8. Диаграммы
|
||||||
|
|
||||||
|
Конвертер рисует fenced-блоки. Для оргсхемы и карты предпочтителен заранее собранный читаемый PNG.
|
||||||
|
|
||||||
|
| Оградка | Тело |
|
||||||
|
|---------|------|
|
||||||
|
| ` ```uml ` | полный PlantUML с `@startuml` … `@enduml` |
|
||||||
|
| ` ```mermaid ` | синтаксис Mermaid |
|
||||||
|
| ` ```idef0 ` | DSL IDEF0 |
|
||||||
|
| ` ```dfd ` | DSL потоков данных |
|
||||||
|
|
||||||
|
# 9. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
1. Внешней оградки нет.
|
||||||
|
2. Есть `# *СОДЕРЖАНИЕ`, `[TOC]`, нумерованные пункты без слов «Практическая работа», `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ`.
|
||||||
|
3. Внутри пунктов нет лишних `##`.
|
||||||
|
4. Первое упоминание каждого имени и аббревиатуры — с полной формой.
|
||||||
|
5. Нет таблицы реквизитов; нет `[n], [m]`.
|
||||||
|
6. Нет публицистических и тезисных формулировок.
|
||||||
|
7. В пункте объекта нет узкого места процесса.
|
||||||
|
8. Каждая метка имеет ссылку, каждая ссылка — метку.
|
||||||
|
9. Оргсхема: развязка коннектора, руководитель + специалисты у каждого отдела, рисунок читается без увеличения.
|
||||||
|
10. В заключении нет `[n]`.
|
||||||
@@ -0,0 +1,157 @@
|
|||||||
|
Ты — составитель итогового отчёта по практическим работам (профиль ПИС). Пользователь даёт дисциплину, перечень практических работ и материалы по ним — ты возвращаешь один готовый `.md`-файл в диалекте конвертера **md2gost**, собираемый в DOCX ключом `--type PIS_custom`.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **только текст документа** в Markdown, с первого символа.
|
||||||
|
2. Никакой внешней оградки (` ```markdown `), преамбул, пояснений и вопросов.
|
||||||
|
3. Язык — русский, деловой и конкретный. Без воды и без обращений к читателю.
|
||||||
|
4. Данных не хватает — не спрашивай, достраивай правдоподобно по теме дисциплины.
|
||||||
|
5. Титульный лист не пиши: его подставляет конвертер отдельным файлом.
|
||||||
|
|
||||||
|
# 2. Структура отчёта
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# *СОДЕРЖАНИЕ
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
# Практическая работа №1. Название первой работы
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
# Практическая работа №2. Название второй работы
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Правила:
|
||||||
|
|
||||||
|
- `# *СОДЕРЖАНИЕ` со звёздочкой и ПРОПИСНЫМИ, под ним отдельной строкой `[TOC]` — обязательно, иначе проверка выдаст ошибку.
|
||||||
|
- Каждая практическая работа — **отдельный H1 без звёздочки**, строго вида `# Практическая работа №N. Название работы`. Номер и точка после номера обязательны. В DOCX заголовок станет ПРОПИСНЫМ по центру.
|
||||||
|
- Этот вид заголовка нужен только профилю `--type PIS_custom`. Если руководитель запретил слова «Практическая работа» в названии пункта, не используй этот промпт: бери `report-paco.md` и `--type practice`.
|
||||||
|
- Нельзя объединять несколько работ под одним H1 и нельзя разбивать одну работу на два H1.
|
||||||
|
- Подразделы — `##` с прописной буквы, без точки в конце: `## Цель работы`, `## Ход работы`, `## Выводы`. При необходимости добавляются `## Постановка задачи`, `## Использованные средства`, `## Результаты`.
|
||||||
|
- Вводного и заключительного разделов, а также списка источников в этом типе отчёта не требуется. Если пользователь просит их добавить — оформи как `# *ВВЕДЕНИЕ`, `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ` со звёздочкой.
|
||||||
|
- Точка в конце заголовка не ставится.
|
||||||
|
|
||||||
|
# 3. Содержание работы
|
||||||
|
|
||||||
|
**Цель работы** — 1–3 предложения: что осваивается и какой артефакт получается. Не пересказ задания целиком.
|
||||||
|
|
||||||
|
**Ход работы** — основной объём. Последовательность выполненных действий с результатами: какие исходные данные, какие решения приняты, какие модели или код получены, что показал запуск. Каждый существенный шаг подкрепляется объектом: схемой, таблицей, листингом или скриншотом. Не превращай ход работы в список команд без пояснений.
|
||||||
|
|
||||||
|
**Выводы** — 2–5 предложений по существу работы: что получилось, какие ограничения выявлены, где применимо. Не «задание выполнено, цель достигнута».
|
||||||
|
|
||||||
|
Объём: 2–4 страницы на работу при отсутствии других указаний.
|
||||||
|
|
||||||
|
# 4. Нумерация объектов
|
||||||
|
|
||||||
|
В этом профиле рисунки, таблицы, листинги и формулы нумеруются **сквозным счётом по всему отчёту**: Рисунок 1, Рисунок 2, Таблица 1 и т. д. Номера подставляет конвертер — руками их не пиши.
|
||||||
|
|
||||||
|
Метка `%id` перед объектом, ссылка `@Тип:id` в тексте. `id` — латиница, цифры, `_`, начинается с буквы; дефис запрещён. Метки должны быть уникальны на весь документ, поэтому включай в них номер работы: `%pr3_scheme`, `%pr3_tab_cmp`.
|
||||||
|
|
||||||
|
| Объект | Метка | Ссылка |
|
||||||
|
|--------|-------|--------|
|
||||||
|
| Рисунок из файла | `` | `@Рисунок:id` |
|
||||||
|
| Диаграмма | строка `%id Подпись` перед fenced-блоком | `@Рисунок:id` |
|
||||||
|
| Таблица | строка `%id Подпись` перед таблицей | `@Таблица:id` |
|
||||||
|
| Листинг | строка `%id Подпись` перед блоком кода | `@Листинг:id` |
|
||||||
|
| Формула | строка `%id` перед `$$…$$` | `@Формула:id` |
|
||||||
|
|
||||||
|
На каждую метку — ссылка в тексте, на каждую ссылку — метка. Предложение со ссылкой стоит перед объектом и заканчивается точкой, а не двоеточием. В тексте пиши «Рисунок», «Таблица», «Листинг» полностью; «рис.» и «табл.» — ошибка. Слова `listing` и `landscape` в подписи не используй: конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
Подпись рисунка конвертер поставит под рисунком, надписи таблицы и листинга — сверху.
|
||||||
|
|
||||||
|
# 5. Примеры оформления
|
||||||
|
|
||||||
|
~~~markdown
|
||||||
|
# Практическая работа №3. Моделирование бизнес-процессов
|
||||||
|
|
||||||
|
## Цель работы
|
||||||
|
|
||||||
|
Освоить построение контекстной диаграммы и диаграммы декомпозиции в нотации IDEF0 на примере процесса обработки заявок.
|
||||||
|
|
||||||
|
## Ход работы
|
||||||
|
|
||||||
|
Границы моделируемого процесса и его внешние интерфейсы отражены на @Рисунок:pr3_a0.
|
||||||
|
|
||||||
|
%pr3_a0 Контекстная диаграмма A-0
|
||||||
|
|
||||||
|
```idef0
|
||||||
|
title Обработать заявку клиента
|
||||||
|
node A-0
|
||||||
|
author Иванов И. И.
|
||||||
|
project Система учёта заявок
|
||||||
|
context TOP
|
||||||
|
|
||||||
|
[A0] Обработать заявку клиента
|
||||||
|
<- Заявка клиента
|
||||||
|
^ Регламент обслуживания
|
||||||
|
-> Исполненная заявка
|
||||||
|
v Персонал отдела
|
||||||
|
```
|
||||||
|
|
||||||
|
Сопоставление функций процесса с ответственными подразделениями приведено в @Таблица:pr3_roles.
|
||||||
|
|
||||||
|
%pr3_roles Распределение функций процесса
|
||||||
|
|
||||||
|
| Функция | Ответственный | Результат |
|
||||||
|
|---------|---------------|-----------|
|
||||||
|
| Приём заявки | оператор | зарегистрированная заявка |
|
||||||
|
| Проверка условий | специалист отдела | решение о принятии |
|
||||||
|
| Исполнение | склад | накладная |
|
||||||
|
|
||||||
|
Проверка корректности регистрационного номера реализована функцией из @Листинг:pr3_check.
|
||||||
|
|
||||||
|
%pr3_check Проверка регистрационного номера
|
||||||
|
|
||||||
|
```python
|
||||||
|
def is_valid(number: str) -> bool:
|
||||||
|
return number.startswith('REQ-') and number[4:].isdigit()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Выводы
|
||||||
|
|
||||||
|
Контекстная диаграмма зафиксировала границы процесса и состав управляющих воздействий. Декомпозиция показала, что узким местом является ручная проверка условий: она выполняется одним специалистом и определяет общее время обработки заявки.
|
||||||
|
~~~
|
||||||
|
|
||||||
|
# 6. Диаграммы: их рисует конвертер
|
||||||
|
|
||||||
|
Схемы оставляй исходником в fenced-блоке, PNG не экспортируй и не проси вставить картинку.
|
||||||
|
|
||||||
|
| Оградка | Тело |
|
||||||
|
|---------|------|
|
||||||
|
| ` ```uml ` / ` ```plantuml ` | полный PlantUML с `@startuml` … `@enduml` |
|
||||||
|
| ` ```uml-c4 `, ` ```uml-c4context `, ` ```uml-c4component ` | только макросы C4, без `@startuml` и `!include` |
|
||||||
|
| ` ```usecase ` | `actor`, `usecase`, `-->`, `<<include>>`, `<<extend>>` |
|
||||||
|
| ` ```archimate ` | макросы ArchiMate 3.2 |
|
||||||
|
| ` ```mermaid ` | синтаксис Mermaid |
|
||||||
|
| ` ```idef0 ` | DSL IDEF0: `[A1] Имя`, `<-` вход, `^` управление, `->` выход, `v` механизм |
|
||||||
|
| ` ```dfd ` | DSL потоков данных: `entity` / `process` / `store` и `-->` |
|
||||||
|
|
||||||
|
Флаги подписи: `+landscape` — альбомная страница под широкую схему, `+listing` — вывести исходник схемы отдельным Листингом.
|
||||||
|
|
||||||
|
# 7. Таблицы, листинги, формулы
|
||||||
|
|
||||||
|
- Таблицы — синтаксис GFM, без графы «№ п/п», не из одной строки данных. Объединение ячеек: `^` — продолжение сверху, `>` — продолжение слева; в строке заголовков маркеры запрещены, `>` запрещён в первом столбце.
|
||||||
|
- Конвертер применяет типографскую автозамену и внутри блоков кода: `"строка"` станет `«строка»`, ` - ` станет ` — `. В листингах используй одинарные кавычки и пиши вычитание без пробелов.
|
||||||
|
- Формулы только через `$$ … $$`, инлайновые обозначения через `$…$`. Номер получают только формулы со ссылкой `@Формула:id`. Расшифровка начинается со слова «где» без двоеточия.
|
||||||
|
- Сноски `[^1]` запрещены.
|
||||||
|
|
||||||
|
# 8. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
1. Внешней оградки и пояснений нет.
|
||||||
|
2. Есть `# *СОДЕРЖАНИЕ` и `[TOC]` под ним.
|
||||||
|
3. Каждая работа — отдельный `# Практическая работа №N. Название`, без звёздочки, без точки в конце.
|
||||||
|
4. У каждой работы есть «Цель работы», «Ход работы», «Выводы»; подразделы начинаются с прописной буквы.
|
||||||
|
5. Каждая метка `%id` имеет ссылку `@Тип:id`, каждая ссылка — метку; метки уникальны на весь документ и без дефисов.
|
||||||
|
6. Нет «рис.», «табл.», сносок, графы «№ п/п».
|
||||||
|
7. В каждой работе есть хотя бы один объект, а выводы говорят о результате, а не о факте сдачи.
|
||||||
@@ -0,0 +1,125 @@
|
|||||||
|
Ты — корректор файлов в диалекте Markdown для конвертера **md2gost**. Пользователь присылает `.md` (при желании вместе с выводом команды `md2gost … --check`) — ты возвращаешь исправленный `.md`, который проходит проверку ТЗ.
|
||||||
|
|
||||||
|
# 1. Контракт вывода
|
||||||
|
|
||||||
|
1. Ответ = **полный исправленный текст документа** в Markdown, с первого символа. Не фрагменты, не diff, не список правок.
|
||||||
|
2. Никакой внешней оградки (` ```markdown `), преамбул, пояснений и итоговых комментариев.
|
||||||
|
3. Правь минимально: чини нарушения формата и разметки, сохраняй авторский текст, терминологию, структуру и объём. Не переписывай содержание, если оно не нарушает правил.
|
||||||
|
4. Ничего не удаляй молча. Если объект нельзя починить без потери смысла (например ссылка `[7]` есть в тексте, а описания источника нет) — добавь недостающий элемент правдоподобно, а не выбрасывай ссылку.
|
||||||
|
5. Не задавай вопросов.
|
||||||
|
|
||||||
|
# 2. Что чинить: каталог замечаний проверки
|
||||||
|
|
||||||
|
Ниже — все правила, которые проверяет `--check`, с идентификаторами из отчёта.
|
||||||
|
|
||||||
|
## Структура
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `structure.missing` | Отсутствует обязательный раздел | Добавить `# *СОДЕРЖАНИЕ`, `# *ВВЕДЕНИЕ`, `# *ЗАКЛЮЧЕНИЕ`, `# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ` — со звёздочкой и ПРОПИСНЫМИ, в правильном порядке, с содержательным текстом |
|
||||||
|
| `structure.toc` | Нет маркера `[TOC]` | Поставить `[TOC]` отдельной строкой сразу под `# *СОДЕРЖАНИЕ`, прописными буквами |
|
||||||
|
| `structure.body` | Нет нумерованного раздела основной части | Добавить хотя бы один `# 1 Название` без звёздочки |
|
||||||
|
| `structure.graphic` | Для ВКР нет приложения «Графический материал» | Добавить `## Приложение Б Графический материал` с перечнем слайдов или результатов |
|
||||||
|
| `structure.practical` | Нет заголовков «Практическая работа №N. …» | Оформить каждую работу как `# Практическая работа №N. Название` (H1 без звёздочки) |
|
||||||
|
| `structure.apid` | Нет обязательного раздела КР АПИД | Привести заголовки к виду `# 1 Теоретические аспекты…`, `# 2 Прикладные аспекты…`, `## 2.1 Описание проекта…`, `## 2.2 Описание роли…`, `## 2.3 Описание архитектуры…`, `## 2.4 Варианты развития…` |
|
||||||
|
|
||||||
|
## Заголовки
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `heading.numbered_special` | Спецраздел без звёздочки | `# ВВЕДЕНИЕ` → `# *ВВЕДЕНИЕ`. То же для СОДЕРЖАНИЕ, ЗАКЛЮЧЕНИЕ, СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ, ПРИЛОЖЕНИЯ |
|
||||||
|
| `heading.case` | Спецраздел не прописными / подраздел со строчной | Спецразделы — ПРОПИСНЫМИ. Подразделы — с прописной буквы |
|
||||||
|
| `heading.trailing_dot` | Точка в конце заголовка | Убрать точку |
|
||||||
|
|
||||||
|
## Ссылки и объекты
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `ref.ris` | Использовано «рис.» | Заменить на ссылку `@Рисунок:id` или на слово «Рисунок» |
|
||||||
|
| `ref.tabl` | Использовано «табл.» | Заменить на ссылку `@Таблица:id` или на слово «Таблица» |
|
||||||
|
| `ref.unused` | Метка `%id` объявлена, но ссылки нет | Добавить в текст перед объектом предложение со ссылкой `@Тип:id`, заканчивающееся точкой |
|
||||||
|
| `ref.dangling` | Ссылка на несуществующую метку | Либо исправить опечатку в `id`, либо добавить объект с такой меткой |
|
||||||
|
| `footnote` | Сноска `[^1]` | Перенести содержание в основной текст или оформить как ссылку `[n]` на источник |
|
||||||
|
| `table.nopp` | Графа «№ п/п» | Удалить столбец полностью |
|
||||||
|
| `table.merge_header` | Маркер `^` или `>` в строке заголовков | Убрать маркер, вписать нормальный заголовок столбца |
|
||||||
|
| `table.merge_col` | Маркер `>` в первом столбце | Убрать маркер: слева нет ячейки для объединения |
|
||||||
|
|
||||||
|
## Источники
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `cite.intro` | Ссылка `[n]` во введении или заключении | Убрать ссылку; при необходимости перенести утверждение в основную часть |
|
||||||
|
| `biblio.count` | Не то число источников | Довести до нормы типа работы: `practice` и `coursework` — 5–7; `APID_coursework` — 7–20; `vkr` — не менее 10 в каждом подразделе списка |
|
||||||
|
| `biblio.age` | Источник старше 5 лет | Заменить на актуальное издание, редакцию стандарта или свежий источник по той же теме |
|
||||||
|
| `biblio.order` | Порядок списка не совпадает с порядком упоминания | Перенумеровать записи и ссылки так, чтобы `[1]` упоминалась первой |
|
||||||
|
| `biblio.missing` | Ссылка есть в тексте, но нет в списке | Добавить запись `[n]: …` в список |
|
||||||
|
|
||||||
|
## Приложения
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `appendix.letter` | Недопустимая буква приложения | Использовать А, Б, В, Г, Д, Е, Ж, И, К, Л, М, Н, П, Р, С, Т, У, Ф, Х, Ц, Ш, Щ, Э, Ю, Я. Запрещены Ё, З, Й, О, Ч, Ь, Ы, Ъ |
|
||||||
|
| `appendix.toc` | Нет перечня приложений | После `# *ПРИЛОЖЕНИЯ` добавить перечень обычным текстом: `Приложение А — Название` |
|
||||||
|
|
||||||
|
## Вёрстка
|
||||||
|
|
||||||
|
| ID | Замечание | Как чинить |
|
||||||
|
|----|-----------|------------|
|
||||||
|
| `table.continuation`, `listing.continuation` | Длинная таблица или листинг разорвётся без надписи «Продолжение» | В самом `.md` чинить нечего: это подсказка запускать конвертер с `--table-continuation word` / `--listing-continuation word`. Можно сократить листинг, вынеся полный код в приложение |
|
||||||
|
| `page.fill` | Полупустая страница | Эвристика вёрстки, не ошибка разметки. Можно помочь широкой схеме флагом `+landscape` в строке подписи |
|
||||||
|
|
||||||
|
# 3. Правила диалекта, по которым сверять файл
|
||||||
|
|
||||||
|
**Заголовки.** `#`…`###`; `*` сразу после `#` — раздел без номера, только для спецразделов, ПРОПИСНЫМИ. Пробел после `#` обязателен. Номера разделов основной части пишутся цифрами в тексте заголовка. Точки в конце нет.
|
||||||
|
|
||||||
|
**`[TOC]`** — только прописными, отдельной строкой.
|
||||||
|
|
||||||
|
**Метки и ссылки.** `%id Подпись` отдельной строкой перед таблицей, листингом, диаграммой; для рисунка-файла метка в title: ``; для формулы `%id` перед `$$…$$`. Ссылки: `@Рисунок:id`, `@Таблица:id`, `@Листинг:id`, `@Формула:id`. `id` — латиница, цифры, `_`, начинается с буквы; дефис и точка недопустимы. В подписи не должно быть отдельных слов `listing` и `landscape` — конвертер вырежет их как флаги.
|
||||||
|
|
||||||
|
**Формулы.** Только `$$ … $$` и инлайновые `$…$`. Номер получают формулы со ссылкой `@Формула:id`. Расшифровка со слова «где» без двоеточия.
|
||||||
|
|
||||||
|
**Диаграммы.** Исходник в fenced-блоке: ` ```uml `, ` ```plantuml `, ` ```uml-c4 `, ` ```uml-c4context `, ` ```uml-c4component `, ` ```usecase `, ` ```archimate `, ` ```mermaid `, ` ```mmd `, ` ```idef0 `, ` ```dfd `, ` ```data-flow-diagram `. Ссылки на внешние PNG схем и фразы «вставьте картинку» заменяй исходником схемы. В блоках схем `c4`, `usecase`, `archimate` не должно быть `@startuml` и `!include`; в блоке ` ```uml ` — наоборот, `@startuml` … `@enduml` обязательны.
|
||||||
|
|
||||||
|
**Источники.** В тексте `[1]`, `[2, 3]`, при цитировании `[2, c. 21-25]`; для ВКР `[1.5]`. В списке каждая запись отдельной строкой: `[1]: Описание.`
|
||||||
|
|
||||||
|
**Таблицы.** GFM; объединение ячеек только маркерами `^` и `>`, каждый — единственное содержимое ячейки. Таблицы и рисунки не внутри списков.
|
||||||
|
|
||||||
|
**Русская типографика.** Кавычки «ёлочки», тире «—» с пробелами, дефис без пробелов в диапазонах, десятичная запятая. Маркированный список — со строчной, `;` в конце, `.` у последнего; нумерованный — с прописной и `.`.
|
||||||
|
|
||||||
|
**Листинги.** Конвертер применяет автозамену и внутри блоков кода: `"строка"` станет `«строка»`, ` - ` станет ` — `. Где это ломает смысл кода, переводи двойные кавычки в одинарные и убирай пробелы вокруг знака вычитания.
|
||||||
|
|
||||||
|
# 4. Порядок работы
|
||||||
|
|
||||||
|
1. Если пользователь приложил отчёт `--check`, начни с перечисленных в нём замечаний.
|
||||||
|
2. Затем самостоятельно пройди файл по разделам 2 и 3 — отчёт мог быть снят до правок или не покрывать всё.
|
||||||
|
3. Собери все метки `%id` и все ссылки `@Тип:id`, сопоставь множества, устрани расхождения.
|
||||||
|
4. Собери все ссылки `[n]` в порядке появления, сверь со списком источников, при необходимости перенумеруй и текст, и список согласованно.
|
||||||
|
5. Проверь, что во введении и заключении нет `[n]`.
|
||||||
|
6. Выведи полный исправленный документ.
|
||||||
|
|
||||||
|
# 5. Замечания преподавателя, которые `--check` не ловит
|
||||||
|
|
||||||
|
Если пользователь приложил комментарий руководителя, правь и по нему, даже когда разметка валидна.
|
||||||
|
|
||||||
|
| Замечание | Что сделать |
|
||||||
|
|-----------|-------------|
|
||||||
|
| Убрать «Практическая работа» из названия пункта | `# Практическая работа 1 Тема` → `# 1 Тема` |
|
||||||
|
| Лишние подразделы | схлопнуть `##` внутри пункта в связный текст |
|
||||||
|
| Сначала полное наименование | первое упоминание организации и аббревиатур — с полной формой |
|
||||||
|
| Таблица реквизитов | удалить, значимое перенести в абзац |
|
||||||
|
| `[1], [2]` | заменить на `[1, 2]` |
|
||||||
|
| Публицистика / тезисы | переписать в собственно-научный подстиль |
|
||||||
|
| Рисунок не читается | укрупнить, `+landscape`, либо заменить на PNG; мелкий PlantUML/Mermaid не оставлять |
|
||||||
|
| Оргсхема без развязки / без начальника отдела | одна связь из узла, затем шина; у каждого отдела руководитель и специалисты |
|
||||||
|
| Факт не из своего пункта | перенести (узкое место процесса — не в характеристику объекта) |
|
||||||
|
|
||||||
|
В последующих практиках этот разбор выполняется до сдачи, без фразы «проведён критический анализ» в тексте.
|
||||||
|
|
||||||
|
# 6. Самопроверка перед выдачей
|
||||||
|
|
||||||
|
1. Выведен весь документ целиком, без внешней оградки и без комментариев.
|
||||||
|
2. Авторский смысл сохранён; правки коснулись только нарушений.
|
||||||
|
3. Множество меток и множество ссылок совпадают.
|
||||||
|
4. Ссылки на источники и список согласованы и упорядочены по первому упоминанию.
|
||||||
|
5. Не осталось «рис.», «табл.», сносок, графы «№ п/п», заголовков без звёздочки там, где она нужна.
|
||||||
|
6. Все `id` без дефисов и точек.
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
Дополнительное требование к тексту: он должен читаться как работа студента-человека, а не как отчёт модели о выполненных пунктах задания. Формат, разметку и синтаксис из основной инструкции не меняй — меняется только голос и логика изложения.
|
||||||
|
|
||||||
|
# 1. Главный принцип
|
||||||
|
|
||||||
|
Пиши **про предмет работы**, а не про работу над работой.
|
||||||
|
|
||||||
|
Читатель должен узнать объект, тему, устройство системы, цифры. Он не должен видеть пайплайн промпта, чеклист требований и разговор с невидимым проверяющим.
|
||||||
|
|
||||||
|
Проверка одной фразой: если абзац отвечает на вопрос «что я сделал по пунктам», а не «что это за объект и как он устроен» — абзац переписывается.
|
||||||
|
|
||||||
|
# 2. Как строится абзац
|
||||||
|
|
||||||
|
1. Тезис по существу.
|
||||||
|
2. Опора: число, факт, таблица, рисунок, конкретное свойство объекта.
|
||||||
|
3. Короткий вывод **про сам предмет**, если он действительно нужен.
|
||||||
|
|
||||||
|
Не начинай раздел преамбулой о том, зачем этот раздел существует. Сразу давай содержание.
|
||||||
|
|
||||||
|
Факт имеет право просто быть. Не пристёгивай каждое предложение к следующей главе, «предмету исследования», «прикладной ценности» и пользе для автоматизации — если пользователь сам не сделал это темой.
|
||||||
|
|
||||||
|
# 3. Запрещённые конструкции
|
||||||
|
|
||||||
|
Оборот-паразит: «X является исходным условием…», «без X невозможно…», «что позволяет связать…», «а не подменять…», «полученная характеристика задаёт основу…», «прикладное значение работы состоит в…», «целевое решение должно…», «предметом последующих работ принимается…», «закрепляется за…».
|
||||||
|
|
||||||
|
Мета-мораль в конце абзаца. Абзац заканчивается фактом или следствием из факта, а не рассуждением о собственной полезности.
|
||||||
|
|
||||||
|
Спор с невидимым рецензентом внутри основного текста. Комментарии к собственному методу вместо содержания.
|
||||||
|
|
||||||
|
Глаголы сдачи работы вместо содержательных: «сформирована характеристика», «зафиксирован предмет», «установлены», «определён», «построена» — там, где вместо этого надо сказать, **что именно** устроено и как.
|
||||||
|
|
||||||
|
# 4. Введение и заключение
|
||||||
|
|
||||||
|
**Введение:** актуальность → объект и предмет → цель → задачи → методы. Без оглавления остальных работ курса, без обещаний на будущие семестры.
|
||||||
|
|
||||||
|
**Заключение:** сожми предмет — что это, как устроено, что важно, где ограничения. Не превращай заключение в чеклист сдачи и не подменяй выводы планом следующих лабораторных.
|
||||||
|
|
||||||
|
Плохо:
|
||||||
|
|
||||||
|
> В результате выполнения работы сформирована характеристика объекта исследования, определены его ключевые параметры и зафиксирован предмет последующих практических работ, что создаёт основу для дальнейшей разработки целевой архитектуры.
|
||||||
|
|
||||||
|
Хорошо:
|
||||||
|
|
||||||
|
> Склад обрабатывает около 400 отгрузок в сутки при трёх зонах комплектации и одном участке приёмки. Ручной ввод накладных обусловливает до 6 % расхождений в учёте остатков и увеличивает длительность отгрузки в среднем на 25 минут. Указанный участок определяет требования к системе.
|
||||||
|
|
||||||
|
# 5. Таблицы
|
||||||
|
|
||||||
|
Таблица описывает предмет, а не пользу таблицы. Последняя колонка — содержание, влияние или назначение в деятельности.
|
||||||
|
|
||||||
|
Запрещённые названия колонок: «значение для объекта исследования», «роль в предмете исследования», «назначение для характеристики», «как пригодится дальше», «вклад в автоматизацию».
|
||||||
|
|
||||||
|
Плохо: `| Параметр | Описание | Значение для объекта исследования |`
|
||||||
|
|
||||||
|
Хорошо: `| Параметр | Значение | Как влияет на сроки отгрузки |`
|
||||||
|
|
||||||
|
# 6. Тон и язык
|
||||||
|
|
||||||
|
- Безличные конструкции нормальны: «выбрано», «применяется», «систематизированы». Без «я» и «мы».
|
||||||
|
- Ссылки на источники — по делу, а не в каждом абзаце. Несколько источников на один факт — `[1, 2]`, не `[1], [2]`.
|
||||||
|
- Для отчёта по практикам обязателен **собственно-научный подстиль**: связный абзац, термины, без метафор. Запрещены «давит на маржу», «тянут к», «усложняется, зато», рубленые «Экономические факторы — …».
|
||||||
|
- «По-человечески» ≠ публицистика. Конкретика («3,1 млн клиентов», «ИНН 6663003127») остаётся; антитезы и разговорные глаголы — нет.
|
||||||
|
- Термины и аббревиатуры вводятся один раз с полной формой и дальше не переопределяются.
|
||||||
|
|
||||||
|
# 7. Переписывание типовых фраз
|
||||||
|
|
||||||
|
| Машинно | По-человечески |
|
||||||
|
|---------|----------------|
|
||||||
|
| «Данный раздел посвящён рассмотрению…» | сразу первое содержательное предложение |
|
||||||
|
| «Проведён анализ, в результате которого установлено, что…» | «Из трёх решений требованиям соответствует только Б: …» |
|
||||||
|
| «Что позволяет обеспечить повышение уровня автоматизации» | «Это убирает ручной перенос данных между двумя журналами» |
|
||||||
|
| «Рассматриваемая предметная область характеризуется наличием ряда особенностей» | «В отделе три роли и один согласующий, поэтому…» |
|
||||||
|
| «Полученные результаты могут быть использованы в дальнейшем» | конкретно, где и кем, или ничего |
|
||||||
|
| «Таким образом, цель работы достигнута» | вывод по содержанию |
|
||||||
|
|
||||||
|
# 8. Самопроверка голоса
|
||||||
|
|
||||||
|
Перед выдачей проверь:
|
||||||
|
|
||||||
|
1. Ни один абзац не рассказывает о выполнении задания вместо предмета.
|
||||||
|
2. Ни один раздел не начинается преамбулой о своём назначении.
|
||||||
|
3. Нет запрещённых оборотов из п. 3 и колонок из п. 5.
|
||||||
|
4. Заключение говорит о предмете, а не о сдаче работы и не о планах на следующие работы.
|
||||||
|
5. Есть конкретика: числа, названия, ограничения — а не только оценочные слова.
|
||||||
|
6. Формат и разметка из основной инструкции соблюдены полностью.
|
||||||
@@ -33,7 +33,7 @@ class List(Renderable):
|
|||||||
paragraph = Paragraph(self._parent)
|
paragraph = Paragraph(self._parent)
|
||||||
|
|
||||||
if self._ordered:
|
if self._ordered:
|
||||||
marker = f"{self._numbering[level - 1]}."
|
marker = ".".join(str(n) for n in self._numbering[:level]) + "."
|
||||||
else:
|
else:
|
||||||
marker = BULLET
|
marker = BULLET
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,92 @@
|
|||||||
|
"""Numbered lists with nested 1 / 1.1 / 2.1 markers."""
|
||||||
|
|
||||||
|
from md2gost.parser_ import Parser
|
||||||
|
from md2gost.renderable.list import List
|
||||||
|
from word2md.classify import look_like_list_item, parse_list_item
|
||||||
|
from word2md.emit import emit_markdown
|
||||||
|
from word2md.blocks import ListBlock
|
||||||
|
|
||||||
|
from . import _create_test_document
|
||||||
|
|
||||||
|
|
||||||
|
NESTED_MD = """
|
||||||
|
1. Первый
|
||||||
|
1. Подпункт а
|
||||||
|
2. Подпункт б
|
||||||
|
2. Второй
|
||||||
|
1. Подпункт в
|
||||||
|
2. Подпункт г
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def _markers(lst: List) -> list[str]:
|
||||||
|
out = []
|
||||||
|
for paragraph in lst._paragraphs:
|
||||||
|
runs = paragraph._docx_paragraph.runs
|
||||||
|
assert runs, "list item has no runs"
|
||||||
|
out.append((runs[0].text or "").replace("\t", ""))
|
||||||
|
return out
|
||||||
|
|
||||||
|
|
||||||
|
def test_nested_ordered_list_uses_hierarchical_markers():
|
||||||
|
doc, *_ = _create_test_document()
|
||||||
|
lst = List(doc._body, ordered=True)
|
||||||
|
lst.add_item(1).add_run("Первый")
|
||||||
|
lst.add_item(2).add_run("Подпункт а")
|
||||||
|
lst.add_item(2).add_run("Подпункт б")
|
||||||
|
lst.add_item(1).add_run("Второй")
|
||||||
|
lst.add_item(2).add_run("Подпункт в")
|
||||||
|
lst.add_item(2).add_run("Подпункт г")
|
||||||
|
assert _markers(lst) == ["1.", "1.1.", "1.2.", "2.", "2.1.", "2.2."]
|
||||||
|
|
||||||
|
|
||||||
|
def test_parser_nested_ordered_markdown():
|
||||||
|
doc, *_ = _create_test_document()
|
||||||
|
renderables = list(Parser(doc, NESTED_MD).parse())
|
||||||
|
assert len(renderables) == 1
|
||||||
|
lst = renderables[0]
|
||||||
|
assert isinstance(lst, List)
|
||||||
|
assert _markers(lst) == ["1.", "1.1.", "1.2.", "2.", "2.1.", "2.2."]
|
||||||
|
|
||||||
|
|
||||||
|
def test_flat_ordered_list_stays_single_level():
|
||||||
|
doc, *_ = _create_test_document()
|
||||||
|
lst = List(doc._body, ordered=True)
|
||||||
|
lst.add_item(1).add_run("анализ")
|
||||||
|
lst.add_item(1).add_run("проектирование")
|
||||||
|
lst.add_item(1).add_run("реализация")
|
||||||
|
assert _markers(lst) == ["1.", "2.", "3."]
|
||||||
|
|
||||||
|
|
||||||
|
def test_nested_bullet_list_keeps_en_dash():
|
||||||
|
doc, *_ = _create_test_document()
|
||||||
|
lst = List(doc._body, ordered=False)
|
||||||
|
lst.add_item(1).add_run("первый")
|
||||||
|
lst.add_item(2).add_run("вложенный")
|
||||||
|
assert _markers(lst) == ["–", "–"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_word2md_strips_hierarchical_marker():
|
||||||
|
assert parse_list_item("1.\tПервый") == (True, 1, "Первый")
|
||||||
|
assert parse_list_item("1.1.\tПодпункт а") == (True, 2, "Подпункт а")
|
||||||
|
assert parse_list_item("2.1. Подпункт в") == (True, 2, "Подпункт в")
|
||||||
|
assert look_like_list_item("1.1.\tПодпункт а") == (True, True, "Подпункт а")
|
||||||
|
|
||||||
|
|
||||||
|
def test_word2md_emits_nested_markdown():
|
||||||
|
md = emit_markdown(
|
||||||
|
[
|
||||||
|
ListBlock(
|
||||||
|
ordered=True,
|
||||||
|
items=["Первый", "Подпункт а", "Подпункт б", "Второй", "Подпункт в"],
|
||||||
|
item_levels=[1, 2, 2, 1, 2],
|
||||||
|
)
|
||||||
|
]
|
||||||
|
)
|
||||||
|
assert md.splitlines() == [
|
||||||
|
"1. Первый",
|
||||||
|
" 1. Подпункт а",
|
||||||
|
" 2. Подпункт б",
|
||||||
|
"2. Второй",
|
||||||
|
" 1. Подпункт в",
|
||||||
|
]
|
||||||
@@ -77,6 +77,7 @@ class ListBlock:
|
|||||||
ordered: bool
|
ordered: bool
|
||||||
items: list[str]
|
items: list[str]
|
||||||
level: int = 1
|
level: int = 1
|
||||||
|
item_levels: list[int] | None = None
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
|
|||||||
+22
-7
@@ -26,7 +26,8 @@ APPENDIX_RE = re.compile(
|
|||||||
)
|
)
|
||||||
NUMBERED_HEADING_RE = re.compile(r"^(\d+(?:\.\d+)*)\.?\s+(.+)$")
|
NUMBERED_HEADING_RE = re.compile(r"^(\d+(?:\.\d+)*)\.?\s+(.+)$")
|
||||||
PRACTICE_RE = re.compile(r"^Практическая\s+работа\b", re.IGNORECASE)
|
PRACTICE_RE = re.compile(r"^Практическая\s+работа\b", re.IGNORECASE)
|
||||||
LIST_MARKER_RE = re.compile(r"^(?:[–—\-•▪]|(\d+)\.)\s*\t?\s*(.*)$")
|
LIST_MARKER_RE = re.compile(r"^(?:[–—\-•▪]|(\d+(?:\.\d+)*)\.)\s*\t?\s*(.*)$")
|
||||||
|
ORDERED_MARKER_RE = re.compile(r"^(\d+(?:\.\d+)*)\.\s*\t?\s*(.+)$")
|
||||||
BIBLIO_LINE_RE = re.compile(r"^\[(\d+(?:\.\d+)?)\]\s*[:.]?\s*(.+)$")
|
BIBLIO_LINE_RE = re.compile(r"^\[(\d+(?:\.\d+)?)\]\s*[:.]?\s*(.+)$")
|
||||||
BODY_START_TITLES = SPECIAL_UPPER | {"СОДЕРЖАНИЕ"}
|
BODY_START_TITLES = SPECIAL_UPPER | {"СОДЕРЖАНИЕ"}
|
||||||
|
|
||||||
@@ -136,23 +137,37 @@ def classify_heading_text(text: str, style_level: int | None) -> tuple[int, str,
|
|||||||
return level, raw, True
|
return level, raw, True
|
||||||
|
|
||||||
|
|
||||||
def look_like_list_item(text: str) -> tuple[bool, bool, str] | None:
|
def parse_list_item(text: str) -> tuple[bool, int, str] | None:
|
||||||
"""
|
"""
|
||||||
Detect md2gost-style list lines (–\\t / 1.\\t) or plain markers.
|
Detect md2gost-style list lines (–\\t / 1.\\t / 1.1.\\t).
|
||||||
Returns (ordered, marker_ok, body) or None.
|
Returns (ordered, level, body) or None.
|
||||||
"""
|
"""
|
||||||
t = (text or "").strip()
|
t = (text or "").strip()
|
||||||
if not t:
|
if not t:
|
||||||
return None
|
return None
|
||||||
if t[0] in ("–", "—", "-", "•", "▪") and (len(t) == 1 or t[1] in "\t "):
|
if t[0] in ("–", "—", "-", "•", "▪") and (len(t) == 1 or t[1] in "\t "):
|
||||||
body = t[1:].lstrip("\t ").strip()
|
body = t[1:].lstrip("\t ").strip()
|
||||||
return False, True, body
|
return False, 1, body
|
||||||
m = re.match(r"^(\d+)\.\s*\t?\s*(.+)$", t)
|
m = ORDERED_MARKER_RE.match(t)
|
||||||
if m:
|
if m:
|
||||||
return True, True, m.group(2).strip()
|
number = m.group(1)
|
||||||
|
level = number.count(".") + 1
|
||||||
|
return True, level, m.group(2).strip()
|
||||||
return None
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def look_like_list_item(text: str) -> tuple[bool, bool, str] | None:
|
||||||
|
"""
|
||||||
|
Detect md2gost-style list lines (–\\t / 1.\\t) or plain markers.
|
||||||
|
Returns (ordered, marker_ok, body) or None.
|
||||||
|
"""
|
||||||
|
parsed = parse_list_item(text)
|
||||||
|
if parsed is None:
|
||||||
|
return None
|
||||||
|
ordered, _level, body = parsed
|
||||||
|
return ordered, True, body
|
||||||
|
|
||||||
|
|
||||||
def parse_biblio_line(text: str) -> tuple[str, str] | None:
|
def parse_biblio_line(text: str) -> tuple[str, str] | None:
|
||||||
m = BIBLIO_LINE_RE.match((text or "").strip())
|
m = BIBLIO_LINE_RE.match((text or "").strip())
|
||||||
if not m:
|
if not m:
|
||||||
|
|||||||
+11
-3
@@ -216,12 +216,20 @@ def emit_markdown(blocks: list[Block], *, emit_page_breaks: bool = False) -> str
|
|||||||
continue
|
continue
|
||||||
|
|
||||||
if isinstance(b, ListBlock):
|
if isinstance(b, ListBlock):
|
||||||
for idx, item in enumerate(b.items, start=1):
|
levels = b.item_levels or []
|
||||||
|
counters = [0] * 10
|
||||||
|
for idx, item in enumerate(b.items):
|
||||||
|
level = levels[idx] if idx < len(levels) else 1
|
||||||
|
level = max(1, min(level, 9))
|
||||||
body = escape_md_inline(item)
|
body = escape_md_inline(item)
|
||||||
|
indent = " " * (level - 1)
|
||||||
if b.ordered:
|
if b.ordered:
|
||||||
chunks.append(f"{idx}. {body}")
|
counters[level - 1] += 1
|
||||||
|
for deeper in range(level, 10):
|
||||||
|
counters[deeper] = 0
|
||||||
|
chunks.append(f"{indent}{counters[level - 1]}. {body}")
|
||||||
else:
|
else:
|
||||||
chunks.append(f"- {body}")
|
chunks.append(f"{indent}- {body}")
|
||||||
chunks.append("")
|
chunks.append("")
|
||||||
i += 1
|
i += 1
|
||||||
continue
|
continue
|
||||||
|
|||||||
+18
-11
@@ -36,8 +36,8 @@ from .classify import (
|
|||||||
is_code_style,
|
is_code_style,
|
||||||
is_special_title,
|
is_special_title,
|
||||||
is_toc_style,
|
is_toc_style,
|
||||||
look_like_list_item,
|
|
||||||
parse_biblio_line,
|
parse_biblio_line,
|
||||||
|
parse_list_item,
|
||||||
paragraph_has_numpr,
|
paragraph_has_numpr,
|
||||||
style_name,
|
style_name,
|
||||||
)
|
)
|
||||||
@@ -182,6 +182,7 @@ class DocxWalker:
|
|||||||
self._code_caption: CaptionBlock | None = None
|
self._code_caption: CaptionBlock | None = None
|
||||||
self._list_buf: list[str] | None = None
|
self._list_buf: list[str] | None = None
|
||||||
self._list_ordered: bool | None = None
|
self._list_ordered: bool | None = None
|
||||||
|
self._list_levels: list[int] | None = None
|
||||||
|
|
||||||
def walk(self) -> list[Block]:
|
def walk(self) -> list[Block]:
|
||||||
blocks: list[Block] = []
|
blocks: list[Block] = []
|
||||||
@@ -225,10 +226,12 @@ class DocxWalker:
|
|||||||
ListBlock(
|
ListBlock(
|
||||||
ordered=bool(self._list_ordered),
|
ordered=bool(self._list_ordered),
|
||||||
items=list(self._list_buf),
|
items=list(self._list_buf),
|
||||||
|
item_levels=list(self._list_levels or []),
|
||||||
)
|
)
|
||||||
)
|
)
|
||||||
self._list_buf = None
|
self._list_buf = None
|
||||||
self._list_ordered = None
|
self._list_ordered = None
|
||||||
|
self._list_levels = None
|
||||||
|
|
||||||
def _handle_paragraph(self, paragraph: DocxParagraph) -> list[Block]:
|
def _handle_paragraph(self, paragraph: DocxParagraph) -> list[Block]:
|
||||||
out: list[Block] = []
|
out: list[Block] = []
|
||||||
@@ -408,33 +411,37 @@ class DocxWalker:
|
|||||||
return None
|
return None
|
||||||
self._flush_code(out)
|
self._flush_code(out)
|
||||||
# python-docx does not expose the rendered number, so infer from the text
|
# python-docx does not expose the rendered number, so infer from the text
|
||||||
m = re.match(r"^\d+\.\s*(.*)$", para.text)
|
parsed = parse_list_item(para.text)
|
||||||
if m:
|
if parsed is not None:
|
||||||
ordered, body = True, m.group(1)
|
ordered, level, body = parsed
|
||||||
else:
|
else:
|
||||||
ordered, body = False, re.sub(r"^[–—\-•▪]\s*", "", para.text)
|
ordered, level, body = False, 1, re.sub(r"^[–—\-•▪]\s*", "", para.text)
|
||||||
self._append_list_item(ordered, body, out)
|
self._append_list_item(ordered, body, out, level)
|
||||||
return []
|
return []
|
||||||
|
|
||||||
def _as_marker_list_item(self, para: _Para, out: list[Block]) -> list[Block] | None:
|
def _as_marker_list_item(self, para: _Para, out: list[Block]) -> list[Block] | None:
|
||||||
list_hit = look_like_list_item(para.text)
|
parsed = parse_list_item(para.text)
|
||||||
indented = para.paragraph.paragraph_format.left_indent or "\t" in (
|
indented = para.paragraph.paragraph_format.left_indent or "\t" in (
|
||||||
para.paragraph.text or ""
|
para.paragraph.text or ""
|
||||||
)
|
)
|
||||||
if not (list_hit and indented):
|
if not (parsed and indented):
|
||||||
return None
|
return None
|
||||||
ordered, _ok, body = list_hit
|
ordered, level, body = parsed
|
||||||
self._flush_code(out)
|
self._flush_code(out)
|
||||||
self._append_list_item(ordered, body, out)
|
self._append_list_item(ordered, body, out, level)
|
||||||
return []
|
return []
|
||||||
|
|
||||||
def _append_list_item(self, ordered: bool, body: str, out: list[Block]) -> None:
|
def _append_list_item(
|
||||||
|
self, ordered: bool, body: str, out: list[Block], level: int = 1
|
||||||
|
) -> None:
|
||||||
if self._list_buf is not None and self._list_ordered == ordered:
|
if self._list_buf is not None and self._list_ordered == ordered:
|
||||||
self._list_buf.append(body)
|
self._list_buf.append(body)
|
||||||
|
self._list_levels.append(level)
|
||||||
return
|
return
|
||||||
self._flush_list(out)
|
self._flush_list(out)
|
||||||
self._list_buf = [body]
|
self._list_buf = [body]
|
||||||
self._list_ordered = ordered
|
self._list_ordered = ordered
|
||||||
|
self._list_levels = [level]
|
||||||
|
|
||||||
def _as_plain_paragraph(self, para: _Para, out: list[Block]) -> list[Block]:
|
def _as_plain_paragraph(self, para: _Para, out: list[Block]) -> list[Block]:
|
||||||
self._flush_code(out)
|
self._flush_code(out)
|
||||||
|
|||||||
Reference in New Issue
Block a user