# Repository Guidelines ## Project Overview Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Локальный гейт перед `git push` — `mvn clean verify` (CI не блокирует push, но Gitea Actions `PR checks` — required-контексты защиты `main`; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — gateway-контейнер nginx (:9010 prod / :9011 dev), НЕ 8080. README устарел (порты/топология, «413 6 МБ» — фактически 100 МБ, нет API-ключа, лимиты подаёт как константы — они конфигурируемы); авторитетен этот файл. ## Architecture & Data Flow ### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` (порядок фиксирован, менять местами нельзя) Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → контейнер (.docx-манифест + zip-бомба) → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`: 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). 2. Нормализация байтов docx до JAXB-загрузки — цепочка `List 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.xslt` docx4j ветка `%` закомментирована, 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: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-ссылками (oleObject-ссылки удаляются по типу, включая TargetMode=External) и Override удалённых частей; элементы `` из `word/*.xml` НЕ выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10): `w:drawing` переиспользуется дословно, `v:imagedata r:id` → inline-DrawingML на ту же image-часть (размер из `style` `v:shape`, иначе `w:dxaOrig`/`w:dyaOrig` ×635), блоки с `w:control` и без плейсхолдера удаляются; OLE-бинарники никогда не читаются; находка — OLE-часть ИЛИ разметка ` 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`, **фолбэк-семейство темы тоже алиасится** — иначе «Calibri» не находится в `GlyphFont` и текст молча уезжает в более широкий DejaVu, из-за чего переносы вылезали за фигуру, регрессия `DrawMlTextTest#fallbackFamilyAliasedToBundle`; `fitCut` гарантирует прогресс реза на 1 символе — иначе `wrapLines` вечный цикл; высота строки — из `a:lnSpc` spcPct/spcPts §21.1.2.4, регрессия `DrawMlTextTest#lineSpacingPct_compactsLines`); autofit фигур — только `normAutofit` (§21.1.2.1.2/.3: отсутствие autofit-элемента имплицирует noAutofit — заявленный кегль не ужимается, переполнение уходит за фигуру, как Word; запечённый Word-ом `fontScale` применяется, без него — подбор кегля под высоту надетого текста `DrawMlText.totalHeight` с низом `MIN_FONT_PT=4pt`; регрессии `SmartArtRendererTest#normAutofitShrinksToFit`/`#missingAutofitKeepsDeclaredSize`); заполнитель `dgm:prSet/@phldrT` («[Текст]», §21.4.3.4) не рисуется — элемент UI, в PDF Word его не показывает (`SmartArtRendererTest#emptyTxBody_noPlaceholderInk`, `render` без `CTDataModel`); утилиты `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`. `Combo` (Word «Комбинированная», §21.2.2.145): несколько групп в одном `c:plotArea` (`c:barChart` + `c:lineChart`/`c:areaChart`), каждая со своими `c:axId` (§21.2.2.9) — `parse` привязывает группы по id осей: `Series.renderAs` (семейство отрисовки ряда), `Series.grouping` (накопление своей группы), `Series.valAxis` + `ChartSpec.secondaryValAxis` (ось значений группы, обычно `c:axPos="r"`); `spec.valAxis`/`catAxis` — first-wins (не last-wins), `type` combo = первая группа (без `axId` в XML — поведение как у одноосных, привязка пропускается). `CartesianPainter` рисует семейства в порядке BAR→AREA→LINE (столбцы позади, линия поверх), каждая серия масштабируется по своей оси, вторичная ось — линия по правому краю + подписи справа (gridlines только если заявлена), `stacked` накапливает только внутри семейства, у stacked-серии на вторичной оси (враждебный XML) — сырые значения; легенда `lineLike` по `renderAs` ряда. Регрессии — `ChartSpecTest#combo_barAndLine_renderAsAndAxes`/`combo_sameAxis_noSecondary`, `CartesianPainterTest#combo_barsAndLineOnSecondary_bothDrawn`, фикстура `chart-types` (chart14 «Комбинация»). ### Критические инварианты (нарушение = битый вывод) - `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`. - `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback. - FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo` 17.3.2, в pom не пинится; пакеты `org.apache.fop.*`). `Fop.Renderers.getRenderer()` возвращает **список** (рендер выбирается по mime `application/pdf`). `docx2fo.xslt` в репозитории нет — он в jar `docx4j-export-fo`. - Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; JAXB-обход удалён — `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитулах — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy-значения `val`: `null|true|1|on`); на не-zip молчит — подпись проверяет вызывающий. Все отказы — `ValidationException`. - Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно). - Внимательно: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно). ### Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`) 7 семейств × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в `BundledFontMapper.ALIASES` (ключи lowercase): MS→аналоги — Calibri→Carlito, **Calibri Light→Carlito**, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. `DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`); `BundledFontMapper.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движок). Публичный API `BundledFonts` шире реестра: `families()` (источник для `FopFallbackFonts`), `font/regular/bold/italic/boldItalic(family)`, `FALLBACK_FAMILY`. `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для текста chart-движка и покрытие глифов в `GlyphCoverageNormalizer`); читает TTF напрямую из classpath (не зависит от `init()`); рантайм не требует fontconfig/системных шрифтов — `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). ## Key Directories |Путь|Назначение| |---|---| |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)| |`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка совместимости commons-compress, шаг 0 `convertToStream`) (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`/`DependencyGuard.check`; `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-команды не меняются. ```bash 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://:9011 (0.0.0.0), без ключа, springdoc вкл ``` Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` и `ole-embedded.docx` НЕ генерируются — созданы вручную, не перезаписывать; `chart-types.docx` — `ChartTypesDocxGenerator`, chart-XML литералами, команда в его javadoc): ```bash 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 обновляют по маркеру ``; `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`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. - Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`. ## Important Files - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки). - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB` 5, `MAX_PAGES` 100, `ERROR_ON_*=false`); рантайм-конфигурации в ядре нет. - `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=2MB` — части крупнее 2 МБ на диск, не в память; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-mb`/`max-pages` здесь намеренно нет. - `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core. - `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85). - Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, 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); `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-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`) и защитные ветви сканеров нормализаторов/валидатора, разобранные в комментариях к тестам. - 35 тестовых класса / 528 `@Test` (core 29/486, app 6/42: ConvertController 22 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ два `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`). - **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`; исключение — структурная проверка чернил в `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 там падали `GlyphCoverageNormalizerTest` 12 / `CartesianPainterTest` 3 / `PiePainterTest` 2 / chart-тесты `WordPdfConverterTest` 4, chart-рендер молча деградировал). `GlyphFontTest` написан без единого `java.awt.Font` — обязан проходить на хосте без fontconfig. - Фикстуры — закоммиченные `samples/*.docx` (13; в тестах не генерировать; все ECMA-conformant по `docs/standards/validate-fixtures.py` — фикстура невалидна, правится фикстура, не код): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — 1×1 RGBA; исходный рукописный PNG был бит (IDAT length 13 при 16 байтах данных + мусор перед IEND, FOP падал `chunkType is null` в `PNGImageDecoder`) — заменён in-place на валидный, XML-части не тронуты; ручная, генератором не перезаписывать), `chart-types` (13 графиков + wireframe-поверхность + combo = 14: 9 типов + ofPie pie-вариант (`c:ofPieType`="pie") + lineChart `c:grouping`=stacked + `c:wireframe` val="1" + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `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` (+app `errorFlagOle_rejected`/`oleObjects_removedByDefault`; сохранение плейсхолдера — юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`/`errorFlagObjectWithoutBin_rejects`, в `oleObjects_removedAndConverted` — `distinctImageCount==1`, RGBA FOP режет на картинку+SMask), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero` — нечитаемый `` → 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_*`↔app `errorFlagCharts_rejected`/`errorFlagSmartArt_rejected`), новые пейнтеры `ScatterPainterTest`/`RadarPainterTest`/`StockPainterTest`/`OfPiePainterTest`/`Surface2dPainterTest`/`Cartesian3dPainterTest`↔`chartTypes_allTypesRenderAsImages` (фикстура `chart-types`; ось X scatter/bubble и OF_PIE-заголовок — `ChartSpecTest`), lineChart stacked — `ChartSpecTest#lineGroupingParsed` + `ChartRendererTest#stackedCumulative_*`/`stackedRange_coversNegativeSums` + `CartesianPainterTest#stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`↔`chartTypes_allTypesRenderAsImages`; `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `plainZipNotDocx_rejected` (голый zip без манифеста → 400), `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath), `dotSegmentOpenPrefix_rejected` (точечные сегменты `..`/`%2e` — не открытый путь), `errorFlagNotBoolean_rejected` (битый error-флаг → 400), `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-легенда). - SmartArt-текст: `SmartArtRendererTest#normAutofitShrinksToFit`/`#missingAutofitKeepsDeclaredSize`/`#emptyTxBody_noPlaceholderInk` + `DrawMlTextTest#fallbackFamilyAliasedToBundle`/`#lineSpacingPct_compactsLines` ↔ `chartsSmartArt_drawingsBecomeImages` (autofit только `normAutofit` §21.1.2.1.2/.3 с подбором кегля под перенесённый текст, высота строки из `a:lnSpc`, фолбэк-семейство темы алиасится в бандл, `phldrT` не рисуется). - 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 против живого прода.