Files
java-word-pdf/docs/agent/pipeline.md
T
Pjandro f3ff218686
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 5m26s
Main: tests, deploy, autotests / web (push) Successful in 9s
Main: tests, deploy, autotests / images-web (push) Successful in 23s
Main: tests, deploy, autotests / java (push) Successful in 1m30s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Successful in 2m13s
Main: tests, deploy, autotests / autotests (push) Successful in 17s
Main: tests, deploy, autotests / rollback (push) Has been skipped
feat(core): собственный рендер OMML→PNG и полный FOP-конфиг шрифтов
Замена JEuclid/AWT-ветки формул на детерминированный растер только
бандл-шрифтами jar (без fontconfig); FOP-конфиг дополняется всеми
бандл-начертаниями при каждом declare — иначе общая FopFactory
замораживает fopconf первого документа и теряет глифы.

MathModel/MathRenderer: OMML (§22.1) → дерево боксов → PNG 300 dpi
(только GlyphFont/fontbox, без java.awt.Font); метрики боксов равны
габариту paint (пределы nary/sPre не обрезаются канвой). Unsupported
конструкция или переполнение бюджета — текстовая деградация (m:t).
Inline-картинка опускается раном w:rPr/w:position на базовую линию
строки (FOP ставит инлайн-графику нижним краем на базу; AUDIT-FIX
baseline-shift). Байтовое правило 6 MathFallbackNormalizer (перед
GlyphCoverage) срезает unsupported-формулы до загрузки docx4j; формула
в wps:txbx уходит в docx4j-фолбэк mathText.

JEuclid исключён из pom (de.rototor jeuclid-core/jeuclid-fop); порядок
zip-правил сдвинут (MathFallback → 6). Порядок сканов шрифтов закрыт
гейтом FontsBundledOnlyInvariantTest + BundledFontAliases (единый
алиас-реестр вместо рефлексивных мутаций реестра).

Счётчики: 63 класса / 1004 теста (core 57/956, app 6/48); JaCoCo
BRANCH core 0.8518. Доки: pipeline/render-limitations/repo-map/
testing/doc-bridge/MEM_USAGE_UPGRADE синхронизированы.
2026-11-20 23:51:40 +03:00

22 KiB
Raw Blame History

читать при правке конвейера WordPdfConverter/нормализаторов/валидатора. Авторитетно наравне с AGENTS.md.

Шаги конвейера 0–7 (полное «что делает» с обоснованиями)

# Шаг Что делает
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)
2 DocxRewritePipeline.STEP → OleObjectNormalizer → WordprocessingMLPackage.load Один zip-проход переписывания XML-частей (правила 1–11 — раздел «Нормализаторы: контракт и правила 1–12» в этом файле) + условная OLE-вычистка (правило 12)
3 pkg.setFontMapper(mapper) Привязка шрифтов документа к физическим TTF
3.5 DrawingPreRenderer.run(pkg, options) c:chart/dgm:relIds/m:oMath → PNG 300 dpi → pic:pic (docx2fo.xslt их не умеет); формулы — собственный растер MathModel/MathRenderer (только бандл-шрифты, без AWT/JEuclid), inline-картинка опускается ран-w:rPr/w:position на свой нижний запас (FOP ставит инлайн-графику нижним краем на базу строки; регрессия — WordPdfConverterTest#ommlMathInline_sitsOnTextBaseline), неподдерживаемая конструкция — текстовая деградация + warn; budget chart/math-PNG общий
4 new FOSettings(pkg) + FopFallbackFonts.declare(foSettings) В FOP-конфиг добавляются все бандл-семейства: FOP встраивает только задекларированные. Конфиг обязан быть полным при каждом declare: docx4j декларирует из fontsInUse только использованные начертания (или simulate-style на regular-файле), а общая FopFactory замораживает fopconf первого документа JVM — declareFamily+hasRealFace дополняют каждое семейство недостающими реальными начертаниями (регрессия — fopFactoryFrozenFromFirstDoc_fontsComplete)
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
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() нет — пакет в памяти

warmup() — прогрев ядра (шаги 0–7 на минимальном docx)

Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы; замер 2026-11), её платил первый запрос после деплоя. Публичный WordPdfConverter.warmup() прогоняет шаги 0–7 на минимальном docx, собранном в байтах (три zip-части константами, фикстуры не задействованы; алиас Calibri→Carlito греет маппер и embed-подмножество), и греет Java2D/PNG-энкодер (warmRaster() — растер + GlyphFont.draw + ImageIO.write), иначе первый чартный документ платит ещё ~200 мс. Идемпотентен (volatile warmedUp, метод synchronized), никогда не бросает (провал — warn в JUL), артефакты отбрасываются; вызывать на потоке, сериализующем конвертации. Ядро само себя не зовёт: wordpdf-app ставит warmup головой очереди воркеров в конструкторе ConversionService. Прогретый первый конверт ru-plain.docx HTTP-запросом: 0,13 с против 1,74 с (A/B на одной машине, сборки ветки и main).

Валидация входа и подсчёт страниц

Вход валидируется до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись: zip PK\x03\x04 или CFB D0 CF 11 E0 → контейнер → страницы). Для .doc страницы считаются по сырым байтам .doc, до конвертации: checkPageCountDoc = max(SummaryInfo PageCount, 1 + разрывы 0x0C − непрерывные межсекционные (sprmSBkc 0/1) + sprmPFPageBreakBefore) (код — DocFile.countPages). Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–11 число учитываемых разрывов не увеличивают (правило 10 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).

  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционные w:sectPr в body + w:br type="page" + pageBreakBefore (включая таблицы и w:sdt). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; WordPdfValidator не зависит от docx4j): атрибуты — по локальному имени (attrLocal, не по transitional-URI: иначе в strict-документе w:br type="page" не засчитываются); sectPr внутри pPr не считает, последнюю body-direct секцию не считает, continuous-секции не считает, в колонтитуках — только w:br type="page", pageBreakBefore — только внутри pPr вне sectPr (truthy val: null|true|1|on). На не-zip молчит — подпись проверяет вызывающий. checkPageCount — один стриминговый проход ZipInputStream без буферизации частей (хелпер noClose глушит close() сканеров): потребление O(одной части) вместо O(суммы XML-частей).

Нормализаторы: контракт и правила 1–12 (детали)

Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame в тестах). Одиннадцать rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу STEP (public static final DocxNormalizer) несёт только DocxRewritePipeline (собирает рерайты сам), у OleObjectNormalizer STEP нет — он подключается лямбдой в WordPdfConverter.normalizers(), а вместо normalize(byte[]) у него normalize(byte[], boolean). Правила 1–11 применяет internal/DocxRewritePipeline — один zip-проход: к каждой записи word/*.xml рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из word/document.xml извлекается полоса набора (TableIndentNormalizer.bandOf, −1 — полосы нет), и word/headerN.xml/footerN.xml дополнительно прогоняются через TableIndentNormalizer.rewritePart с этой полосой, и из word/styles.xml читается множество vanish-стилей (HiddenTextNormalizer.vanishStyles, цепочка w:basedOn) — контекст правила 10; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. OleObjectNormalizer — второй условный проход (меняет части, а не XML). Индивидуальные normalize() десяти нормализаторов сохранены (контракт юнит-тестов), но WordPdfConverter их не вызывает — его normalizers(options) = DocxRewritePipeline.STEP + лямбда OLE. Порядок правил значим:

  1. StrictOoxmlNormalizer — strict-OOXML → transitional: a:-проценты и w14:fillToRect → тысячные ×1000, текст wp14:pctWidth/pctHeight; элементы w:start/w:end → w:left/w:right (кроме w:lvl/w:start в numbering.xml); значения w:val="start"/"end" у w:jc и w:tab правятся всегда (docx4j Justification.setXslFO знает только left/center/right/both, для END fo:text-align не пишет вовсе — jc="end" рендерился по левому краю; Part 1 §17.3.1.13: jc val="end" — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием http://purl.oclc.org (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). Guard сосуществования форм: атрибут w:start/w:end переименовывается только внутри открывающего тега w:ind (MS-OI29500 §2.1.174 — псевдонимы left/right; у w:pgNumType w:start — старт нумерации страниц, легален в transitional, Part 1 §17.13.4 — не трогается) и не переименовывается, если в том же открывающем теге уже есть w:left/w:right (дубль атрибута ломает well-formedness — регрессии indCoexistLeftStartUntouched, indCoexistForms_convertsNotRejected, pgNumTypeStartAttrUntouched); элементы w:start/w:end в strict-части переименовываются глобально, в transitional — только внутри w:tcMar/w:tblCellMar без одноимённого соседа (maxOccurs=1 на left). Ничего не поменялось → rewrite вернул null → исходный массив (StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray).
  2. DocxOnOffNormalizer — w:val="off"/"on" → "false"/"true"; якорь по тегу, правится только атрибут w:val, текст между тегами не трогается.
  3. SymbolFontNormalizer — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает <w:sym>, правит w:lvl в numbering.xml; 5 карт по 256 слотов (таблица SymbolMapper из docx4j 17.x).
  4. FieldNormalizer — fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.
  5. InvisibleCharNormalizer — вырезает из w:t U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D не трогает.
  6. MathFallbackNormalizer — байтовый скан OMML-формул (§22.1) до загрузки пакета: формулы с конструкциями вне MathModel.SUPPORTED (или structurally битые) деградируют в текст — m:oMathPara/m:oMath → обычные раны с конкатенацией m:t (как в штатном фолбэке docx4j XsltFOFunctions.mathText); поддерживаемые части не трогаются (rewrite → null, тот же массив) — их рисует собственный MathRenderer на шаге 3.5. Позиция до GlyphCoverage обязательна: деградировавшие раны с математическими символами (U+1D400+) обязаны пройти резку по покрытию, иначе FOP рисует «#». m:oMathPara содержит m:oMath, поэтому блок para заменяется первым. Регрессия — WordPdfConverterTest#ommlMathUnsupported_flattenedToText, юниты — MathFallbackNormalizerTest.
  7. GlyphCoverageNormalizer — режет раны по покрытию глифов и пишет семейство в w:rFonts, иначе FOP рисует «#». Покрытие — GlyphFont (fontbox, cmap) + BitSet-кэш, не docx4j GlyphCheck (плодит INFO-лог; java.awt.Font требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в SERIF_FAMILIES (dejavu serif, tinos, caladea), затем в sans.
  8. TableIndentNormalizer — свёртка w:tblPr/w:jc (center/right) с любым (в т.ч. отсутствующим/нулевым) w:tblInd в абсолютный w:tblInd с удалением w:jc (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — аудит раскладки ECMA-376, матрица B3, а центрированию пишет абсолютный start-indent без вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right; у CT_PageMar полей w:start/w:end нет, полоса берётся из сырого document.xml до правила 1; дефолты 11906/1440 — измеренное поведение docx4j, ECMA дефолтов не фиксирует §17.6.11/.13), T — Σ gridCol; пропускает несколько body-level sectPr, tblInd с явным w:type ≠ dxa (опущенный type — dxa, §17.4.87), tblPr с tblCellSpacing без tblInd (нет корректной позиции вставки по CT_TblPrBase), tblW pct, нецелые gridCol. Кроме rewrite (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.
  9. NumberingSuffixNormalizer — w:suff w:val="space" → дописанный обычный пробел в конце следующего w:lvlText того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; ST_LevelSuffix Part 1 §17.9.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
  10. HiddenTextNormalizer — вырезание скрытых ранов (Part 1 §17.3.2.41): truthy w:vanish в собственном w:rPr ранa (обе OnOff-формы; вал опущен — default true; явный false/0/off в ране перекрывает vanish-стиль) или 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, #hiddenText_directFalseOverridesVanishStyle, юниты — HiddenTextNormalizerTest.
  11. RubyNormalizer — разбор руби-разметки (Part 1 §17.3.3.24–.28): снимается обёртка w:ruby (схемно-валидная транзишнл-разметка w:r→w:ruby→rubyPr/rt/rubyBase иначе достаёт catch-all-шаблону XSLT, и база теряется молча), w:rubyBase разворачивается в обычные раны, 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.
  12. 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 вместо вычистки — OleFoundException. Лечит оба механизма падения 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»).