Files
java-word-pdf/AGENTS.md
T
Pjandro 230fe233c0
PR checks / web (pull_request) Successful in 32s
PR checks / java (pull_request) Successful in 1m23s
Main: tests, deploy, autotests / web (push) Successful in 32s
Main: tests, deploy, autotests / java (push) Successful in 1m8s
Main: tests, deploy, autotests / images-web (push) Successful in 31s
Main: tests, deploy, autotests / images-app (push) Successful in 44s
Main: tests, deploy, autotests / deploy (push) Failing after 3m14s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Failing after 2m29s
docs(AGENTS): уточнить детали, верифицированные срезом кода
- мост: [MS-ODRAWXML] в docs/standards/docx/; public-поверхность — CfbReader.readStreams
- конвенции: TableIndentNormalizer.rewritePart — второй per-part-хук пайплайна
- app-тесты: четыре Spring-контекста (не три); ConversionService/ApiExceptionHandler без контекста
- compose.dev.yml: springdoc включён по умолчанию (env-переменных нет)
- mise: автосоздание prod-autotests/.venv; CI job web: нода раннера (setup-node нет)
2026-11-01 02:42:21 +00:00

104 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx/.doc → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Бинарный .doc (Word 97-2003) — собственный мост MS-DOC/MS-CFB internal/doc → in-memory .docx → тот же конвейер. Java 17, только Maven.

Три независимых модуля:

  • wordpdf-core — библиотека конвертации (docx4j → XSL-FO → Apache FOP), шрифты и chart/SmartArt-движок внутри.
  • wordpdf-app — REST API (Spring Boot 4.1.1), единственный public-класс — WordPdfApplication.
  • wordpdf-web — SPA (React 19 + TS + Vite + Tailwind), собирается npm, деплоится отдельно от Maven.

Вход стека — gateway-контейнер nginx (:9010 prod-like compose / :9011 dev), не 8080. Авторитетны этот файл и код.

Architecture & Data Flow

Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions])

Порядок фиксирован, местами менять нельзя (WordPdfConverter.convertToStream). Вход роутируется по сигнатуре до входа в конвейер: PK\x03\x04 → docx-путь, D0 CF 11 E0 A1 B1 1A E1 (CFB, MS-CFB §2.2) → мост DocToDocx.convert → in-memory .docx → этот конвейер (WordPdfValidator.isBinaryDoc — единый предикат):

# Шаг Что делает
0 DependencyGuard.check() API-проба ZipArchiveInputStream.getNextEntry() — совместимость commons-compress ≥ 1.25.0; иначе ConversionException с инструкцией вместо мутного NoSuchMethodError внутри docx4j
1 new BundledFontMapper() → BundledFonts.init() → restrictToBundled() Конструктор маппера добавляет системные шрифты в глобальный реестр PhysicalFonts; init() вызывает dropNonBundled() до регистрации бандла (addPhysicalFont не перезаписывает занятый ключ — иначе системный Calibri ломает em-dash-fallback)
2 DocxRewritePipeline.STEP → OleObjectNormalizer → WordprocessingMLPackage.load Один zip-проход переписывания XML-частей (правила 1–8, см. ниже) + условная OLE-вычистка (правило 9)
2.5 WordPdfValidator.checkPageCount(normalizedBytes, maxPages) Lightweight-оценка страниц по zip, до рендера
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); 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() нет — пакет в памяти

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

Мост .doc → .docx (internal/doc)

Нормативный источник — docs/standards/doc/ ([MS-DOC], [MS-CFB], [MS-OLEPS], [MS-ODRAW]; [MS-ODRAWXML] лежит в docs/standards/docx/), ссылки — с номерами секций. Новых runtime-зависимостей нет (POI остаётся test-scope; POIFS — только в тестах для упаковки крафтовых CFB). Публичные точки: DocToDocx.convert(byte[]) (вызывает WordPdfConverter) и DocToDocx.countPages(byte[]) (вызывает WordPdfValidator.checkPageCountDoc); общий разбор — DocFile (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — DocToDocx и CfbReader (public, публичный член — static readStreams(byte[])).

Класс Спецификация
CfbReader [MS-CFB] заголовок (секторы 512/4096, mini 64), FAT/DIFAT (лимиты секторов + защита от циклов), miniFAT + mini stream из root, directory; любой брак (цикл, ссылка за файл, обрезанный поток, битый заголовок) → ValidationException
FibHeader [MS-DOC §2.4.1/§2.6.1] FibBase (fWhichTblStm — бит 9 u16@10 → 1Table/0Table), FibRgLw97 (ccpText/ccpFtn/ccpHdd), пары FibRgFcLcb97: fcStshf=1, fcPlcfSed=6, fcPlcfHdd=11, fcPlcfBteChpx=12, fcPlcfBtePapx=13, fcSttbfFfn=15, fcClx=33, fcDggInfo=50, fcPlfLst=73, fcPlfLfo=74
PieceTable §2.9.135 Clx/Pcdt: куски compressed (FC/2, байт + CP1252-карта 0x80–0x9F) и uncompressed (UTF-16LE); FC за потоком → ValidationException
Grpprl §2.6.2 sprm'ы: CHPX — bold 0x0835, italic 0x0836, strike 0x0837, kul 0x2A3E, hps 0x4A43, hpsBi 0x4A61, ftc0 0x4A4F, ftc1 0x4A50, cv 0x6870 (4-й байт FF → auto), sprmCFSpec 0x0875, rMarkDel 0x0800/rMarkIns 0x0801 (непринятые правки → w:del/w:ins), smallCaps 0x083A/caps 0x083B (апкейс текста в мосту), vanish 0x083C (фильтр рана — FO w:vanish не читает), hpsPos 0x4845 (со знаком, hps → w:position), sprmCPicLocation 0x6A03 (смещение BLIP в Data); PAPX — sprmPHugePapx 0x6646/sprmPTableProps 0x646B (указатели на PrcData в Data, разворачивает PrcData.resolve; Grpprl.scan сам их корректно пропускает по spra=3), jc 0x2461 (4→distribute, 5/7/8/9→both, 6 — игнор) и jc80 0x2403 (3/4/5 — justify-both с разной компрессией, distribute у jc80 нет), dxaLeft/dxaLeft1/dxaRight + 80-варианты 0x840F/0x8411/0x840E и sprmPNest 0x465F/sprmPNest80 0x4610 (XAS со знаком → hanging/firstLine; общий накопитель Grpprl.Indents: nest к своему dxaLeft, современное семейство вытесняет 80-е), pageBreakBefore 0x2407 (перед ним keepFollow 0x2406/keep 0x2405 → w:keepNext/w:keepLines), InTable 0x2416, sprmPFTtp 0x2417, istd 0x8463, LSPD 0x6412 (dyaLine i16 + fMult), before/after 0xA413/0xA414, PChgTabs 0xC60D и sprmPChgTabs 0xC615 (табы стиля; PChgTabsDelClose §2.9.182 — радиус удаления из rgdxaClose, XAS_plusOne), ilvl 0x260A (u8; 0x0C — «пропустить, не нумеровать»), ilfo 0x460B (i16: 0/0xF801 — списока нет, 1..0x07FE — 1-базированный индекс rgLfo, 0xF802..0xFFFF — отрицание индекса с сохранением отступов); TAP — sprmTDefTable 0xD608, sprmTTableBorders 0xD613, sprmTTableBorders80 0xD605, sprmTJc 0x548A / sprmTJc90 0x5400 (u16 0/1/2 → left/center/right, единый маппинг: FOP complex-script не поддерживает, RTL вне контура), sprmTVertAlign 0xD62C (CellRangeVertAlign §2.9.30: cb=3 + itcFirst + itcLim + VerticalAlign 0/1/2 → w:vAlign; cb≠3 — операнд игнорируется). Спец-длины операндов spra=6: у 0xD608 счётчик cb двухбайтовый («остаток+1», §2.9.321 — формула «1+первый байт» врёт при cb>255), у 0xC60D cb=0xFF — обрыв разбора; у 0xC615 cb=0xFF — длина 3 + 4·cTabsDel + 3·cTabsAdd по раскладке §2.9.182 (разбор продолжается)
ChpxIndex/PapxIndex §2.4.6: PlcfBte (aFc n+1 + pn 22 бита) → FKP-страницы 512 Б по pn·512 (rgfc (n+1)×4, rgbx n×1/×13, crun/cpara — последний байт); Chpx = cb + grpprl; PapxInFkp: cb≠0 → GrpPrlAndIstd 2cb−1, cb=0 → cb′ → 2cb′ (внутри istd(2) + grpprl, grpprl может быть пустым — istd без прямых Prl); bOffset=0 → свойств нет (дефолт), но граница rgfc[j+1] в индекс заносится — иначе дефолтный ран проглотил бы последующие CHPX-раны абзаца (регрессии ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept, WordPdfConverterTest#docClassD_landscapeHiddenDelCaps); istd сохраняется (istdFor, вне диапазона −1) — по нему DocxBody применяет цепочку Styles
Styles §2.9.271 STSH по fcStshf: LPStshi (cbStshi, cstd, cbSTDBaseInFile) → LPStd на чётных границах → Std (stdf: sti/stk/istdBase/cupx + xstzName + LPUpx): stk=1 → UPX[0]=UpxPapx (istd(2)+grpprl), UPX[1]=UpxChpx. Цепочка base-first (предок раньше потомка, last-wins при скане); istdBase 0x0FFF — без предка, цикл — обрыв на MAX_CHAIN=16. Разбор снисходительный (образец FontTable): битый/отсутствующий STSH → пустая таблица, конвертация на прямых свойствах, без ValidationException
Tables TAP TTP-абзаца (§2.6.3) → Grid(colWidths, indent, bordersXml, tblJc, cellVAlign): sprmTDefTable (§2.9.321, ncols 1..63, rgdxaCenter XAS со знаком — ширина = center[i+1]−center[i], первый center — сдвиг от поля); границы: sprmTTableBorders (§2.9.302, 6×Brc: cv fAuto, dptLineWidth 1/8pt, brcType §2.9.39) иначе sprmTTableBorders80 (§2.9.303, ico→цвет §2.9.171); brcType=0 не эмитится, ≥0x40 ширина ×8, sz<2 → 2; выравнивание: sprmTJc/sprmTJc90 (u16: 1→"center", 2→"right", прочее → null — элемент не эмитится), современный перекрывает 90-вариант (тот же приоритет, что у 0xD613 над 0xD605) → w:jc в tblPr (openTable; регрессия — WordPdfConverterTest#docFooterTableCentered_shiftedLikeWord); вертикальное выравнивание ячеек: sprmTVertAlign 0xD62C (CellRangeVertAlign §2.9.30) → cellVAlign[] по индексам колонок (диапазоны clamped к сетке, top/вне диапазона — не эмитится) → w:vAlign в w:tcPr после w:gridSpan (регрессии — TablesTest#vertAlign_, DocToDocxFormattingTest#cellVertAlign_). null (нет/битый TDefTable, неположительная ширина) → строка деградирует в плоские абзацы
Lists §2.9.200/.201 PlfLst/PlfLfo → word/numbering.xml: PlfLst — cLst SHORT (2 Б) при fc, rgLstf с fc+2 (§2.9.201, Figure 56); LSTF (28 Б, fSimpleList→1 LVL иначе 9, массив LVL приложен за fc+lcb) + LVL (LVLF 28 Б: iStartAt/nfc/jc/ixchFollow/cbGrpprl'ы; Xst: плейсхолдеры 0x00–0x08 → %{n+1}, литеральный % → %%) → w:abstractNum (MSONFC [MS-OSHARED §2.2.1.3] → ST_NumberFormat §17.18.59, общий numFmt с DocxBody.appendPgNumType, экзотика CJK → decimal — нет глифов в бандле; ixchFollow 1/2 → w:suff space/nothing, 0=tab не эмитится; grpprlPapx уровня → w:ind, grpprlChpx → w:rPr rFonts/b/sz); LFO (lsid→первый LSTF) + LFOLVL (fStartAt → w:startOverride, fFormatting → полный w:lvl) → w:num (numId = 1-базированный ilfo). Снисходительно (образец Styles): битая таблица/обрыв LVL → пустой/неполный результат; hasNum — numId разрешается в валидный abstractNum, иначе абзацы деградируют в плоские
Sections PlcfSed (§2.8.26): aCP n+1 + Sed n (12 Б) + Sepx (cb + секционные sprm) → list() — список record'ов Section (CP-диапазон, геометрия секции, continuous из sprmSBkc, landscape из sprmSBOrientation 0x301D (§2.9.236: 1/2), нумерация страниц — pgNumStart (0 = не задан; sprmSFPgnRestart 0x3011 + sprmSPgnStart97 0x501C, restart без start клампится к 1) и nfcPgn (sprmSNfcPgn 0x300E, MSONFC), колонки — sprmSCcolumns 0x500B (число − 1, кап 44), sprmSFEvenlySpaced 0x3005 (Bool8, дефолт true), sprmSDxaColumns 0x900C; при неравных колонках per-column ширины/зазоры из sprmSDxaColWidth 0xF203/sprmSDxaColSpacing 0xF204 (SDxaColWidthOperand/SDxaColSpacingOperand §2.9.241/.242: iCol+dxa)); невозрастающие aCP → ValidationException; финальный aCP реальные файлы пишут за ccpText (PLC покрывает весь текстовый поток) — конец последней секции клампится к ccpText; pageWidth()/header()/footer() — геометрия последней секции (полоса набора для правила 7), continuousSectionEnds() — вычитание из подсчёта страниц (последняя секция не считается)
FontTable SttbfFfn (§2.9.147): индекс ftc → имя семейства в w:rFonts
SummaryInfo [MS-OLEPS §2.2] PropertySet-поток \x01SummaryInformation; offset'ы заголовка относительны начала PropertySet-потока (abs = Offset0 + offset); PIDSI_PAGECOUNT=0x0E
Headers Plcfhdd (§2.4.1): 6 разделителей + по 6 историй на секцию (even/odd/first × hdr/ftr); odd hdr/ftr каждой секции → своя часть headerN.xml/footerN.xml (нумерация независимая по типу) и headerReference/footerReference type="default" в её sectPr; пустая история [x,x) → части нет, docx4j наследует колонтитук предыдущей секции; guard-¶ отрезается; PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple (та же семантика, что FieldNormalizer в docx-пути)
OfficeArt [MS-ODRAW] PICF @ fcDggInfo/lcbDggInfo (Table-поток), delay-поток = WordDocument; DggContainer → BStoreContainer(0xF004)/BStoreContainerDelay(0xF007)/инлайн → FBSE → BLIP: 0xF01A EMF / 0xF01B WMF / 0xF01C PICT / 0xF01D JPEG (=0xF02A) / 0xF01E PNG / 0xF01F DIB; PNG/JPEG дословно, DIB → ImageIO → PNG, EMF/WMF/PICT → пропуск + warn (EMF-рендера в Java2D нет)
PrcData §2.9.210 PrcData в Data-потоке ([cbGrpprl:2][grpprl], капа cb 0x3FA2, поля next нет): resolve(data, grpprl) разворачивает grpprl абзаца, чьи свойства Word вынес за FKP-страницу PAPX, — одиночный Prl sprmPHugePapx (0x6646; в grpprl GrpPrlAndIstd — единственный Prl при istd=0, §2.6.2) и sprmPTableProps (0x646B — цепочка продолжается в указанном PrcData). Оба указателя разворачиваются на своей позиции без обрыва текущего массива, не-спец-спрмы сохраняются (union): spec §2.6.2 велит хвост за PTableProps игнорировать, но Word пишет в нём легаси-зеркало (в samples/ru-table-image.doc — единственный sprmTDefTable, Appendix A <9>), а sprmTInsert из PrcData конвертер не читает — замещение ломало бы сетку; спец-спрмов нет → тот же массив (по ссылке); любой брак (ptr за Data, cb вне [1, 0x3FA2], цикл A→B→A — бюджет 32 PrcData) → останов без исключения, снисходительно (образец Styles/Lists). Подключается единственной точкой — DocxBody.buildRange (покрывает тело, колонтитуки, TTP-ветку и обычные huge-PAPX абзацы). Регрессия — DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData
DocToDocx Оркестратор + вложенный DocxBody: текст → раны (CHPX+стилевой chpx-цепочка → rPr, прямой PAPX — после PrcData.resolve — +стилевая papx-цепочка (отступы через Grpprl.Indents, 80-варианты включительно; sprmPChgTabsPapx/sprmPChgTabs → w:tabs, у стилевого варианта радиус удаления из rgdxaClose) + sprmPIlfo/sprmPIlvl → pPr + w:numPr (между pageBreakBefore и tabs, CT_PPr §17.3.1.26; ilfo=0 перекрывает стилевой, ilvl=0x0C и неразрешённый numId → без numPr), base→derived→direct last-wins; флаги рана: vanish — мост фильтрует вывод рана (w:vanish в FO мёртв), caps/smallCaps — Character.toUpperCase в мосту (w:caps/w:smallCaps конвейер не читает, FOP без font-variant), rMarkIns/rMarkDel — ран оборачивается в w:ins/w:del+w:delText (шаблоны docx2fo рисуют правки — вид «Show Markup»), hpsPos → w:position (вендорный AUDIT-FIX → baseline-shift)), ¶ → <w:p>; TAB/0x0B → w:tab/w:br, 0x0E → w:br type="column" (конец колонки при sprmSCcolumns), 0x0C в ране → w:br type="page", 0x0C в конце абзаца — разрыв секции: sectPr соответствующей Sections.Section (матчинг по конечному CP) в pPr этого абзаца, внутри таблицы деградирует в w:br type="page"; body-level sectPr — последняя секция; w:type continuous из sprmSBkc; w:pgSz w:orient="landscape" со сменой w/h местами, w:pgNumType (w:start при restart, w:fmt только для числовых nfc — общий маппинг Lists.numFmt), w:cols (evenly → w:num+w:space, иначе per-column w:col; неравные/неполные ширины → деградация в одноколонную) — DocxBody.sectPrXml/appendPgNumType/appendCols; pPr: w:keepNext/w:keepLines перед w:pageBreakBefore (CT_PPr §17.3.1.26); 0x1E → U+2011, 0x1F → U+00AD, 0x02/0x03/0x04 (сноски) → пропуск; U+0001/U+0008 со sprmCPicLocation → DrawingML pic (общий путь с картинками и OLE-fallback; 0x08 — якорь плавающей картинки §2.9.267, переносится inline-приближением: PlcfSpa не читается, позиция/обтекание теряются); field-символы в основном тексте: инструкция скрыта, кэшированный результат после разделителя видим; табличный автомат: абзац с 0x07 без TTP закрывает ячейку, 0x07+sprmPFTtp — конец строки (Tables.parse по TAP → w:tbl/w:tr/w:tc, сам маркер не эмитится), sprmPFInTable открывает ячейку; без корректного TDefTable строка деградирует в плоские абзацы (прежнее поведение); сетка первой строки действует на всю таблицу как tblGrid, ширины/объединение ячеек каждой строки — из её собственного TDefTable (горизонтальное слияние → w:gridSpan)
DocxWriter Мульти-частный zip: [Content_Types].xml (hdr/ftr/numbering/png/jpg), _rels/.rels, word/document.xml (посекционные sectPr + headerReference; tblPr таблиц: tblW → jc (из sprmTJc) → tblInd → tblBorders), word/_rels/document.xml.rels, word/numbering.xml, word/headerN.xml/footerN.xml (по одной на непустую историю секции), `word/media/imageN.(png

Остаток моста (осознанный, вне контура): семантика рестартов списков не переносится (fNoRestart/ilvlRestartLim → w:lvlRestart — docx4j-Emulator применяет свой дефолт «рестарт на старшем уровне»), как и fLegal/isLgl, dxaIndentSav и LfoData.cp; sprmPIlvl=0x0C — абзац без numPr (не «в списке без номера»); AUTONUM-поля трактуются как обычные списки; отрицательный sprmPIlfo («сохранить отступы») — обычный numPr, отступы делает прямой w:ind абзаца; объединённые ячейки: вертикальное слияние (vertMerge) не переносится, горизонтальное — переносится собственной сеткой строки (TTP-абзац каждой строки несёт свой sprmTDefTable, §2.9.321 → w:gridSpan+суммарный w:tcW; регрессия — WordPdfConverterTest#docMergedTableRow_fullWidthNotSplit, юниты — DocToDocxFormattingTest#mergedRow_gridSpanAndWidth, #misalignedRow_fallsBackToColumnWidths), вложенные таблицы (sprmPFInnerTtp — разделитель ячейки/строки там ¶ 0x0D, не 0x07) и бордюры уровня ячейки (TC80/sprmTCellBorders) не переносятся — только сетка и строковые границы; строки, у которых сетка задана только sprmTInsert (в PrcData нет sprmTDefTable, а PAPX-зеркало отсутствует), деградируют в плоские абзацы (sprmTInsert конвертер не читает); DocFile.countPages (PapxIndex.countPageBreakBefore) цепочку PrcData не следует — свойства вне FKP в подсчёт страниц не попадают, 0x0C-разрывы считаются; сноски/концевые сноски/комментарии не рендерятся (метки ссылок пропускаются); плавающие объекты (якорь 0x08) — только inline-картинкой: позиция/плавание/обтекание (PlcfSpa) не переносятся; непринятые правки рендерятся как разметка (w:ins/w:del, вид «Show Markup»), эмуляция принятия правок не делается; скрытый текст вырезается мостом (конвейер w:vanish не читает), ВСЕ ПРОПИСНЫЕ/малые капители — апкейс текста (FOP без font-variant); подсветка sprmCHighlight 0x2A0C и затенения (sprmCShd 0xCA71/sprmPShd 0xC64D/sprmTSetShd 0xD62D) не переносятся — конвейер не читает ни highlight, ни shd, у fo:inline в FOP фона нет; границы абзацев (sprmPBfc/sprmPBcl + PlfBdx §2.9.8) не переносятся (нужен отдельный PLC-парсер); чётные и first-page варианты колонтитуков не переносятся (переносится только odd → type="default", FOP не различает чётность полос набора, titlePg не эмитится); разрыв секции в абзаце со sprmPFInTable деградирует в разрыв страницы (w:sectPr в w:pPr внутри w:tc невалиден); error-флаги errorOnCharts/errorOnSmartArt/errorOnOle на .doc не срабатывают — диаграммы/SmartArt/OLE в бинарном формате существуют только как BLIP-плейсхолдеры, мост выдаёт их картинками (задокументировано в @Operation); stale-cache.doc конвертируется (кэш PageCount=5, концепта lastRenderedPageBreak в .doc нет) — семантика отличается от docx-фикстуры, запинено тестом.

Нормализаторы (internal/DocxNormalizer)

Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame в тестах). Восемь rewrite-нормализаторов выставляют константу STEP (public static final DocxNormalizer); у OleObjectNormalizer STEP нет — он подключается лямбдой в WordPdfConverter.normalizers(). Правила 1–8 применяет internal/DocxRewritePipeline — один zip-проход: к каждой записи word/*.xml рерайты цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из word/document.xml извлекается полоса набора (TableIndentNormalizer.bandOf, −1 — полосы нет), и word/headerN.xml/footerN.xml дополнительно прогоняются через TableIndentNormalizer.rewritePart с этой полосой; неизменённые записи переносятся 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. 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»).

REST API (wordpdf-app, всё package-private кроме WordPdfApplication)

Единственный эндпоинт POST /api/v1/convert: multipart-поле file + факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолт каждого — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Проверка .docx/.doc-расширения — в ConvertController (ошибочный текст 400 — контракт с фронтом); ConversionService.safeBaseName — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены [\p{L}\p{N} ._-], пустое → document). Error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в @Operation.

Ситуация HTTP Класс
Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) 400 ValidationException (наследник ConversionException)
Error-флаг на диаграммы/SmartArt/OLE 422 DrawingRejectedException (core-DrawingFoundException, Kind {CHARTS, SMARTART, OLE})
Ошибка ядра/рендера 500 ConversionFailedException
Очередь переполнена 503 ConversionRejectedException
Дольше wordpdf.convert-timeout (2m) 504 ConversionTimeoutException
Превышен multipart-лимит 413 MaxUploadSizeExceededException
Неизвестный путь / метод / content-type 404 / 405 / 415 NoResourceFoundException / HttpRequestMethodNotSupportedException / HttpMediaTypeNotSupportedException
Битый error-флаг, нет части/параметра 400 MethodArgumentTypeMismatchException, MissingServletRequestPartException, MissingServletRequestParameterException

Тело ошибки — {"error": …}. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». ApiExceptionHandler не видит ошибок фильтров — 401 пишет сам ApiKeyFilter.

  • Ключ доступа: ApiKeyFilter сверяет заголовок X-API-Key (ApiKeyFilter.HEADER) со свойством wordpdf.api-key (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). Без ключа открыты OPEN_PREFIXES = /actuator/, /swagger-ui, /v3/api-docs — матч по пути без forwarded-contextPath (getRequestURI() минус getContextPath(); иначе под X-Forwarded-Prefix HEALTHCHECK получил бы 401). Пути с точечными сегментами (../%2e) открытыми не считаются никогда.
  • Очередь: конвертации сериализованы однопоточным ThreadPoolExecutor (ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts и не потокобезопасно. future.cancel(true) при таймауте не останавливает FOP мгновенно — осознанный компромисс.
  • Лимиты входа задаёт только конфигурация сервера: wordpdf.max-mb/wordpdf.max-pages (env WORDPDF_MAX_MB/WORDPDF_MAX_PAGES), @Value в ConvertController с дефолтом-SpEL из WordPdfSettings (5 МБ / 100); значение ≤ 0 → IllegalStateException на старте; параметрами запроса не переопределяются. Ключи в application.properties не объявлены — пустое значение затенит SpEL-дефолт.
  • SPA: вся сеть в wordpdf-web/src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), при 401 очищается, экран ApiKeyGate (UnauthorizedError — наследник ApiError, проверяется раньше); гейт показывается только когда probeApiKey() (GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на ${import.meta.env.BASE_URL}api/... (vite base из VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом /pdf-converter/). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает .docx,.doc (accept + текст зоны).

Chart/SmartArt-движок (internal/chart)

Нормативный источник любых правок — ECMA-376 (docs/standards/docx/: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD schema/strict//schema/transitional/; поведение Word — ms-oi29500.md, ms-odrawxml.md), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, PIE_DEPTH) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300, PADDING = 4.0, растр × DPI/72, размеры в пунктах, EMU→pt cx/12700.0). Потолок растра ChartRenderer.MAX_PIXELS = 16_777_216 (4096², 64 МБ ARGB): при превышении fitDpi uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); SmartArtRenderer использует тот же DPI/fitDpi. ChartSpec.parse (enum Type: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). c:autoTitleDeleted (§21.2.2.7, val опущен — default true) применяется только при отсутствии c:title (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии c:title и val=0 рисуется автозаголовок. Пустой/пробельный c:title (или val=0 без c:title) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе ChartSpec.AUTO_TITLE = "Название диаграммы"; несколько абзацев a:p склеиваются '\n' (жёсткий перенос в DrawMlText). Регрессии — ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName, #deletedTitleWithText_stillShown, #deletedTitleValOmitted_stillShown, #multiSeriesDoughnut_placeholderNotSeriesName, #multiParagraphTitle_joinedWithNewlines. Палитра accent1..6 темы; легенда по умолчанию снизу; overlay (§21.2.2.132) рисуется поверх области построения, место не резервирует.

Пейнтеры: CartesianPainter (2-D line/bar/area; c:grouping stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через ChartRenderer.stackedCumulative), PiePainter (PIE_DEPTH = 0.22, PIE_FIT = 0.865), Surface3dPainter (камера — регрессия cameraMatchesWordReference: DEPTH_RATIO = 0.705, HEIGHT_RATIO = 0.664, GUTTER_LEFT/RIGHT = 0.1485, GUTTER_TOP = 0.116, GUTTER_BOTTOM = 0.146, свет LIGHT_X/Y/Z = 0.83/0.48/0.28; c:rAngAx=true приоритетнее c:perspective (MS-OI29500 §2.1.1516(b)); c:wireframe §21.2.2.205 — только каркас), ScatterPainter (радиус пузыря sqrt при c:sizeRepresents="area" §21.2.2.128), RadarPainter (спицы от 12 часов), StockPainter (upDownBars обводятся контуром, дефолт чёрный 0.75pt), OfPiePainter (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), Surface2dPainter (контурная карта §21.2.2.204, marching squares, изолинии по c:bandFmts §21.2.2.13/.14), Cartesian3dPainter (bar3D/line3D/area3D §21.2.2.19/.101/.122, c:shape §21.2.3.44), SmartArtRenderer (кэш word/diagrams/drawing1.xml через relationship …/office/2007/relationships/diagramDrawing; формы — PresetGeometry из a:prstGeom, семь пресетов дословно из presetShapeDefinitions.xml; оператор ?: = «if x > 0 then y else z» (ISO/IEC 29500-1, не x != 0); углы в Arc2D — со знаком минус; текст — DrawMlText, шрифты через BundledFontMapper.bundledFamily; autofit только normAutofit §21.1.2.1.2/.3; dgm:prSet/@phldrT не рисуется).

Защитные лимиты против враждебного chart-XML: ChartSpec.MAX_POINTS = 100_000 (c:pt/@idx §21.2.2.150/.151, c:ptCount §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ IllegalArgumentException до предвыделения списка), ChartRenderer.MAX_TICKS = 1000 (шаг ≤ 0/NaN/слишком мелкий в axisBounds заменяется niceUnit 1/2/5·10ⁿ), DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000 (≈24″; при cx/cy вне капа объект оставляется как есть + warn, картинка не рендерится — регрессия hugeExtentChart_removedNotOom). Бросок перехватывает catch в DrawingPreRenderer.renderChart → штатная деградация «объект удалён + warn». Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), не getOwningRelationshipPart(); обход XML обязан раскрывать JAXBElement.

Combo (Word «Комбинированная», §21.2.2.145): несколько групп в одном c:plotArea (c:barChart + c:lineChart/c:areaChart), каждая со своими c:axId (§21.2.2.9). parse привязывает группы по id осей: Series.renderAs (семейство отрисовки), Series.grouping, Series.valAxis + ChartSpec.secondaryValAxis (обычно c:axPos="r"); spec.valAxis/catAxis — first-wins. CartesianPainter рисует семейства в порядке BAR→AREA→LINE, каждая серия масштабируется по своей оси, вторичная ось — линия справа + подписи справа.

Критические инварианты (нарушение = битый вывод, не исключение)

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter. Иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам → FOP падает на docx4j-baseline.
  • Единственный XSL-FO-стилист — вендорный wordpdf-core/src/main/resources/xslt/docx2fo.xslt (копия docx2fo.xslt из docx4j-export-fo 17.3.2 + AUDIT-FIX-патч w:rPr/w:position → baseline-shift, полупункты, Part 1 §17.3.2.24 — docx4j position игнорирует). Дрейф-гейт WordPdfConverterTest#vendoredXsltTracksJarCopy: вне AUDIT-FIX-региона вендорная копия обязана быть побайтно равна стилисту из jar'а (сравнение с возвратом патч-региона к исходному вызову createBlockForRPr) — при апгрейде docx4j перевендорить и перенести патч. setCustomXsltTemplates принимает предкомпилированный Templates (getTemplates кастит Object→Templates, поток кидает CCE).
  • slf4j-simple обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия noLoggingWarningInPdf). Приложение исключает его из зависимости ядра — логи ведёт logback.
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 (транзитив от docx4j-export-fo 17.3.2, в pom не пинится; пакеты org.apache.fop.*). w:renderers в docx4j 17.x содержит несколько w:renderer (по mime) — FopFallbackFonts берёт тот, у которого mime application/pdf, иначе первый со шрифтами. Оригинал docx2fo.xslt — в jar docx4j-export-fo, в конвейере используется вендорная копия (см. выше).
  • Порядок инициализации шрифтов: new BundledFontMapper() → BundledFonts.init() → restrictToBundled() — до load(). BundledFonts.init() идемпотентен и synchronized, распаковывает TTF во временный каталог wordpdf-fonts-* (deleteOnExit на файлы и на каталог). dropNonBundled() чистит глобальный реестр PhysicalFonts от всего, что вне бандла.
  • PhysicalFonts — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.
  • Страницы в валидаторе = 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-частей).
  • Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).
  • Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): w:jc="distribute" рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства text-align-last в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); w:suff="tab" и w:lvlJc игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 8, suff=nothing совпадает с docx4j — разделителя нет); абзац без w:line рендерится natural-высотой FOP 15.44pt@11pt, явный lineRule="auto" — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; «Word ≈13.9pt» из первичного аудита не воспроизводится: обе величины считаются по метрикам шрифта, артефакты исходного замера не сохранились → пункт закрыт без правок); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy kern-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (TextLayoutManager→Font.hasKerning) читает только legacy kern и такие пары отбрасывает; свойства kerning в форке нет, порог w:kern через FO не выражается. Word кернит только при явно заданном w:kern в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19; при отсутствии w:kern Office не кернит — MS-OI29500 §21.1.2.3.9a) — по умолчанию совпадает с нами, расходится только для документов с явно заданным w:kern. Починено веткой layout-class-c: левый padding ячейки (LayoutPostRenderer, шаг 4.25), w:tblInd при w:jc≠left (правило 7), w:suff="space" (правило 8).
  • Внимание: комментарии в WordPdfConverter/DocxOnOffNormalizer говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).

Шрифты (30 TTF + 3 лицензии, SIL OFL, wordpdf-core/src/main/resources/fonts/)

7 семейств × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в BundledFontMapper.ALIASES (ключи lowercase): Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; self-map всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный SYMBOL_FONT «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. DISPLAY_NAMES — обратный маппинг lowercase→отображаемое имя для documentFontName (пишет GlyphCoverageNormalizer в w:rFonts). BundledFontMapper.bundledFamily — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движком). Публичный API BundledFonts: families(), font/regular/bold/italic/boldItalic(family), FALLBACK_FAMILY. GlyphFont — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF напрямую из classpath fonts/<file> (не из temp-каталога BundledFonts), кэш по family/variant, of() возвращает null для неизвестного семейства; java.awt.Font из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ Публичный API: WordPdfConverter (convert(byte[],String[,ConvertOptions])), WordPdfValidator (checkInput/checkPageCount/validate — без зависимости от docx4j), ConversionException, ValidationException (наследник — «вход некорректен»), DrawingFoundException (enum Kind {CHARTS, SMARTART, OLE}), WordPdfSettings (MAX_INPUT_MB=5, MAX_PAGES=100, защитные MAX_DECOMPRESSED_MB=200/MAX_ZIP_ENTRIES=8192, ERROR_ON_*=false), ConvertOptions (record)
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы, self-map, DISPLAY_NAMES, bundledFamily), GlyphFont (глиф-движок fontbox)
…/wordpdf/internal/ 9 нормализаторов + DocxRewritePipeline (один zip-проход правил 1–8, 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 классов (см. секцию «Мост») — 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/ 17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только DrawingPreRenderer.run)
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/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 (10 классов): WordPdfApplication (единственный public), ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter, OpenApiConfig (@SecurityScheme X-API-Key) + 4 класса исключений
wordpdf-web/src/ SPA: api.ts (вся сеть), components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)
корневые Containerfile, compose.yml, compose.dev.yml, gateway/nginx.conf Образ бэкенда (multi-stage maven:3.9-eclipse-temurin-17 → eclipse-temurin:17-jre-alpine, non-root uid 10001, -XX:MaxRAMPercentage=70, HEALTHCHECK — busybox wget); compose app+web+gateway (mem_limit: 2g app, подсеть 10.113.0.0/24 gw 10.113.0.1, x-podman.name_separator_compat); прод-compose не в репо — его рендерит job deploy; в репо-compose.yml springdoc выключен env (SPRINGDOC_API_DOCS_ENABLED=false, SPRINGDOC_SWAGGER_UI_ENABLED=false), в compose.dev.yml springdoc-переменных нет вовсе — включён по умолчанию (не отключается). wordpdf-web/Containerfile — node:24-alpine → nginx:alpine, ARG VITE_BASE=/ (прод-CI печёт /pdf-converter/); репозиторный wordpdf-web/nginx.conf в образ не копируется (SPA одностраничная, без клиентского роутинга — SPA-fallback не нужен)
.env.example Шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_MB/WORDPDF_MAX_PAGES (пустое значение ломает binding long/int). Проду .env не нужен — ключ и лимиты подаёт job deploy из Gitea Secrets/Variables
.gitea/workflows/ Gitea Actions: pr.yml (PR checks), main.yml (тесты + coverage-сводка и комментарий в PR → images-app/images-web (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback)
GITEA-vars.md Инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений
prod-autotests/ Прод-автотесты API (pytest + requests, 31 проверка): конфигурация стенда только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR факультативны) — прод-хостов/ключей в коде нет
docs/standards/ Нормативная документация форматов Word, две категории: docx/ — OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD docx/schema/strict/ (21) + docx/schema/transitional/ (26), docx/validate-fixtures.py — XSD-валидация samples/*.docx (lxml, ставится отдельно); doc/ — бинарный .doc: md [MS-DOC] (ms-doc.md + ms-doc-full.md — тот же текст с HTML packet diagram'ами и таблицами sprm §2.6.1–2.6.3, где ms-doc.md даёт [TABLE]) + окружение [MS-CFB]/[MS-OSHARED]/[MS-ODRAW]/[MS-OLEPS]/[MS-OFFCRYPTO]/[MS-OVBA]/[MS-WMF]/[MS-EMF]; регенерация — README в каждой категории: docx/README.md, doc/README.md
develop/ (вне git, gitignored) Рабочие материалы и эталоны сравнения рендера — не фикстуры, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах

Development Commands

Бутстрап toolchain: sh bootstrap.sh (Windows: powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1) — ставит project-local mise в ./.mise/ (gitignored, в систему ничего не ставится) и инструменты из корневого mise.toml. Дальше — через ./mise.sh / .\mise.ps1 (Windows) либо eval "$(./.mise/bin/mise activate bash)".

./mise.sh run verify                      # = mvn clean verify: тесты + PMD + гейты JaCoCo (обязательный гейт перед push)
mvn clean verify                          # то же самое; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-app -am package           # исполняемый jar бэкенда (-am обязателен: app берёт test-jar core)
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
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf
./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-стенд: http://<LAN-IP хоста>:9011, без ключа, springdoc вкл; --force-recreate ОБЯЗАТЕЛЕН: без него podman-compose пересобирает образ, но контейнеры оставляет на старом (проверено: свежий image, а в app крутится jar прошлой сборки)
./mise.sh run prod-tests                 # прод-автотесты: pip install + pytest -q . в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx   # XSD-валидация фикстур (lxml)

# Перевендорить 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-патч (w:rPr/w:position → baseline-shift, образец — комментарий в самом файле)

Задачи mise: verify, app-package, app-run, web-install, web-build, web-lint, web-dev, prod-tests. Venv прод-автотестов prod-autotests/.venv mise создаёт сам ([env] в mise.toml).

«Запусти тестовый сервер» (термин пользователя) = полный dev-стенд, НЕ java -jar: podman-compose -f compose.dev.yml up -d --build --force-recreate — все контейнеры (app+web+gateway) с полной пересборкой образов. Обязательные свойства после запуска: фронт доступен без API-ключа (compose.dev.yml не задаёт WORDPDF_API_KEY → wordpdf.api-key пуст → ApiKeyFilter прозрачен) и с других ПК сети — вход http://<LAN-IP хоста>:9011 (hostname -I на хосте), не localhost. Проверить: podman-compose -f compose.dev.yml ps (контейнеры healthy) и curl -s -o /dev/null -w '%{http_code}' http://<LAN-IP>:9011/ = 200.

Пересоздать 10 фикстур (POI, test scope; charts-smartart.docx и ole-embedded.docx НЕ генерируются — созданы вручную, не перезаписывать; chart-types.docx — ChartTypesDocxGenerator):

mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
    ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples

Деплой. Прод — на пользовательском LAN-сервере (podman + podman-compose, docker-бинарников нет); координаты сервера и гейты успешности — вне репо: /home/pjandro/prod/java-word-pdf/DEPLOY.md (обязательно прочитать перед любым деплоем/перезапуском). Прод-хост не хранит ни конфигураций, ни секретов: job deploy в main.yml рендерит docker-compose.yml и nginx.conf в директорию деплоя (значения — из Variables, API-ключ — из Secret WORDPDF_API_KEY через окружение деплоя, на диск не пишется), затем login/pull/up -d --force-recreate app web/гейты healthy+image/recreate gateway. Наследие restart.sh и .env деплой удаляет; единственное состояние на проде — .rollback.env (image ID для отката). Перезадеплой — push в main или Run workflow (workflow_dispatch), ручных скриптов нет. Наружный вход — https://pjandro.ru/pdf-converter/.

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: BundledFontMapper (extends BestMatchingMapper), обёртка цветов DrawMlColor (instance, но не наследник docx4j) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единый контракт internal/DocxNormalizer + константа STEP; цепочка WordPdfConverter.normalizers() = DocxRewritePipeline.STEP (правила 1–8 одним zip-проходом) + лямбда OleObjectNormalizer; нечего менять → тот же массив; package-private хук static String rewrite(String xml) для юнит-тестов (возвращает null при отсутствии изменений; есть у 8 из 9 — у многочастного OleObjectNormalizer нет); у StrictOoxmlNormalizer есть также rewritePart(entryName, xml), у TableIndentNormalizer — rewritePart(name, xml, band) (per-part-логика, хуки пайплайна); правятся только части word/*.xml.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же.
  • Константы UPPER_SNAKE с числовыми эталонными значениями (PIE_DEPTH, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Классы в internal — public (иначе родительский пакет не вызвал бы), но публичные члены наружу только normalize/STEP/declare/DrawingPreRenderer.run/DependencyGuard.check (rewrite, карты — package-private); в wordpdf-app всё package-private кроме WordPdfApplication.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles, checkInput_bytesOverLimit, noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple, splitsRunForUncoveredGlyph); оба стиля разрешает PMD-паттерн junit5TestPattern (^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$).
  • PMD (pmd-ruleset.xml, execution pmd-check на verify, includeTests=true — тесты тоже сканируются): category/java/codestyle.xml минус 14 opinionated-правил (AtLeastOneConstructor, CallSuperInConstructor, CommentDefaultAccessModifier, ConfusingTernary, FieldDeclarationsShouldBeAtStartOfClass, LocalVariableCouldBeFinal, LongVariable, MethodArgumentCouldBeFinal, OnlyOneReturn, PrematureDeclaration, ShortMethodName, ShortVariable, UseExplicitTypes, UseUnderscoresInNumericLiterals); MethodNamingConventions с junit5TestPattern и TooManyStaticImports (максимум 12) исключены из категории и переопределены ниже по своим настройкам; XPath-правило LiteralFirstInEquals (строковый литерал слева в equals/equalsIgnoreCase), unused-правила из bestpractices.xml, ReturnEmptyCollectionRatherThanNull (errorprone, priority 1), AvoidLiteralsInIfCondition (errorprone, priority 3), EmptyCatchBlock (errorprone, priority 2), ForLoopCanBeForeach (bestpractices, priority 2). failurePriority не задан — на практике verify валит нарушения любой приоритетности.

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures + normalizers(options) (порядок цепочки).
  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j).
  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java — все дефолты ядра (MAX_INPUT_MB = 5, MAX_PAGES = 100, ERROR_ON_* = false); рантайм-конфигурации в ядре нет.
  • 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).
  • 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).
  • 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.
  • wordpdf-web/vite.local.config.ts — легаси-одноразовщик (прокси /api → :8091), в tsconfig.node.json не включён; кандидат на удаление, не тиражировать паттерн. Корневые javac.*.args — мусор пробной компиляции (gitignored), тоже кандидат на удаление.

Runtime & Tooling Preferences

  • Java 17 + Maven (обязательны; wrapper mvnw нет — только системный Maven); UTF-8. Только Maven — никаких Gradle/Ant. Java/Maven/Node/Python для локальной разработки ставит project-local mise (бинарь в .mise/, вне системы), версии пинятся в корневом mise.toml (java = temurin-17, maven = 3.9.16, node = 24, python = 3.15), ежедневный запуск — ./mise.sh / .\mise.ps1. Bootstrap качает mise 2026.10.19 → ./.mise/bin, затем mise trust → mise install → mise run web-install.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Зависимости Maven — через зеркало Nexus maven-central: локально ~/.m2/settings.xml (литеральный URL, файл вне репо), CI/Containerfile — .ci/maven-settings.xml + MAVEN_MIRROR_URL (Variable / build-arg).
  • Фронт: 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.
  • Локальная проверка одна: mvn clean verify (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD.
  • Исполняемый jar бэкенда проверять только java -jar (тесты идут по classpath и repackage-специфику не видят; BundledFontsTest#listedFilesCoverAllTtfInResources требует file:-протокол classpath — только surefire, не fat-jar).
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf, main/dev защищены (правила глобального AGENTS.md; локально только main).
  • Push всегда в конце задачи: git push (и следующий за ним PR) — завершающий шаг, только когда вся реализация готова и обязательные гейты пройдены (./mise.sh run verify). Промежуточные push запрещены; коммиты в ходе работы — по правилам глобального AGENTS.md.

CI/CD (Gitea Actions)

Два 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 нет — нода берётся с раннера).

.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).

Артефактов покрытия нет намеренно: upload-artifact@v4 Gitea не поддерживает, @v3 на этом стенде зависает. HTML-отчёт — локально target/site/jacoco/, web (кеш ~/.npm).

Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — Gitea Actions Variables (DEPLOY_HOST, DEPLOY_USER, DEPLOY_DIR, WORDPDF_BASE_URL, WORDPDF_MAX_PAGES, WORDPDF_MAX_MB, REGISTRY, PIP_INDEX_URL, MAVEN_MIRROR_URL), креды — Secrets (DEPLOY_SSH_KEY, DEPLOY_KNOWN_HOSTS, WORDPDF_API_KEY, REGISTRY_USER, REGISTRY_PASSWORD); workflow-файлы ссылаются на них только ${{ vars.* }}/${{ secrets.* }}. Смена лимитов = правка Variables, PR не нужен. Защита ветки main: required-контексты PR checks / java (pull_request), PR checks / web (pull_request) (deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).

Testing & QA

  • Гейт maven-pmd-plugin 3.28.0 на verify для обоих модулей, ruleset pmd-ruleset.xml, includeTests=true. Версия PMD-движка в pom не пинится (тянется плагином).
  • Гейт 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) и защитные ветви сканеров нормализаторов/валидатора.
  • 55 тестовых класса / 824 теста (core 49/781 — из них 17 классов / 210 тестов в internal/doc/, app 6/43: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). 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).
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper (пер-странично setStartPage/setEndPage), override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчик картинок (imageCount/distinctImageCount — SMask игнорируется). Негативные маркеры: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); в tableImage_tableAndImage — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
  • Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word (экспорт 300 dpi, числа зашиты в тесты), допуски assertRatio <0.06 (PiePainterTest, CartesianPainterTest) / <0.10 (Surface3dPainterTest, + assertRange ±6 pt для центров силуэта); пороги залитых px, перцентильные коридоры яркости, «серый» px — разброс каналов GRAY_MAX_SPREAD=25; исключение — структурная проверка чернил в GlyphFontTest. Эталонные файлы — develop/, вне git. Хелперы chart-тестов (render, countColor, assertRatio, paint) продублированы по классам — общего test-util нет.
  • GlyphFont (fontbox): метрики пиксельно-метрически эквивалентны AWT (ascent/descent/leading/advance совпадают до 4-го знака, кернинг-дрейф 0.0000 — DejaVu Sans, Carlito). Приёмочный стенд без-fontconfig: контейнер без libfontconfig.so.1* и /etc/fonts, mvn verify + java -jar (до перехода на GlyphFont там падали GlyphCoverageNormalizerTest 12 / CartesianPainterTest 3 / PiePainterTest 2 / chart-тесты WordPdfConverterTest 4, chart-рендер молча деградировал). GlyphFontTest написан без единого java.awt.Font — обязан проходить на хосте без fontconfig.
  • Фикстуры — закоммиченные samples/*.docx + samples/*.doc (13 + 12; в тестах не генерировать; .docx все ECMA-conformant по docs/standards/docx/validate-fixtures.py — фикстура невалидна, правится фикстура, не код; .doc — эталоны заказчика, конвертируются мостом): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[]; in-memory .doc — POIFS (POIFSFileSystem) вокруг крафтовых WordDocument/1Table/Data (DocToDocxFormattingTest). Ключевые: too-many-pages (150 явных разрывов → 151; .doc-пара — кэш PageCount=150 → 400 «не менее 151»), stale-cache (docx: кэш <Pages>1</Pages> + 110 lastRenderedPageBreak → 400; doc: кэш 5 → конвертируется — семантика запинена), charts-smartart (4 растра; SmartArt-одиночка = ровно 2 Image XObject; .doc-пара — 3 BLIP-fallback → 3 картинки), ole-embedded (осиротевший bin с ложным Default bin→footer+xml + настоящий w:object с честным Override → oleObject и VML-плейсхолдером media/fallback.png — ручная, генератором не перезаписывать; .doc-пара — OLE-fallback BLIP → 1 картинка), chart-types (14 графиков: 9 типов + ofPie-pie + lineChart stacked + c:wireframe + combo barChart+lineChart на вторичной c:valAx pos="r"; пересоздание — ChartTypesDocxGenerator; .doc-аналога нет), doc-formats.doc (2 страницы — лимит страниц на .doc-пути).
  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame) и неприкосновенность частей вне word/*.xml ([Content_Types].xml). Тесты бьют и в package-private API (GlyphCoverageNormalizer.split(text, family), ChartSpec.readTitle). Исключение — OleObjectNormalizerTest: многочастный нормализатор без rewrite-хука, тесты только через normalize на in-memory zip.
  • Юниты моста (internal/doc/): CfbReaderTest строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); SummaryInfoTest — крафтовый PropertySetStream (пинит относительность offset от начала PropertySet, реальные фикстуры её не различают); PieceTableTest/ChpxIndexTest/PapxIndexTest (в т.ч. istdFor: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → дефолтные свойства при сохранённой границе)/SectionsTest/FibHeaderTest (пара fcStshf)/GrpprlTest (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (scan_pChgTabsSentinel_lengthByFormula))/FontTableTest/HeadersTest/OfficeArtTest/PrcDataTest — byte[]-конструкции in memory (PrcDataTest: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); StylesTest — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; TablesTest — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; ListsTest — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → %{n+1} и литеральный % → %%, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→w:suff, grpprl уровня → w:ind/w:rFonts, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); DocToDocxFormattingTest — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (styleTabsChg_reachesFooterPart/styleTabsChgDel_removesStop: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (footerTable_jcCenterEmitted: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: listParagraphs_getNumPrAndNumberingPart (sprmPIlfo/sprmPIlvl в PAPX → w:numPr + word/numbering.xml c w:num/Override/rels), listCancelledByDirectZero_noNumPr (ilfo стиля, перекрытый прямым 0), ilvlSkipValue_noNumPr (ilvl=0x0C), missingListTables_degradeToPlain (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: assertCyrillicAndStyles/assertPageNumbers/assertTableImage/assertOleObjectsRemoved/assertDrawingsBecomeImages/assertTooManyPages/assertExoticGlyphs вызываются с ru-plain.doc/page-numbers.doc/ru-table-image.doc/ole-embedded.doc/charts-smartart.doc/too-many-pages.doc/exotic-glyphs.doc (тесты-пары называются по docx-имени, внутри зовут оба формата); WordPdfValidatorTest#checkPageCountDoc_* + ConvertControllerTest (.doc upload, nonDocxFilename_rejected).
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); четыре контекста — ConvertControllerTest (пустой ключ), ApiKeyFilterTest (properties = "wordpdf.api-key=…"), ConvertLimitsTest (@TestPropertySource max-mb/max-pages), ConversionTimeoutTest (@TestPropertySource convert-timeout=1ms) — четыре разных набора свойств = четыре кэшированных контекста (отдельные классы, не @Nested: @Nested + @TestPropertySource не даёт отдельного контекста); ConversionServiceTest/ApiExceptionHandlerTest — без Spring-контекста (прямые юниты).
  • Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): StrictOoxmlNormalizerTest↔strictOoxml_convertsNotRejected (+pageCount_strictBreaksCountedLightweight; юниты indCoexistLeftStartUntouched/tcMarCoexistKept/tcBordersElementsKeptTransitional/jcStartRenamedTransitional/tabStartRenamedTransitional/transitionalCoexistReturnsOriginalArray), DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont, SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash, FieldNormalizerTest↔pageNumbers_recomputedNotCached, InvisibleCharNormalizerTest↔invisibleChars_noEmptyLines, GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash, OleObjectNormalizerTest↔oleObjects_removedAndConverted/drawingErrors_errorFlagRejectsOle (+app errorFlagOle_rejected/oleObjects_removedByDefault; юниты objectWithImagedata_placeholderKept/objectWithoutImage_removed/objectWithDrawing_reusedVerbatim/controlBlockRemoved/sizeFromDxaOrig/styleUnits_allConvertToEmu/objectWithoutBin_stillRewritten/externalOleLinkRelRemoved), WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender (+checkPageCount_limitBoundary 99/100/101, cachedPagesUnreadableFallsBackToZero, pageCount_breaksInsideTablesAreCounted, pageCount_continuousSectionsNotCountedLightweight, validate_notAZip/validate_plainZipRejected/validate_xlsxRenamedRejected/validate_zipBombRejected/validate_tooManyEntriesRejected), BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, PresetGeometryTest↔chartsSmartArt_drawingsBecomeImages (tableMatchesEcmaXml), chart-пейнтеры↔chartTypes_allTypesRenderAsImages, ChartSpecTest↔автозаголовки/комбо/DoS (hugePointIndex_rejectedNotOom, hugePtCount_rejectedNotOom, hugeCategoryIndex_rejectedNotOom, nonFiniteScalingBounds_dropped, overlayLegend_keepsPositionAndFlag, emptyTitleSingleSeriesBar_usesSeriesName, deletedTitleWithText_stillShown, deletedTitleValOmitted_stillShown, multiSeriesDoughnut_placeholderNotSeriesName, multiParagraphTitle_joinedWithNewlines), Surface3dPainterTest↔axisBounds_tinyMajorUnit_fallsBackToNiceUnit/axisBounds_zeroMajorUnit_fallsBackToNiceUnit, ChartRendererTest↔axisBounds_explicitHugeRange_reunitsToMaxTicks/axisBounds_infiniteSpan_fallsBackToData/stackedCumulative_*/stackedRange_coversNegativeSums/overlayLegend_drawnOverPlot/wireframeSurfaceLegend_hollowMarkers, DrawMlTextTest↔hugeWord_wrapsLinearly/fallbackFamilyAliasedToBundle/lineSpacingPct_compactsLines, DrawMlColorTest↔invalidSrgbHexFallsBackToOfficeDefault, SmartArtRendererTest↔normAutofitShrinksToFit/missingAutofitKeepsDeclaredSize/emptyTxBody_noPlaceholderInk, CartesianPainterTest↔stackedLine_seriesStackCumulatively/percentStackedLine_topSeriesFlatAtHundred/areaFill_closesToBaseline/combo_barsAndLineOnSecondary_bothDrawn, GlyphCoverageNormalizerTest↔multipleTextNodes_runLeftUntouched/nestedRunInTextBox_innerSplit, SymbolFontNormalizerTest↔nestedRunInTextBox_innerNormalized, WordPdfConverterTest↔noLoggingWarningInPdf/pdfTitle_comesFromParameter/hostileChartAxis_convertsNotHangs/hugeExtentChart_removedNotOom/chartWithoutExtent_errorFlagRejects/jcEndTransitional_rightAligned/rPrPosition_raisesBaseline/vendoredXsltTracksJarCopy (аудит раскладки ECMA-376), LayoutPostRendererTest↔tableCellPadding_textInsetLikeWord (+lineRuleAuto_wordSingleLinePitch пинит метрический шаг «single» от псевдофиксов, carlitoAutoBlock_untouched), TableIndentNormalizerTest↔tableIndentCentered_shiftedLikeWord (+rewritePart*↔headerTableIndent_centeredInHeader, +jcWithoutIndent_folded/rightWithoutIndent_folded/zeroIndent_folded/cellSpacingWithoutIndent_returnsNull↔tableCenteredNoIndent_shiftedLikeWord), NumberingSuffixNormalizerTest↔suffSpace_labelGetsSpace, 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 продублирован в обоих тестовых классах). 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.
  • UI-тестов нет; гейт SPA — npm run build (tsc -b) + npm run lint (oxlint, .oxlintrc.json: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 31 проверка — 27 под маркером needs_key (SKIP без ключа; включая .doc-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, mise exec -- python -m pytest -q . из prod-autotests/) гоняются CI после deploy против живого прода.