Igor20264
166 lines
16 KiB
Markdown
166 lines
16 KiB
Markdown
# Проверка ТЗ — полный каталог замечаний
|
||
|
||
Что именно проверяет `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`, факты — вычиткой.
|