SSAUGenerator/docx/AGENTS.md

# AGENTS.md — генератор DocxGenerator

`DocxGenerator` — автономный инструмент, который собирает отчёт в формате **DOCX** из обычных
**Markdown**-файлов по фиксированному дизайну СТО 02068410-004-2018. Поведение полностью
задаётся файлом `config.yaml`.

Документ создан и для людей, и для ИИ-агентов: он описывает CLI, формат контента, схему
конфига и порядок сборки `.exe`.

---

## 1. Требования

- Windows (собранный `.exe` под `win-x64`).
- Node.js **только для сборки** `.exe` из исходников. Конечному пользователю Node.js не нужен.
- Готовые PNG вставляются без внешних зависимостей. Для рендеринга PlantUML (`.puml`)
  нужны установленная Java (JRE 11+) и файл `plantuml.jar` (см. п. 4, `plantuml`).

## 2. Состав дистрибутива

```
DocxGenerator.exe              # исполняемый файл
config.yaml              # настройки (создаётся автоматически при первом запуске)
content/                 # Markdown-файлы документа и ресурсы
  *.md
  assets/
    images/              # PNG для рисунков (готовятся заранее) и исходники .puml
    title-page.docx      # титульный лист (по умолчанию content/assets/title-page.docx)
tools/
  plantuml.jar           # рендерер PlantUML (для файлов .puml)
report.docx              # результат сборки (путь задаётся document.output)
```

Все относительные пути в `config.yaml` считаются **от каталога самого `config.yaml`**.
Сам `config.yaml` и папки ищутся **рядом с `DocxGenerator.exe`**.

В монорепозитории общий `plantuml.jar` лежит в корне, в `tools/plantuml.jar`,
поэтому репозиторный `config.yaml` задаёт `plantuml.jar: ../tools/plantuml.jar`.
Для автономного дистрибутива положите `tools/plantuml.jar` рядом с `.exe`
(значение по умолчанию при `--init` — `tools/plantuml.jar`).

## 3. Командная строка

```
DocxGenerator [опции]

  --config <путь>   путь к config.yaml (по умолчанию рядом с exe)
  --content <dir>   каталог с config.yaml, content/ и assets/ (по умолчанию рядом с exe)
  --output <путь>   переопределить путь выходного .docx
  --check           только проверить конфиг и ссылки, без записи файла
  --init            создать шаблон config.yaml/content/assets и выйти
  --verbose         подробный вывод
  --version         показать версию
  --help            справка
```

Поведение:

- Если `config.yaml` не найден, инструмент **сам создаёт** `config.yaml`, примеры `content/*.md`
  и `assets/images/placeholder.png`, печатает подсказку и завершается.
- `--check` не пишет DOCX, но сообщает обо всех ошибках (битые ссылки, выход `[@n]` за границы
  списка источников, отсутствующие картинки и т.п.).

Типичный цикл работы:

```powershell
.\DocxGenerator.exe --init        # первый запуск: получить шаблон
# ... правим config.yaml и content/*.md ...
.\DocxGenerator.exe --check       # проверить
.\DocxGenerator.exe               # собрать report.docx
```

## 4. Схема `config.yaml`

Любой ключ можно опустить — берётся значение по умолчанию (см. `src/config/defaults.js`).

### document
| Ключ | Тип | Смысл |
|------|-----|-------|
| `output` | string | путь выходного `.docx` |
| `titlePage` | string/null | путь к готовому `title-page.docx` (по умолчанию `content/assets/title-page.docx`); `null` — без титульника |
| `features.updateFields` | bool | обновлять поля (в т.ч. оглавление) при открытии в Word |

**Титульный лист.** Берётся готовый DOCX по пути `document.titlePage` и склеивается перед
документом; между титульником и основным текстом вставляется разрыв страницы. При `--init`
создаётся пример `content/assets/title-page.docx` — замените его своим. Значение `null`
отключает титульный лист.

### paths
| Ключ | Смысл |
|------|-------|
| `assets` | корень ресурсов; `file=images/x.png` в директивах ищется здесь (по умолчанию `content/assets`) |

### output
Путь и имя выходного `.docx` задаются ключом `document.output` (по умолчанию
`report.docx`). Путь считается от каталога `config.yaml` и может быть переопределён
флагом `--output`.

### page
`width`, `height` (DXA, 1/20 pt), `margins: {left,right,top,bottom}` (twips). A4 и поля СТО
заданы по умолчанию.

### typography
| Ключ | Смысл |
|------|-------|
| `font` | гарнитура (по умолчанию Times New Roman) |
| `sizeBody` / `sizeTable` / `sizeSmall` | размеры в half-points (28 = 14 pt) |
| `lineSpacing` | множитель межстрочного интервала (1.5 = полуторный) |
| `color` | цвет текста (hex, без `#`) |
| `useBold` | разрешить полужирный (СТО: `false`) |
| `allowEmphasis` | разрешить курсив (СТО: `false`) |

### headings
Интервалы/выравнивание для `struct`, `section`, `subsection`, `point` (twips).

### captions
`figure`, `table`, `tableContinue` — префиксы и тире подписей (`Рисунок`, `Таблица`, `—`).

### lists
`bulletChar`, `letterSuffix`, `numberSuffix`, `nestedLevelStep`, `forbiddenLetters`.

### numbering
`figures`, `tables`, `formulas`: `global` (сквозная по документу) или `section` (в пределах
раздела, вид `1.1`). Приложения всегда имеют префикс буквы (`А.1`).

### formula
`spacingBeforeAfter`, `whereTabPosition`.

### table
`font`, `size`, `borderColor`, `borderSize`, `cellMargins: {top,bottom,left,right}`,
`headerFill`, `cellFill`.

### figure
`maxWidth` (px; `null` — по ширине полосы), `maxHeight` (px).

### plantuml
Генерация рисунков из исходников PlantUML (см. п. 5, «Рисунки»).

| Ключ | Тип | Смысл |
|------|-----|-------|
| `enabled` | bool | включить рендеринг `.puml`; `false` — считать ошибкой при наличии `.puml` |
| `java` | string | исполняемый файл Java; `auto` — `%JAVA_HOME%\bin\java`, иначе `java` из PATH |
| `jar` | string | путь к `plantuml.jar` (относительно `config.yaml`) |
| `format` | string | только `png` |
| `charset` | string | кодировка исходника (по умолчанию `UTF-8`) |
| `cache` | bool | не перерисовывать неизменённый исходник |
| `cacheDir` | string | каталог кэша PNG (относительно `config.yaml`) |
| `timeoutMs` | int | таймаут рендера одной диаграммы, мс |

Ошибки рендера (нет `jar`, нет Java, синтаксическая ошибка) — **фатальные**: сборка
прекращается с кодом выхода `1`. Требуется установленная Java (JRE 11+) и файл
`plantuml.jar`; для части типов диаграмм нужен Graphviz либо встроенный Smlayout.

### pageNumber
`align`, `format`, `startFrom`.

### toc
`enabled` (bool), `title`, `depth` (1..3). Оглавление вставляется записью
`sections: [{ type: toc }]`.

### bibliography / citation / appendix
`bibliography.title`, `citation: {bracketOpen,bracketClose,pagePrefix}`,
`appendix: {labelPrefix, forbiddenLetters}`.

### sections — структура документа
Упорядоченный список частей:

```yaml
sections:
  - { type: toc }                                        # поле оглавления
  - { file: content/01-introduction.md, type: structural, title: Введение }
  - { file: content/02-main.md,         type: numbered } # # = 1, ## = 1.1, ### = 1.1.1
  - { file: content/03-conclusion.md,   type: structural, title: Заключение }
  - { file: content/04-bibliography.md, type: bibliography }
  - { file: content/05-appendix-a.md,   type: appendix, letter: А, title: Приложение }
```

Типы частей:

| type | Поведение |
|------|-----------|
| `toc` | вставляет оглавление (не требует `file`) |
| `structural` | ненумерованный раздел (Введение/Заключение): заголовок = `title`, ЗАГЛАВНЫМИ, по центру, с новой страницы |
| `numbered` | нумеруемый раздел; `#` = раздел, `##`/`###` = подраздел/пункт |
| `bibliography` | список источников; нумеруется автоматически |
| `appendix` | приложение: заголовок «ПРИЛОЖЕНИЕ <letter>» + `title`, нумерация рисунков/таблиц с префиксом буквы |

## 5. Формат контента

### Заголовки

В файле `type: numbered`:

```md
# НАЗВАНИЕ РАЗДЕЛА        -> 1 НАЗВАНИЕ РАЗДЕЛА (с новой страницы)
## Подраздел             -> 1.1 Подраздел
### Пункт                -> 1.1.1 Пункт
```

Номера подставляются автоматически (Word-numbering). В `structural`/`appendix` заголовок
берётся из конфига, а заголовки внутри файла рендерятся как обычные заголовки без номера.

### Абзацы, списки

Обычные абзацы и списки Markdown. Списки:

```md
- первый пункт;
- второй пункт:
  1. вложенный пункт (выведется как «а) вложенный пункт»);
  2. ещё один.
```

Маркер вложенности выбирается автоматически: тире → `а)` → `1)`. Полужирный/курсив по
умолчанию игнорируются (СТО).

### Таблицы

- Обычная GFM-таблица без директивы — таблица **без подписи и номера**.
- С подписью и автономером — директива `::: table`:

```md
::: table "Название таблицы" id=params note="примечание"
| Параметр | Значение |
|---|---|
| A | 1 |
| B | 2 |
:::
```

### Рисунки

```md
::: figure "Название рисунка" id=arch file=images/arch.png
а) первый поясняемый элемент;
б) второй поясняемый элемент.
:::
```

`file` — относительно `config.paths.assets`. Если файла нет — предупреждение, подпись
всё равно выводится.

**PlantUML.** Если `file` оканчивается на `.puml` (`.plantuml`, `.pu`, `.iuml`), то файл
считается исходником PlantUML: инструмент рендерит его в PNG через локальный
`plantuml.jar` (см. `plantuml` в конфиге) и вставляет результат как обычный рисунок.
Нумерация, ссылки `@fig:id` и примечания работают так же. Пример:

```md
::: figure "Диаграмма последовательности" id=seq file=images/seq.puml
а) запрос клиента;
б) ответ сервера.
:::
```

Ошибка рендера — фатальная (код выхода `1`), `--check` тоже рендерит `.puml`.

**Подписи по СТО.** Подпись ставится **под** рисунком по центру: `Рисунок N — Наименование`
(с прописной буквы, без точки в конце). Если на рисунке обозначены отдельные детали,
пояснительные данные размещают **над подписью** и оформляют перечислением `а)`, `б)`, `в)` —
именно так, как показано в примере выше. Если рисунок общий и пояснять нечего, указывают
только подпись `Рисунок N — Наименование`, а тело директивы оставляют пустым:

```md
::: figure "Общая схема системы" id=common file=images/common.png
:::
```

В приложениях номер рисунка получает префикс буквы: `Рисунок А.1 — Наименование`.

### Формулы

```md
::: formula id=line
y = a*x + b
:::

::: where
y — результат;
x — аргумент;
a — коэффициент.
:::
```

В формулах поддерживается простой синтаксис: `^` (степень), `_` (индекс), `/` (дробь).
Номер формулы ставится автоматически справа.

### Примечания и термины

```md
::: note
Текст примечания.
:::

::: notes
- первое примечание;
- второе примечание.
:::

::: definitions
Термин — определение;
Ещё термин — определение.
:::
```

### Разрыв страницы

```md
::: pagebreak
:::
```

Тематический разрыв `---` также трактуется как разрыв страницы.

### Ссылки на источники

`[@1]` — ссылка на 1-й источник, `[@1, с. 96]` — с номером страницы. Список источников —
это Markdown-список в файле `type: bibliography`; порядок строк = номера источников.
Ссылка вне диапазона — ошибка в `--check`.

### Перекрёстные ссылки

`@fig:id`, `@tbl:id`, `@eq:id` подставляют актуальный номер рисунка/таблицы/формулы
(например `2`, `1.1`, `А.1`). `id` задаётся в директиве.

### Блоки кода

Функция листингов удалена: fenced-блоки ``` игнорируются с предупреждением.

## 6. Проверка и ошибки

`DocxGenerator --check` проверяет:

- корректность `config.yaml` (типы, существование файлов, допустимые буквы приложений);
- наличие всех `sections[].file`;
- существование меток в `@fig/@tbl/@eq`;
- диапазон ссылок `[@n]`;
- рендеринг всех `::: figure ... file=*.puml` (PlantUML).

Ошибки печатаются списком и возвращают код выхода `1`. Предупреждения (например,
отсутствующий PNG) не останавливают сборку; ошибки PlantUML — фатальные.

## 7. Сборка `.exe` из исходников

```powershell
npm install
npm run build:exe      # -> DocxGenerator.exe в корне (target node24-win-x64)
npm run generate       # локальная сборка (node src/cli.js)
npm run check          # проверка конфига и ссылок
```

Упаковка выполняется через `@yao-pkg/pkg`. Чтобы уменьшить размер, можно добавить
`--compress Brotli` в команду `build:exe`.

### Подготовка диаграмм

Готовые PNG кладутся в `content/assets/images/`. Для исходников PlantUML (`*.puml`)
инструмент рендерит PNG сам: положите исходник в `content/assets/images/`, укажите его в
`::: figure ... file=images/<имя>.puml` и поместите `plantuml.jar` в `tools/plantuml.jar`
(или задайте путь в `plantuml.jar`). Диаграммы других форматов (Mermaid, draw.io) готовятся
внешними средствами и вставляются как PNG.

## 8. Замечания по дизайну

- Дизайн фиксирован под СТО 02068410-004-2018; меняются только параметры из `config.yaml`.
- Полужирный и курсив по умолчанию отключены (`typography.useBold`, `allowEmphasis`).
- Шрифт, размеры, интервалы, отступы и подписи настраиваются в конфиге.
- Оглавление — поле Word; при открытии нажмите «Обновить поле», либо включено
  `document.features.updateFields`.