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:
@@ -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.
|
||||
Reference in New Issue
Block a user