Files
java-word-pdf/AGENTS.md
T
Pjandro c7af4185cc
PR checks / web (pull_request) Successful in 32s
PR checks / java (pull_request) Successful in 1m38s
Main: tests, deploy, autotests / web (push) Successful in 31s
Main: tests, deploy, autotests / images-web (push) Successful in 32s
Main: tests, deploy, autotests / java (push) Successful in 1m27s
Main: tests, deploy, autotests / images-app (push) Successful in 44s
Main: tests, deploy, autotests / deploy (push) Successful in 1m29s
Main: tests, deploy, autotests / autotests (push) Successful in 40s
Main: tests, deploy, autotests / rollback (push) Has been skipped
chart: lineChart c:grouping stacked/percentStacked (§21.2.2.76) — ряд на накопленной сумме
- ChartSpec: чтение c:grouping у CTLineChart (line3D осознанно игнорирует)
- CartesianPainter (LINE): кумулятивный диапазон оси и ломаные по stackedCumulative; percentStacked — нормировка к 100
- хелперы isStacked/stackedCumulative/stackedRange переехали из Cartesian3dPainter в ChartRenderer (общие для 2-D и 3-D)
- фикстура chart-types.docx: +10-я диаграмма «График с накоплением»; тест переименован в chartTypes_allTypesRenderAsImages (чинит 14 stale-javadoc-ссылок), assertEquals(10, …)
- юниты ChartSpecTest/ChartRendererTest + пиксельные CartesianPainterTest (инверсия порядка линий stacked vs standard; плоский верх 100% в percentStacked)
2026-10-25 15:20:57 +00:00

62 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: wordpdf-core (библиотека), wordpdf-app (Spring Boot 4.1.1 REST API); wordpdf-web — React SPA в nginx-контейнере (отдельный деп, вне Maven). Локальный гейт перед git push — mvn clean verify (CI не блокирует push, но Gitea Actions PR checks — required-контексты защиты main; SPA гейтуется npm run build + npm run lint). Вход стека — gateway-контейнер nginx (:9010 prod / :9011 dev), НЕ 8080. README устарел (порты/топология, «413 6 МБ» — фактически 100 МБ, нет API-ключа, лимиты подаёт как константы — они конфигурируемы); авторитетен этот файл.

Architecture & Data Flow

Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) (порядок фиксирован, менять местами нельзя)

Наружу WordPdfValidator.validate(docxBytes, options) (размер → zip-подпись PK\x03\x04 → контейнер (.docx-манифест + zip-бомба) → страницы) вызывается до приватного convertToStream; внутри convertToStream:

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестр PhysicalFonts; ключ реестра — имя из name-таблицы TTF, addPhysicalFont(URI) не перезаписывает занятый → init() вызывает dropNonBundled() до регистрации и load() (иначе системный Calibri ломает em-dash-fallback).
  2. Нормализация байтов docx до JAXB-загрузки — цепочка List<DocxNormalizer> normalizers(options) (@FunctionalInterface internal/DocxNormalizer: byte[] normalize(byte[]) throws IOException, контракт — нечего менять → тот же массив; каждый нормализатор выставляет константу STEP, порядок значим): 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), значения start/end у w:jc/w:tab; в mc-preprocessor.xslt docx4j ветка % закомментирована, start/end не маппятся; namespaces и pt-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → DocxOnOffNormalizer (w:val="off"/"on" → false/true) → SymbolFontNormalizer (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы <w:sym>, правит w:lvl в numbering.xml; 5 карт по 256 слотов, таблица SymbolMapper сгенерирована из docx4j 17.x) → FieldNormalizer (fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, вложенные/битые поля пропускает) → InvisibleCharNormalizer (вырезание из w:t U+0085/U+2028/U+2029/U+2060/U+FEFF/bidi-меток — FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы; U+00A0/U+00AD/U+200B–U+200D НЕ трогает) → GlyphCoverageNormalizer (режет ран по покрытию глифов, пишет семейство в w:rFonts, иначе FOP рисует «#»; покрытие — GlyphFont (fontbox, cmap) + BitSet-кэш, НЕ docx4j GlyphCheck — тот плодит INFO-лог, java.awt.Font требовал fontconfig на хосте; для serif-ран fallback ищется сначала в SERIF_FAMILIES (DejaVu Serif/Tinos/Caladea), затем в sans) → OleObjectNormalizer (принимает флаг errorOnOle: OLE-bin-части — детекция по [Content_Types].xml: тип …oleObject ИЛИ ложный +xml-тип у .bin (XML в bin не бывает; printerSettings не трогается) — удаляются вместе с rels-ссылками (TargetMode=External не трогается), элементами <w:object> из word/*.xml и Override удалённых частей; при 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-хука нет) → WordprocessingMLPackage.load.
  3. WordPdfValidator.checkPageCount(docxBytes, maxPages) — до рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg, options) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет — свой Java2D-движок internal/chart/* рендерит в PNG 300 dpi и подменяет на pic:pic; объекты конвертируются всегда, отказ только по error-флагу ConvertOptions — DrawingFoundException; упавший рендер — объект удаляется из docx (gd.getAny().clear()) + warn, деградация не падение).
  5. new FOSettings(pkg) + FopFallbackFonts.declare (декларирует все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP/FOUserAgent (непустой title → заголовок PDF) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  6. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

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

  • Единственный эндпоинт POST /api/v1/convert (multipart-поле file, факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle — дефолт каждого WordPdfSettings.ERROR_ON_*; диаграммы/SmartArt конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются) → application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Проверка .docx-расширения — в ConvertController; safeBaseName в ConversionService — единый источник имени для файла, заголовка ответа и PDF-title (разрешены [\p{L}\p{N} ._-], пустое → document).
  • Конвертации сериализованы однопоточным ThreadPoolExecutor (ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts. future.cancel(true) при таймауте не останавливает FOP мгновенно — осознанный компромисс.
  • Ошибки (ApiExceptionHandler, тело {"error": …}): ValidationException → 400; DrawingRejectedException (core-DrawingFoundException от error-флагов — Kind {CHARTS, SMARTART, OLE}, конвертируется в ConversionService.doConvert) → 422 (текст — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты»); ConversionFailedException → 500; ConversionRejectedException → 503; ConversionTimeoutException (wordpdf.convert-timeout, 2m) → 504; MaxUploadSizeExceededException → 413; MissingServletRequestPartException/MissingServletRequestParameterException/MethodArgumentTypeMismatchException (битый error-флаг) → 400; NoResourceFoundException (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). ValidationException — тип ядра ru.pjandro.wordpdf.ValidationException extends ConversionException (публичный), валидатор бросает его сам, app-дубликата нет; четыре app-исключения (ConversionFailed/Rejected/Timeout/DrawingRejected) — package-private, несут семантику 500/503/504/422. Граница: сломанный контейнер (не zip / голый zip без манифеста wordprocessingml / zip-бомба / размер / страницы) → 400, валидный .docx-контейнер с мусором внутри → 500. Валидация до очереди: WordPdfValidator.validate(docxBytes, options) (внутри порядок значим: checkInput → zip-магик PK\x03\x04 → checkDocxContainer — потоковый проход: декларация wordprocessingml.document в [Content_Types].xml + лимиты zip-бомбы WordPdfSettings.MAX_DECOMPRESSED_MB/MAX_ZIP_ENTRIES, не переопределяются ConvertOptions — → checkPageCount); тот же метод — вход ядра.
  • Ключ доступа: ApiKeyFilter сверяет заголовок X-API-Key (ApiKeyFilter.HEADER) со свойством wordpdf.api-key (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). Без ключа открыты /actuator/** (HEALTHCHECK), /swagger-ui*, /v3/api-docs* — матч по пути без forwarded-contextPath (getRequestURI() минус getContextPath(); иначе под X-Forwarded-Prefix HEALTHCHECK получил бы 401); пути с точечными сегментами (../%2e) никогда не открыты. 401 пишет сам фильтр (ApiExceptionHandler ошибок фильтров не видит). Springdoc в repo compose.yml выключён (SPRINGDOC_API_DOCS_ENABLED/SPRINGDOC_SWAGGER_UI_ENABLED=false); на живом проде (compose вне репо) включён и документация открыта без ключа под https://pjandro.ru/pdf-converter/swagger-ui.html — это безусловно проверяют prod-автотесты; server-URL спека собирается из X-Forwarded-* (server.forward-headers-strategy=framework — native-клапан Tomcat X-Forwarded-Prefix не понимает). Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen, ApiKeyFilterTest#docsOpenWithoutKey.
  • Лимиты входа задаёт только конфигурация сервера: 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: вся сеть в src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), при 401 очищается, экран ApiKeyGate (UnauthorizedError — наследник ApiError, проверяется раньше); гейт показывается только когда probeApiKey() (GET /api/v1/convert → 401 от ApiKeyFilter) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на ${import.meta.env.BASE_URL}api/... (vite base из VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом /pdf-converter/). Три переключателя error-флагов в форме (App.tsx): «Диаграммы», «SmartArt», «OLE-объекты» (дефолт — все выключены), уходят в convertDocx как errorOnCharts/errorOnSmartArt/errorOnOle.

Chart-движок (internal/chart, package-private кроме DrawingPreRenderer.run)

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

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300, PADDING = 4.0, растр × DPI/72, размеры — в пунктах, EMU→pt cx/12700.0). ChartSpec.parse (enum Type: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/SCATTER/BUBBLE/RADAR/STOCK/OF_PIE/SURFACE/BAR3D/AREA3D/LINE3D/UNSUPPORTED; пустой c:title + autoTitleDeleted="0" → у круговых имя первого ряда, у прочих — AUTO_TITLE = "Название диаграммы" (русская замена англ. плейсхолдеру Word); палитра accent1..6 темы, легенда по умолчанию снизу (у SURFACE — полосы высот «0-1»…), позиция t поддержана, overlay (§21.2.2.132) → рисуется поверх области построения, место не резервирует (ChartSpec.legendOverlay, регрессия ChartRendererTest#overlayLegend_drawnOverPlot)) → ChartRenderer (осевые «круглые» шаги niceUnit 1/2/5·10ⁿ как Word; санитайзер c:majorUnit — MAX_TICKS = 1000: шаг ≤ 0/NaN/слишком мелкий в axisBounds заменяется niceUnit, иначе циклы делений вечные; общие кумулятивные хелперы stacked isStacked/stackedCumulative/stackedRange) → пейнтеры CartesianPainter (2-D line/bar/area; lineChart c:grouping stacked/percentStacked §21.2.2.76 — ряд рисуется на накопленной сумме через ChartRenderer.stackedCumulative, регрессии stackedLine_seriesStackCumulatively/percentStackedLine_topSeriesFlatAtHundred)/PiePainter (PIE_DEPTH=0.22, PIE_FIT=0.865)/Surface3dPainter (калибровка по эталону Word 300 dpi, камера — регрессия 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 во всех 3D-пейнтерах имеет приоритет над c:perspective (MS-OI29500 §2.1.1516(b)), c:hPercent сжимает глубину, c:wireframe §21.2.2.205 — только каркас без полос высот, bandFmt-полосы сортируются по глубине)/ScatterPainter (scatter/bubble: обе оси числовые, две c:valAx, X — первая; маркеры по c:marker, c:scatterStyle §21.2.2.136; радиус пузыря sqrt при c:sizeRepresents="area" §21.2.2.128 и линейно при «w», масштаб c:bubbleScale)/RadarPainter (спицы от 12 часов по часовой, c:radarStyle §21.2.2.119 standard/marker/filled, сетка — концентрические многоугольники)/StockPainter (high-low-close: c:hiLowLines/c:upDownBars/c:dropLines; цвета — дефолты UI Word, эмпирика запинена тестом)/OfPiePainter (главный пирог + вторичный пирог/стек, разбиение по c:splitType §21.2.2.155 (splitPos — MS-OI29500 §2.1.1554a/b), связи c:serLines)/Surface2dPainter (контурная карта §21.2.2.204: полосы высот между ломаными соседних рядов §21.2.2.13, передняя стенка — полоса значения переднего края, c:wireframe §21.2.2.205 — сетка листа, оси общие с декартовыми)/Cartesian3dPainter (bar3D/line3D/area3D §21.2.2.19/.101/.122 — камера Surface3dPainter.project, ряды уходят в глубину; bar3D: c:shape box/cone/cylinder/pyramid + *ToMax §21.2.3.44 (per-series c:shape переопределяет диаграммный, горизонтальная ориентация — всегда box), c:grouping stacked/percentStacked §21.2.2.76 (одна полоса глубины на категорию, сегменты столбиком, percent — нормировка к 100%; area3D stacked — полосы на стене v=0, line3D grouping игнорирует), c:gapDepth — MS-OI29500 §2.1.1474, подписи serAx рисуются, c:delete осей учитывается); SmartArtRenderer рисует кэш разложенной схемы (relationship …/office/2007/relationships/diagramDrawing, фактически word/diagrams/drawing1.xml), формы строит PresetGeometry — ECMA-пресет-геометрия a:prstGeom: avLst/gdLst/pathLst семи пресетов (rect, roundRect, ellipse, gear6, gear9, circularArrow, leftCircularArrow) дословно из presetShapeDefinitions.xml, вычислитель префиксных формул; оператор ?: = «if x > 0 then y else z» (ISO/IEC 29500-1, НЕ x != 0), углы в Arc2D передавать со знаком минус (математическая конвенция y вверх), неизвестный пресет → прямоугольник ячейки (синхрон таблицы со стандартом пинит PresetGeometryTest#tableMatchesEcmaXml); палитра темы — DrawMlColor (instance; без ThemePart — дефолтная Office-палитра accent1=4472C4…); текст — DrawMlText (шрифты — тот же бандл через BundledFontMapper.bundledFamily); утилиты RgbHsl. Калибровочные константы менять только вместе с Surface3dPainterTest/PiePainterTest. Защитные лимиты против враждебного chart-XML: ChartSpec.MAX_POINTS (c:pt/@idx §21.2.2.150/.151 и c:ptCount §21.2.2.152 — ST_UnsignedInt без верхней границы, отказ IllegalArgumentException до предвыделения списка) и MAX_TICKS (см. выше); бросок перехватывает catch DrawingPreRenderer.renderChart → штатная деградация «объект удалён + warn». Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), НЕ getOwningRelationshipPart() (это rels ссылающегося); обход XML обязан раскрывать JAXBElement.

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

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter. Иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам (без них нет колонок) → FOP падает на docx4j-baseline.
  • 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.*). Fop.Renderers.getRenderer() возвращает список (рендер выбирается по mime application/pdf). docx2fo.xslt в репозитории нет — он в jar docx4j-export-fo.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционные sectPr в body + w:br type="page" + pageBreakBefore (включая таблицы и w:sdt). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; JAXB-обход удалён — 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 молчит — подпись проверяет вызывающий. Все отказы — ValidationException.
  • Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).
  • Внимательно: комментарии в 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): MS→аналоги — 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() (источник для FopFallbackFonts), font/regular/bold/italic/boldItalic(family), FALLBACK_FAMILY. GlyphFont — глиф-движок на fontbox (метрики + растеризация глифов для текста chart-движка и покрытие глифов в GlyphCoverageNormalizer); читает TTF напрямую из classpath (не зависит от init()); рантайм не требует fontconfig/системных шрифтов — java.awt.Font из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator (перегрузки checkInput/checkPageCount и validate(byte[], ConvertOptions) — полная цепочка; без зависимости от docx4j), ConversionException, ValidationException (наследник — «вход некорректен»), DrawingFoundException (enum Kind {CHARTS, SMARTART, OLE} — отказ по error-флагу), WordPdfSettings (константы-дефолты: MAX_INPUT_MB=5, MAX_PAGES=100, защитные MAX_DECOMPRESSED_MB=200/MAX_ZIP_ENTRIES=8192, ERROR_ON_CHARTS/SMARTART/OLE=false), ConvertOptions (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF, families(), FALLBACK_FAMILY), BundledFontMapper (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук bundledFamily), GlyphFont (глиф-движок fontbox: метрики/глифы без java.awt.Font)
…/wordpdf/internal/ 7 байтовых нормализаторов + интерфейс DocxNormalizer + FopFallbackFonts (классы public — вызываются из родительского пакета; публичные члены только normalize/STEP/declare; OleObjectNormalizer — многочастный, публичный normalize(byte[], boolean), бросает DrawingFoundException(OLE))
…/wordpdf/internal/chart/ 17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только DrawingPreRenderer)
wordpdf-core/src/main/resources/fonts/ 30 TTF + 3 лицензии — бинарные фикстуры, часть 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 для springdoc) + 5 класса исключений
wordpdf-web/src/ SPA (React 19 + TS + Vite + Tailwind): 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 (musl) — chart-движку нужен только модуль java.desktop (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox, см. fonts/GlyphFont (проверено на musl-стенде без libfontconfig//etc/fonts); HEALTHCHECK busybox wget (curl/apt не ставим), non-root uid 10001); compose app+web+gateway: web-образ со своим HEALTHCHECK (wget /), в обоих compose depends_on web: condition: service_healthy; прод-compose не в репо — его рендерит job deploy (лимиты запекаются из Variables); podman-специфика обоих compose: x-podman.name_separator_compat (docker-style имена), явные healthcheck app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет; app-хелсчеки — wget, как в Containerfile), зафиксированная подсеть 10.113.0.0/24 gw 10.113.0.1 под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть). Комментарий в wordpdf-web/Containerfile «compose прод-запуска передаёт ARG VITE_BASE» устарел — repo-compose не передаёт, arg печёт CI
корневой .env.example шаблон env для локальных/compose-стендов: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_MB/WORDPDF_MAX_PAGES (пустое значение ломает binding long/int); проду .env не нужен: ключ и лимиты подаёт job deploy из Gitea Secrets/Variables, legacy-.env на проде удаляется деплоем
.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 факультативны) — прод-хостов/ключей в коде нет; окружение — mise (mise.toml: python 3.15 + автосоздаваемый .venv); прод-раннер вне git — /home/pjandro/prod/java-word-pdf/run-prod-tests.sh
docs/standards/ нормативная документация OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD schema/strict/+schema/transitional/ — источник истины для chart-движка и фикстур (правило — в секции «Chart-движок»); validate-fixtures.py — XSD-валидация samples/*.docx (lxml); регенерация — docs/standards/README.md
develop/ (вне git, gitignored) рабочие материалы и эталоны сравнения рендера (скриншоты original.jpg/converted.jpg) — не фикстуры, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах

Development Commands

mvn clean verify                        # все модули + тесты + PMD (pmd-ruleset.xml) + гейты JaCoCo: 90% строк (оба модуля) и 85% веток (core) — обязательный гейт перед push; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-app -am package         # исполняемый jar бэкенда
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   # -am обязателен (test-jar core)
npm run dev                             # (wordpdf-web/) SPA :5173, vite-proxy /api|/swagger-ui|/v3/api-docs → :8080
npm run build                           # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
podman-compose -f compose.dev.yml up -d --build   # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл

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

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 REGISTRY/DEPLOY_HOST/DEPLOY_USER/DEPLOY_DIR/WORDPDF_MAX_MB/WORDPDF_MAX_PAGES, API-ключ — из Secret WORDPDF_API_KEY через окружение деплоя, на диск не пишется), затем login/pull/up -d --force-recreate app web/гейты healthy+image/recreate gateway. Наследие ручного setup restart.sh и .env деплой удаляет; единственное состояние на проде — .rollback.env (image ID для отката). Перезадеплой — push в main или Run workflow (workflow_dispatch), ручных скриптов нет. В прод попадает только собранное CI из main; прод не собирает код и git-клона на проде нет (insecure-запись реестра в /etc/containers/registries.conf.d/). Рендеренный compose содержит podman-специфику: x-podman.name_separator_compat (имена wordpdf-prod-app-1, от них зависят гейты), явные healthcheck app/web — wget (alpine-jre образ curl не содержит; curl-хелсчек на новом образе давал вечный unhealthy и висящий up), наружный порт gateway 9010 (bind 127.0.0.1 + $DEPLOY_HOST) и фиксированная подсеть 10.112.0.0/24 gw 10.112.0.1 — внутренняя геометрия стека, литералом в workflow (не координата стенда, Variables для неё не заведены). Наружный вход https://pjandro.ru/pdf-converter/ (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа рендерится workflow и отличается от репо только резолвером 10.112.0.1 — под свою подсеть — и proxy_read_timeout 300s — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + proxy_pass через переменную есть и там и там). Тот же наружный nginx в location /pdf-converter/ добавляет X-Forwarded-Host/X-Forwarded-Prefix — из них springdoc собирает server-URL спека под префиксом. Dev-стенд — из репо compose.dev.yml (проект wordpdf-dev, 9011:80 на все интерфейсы, без env → ключ пуст, springdoc вкл). Репозиторный compose.yml — третий вариант (проект wordpdf, 9010:80, WORDPDF_API_KEY fail-closed без .env — up упадёт; VITE_BASE — build-arg wordpdf-web/Containerfile, репо-compose НЕ передаёт: compose build без arg даёт base / и битые ассеты под префиксом; на прод-путь не влияет — там VITE_BASE=/pdf-converter/ запекает CI в job images-web). Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.

CI/CD (Gitea Actions)

Два workflow. .gitea/workflows/pr.yml — PR checks (pull_request + workflow_dispatch): job java (temurin 17, кеш ~/.m2 через actions/cache, Maven 3.9.16 ставится вручную с dlcdn, mvn -B clean verify, затем Coverage summary — разбор target/site/jacoco/jacoco.xml python-сниппетом в step summary и Comment coverage on PR — тот же текст комментарием в PR (создаётся один раз, повторные push обновляют по маркеру <!-- jacoco-coverage -->; continue-on-error — падение комментария не валит job; в main.yml шаг продублирован байт-в-байт, но там никогда не срабатывает — нет PR-события). Артефактов покрытия нет намеренно: upload-artifact@v4 Gitea не поддерживает («not currently supported on GHES»), @v3 на этом стенде зависает на загрузке (проверено: отменена и с ~150 файлов, и с одним zip); HTML-отчёт — локально target/site/jacoco/) и web (кеш ~/.npm, npm ci/build/lint). .gitea/workflows/main.yml — Main: tests, deploy, autotests (push в main + workflow_dispatch): те же java/web (байт-в-байт дубль — файлы самодостаточны, 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, job-контейнеры видят podman-сокет хоста — настройка раннера вне репо, см. DEPLOY.md), deploy (SSH на прод: рендер конфигов стека heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc (рег. run 482), валидация PyYAML (рег. run 484); сохранение .rollback.env — image ID контейнеров app/web; login/pull/timeout 90 podman-compose up -d --force-recreate app web — timeout обязателен (рег. run 488); гейты healthy и image; gateway пересоздаётся последним; health-check), autotests (venv + prod-autotests/ против прода), rollback (if: failure() — сначала перерендер/перезалив prod-файлов тем же шагом (YAML-якорь *render-stack-files), что у deploy, затем retag прежних image ID на ${{ vars.REGISTRY }}/wordpdf-app:prod и …/wordpdf-web:prod, --force-recreate app web, пересоздание gateway). Кеш раннеров — сервер act_runner (серверная часть, вне репо).

Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние 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, WORDPDF_API_KEY, REGISTRY_USER, REGISTRY_PASSWORD); workflow-файлы ссылаются на них только ${{ vars.* }}/${{ secrets.* }}. Смена лимитов = правка Variables, PR не нужен. Инструкция владельца — корневой GITEA-vars.md (только имена, без значений). Защита ветки main: required-контексты PR checks / java (pull_request), PR checks / web (pull_request) (формат Gitea 1.26; deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследник BundledFontMapper (extends BestMatchingMapper), обёртка цветов DrawMlColor (тоже instance, но НЕ наследник docx4j) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единый контракт internal/DocxNormalizer (byte[] normalize(byte[]) throws IOException) + константа STEP для сборки цепочки; нечего менять → вернуть тот же массив (assertSame в тестах); package-private хук static String rewrite(String xml) для юнит-тестов (возвращает null при отсутствии изменений; есть у 6 из 7 — у многочастного OleObjectNormalizer нет); правятся только части word/*.xml.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — SymbolFontNormalizer, WordPdfValidator, Surface3dPainter и классы app; новые правки обязаны ссылаться).
  • Константы UPPER_SNAKE с числовыми эталонными значениями (PIE_DEPTH, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Классы в internal — public (иначе родительский пакет не вызвал бы), но публичные члены наружу только normalize/STEP/declare/DrawingPreRenderer.run (rewrite, карты — package-private); в wordpdf-app всё package-private кроме WordPdfApplication.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles, checkInput_bytesOverLimit, noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple, splitsRunForUncoveredGlyph); оба стиля разрешает PMD-паттерн junit5TestPattern.

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures + normalizers(options) (порядок цепочки).
  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java — все дефолты ядра (MAX_INPUT_MB 5, MAX_PAGES 100, ERROR_ON_*=false); рантайм-конфигурации в ядре нет.
  • wordpdf-app/src/main/resources/application.properties — multipart 100MB (max-file-size/max-request-size + file-size-threshold=100MB, держит файл в памяти; в тон 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, slf4j 2.0.20, JUnit 6.1.3, PDFBox/fontbox 3.0.8 (fontbox — compile в core: глиф-движок GlyphFont; pdfbox — test в обоих модулях), POI 5.5.1 (test: генератор фикстур + in-memory документы в WordPdfValidatorTest), 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 plugin 3.28.0, JaCoCo 0.8.15; пустой дефолт <argLine> (для -Djacoco.skip=true).
  • Корневой pmd-ruleset.xml — ruleset PMD (см. Testing & QA): category/java/codestyle.xml минус opinionated-правила, MethodNamingConventions с junit5TestPattern под underscore-имена регрессий, TooManyStaticImports до 12, XPath-правило LiteralFirstInEquals, unused-правила из bestpractices.xml, ReturnEmptyCollectionRatherThanNull (errorprone, priority 1), AvoidLiteralsInIfCondition (errorprone, дефолтная 3), EmptyCatchBlock (errorprone) и ForLoopCanBeForeach (bestpractices) — оба priority 2.
  • 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); resolver 10.113.0.1 + proxy_pass через переменные (статический proxy_pass резолвит имя один раз при старте — gateway раньше app поднялся бы с 502 до перезапуска). wordpdf-web/nginx.conf — чистая статика с SPA-fallback, /api НЕ проксирует.
  • wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур.
  • wordpdf-web/vite.local.config.ts — легаси-одноразовщик (прокси /api → :8091), коммит против воли автора (*.local в gitignore не накрывает .ts-суффикс), в tsconfig.node.json не включён; кандидат на удаление, не тиражировать паттерн. Корневой javac.*.args — мусор пробной компиляции (gitignored), тоже кандидат на удаление.

Runtime & Tooling Preferences

  • Java 17 + Maven (обязательны; wrapper mvnw нет); UTF-8. Только Maven — никакого Gradle/Ant.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Фронт: Node ^20.19.0 || >=22.12.0 (engines vite/rolldown/oxlint из package-lock.json — в package.json секции engines нет; 21.x и 22.0–22.11 НЕ поддерживаются), 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; podman-сборка web на node:24-alpine.
  • Контейнеры (podman/buildah): FROM только FQDN (docker.io/library/... — short-name не резолвится без unqualified-search-registries); buildah подмешивает хостовые прокси-переменные в RUN/HEALTHCHECK — обнулять HTTP_PROXY= http_proxy= … на самой команде (ENV не перебивает).
  • CI-гейта перед локальным push, форматтеров, checkstyle для Java — нет (Gitea Actions — на PR/merge, см. CI/CD); статический линтер — PMD на verify (см. Testing & QA); локальная проверка одна: mvn clean verify.
  • Исполняемый 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).

Testing & QA

  • Гейт maven-pmd-plugin 3.28.0 на verify для обоих модулей, ruleset pmd-ruleset.xml (codestyle без opinionated-правил + unused-правила + XPath LiteralFirstInEquals — строковый литерал слева в equals/equalsIgnoreCase; junit5TestPattern разрешает underscore-имена регрессий; includeTests=true — тесты сканируются; failurePriority не задан — на практике verify валят нарушения любой приоритетности, проверено на priority 3–4: строки [WARNING] PMD Failure = BUILD FAILURE). Версия PMD-движка в pom не пинится (тянется плагином).
  • Гейт JaCoCo 0.8.15: jacoco:check (правило BUNDLE, LINE COVEREDRATIO 0.90 — обоих модулей; в wordpdf-core/pom.xml execution check переопределён и добавляет BRANCH COVEREDRATIO 0.85 — только для core, у app бранчи ниже порога) на 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) и защитные ветви сканеров нормализаторов/валидатора, разобранные в комментариях к тестам.
  • 34 тестовых класса / 455 @Test (core 28/415, app 6/40: ConvertController 20 + 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 в argLine; только Assertions (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest org.hamcrest.Matchers.containsString в andExpect), тестовые классы package-private, зеркалят main-пакеты; только @Test (+ единственный @BeforeAll — warm-up шрифтов в GlyphCoverageNormalizerTest).
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper для текста (пер-странично setStartPage/setEndPage), override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчик картинок (imageCount). Негативные маркеры — регрессии: 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. Эталонные файлы — develop/, вне git.
  • 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; ручная, генератором не перезаписывать), chart-types (10 графиков: 9 типов + lineChart c:grouping=stacked; пересоздание — ChartTypesDocxGenerator).
  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame покрыт тестами только у zip-нормализаторов DocxOnOff/SymbolFont/StrictOoxml; у Field/GlyphCoverage/InvisibleChar — rewrite→null) и неприкосновенность частей вне 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).
  • Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): StrictOoxmlNormalizerTest↔strictOoxml_convertsNotRejected (+pageCount_strictBreaksCountedLightweight — lightweight против strict), 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), WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender (+checkPageCount_limitBoundary 99/100/101, pageCount_breaksInsideTablesAreCounted, pageCount_continuousSectionsNotCountedLightweight, validate_notAZip↔inputNotAZip_rejectedBeforeRender, validate_plainZipRejected/validate_xlsxRenamedRejected/validate_zipBombRejected/validate_tooManyEntriesRejected↔plainZipNotDocx_rejected/inputNotDocx_rejectedBeforeRender — контейнер и zip-бомба), BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, ChartSpecTest↔автозаголовки, PresetGeometryTest↔chartsSmartArt_drawingsBecomeImages (tableMatchesEcmaXml — синхрон таблицы пресетов с ECMA XML; кольцевые стрелки — семантика ?: и знаки дуг Arc2D), chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages (+drawingErrors_*↔app errorFlagCharts_rejected/errorFlagSmartArt_rejected), новые пейнтеры ScatterPainterTest/RadarPainterTest/StockPainterTest/OfPiePainterTest/Surface2dPainterTest/Cartesian3dPainterTest↔chartTypes_allTypesRenderAsImages (фикстура chart-types; ось X scatter/bubble и OF_PIE-заголовок — ChartSpecTest), lineChart stacked — ChartSpecTest#lineGroupingParsed + ChartRendererTest#stackedCumulative_*/stackedRange_coversNegativeSums + CartesianPainterTest#stackedLine_seriesStackCumulatively/percentStackedLine_topSeriesFlatAtHundred↔chartTypes_allTypesRenderAsImages; noLoggingWarningInPdf — регрессия slf4j-simple, pdfTitle_comesFromParameter — регрессия PDF-title (юнит-партнёра нет). App-регрессии: requestLimitParams_areIgnored, nonPositiveLimits_failStartup, unknownPath_notFound, concurrentRequests_bothSucceed (гонка реестра PhysicalFonts), corruptNotAZip_rejected, plainZipNotDocx_rejected (голый zip без манифеста → 400), junkInsideValidZip_conversionError (500 на валидном .docx-контейнере с мусором), nonDocxFilename_rejected, oversizedOverCoreLimit_rejected, drawingsAlwaysRendered, cyrillicAndPathInFilename_sanitizedResponseName (RFC 5987 + path-traversal), docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey (открытая документация + матч фильтра без forwarded-contextPath), dotSegmentOpenPrefix_rejected (точечные сегменты ../%2e — не открытый путь), errorFlagNotBoolean_rejected (битый error-флаг → 400); DoS/корректность core: ChartSpecTest#hugePointIndex_rejectedNotOom/hugePtCount_rejectedNotOom/hugeCategoryIndex_rejectedNotOom (MAX_POINTS), Surface3dPainterTest#axisBounds_tinyMajorUnit_fallsBackToNiceUnit/axisBounds_zeroMajorUnit_fallsBackToNiceUnit (MAX_TICKS), GlyphCoverageNormalizerTest#multipleTextNodes_runLeftUntouched (guard составного рана)/nestedRunInTextBox_innerSplit + SymbolFontNormalizerTest#nestedRunInTextBox_innerNormalized (вложенные раны текстбоксов), CartesianPainterTest#areaFill_closesToBaseline (AREA к базовой линии), ChartRendererTest#overlayLegend_drawnOverPlot + ChartSpecTest#overlayLegend_keepsPositionAndFlag (overlay-легенда).
  • 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 против живого прода.