- AGENTS.md: guard сосуществования StrictOoxml + якорь DocxOnOff в описании цепочки; MAX_EXTENT_EMU/axisBounds-реюнит/fitCut в защитных лимитах; file-size-threshold=2MB; mem_limit 2g + JAVA_TOOL_OPTIONS; proxy_*_timeout 300s у gateway; два @BeforeAll; assertSame-список; пиксели — исключение GlyphFontTest; новые регрессивные пары - App.tsx: лимиты без запечённых чисел (их подаёт конфигурация сервера) - api.ts: 'Framework 7' -> Spring; 405 — от ApiExceptionHandler (после фикса 405 больше не дефолт Tomcat)
68 KiB
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:
new BundledFontMapper()→BundledFonts.init()→BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестрPhysicalFonts; ключ реестра — имя из name-таблицы TTF,addPhysicalFont(URI)не перезаписывает занятый →init()вызываетdropNonBundled()до регистрации иload()(иначе системный Calibri ломает em-dash-fallback).- Нормализация байтов 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; рерайт только strict-документов (содержатpurl.oclc.org), а при уже присутствующем transitional-URI в документе — никакого рерайта (guard сосуществования форм —transitionalCoexistReturnsOriginalArray); вmc-preprocessor.xsltdocx4j ветка%закомментирована, start/end не маппятся; namespaces иpt-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) →DocxOnOffNormalizer(w:val="off"/"on"→false/true, якорь по тегу — только атрибутw:val, текст между тегами не трогается) →SymbolFontNormalizer(PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы<w:sym>, правитw:lvlв numbering.xml; 5 карт по 256 слотов, таблицаSymbolMapperсгенерирована из docx4j 17.x) →FieldNormalizer(fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple, вложенные/битые поля пропускает) →InvisibleCharNormalizer(вырезание изw:tU+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-кэш, НЕ docx4jGlyphCheck— тот плодит 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) и NPEchunkType is nullв VML-сериализацииw:objectпри честном типе; многочастный — публичный член толькоnormalize(byte[], boolean),rewrite-хука нет) →WordprocessingMLPackage.load. WordPdfValidator.checkPageCount(docxBytes, maxPages)— до рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.pkg.setFontMapper(mapper)→DrawingPreRenderer.run(pkg, options)(шаг 3.5:c:chart/dgm:relIdsdocx2fo.xslt не умеет — свой Java2D-движокinternal/chart/*рендерит в PNG 300 dpi и подменяет наpic:pic; объекты конвертируются всегда, отказ только по error-флагуConvertOptions—DrawingFoundException; упавший рендер — объект удаляется из docx (gd.getAny().clear()) + warn, деградация не падение).new FOSettings(pkg)+FopFallbackFonts.declare(декларирует все бандл-семейства — FOP встраивает только задекларированные) →FORendererApacheFOP/FOUserAgent(непустойtitle→ заголовок PDF) →Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).finally:deleteEmbeddedFontTempFiles()(в 17.xOpcPackage.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(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты). Без ключа открыты/actuator/**(HEALTHCHECK),/swagger-ui*,/v3/api-docs*— матч по пути без forwarded-contextPath (getRequestURI()минусgetContextPath(); иначе подX-Forwarded-PrefixHEALTHCHECK получил бы 401); пути с точечными сегментами (../%2e) никогда не открыты. 401 пишет сам фильтр (ApiExceptionHandlerошибок фильтров не видит). Springdoc в repocompose.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-клапан TomcatX-Forwarded-Prefixне понимает). Регрессии —ApiKeyFilterTest#forwardedPrefix_healthStaysOpen,ApiKeyFilterTest#docsOpenWithoutKey. - Лимиты входа задаёт только конфигурация сервера:
wordpdf.max-mb/wordpdf.max-pages(envWORDPDF_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/...(vitebaseиз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, иначе циклы делений вечные; axisBounds также перебирает шаг при неконечном диапазоне и отбрасывает нечитаемый majorUnit при ±∞-осях scaling; общие кумулятивные хелперы 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 (главный пирог, замкнутый «Other»-сектором — MS-OI29500 §2.1.1507(a), обращён центром к 3 часам ко вторичной, цвет — следующая ротация палитры; пара пирогов центрирована, зазор GAP_FIT=0.25·d1 — Word-эмпирика; вторичный пирог/стек, разбиение по c:splitType §21.2.2.155 (splitPos — MS-OI29500 §2.1.1554a/b), вторичный пирог стартует от конца «Other»-сектора; c:serLines — ровно две связи от границ «Other»-сектора к ободу вторичного на 270°±wedgeSweep / левым углам столбца — MS-OI29500 §2.1.1545(a))/Surface2dPainter (контурная карта §21.2.2.204: полосы высот между ломаными соседних рядов §21.2.2.13, передняя стенка — полоса значения переднего края; c:wireframe §21.2.2.230 — вид сверху (X=категории, Y=ряды, серия 0 внизу) без заливок: изолинии на границах полос высот lo+k·unit цветом нижней полосы (c:bandFmts §21.2.2.13/.14, без них — палитра), marching squares, седло — по среднему ячейки; сетка catAx/serAx, рамка plot; ось значений не рисуется)/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…, битый a:srgbClr/@val — дефолт вместо падения); текст — DrawMlText (шрифты — тот же бандл через BundledFontMapper.bundledFamily; fitCut гарантирует прогресс реза на 1 символе — иначе wrapLines вечный цикл); утилиты 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 (см. выше) и ChartSpec.MAX_EXTENT_EMU (a:ext/a:chExt §21.2.2.62 — ST_PositiveSizeType без верхней границы, extent > 2^31 EMU заменяется размером якоря, иначе BufferedImage OOM); бросок перехватывает catch DrawingPreRenderer.renderChart → штатная деградация «объект удалён + warn» (DrawingPreRenderer log; подмена graphic на pic:pic — структурный обход swapForPicture, не toString-замена). Обход 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-fo17.3.2, в pom не пинится; пакетыorg.apache.fop.*).Fop.Renderers.getRenderer()возвращает список (рендер выбирается по mimeapplication/pdf).docx2fo.xsltв репозитории нет — он в jardocx4j-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, JAVA_TOOL_OPTIONS=-Xmx1536m); compose app+web+gateway: mem_limit: 2g app (в паре с -Xmx1536m — heap в лимите контейнера, JVM не OOM-киллится), web-образ со своим HEALTHCHECK (wget /), в обоих compose depends_on web: condition: service_healthy; прод-compose не в репо — его рендерит job deploy (лимиты запекаются из Variables, mem_limit литералом); 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; прод-тесты: ./mise.sh run prod-tests); прод-раннер вне 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
Перед первой сборкой — бутстрап toolchain: скачивает сам mise в ./.mise/bin (gitignored, в систему ничего не ставится) и ставит инструменты из корневого mise.toml — Linux/macOS sh bootstrap.sh, Windows powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1. mvn/npm/python/java из команд ниже берутся из project-local mise: запуск ./mise.sh exec -- mvn clean verify (Windows .\mise.ps1 exec -- …) либо активация шелла eval "$(./.mise/bin/mise activate bash)"; готовые задачи — ./mise.sh run verify|app-package|app-run|web-install|web-build|web-lint|web-dev|prod-tests. Контейнерные/compose-команды не меняются.
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_MB5,MAX_PAGES100,ERROR_ON_*=false); рантайм-конфигурации в ядре нет.wordpdf-app/src/main/resources/application.properties— multipart 100MB (max-file-size/max-request-size+file-size-threshold=2MB— части крупнее 2 МБ на диск, не в память; в тон gatewayclient_max_body_size 100m),wordpdf.convert-timeout=2m, пустойwordpdf.api-key,server.forward-headers-strategy=framework(префикс прод-прокси для springdoc) +springdoc.swagger-ui.persist-authorization=true;wordpdf.max-mb/max-pagesздесь намеренно нет.wordpdf-app/pom.xml—spring-boot-maven-pluginс явной executionrepackage(в 4.1.1 сам не связывается, jar останется тонким);slf4j-simpleисключён;spring-boot-starter-webmvc(Boot 4: переименован из starter-web) +spring-boot-starter-actuator(нужен HEALTHCHECK контейнера/actuator/health); тест-зависимости:spring-boot-webmvc-test(в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.wordpdf-core/pom.xml—maven-jar-pluginexecutiontest-jar(публикует фикстуры для app); JaCoCo executioncheckпереопределён (LINE 0.90 + BRANCH 0.85).- Корневой
pom.xml— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.2, slf4j2.0.20, JUnit6.1.3, PDFBox/fontbox3.0.8(fontbox— compile в core: глиф-движокGlyphFont;pdfbox— test в обоих модулях), POI5.5.1(test: генератор фикстур + in-memory документы вWordPdfValidatorTest), Spring Boot4.1.1(BOM-import), springdoc3.1.1; pluginManagement: compiler3.16.0, surefire3.6.0с-Djava.awt.headless=true, jar3.5.1, PMD plugin3.28.0, JaCoCo0.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);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-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. Java/Maven/Node/Python для локальной разработки ставит project-local mise (бинарь в.mise/, вне системы; кеш инструментов — user-директория mise по умолчанию), версии пинятся в корневомmise.toml, ежедневный запуск —./mise.sh/.\mise.ps1(см. Development Commands). - Версии зависимостей — только в корневом
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-plugin3.28.0 наverifyдля обоих модулей, rulesetpmd-ruleset.xml(codestyle без opinionated-правил + unused-правила + XPathLiteralFirstInEquals— строковый литерал слева в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 COVEREDRATIO0.90— обоих модулей; вwordpdf-core/pom.xmlexecutioncheckпереопределён и добавляет BRANCH COVEREDRATIO0.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 тестовых класса / 462
@Test(core 28/422, 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-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect), тестовые классы package-private, зеркалят main-пакеты; только@Test(+ два@BeforeAll— warm-up шрифтов вGlyphCoverageNormalizerTestиBundledFonts.init()вBundledFontsTest). - PDF сравнивается текстом, не растеризацией: PDFBox 3 (
Loader.loadPDF) —PDFTextStripperдля текста (пер-страничноsetStartPage/setEndPage), overrideprocessTextPositionдля шрифта конкретного символа (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; исключение — структурная проверка чернил вGlyphFontTest(без сравнения с эталоном). Эталонные файлы —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 там падалиGlyphCoverageNormalizerTest12 /CartesianPainterTest3 /PiePainterTest2 / chart-тестыWordPdfConverterTest4, chart-рендер молча деградировал).GlyphFontTestнаписан без единогоjava.awt.Font— обязан проходить на хосте без fontconfig.- Фикстуры — закоммиченные
samples/*.docx(13; в тестах не генерировать; все ECMA-conformant поdocs/standards/validate-fixtures.py— фикстура невалидна, правится фикстура, не код): core грузит classpath-ресурсом →byte[], PDF для PDFBox — временный файл; app читает/samples/…из test-jar core (classifiertests) →mvn -pl wordpdf-appбез-amне соберётся. In-memory docx —ZipOutputStreamиз литеральных XML или POI вbyte[]. Ключевые:too-many-pages(150 явных разрывов → 151),stale-cache(кэш<Pages>1</Pages>+ 110lastRenderedPageBreak),charts-smartart(4 растра; SmartArt-одиночка = ровно 2 Image XObject),ole-embedded(осиротевший bin с ложнымDefault bin→footer+xml+ настоящийw:objectс честнымOverride → oleObject; ручная, генератором не перезаписывать),chart-types(12 графиков + wireframe-поверхность = 13: 9 типов + ofPie pie-вариант (c:ofPieType="pie") + lineChartc:grouping=stacked +c:wireframeval="1"; пересоздание —ChartTypesDocxGenerator). - Юниты нормализаторов работают строками (
rewrite) + zip'ами изZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSameпокрыт тестами у zip-нормализаторовDocxOnOff/SymbolFont/StrictOoxml/InvisibleCharи многочастногоOleObject; уField/GlyphCoverage—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;indCoexistForms_convertsNotRejected+ юнитыindCoexistLeftStartUntouched/indStartOnlyRenamedTransitional/tcMarCoexistKept/tcMarStartOnlyRenamedTransitional/tcBordersElementsKeptTransitional/jcStartKeptTransitional/tabStartRenamedTransitional/transitionalCoexistReturnsOriginalArray— guard сосуществования форм + strict-gating),DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont(+onOffInTextNotTouched—w:valправится только внутри тега),SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash,FieldNormalizerTest↔pageNumbers_recomputedNotCached,InvisibleCharNormalizerTest↔invisibleChars_noEmptyLines,GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash,OleObjectNormalizerTest↔oleObjects_removedAndConverted/drawingErrors_errorFlagRejectsOle(+apperrorFlagOle_rejected/oleObjects_removedByDefault),WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender(+checkPageCount_limitBoundary99/100/101,cachedPagesUnreadableFallsBackToZero— нечитаемый<Pages>→ 0,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_*↔apperrorFlagCharts_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),methodNotSupportedReturns405/badContentTypeReturns415(405/415 вместо catch-all 500); DoS/корректность core:ChartSpecTest#hugePointIndex_rejectedNotOom/hugePtCount_rejectedNotOom/hugeCategoryIndex_rejectedNotOom(MAX_POINTS),Surface3dPainterTest#axisBounds_tinyMajorUnit_fallsBackToNiceUnit/axisBounds_zeroMajorUnit_fallsBackToNiceUnit(MAX_TICKS),ChartRendererTest#axisBounds_explicitHugeRange_reunitsToMaxTicks/axisBounds_infiniteSpan_fallsBackToData(шаг при враждебном/неконечном диапазоне),ChartSpecTest#nonFiniteScalingBounds_dropped(±∞ scaling),WordPdfConverterTest#hostileChartAxis_convertsNotHangs/hugeExtentChart_removedNotOom/chartWithoutExtent_errorFlagRejects(MAX_EXTENT_EMU),DrawMlTextTest#hugeWord_wrapsLinearly(fitCut — прогресс реза),DrawMlColorTest#invalidSrgbHexFallsBackToOfficeDefault(битый hex темы — деградация),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 против живого прода.