From 179a2e5258d2349b0fd172308b4252e873083edd Mon Sep 17 00:00:00 2001 From: Pjandro Date: Sun, 25 Oct 2026 00:43:30 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=D0=BF=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=20=D0=BF=D0=BE=20=D1=81=D0=B2?= =?UTF-8?q?=D0=B5=D0=B6=D0=B5=D0=BC=D1=83=20=D1=81=D1=80=D0=B5=D0=B7=D1=83?= =?UTF-8?q?=20=D0=BA=D0=BE=D0=B4=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Инвизим-нормализатор (7-й шаг конвейера, интерфейс DocxNormalizer + STEP), счётчики тестов 27/323, ERROR_ON_* , MethodArgumentTypeMismatch 400, отказ точечных сегментов в ApiKeyFilter, MAX_TICKS/MAX_POINTS, версии pytest/requests, Node-engines из lockfile, PMD-движок не пинится, CI-регрессы runs 482/484/488, устаревшие пометки убраны --- AGENTS.md | 116 ++++++++++++++++++++++++------------------------------ 1 file changed, 52 insertions(+), 64 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e971390..a326ab6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Наружу `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-загрузки (цепочка `byte[] → byte[]`, порядок значим): `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, переписывает и элементы ``; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `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 не трогается), элементами `` из `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`. +2. Нормализация байтов docx до JAXB-загрузки — цепочка `List 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: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 не трогается), элементами `` из `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)`. @@ -19,10 +19,10 @@ ### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`) -- Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` — дефолт каждого `WordPdfSettings.ERROR_*`; диаграммы/SmartArt конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). +- Единственный эндпоинт `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` → 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). 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`. +- Ошибки (`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`. @@ -30,7 +30,7 @@ Нормативный источник любых правок/решений по диаграммам и SmartArt — ECMA-376 (`docs/standards/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + `schema/*.xsd`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word-эмпирике; эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). -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/UNSUPPORTED; пустой `c:title` + `autoTitleDeleted="0"` → у **круговых** имя первого ряда, у прочих — `AUTO_TITLE = "Название диаграммы"` (русская замена англ. плейсхолдеру Word); палитра `accent1..6` темы, легенда по умолчанию снизу, позиция `t` поддержана, `overlay` (§21.2.2.132) → рисуется поверх области построения, место не резервирует (`ChartSpec.legendOverlay`, регрессия `ChartRendererTest#overlayLegend_drawnOverPlot`)) → `ChartRenderer` (осевые «круглые» шаги `niceUnit` 1/2/5·10ⁿ как Word; санитайзер `c:majorUnit` — `MAX_TICKS`: шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется niceUnit, иначе циклы делений вечные) → пейнтеры `CartesianPainter`/`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`); `SmartArtRenderer` рисует кэш разложенной схемы (relationship `…/office/2007/relationships/diagramDrawing`, фактически `word/diagrams/drawing1.xml`; fit-scale ×0.80), формы строит `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`; утилиты `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`. +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/UNSUPPORTED; пустой `c:title` + `autoTitleDeleted="0"` → у **круговых** имя первого ряда, у прочих — `AUTO_TITLE = "Название диаграммы"` (русская замена англ. плейсхолдеру Word); палитра `accent1..6` темы, легенда по умолчанию снизу, позиция `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, иначе циклы делений вечные) → пейнтеры `CartesianPainter`/`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`); `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`. ### Критические инварианты (нарушение = битый вывод) @@ -49,27 +49,27 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |Путь|Назначение| |---|---| -|`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_*=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)| +|`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/`|6 байтовых нормализатора + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)| +|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)| |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| |`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/test/resources/samples/`|12 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры)| |`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-стенда одновременно не поднять (общая подсеть)| -|корневой `.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` на проде удаляется деплоем| +|корневые `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/` — источник истины для chart-движка (правило — в секции «Chart-движок»); регенерация — `docs/standards/README.md`| -|`develop/` (вне git, gitignored)|рабочие материалы и эталоны Word для ручного сравнения — **не фикстуры**, в тесты/jar не подключать; на 2026-10 директория пуста (эталоны вынесены, пиксельные замеры зашиты числами в chart-тестах)| +|`develop/` (вне git, gitignored)|рабочие материалы и эталоны сравнения рендера (скриншоты `original.jpg`/`converted.jpg`) — **не фикстуры**, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах| ## Development Commands ```bash -mvn clean verify # все модули + тесты + PMD (pmd-ruleset.xml) + гейты JaCoCo: 90% строк (оба модуля) и 85% веток (core) — обязательный гейт перед push +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 @@ -88,77 +88,65 @@ 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`/`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` — внутренняя отладка. +Деплой. **Прод** — на пользовательском 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-сниппетом в файл -`coverage-summary.md` + step summary job'а и `Comment coverage on PR` — тот же текст -комментарием в PR (создаётся один раз, повторные push обновляют по маркеру -``; `continue-on-error` — падение комментария не валит job; -в `main.yml` шаг продублирован байт-в-байт, но `if: github.event_name == 'pull_request'` -там не срабатывает). **Артефактов покрытия нет намеренно**: `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` -(два job, needs `java`/`web` соответственно: `docker build` каждого Containerfile + `docker push` в 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 на прод: рендер `docker-compose.yml` -и `nginx.conf` в директорию деплоя (Variable `DEPLOY_DIR`) из Variables/Secrets — -на проде конфигурации не хранится; сохранение `.rollback.env` — image ID контейнеров -app/web; login/pull/`up -d --force-recreate app web`; гейты healthy и image; -`up -d --force-recreate gateway`; health-check. Лимиты задают Variables -`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, `autotests`/`rollback` используют те же), `autotests` (venv + -`prod-autotests/` против прода), -`rollback` (`if: failure()` — сначала перерендер/перезалив prod-файлов тем же шагом, что у deploy, -затем retag прежних image ID на `${{ vars.REGISTRY }}/wordpdf-app:prod` и `…/wordpdf-web:prod`, `--force-recreate app web`, пересоздание gateway). Кеш раннеров — -сервер act_runner (серверная часть, вне репо). +затем `Coverage summary` — разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary +и `Comment coverage on PR` — тот же текст комментарием в PR (создаётся один раз, повторные push обновляют по маркеру +``; `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.* }}`. -Инструкция владельца — корневой `GITEA-vars.md` (только имена, без значений). Защита ветки -`main`: required-контексты **`PR checks / java (pull_request)`, `PR checks / web (pull_request)`** -(формат Gitea 1.26; deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда). +**Правило: координаты прода и креды в коммитимые файлы не попадают** — ни внутренние 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`. -- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений); правятся только части `word/*.xml`. +- Нормализаторы — единый контракт `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`/`declare`/`DrawingPreRenderer.run` (`rewrite`, `split`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. -- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`). +- Классы в `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`. -- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB` 5, `MAX_PAGES` 100, `ERROR_*=false`); рантайм-конфигурации в ядре нет. +- `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). -- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `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 `3.28.0`, JaCoCo `0.8.15`. +- `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`; пустой дефолт `` (для `-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` не включён; кандидат на удаление, не тиражировать паттерн. +- `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/oxlint из lockfile; 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`. +- Фронт: 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). @@ -166,14 +154,14 @@ SSH-пользователи/логины, ни хосты, ни директо ## Testing & QA -- Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `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). Литералы в условиях `if` — только именованными константами (`AvoidLiteralsInIfCondition`; `else if`-ветки правило не проверяет, обычный вложенный `if` — проверяет; пустые `while` тоже валятся — `EmptyControlStatement`), `null` вместо пустой коллекции запрещён (`ReturnEmptyCollectionRatherThanNull` — `GlyphCoverageNormalizer.split` возвращает пустой список). -- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило 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`) и защитные ветви сканеров нормализаторов/валидатора, разобранные в комментариях к тестам. -- 26 тестовых класса / 367 `@Test` (core 20/327, app 6/40: ConvertController 20 + ApiKeyFilter 8 + ConvertLimits 2 + ConversionService 5 + ApiExceptionHandler 4 + 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, допуски `assertRatio` <0.06 (`PiePainterTest` аспект h/w=0.585) / <0.10 (`Surface3dPainterTest`, + `assertRange` ±6 pt для центров силуэта); пороги залитых px и перцентильные коридоры яркости. Эталонные замеры — по Word-экспорту 300 dpi (числа зашиты в тесты; эталонные файлы — `develop/`, вне git, на 2026-10 пуста). +- Гейт `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`) и защитные ветви сканеров нормализаторов/валидатора, разобранные в комментариях к тестам. +- 27 тестовых классов / 323 `@Test` (core 21/283, 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` (12; в тестах не генерировать): 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` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject`; ручная, генератором не перезаписывать). -- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml` и у `OleObject` — `printerSettings`-bin/нет `.bin`; у `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` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `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`); `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 + requests, 21 проверка, env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода; `WORDPDF_API_KEY` пуст → честный SKIP `@needs_key`-проверок. +- Юниты нормализаторов работают строками (`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`); `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 против живого прода. -- 2.56.1