3dd770c542
Пересобран корневой AGENTS.md по результатам параллельного исследования (core src, tests, build/config, app/web/docs). Сохранены все разделы и инварианты, добавлены точные счётчики и недостающие детали, полезные AI-ассистенту (идиомы загрузки фикстур по модулям, жизненный цикл тестов, правила PMD/JaCoCo, карта HTTP-контракта). Исправлен фактический дрейф в соседних справках (docs/agent/* объявлены авторитетными наравне с AGENTS.md): - счётчики тестов: 891 → 893 (core 848 → 849, app 43 → 44; ApiExceptionHandlerTest = 5); - internal/chart: 17 → 18 классов, public ещё и ChartImageHandler; - wordpdf-app: 10 → 11 классов (5 классов исключений); - константа STEP: 8 → 9 из 10 rewrite-нормализаторов (есть у HiddenTextNormalizer); - docs/standards: шесть → восемь каталогов; в перечне docs/agent добавлен repo-map. Проверено: mvn clean verify — 893 теста, PMD (includeTests) и гейты JaCoCo (LINE 0.90 обоих модулей, BRANCH 0.85 core) зелёные.
46 lines
20 KiB
Markdown
46 lines
20 KiB
Markdown
> Извлечение из AGENTS.md; читать при правке конвейера `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–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` |
|
||
| 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 в основном тексте + `sprmPFPageBreakBefore` из PAPX. Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–10 число учитываемых разрывов не увеличивают (правило 9 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
|
||
|
||
- Страницы в валидаторе = `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–11 (детали)
|
||
|
||
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Десять rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу `STEP` (`public static final DocxNormalizer`) выставляют девять из десяти (нет только у `RubyNormalizer` — он цепочный, подключается внутри пайплайна), у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`. Правила 1–10 применяет `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`) — контекст правила 9; неизменённые записи переносятся 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.174a — псевдонимы left/right; у `w:pgNumType` `w:start` — старт нумерации страниц, легален в transitional, Part 1 §17.13.7 — не трогается) и не переименовывается, если в том же открывающем теге уже есть `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. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans.
|
||
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.
|
||
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»).
|