docs: warmup + отключение discovery в инвариантах, pipeline и счётчиках
PR checks / web (pull_request) Successful in 45s
PR checks / java (pull_request) Successful in 1m53s
Main: tests, deploy, autotests / web (push) Successful in 34s
Main: tests, deploy, autotests / java (push) Successful in 1m7s
Main: tests, deploy, autotests / images-web (push) Successful in 31s
Main: tests, deploy, autotests / images-app (push) Successful in 51s
Main: tests, deploy, autotests / deploy (push) Successful in 2m30s
Main: tests, deploy, autotests / autotests (push) Successful in 1m48s
Main: tests, deploy, autotests / rollback (push) Has been skipped

- инвариант: гейт-свойства discoverPhysicalFonts/discoverJarFonts в
  static-блоке WordPdfConverter (замер реестра 114 → 0+7 symbol);
- pipeline.md: шаг 1 (constructor больше не сканирует систему/jar'ы) +
  раздел warmup() с A/B-числами (0,13 с против 1,74 с);
- очередь app: warmup головой очереди;
- счётчики тестов: 59/891 (core 53/848, WordPdfConverterTest 77).
This commit was merged in pull request #92.
This commit is contained in:
Pjandro
2026-11-03 20:37:53 +00:00
parent 30aba6bb45
commit 1ecaa9e959
3 changed files with 10 additions and 5 deletions
+3 -2
View File
@@ -84,7 +84,7 @@
Тело ошибки — `{"error": …}`. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
- **Ключ доступа**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES`, пути с точечными сегментами — никогда. Механика `ApiKeyFilter` — `docs/agent/repo-map.md`.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (переполнение → 503) — ядро мутирует глобальный `PhysicalFonts` и **не потокобезопасно**; лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, SpEL-дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются, в `application.properties` не объявлены). Подробности — `docs/agent/repo-map.md`.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (переполнение → 503) — ядро мутирует глобальный `PhysicalFonts` и **не потокобезопасно**; головой очереди на старте стоит `WordPdfConverter.warmup()` (первый запрос после деплоя — за прогретым ядром, ~0,1–0,4 с вместо 1,4–1,9 с); лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, SpEL-дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются, в `application.properties` не объявлены). Подробности — `docs/agent/repo-map.md`.
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), экран `ApiKeyGate` показывается только когда `probeApiKey()` подтвердил требование ключа; base — `VITE_BASE` (дефолт `/`, CORS не нужен); три error-флага (дефолт — выключены), DropZone `.docx,.doc`. Полный текст — `docs/agent/repo-map.md`.
### Chart/SmartArt-движок (`internal/chart`)
@@ -100,6 +100,7 @@ chart-PNG вставляются media-частями вручную (`DrawingPr
### Критические инварианты (нарушение = битый вывод, не исключение)
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `docx4j.fonts.discoverJarFonts.enabled=false` — static-блок `WordPdfConverter`: `BestMatchingMapper` (static) сканирует системные шрифты и jar'ы classpath'а, а `BundledFonts.restrictToBundled()` перед каждой конвертацией всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше (замер: реестр без гейта 114 шрифтов, с гейтом 0 + 7 symbol).
- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия `docx2fo.xslt` из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, полупункты, Part 1 §17.3.2.24 — docx4j position игнорирует; AUDIT-FIX-2 — шаблоны `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir` (plain-text passthrough, move-правки не раскрашиваются, bidi — принятая деградация), иначе их ловит catch-all `match="*"` и текст теряется; руби тут не чинится — схема docx4j не биндит `w:rubyBase`/`w:rt`, их разбирает правило 10 в байтах). Дрейф-гейт `WordPdfConverterTest#vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилисту из jar'а (сравнение с возвратом AUDIT-FIX-региона к исходному вызову `createBlockForRPr` и удалением региона AUDIT-FIX-2) — при апгрейде docx4j перевендорить и перенести патчи. `setCustomXsltTemplates` принимает предкомпилированный `Templates` (`getTemplates` кастит Object→Templates, поток кидает CCE).
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo` 17.3.2, в pom не пинится; пакеты `org.apache.fop.*`). `w:renderers` в docx4j 17.x содержит несколько `w:renderer` (по mime) — `FopFallbackFonts` берёт тот, у которого mime `application/pdf`, иначе первый со шрифтами. Оригинал `docx2fo.xslt` — в jar `docx4j-export-fo`, в конвейере используется вендорная копия (bullet «Единственный XSL-FO-стилист»).
@@ -185,7 +186,7 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
## Testing & QA
- Гейты: PMD `maven-pmd-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — пороги LINE `0.90` (оба модуля), BRANCH `0.85` (core); отчёт `report` раньше `check` (при провале порога отчёт уже на диске). Механика `argLine`/`prepare-agent`/`jacoco.skip` — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
- Счётчики: 57 тестовых класса / 886 теста (core 51/843, app 6/43; разбивка — `docs/agent/repo-map.md`). JUnit 6, только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты.
- Счётчики: 59 тестовых класса / 891 тест (core 53/848, app 6/43; разбивка — `docs/agent/repo-map.md`). JUnit 6, только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично), `processTextPosition` для шрифта символа, обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`), счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`).
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — `docs/agent/testing.md`.
- Фикстуры — только закоммиченные `samples/*.docx` + `samples/*.doc`, в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.