Files
java-word-pdf/docs/development/setup.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

4.3 KiB
Raw Blame History

Окружение разработчика

Требуется 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.