- readTitle: пустой/пробельный c:title (или val=0 без c:title) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда любого типа графика, иначе плейсхолдер; раньше имя ряда — только у круговых - autoTitleDeleted (§21.2.2.7) применяется только при отсутствии c:title (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге - регрессии ChartSpecTest: emptyTitleSingleSeriesBar_usesSeriesName, deletedTitleWithText_stillShown, deletedTitleValOmitted_stillShown, noTitleElement_*; AGENTS.md приведён в соответствие
69 KiB
Repository Guidelines
Project Overview
Конвертер .docx → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). 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):
| # | Шаг | Что делает |
|---|---|---|
| 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(docxBytes, options) (размер → zip-подпись PK\x03\x04 → контейнер → страницы). Тот же метод — вход приложения.
Нормализаторы (internal/DocxNormalizer)
Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame в тестах). Каждый выставляет константу STEP (public static final DocxNormalizer). Правила 1–8 применяет internal/DocxRewritePipeline — один zip-проход: к каждой записи word/*.xml рерайты цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. OleObjectNormalizer — второй условный проход (меняет части, а не XML). Индивидуальные normalize() восьми нормализаторов сохранены (контракт юнит-тестов), но WordPdfConverter их не вызывает — его normalizers(options) = DocxRewritePipeline.STEP + лямбда OLE. Порядок правил значим:
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правятся всегда (docx4jJustification.setXslFOзнает только left/center/right/both, для ENDfo: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:left/w:right(дубль атрибута ломает well-formedness — регрессииindCoexistLeftStartUntouched,indCoexistForms_convertsNotRejected); элементыw:start/w:endв strict-части переименовываются глобально, в transitional — только внутриw:tcMar/w:tblCellMarбез одноимённого соседа (maxOccurs=1на left). Ничего не поменялось →rewriteвернулnull→ исходный массив (StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray).DocxOnOffNormalizer—w:val="off"/"on"→"false"/"true"; якорь по тегу, правится только атрибутw:val, текст между тегами не трогается.SymbolFontNormalizer— PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает<w:sym>, правитw:lvlв numbering.xml; 5 карт по 256 слотов (таблицаSymbolMapperиз docx4j 17.x).FieldNormalizer—fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple(кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.InvisibleCharNormalizer— вырезает изw:tU+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 не трогает.GlyphCoverageNormalizer— режет раны по покрытию глифов и пишет семейство вw:rFonts, иначе FOP рисует «#». Покрытие —GlyphFont(fontbox, cmap) + BitSet-кэш, не docx4jGlyphCheck(плодит INFO-лог;java.awt.Fontтребовал fontconfig на хосте). Для serif-ран fallback ищется сначала вSERIF_FAMILIES(dejavu serif,tinos,caladea), затем в sans.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): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right; дефолты 11906/1440 — измеренное поведение docx4j, не ECMA-1800), T — Σ gridCol; пропускает несколько body-levelsectPr, отсутствие tblInd,tblW pct, нецелые gridCol; трогает толькоword/document.xml. Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord.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.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-часть (размер изstylev:shape, иначеw:dxaOrig/w:dyaOrig×635), блоки сw:controlи без плейсхолдера удаляются. OLE-бинарники никогда не читаются. ПриerrorOnOle=trueвместо вычистки —DrawingFoundException(OLE). Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPEchunkType 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-расширения — в ConvertController; ConversionService.safeBaseName — единый источник имени для файла, заголовка ответа и PDF-title (разрешены [\p{L}\p{N} ._-], пустое → document).
| Ситуация | HTTP | Класс |
|---|---|---|
| Некорректный вход (размер, zip, контейнер, страницы) | 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(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты). Без ключа открытыOPEN_PREFIXES=/actuator/,/swagger-ui,/v3/api-docs— матч по пути без forwarded-contextPath (getRequestURI()минусgetContextPath(); иначе подX-Forwarded-PrefixHEALTHCHECK получил бы 401). Пути с точечными сегментами (../%2e) открытыми не считаются никогда. - Очередь: конвертации сериализованы однопоточным
ThreadPoolExecutor(ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестрPhysicalFontsи не потокобезопасно.future.cancel(true)при таймауте не останавливает FOP мгновенно — осознанный компромисс. - Лимиты входа задаёт только конфигурация сервера:
wordpdf.max-mb/wordpdf.max-pages(envWORDPDF_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/...(vitebaseизVITE_BASE, дефолт/) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом/pdf-converter/). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены).
Chart/SmartArt-движок (internal/chart)
Нормативный источник любых правок — ECMA-376 (docs/standards/: графики §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-fo17.3.2, в pom не пинится; пакетыorg.apache.fop.*).w:renderersв docx4j 17.x содержит несколькоw:renderer(по mime) —FopFallbackFontsберёт тот, у которого mimeapplication/pdf, иначе первый со шрифтами. Оригиналdocx2fo.xslt— в jardocx4j-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(truthyval: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, а legacykern-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (TextLayoutManager→Font.hasKerning) читает только legacykernи такие пары отбрасывает; свойстваkerningв форке нет, порогw:kernчерез FO не выражается. Word кернит только при явно заданномw:kernв иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19; при отсутствииw:kernOffice не кернит — 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/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/ |
13 закоммиченных .docx-фикстур (единственные .docx-фикстуры), все проходят docs/standards/validate-fixtures.py |
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. 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, 21 проверка): конфигурация стенда только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR факультативны) — прод-хостов/ключей в коде нет |
docs/standards/ |
Нормативная документация OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD schema/strict/ (21) + schema/transitional/ (26); validate-fixtures.py — XSD-валидация samples/*.docx (lxml, ставится отдельно); регенерация — docs/standards/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 # dev-стенд: http://<LAN-IP хоста>:9011, без ключа, springdoc вкл
./mise.sh run prod-tests # прод-автотесты: pip install + pytest -q . в prod-autotests/
python3 docs/standards/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.
Пересоздать 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)(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, executionpmd-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 МБ на диск, не в память; в тон gatewayclient_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с явной executionrepackage(в 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-pluginexecutiontest-jar(публикует фикстуры для app); JaCoCo executioncheckпереопределён (LINE 0.90 + BRANCH 0.85).- Корневой
pom.xml— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.2, commons-compress1.28.0, slf4j2.0.20, JUnit6.1.3, PDFBox/fontbox3.0.8(fontbox— compile в core: глиф-движокGlyphFont;pdfbox— test в обоих модулях; commons-logging исключён, мост —jcl-over-slf4j), POI5.5.1(test), Spring Boot4.1.1(BOM-import), springdoc3.1.1; pluginManagement: compiler3.16.0, surefire3.6.0с-Djava.awt.headless=true, jar3.5.1, PMD3.28.0, JaCoCo0.8.15; пустой дефолт<argLine>(для-Djacoco.skip=true). pmd-ruleset.xml— ruleset PMD (см. Code Conventions).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 качает mise2026.10.19→./.mise/bin, затемmise trust→mise install→mise run web-install. - Версии зависимостей — только в корневом
pom.xml(properties + dependencyManagement); новые зависимости — latest stable. - Фронт: 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).
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 clean verify) → 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).
.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>; 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; сохранение .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), креды — 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-plugin3.28.0 наverifyдля обоих модулей, rulesetpmd-ruleset.xml,includeTests=true. Версия PMD-движка в pom не пинится (тянется плагином). - Гейт JaCoCo
0.8.15:jacoco:check(правило BUNDLE, LINE COVEREDRATIO0.90— обоих модулей; вwordpdf-core/pom.xmlexecutioncheckпереопределён и добавляет BRANCH COVEREDRATIO0.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) и защитные ветви сканеров нормализаторов/валидатора. - 38 тестовых классов / 579
@Test(core 32/537, app 6/42: ConvertController 22 + 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-Hamcrestorg.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), overrideprocessTextPositionдля шрифта конкретного символа (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 там падалиGlyphCoverageNormalizerTest12 /CartesianPainterTest3 /PiePainterTest2 / chart-тестыWordPdfConverterTest4, chart-рендер молча деградировал).GlyphFontTestнаписан без единогоjava.awt.Font— обязан проходить на хосте без fontconfig.- Фикстуры — закоммиченные
samples/*.docx(13; в тестах не генерировать; все ECMA-conformant поdocs/standards/validate-fixtures.py— фикстура невалидна, правится фикстура, не код): core грузит classpath-ресурсом →byte[], PDF для PDFBox — временный файл; app читает/samples/…из test-jar core (classifiertests) →mvn -pl wordpdf-appбез-amне соберётся. In-memory docx —ZipOutputStreamиз литеральных XML или POI вbyte[]. Ключевые:too-many-pages(150 явных разрывов → 151),stale-cache(кэш<Pages>1</Pages>+ 110lastRenderedPageBreak),charts-smartart(4 растра; SmartArt-одиночка = ровно 2 Image XObject),ole-embedded(осиротевший bin с ложнымDefault bin→footer+xml+ настоящийw:objectс честнымOverride → oleObjectи VML-плейсхолдеромmedia/fallback.png— ручная, генератором не перезаписывать),chart-types(14 графиков: 9 типов + ofPie-pie + lineChart stacked +c:wireframe+ combo barChart+lineChart на вторичнойc:valAxpos="r"; пересоздание —ChartTypesDocxGenerator). - Юниты нормализаторов работают строками (
rewrite) + zip'ами изZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame) и неприкосновенность частей внеword/*.xml([Content_Types].xml). Тесты бьют и в package-private API (GlyphCoverageNormalizer.split(text, family),ChartSpec.readTitle). Исключение —OleObjectNormalizerTest: многочастный нормализатор безrewrite-хука, тесты только черезnormalizeна in-memory zip. - App-тесты:
@SpringBootTest+@AutoConfigureMockMvc(Boot 4:org.springframework.boot.webmvc.test.autoconfigure); три контекста —ConvertControllerTest(пустой ключ),ApiKeyFilterTest(properties = "wordpdf.api-key=…"),ConvertLimitsTest/ConversionTimeoutTest(@TestPropertySource— отдельные классы, не@Nested:@Nested+@TestPropertySourceне даёт отдельного контекста). - Регрессивные пары (фикс = нормализатор/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(+apperrorFlagOle_rejected/oleObjects_removedByDefault; юнитыobjectWithImagedata_placeholderKept/objectWithoutImage_removed/objectWithDrawing_reusedVerbatim/controlBlockRemoved/sizeFromDxaOrig/styleUnits_allConvertToEmu/objectWithoutBin_stillRewritten/externalOleLinkRelRemoved),WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender(+checkPageCount_limitBoundary99/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,NumberingSuffixNormalizerTest↔suffSpace_labelGetsSpace. 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, 21 проверка — 17 под маркеромneeds_key(SKIP без ключа), 4 открытых: health/SPA-root/swagger/spec; env-конфиг,mise exec -- python -m pytest -q .изprod-autotests/) гоняются CI после deploy против живого прода.