docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+83
View File
@@ -0,0 +1,83 @@
# Окружение разработчика
Требуется **Java 17**, **Maven 3.9.16**, **Node 24** (engines Vite: `^20.19.0 ||
>=22.12.0`), **Python 3.15** (прод-автотесты, сайт документации). Всё это ставит
project-local mise: сам бинарь — в `./.mise/bin` (gitignored), кеш инструментов —
в user-директории mise, **в систему ничего не устанавливается**. Версии пиныны
в `mise.toml`.
## Бутстрап (первая настройка)
```bash
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
```
Дальше команды — через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
```bash
./mise.sh run verify # полный гейт перед push
./mise.sh exec -- mvn -v # любая команда с инструментами в PATH
./mise.sh tasks # список задач
```
Альтернатива — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`):
`eval "$(./.mise/bin/mise activate bash)"`.
## Задачи mise
|Задача|Содержание|
|---|---|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo (гейт перед push)|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (как CI; требует podman/docker)|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|`app-package`|исполняемый jar бэкенда|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|`web-install`|`npm ci` в `wordpdf-web`|
|`web-build`|гейт SPA: `tsc -b && vite build`|
|`web-lint`|oxlint|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|`docs-install`|venv `docs/.venv` + `mkdocs-material`|
|`docs-serve`|локальный предпросмотр сайта на :8000 (live-reload)|
|`docs-build`|strict-сборка сайта в `site/` (битые ссылки/навигация = ошибка)|
|`docs-javadoc`|javadoc публичного API core в `wordpdf-core/target/site/apidocs`|
|`docs-deploy`|публикация сайта на rpi (:9012): javadoc + strict-build + rsync|
## Прямые команды (без задач)
```bash
mvn clean verify # все модули + тесты
mvn test -Djacoco.skip=true # тесты без агента покрытия
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test # -am обязателен: app берёт фикстуры из test-jar core
mvn -pl wordpdf-app -am package # исполняемый jar → wordpdf-app/target/
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
npm ci && npm run build # в wordpdf-web/ (или задачи web-*)
npm run dev # SPA :5173, проксирует /api на :8080
```
## Стенды на контейнерах (podman)
```bash
# dev (:9011), без ключа, springdoc включён
podman-compose -f compose.dev.yml up -d --build --force-recreate
# prod-like (:9010), fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
cp .env.example .env # ключ: openssl rand -hex 32
podman-compose up -d --build
```
`--force-recreate` для dev обязателен: без него podman-compose пересоберёт образ,
но контейнеры оставит на старом jar. Наружу публикуется только nginx-gateway
(9010/9011), 8080 наружу не выставляется. Подробности —
[Стенды](../operations/stack.md).
!!! info "«Запусти тестовый сервер»"
Так в проекте называют dev-стенд (`compose.dev.yml`, `http://<LAN-IP>:9011`),
а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f
compose.dev.yml ps`) + корень SPA отвечает 200.