Слияние docx4j 17.3.5 в wordpdf-core и форк FO-рендерера 2.11-docx4j.8 в реактор
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 18m31s

- wordpdf-core/src/main/java впитаны исходники docx4j-core, -export-fo,
  -chart-render, -JAXB-ReferenceImpl, -copy, -generated-objects (17.3.5) +
  сгенерированная XJC JAXB-модель; ресурсы — тем же путём; артефакты группы
  org.docx4j из внешних репозиториев больше не подключаются
- vendor/fop: форк docx4j-fo-renderer 2.11-docx4j.8 (util/events/core/fop)
  собирается в реакторе вместо jar из Nexus
- docx2fo.xslt перевендорен со стилем 17.3.5, оба AUDIT-FIX-патча перенесены;
  дрейф-гейт vendoredXsltTracksJarCopy зелёный
- upstream-тесты docx4j перенесены в src/test/java/org (658 классов, вне гейта);
  execution upstream-docx4j-tests в профиле upstream-tests (./mise.sh run
  upstream-tests, в pr.yml non-blocking шаг): 3470 тестов, 3457 зелёных,
  13 красных — категории окружения/калибровки хоста и следствий слияния
  classpath задокументированы в docs/agent/testing.md
- surefire: провайдер SLF4J фиксируется коротким slf4j.provider по execution;
  перенесён upstream logback.xml (root=DEBUG без конфига ломает visitor-экспорт
  VML); upstream-форки пинят JDK JAXP-фабрики; PMD/JaCoCo исключают org/**
- wordpdf-app: без изменений кода (зависит от слитого ядра); тесты 44/44
- документация синхронизирована (AGENTS.md, README, docs/agent/*), mise task
  upstream-tests
This commit is contained in:
Pjandro
2026-11-08 02:54:49 +00:00
parent f41ac54072
commit 8529b6877b
10191 changed files with 1694473 additions and 75 deletions
+13 -9
View File
@@ -4,11 +4,12 @@
## Project Overview
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP, без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven.
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.5 (исходники слиты в ядро, пакет `org.docx4j.*`) → XSL-FO → форк Apache FOP (`vendor/fop`, 2.11-docx4j.8, собирается из исходников), без LibreOffice/Aspose; Maven Central для группы `org.docx4j` не используется. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven.
| Модуль | Содержимое |
|---|---|
| `wordpdf-core` | библиотека: 62 Java-файла (7 — публичный API, 16 `internal/`, 18 `internal/doc/`, 18 `internal/chart/`, 3 `fonts/`) |
| `wordpdf-core` | библиотека: 4375 Java-файлов — наш код 62 (7 — публичный API, 16 `internal/`, 18 `internal/doc/`, 18 `internal/chart/`, 3 `fonts/`) + слитый docx4j 17.3.5 в `org.docx4j.*`/`org.pptx4j.*`/`org.xlsx4j.*`/`org.glox4j.*`/`org.opendope.*` (≈2.9 тыс. handwritten + ≈2.7 тыс. сгенерированная JAXB-модель); тесты: 53 проекта в ядре (+6 в app) + ≈660 перенесённых upstream-классов |
| `vendor/fop` | форк FO-рендерера `org.docx4j:docx4j-fo-renderer{,-core,-events,-util}:2.11-docx4j.8` (plutext/xmlgraphics-fop), собирается из исходников; JAI 1.1.3 (compile-only) — бинарно в `vendor/fop/lib/`, ставится в локальный репозиторий родителем |
| `wordpdf-app` | REST API на Spring Boot 4.1.1: 11 классов, единственный `public` — `WordPdfApplication` |
| `wordpdf-web` | SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ |
@@ -48,14 +49,15 @@ Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_2
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`; иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `discoverJarFonts.enabled=false` — static-блок: иначе `BestMatchingMapper` сканирует системные шрифты и jar'ы classpath'а, а `restrictToBundled()` всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
- Единственный XSL-FO-стилист — вендорный `xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, Part 1 §17.3.2.24; AUDIT-FIX-2 — `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`, иначе их ловит catch-all `match="*"` и текст теряется). Дрейф-гейт `vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов копия побайтно равна стилю из jar'а. `setCustomXsltTemplates` принимает предкомпилированный `Templates`.
- Единственный XSL-FO-стилист — вендорный `xslt/docx2fo.xslt` (копия из слитого docx4j-export-fo 17.3.5 — база `wordpdf-core/src/main/java/org/docx4j/convert/out/fo/docx2fo.xslt` + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, Part 1 §17.3.2.24; AUDIT-FIX-2 — `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`, иначе их ловит catch-all `match="*"` и текст теряется). Дрейф-гейт `vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов копия побайтно равна стилю из classpath (`org/docx4j/convert/out/fo/docx2fo.xslt`). `setCustomXsltTemplates` принимает предкомпилированный `Templates`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`); приложение исключает его — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.8 (reactor-модуль `vendor/fop`, собирается из исходников; версия пинится свойством `docx4j.fo.renderer.version` в корневом pom; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
- `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла.
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером; `warmup()` идёт тем же потоком.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `docs/agent/pipeline.md`.
- Не чинить: `jc="distribute"`, `suff="tab"`/`lvlJc`, метрика «single», кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`.
- Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
- Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.5 (описанное поведение верно).
- PMD и JaCoCo ядра исключают `org/docx4j/**` (и `org/pptx4j|org/xlsx4j/**`) — слитый чужой код не линтеруется и не входит в порог покрытия. `BundledFontsTest#listedFilesCoverAllTtfInResources` берёт каталог `fonts/` от корня классов модуля, а не первым из classloader'а: после слияния `fonts/` есть и в test-classes (upstream-шрифты тестов).
## Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
@@ -73,13 +75,14 @@ mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsP
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
./mise.sh run upstream-tests # mvn -pl wordpdf-core -am test -Pupstream-tests (upstream-набор, не гейт; десятки минут)
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
./mise.sh run prod-tests # прод-автотесты в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
```
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
Задачи mise (9): `verify`, `upstream-tests`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе.
@@ -101,7 +104,7 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
## Runtime & Tooling
- Java 17 + Maven (обязательны; wrapper `mvnw` НЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml`; ежедневный запуск — `./mise.sh`.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement), новые — latest stable; закреплённый список — `docs/agent/repo-map.md`. Maven-зависимости — через Nexus `maven-central`: локально `~/.m2/settings.xml` (файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL`.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement), новые — latest stable; закреплённый список — `docs/agent/repo-map.md`. Maven-зависимости — через Nexus `maven-central`: локально `~/.m2/settings.xml` (файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL` (в Containerfile ARG пуст по умолчанию → settings не ставится, прямой Central; форк FOP и слитое ядро — reactor из дерева, из репозитория не тянутся).
- Фронт: Node из engines vite/oxlint, `npm ci` с закоммиченным `package-lock.json`, TS `strict` нигде не включён. Контейнеры (podman/buildah): `FROM` только FQDN, хостовые прокси-переменные обнулять на самой команде (`RUN`/`HEALTHCHECK`), `DOCKER_BUILDKIT=0` обязателен, fontconfig рантайму не нужен (глифы — fontbox).
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только `java -jar`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
@@ -109,13 +112,14 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
## CI/CD (Gitea Actions)
`pr.yml` (`PR checks`): job `java` (`mvn -B -s .ci/maven-settings.xml clean verify` через Nexus) + coverage-сводка и комментарий в PR, job `web` (`npm ci` → build → lint). `main.yml`: `java`/`web` → `images-app`/`images-web` (build+push в Nexus, теги `prod` + `sha-<7>`) → `deploy` (SSH, рендер прод-конфигов, гейты healthy) → `autotests` → `rollback` при провале. Нарратив — `docs/agent/ci-cd.md`.
`pr.yml` (`PR checks`): job `java` (`mvn -B -s .ci/maven-settings.xml clean verify` через Nexus, затем non-blocking шаг upstream-набора `-Pupstream-tests` — отчёт, не гейт) + coverage-сводка и комментарий в PR, job `web` (`npm ci` → build → lint). `main.yml`: `java`/`web` → `images-app`/`images-web` (build+push в Nexus, теги `prod` + `sha-<7>`) → `deploy` (SSH, рендер прод-конфигов, гейты healthy) → `autotests` → `rollback` при провале. Нарратив — `docs/agent/ci-cd.md`.
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
## Testing & QA
- Гейты: PMD `maven-pmd-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — LINE `0.90` (оба модуля), BRANCH `0.85` (только core); отчёт `report` раньше `check` (`target/site/jacoco/`). Механика — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
- Гейты: PMD `maven-pmd-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — LINE `0.90` (оба модуля), BRANCH `0.85` (только core); отчёт `report` раньше `check` (`target/site/jacoco/`). В ядре оба гейта исключают слитый код `<excludes>` по пакетам `org/docx4j|glox4j|merlin|opendope|pptx4j|xlsx4j/**`. Механика — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
- Перенесённые upstream-тесты docx4j (`src/test/java/org`) в гейт `verify` **не входят**: default-execution surefire ограничен includes `ru/pjandro/wordpdf/*Test.java` + `ru/pjandro/wordpdf/**/*Test.java` (у plexus-паттернов `**` **не матчит ноль каталогов** — root-пакеты всегда отдельным паттерном, иначе классы корневого пакета молча выпадают из прогона); отдельный execution `upstream-docx4j-tests` в профиле `upstream-tests` (`./mise.sh run upstream-tests`). Провайдер SLF4J фиксируется системным свойством `slf4j.provider` (не `org.slf4j.provider`: SLF4J читает короткий ключ, с длинным фиксация молча игнорируется и побеждает service-discovery) в `argLine` каждого execution (проекные тесты — `slf4j-simple`, upstream — `logback`, он test-зависимость для их 6 лого-тестов): иначе выбор провайдера в classpath непредсказуем и `noLoggingWarningInPdf` нестабилен. Upstream-форки дополнительно пинят перенесённый `src/test/resources/logback.xml` (без конфига root=DEBUG и этот путь ломает visitor-экспорт VML textbox) и JDK-реализации JAXP-фабрик (иначе standalone `xercesImpl` с test-classpath перехватывает парсинг) — категории красных upstream-прогона и ловушки: `docs/agent/testing.md`.
- Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры — `.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`.