Слияние 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:
+1
-1
@@ -6,7 +6,7 @@
|
||||
|
||||
### Job'ы workflow'ов
|
||||
|
||||
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера).
|
||||
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2` по хешу pom'ов включая `vendor/fop/pom.xml`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Upstream docx4j tests` (`-pl wordpdf-core -am test -Pupstream-tests`, `if: always()` + `continue-on-error` — отчёт о состоянии перенесённого набора, не гейт: часть тестов красна из-за окружения/наследия) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера).
|
||||
|
||||
`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
|
||||
|
||||
|
||||
@@ -5,13 +5,13 @@
|
||||
| # | Шаг | Что делает |
|
||||
|---|---|---|
|
||||
| 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j |
|
||||
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера (static `BestMatchingMapper`) регистрирует в `PhysicalFonts` только symbol-шрифты из `docx4j-export-fo-fonts-symbol` (сканы системы и jar'ов отключены в static-блоке `WordPdfConverter` гейт-свойствами — всё найденное всё равно выбрасывает `restrictToBundled()`); `init()` вызывает `dropNonBundled()` **до** регистрации бандла, `restrictToBundled()` оставляет реестр = бандл + встроенные в docx. Порядок `init()` после конструктора — инвариант: `addPhysicalFont` не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) |
|
||||
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера (static `BestMatchingMapper`) регистрирует в `PhysicalFonts` только symbol-шрифты из ресурсного каталога `fonts-symbol` (бывший модуль `docx4j-export-fo-fonts-symbol`, слит в ресурсы ядра; сканы системы и jar'ов отключены в static-блоке `WordPdfConverter` гейт-свойствами — всё найденное всё равно выбрасывает `restrictToBundled()`); `init()` вызывает `dropNonBundled()` **до** регистрации бандла, `restrictToBundled()` оставляет реестр = бандл + встроенные в docx. Порядок `init()` после конструктора — инвариант: `addPhysicalFont` не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) |
|
||||
|2|`DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load`|Один zip-проход переписывания XML-частей (правила 1–10 — раздел «Нормализаторы: контракт и правила 1–11» в этом файле) + условная OLE-вычистка (правило 11)|
|
||||
| 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF |
|
||||
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) |
|
||||
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные |
|
||||
| 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` |
|
||||
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
|
||||
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия стилиста слитого export-fo `org/docx4j/convert/out/fo/docx2fo.xslt` + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
|
||||
| 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF |
|
||||
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
|
||||
| 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти |
|
||||
@@ -39,7 +39,7 @@
|
||||
7. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — Part 1 §17.4.50, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right в transitional и `w:start`/`w:end` в strict; дефолты 11906/1440 — измеренное поведение docx4j, не ECMA-1800), T — Σ gridCol; пропускает несколько body-level `sectPr`, не-dxa `tblInd`, `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite`/`STEP` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.
|
||||
8. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; Part 1 §17.3.1.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
|
||||
9. `HiddenTextNormalizer` — вырезание скрытых ранов (Part 1 §17.3.2.30): truthy `w:vanish` в собственном `w:rPr` ранa (обе OnOff-формы; вал опущен — default true) **или** `w:rStyle` ∈ vanish-стили из `word/styles.xml` (транзитивно по `w:basedOn`, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (`fldChar`/`instrText`/`footnoteReference`/`endnoteReference`/`drawing`/`pict`/`object`/`txbxContent`) не трогается — удаление спаренных `begin…separate…end` сломало бы поле. Word скрытое не печатает, стилист docx4j `vanish` не читает вовсе → без правила скрытое утекало в PDF. Индивидуальный `normalize()` — свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, юниты — HiddenTextNormalizerTest.
|
||||
10. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.18/.19/.20/.21): `w:rubyBase`/`w:rubyBaseText` разворачиваются в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.2 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.
|
||||
10. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.18/.19/.20/.21): `w:rubyBase`/`w:rubyBaseText` разворачиваются в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.5 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.
|
||||
11. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `word/*.xml` не выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10): `w:drawing` переиспользуется дословно, `v:imagedata r:id` → inline-DrawingML на ту же image-часть (размер из `style` `v:shape`, иначе `w:dxaOrig`/`w:dyaOrig` ×635), блоки с `w:control` и без плейсхолдера удаляются. OLE-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `DrawingFoundException(OLE)`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет.
|
||||
|
||||
`mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
|
||||
`mc-preprocessor.xslt` docx4j (в слитом ядре: ресурс `org/docx4j/jaxb/mc-preprocessor.xslt`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
|
||||
|
||||
+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'а, иначе сравнивал бы не тот каталог.
|
||||
|
||||
## Шрифты (детали)
|
||||
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
|
||||
### Счётчики (2026-11)
|
||||
|
||||
- 59 тестовых классов / 898 тестов: core 53/849 (`internal/doc/` 17/225, `internal/chart/` 17/271, `WordPdfConverterTest` 77), app 6/49 (ConvertController 23, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 5, ConversionTimeout 3). Обновлять при изменении набора.
|
||||
- 59 тестовых классов / 898 тестов гейта `verify`: core 53/849 (`internal/doc/` 17/225, `internal/chart/` 17/271, `WordPdfConverterTest` 77), app 6/49 (ConvertController 23, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 5, ConversionTimeout 3). Обновлять при изменении набора.
|
||||
- Перенесённый upstream-набор docx4j (`src/test/java/org`, ~660 классов) — вне гейта: execution `default-test` ограничен includes `ru/pjandro/wordpdf[/**]/*Test.java`, execution `upstream-docx4j-tests` (профиль `upstream-tests`, `./mise.sh run upstream-tests`) берёт `org/{docx4j,pptx4j,xlsx4j}[/**]/*Test(s).java` (кроме `**/samples/**`, `AbstractNumberingTest` — абстрактный базовый класс, и `Docx4jPropertiesFoFileTest` — читает `docx4j.properties` из корня classpath). Провайдер SLF4J фиксируется коротким `-Dslf4j.provider` в `argLine` каждого execution (simple / logback): длинный ключ `org.slf4j.provider` SLF4J 2.x не читает, фиксация молча игнорируется и побеждает service-discovery; часть upstream-тестов (`IntegerRangeReportTest`, `FontReportLogTest`, `CssLengthRangeWarnTest`, `ChartExDefectsTest`, `InspectRangesTest`) кастует логгер к logback — без пина они падали в simple-форке, и наоборот. Порта upstream-овского `logback.xml` (`src/test/resources/logback.xml`, из core-tests) обязателен: без конфига root logback = DEBUG, и DEBUG-only путь ломает visitor-экспорт VML textbox (`CTTextbox` marshal без `@XmlRootElement`); на тесты проекта конфиг не действует (пин simple), в test-jar не попадает (includes `ru/pjandro|samples|geom`). JAXP-фабрики upstream-форки пинят JDK-реализациями (как upstream `docx4j.properties`, который намеренно не портирован — он менял бы поведение всем тестам модуля): иначе `xercesImpl` из test-classpath перехватывает `DocumentBuilderFactory.newInstance()` и `ExtractionConformanceTest` падает на неподдерживаемом standalone-Xerces свойстве `accessExternalDTD`. **Ловушка plexus-паттернов: `**` не матчит ноль каталогов** — классы пакетов `ru/pjandro/wordpdf`, `org.docx4j`, `org.pptx4j`, `org.xlsx4j` добавлены отдельными паттернами; молчаливое исчезновение классов из прогона проверять диффом «`*Test.java` в дереве ↔ `in <класс>` в логе surefire» (так терялись `WordPdfConverterTest`/`WordPdfValidatorTest`).
|
||||
- Триаж upstream-прогона (2026-11): 3470 тестов, 3457 зелёных, 54 skipped, 13 красных — гейтом не считаются (в CI `continue-on-error`, прогон отчётный). Категории: **окружение/калибровка хоста** — `ChartRenderGateTest#gate` (пиксельные метрики против эталонов Office на машине автора), `ChartAnchorSizeTest` ×3 и `ChartImagesTest` ×2 (размеры якорей из xlsx через метрики Calibri; на хосте подстановка Carlito/DejaVu), `FopConfigFamilyTripletTest#noFaceIsDeclaredUnderAnotherFacesFamily` (инвариант по системным шрифтам, ломает `wqy-zenhei.ttc`), `Phase3ProbeWordTest#wordsShapeSurvivesTheUpdaterWithoutPages`; **следствия слияния classpath** — `TocUpdateFacadeTest#pageNumbersWithoutAPaginator` (ждёт TocException «нет docx4j-export-fo», после слияния стилист всегда в ядре), `ChartCreatorHostTest#workbookAuthorAndTimes` и `ChartBoxTest#pptxSvgKeepsTheChartsFrame` (ждут `docx4j.dc.write=true`/`docx4j.DPI=96` из неперенесённого `docx4j.properties`), `MetafileHtmlTest#aDataUriHandlerEmbedsAPng` и `VmlObjectHtmlTest#aMetafilePreviewIsDrawn` (data-URI-рейстеризация metafile в HTML-экспорте, путь проектом не используется; файловый image-handler тот же metafile рейстеризует — соседние методы зелёные). Метод-уровневые `#`-исключения surefire запрещает POM («Method filter prohibited»), поэтому точечные красные методы остаются в отчёте.
|
||||
|
||||
### Пиксели, метрики шрифтов, стенд без fontconfig
|
||||
|
||||
@@ -29,7 +31,7 @@
|
||||
Остальные пары `XxxNormalizerTest`↔`тест-в-конвейере` и юнит-перечисления воспроизводятся грепом по javadoc-ссылкам «Регрессия — Test#имя, фикстура …» (конвенция в AGENTS.md) и удалены отсюда намеренно. Здесь — только записи без javadoc-якорей:
|
||||
|
||||
- `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается.
|
||||
- `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде docx4j — перевендорить и перенести патчи).
|
||||
- `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту слитого export-fo (`org/docx4j/convert/out/fo/docx2fo.xslt` из classpath ядра; при апгрейде docx4j — перевендорить и перенести патчи).
|
||||
- Крафт POIFS (закоммиченных фикстур нет, крафт продублирован в `WordPdfConverterTest`): `ListsTest`+`DocToDocxFormattingTest#list*`↔`docLists_numberingAndBulletsRendered` (синтетический .doc со списками → PDF: `1.` `2.` `a)` `b)` `•`, ни одного `#`; фикстур со списками нет — крафт POIFS продублирован в `WordPdfConverterTest`), `PrcDataTest`+`DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` (TTP-абзац с grpprl в PrcData Data-потока → `w:tbl`/`w:tr`/сетка из цепочки; фикстуры нет — `docTest.doc` заказчика не коммитим, крафт POIFS продублирован), `SectionsTest`+`HeadersTest`+`DocToDocxFormattingTest#twoSections*/sectionBreakInTable*`↔`docMultiSection_perSectionHeaders` (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной `#`; крафт POIFS продублирован в `WordPdfConverterTest`), `ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept`+`DocToDocxFormattingTest#runFlags_*/keepNextKeepLines_*/sectLandscapePgNumCols_*/sectUnevenCols_*/cellVertAlign_*/drawnObject_*`+`SectionsTest#orientationPgNumColumns_applied/unevenColumns_perIndexWidths/restartWithoutStart_clampsToOne`+`TablesTest#vertAlign_*`↔`WordPdfConverterTest#docClassD_landscapeHiddenDelCaps/#docClassD_pageNumberRestartLowerRoman/#docClassD_twoColumnsBreak/#docClassD_drawnObjectBecomesImage` (закрытие пробелов класса D: vanish-фильтр/правки/caps/position/keep, landscape+pgNumType, колонки+column break, vAlign, 0x08→inline-картинка; фикстур нет — крафт POIFS продублирован в обоих тестовых классах).
|
||||
- Синтетика через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`: AUDIT-FIX-2↔`movedRevision_textPrinted`/`bdoDir_textPrinted` (фикстур нет — синтетический docx через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`); пиннинг аудита .docx↔`footnote_rendersAtPageBottom`, `endnote_rendersAtDocumentEnd`, `docxHyperlink_uriAnnotation`, `pageRefField_liveNotCached` (кэш 9001/7777 заменён живым номером), `dateField_notStaleCache` (кэш 01.02.2003 заменён текущей датой), `titlePg_firstPageHeader`, `vMergeCell_spansRows`, `sdtContent_rendered`, `drawingTextBox_textPrinted`, `ommlMath_drawnAsVectors` (пиксели: +150 тёмных px@150dpi сверх текста), `highlightAndShading_backgroundDrawn` (жёлтые px >0 против baseline 0), аудит [MS-DOC] моста 2026-11: `GrpprlTest#tInsertOperand_skippedBySpra`/`tInsertOperand_truncated_aborts` (sprmTInsert — 4 байта, хвост TAP не рассинхронизирован), `TablesTest#cellPadding_*` + `DocToDocxFormattingTest#cellMargins_becomeTcMar` ↔ `WordPdfConverterTest#tableTcMar_textInsetLikeWord` (CSSA→w:tcMar, пайплайн красит поля ячейки как tblCellMar — текст на margin+padding), `StylesTest#characterStyle_stk3_chainViaCharChain`/`charChain_nonCharacterStk_empty` + `DocToDocxFormattingTest#charStyle_viaIstd_mergesUnderDirect` (sprmCIstd: символьная chpx-цепочка между стилевой и прямыми, direct wins), `DocToDocxFormattingTest#runHighlightAndShading_inRPr`/`runShadingPattern_degradesToBackFill`/`paraShd_inPPrBeforeJc` ↔ `docHighlightAndShading_yellowPixels` (Ico→ST_HighlightColor; w:shd в форме FOP val="clear"+fill; паттерн→cvBack), `SectionsTest#titlePage_flagFromSepx` + `DocToDocxFormattingTest#titlePage_emittedAfterCols` ↔ `docTitlePage_firstHeaderOnlyFirstPage` (sprmSFTitlePage + first-слоты Plcfhdd → headerReference type="first", первая страница — только first-шапка)..
|
||||
- App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
|
||||
|
||||
Reference in New Issue
Block a user