JaCoCo: гейт покрытия 90% строк + сводка/артефакты репортов в CI
PR checks / web (pull_request) Successful in 54s
PR checks / java (pull_request) Failing after 1m9s

Корневой pom: jacoco-maven-plugin 0.8.15 (prepare-agent, report+check на
verify, report раньше check — отчёт готов даже при провале гейта), surefire
argLine через @{argLine}. pr.yml/main.yml job java: Coverage summary в
step summary + артефакт jacoco-html (оба шага if: always()).

Тесты ради гейта (23 класса / 218 @Test): app ConversionService/
ApiExceptionHandler/ConversionTimeout +1 в ConvertController; core
DrawMlColor/DrawMlText + инкременты ChartSpec/PresetGeometry.
Покрытие: core 91,0%, app 92,9% строк.
This commit is contained in:
Pjandro
2026-10-24 18:39:44 +00:00
parent dfa6135701
commit 8a07597d4c
12 changed files with 1411 additions and 6 deletions
+8 -5
View File
@@ -58,7 +58,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)|
|корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-**21-jre-alpine** (musl) — chart-движку нужен только модуль java.desktop (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox, см. `fonts/GlyphFont` (проверено на musl-стенде без libfontconfig/`/etc/fonts`); HEALTHCHECK busybox `wget` (curl/apt не ставим), non-root uid 10001); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy`; прод-compose не в репо — его рендерит job `deploy` (лимиты запекаются из Variables); podman-специфика обоих compose: `x-podman.name_separator_compat` (docker-style имена), явные `healthcheck` app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет; app-хелсчеки — `wget`, как в Containerfile), зафиксированная подсеть `10.113.0.0/24` gw `10.113.0.1` под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)|
|корневой `.env.example`|шаблон env для локальных/compose-стендов: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (пустое значение ломает старт — binding long/int); проду `.env` **не нужен**: ключ и лимиты подаёт job `deploy` из Gitea Secrets/Variables, legacy-`.env` на проде удаляется деплоем|
|`.gitea/workflows/`|Gitea Actions: `pr.yml` (PR checks), `main.yml` (тесты → `images-app`/`images-web` (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback)|
|`.gitea/workflows/`|Gitea Actions: `pr.yml` (PR checks), `main.yml` (тесты + coverage-сводка/артефакты JaCoCo → `images-app`/`images-web` (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback)|
|корневой `GITEA-vars.md`|инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений|
|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 21 проверка): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh`|
|`develop/` (вне git, gitignored)|рабочие материалы и эталоны Word для ручного сравнения — **не фикстуры**, в тесты/jar не подключать; на 2026-10 директория пуста (эталоны вынесены, пиксельные замеры зашиты числами в chart-тестах)|
@@ -66,7 +66,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
## Development Commands
```bash
mvn clean verify # все модули + тесты + PMD (pmd-ruleset.xml) — обязательный гейт перед push
mvn clean verify # все модули + тесты + PMD (pmd-ruleset.xml) + гейт покрытия JaCoCo 90% строк — обязательный гейт перед push
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
@@ -90,7 +90,9 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
## CI/CD (Gitea Actions)
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`):
job `java` (temurin 21, кеш `~/.m2` через `actions/cache`, Maven 3.9.16 ставится вручную с dlcdn, `mvn -B clean verify`)
job `java` (temurin 21, кеш `~/.m2` через `actions/cache`, Maven 3.9.16 ставится вручную с dlcdn, `mvn -B clean verify`,
затем `Coverage summary` — разбор `target/site/jacoco/jacoco.xml` python-сниппетом в лог job'а и
`actions/upload-artifact` HTML-отчётов обоих модулей артефактом `jacoco-html`)
и `web` (кеш `~/.npm`, `npm ci`/`build`/`lint`). `.gitea/workflows/main.yml` — `Main: tests,
deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-в-байт
дубль — файлы самодостаточны, reusable-workflow не вводить), затем `images-app`/`images-web`
@@ -135,7 +137,7 @@ SSH-пользователи/логины, ни хосты, ни директо
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=100MB`, держит файл в памяти; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-mb`/`max-pages` здесь намеренно нет.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях), POI `5.5.1` (test: генератор фикстур + in-memory документы в `WordPdfValidatorTest`), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.28.0`.
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях), POI `5.5.1` (test: генератор фикстур + in-memory документы в `WordPdfValidatorTest`), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.28.0`, JaCoCo `0.8.15`.
- Корневой `pmd-ruleset.xml` — ruleset PMD (см. Testing & QA): `category/java/codestyle.xml` минус opinionated-правила, `MethodNamingConventions` с `junit5TestPattern` под underscore-имена регрессий, `TooManyStaticImports` до 12, XPath-правило `LiteralFirstInEquals`, unused-правила из `bestpractices.xml`, `ReturnEmptyCollectionRatherThanNull` (errorprone, priority 1), `AvoidLiteralsInIfCondition` (errorprone, дефолтная 3), `EmptyCatchBlock` (errorprone) и `ForLoopCanBeForeach` (bestpractices) — оба priority 2.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API); `resolver 10.113.0.1` + `proxy_pass` через переменные (статический proxy_pass резолвит имя один раз при старте — gateway раньше app поднялся бы с 502 до перезапуска). `wordpdf-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует.
@@ -155,7 +157,8 @@ SSH-пользователи/логины, ни хосты, ни директо
## Testing & QA
- Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `verify` для обоих модулей, ruleset `pmd-ruleset.xml` (codestyle без opinionated-правил + unused-правила + XPath `LiteralFirstInEquals` — строковый литерал слева в `equals`/`equalsIgnoreCase`; `junit5TestPattern` разрешает underscore-имена регрессий; `includeTests=true` — тесты сканируются; `failurePriority` не задан — на практике `verify` валят нарушения любой приоритетности, проверено на priority 3–4: строки `[WARNING] PMD Failure` = BUILD FAILURE). Литералы в условиях `if` — только именованными константами (`AvoidLiteralsInIfCondition`; `else if`-ветки правило не проверяет, обычный вложенный `if` — проверяет; пустые `while` тоже валятся — `EmptyControlStatement`), `null` вместо пустой коллекции запрещён (`ReturnEmptyCollectionRatherThanNull` — `GlyphCoverageNormalizer.split` возвращает пустой список).
- 18 тестовых классов / 170 `@Test` (core 15/143, app 3/27: ConvertController 18 + ApiKeyFilter 7 + ConvertLimits 2). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`).
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило LINE, COVEREDRATIO `0.90`) на `verify` обоих модулей; агент подключается в surefire через `argLine` = `@{argLine} -Djava.awt.headless=true` (свойство `argLine` в корневом pom по умолчанию пусто и перезаписывается `prepare-agent` — `mvn test -Djacoco.skip=true` без агента работоспособно); `report` и `check` оба на `verify`, report раньше — при провале порога отчёт уже на диске; отчёты `target/site/jacoco/` (html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (`GlyphFont`, `BundledFonts`) и рендер-код, требующий эталонного Word.
- 23 тестовых класса / 218 `@Test` (core 17/180, app 6/38: ConvertController 19 + ApiKeyFilter 7 + ConvertLimits 2 + ConversionService 5 + ApiExceptionHandler 4 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`).
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
- Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word, допуски `assertRatio` <0.06 (`PiePainterTest` аспект h/w=0.585) / <0.10 (`Surface3dPainterTest`, + `assertRange` ±6 pt для центров силуэта); пороги залитых px и перцентильные коридоры яркости. Эталонные замеры — по Word-экспорту 300 dpi (числа зашиты в тесты; эталонные файлы — `develop/`, вне git, на 2026-10 пуста).
- `GlyphFont` (fontbox): метрики пиксельно-метрически эквивалентны AWT (ascent/descent/leading/advance совпадают до 4-го знака, кернинг-дрейф 0.0000 — DejaVu Sans, Carlito). Приёмочный стенд без-fontconfig: контейнер без `libfontconfig.so.1*` и `/etc/fonts`, `mvn verify` + `java -jar` (до перехода на GlyphFont там падали `GlyphCoverageNormalizerTest` 12 / `CartesianPainterTest` 3 / `PiePainterTest` 2 / chart-тесты `WordPdfConverterTest` 4, chart-рендер молча деградировал). `GlyphFontTest` написан без единого `java.awt.Font` — обязан проходить на хосте без fontconfig.