docs: полная синхронизация документации с кодом
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 59s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m30s
Main: tests, deploy, autotests / autotests (push) Successful in 41s
Main: tests, deploy, autotests / rollback (push) Has been skipped
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 59s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m30s
Main: tests, deploy, autotests / autotests (push) Successful in 41s
Main: tests, deploy, autotests / rollback (push) Has been skipped
README: X-API-Key/401, полная таблица статусов, gateway-топология :9010/:9011, лимиты 100 МБ multipart и конфигурируемые wordpdf.max-mb/max-pages, пайплайн из 7 правил DocxRewritePipeline + OLE, ConvertOptions/WordPdfValidator, секция CI/CD. AGENTS.md: заголовок диаграммы по ECMA (autoTitleDeleted, §21.2.2.7), потолок растра MAX_PIXELS/fitDpi, стриминговый checkPageCount, 535 @Test (core 493), регрессии ChartSpecTest, сноска «README устарел» удалена. GITEA-vars.md: падающие job'ы — images-app/images-web первыми. wordpdf-web: охват vite-прокси, комментарий VITE_BASE (печёт CI-job images-web).
This commit was merged in pull request #67.
This commit is contained in:
@@ -10,7 +10,7 @@
|
|||||||
- `wordpdf-app` — REST API (Spring Boot 4.1.1), единственный `public`-класс — `WordPdfApplication`.
|
- `wordpdf-app` — REST API (Spring Boot 4.1.1), единственный `public`-класс — `WordPdfApplication`.
|
||||||
- `wordpdf-web` — SPA (React 19 + TS + Vite + Tailwind), собирается npm, деплоится отдельно от Maven.
|
- `wordpdf-web` — SPA (React 19 + TS + Vite + Tailwind), собирается npm, деплоится отдельно от Maven.
|
||||||
|
|
||||||
Вход стека — gateway-контейнер nginx (`:9010` prod-like compose / `:9011` dev), **не** 8080. README.md устарел (порты/топология, «413 6 МБ» — фактически 100 МБ, нет API-ключа, лимиты подаёт как константы — они конфигурируемы); авторитетны этот файл и код.
|
Вход стека — gateway-контейнер nginx (`:9010` prod-like compose / `:9011` dev), **не** 8080. Авторитетны этот файл и код.
|
||||||
|
|
||||||
## Architecture & Data Flow
|
## Architecture & Data Flow
|
||||||
|
|
||||||
@@ -73,7 +73,7 @@
|
|||||||
|
|
||||||
Нормативный источник любых правок — ECMA-376 (`docs/standards/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD `schema/strict/`/`schema/transitional/`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).
|
Нормативный источник любых правок — ECMA-376 (`docs/standards/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD `schema/strict/`/`schema/transitional/`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).
|
||||||
|
|
||||||
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры в пунктах, EMU→pt `cx/12700.0`). `ChartSpec.parse` (`enum Type`: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). Пустой `c:title` + `autoTitleDeleted="0"` → у **круговых** имя первого ряда, у прочих — `ChartSpec.AUTO_TITLE = "Название диаграммы"`. Палитра `accent1..6` темы; легенда по умолчанию снизу; `overlay` (§21.2.2.132) рисуется поверх области построения, место не резервирует.
|
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры в пунктах, EMU→pt `cx/12700.0`). Потолок растра `ChartRenderer.MAX_PIXELS = 16_777_216` (4096², 64 МБ ARGB): при превышении `fitDpi` uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); `SmartArtRenderer` использует тот же `DPI`/`fitDpi`. `ChartSpec.parse` (`enum Type`: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). `c:autoTitleDeleted=true` (в т.ч. при опущенном `c:val` — default true) скрывает заголовок целиком, включая явный `c:tx` (§21.2.2.7). Пустой `c:title` + `autoTitleDeleted="0"` — автозаголовок Word: круговая (PIE/PIE3D/DOUGHNUT/OF_PIE) с **одним** рядом → имя ряда, иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#deletedTitleWithText_notShown`, `#deletedTitleValOmitted_notShown`, `#multiSeriesDoughnut_placeholderNotSeriesName`, `#multiParagraphTitle_joinedWithNewlines`. Палитра `accent1..6` темы; легенда по умолчанию снизу; `overlay` (§21.2.2.132) рисуется поверх области построения, место не резервирует.
|
||||||
|
|
||||||
Пейнтеры: `CartesianPainter` (2-D line/bar/area; `c:grouping` stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через `ChartRenderer.stackedCumulative`), `PiePainter` (`PIE_DEPTH = 0.22`, `PIE_FIT = 0.865`), `Surface3dPainter` (камера — регрессия `cameraMatchesWordReference`: `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, `GUTTER_LEFT/RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`, свет `LIGHT_X/Y/Z = 0.83/0.48/0.28`; `c:rAngAx=true` приоритетнее `c:perspective` (MS-OI29500 §2.1.1516(b)); `c:wireframe` §21.2.2.205 — только каркас), `ScatterPainter` (радиус пузыря sqrt при `c:sizeRepresents="area"` §21.2.2.128), `RadarPainter` (спицы от 12 часов), `StockPainter` (upDownBars обводятся контуром, дефолт чёрный 0.75pt), `OfPiePainter` (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), `Surface2dPainter` (контурная карта §21.2.2.204, marching squares, изолинии по `c:bandFmts` §21.2.2.13/.14), `Cartesian3dPainter` (bar3D/line3D/area3D §21.2.2.19/.101/.122, `c:shape` §21.2.3.44), `SmartArtRenderer` (кэш `word/diagrams/drawing1.xml` через relationship `…/office/2007/relationships/diagramDrawing`; формы — `PresetGeometry` из `a:prstGeom`, семь пресетов дословно из `presetShapeDefinitions.xml`; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, **не** x != 0); углы в Arc2D — со знаком минус; текст — `DrawMlText`, шрифты через `BundledFontMapper.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
|
Пейнтеры: `CartesianPainter` (2-D line/bar/area; `c:grouping` stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через `ChartRenderer.stackedCumulative`), `PiePainter` (`PIE_DEPTH = 0.22`, `PIE_FIT = 0.865`), `Surface3dPainter` (камера — регрессия `cameraMatchesWordReference`: `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, `GUTTER_LEFT/RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`, свет `LIGHT_X/Y/Z = 0.83/0.48/0.28`; `c:rAngAx=true` приоритетнее `c:perspective` (MS-OI29500 §2.1.1516(b)); `c:wireframe` §21.2.2.205 — только каркас), `ScatterPainter` (радиус пузыря sqrt при `c:sizeRepresents="area"` §21.2.2.128), `RadarPainter` (спицы от 12 часов), `StockPainter` (upDownBars обводятся контуром, дефолт чёрный 0.75pt), `OfPiePainter` (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), `Surface2dPainter` (контурная карта §21.2.2.204, marching squares, изолинии по `c:bandFmts` §21.2.2.13/.14), `Cartesian3dPainter` (bar3D/line3D/area3D §21.2.2.19/.101/.122, `c:shape` §21.2.3.44), `SmartArtRenderer` (кэш `word/diagrams/drawing1.xml` через relationship `…/office/2007/relationships/diagramDrawing`; формы — `PresetGeometry` из `a:prstGeom`, семь пресетов дословно из `presetShapeDefinitions.xml`; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, **не** x != 0); углы в Arc2D — со знаком минус; текст — `DrawMlText`, шрифты через `BundledFontMapper.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
|
||||||
|
|
||||||
@@ -88,7 +88,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|
|||||||
- 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`.
|
- 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`.
|
||||||
- Порядок инициализации шрифтов: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — **до** `load()`. `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF во временный каталог `wordpdf-fonts-*` (`deleteOnExit` на файлы и на каталог). `dropNonBundled()` чистит глобальный реестр `PhysicalFonts` от всего, что вне бандла.
|
- Порядок инициализации шрифтов: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — **до** `load()`. `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF во временный каталог `wordpdf-fonts-*` (`deleteOnExit` на файлы и на каталог). `dropNonBundled()` чистит глобальный реестр `PhysicalFonts` от всего, что вне бандла.
|
||||||
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.
|
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.
|
||||||
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `w:sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; `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 молчит — подпись проверяет вызывающий.
|
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `w:sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; `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 молчит — подпись проверяет вызывающий. `checkPageCount` — один стриминговый проход `ZipInputStream` без буферизации частей (хелпер `noClose` глушит `close()` сканеров): потребление O(одной части) вместо O(суммы XML-частей).
|
||||||
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
||||||
- Внимание: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
|
- Внимание: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
|
||||||
|
|
||||||
@@ -198,12 +198,12 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
|
|||||||
|
|
||||||
- Гейт `maven-pmd-plugin` 3.28.0 на `verify` для обоих модулей, ruleset `pmd-ruleset.xml`, `includeTests=true`. Версия PMD-движка в pom не пинится (тянется плагином).
|
- Гейт `maven-pmd-plugin` 3.28.0 на `verify` для обоих модулей, ruleset `pmd-ruleset.xml`, `includeTests=true`. Версия PMD-движка в pom не пинится (тянется плагином).
|
||||||
- Гейт 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`) и защитные ветви сканеров нормализаторов/валидатора.
|
- Гейт 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`) и защитные ветви сканеров нормализаторов/валидатора.
|
||||||
- 35 тестовых классов / 531 `@Test` (core 29/489, 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`; только `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`).
|
- 35 тестовых классов / 535 `@Test` (core 29/493, 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`; только `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`).
|
||||||
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
|
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `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. Хелперы chart-тестов (`render`, `countColor`, `assertRatio`, `paint`) продублированы по классам — общего test-util нет.
|
- Пиксели (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. Хелперы chart-тестов (`render`, `countColor`, `assertRatio`, `paint`) продублированы по классам — общего test-util нет.
|
||||||
- `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.
|
- `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` (кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`).
|
- Фикстуры — закоммиченные `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` (кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`).
|
||||||
- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). Исключение — `OleObjectNormalizerTest`: многочастный нормализатор без `rewrite`-хука, тесты только через `normalize` на in-memory zip.
|
- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame`) и неприкосновенность частей вне `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`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста).
|
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest`/`ConversionTimeoutTest` (`@TestPropertySource` — отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста).
|
||||||
- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight`; юниты `indCoexistLeftStartUntouched`/`tcMarCoexistKept`/`tcBordersElementsKeptTransitional`/`jcStartKeptTransitional`/`tabStartRenamedTransitional`/`transitionalCoexistReturnsOriginalArray`), `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`; юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero`, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`/`validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `PresetGeometryTest`↔`chartsSmartArt_drawingsBecomeImages` (`tableMatchesEcmaXml`), chart-пейнтеры↔`chartTypes_allTypesRenderAsImages`, `ChartSpecTest`↔автозаголовки/комбо/DoS (`hugePointIndex_rejectedNotOom`, `hugePtCount_rejectedNotOom`, `hugeCategoryIndex_rejectedNotOom`, `nonFiniteScalingBounds_dropped`, `overlayLegend_keepsPositionAndFlag`), `Surface3dPainterTest`↔`axisBounds_tinyMajorUnit_fallsBackToNiceUnit`/`axisBounds_zeroMajorUnit_fallsBackToNiceUnit`, `ChartRendererTest`↔`axisBounds_explicitHugeRange_reunitsToMaxTicks`/`axisBounds_infiniteSpan_fallsBackToData`/`stackedCumulative_*`/`stackedRange_coversNegativeSums`/`overlayLegend_drawnOverPlot`/`wireframeSurfaceLegend_hollowMarkers`, `DrawMlTextTest`↔`hugeWord_wrapsLinearly`/`fallbackFamilyAliasedToBundle`/`lineSpacingPct_compactsLines`, `DrawMlColorTest`↔`invalidSrgbHexFallsBackToOfficeDefault`, `SmartArtRendererTest`↔`normAutofitShrinksToFit`/`missingAutofitKeepsDeclaredSize`/`emptyTxBody_noPlaceholderInk`, `CartesianPainterTest`↔`stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`/`areaFill_closesToBaseline`/`combo_barsAndLineOnSecondary_bothDrawn`, `GlyphCoverageNormalizerTest`↔`multipleTextNodes_runLeftUntouched`/`nestedRunInTextBox_innerSplit`, `SymbolFontNormalizerTest`↔`nestedRunInTextBox_innerNormalized`, `WordPdfConverterTest`↔`noLoggingWarningInPdf`/`pdfTitle_comesFromParameter`/`hostileChartAxis_convertsNotHangs`/`hugeExtentChart_removedNotOom`/`chartWithoutExtent_errorFlagRejects`. App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
|
- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight`; юниты `indCoexistLeftStartUntouched`/`tcMarCoexistKept`/`tcBordersElementsKeptTransitional`/`jcStartKeptTransitional`/`tabStartRenamedTransitional`/`transitionalCoexistReturnsOriginalArray`), `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`; юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero`, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`/`validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `PresetGeometryTest`↔`chartsSmartArt_drawingsBecomeImages` (`tableMatchesEcmaXml`), chart-пейнтеры↔`chartTypes_allTypesRenderAsImages`, `ChartSpecTest`↔автозаголовки/комбо/DoS (`hugePointIndex_rejectedNotOom`, `hugePtCount_rejectedNotOom`, `hugeCategoryIndex_rejectedNotOom`, `nonFiniteScalingBounds_dropped`, `overlayLegend_keepsPositionAndFlag`, `deletedTitleWithText_notShown`, `deletedTitleValOmitted_notShown`, `multiSeriesDoughnut_placeholderNotSeriesName`, `multiParagraphTitle_joinedWithNewlines`), `Surface3dPainterTest`↔`axisBounds_tinyMajorUnit_fallsBackToNiceUnit`/`axisBounds_zeroMajorUnit_fallsBackToNiceUnit`, `ChartRendererTest`↔`axisBounds_explicitHugeRange_reunitsToMaxTicks`/`axisBounds_infiniteSpan_fallsBackToData`/`stackedCumulative_*`/`stackedRange_coversNegativeSums`/`overlayLegend_drawnOverPlot`/`wireframeSurfaceLegend_hollowMarkers`, `DrawMlTextTest`↔`hugeWord_wrapsLinearly`/`fallbackFamilyAliasedToBundle`/`lineSpacingPct_compactsLines`, `DrawMlColorTest`↔`invalidSrgbHexFallsBackToOfficeDefault`, `SmartArtRendererTest`↔`normAutofitShrinksToFit`/`missingAutofitKeepsDeclaredSize`/`emptyTxBody_noPlaceholderInk`, `CartesianPainterTest`↔`stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`/`areaFill_closesToBaseline`/`combo_barsAndLineOnSecondary_bothDrawn`, `GlyphCoverageNormalizerTest`↔`multipleTextNodes_runLeftUntouched`/`nestedRunInTextBox_innerSplit`, `SymbolFontNormalizerTest`↔`nestedRunInTextBox_innerNormalized`, `WordPdfConverterTest`↔`noLoggingWarningInPdf`/`pdfTitle_comesFromParameter`/`hostileChartAxis_convertsNotHangs`/`hugeExtentChart_removedNotOom`/`chartWithoutExtent_errorFlagRejects`. App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
|
||||||
- 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 против живого прода.
|
- 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 против живого прода.
|
||||||
|
|||||||
+1
-1
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
Секреты, переменные и защиту ветки заводит **владелец репо** в Web UI — у CI-токена прав
|
Секреты, переменные и защиту ветки заводит **владелец репо** в Web UI — у CI-токена прав
|
||||||
admin нет. Workflow-файлы уже в репо; прогоны main-пайплайна без Variables/Secrets падают на
|
admin нет. Workflow-файлы уже в репо; прогоны main-пайплайна без Variables/Secrets падают на
|
||||||
job'ах `deploy`/`autotests` с внятным сообщением, чего не хватает, — это ожидаемо. После
|
job'ах `images-app`/`images-web` (проверка `REGISTRY`/`REGISTRY_USER`/`REGISTRY_PASSWORD`), `deploy`/`autotests` с внятным сообщением, чего не хватает, — это ожидаемо. После
|
||||||
заполнения перезапустите упавший run («Re-run jobs» на странице run'а) или запустите
|
заполнения перезапустите упавший run («Re-run jobs» на странице run'а) или запустите
|
||||||
`Main: tests, deploy, autotests` вручную (Actions → Run workflow, branch `main`).
|
`Main: tests, deploy, autotests` вручную (Actions → Run workflow, branch `main`).
|
||||||
|
|
||||||
|
|||||||
@@ -11,6 +11,8 @@ LibreOffice/Aspose. Шрифты упакованы в jar — конверта
|
|||||||
в docx4j/FOP.
|
в docx4j/FOP.
|
||||||
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
||||||
(см. «Шрифты» ниже).
|
(см. «Шрифты» ниже).
|
||||||
|
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
||||||
|
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
||||||
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
||||||
и веб-интерфейс (`wordpdf-web`, React SPA).
|
и веб-интерфейс (`wordpdf-web`, React SPA).
|
||||||
|
|
||||||
@@ -27,12 +29,15 @@ java-word-pdf/
|
|||||||
|
|
||||||
|Класс|Назначение|
|
|Класс|Назначение|
|
||||||
|---|---|
|
|---|---|
|
||||||
| `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(byte[], String)` — байты на входе, байты PDF на выходе |
|
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — байты на входе, байты PDF на выходе|
|
||||||
| `ru.pjandro.wordpdf.ConversionException` | исключение конвертации |
|
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц по zip без рендера (`checkInput`/`checkPageCount`/`validate`)|
|
||||||
|
|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`; `ConvertOptions.defaults()`)|
|
||||||
|
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
||||||
| `ru.pjandro.wordpdf.internal.DocxOnOffNormalizer` | нормализация `w:val="off"/"on"` перед загрузкой |
|
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|семь правил нормализации XML-частей одним zip-проходом|
|
||||||
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|
||||||
|
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
|
||||||
|
|
||||||
## Инструменты проекта (mise)
|
## Инструменты проекта (mise)
|
||||||
|
|
||||||
@@ -77,10 +82,10 @@ powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
|||||||
|
|
||||||
## Сборка
|
## Сборка
|
||||||
|
|
||||||
Требуется **Java 17** и **Maven** (бэкенд), **Node.js ≥ 20.19** (веб-интерфейс) — всё
|
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
|
||||||
это ставит project-local mise (см. «Инструменты проекта (mise)» выше). Команды ниже
|
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
|
||||||
запускайте через `./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после
|
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
|
||||||
активации mise в шелле.
|
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mvn clean verify # все модули + тесты
|
mvn clean verify # все модули + тесты
|
||||||
@@ -97,38 +102,67 @@ mvn -pl wordpdf-app -am package # исполняемый jar бэкенд
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||||
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
||||||
|
http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
```
|
```
|
||||||
|
|
||||||
`POST /api/v1/convert` принимает multipart-поле `file` (.docx) и синхронно
|
`POST /api/v1/convert` принимает multipart-поле `file` (.docx) и синхронно
|
||||||
возвращает байты PDF (`application/pdf`, attachment).
|
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
||||||
|
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
||||||
|
|
||||||
|
**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key`
|
||||||
|
(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`,
|
||||||
|
dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа
|
||||||
|
или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`.
|
||||||
|
|
||||||
|
**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle`
|
||||||
|
(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют
|
||||||
|
конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты
|
||||||
|
при `errorOnOle=false` тихо удаляются.
|
||||||
|
|
||||||
|
**Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages`
|
||||||
|
(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц); параметрами
|
||||||
|
запроса не переопределяются.
|
||||||
|
|
||||||
|Код|Смысл|
|
|Код|Смысл|
|
||||||
|---|---|
|
|---|---|
|
||||||
|200|PDF в теле ответа|
|
|200|PDF в теле ответа|
|
||||||
|400|некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц|
|
|400|некорректный вход (не .docx / пустой / не zip / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|
||||||
|413|тело запроса больше контейнерного лимита multipart (6 МБ)|
|
|401|нет или неверен `X-API-Key`|
|
||||||
|503|очередь конвертации занята — повторить позже|
|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||||
|504|конвертация дольше таймаута (`wordpdf.convert-timeout`, по умолчанию 2m)|
|
|405|не-POST|
|
||||||
|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
||||||
|
|415|не-multipart тело|
|
||||||
|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
||||||
|
|500|ошибка ядра/рендера|
|
||||||
|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
||||||
|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||||
|
|
||||||
Ошибки — JSON `{"error": "..."}`. Интерактивная документация:
|
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
|
||||||
Swagger UI — `/swagger-ui.html`, OpenAPI — `/v3/api-docs`.
|
мутирует глобальный реестр шрифтов. Интерактивная документация: Swagger UI —
|
||||||
|
`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде;
|
||||||
|
в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`,
|
||||||
|
`SPRINGDOC_SWAGGER_UI_ENABLED=false`).
|
||||||
|
|
||||||
### Библиотека
|
### Библиотека
|
||||||
|
|
||||||
```java
|
```java
|
||||||
import ru.pjandro.wordpdf.WordPdfConverter;
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
|
import ru.pjandro.wordpdf.ConvertOptions;
|
||||||
import java.nio.file.Files;
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
|
|
||||||
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
||||||
byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF
|
byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF
|
||||||
|
// с опциями: errorOnCharts/errorOnSmartArt/errorOnOle, лимиты МБ/страниц
|
||||||
|
pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, false, 5, 100));
|
||||||
Files.write(Path.of("out.pdf"), pdf);
|
Files.write(Path.of("out.pdf"), pdf);
|
||||||
```
|
```
|
||||||
|
|
||||||
Ошибки валидации (не `.docx` по содержимому, размер больше 5 МБ, страниц
|
Ошибки валидации (не `.docx` по содержимому, размер больше 5 МБ, страниц
|
||||||
больше ста) бросают `ConversionException`. Работа с файлами — забота
|
больше ста) бросают `ValidationException` (подтип `ConversionException`). Те же
|
||||||
вызывающего: ядро пути не принимает.
|
проверки без рендера доступны отдельно: `WordPdfValidator.validate(bytes, options)`.
|
||||||
|
Работа с файлами — забота вызывающего: ядро пути не принимает.
|
||||||
|
|
||||||
#### Зависимость commons-compress (интеграция в чужой проект)
|
#### Зависимость commons-compress (интеграция в чужой проект)
|
||||||
|
|
||||||
@@ -177,16 +211,25 @@ dependencies {
|
|||||||
### Веб-интерфейс и контейнеры (podman)
|
### Веб-интерфейс и контейнеры (podman)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||||
podman-compose up -d --build
|
podman-compose up -d --build
|
||||||
```
|
```
|
||||||
|
|
||||||
Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует
|
Наружный вход — nginx-контейнер `gateway` на `http://localhost:9010/` (контейнер
|
||||||
`/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не
|
`app` наружу не публикуется). Файл `compose.yml` fail-closed: без `WORDPDF_API_KEY`
|
||||||
публикуется).
|
в `.env` стек не поднимется. Маршруты gateway: `/api/`, `/swagger-ui`,
|
||||||
|
`/v3/api-docs`, `/actuator` → `app:8080` (таймауты прокси 300s,
|
||||||
|
`client_max_body_size 100m`), остальное → `web` — чистая статика SPA.
|
||||||
|
|
||||||
|
Dev-стенд без ключа, с включённым springdoc:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
podman-compose -f compose.dev.yml up -d --build # http://<LAN-IP>:9011
|
||||||
|
```
|
||||||
|
|
||||||
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
|
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
|
||||||
(порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
||||||
(Vite проксирует `/api` на 8080, CORS не нужен).
|
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
|
||||||
|
|
||||||
## Шрифты
|
## Шрифты
|
||||||
|
|
||||||
@@ -225,20 +268,24 @@ Dev-режим без контейнеров: бэкенд `java -jar wordpdf-ap
|
|||||||
## Как это работает
|
## Как это работает
|
||||||
|
|
||||||
```
|
```
|
||||||
docx ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
docx ──> валидация входа ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||||
──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
──> диаграммы → PNG ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Байты `.docx` нормализуются, пока docx4j не увидел документ:
|
1. Вход проверяется до рендера: размер → zip-подпись → контейнер → число страниц
|
||||||
`DocxOnOffNormalizer` (docx4j теряет `w:val="off"/"on"` при JAXB-разборе,
|
(`WordPdfValidator`, lightweight StAX-оценка по zip без зависимости от docx4j).
|
||||||
из-за чего regular-раны могли рендериться жирным курсивом),
|
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — семь правил:
|
||||||
`SymbolFontNormalizer` (маркеры из Symbol/Wingdings вместо «#») и
|
strict→transitional (`w:start`/`w:end`, проценты), `on/off` → `true/false`
|
||||||
`FieldNormalizer` (поля `PAGE`/`NUMPAGES` пересчитываются, а не печатают
|
(иначе docx4j теряет значение, и regular-раны рендерились жирным курсивом),
|
||||||
кэш из docx) и `GlyphCoverageNormalizer` (раны со знаками вне их шрифта).
|
маркеры Symbol/Wingdings → Unicode (вместо «#»), поля `PAGE`/`NUMPAGES` →
|
||||||
2. Документ загружается в `WordprocessingMLPackage`, привязывается
|
`w:fldSimple` (пересчитываются, а не печатают кэш из docx), невидимые символы,
|
||||||
`BundledFontMapper`, диаграммы и SmartArt предварительно растеризуются
|
раны со знаками вне их шрифта. Затем вычищаются OLE-объекты
|
||||||
в PNG (`DrawingPreRenderer`).
|
(`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
|
||||||
3. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
|
3. Документ загружается в `WordprocessingMLPackage`, привязывается
|
||||||
|
`BundledFontMapper`.
|
||||||
|
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
|
||||||
|
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
||||||
|
5. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
|
||||||
рендерит PDF, встраивая используемые подмножества шрифтов.
|
рендерит PDF, встраивая используемые подмножества шрифтов.
|
||||||
|
|
||||||
## Ограничения
|
## Ограничения
|
||||||
@@ -255,9 +302,24 @@ docx ──> нормализация байтов ──> docx4j (Wordprocessin
|
|||||||
|
|
||||||
## Тесты
|
## Тесты
|
||||||
|
|
||||||
Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/`
|
Тесты используют 13 закоммиченных `.docx`-фикстур из
|
||||||
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
|
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
|
||||||
шрифтов. Запуск: `mvn test`.
|
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
|
||||||
|
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
|
||||||
|
`./mise.sh run verify` (тесты + PMD + JaCoCo).
|
||||||
|
|
||||||
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
|
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
|
||||||
на тех же фикстурах — ядро отдаёт их test-jar'ом.
|
на тех же фикстурах — ядро отдаёт их test-jar'ом.
|
||||||
|
|
||||||
|
## CI/CD и деплой
|
||||||
|
|
||||||
|
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
|
||||||
|
- Push в `main` → `main.yml`: тесты → сборка и push образов `wordpdf-app`/`wordpdf-web` в реестр → deploy (job рендерит прод-конфиги, `podman-compose pull && up -d --force-recreate`, health-гейты, автооткат при провале) → prod-автотесты против живого стенда.
|
||||||
|
- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx.
|
||||||
|
- Локальный прогон prod-автотестов (из `prod-autotests/`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> mise exec -- python -m pytest -q .
|
||||||
|
```
|
||||||
|
|
||||||
|
21 проверка; без ключа 17 требующих его пропускаются.
|
||||||
|
|||||||
@@ -10,7 +10,8 @@ COPY package.json package-lock.json ./
|
|||||||
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= ALL_PROXY= all_proxy= npm ci
|
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= ALL_PROXY= all_proxy= npm ci
|
||||||
COPY . .
|
COPY . .
|
||||||
# base для сборки SPA под префиксом: прод pjandro.ru — /pdf-converter/
|
# base для сборки SPA под префиксом: прод pjandro.ru — /pdf-converter/
|
||||||
# (compose прод-запуска передаёт arg); дефолт '/' — standalone
|
# (arg передаёт CI-job `images-web` в .gitea/workflows/main.yml при печи образа;
|
||||||
|
# compose-файлы репо образ не собирают с этим arg); дефолт '/' — standalone
|
||||||
ARG VITE_BASE=/
|
ARG VITE_BASE=/
|
||||||
ENV VITE_BASE=${VITE_BASE}
|
ENV VITE_BASE=${VITE_BASE}
|
||||||
RUN npm run build
|
RUN npm run build
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ SPA-фронт конвертера Word → PDF: React 19 + TypeScript + Vite +
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
npm install
|
||||||
npm run dev # http://localhost:5173, /api проксируется на :8080
|
npm run dev # http://localhost:5173, /api, /swagger-ui, /v3/api-docs проксируются на :8080
|
||||||
```
|
```
|
||||||
|
|
||||||
Бэкенд для dev: `java -jar ../wordpdf-app/target/wordpdf-app-1.0.0.jar`.
|
Бэкенд для dev: `java -jar ../wordpdf-app/target/wordpdf-app-1.0.0.jar`.
|
||||||
|
|||||||
Reference in New Issue
Block a user