- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.3 KiB
Окружение разработчика
Требуется 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`.
Бутстрап (первая настройка)
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
Дальше команды — через обёртку ./mise.sh (Windows: .\mise.ps1):
./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 |
Прямые команды (без задач)
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)
# 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 наружу не выставляется. Подробности —
Стенды.
!!! info "«Запусти тестовый сервер»"
Так в проекте называют dev-стенд (compose.dev.yml, http://<LAN-IP>:9011),
а не java -jar. Готовность — контейнеры healthy (podman-compose -f compose.dev.yml ps) + корень SPA отвечает 200.