Rename project to SSAU Generator and restructure content

- Move projects into content/<project>/{docx,pptx} with shared assets/ - Flatten config paths; output = project name in project folder - Add pptx --init scaffold; remove docx exe build - Add feature-complete content/example; ignore content/* except example - Rewrite README and AGENTS.md
2026-10-31 10:18:29 +04:00 · 2026-10-11 23:25:22 +04:00
parent 35611e2a91
commit bf7816ab7c
80 changed files with 1166 additions and 3432 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,111 @@
+# AGENTS.md — управление проектом SSAU Generator
+
+Репозиторий содержит два независимых генератора отчётных документов из Markdown.
+Этот файл описывает управление проектом в целом. Правила работы с конкретным
+документом — в [`docx/AGENTS.md`](docx/AGENTS.md) и [`pptx/AGENTS.md`](pptx/AGENTS.md).
+
+## Что использовать по запросу пользователя
+
+- Просит **сгенерировать документ** (отчёт, DOCX, пояснительную записку,
+  лабораторную работу) — используйте генератор в папке `docx/`.
+- Просит **сгенерировать презентацию** (PPTX, слайды) — используйте генератор в
+  папке `pptx/`.
+
+Команды запускаются из корня репозитория; генератору указывается `config.yaml`
+нужного проекта. Содержимое документа задаётся Markdown-файлами и `config.yaml`
+проекта, а не кодом генератора.
+
+## Правила работы над проектом
+
+- **Уточните название проекта.** Если пользователь не указал, над каким проектом
+  ведётся работа, сначала спросите его. Проект — это папка `content/<проект>/`.
+- **Один проект за сессию.** В рамках одной сессии работайте только над одним
+  проектом.
+- **Создание — только через `--init`.** Новый проект создавайте командами с флагом
+  `--init` (см. ниже): они формируют правильную структуру и общий каталог
+  ресурсов.
+- **Имя результата = имя проекта.** Документ и презентация собираются в папку
+  проекта, а имя файла совпадает с именем проекта:
+  `content/<проект>/<проект>.docx` и `content/<проект>/<проект>.pptx`.
+  Соответствующий путь задаётся ключом `output` в `config.yaml`.
+- **Пересобирайте после правок.** При любом изменении исходных файлов
+  (`config.yaml`, `*.md`, ресурсов в `assets/`) заново запускайте сборку docx
+  и/или pptx, чтобы результат соответствовал исходникам.
+
+## Структура репозитория
+
+```
+ssau-generator/
+├── docx/            # генератор DOCX (только код)
+├── pptx/            # генератор PPTX (только код)
+├── tools/           # общий plantuml.jar (не в git)
+├── content/         # проекты (в git хранится только example)
+│   └── example/
+│       ├── assets/  # общие ресурсы проекта (для docx и pptx)
+│       ├── docx/    # config.yaml + *.md
+│       └── pptx/    # config.yaml + slides/
+├── AGENTS.md        # этот файл
+└── README.md
+```
+
+## Проекты и каталог content
+
+- **Один проект = одна папка** `content/<проект>/`.
+- Внутри проекта при необходимости лежат папки `docx/` и `pptx/`.
+- **Общие ресурсы проекта** (титульный лист, задники, изображения, исходники
+  `.puml`) размещаются в `content/<проект>/assets/` и используются обоими
+  генераторами. В `docx/` и `pptx/` внутри проекта хранятся только `config.yaml`
+  и Markdown.
+- Папки `content/*` добавлены в `.gitignore`; в репозитории хранится только
+  `content/example/`. Рабочие проекты пользователя коммитить не нужно.
+
+## Создание нового проекта
+
+Проект создаётся командами с флагом `--init` — они формируют структуру и общие
+ресурсы автоматически:
+
+```powershell
+# только документ DOCX
+node docx/src/cli.js --content content/<проект>/docx --init
+
+# только презентация PPTX
+node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init
+
+# оба генератора (каталог content/<проект>/assets/ создаётся первым вызовом
+# и переиспользуется вторым)
+```
+
+После создания отредактируйте `config.yaml` и Markdown; общие ресурсы
+(титульный лист, задники, изображения, `.puml`) положите в
+`content/<проект>/assets/`.
+
+## Сборка
+
+```powershell
+# Документ DOCX
+node docx/src/cli.js --content content/<проект>/docx --check
+node docx/src/cli.js --content content/<проект>/docx
+
+# Презентация PPTX
+node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check
+node pptx/src/cli.js -c content/<проект>/pptx/config.yaml
+```
+
+Результат: `content/<проект>/<проект>.docx` или
+`content/<проект>/<проект>.pptx` (имя и путь задаются ключом `output` в
+`config.yaml`). После правок исходников пересобирайте файлы.
+
+## Требования
+
+- Node.js 18+, зависимости устанавливаются командой `npm install` в `docx/` и
+  `pptx/`.
+- Java 11+ и файл `tools/plantuml.jar` (не хранится в git) — для рендеринга схем
+  PlantUML (`.puml`).
+
+## Правила
+
+- Для сборки документа не редактируйте код генераторов — меняйте `config.yaml`
+  и Markdown проекта.
+- Не коммитьте содержимое `content/`, кроме `content/example/`.
+- Не храните ресурсы внутри `docx/` и `pptx/` — общие файлы живут в
+  `content/<проект>/assets/`.