Files
java-word-pdf/AGENTS.md
T
Pjandro 8cd6079170
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 1m29s
Аудит раскладки по ECMA-376: jc start/end ренейм всегда, вендорный docx2fo.xslt с патчем w:position
- StrictOoxmlNormalizer: w:jc val=start/end переименовывается и в
  transitional (docx4j Justification.setXslFO дропает END без
  fo:text-align — jc=end рендерился по левому краю; Part 4 §14.11.2)
- вендорный xslt/docx2fo.xslt = копия docx4j-export-fo + AUDIT-FIX
  (w:rPr/w:position -> baseline-shift, §17.3.2.24); WordPdfConverter
  инжектит предкомпилированный Templates (шаг 4.5)
- дрейф-гейт vendoredXsltTracksJarCopy (SHA-256 стилиста из jar'а)
- регрессии jcEndTransitional_rightAligned, rPrPosition_raisesBaseline
- AGENTS.md: шаг 4.5, инвариант стилиста, ограничения из аудита
  (distribute/suff/lvlJc/tblInd/auto-line-height/kern)
2026-10-27 01:57:59 +00:00

64 KiB
Raw Blame History

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–6, см. ниже) + условная OLE-вычистка (правило 7)
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.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–6 применяет internal/DocxRewritePipeline — один zip-проход: к каждой записи word/*.xml рерайты цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); неизменённые записи переносятся 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 4 §14.11.2: left≡start, right≡end, 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).
  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. 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-расширения — в 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 (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-объекты», дефолт — все выключены).

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=true (в т.ч. при опущенном c:val — default true) скрывает заголовок целиком, включая явный c:tx (§21.2.2.7). Пустой c:title + autoTitleDeleted="0" — автозаголовок Word: круговая (PIE/PIE3D/DOUGHNUT/OF_PIE) с одним рядом → имя ряда, иначе ChartSpec.AUTO_TITLE = "Название диаграммы"; несколько абзацев a:p склеиваются '\n' (жёсткий перенос в DrawMlText). Регрессии — ChartSpecTest#deletedTitleWithText_notShown, #deletedTitleValOmitted_notShown, #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 4 §17.3.2.24 — docx4j position игнорирует). Дрейф-гейт WordPdfConverterTest#vendoredXsltTracksJarCopy (SHA-256 стилиста из jar'а): при апгрейде 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 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): w:jc="distribute" рендерится как left (XSLT-обходки невозможны: FOP не джаститифицирует истинно последнюю строку блока, text-align-last работает только перед форсированным разрывом); w:suff (nothing/space) и w:lvlJc игнорируются (numbering-лейбл всегда через hanging-tab); w:tblInd при w:jc≠left игнорируется (буквально по §17.4.50; Word не игнорирует — MS-OI29500 §2.1.155); высота строки lineRule="auto" калибрована docx4j на Word-single (~13.9pt@11pt), не на natural-высоту FOP (15.44pt); кернинг применяется без порога w:kern.
  • Внимание: комментарии в 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/ 7 нормализаторов + DocxRewritePipeline (один zip-проход правил 1–6, raw-копия неизменённых записей) + интерфейс DocxNormalizer + FopFallbackFonts + DependencyGuard (проверка commons-compress, шаг 0). Классы public (иначе родительский пакет не вызвал бы), публичные члены наружу только normalize/STEP/declare/DependencyGuard.check; 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)

Задачи 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–6 одним zip-проходом) + лямбда OleObjectNormalizer; нечего менять → тот же массив; package-private хук static String rewrite(String xml) для юнит-тестов (возвращает null при отсутствии изменений; есть у 6 из 7 — у многочастного 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, 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).
  • 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.
  • Фронт: 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-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) и защитные ветви сканеров нормализаторов/валидатора.
  • 35 тестовых классов / 538 @Test (core 29/496, 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-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 (13; в тестах не генерировать; все ECMA-conformant по docs/standards/validate-fixtures.py — фикстура невалидна, правится фикстура, не код): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[]. Ключевые: too-many-pages (150 явных разрывов → 151), stale-cache (кэш <Pages>1</Pages> + 110 lastRenderedPageBreak), 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:valAx pos="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 (+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, deletedTitleWithText_notShown, deletedTitleValOmitted_notShown, 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). 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 против живого прода.