From 33d829a22d17b06c9fc1582ff220ee052b5caa2d Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 3 Nov 2026 20:16:24 +0000 Subject: [PATCH 1/4] =?UTF-8?q?perf(core):=20=D0=BE=D1=82=D0=BA=D0=BB?= =?UTF-8?q?=D1=8E=D1=87=D0=B8=D1=82=D1=8C=20=D0=BC=D1=91=D1=80=D1=82=D0=B2?= =?UTF-8?q?=D1=8B=D0=B5=20=D1=81=D0=BA=D0=B0=D0=BD=D1=8B=20=D1=88=D1=80?= =?UTF-8?q?=D0=B8=D1=84=D1=82=D0=BE=D0=B2=20docx4j=20=D0=B2=20BestMatching?= =?UTF-8?q?Mapper?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BestMatchingMapper (static) при первом касании сканирует системные шрифты и все jar'ы classpath'а (~100–140 мс на JVM плюс память реестра), а BundledFonts.restrictToBundled() перед каждой конвертацией всё найденное выбрасывает. Гейт-свойства discoverPhysicalFonts/discoverJarFonts ставим в false в static-блоке WordPdfConverter (инициализация класса предшествует первому new BundledFontMapper()). discoverJarFonts("fonts-symbol") свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше; живой реестр (Panose-путь) после restrict идентичен, всё незамапленное — финальный fallback DejaVu Sans (прежняя стратегия). --- .../main/java/ru/pjandro/wordpdf/WordPdfConverter.java | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java index 7ca1e25..fd09cbc 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -57,6 +57,16 @@ public final class WordPdfConverter { // которые FOP отвергает («Invalid property ... docx4j-baseline»). // GSUB-фичи отключаем: без них FOP живёт нормально, а с ними — нет. Docx4jProperties.setProperty("docx4j.convert.out.fo.gsubFeatures", "false"); + // BestMatchingMapper (static) сканирует системные шрифты и все jar'ы + // classpath'а за шрифтами — всё найденное выбрасывает + // BundledFonts.restrictToBundled() перед каждой конвертацией. + // Реестр обязан оставаться бандл + встроенные в docx. Свойства читает + // тот же static-блок BestMatchingMapper (docx4j-core 17.3.2); наша + // инициализация предшествует первому new BundledFontMapper(). + // discoverJarFonts("fonts-symbol") свойством не гейтится — символ- + // шрифт регистрируется как раньше и снимается restrict'ом как раньше. + Docx4jProperties.setProperty("docx4j.fonts.discoverPhysicalFonts.enabled", "false"); + Docx4jProperties.setProperty("docx4j.fonts.discoverJarFonts.enabled", "false"); } private WordPdfConverter() { -- 2.56.1 From 1f00512a6649f07798c5593bc348997b45210963 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 3 Nov 2026 20:23:59 +0000 Subject: [PATCH 2/4] =?UTF-8?q?perf(core):=20WordPdfConverter.warmup()=20?= =?UTF-8?q?=E2=80=94=20=D0=BF=D1=80=D0=BE=D0=B3=D1=80=D0=B5=D0=B2=20=D1=8F?= =?UTF-8?q?=D0=B4=D1=80=D0=B0=20=D0=BC=D0=B8=D0=BD=D0=B8=D0=BC=D0=B0=D0=BB?= =?UTF-8?q?=D1=8C=D0=BD=D1=8B=D0=BC=20docx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. warmup() прогоняет весь пайплайн на минимальном docx, собранном в байтах (фикстуры не задействованы), и греет Java2D/PNG-энкодер для пре-рендера диаграмм. Идемпотентен (volatile флаг), не бросает (провал — warn в JUL), артефакты отбрасываются. Ядро само себя не прогревает — момент прогрева решает приложение. Прогретая первая конвертация ru-plain.docx: 100 мс против ~1,4 с холодную. --- .../ru/pjandro/wordpdf/WordPdfConverter.java | 111 ++++++++++++++++++ .../pjandro/wordpdf/WordPdfConverterTest.java | 8 ++ 2 files changed, 119 insertions(+) diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java index fd09cbc..5dc60b3 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -11,6 +11,7 @@ import org.docx4j.convert.out.fo.renderers.FORendererApacheFOP; import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import ru.pjandro.wordpdf.fonts.BundledFontMapper; import ru.pjandro.wordpdf.fonts.BundledFonts; +import ru.pjandro.wordpdf.fonts.GlyphFont; import ru.pjandro.wordpdf.internal.chart.ChartImageHandler; import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer; import ru.pjandro.wordpdf.internal.DependencyGuard; @@ -21,13 +22,23 @@ import ru.pjandro.wordpdf.internal.OleObjectNormalizer; import ru.pjandro.wordpdf.internal.FopFallbackFonts; import ru.pjandro.wordpdf.internal.LayoutPostRenderer; +import java.awt.Graphics2D; +import java.awt.RenderingHints; +import java.awt.geom.Ellipse2D; +import java.awt.image.BufferedImage; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; +import java.io.IOException; import javax.xml.transform.Templates; import javax.xml.transform.stream.StreamSource; +import javax.imageio.ImageIO; import java.io.InputStream; import java.io.OutputStream; +import java.nio.charset.StandardCharsets; import java.util.List; +import java.util.logging.Logger; +import java.util.zip.ZipEntry; +import java.util.zip.ZipOutputStream; /** * Конвертер docx -> PDF на базе docx4j + Apache FOP @@ -155,6 +166,106 @@ public final class WordPdfConverter { return bos.toByteArray(); } + /** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */ + private static volatile boolean warmedUp; + + private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName()); + + /** + * Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с + * (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет + * пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не + * задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм. + * Идемпотентен, никогда не бросает (провал — только warn); вызывать нужно + * на том же потоке, на котором сериализованы конвертации (ядро не + * потокобезопасно, см. {@code PhysicalFonts}). Артефакты (PDF, растр) + * отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева + * решает вызывающее приложение. + */ + public static synchronized void warmup() { + if (warmedUp) { + return; + } + try { + convert(warmupDocx(), "warmup"); + warmRaster(); + warmedUp = true; + } catch (Throwable t) { + // Провал прогрева не должен валить старт приложения: в худшем + // случае первый запрос заплатит холодный путь, как платил до + // появления warmup(). + LOG.warning("Прогрев ядра не выполнен: " + t); + } + } + + /** Минимальный docx прогрева: три обязательные части, собранные в zip. */ + private static byte[] warmupDocx() throws IOException { + ByteArrayOutputStream bos = new ByteArrayOutputStream(1 << 10); + try (ZipOutputStream zip = new ZipOutputStream(bos, StandardCharsets.UTF_8)) { + putWarmupEntry(zip, "[Content_Types].xml", WARMUP_CONTENT_TYPES); + putWarmupEntry(zip, "_rels/.rels", WARMUP_ROOT_RELS); + putWarmupEntry(zip, "word/document.xml", WARMUP_DOCUMENT); + } + return bos.toByteArray(); + } + + private static void putWarmupEntry(ZipOutputStream zip, String name, String xml) + throws IOException { + zip.putNextEntry(new ZipEntry(name)); + zip.write(xml.getBytes(StandardCharsets.UTF_8)); + zip.closeEntry(); + } + + /** Маркер {@code wordprocessingml.document} — требование WordPdfValidator. */ + private static final String WARMUP_CONTENT_TYPES = """ + \ + \ + \ + \ + \ + """; + + private static final String WARMUP_ROOT_RELS = """ + \ + \ + \ + """; + + /** + * Текст ранa: алиас Calibri→Carlito прогревает маппер и embed-подмножество + * Carlito; em dash (U+2014) — обычный глиф Carlito, а fallback-путь для + * U+2000–U+2EFF декларируется {@code FopFallbackFonts.declare} на каждом + * конверте и прогревается самим прогоном. + */ + private static final String WARMUP_DOCUMENT = """ + \ + \ + \ + Warmup text with em dash — for font subsetting.\ + \ + """; + + /** + * Прогрев Java2D/PNG-энкодера: первый «чартный» документ после старта + * иначе платит ещё ~200 мс холодного растрового пути (пре-рендер + * диаграмм — raster + {@link GlyphFont}). Растер headless-безопасен, + * fontconfig не нужен (глифы — fontbox, см. javadoc {@link GlyphFont}). + */ + private static void warmRaster() throws IOException { + BufferedImage img = new BufferedImage(64, 64, BufferedImage.TYPE_INT_ARGB); + Graphics2D g = img.createGraphics(); + g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); + g.fill(new Ellipse2D.Double(4, 4, 32, 32)); + GlyphFont.of(BundledFonts.FALLBACK_FAMILY, BundledFonts.V_REGULAR) + .draw(g, "Warmup", 2, 30, 12); + g.dispose(); + ImageIO.write(img, "png", new ByteArrayOutputStream()); + } + /** * Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. Шаг 0 — проверка * совместимости commons-compress в classpath потребителя (DependencyGuard): diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java index f3810ee..01f58b0 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -533,6 +533,14 @@ class WordPdfConverterTest { assertTrue(text.contains("quick brown fox"), fixture + ": нет «quick brown fox»: " + text); } + @Test + void warmup_idempotentAndPipelineIntact() throws Exception { + WordPdfConverter.warmup(); + WordPdfConverter.warmup(); // повторный вызов — no-op, не бросает + // прогрев не сломал штатный путь: конвертация прогретым ядром + assertEnglishText("en-plain.docx"); + } + @Test void mixed_headingListTable() throws Exception { assertHeadingListTable("ru-en-mixed.docx"); -- 2.56.1 From 30aba6bb45d385848e39c0da43c96bd05253a927 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 3 Nov 2026 20:26:16 +0000 Subject: [PATCH 3/4] =?UTF-8?q?perf(app):=20=D0=BF=D1=80=D0=BE=D0=B3=D1=80?= =?UTF-8?q?=D0=B5=D0=B2=20=D1=8F=D0=B4=D1=80=D0=B0=20=D0=B3=D0=BE=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=D0=BE=D0=B9=20=D0=BE=D1=87=D0=B5=D1=80=D0=B5=D0=B4?= =?UTF-8?q?=D0=B8=20=D0=BA=D0=BE=D0=BD=D0=B2=D0=B5=D1=80=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D0=B9=20=D0=BD=D0=B0=20=D1=81=D1=82=D0=B0=D1=80=D1=82?= =?UTF-8?q?=D0=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ConversionService в конструкторе ставит WordPdfConverter.warmup() головой той же однопоточной очереди: первый реальный запрос после деплоя — за прогретым ядром (~50–300 мс вместо 1,4–1,9 с) и сериализован с конвертациями. Тесту сатурации нужен сентинел после конструктора: прогрев занимает слот воркера головой очереди. --- .../java/ru/pjandro/wordpdf/app/ConversionService.java | 7 +++++++ .../java/ru/pjandro/wordpdf/app/ConversionServiceTest.java | 5 +++++ 2 files changed, 12 insertions(+) diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java index a1a7af5..d49b7d8 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java @@ -53,6 +53,13 @@ final class ConversionService { this.timeout = timeout; this.workers = new ThreadPoolExecutor(1, 1, 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(QUEUE_CAPACITY)); + // Прогрев ядра — головой той же однопоточной очереди: первый реальный + // запрос после деплоя становится за прогретым ядром (~50–300 мс вместо + // 1,4–1,9 с) и гарантированно сериализован с конвертациями (ядро не + // потокобезопасно). warmup() не бросает — Future никто не забирает; + // запросы, пришедшие во время прогрева, ждут в очереди (штатная + // семантика, лимит convert-timeout с запасом). + this.workers.submit(WordPdfConverter::warmup); } /** diff --git a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConversionServiceTest.java b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConversionServiceTest.java index 3d5c11b..f7ec9c5 100644 --- a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConversionServiceTest.java +++ b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConversionServiceTest.java @@ -52,6 +52,11 @@ class ConversionServiceTest { void saturatedQueue_rejectsImmediately() throws Exception { ConversionService svc = new ConversionService(Duration.ofMinutes(2)); ThreadPoolExecutor workers = workersOf(svc); + // Конструктор ставит прогрев ядра головой очереди: дождаться его + // сентинельной задачей (FIFO — сентинел отработает сразу после + // прогрева), иначе прогрев занимает слот воркера и последний + // filler-блокировка не влезает в очередь. + workers.submit(() -> null).get(30, TimeUnit.SECONDS); CountDownLatch block = new CountDownLatch(1); CountDownLatch workerBusy = new CountDownLatch(1); List> fillers = new ArrayList<>(); -- 2.56.1 From 1ecaa9e9591234d7782760b5e6c8058b48daab92 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 3 Nov 2026 20:37:53 +0000 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20warmup=20+=20=D0=BE=D1=82=D0=BA?= =?UTF-8?q?=D0=BB=D1=8E=D1=87=D0=B5=D0=BD=D0=B8=D0=B5=20discovery=20=D0=B2?= =?UTF-8?q?=20=D0=B8=D0=BD=D0=B2=D0=B0=D1=80=D0=B8=D0=B0=D0=BD=D1=82=D0=B0?= =?UTF-8?q?=D1=85,=20pipeline=20=D0=B8=20=D1=81=D1=87=D1=91=D1=82=D1=87?= =?UTF-8?q?=D0=B8=D0=BA=D0=B0=D1=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - инвариант: гейт-свойства 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). --- AGENTS.md | 5 +++-- docs/agent/pipeline.md | 6 +++++- docs/agent/repo-map.md | 4 ++-- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b0ea24..d809a31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`. diff --git a/docs/agent/pipeline.md b/docs/agent/pipeline.md index 7d77c0f..3cebca9 100644 --- a/docs/agent/pipeline.md +++ b/docs/agent/pipeline.md @@ -5,7 +5,7 @@ | # | Шаг | Что делает | |---|---|---| | 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j | -| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера добавляет системные шрифты в глобальный реестр `PhysicalFonts`; `init()` вызывает `dropNonBundled()` **до** регистрации бандла (`addPhysicalFont` не перезаписывает занятый ключ — иначе системный Calibri ломает em-dash-fallback) | +| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера (static `BestMatchingMapper`) регистрирует в `PhysicalFonts` только symbol-шрифты из `docx4j-export-fo-fonts-symbol` (сканы системы и jar'ов отключены в static-блоке `WordPdfConverter` гейт-свойствами — всё найденное всё равно выбрасывает `restrictToBundled()`); `init()` вызывает `dropNonBundled()` **до** регистрации бандла, `restrictToBundled()` оставляет реестр = бандл + встроенные в docx. Порядок `init()` после конструктора — инвариант: `addPhysicalFont` не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) | |2|`DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load`|Один zip-проход переписывания XML-частей (правила 1–10 — раздел «Нормализаторы: контракт и правила 1–11» в этом файле) + условная OLE-вычистка (правило 11)| | 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF | | 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) | @@ -16,6 +16,10 @@ | 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF | | 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти | +### `warmup()` — прогрев ядра (шаги 0–7 на минимальном docx) + +Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы; замер 2026-11), её платил первый запрос после деплоя. Публичный `WordPdfConverter.warmup()` прогоняет шаги 0–7 на минимальном docx, собранном в байтах (три zip-части константами, фикстуры не задействованы; алиас Calibri→Carlito греет маппер и embed-подмножество), и греет Java2D/PNG-энкодер (`warmRaster()` — растер + `GlyphFont.draw` + `ImageIO.write`), иначе первый чартный документ платит ещё ~200 мс. Идемпотентен (`volatile warmedUp`, метод `synchronized`), никогда не бросает (провал — warn в JUL), артефакты отбрасываются; вызывать на потоке, сериализующем конвертации. Ядро само себя не зовёт: `wordpdf-app` ставит warmup головой очереди воркеров в конструкторе `ConversionService`. Прогретый первый конверт ru-plain.docx HTTP-запросом: 0,13 с против 1,74 с (A/B на одной машине, сборки ветки и `main`). + ### Валидация входа и подсчёт страниц Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись: zip `PK\x03\x04` или CFB `D0 CF 11 E0` → контейнер → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + явные разрывы)`; явные — 0x0C в основном тексте + `sprmPFPageBreakBefore` из PAPX. Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–10 число учитываемых разрывов не увеличивают (правило 9 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита). diff --git a/docs/agent/repo-map.md b/docs/agent/repo-map.md index 1544bce..b7c6cd2 100644 --- a/docs/agent/repo-map.md +++ b/docs/agent/repo-map.md @@ -82,7 +82,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`. - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда. -- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. +- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. - **Лимиты входа** задаёт только конфигурация сервера: `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**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом `/pdf-converter/`). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает `.docx,.doc` (`accept` + текст зоны). @@ -98,7 +98,7 @@ PMD: `failurePriority` в плагине не задан — на практик - Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. - Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `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`) и защитные ветви сканеров нормализаторов/валидатора. -- 57 тестовых класса / 886 теста (core 51/843 — из них 17 классов / 225 тестов в `internal/doc/`, `WordPdfConverterTest` 75 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелпер `docx(...)`; app 6/43: ConvertController 23 + 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`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`). +- 59 тестовых класса / 891 тест (core 53/848 — из них 17 классов / 225 тестов в `internal/doc/`, `WordPdfConverterTest` 77 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелпер `docx(...)`; app 6/43: ConvertController 23 + 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`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`). - Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), 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`; сборка web-образа на `node:24-alpine`. - Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …` **на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`. -- 2.56.1