Слияние docx4j 17.3.5 в wordpdf-core и форк FO-рендерера 2.11-docx4j.8 в реактор
- 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:
+17
-10
@@ -9,8 +9,10 @@
|
||||
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` |
|
||||
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) |
|
||||
| `…/wordpdf/internal/chart/` |18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: `DrawingPreRenderer.run` и `ChartImageHandler` — второй инстанцируется из `WordPdfConverter`)|
|
||||
| `wordpdf-core/src/main/java/org/` | Слитый docx4j 17.3.5: `org.docx4j.*` (core + export-fo + chart-render + JAXB-ReferenceImpl + copy-мост), JAXB-модель `org.docx4j.{wml,dml,sharing,vml,…}`, `org.pptx4j.*`/`org.xlsx4j.*`/`org.glox4j.*`, `org.opendope.*`; `docx4j_version.properties` — версия `${docx4j.version}` подставляется фильтрацией ресурсов при сборке (в jar читатель `org.docx4j.Version` видит 17.3.5). PMD/JaCoCo этот код не проверяют. Правки — только точечные AUDIT-FIX с комментарием; апгрейд — перевыгрузка с `~/code/docx4j` + перевендоривание стилиста |
|
||||
| `vendor/fop/` | Форк FO-рендерера `org.docx4j:docx4j-fo-renderer{,-core,-events,-util}:2.11-docx4j.8` (plutext/xmlgraphics-fop, Apache FOP 2.11 main + патчи docx4j); reactor-модуль root-реактора, версия зафиксирована литералом (схема `${revision}`+flatten удалена), профиль release и сторонние `<repositories>` вычищены; в `fop-events` удалено antrun-исполнение `codegen-test-events` (тестовая кодогенерация). `lib/` — JAI `jai-core`/`jai-codec` 1.1.3 бинарно (compile-only для fop-core), ставятся в local repo execution `install-file` у родителя. Отдельный `-pl wordpdf-core` без `-am` требует установленных в local repo jar'ов форка |
|
||||
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar |
|
||||
| `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патчи), часть jar |
|
||||
| `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия `org/docx4j/convert/out/fo/docx2fo.xslt` слитого export-fo + AUDIT-FIX-патчи), часть jar |
|
||||
| `wordpdf-core/src/test/resources/samples/` | 25 закоммиченных фикстур: 13 `.docx` + 12 `.doc` (11 эталонов заказчика из `develop/doc/` с теми же базовыми именами + `doc-formats.doc`); `.docx` проходят `docs/standards/docx/validate-fixtures.py`, `.doc` — бинарные, XSD к ним неприменим |
|
||||
| `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) |
|
||||
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (11 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 5 классов исключений (`BadRequest`, `DrawingRejected`, `ConversionFailed`, `ConversionRejected`, `ConversionTimeout`) |
|
||||
@@ -32,10 +34,10 @@
|
||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера.
|
||||
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=2MB` — части крупнее 2 МБ на диск, не в память; в тон 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); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85).
|
||||
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), 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`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`).
|
||||
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85, `<excludes>` `org/docx4j|glox4j|merlin|opendope|pptx4j|xlsx4j/**`). Зависимости docx4j развёрнуты явным списком (прежние артефакты docx4j-core/export-fo/chart-render/JAXB-ReferenceImpl/copy больше не подключаются). Ресурсы: `docx4j_version.properties` фильтруется вторым resource-блоком (`${docx4j.version}`), остальные — binary-copy. Surefire: default-test ограничен includes `ru/pjandro/wordpdf/*Test.java` + `ru/pjandro/wordpdf/**/*Test.java` (`**` у plexus-паттернов не матчит ноль каталогов — root-пакеты отдельным паттерном) + `-Dslf4j.provider=…SimpleServiceProvider`; профиль `upstream-tests` добавляет execution `upstream-docx4j-tests` (includes `org/{docx4j,pptx4j,xlsx4j}/*Test(s).java` + те же с `/**`, provider logback). PMD: `<excludes>` те же пакеты слитого кода (glob `**/org/…`) в конфигурации плагина модуля.
|
||||
- Корневой `pom.xml` — модули `vendor/fop`, `wordpdf-core`, `wordpdf-app`; все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.5` (свойство `docx4j.version` — только для `docx4j_version.properties` и документации, артефактов группы `org.docx4j` из репозиториев больше нет), форк FOP `docx4j.fo.renderer.version` `2.11-docx4j.8` (reactor `vendor/fop`), commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), logback-classic (test в core — бэкенд upstream-набора; версии classic/core — только из Boot-BOM, собственной managed-записи в корне нет — она затеняет BOM и разносит classic/core), POI `5.5.1` (test), 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`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`).
|
||||
- `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions).
|
||||
- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).
|
||||
- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg). В Containerfile `ARG MAVEN_MIRROR_URL` пустой по умолчанию: без него settings.xml не устанавливается вовсе — прямой Central (локальные podman-сборки); reactor (`vendor/fop` + ядро) собирается из дерева, артефакты `org.docx4j` из репозитория не тянутся; шаг `dependency:go-offline` из Containerfile удалён (он не видел `vendor/fop` до `COPY . .`).
|
||||
- `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); `proxy_read_timeout`/`proxy_send_timeout 300s` (дефолтные 60s рвут 2-минутные конвертации 504 раньше app-ного 504); `resolver 10.113.0.1` + `proxy_pass` через переменные (статический `proxy_pass` резолвит имя один раз при старте — gateway, поднявшийся раньше app, получал бы 502 до перезапуска).
|
||||
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`.
|
||||
@@ -66,12 +68,17 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
|
||||
|
||||
```bash
|
||||
# Перевендорить XSL-FO-стилист после апгрейда docx4j (этого потребует гейт vendoredXsltTracksJarCopy):
|
||||
unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-export-fo-<версия>.jar \
|
||||
org/docx4j/convert/out/fo/docx2fo.xslt > wordpdf-core/src/main/resources/xslt/docx2fo.xslt
|
||||
# затем перенести AUDIT-FIX-патчи (position → baseline-shift; AUDIT-FIX-2 move/bdo/dir — образец в комментарии самого файла)
|
||||
# апгрейд = перевыгрузка дерева org/** из ~/code/docx4j (docx4j-core/-export-fo/-chart-render/
|
||||
# -JAXB-ReferenceImpl/-copy, generated-objects incl. target/generated-sources/xjc) — тогда база обновится сама;
|
||||
# если менялся только стилист, скопировать базу из upstream вручную:
|
||||
cp ~/code/docx4j/docx4j-export-fo/src/main/java/org/docx4j/convert/out/fo/docx2fo.xslt \
|
||||
wordpdf-core/src/main/java/org/docx4j/convert/out/fo/docx2fo.xslt
|
||||
cp wordpdf-core/src/main/java/org/docx4j/convert/out/fo/docx2fo.xslt \
|
||||
wordpdf-core/src/main/resources/xslt/docx2fo.xslt
|
||||
# затем перенести AUDIT-FIX-патчи в resources-копию (position → baseline-shift; AUDIT-FIX-2 move/bdo/dir — образец в комментарии самого файла); база остаётся нетронутой — с ней сравнивает гейт
|
||||
```
|
||||
|
||||
Задачи mise: `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`. Venv прод-автотестов `prod-autotests/.venv` mise создаёт сам (`[env]` в `mise.toml`).
|
||||
Задачи mise: `verify`, `upstream-tests`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`. Venv прод-автотестов `prod-autotests/.venv` mise создаёт сам (`[env]` в `mise.toml`).
|
||||
|
||||
### «Запусти тестовый сервер» (полный текст)
|
||||
|
||||
@@ -110,13 +117,13 @@ PMD: `failurePriority` в плагине не задан — на практик
|
||||
|
||||
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
|
||||
|
||||
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `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`) и защитные ветви сканеров нормализаторов/валидатора.
|
||||
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core, плюс `<excludes>` на пакеты слитого docx4j `org/docx4j|glox4j|merlin|opendope|pptx4j|xlsx4j/**`) на `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`) и защитные ветви ска…
|
||||
- Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`).
|
||||
|
||||
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; сборка web-образа на `node:24-alpine`.
|
||||
- Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …` **на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`.
|
||||
|
||||
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar).
|
||||
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar). После слияния docx4j каталог `fonts/` есть и в `target/test-classes` (upstream-шрифты тестов) — тест разрешает путь от корня классов модуля через `CodeSource` класса (`target/classes/fonts`), а не первым resource из classloader'а, иначе сравнивал бы не тот каталог.
|
||||
|
||||
## Шрифты (детали)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user