Compare commits

..

37 Commits

Author SHA1 Message Date
Pjandro e7005eb918 fix(core): m-2 докрыт — переполнение maxMb на .doc-пути, правки AGENTS.md
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 2m50s
PR checks / macos-sim (pull_request) Successful in 5m8s
- WordPdfValidator.checkInput — multiplyExact и для порога растра maxMb×5_000_000: экстремальный maxMb на бинарном .doc (миновал бюджеты checkDocxContainer) давал сырой ArithmeticException на границе convert вместо ValidationException/400; регрессии checkInput_rasterCoefficientOverflow_rejected, validate_docExtremeMaxMb_rejectedNotArithmetic (фикстура too-many-pages.doc)
- AGENTS.md: убран устаревший маркер дрейфа «порядок в javadoc WordPdfConverter.normalizers устарел» (javadoc приведён к фактическому порядку в этом PR); счётчики 1023/975
2026-11-23 00:12:42 +03:00
Pjandro 7016df5434 fix(core): находки ревью — капа глубины OMML, арифметика лимитов, тесты деградаций, доки
PR checks / web (pull_request) Successful in 9s
PR checks / macos-sim (pull_request) Successful in 1m44s
PR checks / java (pull_request) Successful in 3m31s
- M-2: MathModel — капа вложенности OMML MAX_DEPTH=64 (deeper() в MathCtx) + капа flatten MAX_TEXT_DEPTH; WordPdfConverter.convert — catch StackOverflowError; регрессии MathModelTest#deepNesting_*, WordPdfConverterTest#ommlDeepNesting_flattenedToText
- m-2: WordPdfValidator — multiplyExact для maxBytes/max* бюджетов, переполнение maxMb -> ValidationException (400)
- m-9: ChartSpec.parseDouble — non-finite (NaN/Infinity) -> null, как не-число
- M-1: DrawingPreRendererTest — 7 тестов деградаций run(): битая chart-часть, отказ рендера, wp:anchor, бюджет math-PNG, w:br в m:r, пустая формула, oMathPara jc=center
- m-7: тесты null-options (convert/validate) и краёв JPEG rasterArea
- m-3: удалены мёртвые normalize() у FieldNormalizer/GlyphCoverageNormalizer (конвейер использует rewrite)
- I-4: DocxRewritePipeline/OleObjectNormalizer — try-with-resources на in-memory zip-потоках
- I-5: OfficeArt (DIB) и Styles (STSH) — warn в молчаливых деградациях моста
- m-1/m-4/m-5/m-8/m-10/I-6: нумерация правил 1-11 в javadoc/xslt, Регрессия-ссылки (сироты исправлены), MS-OI29500 §2.1.44, ToggleOperand 0x80/0x81 §2.9.327, карта pieces §2.9.73, счётчики 1021 тест
2026-11-23 00:06:49 +03:00
Pjandro b558fe1c30 docs: README — короткая точка входа, AGENTS — строка docs-*
PR checks / web (pull_request) Successful in 10s
PR checks / java (pull_request) Successful in 5m51s
PR checks / macos-sim (pull_request) Successful in 7m8s
Main: tests, deploy, autotests / web (push) Successful in 8s
Main: tests, deploy, autotests / java (push) Successful in 1m28s
Main: tests, deploy, autotests / images-web (push) Successful in 1m22s
Main: tests, deploy, autotests / images-app (push) Failing after 50s
Main: tests, deploy, autotests / deploy (push) Has been skipped
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Has been skipped
- README сокращён: human-контент перенесён на сайт документации;
  остались структура, бутстрап, команды, задачи mise, ссылки на документацию.
- AGENTS.md: команды docs-* в Development Commands.
2026-11-22 21:39:08 +03:00
Pjandro 187938c4db build: mise-задачи docs-* и gitignore сайта
- docs-install/docs-serve/docs-build/docs-javadoc/docs-deploy;
  публикация: javadoc → strict-build → rsync в ~/srv/wordpdf-docs (:9012).
- gitignore: site/, docs/.venv/, docs/apidocs/.
2026-11-22 21:39:08 +03:00
Pjandro 0e9266450c build: maven-javadoc-plugin для публичного API core
- Корневой pom: версия 3.12.0 + pluginManagement (outputDirectory закреплён
  на target/site, цель — только javadoc:javadoc, лайфцикл verify не меняется).
- wordpdf-core объявляет плагин без executions; wordpdf-app javadoc не генерирует.
- Правки javadoc-комментарий по ошибкам doclint: {@code <=} в ChartImageHandler,
  полные имена {@link ru.pjandro.wordpdf.ConversionException} в DocToDocx.
2026-11-22 21:39:08 +03:00
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00
Pjandro ae7c8b755a docs: обновить AGENTS.md по итогам обхода репозитория
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 3m23s
Main: tests, deploy, autotests / java (push) Successful in 11s
PR checks / macos-sim (pull_request) Successful in 6m45s
Main: tests, deploy, autotests / web (push) Successful in 11s
Main: tests, deploy, autotests / images-web (push) Successful in 16s
Main: tests, deploy, autotests / images-app (push) Successful in 4m22s
Main: tests, deploy, autotests / deploy (push) Successful in 1m55s
Main: tests, deploy, autotests / autotests (push) Successful in 20s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- internal/doc: 18 top-level классов; CHART_MEDIA_URI_PREFIX принадлежит DrawingPreRenderer
- required-контексты защиты main — java/web (GITEA-vars.md); macos-sim — PR-only, не гейт
- счётчики тестов 63 класса / 1005 (core 957); javadoc normalizers врёт про позицию MathFallback
- .env fail-closed для prod-like стенда; app-run; jeuclid/commons-logging exclusions;
  -Djacoco.skip=true; OLE-плейсхолдер; VITE_BASE-bake в images-web; Hamcrest inline-квалификация
2026-11-21 04:53:42 +03:00
Pjandro fca253b9f5 ci: job macos-sim — тесты под эмуляцией macOS (-Dos.name) на PR
PR checks / web (pull_request) Successful in 10s
PR checks / macos-sim (pull_request) Successful in 1m12s
Main: tests, deploy, autotests / web (push) Successful in 9s
Main: tests, deploy, autotests / images-web (push) Successful in 11s
Main: tests, deploy, autotests / java (push) Successful in 46s
PR checks / java (pull_request) Successful in 5m12s
Main: tests, deploy, autotests / images-app (push) Successful in 23s
Main: tests, deploy, autotests / deploy (push) Successful in 1m58s
Main: tests, deploy, autotests / autotests (push) Successful in 1m16s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Containerfile.test получает ARG SUREFIRE_OS_NAME (пусто — прежнее
поведение), pr.yml — job macos-sim: тот же mvn clean verify с
-Dos.name='Mac OS X' (docx4j PhysicalFonts читает os.name и уходит в
MicrosoftFontsRegistry). Регрессия strictOoxml ловится до мержа.
Документация: AGENTS.md, docs/agent/ci-cd.md.
2026-11-21 03:43:44 +03:00
Pjandro e308db47da fix(fonts): реальные начертания бандла в getBoldForm/getItalicForm/getBoldItalicForm
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 3m57s
Main: tests, deploy, autotests / web (push) Successful in 8s
Main: tests, deploy, autotests / java (push) Successful in 1m16s
Main: tests, deploy, autotests / images-web (push) Successful in 1m22s
Main: tests, deploy, autotests / images-app (push) Successful in 20s
Main: tests, deploy, autotests / deploy (push) Successful in 2m8s
Main: tests, deploy, autotests / autotests (push) Successful in 14s
Main: tests, deploy, autotests / rollback (push) Has been skipped
На macOS PhysicalFonts.getBoldForm для имён бандл-шрифтов ('Tinos Regular',
'Carlito Regular', ...) уходит в MicrosoftFontsRegistry, где у этих записей
Mac-имя файла null, и возвращает null; docx4j строит simulate-style fopconf
(все начертания на regular-TTF), FOP теряет реальные Bold/Italic — метрики и
кернинг ломают переносы (strictOoxml: 'таблица' -> 'таблиц а').

BundledFontMapper переопределяет три variant-form метода: семейство опознаётся
по embeddedURI regular-варианта, начертание берётся реальным из бандла; вне
бандла / без init() — родительская логика без изменений.

Тест: BundledFontMapperTest#variantForms_resolveBundleSibling (красный на macOS
без override); регрессии: WordPdfConverterTest#strictOoxml_convertsNotRejected,
#ruPlain_regularRunsUseRegularFont (проверены под -Dos.name='Mac OS X').
docs/agent/pipeline.md: абзац о macOS-ветке.
2026-11-21 03:06:39 +03:00
Pjandro f3ff218686 feat(core): собственный рендер OMML→PNG и полный FOP-конфиг шрифтов
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 5m26s
Main: tests, deploy, autotests / web (push) Successful in 9s
Main: tests, deploy, autotests / images-web (push) Successful in 23s
Main: tests, deploy, autotests / java (push) Successful in 1m30s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Successful in 2m13s
Main: tests, deploy, autotests / autotests (push) Successful in 17s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Замена JEuclid/AWT-ветки формул на детерминированный растер только
бандл-шрифтами jar (без fontconfig); FOP-конфиг дополняется всеми
бандл-начертаниями при каждом declare — иначе общая FopFactory
замораживает fopconf первого документа и теряет глифы.

MathModel/MathRenderer: OMML (§22.1) → дерево боксов → PNG 300 dpi
(только GlyphFont/fontbox, без java.awt.Font); метрики боксов равны
габариту paint (пределы nary/sPre не обрезаются канвой). Unsupported
конструкция или переполнение бюджета — текстовая деградация (m:t).
Inline-картинка опускается раном w:rPr/w:position на базовую линию
строки (FOP ставит инлайн-графику нижним краем на базу; AUDIT-FIX
baseline-shift). Байтовое правило 6 MathFallbackNormalizer (перед
GlyphCoverage) срезает unsupported-формулы до загрузки docx4j; формула
в wps:txbx уходит в docx4j-фолбэк mathText.

JEuclid исключён из pom (de.rototor jeuclid-core/jeuclid-fop); порядок
zip-правил сдвинут (MathFallback → 6). Порядок сканов шрифтов закрыт
гейтом FontsBundledOnlyInvariantTest + BundledFontAliases (единый
алиас-реестр вместо рефлексивных мутаций реестра).

Счётчики: 63 класса / 1004 теста (core 57/956, app 6/48); JaCoCo
BRANCH core 0.8518. Доки: pipeline/render-limitations/repo-map/
testing/doc-bridge/MEM_USAGE_UPGRADE синхронизированы.
2026-11-20 23:51:40 +03:00
Pjandro 202e4ca97e fix(fonts): FopFallbackFonts дополняет семейства реальными начертаниями
- declareFamily: family-level skip удалён; каждое начертание дописывается,
  если в конфиге нет записи с реальным TTF этого начертания (hasRealFace);
- общая FopFactory замораживает fopconf первого документа JVM, а docx4j
  декларирует только использованные начертания (частично/simulate-style) —
  на macOS это роняло ruPlain_regularRunsUseRegularFont (Carlito-Bold не
  встраивался) и strictOoxml_convertsNotRejected (кириллица на base-14);
- регрессии: FopFallbackFontsTest#declareWhenDocx4jDeclaredRegularOnly_addsMissingVariants,
  #declareWhenDocx4jDeclaredSimulatedStyle_addsRealFaces, #declareTwice_noDuplicates,
  WordPdfConverterTest#fopFactoryFrozenFromFirstDoc_fontsComplete (order-smoke).
2026-11-20 22:10:11 +03:00
Pjandro fa45b7a8be docs: обновить AGENTS.md по итогам аудита репозитория
PR checks / web (pull_request) Successful in 19s
PR checks / java (pull_request) Successful in 2m59s
Main: tests, deploy, autotests / web (push) Successful in 8s
Main: tests, deploy, autotests / java (push) Successful in 39s
Main: tests, deploy, autotests / images-app (push) Successful in 31s
Main: tests, deploy, autotests / images-web (push) Successful in 1m16s
Main: tests, deploy, autotests / deploy (push) Successful in 2m1s
Main: tests, deploy, autotests / autotests (push) Successful in 1m46s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- счётчики тестов 60 классов / 962 теста (core 54/914, app 6/48) вместо устаревших 59/898;
- internal/doc: 17 top-level классов + вложенный DocxBody;
- ValidationException бросает также convert() при options == null;
- открытые префиксы ApiKeyFilter: /actuator/ со слэшем + dot-segment гейт;
- деградация chart: wp:extent вне диапазона оставляет объект + warn;
- детализация шага 4 (4.25/4.5) и finally-очистки конвейера;
- добавлены: mem-bench, file-size-threshold=2MB, ловушка WORDPDF_API_KEY из .env mise,
  прод-вход pjandro.ru/pdf-converter/, лицензии шрифтов OFL/Bitstream-Vera/Noto,
  PMD-движок 6.55.0 как default плагина, явный выключенный TS-strict.
2026-11-20 21:06:52 +03:00
Pjandro 1c8f6e1516 docs: MEM_USAGE_UPGRADE.md — аудит памяти конвейера
PR checks / web (pull_request) Successful in 48s
PR checks / java (pull_request) Successful in 1m19s
Main: tests, deploy, autotests / java (push) Successful in 3m11s
Main: tests, deploy, autotests / web (push) Successful in 1m29s
Main: tests, deploy, autotests / images-app (push) Successful in 2m21s
Main: tests, deploy, autotests / images-web (push) Successful in 2m43s
Main: tests, deploy, autotests / deploy (push) Successful in 1m52s
Main: tests, deploy, autotests / autotests (push) Successful in 58s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- Методология харнеса (peak/used/GC-лог/JFR/VmHWM) и его ограничения;
- baseline suite×20+big, профиль аллокаций: доли приложения ≤0,44%, остальное — JAXB/XSLT/FOP;
- кандидаты A–E с замерными гейтами: все отклонены (A — измерением, B/C/E — долей ниже гейта);
- матрица флагов f1–f5: рекомендация проду -Xmx768m/G1 + mem_limit 1g вместо 2G/3G.
2026-11-17 05:46:10 +03:00
Pjandro 9d4661be3f test: MemoryBench начисто проходит PMD-гейт
- SystemPrintln: вывод харнеса через PrintStream(FileDescriptor.out) вместо System.out;
- AvoidLiteralsInIfCondition: условия сценариев вынесены в булевы локальные переменные;
- membench.sh: заметка про смену GC (нужен и -XX:-UseG1GC, иначе старт падает).
Полный ./mise.sh run verify после правки зелёный: core 914 + app 48, PMD/JaCoCo без нарушений.
2026-11-17 05:46:10 +03:00
Pjandro 67f8636b0c core,test: mem-bench харнес замера памяти (MemoryBench + membench.sh + mise task) 2026-11-17 05:08:54 +03:00
Pjandro 08c68305be docs: актуализация AGENTS.md по свежей сверке с кодом
PR checks / web (pull_request) Successful in 42s
Main: tests, deploy, autotests / web (push) Successful in 45s
PR checks / java (pull_request) Successful in 1m36s
Main: tests, deploy, autotests / images-web (push) Successful in 33s
Main: tests, deploy, autotests / java (push) Successful in 2m59s
Main: tests, deploy, autotests / images-app (push) Successful in 6m29s
Main: tests, deploy, autotests / deploy (push) Successful in 2m35s
Main: tests, deploy, autotests / autotests (push) Successful in 52s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- convert — только 3-аргументная сигнатура; App.tsx в components/; 11 zip-правил + OleObjectNormalizer как 12-й байтовый
- REST: открытые префиксы ApiKeyFilter, тело {"error": …}, карта 404/405/415 в repo-map
- расхождение compose (prod-like гасит springdoc, CI-прод держит swagger открытым); VITE_BASE в образе; подсети resolver; WORDPDF_SAMPLES_DIR; ручные фикстуры не перезаписывать
2026-11-17 04:14:23 +03:00
Pjandro f7304094ec fix: int-оверфлоу requireInFile и закрытие веток гейта JaCoCo
PR checks / web (pull_request) Successful in 43s
PR checks / java (pull_request) Successful in 2m47s
Main: tests, deploy, autotests / web (push) Successful in 41s
Main: tests, deploy, autotests / java (push) Successful in 3m37s
Main: tests, deploy, autotests / images-app (push) Successful in 48s
Main: tests, deploy, autotests / images-web (push) Successful in 38s
Main: tests, deploy, autotests / deploy (push) Successful in 2m0s
Main: tests, deploy, autotests / autotests (push) Successful in 47s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- requireInFile: (long) offset + len > fileLen — offset+len того же класса оверфлоу, что sectorOffset (DIFAT-сектор близ MAX_INT обходил проверку)
- CfbReader.chain: единая капка sect >= min(fat.length, sectorTotal) (меньше незакрытых исходов веток, контракт прежний), регрессии в javadoc
- CfbReaderTest#difatSectorFarBeyondFile_rejected — ветка sectorOffset (фat>MAX_INT при DIFAT[0]=0x400000)
- PieceTableTest#negativeStartCp_rejected: aCP[0] — все 4 байта 0xFF (один байт давал 255 и попадал в ветку монотонности, а не отрицательного CP)
2026-11-16 03:17:55 +03:00
Pjandro e6a8b86583 fix: замечания ревью — crash-гарды моста и сверка цитат MS-DOC
PR checks / web (pull_request) Successful in 44s
PR checks / java (pull_request) Failing after 1m22s
- CfbReader: цепочка FAT — сектор за sectorTotal → ConversionException «за концом FAT» (раньше FAT[>127] уходил за массив: ArrayIndexOutOfBounds на битом CFB)
- FibHeader: cbRgFcLcb — u16 по §2.5.1 (читался u32 → AIOOBE на FIB длиной 154 байта); csw/cslw MUST — цитата §2.5.1 Fib
- PieceTable: aCP[0] < 0 и endCp <= startCp → ConversionException (отрицательный aCP читал бы WordDocument до начала; отрицательный span ронял new String)
- Таблица nFib→cbRgFcLcb — ссыка на [MS-OSHARED] §2.1.1 Table 2
- Цитаты секций MS-DOC по ToC ms-doc-full.md: CSSAOperand §2.9.46, SHDOperand §2.9.249 (Shd §2.9.247, Ipat §2.9.121, Shd80 §2.9.248), Ico §2.9.119, SttbfFfn §2.9.286, Brc/BrcType §2.9.16/.22, PapxFkp §2.9.174 — в Grpprl/Tables/Sections/FibHeader, тестах моста, doc-bridge.md
- Регрессы: FibHeaderTest#blobEndAtBoundary_rejectedNotCrash, PieceTableTest#negativeStartCp_rejected, CfbReaderTest пин «за концом FAT»
2026-11-16 03:06:31 +03:00
Pjandro d44eac683a fix: PMD-чистые константы MUST-полей CFB и ветки покрытия гейта JaCoCo
PR checks / web (pull_request) Successful in 37s
PR checks / java (pull_request) Successful in 2m40s
- CfbReader: MiniStreamCutoff в именованную константу (§2.2) — гейт PMD AvoidLiteralsInIfCondition;
- GrpprlTest: полная таблица Kul→ST_Underline (§2.9.127, все 18 case);
- TableIndentNormalizerTest: явный w:type=pct и tblInd без w:w — пропуск свёртки;
- ChpxIndexTest/PapxIndexTest: отрицательный fcBte, fc раньше первого диапазона,
  вырожденный rgfc (§2.4.6.1) — ветки отказных гвардов.
2026-11-16 00:54:59 +03:00
Pjandro aaad5d2bb0 fix: устранение расхождений кода со спецификациями и синхронизация доков
PR checks / web (pull_request) Successful in 42s
PR checks / java (pull_request) Failing after 2m53s
- docx-нормализаторы: tblInd без w:type = dxa (§17.4.87); явный vanish=false перекрывает стиль (§17.3.2.70);
  RubyNormalizer снимает обёртку w:ruby и удаляет rubyBaseText; DocxOnOffNormalizer не трогает w:scrollbar;
  SymbolFontNormalizer читает прямые коды w:sym
- мост .doc: borderVal 0x1B→inset; STK_CHARACTER=2 (§2.4.6.5); grpprl toggle + знаковые XAS; ChpxIndex cb=0;
  PapxIndex cpara + ключ по последнему символу; sprmCIstd reset+preserve; Sections YAS/bkc/pgnStart/gutter/nfc;
  NPE-гард Lists; BrcMayBeNil = нет границы; emission (w:id, слоты шрифтов, Kul, ISS, header-картинки);
  OfficeArt 0x46B/TIFF/DIB/второй UID + warn EMF/WMF/PICT; PrcData стоп-обработка; CfbReader бюджет +
  MUST-поля заголовка (§2.2); FibHeader csw/cslw + cbRgFcLcb; PieceTable aCP-дубли + cbMac
- мёртвый код: девять неиспользуемых STEP-констант, недостижимая ветка pgMar
- javadoc: исправлены номера секций ECMA-376/MS-DOC/MS-CFB/MS-ODRAW в нормализаторах, chart-пакете, мосту
- доки: pipeline.md, repo-map.md, doc-bridge.md, render-limitations.md, AGENTS.md синхронизированы с кодом
2026-11-16 00:43:43 +03:00
Pjandro 334e6a9006 docs: перегенерировать AGENTS.md по структуре Repository Guidelines
PR checks / web (pull_request) Successful in 1m14s
PR checks / java (pull_request) Successful in 3m1s
Main: tests, deploy, autotests / web (push) Successful in 1m10s
Main: tests, deploy, autotests / images-web (push) Successful in 41s
Main: tests, deploy, autotests / java (push) Successful in 7m19s
Main: tests, deploy, autotests / images-app (push) Failing after 48s
Main: tests, deploy, autotests / deploy (push) Has been skipped
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Has been skipped
- синтез четырёх scout-обходов: core src, тесты, конфигурация/сборка, скрипты/документация
- 8 разделов: Overview, Architecture & Data Flow (пайплайн 0–7, инварианты), Key Directories,
  Development Commands, Conventions, Important Files, Runtime/Tooling, Testing & QA
- сохранены критические инварианты, ловушки (test-jar/-am, @Value-дефолты, idiom загрузки фикстур) и ссылки-роутеры на docs/agent
2026-11-15 01:28:22 +03:00
Pjandro 72cc717056 PMD: откат на движок 6.55.0 (maven-pmd-plugin 3.21.2), закрытый набор из 26 правил; нарушения починены кодом
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 3m4s
Main: tests, deploy, autotests / java (push) Successful in 9s
Main: tests, deploy, autotests / web (push) Successful in 43s
Main: tests, deploy, autotests / images-app (push) Successful in 1m13s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / deploy (push) Successful in 1m35s
Main: tests, deploy, autotests / autotests (push) Successful in 45s
Main: tests, deploy, autotests / rollback (push) Has been skipped
2026-11-13 02:11:51 +03:00
Pjandro 0b2dda8caa PMD: слияние новых правил (bestpractices/design/errorprone/multithreading) + правка нарушений без подавлений
PR checks / web (pull_request) Successful in 1m9s
PR checks / java (pull_request) Successful in 1m17s
Main: tests, deploy, autotests / web (push) Successful in 34s
Main: tests, deploy, autotests / images-web (push) Successful in 38s
Main: tests, deploy, autotests / java (push) Successful in 2m36s
Main: tests, deploy, autotests / images-app (push) Successful in 42s
Main: tests, deploy, autotests / deploy (push) Successful in 2m7s
Main: tests, deploy, autotests / autotests (push) Successful in 45s
Main: tests, deploy, autotests / rollback (push) Has been skipped
2026-11-13 01:24:25 +03:00
Pjandro d8eda0a2e4 Ядро: раздельные исключения ChartsFoundException/SmartArtFoundException/OleFoundException
PR checks / web (pull_request) Successful in 42s
PR checks / java (pull_request) Successful in 2m41s
Main: tests, deploy, autotests / web (push) Successful in 41s
Main: tests, deploy, autotests / images-web (push) Failing after 23s
Main: tests, deploy, autotests / java (push) Successful in 1m22s
Main: tests, deploy, autotests / images-app (push) Failing after 2m32s
Main: tests, deploy, autotests / deploy (push) Has been skipped
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Has been skipped
DrawingFoundException с enum Kind удалён: каждый error-флаг бросает свой
тип-наследник ConversionException с фиксированным сообщением. App-слой
сохраняет один DrawingRejectedException (422) — маппинг по типу в
ConversionService.doConvert, тексты ответа не изменились (контракт с
фронтом). Обновлены тесты и документация.
2026-11-13 00:59:07 +03:00
Pjandro e9abcd38c8 CI: единственный прогон тестов в контейнере без fontconfig
PR checks / web (pull_request) Successful in 40s
PR checks / java (pull_request) Successful in 1m16s
Main: tests, deploy, autotests / java (push) Successful in 38s
Main: tests, deploy, autotests / web (push) Successful in 41s
Main: tests, deploy, autotests / images-web (push) Successful in 35s
Main: tests, deploy, autotests / images-app (push) Successful in 47s
Main: tests, deploy, autotests / deploy (push) Successful in 1m59s
Main: tests, deploy, autotests / autotests (push) Successful in 44s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Хостовые Setup JDK/Maven/кеш~/.m2 и mvn на раннере убраны: полный
mvn clean verify (тесты + PMD + JaCoCo) исполняется только в образе
Containerfile.test (без libfontconfig и /etc/fonts). Отчёты JaCoCo
извлекаются из образа docker create/cp (отсутствие отчёта — пустая
сводка, не падение). mise verify остаётся сырым mvn без docker/podman.
2026-11-10 01:09:13 +03:00
Pjandro 5631c9e0c0 OMML без fontconfig: текстовая деградация формул вместо InternalError
PR checks / web (pull_request) Successful in 41s
PR checks / java (pull_request) Successful in 3m12s
На хостах без fontconfig (arm64 без /etc/fonts) jeuclid-fop при первой
OMML-формуле падает InternalError: Fontconfig head is null — проба
MathMlSupport фиксирует недоступность AWT-шрифтов один раз на JVM,
MathFallbackNormalizer (правило 11, после Ruby) заменяет m:oMath/
m:oMathPara ранами с конкатенацией m:t (как docx4j mathText). С
fontconfig поведение не меняется (вектор).

Контейнер Containerfile.test (maven:3.9-temurin-17 без fontconfig с
JVM-гейтом) прогоняет mvn clean verify по этой ветке всегда: задача
mise verify-nofontconfig и шаг CI в pr.yml/main.yml.
2026-11-10 00:10:35 +03:00
Pjandro 13ca7425a3 refactor(core): сужение уровней доступа — internal-нормализаторы, CfbReader и служебные методы валидатора в package-private
PR checks / web (pull_request) Successful in 33s
PR checks / java (pull_request) Successful in 1m16s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 1m18s
Main: tests, deploy, autotests / images-web (push) Successful in 37s
Main: tests, deploy, autotests / images-app (push) Successful in 42s
Main: tests, deploy, autotests / deploy (push) Successful in 1m58s
Main: tests, deploy, autotests / autotests (push) Successful in 40s
Main: tests, deploy, autotests / rollback (push) Has been skipped
- WordPdfValidator: isBinaryDoc/checkPageCount/checkPageCountDoc → package-private
  (наружу остаются checkInput/validate/maxImagePixels)
- CfbReader: класс и readStreams → package-private (все вызывающие в internal/doc)
- 9 STEP-нормализаторов + RubyNormalizer: класс, STEP и normalize → package-private;
  DocxRewritePipeline.normalize → package-private (STEP остаётся публичным)
- javadoc BundledFontMapper: {@link GlyphCoverageNormalizer} → {@code}
- контракты видимости синхронизированы: AGENTS.md, repo-map.md, doc-bridge.md, README.md
2026-11-08 20:34:43 +00:00
Pjandro af5d09e001 refactor(core,app): WordPdfSettings упразднён — лимиты входа обязательны в ConvertOptions, пороги производные, REST-параметры maxMb/maxPages
PR checks / web (pull_request) Successful in 33s
PR checks / java (pull_request) Successful in 1m18s
- WordPdfSettings удалён; ConvertOptions.defaults() удалён; 2-аргументный
  convert и безлимитные оверлоды валидатора сняты (options == null → 400)
- производные пороги (распаковка total/XML, пиксели растра, zip-записи)
  считаются из maxMb/maxPages формулами в WordPdfConverter/WordPdfValidator
- мост: DocToDocx.convert(+maxMb) → OfficeArt.read(+maxPixels)
- REST: свойства wordpdf.max-mb/max-pages — дефолт эндпоинта (литералы
  @Value 5/100), параметры запроса maxMb/maxPages переопределяют в обе
  стороны (≤ 0 → 400); верхний потолок отсутствует (решение пользователя)
- HTTP-контексты тестов пиныт wordpdf.api-key= (mise подмешивает .env)
- доки/README/autotests-формулировки синхронизированы
2026-11-08 20:16:52 +00:00
Pjandro 8a8e8a9f84 fix(core): бюджет распаковки docx — параметром валидатора из maxMb/maxPages
PR checks / web (pull_request) Successful in 33s
PR checks / java (pull_request) Successful in 1m20s
checkDocxContainer получает бюджеты параметром; validate считает их из
ConvertOptions.maxMb()/maxPages(): clamp(maxMb×10MiB + maxPages×64KiB, 16MiB,
MAX_DECOMPRESSED_MB) и clamp(maxMb×4MiB + maxPages×32KiB, 4MiB,
MAX_DECOMPRESSED_XML_MB) (коэффициенты/полы — package-private константы
WordPdfConverter, compile-time инлайн — WordPdfValidator по-прежнему без
зависимости от docx4j). Константы WordPdfSettings — жёсткие крышки (публичный
API, защита JAXB DOM). Сообщения печатают вычисленный бюджет. Тесты: пол
(16 МБ при maxMb=1), масштабирование и крышка (64 МБ при maxMb=10); доки
синхронизированы.
2026-11-08 19:13:38 +00:00
Pjandro 41b4f89e74 docs: синхронизация AGENTS/repo-map с аудиторскими фиксами
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 1m27s
2026-11-08 16:41:06 +00:00
Pjandro 8b16d64059 fix(infra): безусловная нормализация X-Forwarded-For/Proto/Host на шлюзах; CSP+заголовки безопасности в образ SPA 2026-11-08 16:41:06 +00:00
Pjandro 638e28c653 fix(app): полный validate внутри воркера (до очереди — только размер); 500 без деталей ядра в теле 2026-11-08 16:41:06 +00:00
Pjandro d8353aab61 fix(core): OOM-гейты входа (CFB root/потоки/miniFAT, DIB, растр, дубликаты zip, XML-бюджет), бюджет chart-PNG, монитор WordPdfConverter.class в BundledFonts, restrictToBundled в finally, whitelist схем URL 2026-11-08 16:41:06 +00:00
Pjandro 8d2fa3dad9 fix(core): синхронизация чтения реестра начертаний BundledFonts.font
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 1m20s
Main: tests, deploy, autotests / web (push) Successful in 36s
Main: tests, deploy, autotests / images-web (push) Successful in 35s
Main: tests, deploy, autotests / java (push) Successful in 1m25s
Main: tests, deploy, autotests / images-app (push) Successful in 41s
Main: tests, deploy, autotests / deploy (push) Successful in 1m42s
Main: tests, deploy, autotests / autotests (push) Successful in 44s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Аудит потокобезопасности ядра: font()/regular()/... читали VARIANTS
(HashMap, пишется в init() под монитором BundledFonts.class) без
замка — публичный API гонял с init(). font() стал synchronized
(делегаты regular/bold/italic/boldItalic идут через него). Контракты
зафиксированы javadoc: restrictToBundled() рядом с идущей
конвертацией — только под монитором WordPdfConverter.class;
потокобезопасность GlyphFont (монитор of(), volatile cmap, внутренние
замки fontbox lockReadtable). Инвариант — AGENTS.md. Тест
concurrentFontApi_callsAllSucceed — 4 потока × 50 итераций font-API.

Регрессия — BundledFontsTest#concurrentFontApi_callsAllSucceed.
2026-11-08 14:36:15 +00:00
Pjandro 2116ec43a4 fix(core): сериализация конвертаций монитором класса WordPdfConverter
PR checks / web (pull_request) Successful in 35s
PR checks / java (pull_request) Successful in 1m19s
Публичный convert() теперь безопасен из нескольких потоков: секция после
валидации (мост .doc + convertToStream) выполняется под монитором класса —
общая FopFactory (per-render disableFontCache, имиджевые кеши) и её сброс в
finally больше не могут пересечься с параллельным рендером. warmup()
синхронизирован тем же монитором (реентельно). WordPdfValidator остаётся
до монитора: stateless, вызывается параллельно HTTP-потоками.
Регрессия — WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
Комментарии ConversionService/AGENTS/repo-map приведены к новому контракту.
2026-11-08 14:22:56 +00:00
Pjandro bc98a12421 perf(core): общая FopFactory на JVM со сбросом имиджевых кешей
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m31s
Переиспользование FopFactory между конвертациями раньше запрещалось:
форк FOP копит на фабрике image-кеши (xmlgraphics-commons ImageCache:
imageInfos/images и ImageObjectCacheImpl), ключи записей — временные
файлы file:/tmp/<uuid>… с уникальным на конвертацию именем, попадания
не бывает никогда, а soft-ссылки не освобождаются при свободной куче
(2 ГБ фиксированная): после 30 конвертаций ~1,5 ГБ живых byte[]
против 17 МБ, рост live-кучи, Full GC.

Теперь фабрика одна на JVM, а каждая конвертация в finally вызывает
resetSharedImageCaches() — публичные clearCache() у ImageCache и
ImageObjectCacheImpl. Разбор шрифтов форка (GPOS, ~140k объектов)
теперь один раз на JVM. Замер после фикса: 16,8 МБ живых byte[],
heap used 89 МБ после 30 конвертаций, Full GC от нагрузки — 0.

Регрессии — WordPdfConverterTest#fopFactorySharedAcrossConversions,
#sharedImageCaches_clearedAfterConversion.
2026-11-08 14:06:23 +00:00
Pjandro 8061a2fbe7 perf(core): срез декода растра, стримовый OLE-детект; heap -Xms2g -Xmx2g
PR checks / web (pull_request) Successful in 48s
PR checks / java (pull_request) Successful in 1m44s
ChartImageHandler: для не-JPEG без кропа с ppi <= threshold (или без
размера в макете) PictureCompression.compress всегда возвращает null,
но сначала декодирует полный растр ImageIO — решение принимается по
26 байтам заголовка (PNG/GIF/BMP), растр не декодируется вовсе; JPEG
остаётся на штатном пути CR-029 (перекодировка «для размера» сохранена).

OleObjectNormalizer: детект <w:object — потоковым поиском окном 8 KiB
с перекрытием, без readAllBytes()+new String на каждую word/*.xml.

Heap: ENTRYPOINT -Xms2g -Xmx2g (вместо -XX:MaxRAMPercentage=70),
mem_limit 2g -> 3g (compose.yml, compose.dev.yml, прод-heredoc
main.yml) — фиксированный heap + запас под metaspace/native.

Отменённая ветка: переиспользование общей FopFactory между прогонами
копит шрифтовые данные форка FOP на каждый render (замер 2026-11:
после 30 конвертаций ~1,4 ГБ живых byte[] против 17 МБ при
per-conversion сборке, рост live-кучи, Full GC) — фабрика остаётся
per-conversion, инвариант зафиксирован комментарием.

GC-замер (java -jar, -Xms2g -Xmx2g, 30 конвертаций фикстур): young
5 против 7 на main, паузы 12,2 мс против 18,7 мс, Full GC нет на обоих.

Тесты: ChartImageHandlerTest +5 (PNG/GIF/BMP/JPEG/выше порога),
OleObjectNormalizerTest +1 (маркер через границу окна).
2026-11-08 13:17:34 +00:00
159 changed files with 10022 additions and 1931 deletions
+32 -23
View File
@@ -20,28 +20,29 @@ jobs:
exit 1 exit 1
} }
- name: Setup JDK 17 - name: Build and test without fontconfig (PMD+JaCoCo included)
uses: actions/setup-java@v5
with:
java-version: '17'
distribution: 'temurin'
- name: Cache Maven repository
uses: actions/cache@v4
with:
path: ~/.m2/repository
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
restore-keys: maven-
- name: Setup Maven 3.9.16
run: |
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
env: env:
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }} MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
run: mvn -B -s .ci/maven-settings.xml clean verify run: |
DOCKER_BUILDKIT=0 docker build \
-f Containerfile.test \
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
-t wordpdf-verify:ci \
.
- name: Extract JaCoCo reports
if: always()
run: |
id=$(docker create wordpdf-verify:ci 2>/dev/null) || {
echo "образ не собран — сводка покрытия будет пустой"
exit 0
}
mkdir -p wordpdf-core/target/site/jacoco wordpdf-app/target/site/jacoco
docker cp "$id:/build/wordpdf-core/target/site/jacoco/jacoco.xml" \
wordpdf-core/target/site/jacoco/jacoco.xml || true
docker cp "$id:/build/wordpdf-app/target/site/jacoco/jacoco.xml" \
wordpdf-app/target/site/jacoco/jacoco.xml || true
docker rm "$id" >/dev/null
- name: Coverage summary - name: Coverage summary
if: always() if: always()
@@ -262,9 +263,9 @@ jobs:
# не крушит стек бесконечным crash-loop. Синтаксис on-failure:N podman # не крушит стек бесконечным crash-loop. Синтаксис on-failure:N podman
# переваривает и применяет (проверено: maxtries=N, после исчерпания exited). # переваривает и применяет (проверено: maxtries=N, после исчерпания exited).
restart: on-failure:5 restart: on-failure:5
# heap вписан в лимит (-XX:MaxRAMPercentage=70 в ENTRYPOINT образа); # фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT образа, лимит 3g —
# паритет с repo compose.yml # запас под metaspace/потоки/native; паритет с repo compose.yml
mem_limit: 2g mem_limit: 3g
# healthcheck дублируется в compose, а не только в Containerfile: podman # healthcheck дублируется в compose, а не только в Containerfile: podman
# выгружает образы в OCI, где HEALTHCHECK теряется, а gateway в depends_on # выгружает образы в OCI, где HEALTHCHECK теряется, а gateway в depends_on
# ждал бы healthy вечно. wget, не curl: alpine-jre образ curl не содержит. # ждал бы healthy вечно. wget, не curl: alpine-jre образ curl не содержит.
@@ -329,6 +330,14 @@ jobs:
resolver 10.112.0.1 valid=10s ipv6=off; resolver 10.112.0.1 valid=10s ipv6=off;
set \$upstream_app http://app:8080; set \$upstream_app http://app:8080;
set \$upstream_web http://web:80; set \$upstream_web http://web:80;
# X-Forwarded-* переписываются безусловно: клиент не должен иметь
# возможности подсунуть бэкенду подставной "реальный IP/схема/хост"
# (Spring ForwardedHeaderFilter доверяет этим заголовкам).
# X-Forwarded-Prefix не трогаем: его проставляет внешний nginx,
# на нём держится корректный base у swagger-ui за прокси.
proxy_set_header X-Forwarded-For \$remote_addr;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_set_header X-Forwarded-Host \$host;
location /api/ { location /api/ {
# в proxy_pass нет path-части, поэтому URI передаётся как есть # в proxy_pass нет path-части, поэтому URI передаётся как есть
proxy_pass \$upstream_app; proxy_pass \$upstream_app;
+46 -20
View File
@@ -19,28 +19,29 @@ jobs:
exit 1 exit 1
} }
- name: Setup JDK 17 - name: Build and test without fontconfig (PMD+JaCoCo included)
uses: actions/setup-java@v5
with:
java-version: '17'
distribution: 'temurin'
- name: Cache Maven repository
uses: actions/cache@v4
with:
path: ~/.m2/repository
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
restore-keys: maven-
- name: Setup Maven 3.9.16
run: |
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
env: env:
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }} MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
run: mvn -B -s .ci/maven-settings.xml clean verify run: |
DOCKER_BUILDKIT=0 docker build \
-f Containerfile.test \
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
-t wordpdf-verify:ci \
.
- name: Extract JaCoCo reports
if: always()
run: |
id=$(docker create wordpdf-verify:ci 2>/dev/null) || {
echo "образ не собран — сводка покрытия будет пустой"
exit 0
}
mkdir -p wordpdf-core/target/site/jacoco wordpdf-app/target/site/jacoco
docker cp "$id:/build/wordpdf-core/target/site/jacoco/jacoco.xml" \
wordpdf-core/target/site/jacoco/jacoco.xml || true
docker cp "$id:/build/wordpdf-app/target/site/jacoco/jacoco.xml" \
wordpdf-app/target/site/jacoco/jacoco.xml || true
docker rm "$id" >/dev/null
- name: Coverage summary - name: Coverage summary
if: always() if: always()
@@ -103,6 +104,31 @@ jobs:
f"{base}/{existing}" if existing else base, {"body": body}) f"{base}/{existing}" if existing else base, {"body": body})
PY PY
macos-sim:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Check maven mirror var
env:
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
run: |
[ -n "$MAVEN_MIRROR_URL" ] || {
echo "Задайте Actions Variable MAVEN_MIRROR_URL — см. GITEA-vars.md" >&2
exit 1
}
- name: Tests under macOS emulation (-Dos.name)
env:
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
run: |
DOCKER_BUILDKIT=0 docker build \
-f Containerfile.test \
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
--build-arg "SUREFIRE_OS_NAME=Mac OS X" \
-t wordpdf-verify:macos-sim \
.
web: web:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
+5
View File
@@ -44,3 +44,8 @@ DEPLOY.md
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1) # Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
/.mise/ /.mise/
# Сайт документации: сборка, venv, копия javadoc
site/
docs/.venv/
docs/apidocs/
+105 -103
View File
@@ -1,128 +1,130 @@
# Repository Guidelines # Repository Guidelines
> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md`, нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна), пользовательская документация — `README.md`. > Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md` (pipeline, doc-bridge, chart, testing, ci-cd, repo-map, render-limitations — каждый авторитетен наравне с этим файлом), нормативные форматы — `docs/standards/` (навигатор — `docs/standards/README.md`, ссылка на спецификацию — с номером секции).
## Project Overview ## Project Overview
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP, без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven. Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP (`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 — транзитив от `docx4j-export-fo`), без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Maven-мультимодуль `ru.pjandro:java-word-pdf:1.0.0`: `wordpdf-core` (библиотека), `wordpdf-app` (REST на Spring Boot 4.1.1); вне Maven-реактора — SPA `wordpdf-web` (React 19.2 + TS ~6.0 + Vite 8.3 + oxlint + Tailwind v4.3, npm; strict-режим TS намеренно не включён — сборка не strict-гейт) и pytest-автотесты `prod-autotests/`. Java 17, только Maven.
| Модуль | Содержимое | ## Architecture & Data Flow
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Реальный прод-стек (`docker-compose.yml` + прод `nginx.conf`) рендерит CI-job `deploy` — копий на хосте/в репо не заводить. Наружный прод-вход — `https://pjandro.ru/pdf-converter/` (образ web собирается с `VITE_BASE=/pdf-converter/` — bake в job `images-web`, не в compose).
**Пайплайн** `WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions)` → `convertToStream` (публичная сигнатура единственная, 2-аргументной перегрузки **нет**); порядок шагов фиксирован:
0. `DependencyGuard.check()` (commons-compress ≥ 1.25.0 API-проба);
1. шрифты: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — строго в этом порядке, до `load()`;
2. нормализаторы (`DocxRewritePipeline.STEP` + лямбда `OleObjectNormalizer`) → `WordprocessingMLPackage.load`;
3. `setFontMapper`; 3.5 `DrawingPreRenderer.run` (chart/SmartArt/OMML-формулы → PNG; error-флаги бросаются здесь) — **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы;
4. `FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`; 4.25 `LayoutPostRenderer.register`; 4.5 `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`;
5. общая `FopFactory` (DCL на мониторе `WordPdfConverter.class`);
6. `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним;
7. `finally`: сброс temp-шрифтов (`FontTablePart.deleteEmbeddedFontTempFiles()`), `resetSharedImageCaches()` (иначе ~1,5 ГБ за 30 конвертаций), `restrictToBundled()` (иначе встроенные в предыдущий docx шрифты травят реестр).
`WordPdfValidator.validate` вызывается в `convert()` **до** монитора (параллельно); при `options == null` бросает `ValidationException` сам `convert()`. Вход роутируется по сигнатуре: `PK\x03\x04` → docx; `D0 CF 11 E0 A1 B1 1A E1` (CFB) → `DocToDocx.convert`. Для `.doc` страницы считаются по сырым байтам. Пороги валидатора в `WordPdfConverter` объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается).
**Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`):
- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages` — порядок полей фиксирован), `ConversionException` + `ValidationException` + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев (никогда не бросает), решает вызывающий;
- `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby, `OleObjectNormalizer` — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`;
- `internal/doc`: мост `.doc`→`.docx`, 18 top-level классов (17 package-private + `DocToDocx`) + вложенный `DocxBody`, наружу только `DocToDocx.convert/countPages`; любая бита/шифрованный/Word 6-95 входов → `ConversionException`; раскладки — `docs/agent/doc-bridge.md`;
- `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — `fitDpi` понижает dpi; `MAX_POINTS` 100 000, бюджет chart/math-PNG на документ 128 MiB); формулы OMML — собственный растер `MathModel` (разбор §22.1 в дерево боксов, `SUPPORTED` — единый список конструкций) + `MathRenderer` (без AWT/JEuclid, только бандл через `GlyphFont`); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn; неподдерживаемая/битая формула → **текст** (конкатенация `m:t`) + warn; `wp:extent` вне диапазона/ноль → объект **остаётся** + warn (FOP молча потеряет); `OutOfMemoryError` — не деградация, а `ConversionException` (500);
- `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен).
**Concurrency-инвариант**: `PhysicalFonts` — глобальный мутируемый реестр → все конвертации сериализованы монитором `WordPdfConverter.class` (convert, warmup, DCL-фабрика, мутации `BundledFonts`, `BundledFonts.font()`). Приложение дополнительно держит однопоточный `ThreadPoolExecutor` (очередь 16 → 503, `wordpdf.convert-timeout=2m` → 504), головой очереди стоит `warmup()`; `WordPdfValidator.checkInput` выполняется синхронно до очереди.
**REST** (`wordpdf-app`, всё package-private кроме `WordPdfApplication`): `POST /api/v1/convert` (multipart `file` + `errorOnCharts/errorOnSmartArt/errorOnOle`, `maxMb/maxPages` переопределяют серверный дефолт в обе стороны, ≤ 0 → 400; `file.getBytes()` — только после проверки размера; имя файла из `Content-Disposition`, UTF-8 + `.pdf`). Коды: 400 валидация/битые параметры, 401 `ApiKeyFilter` (`X-API-Key` ↔ `wordpdf.api-key`, пусто = выключено, сравнение `MessageDigest.isEqual`; открытые префиксы `/actuator/` (со слэшем!), `/swagger-ui`, `/v3/api-docs`; dot-segment (`..`, `%2e`) заставляет требовать ключ даже на открытых; Advice фильтров не видит — 401 пишет сам), 413 multipart, **422** отказ по графике (`DrawingRejectedException`, фиксированные тексты CHARTS/SMART_ART/OLE — контракт с фронтом), 500 `ConversionFailedException` (текст ядра только в лог, наружу фиксированный), 503 переполнение очереди, 504 timeout; тело ошибки — `{"error": …}` (`record ApiError`). Полная карта, включая 404/405/415, — `docs/agent/repo-map.md`. На `.doc` error-флаги не срабатывают (OLE-вложения — U+0001, мост деградирует в картинки); при снятом флаге `.docx`-OLE теряет data-части, **но сохраняет плейсхолдер-картинку**.
**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ровно 2 `fetch`: `convertDocx`, `probeApiKey()` — 401=required / иначе open; ключ в localStorage `wordpdf.api.key`, при 401 стирается; имя файла из `Content-Disposition filename*=utf-8''`); единственный источник состояния — `useState` в `components/App.tsx` (+ `useRef` для `AbortController`/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер.
### Критические инварианты (нарушение = битый вывод, не исключение)
- Static-блок `WordPdfConverter`: `docx4j.convert.out.fo.gsubFeatures=false` (иначе `WordLayoutFixups` отказывает всем фиксам → FOP падает), `docx4j.fonts.discoverPhysicalFonts.enabled=false`, `discoverJarFonts.enabled=false` — не удалять.
- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + AUDIT-FIX-патчи); обновление docx4j = ручной перенос патчей; дрейф-гейт `vendoredXsltTracksJarCopy`; команда ре-вендоринга — `docs/agent/repo-map.md`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback). Fontbox логируется commons-logging — единственный мост `jcl-over-slf4j`; `commons-logging` исключён из pdfbox/fontbox в dependencyManagement.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится); `jeuclid-fop`/`jeuclid-core` исключены из `docx4j-export-fo` в core-pom (тянут AWT/fontconfig); расхождения с upstream-доками FOP нормальны; `lineRule=auto` не «чинить».
- Chart-media префикс `/word/media/chart-*` — константа `DrawingPreRenderer.CHART_MEDIA_URI_PREFIX` (package-private), пакетный контракт с `ChartImageHandler` (отключение пересжатия); переименование молча вернёт мыльный ресемпл.
- Стоп-лист «не чинить» (до любой попытки починить расхождение с Word — `docs/agent/render-limitations.md`): `jc="distribute"`, `suff="tab"`/`lvlJc`, кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, `ptab`, U+2188/U+218A (GPL-шрифты не добавляем).
## Key Directories
|Каталог|Назначение|
|---|---| |---|---|
| `wordpdf-core` | библиотека: 62 Java-файла (7 — публичный API, 16 `internal/`, 18 `internal/doc/`, 18 `internal/chart/`, 3 `fonts/`) | |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API + `internal/` (нормализаторы) + `internal/doc/` (мост) + `internal/chart/` (рендер) + `fonts/`|
| `wordpdf-app` | REST API на Spring Boot 4.1.1: 11 классов, единственный `public` — `WordPdfApplication` | |`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL/Bitstream-Vera/Noto), `xslt/docx2fo.xslt`, `slf4j-simple.properties`|
| `wordpdf-web` | SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ | |`wordpdf-core/src/test/resources/samples/`|фикстуры: 13 `.docx` + 12 `.doc` (закоммичены, билдятся в test-jar для app; у app своего `src/test/resources` **нет**)|
|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST-слой (11 классов)|
|`wordpdf-web/src/`|SPA: `api.ts` (вся сеть), `components/` (`App.tsx` — состояние, `ApiKeyGate`, `DropZone`, `PdfPreview`, `StatusMessage`, `Logo`)|
|`prod-autotests/`|pytest-проверки живого стенда (31: 4 открытые + 27 `needs_key`)|
|`docs/agent/` · `docs/standards/`|справочники поведения · закоммиченные спецификации (ECMA-376, MS-DOC/CFB/ODRAW…, навигатор — `docs/standards/README.md`)|
|`gateway/nginx.conf`|прод-like шлюз (`client_max_body_size 100m`, таймауты 300 с, `resolver` привязан literal-ом к шлюзу сети)|
|`develop/`|вне git (gitignored): эталоны Word — **не фикстуры**, в тесты/jar не подключать|
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Авторитетны этот файл, `docs/agent/` и код. Полный путеводитель по каталогам, ключевым файлам и командам — `docs/agent/repo-map.md`. ## Development Commands
## Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise 2026.10.19 в `./.mise/` + `mise install` + `npm ci` web; дальше всё через `./mise.sh` / `.\mise.ps1` (тонкие exec-обёртки; инструменты — в `~/.local/share/mise`).
Порядок шагов 0–7 фиксирован (`convertToStream`), местами менять нельзя. Вход роутируется по сигнатуре: `PK\x03\x04` → docx-путь; `D0 CF 11 E0 A1 B1 1A E1` (CFB, MS-CFB §2.2) → `DocToDocx.convert` → in-memory `.docx` → тот же конвейер (предикат — `WordPdfValidator.isBinaryDoc`). Валидация — **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер → страницы); для `.doc` — `checkPageCountDoc` по сырым байтам.
Порядок: шрифты (`BundledFontMapper` → `BundledFonts.init` → `restrictToBundled`) и правила 1–10 (`DocxRewritePipeline.STEP`) + `OleObjectNormalizer` — до `WordprocessingMLPackage.load`; `FOSettings`/`FopFallbackFonts`/`LayoutPostRenderer` — до `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; `finally` → `deleteEmbeddedFontTempFiles()`. Полная таблица шагов и подсчёт страниц — `docs/agent/pipeline.md`.
## Нормализаторы (`internal/DocxNormalizer`)
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame`). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–10 применяет `DocxRewritePipeline.STEP` одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); `OleObjectNormalizer` (правило 11) — лямбдой в `WordPdfConverter.normalizers()`. `STEP` выставляют 9 из 10 rewrite-нормализаторов (нет у `RubyNormalizer`), у `OleObjectNormalizer` её нет. Правила 1–11, guard'ы, номера секций и инвариант `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
## Мост `.doc` → `.docx` (`internal/doc`)
18 классов, 16 package-private; наружу — `DocToDocx` (`convert`/`countPages`) и `CfbReader`. Общий разбор — `DocFile`: CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Источники: [MS-DOC] (`docs/standards/doc/`), [MS-CFB]/[MS-OLEPS]/[MS-ODRAW] (`docs/standards/binary/`). Байтовые раскладки по классам — `docs/agent/doc-bridge.md`.
## REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
`POST /api/v1/convert`: multipart-поле `file` (`.docx`/`.doc`) + query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолты — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`; имя — `ConversionService.safeBaseName`. Тело ошибки — `{"error": …}`. Error-флаги на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки). `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
- **Коды**: 400 — `ValidationException`/`BadRequestException`/битые параметры; 401 — `ApiKeyFilter`; 404/405/415 — путь/метод/content-type; 413 — multipart; **422** — `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`); 500/503/504 — `ConversionFailedException`/`ConversionRejectedException`/`ConversionTimeoutException`. Полная карта — `docs/agent/repo-map.md`.
- **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
- **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503) — ядро не потокобезопасно; головой очереди на старте стоит `warmup()`. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются).
- **SPA**: вся сеть в `wordpdf-web/src/api.ts`; ключ в `localStorage` (`wordpdf.api.key`); `ApiKeyGate` — только если `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**); base — `VITE_BASE`; DropZone `.docx,.doc`.
## Chart/SmartArt-движок (`internal/chart`, 18 классов)
Нормативный источник — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`. Калибровки (камера, `PIE_DEPTH`) меняются только с пиксельными тестами; невалидная фикстура правится, не код.
Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_216` (`fitDpi`); лимиты `ChartSpec.MAX_POINTS = 100_000`, `ChartRenderer.MAX_TICKS = 1000`, `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` — деградация «объект как есть / удалён + warn», не OOM. Chart-PNG вставляются media-частями вручную (`addChartMedia`, `/word/media/chart-*`, без `createImagePart`); `ChartImageHandler` отключает «Compress Pictures» (CR-029) только для них. Пейнтеры, `autoTitleDeleted`, Combo, обходы JAXB — `docs/agent/chart.md`.
## Критические инварианты (нарушение = битый вывод, не исключение)
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`; иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `discoverJarFonts.enabled=false` — static-блок: иначе `BestMatchingMapper` сканирует системные шрифты и jar'ы classpath'а, а `restrictToBundled()` всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
- Единственный XSL-FO-стилист — вендорный `xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, Part 1 §17.3.2.24; AUDIT-FIX-2 — `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`, иначе их ловит catch-all `match="*"` и текст теряется). Дрейф-гейт `vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов копия побайтно равна стилю из jar'а. `setCustomXsltTemplates` принимает предкомпилированный `Templates`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`); приложение исключает его — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
- `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла.
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером; `warmup()` идёт тем же потоком.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `docs/agent/pipeline.md`.
- Не чинить: `jc="distribute"`, `suff="tab"`/`lvlJc`, метрика «single», кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`.
- Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
## Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). `BundledFontMapper.ALIASES`: Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto; fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). `GlyphFont` читает TTF напрямую с classpath через fontbox, **без** `java.awt.Font` (нужен fontconfig на хосте). Публичный API и детали — `docs/agent/repo-map.md`.
## Команды
Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise в `./.mise/`, дальше — `./mise.sh` / `.\mise.ps1`.
```bash ```bash
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push) ./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
mvn clean verify # то же; mvnw НЕТ — только системный Maven ./mise.sh run verify-nofontconfig # тот же verify в контейнерах без fontconfig (как CI)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест mvn test -Djacoco.skip=true # работает: пустой <argLine> по умолчанию в корневом pom
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am: core test-jar mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен: core test-jar
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен ./mise.sh run app-package && ./mise.sh run app-run # jar :8080, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173 ./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа ./mise.sh run mem-bench # membench.sh + core MemoryBench (MB_LABEL, --scenario suite|big|all, --dir develop/)
./mise.sh run prod-tests # прод-автотесты в prod-autotests/ podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
podman-compose up -d --build # prod-like стенд :9010 — fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
./mise.sh run prod-tests # pytest; обязателен WORDPDF_BASE_URL
./mise.sh run docs-install|docs-serve|docs-build|docs-javadoc|docs-deploy # сайт документации (MkDocs Material): venv+pip | preview :8000 | strict-сборка в site/ | javadoc core | публикация в ~/srv/wordpdf-docs (юнит wordpdf-docs.service, :9012)
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml) python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
``` ```
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`. - «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, **не** `java -jar`; вход — `http://<LAN-IP>:9011` (`hostname -I`); гейт готовности — контейнеры healthy (`podman-compose -f compose.dev.yml ps`) + корень SPA 200; `--force-recreate` обязателен.
- `mvn test` PMD и проверки JaCoCo **не** запускает (оба на `verify`; сам агент JaCoCo подключается и на `test` — execution `prepare-agent` на `initialize`); `mvn -pl wordpdf-app` без `-am` падает (зависимость от core test-jar).
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе. - Деплой — push в `main` → Gitea Actions (детали — `docs/agent/ci-cd.md`); **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`** (вне репо); ручных скриптов нет.
Пересоздание фикстур и перевендоривание стилиста — `docs/agent/repo-map.md`. Деплой: **прод** — на пользовательском LAN-сервере; **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**; пуск — push в `main` или Run workflow, ручных скриптов нет (детали — `docs/agent/ci-cd.md`).
## Code Conventions & Common Patterns ## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper`, `DrawMlColor`, Spring-компоненты `wordpdf-app`. - Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет). Исключения-экземпляры: `BundledFontMapper`, Spring-компоненты app. В `internal/**` классы package-private; `public` — только вызываемые извне пакета, контракт не расширять.
- В `internal/**` классы `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: `normalize`/`STEP`/`declare`/`run`/`check`/`register`; `rewrite`-хуки — package-private. В `wordpdf-app` всё package-private кроме `WordPdfApplication`; в `internal/doc` публичны только `DocToDocx` и `CfbReader`. - Ошибки публичного API — только `ConversionException extends RuntimeException`; `ValidationException` не оборачивать; в chart — деградация вместо падения; текст 500 наружу фиксированный (сообщения ядра логируются, не отдаются).
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`. - Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»).
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — собственность `WordPdfValidator`; не оборачивать в общий `ConversionException`. - Логирование по пакетам: `java.util.logging` — корневой пакет и `internal/` (`WordPdfConverter`, `OleObjectNormalizer`, `DocToDocx`); SLF4J — `internal/chart` (`ChartRenderer`, `DrawingPreRenderer`) и `wordpdf-app`; остальное молчит.
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`. - Модели — `record` (`ConvertOptions`, `BundledFonts.Entry`, `MathRenderer.MathImage`, `ApiError`); константы UPPER_SNAKE с javadoc-обоснованием числа; holder-идиомы для ленивой инициализации (`VendoredXslt.TEMPLATES`); DCL+caches (`sharedFopFactory`, `GlyphFont.CACHE`); compile-time literals там, где важен инлайн (`WordPdfConverter` ↔ `WordPdfValidator`).
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`). - Шрифты: новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`); алиасы — `BundledFontAliases.ALIASES` (Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine, …; вынесено из `BundledFontMapper`, чтобы обращение к статикам не инициировало ungated-скан `BestMatchingMapper.<clinit>`), fallback — DejaVu Sans.
- Константы UPPER_SNAKE с эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`. - PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify`, `includeTests=true`, валит любой приоритет): правила не перенастраивать, подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены — нарушения чинятся кодом.
- Логирование: `java.util.logging.Logger` в корневом пакете и `internal/`, SLF4J — в `internal/chart` и `wordpdf-app`. - Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые `main`/`master`/`dev`; все правки — через PR в дефолтную ветку; push — только после `./mise.sh run verify`. Прод-координаты и креды в репо не попадают (Gitea Variables/Secrets — `GITEA-vars.md`; прод-ключ — только Gitea Secret; локальный `.env` gitignored, только для prod-like стенда).
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`), юниты — camelCase (`pageFieldBecomesFldSimple`); оба стиля разрешает PMD-паттерн `junit5TestPattern` (`^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$`).
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify` в обоих модулях, `includeTests=true`, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правило `LiteralFirstInEquals` и настройки — в самом ruleset.
## Runtime & Tooling ## Important Files
- Java 17 + Maven (обязательны; wrapper `mvnw` НЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml`; ежедневный запуск — `./mise.sh`. |Файл|Что держать в голове|
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement), новые — latest stable; закреплённый список — `docs/agent/repo-map.md`. Maven-зависимости — через Nexus `maven-central`: локально `~/.m2/settings.xml` (файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL`. |---|---|
- Фронт: Node из engines vite/oxlint, `npm ci` с закоммиченным `package-lock.json`, TS `strict` нигде не включён. Контейнеры (podman/buildah): `FROM` только FQDN, хостовые прокси-переменные обнулять на самой команде (`RUN`/`HEALTHCHECK`), `DOCKER_BUILDKIT=0` обязателен, fontconfig рантайму не нужен (глифы — fontbox). |`pom.xml` (корень)|единственное место версий (properties + dependencyManagement): docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox/fontbox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15, PMD-плагин 3.21.2; там же плагины: compiler 3.16.0, surefire 3.6.0 (`-Djava.awt.headless=true`), jar 3.5.1; пустой `<argLine/>` — ради `-Djacoco.skip=true`|
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только `java -jar`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`. |`wordpdf-core/src/main/java/.../WordPdfConverter.java`|весь конвейер, static-блок sysprops, пороги-константы, монитор сериализации|
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`. |`wordpdf-app/src/main/resources/application.properties`|multipart 100MB/100MB (зеркалит nginx `client_max_body_size`) + `file-size-threshold=2MB` (сброс больших частей на диск — защита от OOM), `convert-timeout=2m`, `api-key=` (пусто = auth off), `forward-headers-strategy=framework`; `wordpdf.max-mb`/`max-pages` здесь **не объявлять намеренно** — пустое значение затенит `@Value`-дефолты 5/100 (≤ 0 на старте → `IllegalStateException`)|
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}` (список — `GITEA-vars.md`). Локальный `.env` (gitignored) — только для `compose.yml`. |`wordpdf-core/pom.xml` / `wordpdf-app/pom.xml`|execution `test-jar`; BRANCH-гейт 0.85 (только core); exclusions: jeuclid (core), `slf4j-simple` (app); Boot-4 имена: `spring-boot-starter-webmvc` (не `-web`), отдельный `spring-boot-webmvc-test`; `repackage` привязан явно|
|`Containerfile` / `Containerfile.test` / `compose*.yml` / `gateway/nginx.conf`|прод-образ (heap 2G, mem_limit 3G, wget-healthcheck, FQDN FROM, non-root 10001, обнуление прокси на команде) / CI-гейт без fontconfig (Debian-база — alpine amd64-only; `SUREFIRE_OS_NAME` для macos-sim) / стенды :9010–:9011 / шлюз. Нюанс: repo `compose.yml` (prod-like) гасит springdoc env-ами и требует `.env`-ключ, а реальный прод из CI-рендера держит swagger открытым (`test_swagger_ui_open_without_key`) — не путать|
|`.gitea/workflows/pr.yml`, `main.yml`, `.ci/maven-settings.xml`|CI: jobs `java`/`web` в обоих — идентичные шаги, в `pr.yml` дополнительно `macos-sim` (те же тесты с `--build-arg SUREFIRE_OS_NAME="Mac OS X"`, только на PR, не required-гейт); `main.yml`: `images-* → deploy → autotests (+ rollback при failure)`; Maven в CI живёт в контейнере `maven:3.9-eclipse-temurin-17`; зеркало `${env.MAVEN_MIRROR_URL}`, `mirrorOf="*"`|
|`wordpdf-web/src/api.ts`, `vite.config.ts`|вся сеть SPA; `base` — только через env `VITE_BASE` (в прод-образ запекается `--build-arg VITE_BASE=/pdf-converter/` в job `images-web`)|
|`mise.toml`, `GITEA-vars.md`|пины инструментов и все таски / полный список Secrets+Variables CI и настройка branch protection|
## CI/CD (Gitea Actions) ## Runtime/Tooling Preferences
`pr.yml` (`PR checks`): job `java` (`mvn -B -s .ci/maven-settings.xml clean verify` через Nexus) + coverage-сводка и комментарий в PR, job `web` (`npm ci` → build → lint). `main.yml`: `java`/`web` → `images-app`/`images-web` (build+push в Nexus, теги `prod` + `sha-<7>`) → `deploy` (SSH, рендер прод-конфигов, гейты healthy) → `autotests` → `rollback` при провале. Нарратив — `docs/agent/ci-cd.md`. - Java 17 temurin + Maven 3.9.16 + Node 24 + Python 3.15 — пинины в `mise.toml`, всё через project-local mise (`./.mise/bin/mise`, вне системы); `mvnw` **нет** (`.mvn/` — пустой) — только Maven из mise. UTF-8.
- Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом `pom.xml`; FOP-форк отдельно не пинить; `commons-compress` не завышать (привязан к docx4j 17.3.2); `<repositories>` в pom не добавлять (зеркало — через settings).
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен. - Веб: только npm (`package-lock.json` закоммичен; никаких pnpm/yarn); линтер — oxlint (не eslint).
- Контейнеры: podman/buildah; `FROM` только FQDN; хостовые прокси-переменные обнулять на самой команде в `RUN`/`HEALTHCHECK`; `DOCKER_BUILDKIT=0` (CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox); alpine-теги maven/temurin amd64-only — тестовый образ на Debian-базе.
- Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx `resolver` привязан literal-ом к шлюзу сети — 10.113.0.1 стенды / 10.112.0.1 прод).
- Прод-стек (`docker-compose.yml`, `nginx.conf`) рендерится job'ом `deploy` из Variables — копий на хосте/в репо не заводить; required-контексты защиты `main` (по `GITEA-vars.md`) — буквально `PR checks / java (pull_request)`, `PR checks / web (pull_request)`; `macos-sim`, deploy/autotests — не required.
## Testing & QA ## 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` (`target/site/jacoco/`). Механика — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки. - Гейты на `verify`: PMD (движок 6.55.0 — default внутри maven-pmd-plugin 3.21.2, отдельно в pom не пинится; осознанный откат — ruleset использует удалённые в PMD 7 `*MustUseBraces`; подавлений в коде нет и быть не должно) + JaCoCo: LINE ≥ 0.90 оба модуля, BRANCH ≥ 0.85 только core; при провале отчёт уже в `target/site/jacoco/` (`report` привязан до `check`). CI-эквивалент — `./mise.sh run verify-nofontconfig`.
- Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`. - Стек: JUnit 6 (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ запрещены и в pom их нет; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` (полностью квалифицирован, без импортов) в `andExpect`; app не объявляет junit сам — только через `spring-boot-starter-test`. Тестовые классы package-private, зеркалят main-пакеты; только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов и `@AfterEach drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры — `.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`. - Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`), юниты — camelCase (`pageFieldBecomesFldSimple`).
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`. - **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа, живёт только в `WordPdfConverterTest`). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10, эталонные числа Word-рендеров 300 dpi захардкожены). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%PDF".equals(…)`).
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`. - Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать** (все 12 `.doc` — эталоны заказчика, не вывод генераторов).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре контекста (отдельные классы, не `@Nested`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Core-юниты Spring **не поднимают**; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали — `docs/agent/testing.md`. - Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar).
- Жизненный цикл: только `@Test`; исключения — два `@BeforeAll` (прогрев шрифтов) и `@AfterEach drainWorker` в `ConversionTimeoutTest`. Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`. - App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой `.env` в окружение задач — ambient `WORDPDF_API_KEY` взорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста.
- Идиомы загрузки фикстур: **core** — classloader без ведущего слэша, **app** — class-relative со слэшем (core test-jar). Синтетика: docx — `ZipOutputStream`, `.doc` — крафт `POIFSFileSystem`. - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1023 теста (core 57/975, app 6/48); детали — `docs/agent/testing.md`.
- Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (`"%PDF".equals(...)`, PMD `LiteralFirstInEquals`); контракт идентичности — `assertSame`/`assertNotSame`. Общих test-util-классов нет: хелперы (`norm`, `pdfText`, `assertRatio`) намеренно продублированы. - Прод-автотесты: pytest 9.1.1 + requests 2.34.2 (timeout `(10,180)` — больше серверных 2m), конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key`-декоратор `skipif` (немаркированный marker — маркеры не регистрируются) даёт SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда 5/100, `WORDPDF_SAMPLES_DIR` — путь к фикстурам); запуск `./mise.sh run prod-tests` либо job `autotests` в CI.
- Прод-автотесты: pytest + requests; под маркером `needs_key` без ключа SKIP; конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен).
- `mvn test` **не** запускает PMD и JaCoCo-гейты (оба на `verify`) — «зелёное» состояние проверяется `mvn clean verify`. `mvn -pl wordpdf-app` без `-am` падает: app зависит от core test-jar.
+1 -1
View File
@@ -37,5 +37,5 @@ USER app
EXPOSE 8080 EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=5 \ HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=5 \
CMD HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= wget -qO /dev/null http://127.0.0.1:8080/actuator/health || exit 1 CMD HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= wget -qO /dev/null http://127.0.0.1:8080/actuator/health || exit 1
ENTRYPOINT ["java", "-Djava.awt.headless=true", "-XX:MaxRAMPercentage=70", "-jar", "/app/app.jar"] ENTRYPOINT ["java", "-Djava.awt.headless=true", "-Xms2g", "-Xmx2g", "-jar", "/app/app.jar"]
+60
View File
@@ -0,0 +1,60 @@
# Тестовый образ «без fontconfig»: единственный полный прогон mvn clean verify
# (тесты + PMD + JaCoCo) там, где AWT-менеджер шрифтов недоступен (нет
# libfontconfig и /etc/fonts). В CI хостовый mvn не запускается вовсе — набор
# тестов никогда не исполняется на хосте с fontconfig. Локально сырой
# `mvn clean verify` (mise-задача verify) — хост-гейт без docker/podman.
# База — maven:3.9-eclipse-temurin-17, а не alpine: alpine-теги maven/temurin
# публикуются только под amd64, на arm64-хосте образ не собрать.
FROM docker.io/library/maven:3.9-eclipse-temurin-17
WORKDIR /build
# Удаляем fontconfig и системные шрифты; проверяем, что удалить удалось.
RUN set -eux; \
rm -rf /etc/fonts /usr/share/fonts /var/cache/fontconfig; \
find /usr/lib /lib -name 'libfontconfig.so*' -delete 2>/dev/null || true; \
if [ -e /etc/fonts ] || find /usr/lib /lib -name 'libfontconfig.so*' | grep -q .; then \
echo 'fontconfig остался в тестовом образе' >&2; exit 1; fi
# Жёсткий гейт: проба ядра (та же, что в MathMlSupport) обязана падать.
RUN set -eux; mkdir -p /tmp/probe; \
printf '%s\n' \
'public class Probe {' \
' public static void main(String[] a) {' \
' try {' \
' java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment()' \
' .getAvailableFontFamilyNames();' \
' System.exit(0);' \
' } catch (Throwable t) {' \
' System.exit(1);' \
' }' \
' }' \
'}' > /tmp/probe/Probe.java; \
javac -d /tmp/probe /tmp/probe/Probe.java; \
if java -Djava.awt.headless=true -cp /tmp/probe Probe; then \
echo 'AWT-шрифты доступны: fontconfig не удалён' >&2; exit 1; fi; \
echo 'fontconfig отсутствует: AWT-шрифты недоступны (ожидаемо)'; \
rm -rf /tmp/probe
# Зеркало Nexus (в CI приходит --build-arg MAVEN_MIRROR_URL из Gitea Variable).
ARG MAVEN_MIRROR_URL=
ENV MAVEN_MIRROR_URL=${MAVEN_MIRROR_URL}
COPY .ci/maven-settings.xml /tmp/ci-maven-settings.xml
RUN if [ -n "$MAVEN_MIRROR_URL" ]; then mkdir -p /root/.m2 && cp /tmp/ci-maven-settings.xml /root/.m2/settings.xml; fi
COPY pom.xml .
COPY wordpdf-core/pom.xml wordpdf-core/
COPY wordpdf-app/pom.xml wordpdf-app/
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= mvn -B -q dependency:go-offline
COPY . .
# Эмуляция чужой ОС в fork-нутом surefire-JVM: пусто (дефолт) — прежнее
# поведение (одна команда mvn, байт-в-байт как раньше); job `macos-sim` передаёт
# "Mac OS X" (docx4j PhysicalFonts читает os.name и уходит в
# MicrosoftFontsRegistry.getMsFonts()).
# Флаг на команде mvn попадает и в саму Maven-JVM: в Linux-JDK нет
# jdk/net/MacOSXSocketOptions, и первая же сетевая загрузка (surefire-провайдер,
# optional-зависимости, PMD-скин — всё, что НЕ закрыто dependency:go-offline)
# упала бы AssertionError на создании сокета. Поэтому при непустом флаге первым
# проходит полный verify БЕЗ флага — он догревает локальный репозиторий до нуля
# загрузок, и второй verify с флагом уже не открывает сокетов вовсе. Пустой флаг
# = один verify, прежний путь.
ARG SUREFIRE_OS_NAME=
RUN echo "SUREFIRE_OS_NAME=[${SUREFIRE_OS_NAME}]" && \
HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= \
sh -c '[ -z "$SUREFIRE_OS_NAME" ] || mvn -B -q clean verify || exit 1; \
exec mvn -B clean verify ${SUREFIRE_OS_NAME:+-Dos.name="$SUREFIRE_OS_NAME"}'
+32 -319
View File
@@ -6,22 +6,6 @@
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере). шрифтов, установленных в системе (работает «из коробки» на голом сервере).
## Возможности
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются
в docx4j/FOP.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
(см. «Шрифты» ниже).
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки,
картинки — собственный мост `internal/doc` без внешних зависимостей;
error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры
уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
и веб-интерфейс (`wordpdf-web`, React SPA).
## Структура ## Структура
``` ```
@@ -31,327 +15,56 @@ java-word-pdf/
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven) └── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
``` ```
Ключевые классы (`wordpdf-core`): ## Быстрый старт
|Класс|Назначение| Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24,
|---|---| python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA:
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`checkPageCount`/`checkPageCountDoc`/`isBinaryDoc`/`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.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|правила 1–10 нормализации XML-частей одним zip-проходом (+ `OleObjectNormalizer`, правило 11)|
|`ru.pjandro.wordpdf.internal.doc.DocToDocx`|мост бинарного `.doc` → in-memory `.docx` (`convert`/`countPages`)|
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
## Инструменты проекта (mise)
Java, Maven, Node и Python для разработки ставит project-local mise: сам бинарь —
в `./.mise/bin` (gitignored), кеш инструментов — в user-директории mise, в систему
ничего не устанавливается. Версии зафиксированы в корневом `mise.toml`
(temurin-17, maven 3.9.16, node 24, python 3.15).
Первая настройка — скачивает mise, ставит инструменты и делает `npm ci` SPA:
```bash ```bash
sh bootstrap.sh # Linux / macOS sh bootstrap.sh # Linux / macOS
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
``` ```
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows): Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
```bash ```bash
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo ./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH ./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен
./mise.sh tasks # список задач с описаниями curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
``` ```
Задачи проекта (`./mise.sh run <задача>`): Стенды на контейнерах (podman), наружный вход — только nginx-gateway:
```bash
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build # prod-like :9010 (fail-closed: без ключа не встанет)
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev :9011, без ключа
```
## Задачи проекта (`./mise.sh run <задача>`)
|Задача|Содержание| |Задача|Содержание|
|---|---| |---|---|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo| |`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|`app-package`|исполняемый jar бэкенда| |`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)| |`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|`web-install`|`npm ci` в `wordpdf-web`| |`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080|
|`web-build`|гейт SPA: `tsc -b && vite build`| |`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173|
|`web-lint`|oxlint|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`| |`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|`docs-install` / `docs-serve` / `docs-build`|сайт документации: venv+pip / preview :8000 / strict-сборка в `site/`|
|`docs-javadoc` / `docs-deploy`|javadoc core / публикация сайта на rpi (:9012)|
Альтернатива обёртке — активировать mise в шелле и работать напрямую Альтернатива обёртке — активировать mise в шелле и работать напрямую
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`. (`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
## Сборка ## Документация
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`** - **Сайт документации** (пользователю / REST API / библиотека / архитектура /
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise разработчику / эксплуатация): `http://192.168.88.23:9012/`
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через — исходники в `docs/`, публикация `./mise.sh run docs-deploy`,
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле. javadoc — там же по `/apidocs/`.
- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`.
```bash - Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge,
mvn clean verify # все модули + тесты chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда форматов — `docs/standards/`.
``` - Правила репозитория — `AGENTS.md`.
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`).
## Использование
### REST API
```bash
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
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 или .doc) и синхронно
возвращает байты 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 в теле ответа|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|401|нет или неверен `X-API-Key`|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|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": "..."}`. Конвертации сериализуются одним воркером: ядро
мутирует глобальный реестр шрифтов; головой очереди на старте стоит `warmup()` —
первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с).
Интерактивная документация: 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
import ru.pjandro.wordpdf.WordPdfConverter;
import ru.pjandro.wordpdf.ConvertOptions;
import java.nio.file.Files;
import java.nio.file.Path;
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
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);
```
Ошибки валидации (содержимое не `.docx`/не `.doc` по сигнатуре, размер больше
5 МБ, страниц больше ста, зашифрованный `.doc`) бросают `ValidationException`
(подтип `ConversionException`). Формат определяется по сигнатуре байтов:
`PK\x03\x04` → .docx-путь, CFB-подпись `D0 CF 11 E0 A1 B1 1A E1` → мост → тот же
конвейер. Те же проверки без рендера доступны отдельно:
`WordPdfValidator.validate(bytes, options)`.
Работа с файлами — забота вызывающего: ядро пути не принимает.
#### Зависимость commons-compress (интеграция в чужой проект)
Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`,
рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в
classpath потребителя — `NoSuchMethodError:
org.apache.commons.compress.archivers.zip.ZipArchiveEntry
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`.
До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом,
объясняющим, какую версию закрепить.
**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress,
а `dependencyManagement` потребителя перекрывает транзитивные версии
(«nearest wins») — закреплять нужно именно в нём:
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-compress</artifactId>
<version>1.28.0</version>
</dependency>
</dependencies>
</dependencyManagement>
```
Диагностика: `mvn dependency:tree -Dincludes=org.apache.commons:commons-compress`.
**Gradle.** По умолчанию Gradle выбирает максимальную версию и конфликт
разрешает сам — guard не сработает и не нужен. Понижает версию только явный
`constraints` / `platform` / `resolutionStrategy`: уберите понижение либо
закрепите нужную версию:
```kotlin
dependencies {
constraints {
implementation("org.apache.commons:commons-compress:1.28.0")
}
}
```
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
### Веб-интерфейс и контейнеры (podman)
```bash
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build
```
Наружный вход — nginx-контейнер `gateway` на `http://localhost:9010/` (контейнер
`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 --force-recreate # http://<LAN-IP>:9011
```
(`--force-recreate` обязателен: без него podman-compose пересоберёт образ, но
контейнеры оставит на старом — будет крутиться jar прошлой сборки)
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
## Шрифты
В `wordpdf-core/src/main/resources/fonts/` упакованы 30 TTF: 7 текстовых
семейств по 4 начертания плюс два покрывающих шрифта (только regular):
| Семейство | Аналог MS-шрифта |
|---|---|
| Carlito | Calibri |
| Caladea | Cambria |
| Arimo | Arial |
| Tinos | Times New Roman |
| Cousine | Courier New |
| DejaVu Sans / DejaVu Serif | fallback |
| Noto Naskh Arabic | арабские дополнения U+07B1–U+08FF |
| Noto Sans Armenian | армянские знаки Unicode 16 |
`BundledFontMapper` подставляет метрически совместимые аналоги при конвертации
(`Calibri → Carlito` и т.д.). Нераспознанные шрифты и символы, не найденные в
шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в **DejaVu Sans**
(гарантированная кириллица). Знак, которого нет ни в шрифте ранa, ни там, куда
его отправил docx4j, ищет себе место сам: `GlyphCoverageNormalizer` режет такой
ран и для каждой части назначает покрывающее семейство — serif-раны в
**DejaVu Serif**, sans — в **DejaVu Sans**, экзотика — в Noto. Все шрифты
встраиваются в PDF как подмножества.
### Лицензии шрифтов
- Arimo, Cousine, Tinos, Carlito, Caladea — **SIL OFL 1.1**
(см. `fonts/FONT-LICENSE.txt`).
- DejaVu Sans / DejaVu Serif — **SIL OFL 1.1 / Bitstream Vera**
(см. `fonts/DejaVu-LICENSE.txt`).
- Noto Naskh Arabic, Noto Sans Armenian — **SIL OFL 1.1**
(см. `fonts/Noto-LICENSE.txt`).
## Как это работает
```
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx:
контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому
бинарному документу мостом) — `WordPdfValidator`, без зависимости от docx4j.
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — десять
правил (порядок значим): strict→transitional (`w:start`/`w:end`, проценты),
`on/off` → `true/false` (иначе docx4j теряет значение, и regular-раны
рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»),
поля `PAGE`/`NUMPAGES` → `w:fldSimple` (пересчитываются, а не печатают кэш
из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию
глифов), `w:jc` center/right + `w:tblInd` → абсолютный отступ таблицы,
`w:suff="space"` → пробел в номере списка, скрытые раны (`w:vanish`), руби
(надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11,
`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
3. Документ загружается в `WordprocessingMLPackage`, привязывается
`BundledFontMapper`.
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста
docx4j-export-fo с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
`w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer`
компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP`
(форк `docx4j-fo-renderer`) рендерит PDF, встраивая подмножества шрифтов.
## Ограничения
- Это **не** pixel-perfect рендер Word: раскладка, поля и некоторые эффекты
приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
- Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём
есть глиф, иначе — из fallback-семейства DejaVu.
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
остаётся `.notdef`. В эталонном экспорте Word (`develop/`, вне git) таких два — U+2188 (ↈ)
и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится
целиком на SIL OFL.
- Поддержка таблиц/изображений — базовая (через docx4j/FOP).
- Часть расхождений с Word — неустранимые невозможности FOP/docx4j
(`jc="distribute"`, `suff="tab"`, кернинг, `framePr`, кэш `REF`/`SEQ`/`TOC`,
надстрочница руби) — полный перечень с доказательствами:
`docs/agent/render-limitations.md`.
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
бинарного формата — уже растры, они вставляются картинками; EMF/WMF/PICT
пропускаются с warn.
## Тесты
Тесты используют 25 закоммиченных фикстур (13 `.docx` + 12 `.doc`) из
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
`./mise.sh run verify` (тесты + PMD + JaCoCo).
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
на тех же фикстурах — ядро отдаёт их 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-tests`: `pip install`
зависимостей + `pytest -q .` в `prod-autotests/`):
```bash
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests
```
31 проверка; без ключа 27 требующих его пропускаются.
+3 -2
View File
@@ -15,8 +15,9 @@ services:
app: app:
build: . build: .
restart: unless-stopped restart: unless-stopped
# Паритет с compose.yml: heap вписан в лимит (-XX:MaxRAMPercentage=70). # Паритет с compose.yml: фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT,
mem_limit: 2g # лимит 3g — запас под metaspace/потоки/native.
mem_limit: 3g
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI, # Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
# где поля healthcheck нет — без явного healthcheck depends_on # где поля healthcheck нет — без явного healthcheck depends_on
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде. # service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
+4 -3
View File
@@ -7,9 +7,10 @@ services:
app: app:
build: . build: .
restart: unless-stopped restart: unless-stopped
# Heap вписываем в лимит контейнера (-XX:MaxRAMPercentage=70 в ENTRYPOINT); # Фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT образа; лимит 3g — запас
# вход 16×5 МБ очередь + FOP-рендер в 2 ГБ помещаются. # под metaspace/потоки/native. Вход 16×5 МБ + FOP-рендер в 2 ГБ heap
mem_limit: 2g # помещаются.
mem_limit: 3g
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI, # Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
# где поля healthcheck нет — без явного healthcheck depends_on # где поля healthcheck нет — без явного healthcheck depends_on
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде. # service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
+190
View File
@@ -0,0 +1,190 @@
# Потребление памяти при конвертации doc/docx → pdf: аудит и результаты апгрейда (2026-11)
Харнес: `MemoryBench` (`wordpdf-core/src/test/java/ru/pjandro/wordpdf/MemoryBench.java`, test-scope) +
`membench.sh` + `./mise.sh run mem-bench`. Числа ниже получены на них; методология и ограничения — §1.
## 1. Методология измерения
JVM: temurin 17.0.21, флаги харнеса `-Xms64m -Xmx2g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError`
+ JFR `settings=profile` + `-Xlog:gc*=info,gc+heap=debug`. Машина — рабочая станция (amd64), не прод-контейнер.
Метрики на конвертацию (TSV-строки вывода харнеса):
|Метрика|Как снята|Смысл|
|---|---|---|
|`peak`|`MemoryPoolMXBean.getPeakUsage()` по хип-пулам с `reset()` перед каждой конвертацией|высокая вода кучи за конвертацию (включает невозвращённый мусор young-поколения — это мера запроса памяти, не live-сета)|
|`used`|сумма `getUsage().getUsed()` сразу после конвертации|куча «как есть» до ближайшего GC|
|`allocated-estimate`|GC-лог: выметенный Eden + humongous между паузами|честная оценка аллокаций (JFR-веса для этого не годятся — см. ограничения)|
|`max-live-after-gc`|GC-лог: максимум `M->M(after)` по паузам|живая куча после GC (включает конвертацию, идущую в момент паузы)|
|`VmHWM`|`/proc/self/status`|пик резидентной памяти процесса (куча + Metaspace + стеки + JFR-буферы)|
|`top-frames`/`app-sites`|агрегация `jdk.ObjectAllocationSample` из JFR|профиль аллокаций (относительная доля; веса — оценка сэмплера)|
Сценарии: `suite` — все 25 фикстур `samples/` (13 `.docx` + 12 `.doc`) циклами; `big` — синтетический
документ: `document.xml` фикстуры `ru-plain.docx` с повтором секции ×400 (≈1,6 МБ XML после
распаковки, ≈6000 строк контента, PDF ≈50 КБ/конвертация — много контента при малом in-put,
именно он и нагружает конвейер, а не байты входа).
Ограничения (важно для повторного прочтения чисел):
- **шум ±30% на фикстуру** между прогонами (старт нового JVM на сценарий, G1 растягивает young по
ходу прогона); сравнимы только суммарные/медианные агрегаты одного метода на одном железе;
- `peak` включает мусор: документ с большим churn даёт большой peak при малом live-сете;
- веса JFR `ObjectAllocationSample` (profile, period=20ms) — оценка сэмплера; абсолют — только GC-лог;
- фикстуры малы (вход ≤182 КБ, PDF в среднем 385 КБ): кандидаты, экономящие единицы мегабайт,
на них неотличимы от шума — это учитывалось в гейтах (§4).
Воспроизведение: `MB_LABEL=run ./mise.sh run mem-bench --scenario all --loops 20 | tee target/mem-run.txt`;
матрица флагов — через env `MB_JAVA_OPTS` (флаги идут после дефолтных и переопределяют их).
## 2. Baseline (до правок)
`MB_LABEL=before ./mise.sh run mem-bench --scenario all --loops 20` (JVM 17.0.21, пик 2026-11-17):
|Фикстура|n|peak p50, МБ|peak max, МБ|used avg, МБ|
|---|---|---|---|---|
|chart-types.docx|20|641|934|398|
|charts-smartart.doc|20|457|630|321|
|charts-smartart.docx|20|471|751|299|
|doc-formats.doc|20|261|783|326|
|en-plain.doc|20|302|819|273|
|en-plain.docx|20|278|855|298|
|exotic-glyphs.doc|20|328|907|325|
|exotic-glyphs.docx|20|312|950|287|
|ole-embedded.doc|20|298|540|238|
|ole-embedded.docx|20|269|574|222|
|page-numbers.doc|20|234|598|257|
|page-numbers.docx|20|272|558|266|
|ru-en-mixed.doc|20|300|453|293|
|ru-en-mixed.docx|20|344|528|298|
|ru-plain.doc|20|344|572|256|
|ru-plain.docx|20|281|455|274|
|ru-table-image.doc|20|331|462|267|
|ru-table-image.docx|20|299|522|263|
|ru-times.doc|20|275|561|275|
|ru-times.docx|20|251|580|256|
|stale-cache.doc|20|307|511|264|
|stale-cache.docx|20|323|525|269|
|symbol-bullets.docx|20|335|459|310|
|too-many-pages.doc|20|405|599|265|
|too-many-pages.docx|20|327|724|288|
|big (синтетика ×400)|5|924|976|360|
Итоги прогона: `allocated-estimate=36069MB` (≈71 МБ churn на конвертацию при медианном peak 300 МБ),
`max-live-after-gc=504MB`, паузы 536 шт./4815 мс; `VmHWM` процесса: 1,34 ГБ после suite-части,
1,56 ГБ после big-части (`-Xmx2g` доступен, куча растягивается под churn).
Главный вывод baseline: **память уходит не в копии документа, а в churn конвейера**. Вход 2,6–182 КБ
при peak 224–641 МБ — отношение долей порядка сотен. Профиль аллокаций (JFR, alloc-total —
оценка сэмплера 26,3 МБ взвешенных):
- доли приложения в топ-кадрах: `DocxRewritePipeline.normalize` — 0,44%, `WordPdfConverter.convert` —
0,36%, `GlyphFont.draw` — 0,10%; все остальные кадры `ru.pjandro.*` — ниже 0,1% (гейты §4);
- остальное — библиотеки: JAXB-андмаршалинг docx4j через DOM (`DOMScanner.visit/scan`,
`SAXOutput.getQName`, `NamespaceContextImpl.put`, `SAX2DOMEx.startElement`, `ClassFactory.create0`),
Xalan/XSLT, FOP (таблицы OpenType: `OTFAdvancedTypographicTableReader`, `OpenFont.readHorizontalMetrics`),
commons-io `IOUtils.byteArray`, `Arrays.copyOf`, `Throwable.fillInStackTrace` (docx4j использует
исключения как control flow — «Package field null» и т.п.);
- ~~JEuclid (`Parser.parseStreamSourceAsOdf`) — OMML-формулы на хосте с fontconfig (в CI/контейнере
иначе: MathFallback)~~ — **удалён из класса путей** (2026-11): jeuclid исключён exclusion'ом из
`docx4j-export-fo`, формулы рисует собственный `MathRenderer` (PNG, только бандл-шрифты);
`MathFallbackNormalizer` теперь деградирует в текст только конструкции вне `MathModel.SUPPORTED`.
## 3. Что нашли при чтении кода (архитектурные находки)
1. **FO материалзуется как `String`.** Форк `FORendererApacheFOP.convert(FODocumentHandler,
FOConverterContext, String)` (javap docx4j-export-fo 17.3.2) принимает весь выход XSLT одной
строкой UTF-16: для FO-документа это ≈2 байта/символ и FO в разы больше исходного XML.
Убрать можно только правкой форка (`templates.transform` стримом в FOP-парсер) — вне рамок
репозитория; фиделити-риск высокий. Дорожная карта.
2. **`disableFontCache()` в форке вызывается безусловно в 3 местах** (javap `FORendererApacheFOP`:
`FontManager.disableFontCache`), один участок защищён `Fop.isUseCache()` из fop.xconf
(по умолчанию кеш выключен) → таблицы шрифтов перечитываются на каждый рендер (видно в топ-кадрах).
Потенциальный рычаг (churn+CPU), но включение кеша влияет на сабзеттинг/метрики — только с
фиделити-прогоном, в форк/конфиг. Дорожная карта.
3. **`WordprocessingMLPackage` в docx4j 17.3.2 не имеет `close()`/`dispose()`** (javap пакета
`openpackaging.packages`/`parts` — только `setJaxbElement`/`unmarshal`): «освободить пакет явно»
API не даёт; пакет — локальная переменная `convertToStream` и умирает вместе со стеком.
4. **Валидатор делает два полных стриминговых прохода** по байтам входа (`checkPageCount` +
`checkDocxContainer`/`validate`): CPU, память O(8 КБ буферов) — на peak не влияет (§4, гейт E).
5. **Мост `.doc` уже отпускает потоки** (`releaseStreams`), но `DocxWriter.write` держит одновременно
`bodyXml`+`parts`+`hyperlinks` до `toByteArray()`; на фикстурах доля моста в аллокациях <0,15% —
не рычаг при текущих документах (§4, гейт C).
## 4. Кандидаты оптимизаций и гейты
Гейт: кандидат остаётся, только если после правки suite-сумма peak или big-peak улучшились ≥3%
(для «всегдашнего» A — плюс отсутствие регрессии); для B/C/E — плюс доля ≥5% в app-sites JFR.
Прогоны «до/после» — идентичной методикой, один и тот же компьютер, подряд.
|Кандидат|Доля в аллокациях (гейт 5%)|Замер после (гейт 3%)|Итог|
|---|---|---|---|
|A. Чанковый буфер PDF вместо `ByteArrayOutputStream`|—|`allocated` +0,7% (шум), сумма peak **+7,2% (хуже)**|отклонён, откачен|
|B. Needle-гейт декода в `DocxRewritePipeline`|`normalize` 0,44%|—|отклонён до правки|
|C. Ранний отпуск `bodyXml`/`parts`/`hyperlinks` в `DocxWriter.write`|кадров моста в топ-15 нет (<0,15%)|—|отклонён до правки|
|D. Явный release пакета docx4j|API отсутствует (§3.3)|—|нереализуем|
|E. Один проход валидатора|кадров валидатора в топ-15 нет (<0,1%)|—|отклонён до правки (плюс риск порядка ошибок — контракт 400-кодов)|
**Почему A отклонён измерением, хотя «в теории» экономит.** Реализация (`PdfOutputChunks`,
чанки вместо удваивающегося `byte[]`) протестирована на эквивалентность байтов и прогнана полным
бенчем (25 фикстур ×20 + big ×5, тот же метод):
- PDF фикстур в среднем 385 КБ: для них `PdfOutputChunks` с фиксированным чанком выделяет больше,
чем рост `ByteArrayOutputStream` от `Math.max(1<<16, docxBytes.length)` — сумма peak выросла на 7,2%;
- микробенч на 24 МБ (одноразовый `PeakProof`, куча 2г): peak 76 МБ у чанков против 61 МБ у BAOS —
чанк 1 МиБ на G1 humongous (регион 1 МиБ → 2 региона на чанк, отсюда ×2), чанк 256 КиБ уходит в
young и при подсчёте `peak` платит растянутым Eden; live-минимум чанков (P+P против 2–3P у BAOS)
выигрывает только на PDF десятки мегабайт, каких в фикстурах нет;
- вердикт гейта: не улучшено → откачен, конвейер остался на `ByteArrayOutputStream`.
**Итог по правкам ядра: ни один кандидат не прошёл гейт.** Это не «нечего улучшать», а «у текущих
документов память тратят библиотеки» (JAXB-via-DOM, XSLT, FOP-шрифты — §2; JEuclid больше
не потребитель — исключён из зависимостей): точечными
правками репозитория их не сократить, а правки библиотек/форка (FO-стриминг, font cache) —
отдельные задачи с фиделити-гейтом. Практический рычаг «потреблять меньше» прямо сейчас — размеры
кучи и GC (§5).
## 5. Матрица флагов JVM (итог: что ставить в прод)
Один и тот же прогон (`--scenario all --loops 5 --big-loops 2`), меняются только флаги
(`MB_JAVA_OPTS` поверх дефолта харнеса; для смены GC нужен и `-XX:-UseG1GC` — иначе старт падает
с «Multiple garbage collectors selected»). ВМ не кончалась ни на одном наборе, OOM'а нет нигде,
включая big-сценарий:
|Набор|VmHWM suite, МБ|VmHWM +big, МБ|max-live, МБ|Паузы (шт/мс)|Вывод|
|---|---|---|---|---|---|
|f1 — G1, `-Xmx2g` (дефолт харнеса; прод-Containerfile как раз `2G`/`mem_limit 3G`)|931|1337|575|159 / 1724|работает, но куча ×2,6 к реальной потребности|
|f2 — G1, `-Xmx768m`|802|902|451|183 / 1865|**рекомендуемый**: RSS ≤0,9 ГБ с JFR-буферами, запас к max-live 1,7×|
|f3 — G1, `-Xmx512m`|818|843|416|199 / 1877|работает, но max-live 416 из 512 — малый запас на chart-тяжёлые документы|
|f4 — Serial, `-Xmx512m`|748|748|482|126 / 4453|работает; паузы ×2,6 против G1|
|f5 — Serial, `-Xmx384m`|628|634|359|150 / 5803|максимальная плотность (RSS 0,63 ГБ); паузы ×3,4, max-live 359 из 384 — впритык|
`allocated-estimate` у Serial-прогонов — 0: awk-агрегатор GC-лога понимает G1-формат (регионы),
для Serial аллокации считаются по другому шаблону — на вывод матрицы не влияет.
Рекомендация прод-стеку (рендерится job'ом `deploy` из Gitea Variables — менять их, не репо):
1. Heap: `-Xmx768m` (f2) вместо `2G`; `mem_limit` — `1g` вместо `3G`. FopFactory/XSLT-кеш перманентны,
их размер от кучи не зависит; 451 МБ max-live — это ~3 конвертации chart-тяжёлых документов в полёте
(а конвертации сериализованы монитором — реально одна).
2. G1 оставить (~13 мс пауз на конвертацию против ~40 мс у Serial; при конвертациях 1–4 с это не
критично, но G1 при 768m ещё и ровнее ведёт humongous-аллокации растров чартов).
3. Плотность выше f2 (Serial 384m) достижима, но запас <7% к max-live на 384m — для прод-вариабельности
документов неприемлемо.
## 6. Итог апгрейда
- Ядро не изменено: ни один кандидат (A–E, §4) не прошёл замерный гейт; экономия памяти на текущих
документах лежит не в коде репозитория, а внутри JAXB/XSLT/FOP (§2–3). Правки форка
(FO-стриминг, font cache) — зафиксированные дорожные пункты с фиделити-гейтом.
- Практический эффект «потреблять меньше» — профиль кучи: `2G/3G → 768m/1g` (в ~3 раза меньше
резидентной памяти на стенде) без потери проходимости всех сценариев, включая big.
- Инфраструктура измерений осталась в репо: `MemoryBench` + `membench.sh` + `./mise.sh run mem-bench`
— любой следующий раунд начинается с baseline за 10 минут.
## 7. Как читать этот документ дальше
- Перепроверить числа: §1 (команды) — прогон ~10 мин, артефакты в `target/` и `wordpdf-core/target/membench-*.jfr`.
- Перед новым «починить память»: сначала топ-кадры собственного прогона — доли приложения ≤0,4% означают,
что чинить нужно библиотеки, а не `WordPdfConverter`.
- Стоп-лист § «не чинить» из `docs/agent/render-limitations.md` остаётся в силе: экономия памяти
не должна менять выход PDF (фиделити-тесты — единственный арбитр).
+1 -1
View File
@@ -4,7 +4,7 @@
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` (§21.2.2.7, `val` опущен — default true) применяется только при отсутствии `c:title` (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии `c:title` и `val=0` рисуется автозаголовок. Пустой/пробельный `c:title` (или `val=0` без `c:title`) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName`, `#deletedTitleWithText_stillShown`, `#deletedTitleValOmitted_stillShown`, `#multiSeriesDoughnut_placeholderNotSeriesName`, `#multiParagraphTitle_joinedWithNewlines`. Палитра `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` (§21.2.2.7, `val` опущен — default true) применяется только при отсутствии `c:title` (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии `c:title` и `val=0` рисуется автозаголовок. Пустой/пробельный `c:title` (или `val=0` без `c:title`) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName`, `#deletedTitleWithText_stillShown`, `#deletedTitleValOmitted_stillShown`, `#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`, шрифты через `BundledFontAliases.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
Защитные лимиты против враждебного chart-XML: `ChartSpec.MAX_POINTS = 100_000` (`c:pt/@idx` §21.2.2.150/.151, `c:ptCount` §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ `IllegalArgumentException` **до** предвыделения списка), `ChartRenderer.MAX_TICKS = 1000` (шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется `niceUnit` 1/2/5·10ⁿ), `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` (≈24″; при `cx/cy` вне капа объект **оставляется как есть** + warn, картинка не рендерится — регрессия `hugeExtentChart_removedNotOom`). Бросок перехватывает catch в `DrawingPreRenderer.renderChart` → штатная деградация «объект удалён + warn». Обход `pkg.getParts()` — только по **снимку** списка (вставка media-частей `addChartMedia→addPart→loadPart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, **не** `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`. Защитные лимиты против враждебного chart-XML: `ChartSpec.MAX_POINTS = 100_000` (`c:pt/@idx` §21.2.2.150/.151, `c:ptCount` §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ `IllegalArgumentException` **до** предвыделения списка), `ChartRenderer.MAX_TICKS = 1000` (шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется `niceUnit` 1/2/5·10ⁿ), `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` (≈24″; при `cx/cy` вне капа объект **оставляется как есть** + warn, картинка не рендерится — регрессия `hugeExtentChart_removedNotOom`). Бросок перехватывает catch в `DrawingPreRenderer.renderChart` → штатная деградация «объект удалён + warn». Обход `pkg.getParts()` — только по **снимку** списка (вставка media-частей `addChartMedia→addPart→loadPart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, **не** `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`.
+1 -1
View File
@@ -6,7 +6,7 @@
### Job'ы workflow'ов ### Job'ы workflow'ов
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера). Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом → единственный прогон `mvn -B clean verify` внутри образа `Containerfile.test` — без fontconfig, набор тестов никогда не исполняется на хосте с fontconfig; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; зеркало Nexus приходит `--build-arg` → извлечение двух `jacoco.xml` из образа `wordpdf-verify:ci` шагами `docker create`/`docker cp || true` — при непрошедшей сборке пустая сводка, тесты не затронуты) → `Coverage summary` (разбор извлечённого `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `macos-sim` — тот же образ `Containerfile.test`, собранный с `--build-arg SUREFIRE_OS_NAME="Mac OS X"` (эмуляция macOS: единственный хост-зависимый код — docx4j `PhysicalFonts`, читающий `os.name`; внутри образа набор исполняется дважды — сначала `verify` без флага догревает локальный репозиторий до нуля загрузок, затем `verify` с флагом, т.к. Linux-JVM с `os.name=Mac OS X` падает AssertionError на первом же сетевом сокете; шагов JaCoCo/комментария нет — дублировали бы `java`), в `main.yml` отсутствует намеренно. job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера).
`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway). `.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
File diff suppressed because one or more lines are too long
+16 -13
View File
@@ -6,40 +6,43 @@
|---|---|---| |---|---|---|
| 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j | | 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j |
| 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) | | 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)| |2|`DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load`|Один zip-проход переписывания XML-частей (правила 1–11 — раздел «Нормализаторы: контракт и правила 1–12» в этом файле) + условная OLE-вычистка (правило 12)|
| 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF | | 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF |
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) | | 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds`/`m:oMath` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет); формулы — собственный растер `MathModel`/`MathRenderer` (только бандл-шрифты, без AWT/JEuclid), inline-картинка опускается ран-`w:rPr/w:position` на свой нижний запас (FOP ставит инлайн-графику нижним краем на базу строки; регрессия — WordPdfConverterTest#ommlMathInline_sitsOnTextBaseline), неподдерживаемая конструкция — текстовая деградация + warn; budget chart/math-PNG общий |
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные | | 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные. Конфиг обязан быть **полным при каждом `declare`**: docx4j декларирует из `fontsInUse` только использованные начертания (или simulate-style на regular-файле), а общая `FopFactory` замораживает fopconf **первого** документа JVM — `declareFamily`+`hasRealFace` дополняют каждое семейство недостающими реальными начертаниями (регрессия — `fopFactoryFrozenFromFirstDoc_fontsComplete`) |
| 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` | | 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` |
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` | | 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
| 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF | | 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF |
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF | | 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
| 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти | | 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти |
`BundledFontMapper` переопределяет `getBoldForm`/`getItalicForm`/`getBoldItalicForm`: на macOS `PhysicalFonts.getBoldForm` для имён `Tinos Regular`/`Carlito Regular`/… уходит в `MicrosoftFontsRegistry` и возвращает `null` (у записей нет Mac-имени файла), из-за чего docx4j строил simulate-style fopconf — FOP терял реальные начертания и кернинг (регрессии `strictOoxml_convertsNotRejected`, `ruPlain_regularRunsUseRegularFont`). Override находит реальный вариант по `embeddedURI` regular-варианта.
### `warmup()` — прогрев ядра (шаги 0–7 на минимальном docx) ### `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`). Первая конвертация после старта 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 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита). Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись: zip `PK\x03\x04` или CFB `D0 CF 11 E0` → контейнер → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + разрывы 0x0C − непрерывные межсекционные (sprmSBkc 0/1) + sprmPFPageBreakBefore)` (код — `DocFile.countPages`). Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–11 число учитываемых разрывов не увеличивают (правило 10 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
- Страницы в валидаторе = `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-частей). - Страницы в валидаторе = `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-частей).
### Нормализаторы: контракт и правила 1–11 (детали) ### Нормализаторы: контракт и правила 1–12 (детали)
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Десять rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу `STEP` (`public static final DocxNormalizer`) выставляют девять из десяти (нет только у `RubyNormalizer` — он цепочный, подключается внутри пайплайна), у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`. Правила 1–10 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из `word/document.xml` извлекается полоса набора (`TableIndentNormalizer.bandOf`, −1 — полосы нет), и `word/headerN.xml`/`footerN.xml` дополнительно прогоняются через `TableIndentNormalizer.rewritePart` с этой полосой, и из `word/styles.xml` читается множество vanish-стилей (`HiddenTextNormalizer.vanishStyles`, цепочка `w:basedOn`) — контекст правила 9; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` десяти нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим: Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Одиннадцать rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу `STEP` (`public static final DocxNormalizer`) несёт только `DocxRewritePipeline` (собирает рерайты сам), у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`, а вместо `normalize(byte[])` у него `normalize(byte[], boolean)`. Правила 1–11 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из `word/document.xml` извлекается полоса набора (`TableIndentNormalizer.bandOf`, −1 — полосы нет), и `word/headerN.xml`/`footerN.xml` дополнительно прогоняются через `TableIndentNormalizer.rewritePart` с этой полосой, и из `word/styles.xml` читается множество vanish-стилей (`HiddenTextNormalizer.vanishStyles`, цепочка `w:basedOn`) — контекст правила 10; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` десяти нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим:
1. `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); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 1 §17.3.1.13: `jc val="end"` — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` переименовывается только внутри открывающего тега `w:ind` (MS-OI29500 §2.1.174a — псевдонимы left/right; у `w:pgNumType` `w:start` — старт нумерации страниц, легален в transitional, Part 1 §17.13.7 — не трогается) и не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`, `pgNumTypeStartAttrUntouched`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`). 1. `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); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 1 §17.3.1.13: `jc val="end"` — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` переименовывается только внутри открывающего тега `w:ind` (MS-OI29500 §2.1.44 — псевдонимы left/right; у `w:pgNumType` `w:start` — старт нумерации страниц, легален в transitional, Part 1 §17.13.4 — не трогается) и не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`, `pgNumTypeStartAttrUntouched`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`).
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается. 2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается.
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает `<w:sym>`, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x). 3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает `<w:sym>`, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x).
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются. 4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.
5. `InvisibleCharNormalizer` — вырезает из `w:t` U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D **не** трогает. 5. `InvisibleCharNormalizer` — вырезает из `w:t` U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D **не** трогает.
6. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans. 6. `MathFallbackNormalizer` — байтовый скан OMML-формул (§22.1) до загрузки пакета: формулы с конструкциями вне `MathModel.SUPPORTED` (или structurally битые) деградируют в текст — `m:oMathPara`/`m:oMath` → обычные раны с конкатенацией `m:t` (как в штатном фолбэке docx4j `XsltFOFunctions.mathText`); поддерживаемые части не трогаются (`rewrite` → `null`, тот же массив) — их рисует собственный `MathRenderer` на шаге 3.5. Позиция **до GlyphCoverage** обязательна: деградировавшие раны с математическими символами (U+1D400+) обязаны пройти резку по покрытию, иначе FOP рисует «#». `m:oMathPara` содержит `m:oMath`, поэтому блок para заменяется первым. Регрессия — WordPdfConverterTest#ommlUnsupported_degradesToText, юниты — MathFallbackNormalizerTest.
7. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — Part 1 §17.4.50, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right в transitional и `w:start`/`w:end` в strict; дефолты 11906/1440 — измеренное поведение docx4j, не ECMA-1800), T — Σ gridCol; пропускает несколько body-level `sectPr`, не-dxa `tblInd`, `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite`/`STEP` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord. 7. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans.
8. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; Part 1 §17.3.1.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace. 8. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — аудит раскладки ECMA-376, матрица B3, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right; у CT_PageMar полей `w:start`/`w:end` нет, полоса берётся из сырого document.xml до правила 1; дефолты 11906/1440 — измеренное поведение docx4j, ECMA дефолтов не фиксирует §17.6.11/.13), T — Σ gridCol; пропускает несколько body-level `sectPr`, `tblInd` с явным `w:type` ≠ dxa (опущенный type — dxa, §17.4.87), `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.
9. `HiddenTextNormalizer` — вырезание скрытых ранов (Part 1 §17.3.2.30): truthy `w:vanish` в собственном `w:rPr` ранa (обе OnOff-формы; вал опущен — default true) **или** `w:rStyle` ∈ vanish-стили из `word/styles.xml` (транзитивно по `w:basedOn`, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (`fldChar`/`instrText`/`footnoteReference`/`endnoteReference`/`drawing`/`pict`/`object`/`txbxContent`) не трогается — удаление спаренных `begin…separate…end` сломало бы поле. Word скрытое не печатает, стилист docx4j `vanish` не читает вовсе → без правила скрытое утекало в PDF. Индивидуальный `normalize()` — свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, юниты — HiddenTextNormalizerTest. 9. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; ST_LevelSuffix Part 1 §17.9.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
10. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.18/.19/.20/.21): `w:rubyBase`/`w:rubyBaseText` разворачиваются в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.2 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest. 10. `HiddenTextNormalizer` — вырезание скрытых ранов (Part 1 §17.3.2.41): truthy `w:vanish` в собственном `w:rPr` ранa (обе OnOff-формы; вал опущен — default true; явный `false/0/off` в ране **перекрывает** vanish-стиль) **или** `w:rStyle` ∈ vanish-стили из `word/styles.xml` (транзитивно по `w:basedOn`, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (`fldChar`/`instrText`/`footnoteReference`/`endnoteReference`/`drawing`/`pict`/`object`/`txbxContent`) не трогается — удаление спаренных `begin…separate…end` сломало бы поле. Word скрытое не печатает, стилист docx4j `vanish` не читает вовсе → без правила скрытое утекало в PDF. Индивидуальный `normalize()` — свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, #hiddenText_directVanishFalseOverridesStyle, юниты — HiddenTextNormalizerTest.
11. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `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-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `DrawingFoundException(OLE)`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет. 11. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.24–.28): снимается обёртка `w:ruby` (схемно-валидная транзишнл-разметка `w:r`→`w:ruby`→rubyPr/rt/rubyBase иначе достаёт catch-all-шаблону XSLT, и база теряется молча), `w:rubyBase` разворачивается в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.2 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.
12. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `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-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `OleFoundException`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет.
`mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»). `mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
+2 -2
View File
@@ -4,6 +4,6 @@
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно). - Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства `text-align-last` в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); `w:suff="tab"` и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 8, suff=nothing совпадает с docx4j — разделителя нет); абзац без `w:line` рендерится natural-высотой FOP 15.44pt@11pt, явный `lineRule="auto"` — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; обе величины считаются по метрикам шрифта); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy `kern`-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (`TextLayoutManager`→`Font.hasKerning`) читает только legacy `kern` и такие пары отбрасывает; свойства `kerning` в форке нет, порог `w:kern` через FO не выражается. Word кернит только при явно заданном `w:kern` в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19; при отсутствии `w:kern` Office не кернит — MS-OI29500 §21.1.2.3.9a) — по умолчанию совпадает с нами, расходится только для документов с явно заданным `w:kern`. Починено веткой layout-class-c: левый padding ячейки (`LayoutPostRenderer`, шаг 4.25), `w:tblInd` при `w:jc`≠left (правило 7), `w:suff="space"` (правило 8). - Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства `text-align-last` в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); `w:suff="tab"` и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 9, suff=nothing совпадает с docx4j — разделителя нет); абзац без `w:line` рендерится natural-высотой FOP 15.44pt@11pt, явный `lineRule="auto"` — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; обе величины считаются по метрикам шрифта); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy `kern`-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (`TextLayoutManager`→`Font.hasKerning`) читает только legacy `kern` и такие пары отбрасывает; свойства `kerning` в форке нет, порог `w:kern` через FO не выражается. Word кернит только при явно заданном `w:kern` в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19: кернинг применяется, только когда элемент задан; при отсутствии `w:kern` не кернит; MS-OI29500 §2.1.83 уточняет лишь диапазон `w:val`) — по умолчанию совпадает с нами, расходится только для документов с явно заданным `w:kern`. Починено веткой layout-class-c: левый padding ячейки (`LayoutPostRenderer`, шаг 4.25), `w:tblInd` при `w:jc`≠left (правило 8), `w:suff="space"` (правило 9).
- Аудит .docx-путей по ECMA-376 (2026-11) — запинено синтетикой (без фикстур): сноски/концевые сноски с номерами (§17.11), внешние гиперссылки с `/URI`-аннотацией (§17.12.23), `PAGEREF` (complex и вложенный в результат `TOC`) и `DATE` подменяют кэш живым значением, `titlePg` → first/default колонтитуки (§17.13.1.35), `vMerge` restart/continue (§17.4.70), block-level `w:sdt` (§17.5.2), `wps:txbx`-текст (§17.3.3.23), OMML-формулы рисуются вектором jeuclid-fop (§22.1 — текст из PDF не извлекается, пинь пикселями), фон `w:highlight`/`w:shd` рисуется (§17.3.2.16/.29). Скрытый текст `w:vanish` не печатается (правило 9); текст руби-базы и `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir` не теряется (правило 10 + AUDIT-FIX-2). Остаток (не чиним): `w:framePr` игнорируется — текст печатается в общем потоке, геометрия фрейма теряется (ни XSLT, ни `createBlockForPPr` не читают); `REF`/`SEQ`/литеральные записи `TOC` печатают устаревший кэш из docx (движка пересчёта нет; инстринции полей не печатаются); надстрочница руби не выводится (правило 10 печатает только базу — ruby-разметки в FOP нет); `w:ptab` без `@w:alignment`, `bar`, `list` теряются catch-all'ом; `w:bdo`/`w:dir` печатаются LTR (bidi вне контура). - Аудит .docx-путей по ECMA-376 (2026-11) — запинено синтетикой (без фикстур): сноски/концевые сноски с номерами (§17.11), внешние гиперссылки с `/URI`-аннотацией (§17.12.23), `PAGEREF` (complex и вложенный в результат `TOC`) и `DATE` подменяют кэш живым значением, `titlePg` → first/default колонтитуки (§17.10.6), `vMerge` restart/continue (§17.4.70), block-level `w:sdt` (§17.5.2), `wps:txbx`-текст (§17.3.3.23; формула внутри текстового бокса до растера не доходит — обход drawing-нагрузку не спускается и уходит в docx4j-фолбэк `mathText`, конкатенация `m:t`; регрессия — WordPdfConverterTest#drawingTextBoxMath_convertsViaDocx4jTextFallback), OMML-формулы (§22.1) рисует собственный растер `MathModel`/`MathRenderer` — PNG 300 dpi, только бандл-шрифты jar, без AWT/JEuclid (текст из PDF не извлекается, пинь пикселями); неподдерживаемая конструкция или превышение бюджета — текстовая деградация (конкатенация `m:t`, `MathFallbackNormalizer`, правило 6) + warn, inline-формула выравнивается по базовой линии текста (мат-ось Word — принятая деградация), `m:oMathPara` — отдельный центрированный абзац (left/right по `m:jc`, indentLeft→left); фон `w:highlight`/`w:shd` рисуется (§17.3.2.16/.29). Скрытый текст `w:vanish` не печатается (правило 10); текст руби-базы и `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir` не теряется (правило 11 + AUDIT-FIX-2). Остаток (не чиним): `w:framePr` игнорируется — текст печатается в общем потоке, геометрия фрейма теряется (ни XSLT, ни `createBlockForPPr` не читают); `REF`/`SEQ`/литеральные записи `TOC` печатают устаревший кэш из docx (движка пересчёта нет; инстринции полей не печатаются); надстрочница руби не выводится (правило 11 печатает только базу — ruby-разметки в FOP нет); `w:ptab` без `@w:alignment`, `bar`, `list` теряются catch-all'ом; `w:bdo`/`w:dir` печатаются LTR (bidi вне контура).
+17 -16
View File
@@ -4,18 +4,19 @@
| Путь | Назначение | | Путь | Назначение |
|---|---| |---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String[,ConvertOptions])`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `WordPdfSettings` (`MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_*=false`), `ConvertOptions` (record) | | `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String,ConvertOptions)`), `WordPdfValidator` (`checkInput`/`validate` наружу; `checkPageCount`/`checkPageCountDoc`/`isBinaryDoc` — package-private, всё без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `ChartsFoundException`/`SmartArtFoundException`/`OleFoundException` (по error-флагам), `ConvertOptions` (record; дефолтов в ядре нет). Пороги защиты — производные от лимитов входа: `WordPdfValidator.maxDecompressedBytes`/`maxDecompressedXmlBytes` (`max(MIN_*×MiB, maxMb×10/4MiB + maxPages×64/32KiB)`, крышек нет), `maxZipEntries` (`max(2048, maxMb×512 + maxPages×32)`), `maxImagePixels` (`maxMb×5_000_000`); коэффициенты и полы — package-private литералы `WordPdfConverter` (`DECOMPRESS_*`, `MIN_DECOMPRESSED_*`, `IMAGE_PIXELS_PER_MAX_MB`, `ZIP_ENTRIES_*`, javac их инлайнит — валидатор не инициализирует конвертер) |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `GlyphFont` (глиф-движок fontbox) | | `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontAliases` (алиасы, `DISPLAY_NAMES`, `bundledFamily` — без наследования, статика безопасна до гейта), `BundledFontMapper` (экземпляр-маппер docx4j), `GlyphFont` (глиф-движок fontbox) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` | | `…/wordpdf/internal/` | 12 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–11, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы package-private; `public` — `DocxNormalizer`, `DocxRewritePipeline` (наружу только `STEP`, `normalize` package-private), `OleObjectNormalizer`, `FopFallbackFonts` (`declare`), `LayoutPostRenderer` (`register`), `DependencyGuard` (`check`), остальные нормализаторы полностью package-private; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `OleFoundException` |
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) | | `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) |
| `…/wordpdf/internal/chart/` |18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: `DrawingPreRenderer.run` и `ChartImageHandler` — второй инстанцируется из `WordPdfConverter`)| | `…/wordpdf/internal/chart/` |21 классов Java2D-рендера диаграмм/SmartArt/OMML-формул в PNG (`MathModel`/`MathRenderer`/`MathUnsupportedException` — формулы); public: `DrawingPreRenderer.run` и `ChartImageHandler` — второй инстанцируется из `WordPdfConverter`|
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar | | `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar |
| `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патчи), часть jar | | `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патчи), часть jar |
| `wordpdf-core/src/test/resources/samples/` | 25 закоммиченных фикстур: 13 `.docx` + 12 `.doc` (11 эталонов заказчика из `develop/doc/` с теми же базовыми именами + `doc-formats.doc`); `.docx` проходят `docs/standards/docx/validate-fixtures.py`, `.doc` — бинарные, XSD к ним неприменим | | `wordpdf-core/src/test/resources/samples/` | 25 закоммиченных фикстур: 13 `.docx` + 12 `.doc` (11 эталонов заказчика из `develop/doc/` с теми же базовыми именами + `doc-formats.doc`); `.docx` проходят `docs/standards/docx/validate-fixtures.py`, `.doc` — бинарные, XSD к ним неприменим |
| `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) | | `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (11 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 5 классов исключений (`BadRequest`, `DrawingRejected`, `ConversionFailed`, `ConversionRejected`, `ConversionTimeout`) | | `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (11 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 5 классов исключений (`BadRequest`, `DrawingRejected`, `ConversionFailed`, `ConversionRejected`, `ConversionTimeout`) |
| `wordpdf-web/src/` | SPA: `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) | | `wordpdf-web/src/` | SPA: `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`, non-root uid 10001, `-XX:MaxRAMPercentage=70`, HEALTHCHECK — busybox `wget`); compose app+web+gateway (`mem_limit: 2g` app, подсеть `10.113.0.0/24` gw `10.113.0.1`, `x-podman.name_separator_compat`); прод-compose не в репо — его рендерит job `deploy`; в репо-`compose.yml` springdoc выключен env (`SPRINGDOC_API_DOCS_ENABLED=false`, `SPRINGDOC_SWAGGER_UI_ENABLED=false`), в `compose.dev.yml` springdoc-переменных нет вовсе — включён по умолчанию (не отключается). `wordpdf-web/Containerfile` — `node:24-alpine` → `nginx:alpine`, `ARG VITE_BASE=/` (прод-CI печёт `/pdf-converter/`); репозиторный `wordpdf-web/nginx.conf` в образ **не** копируется (SPA одностраничная, без клиентского роутинга — SPA-fallback не нужен) | | `wordpdf-web/nginx.conf` | В образ SPA (`Containerfile` COPY в `/etc/nginx/conf.d/default.conf` — переопределение default-сервера, отдельного монтирования нет): `try_files` SPA-fallback + `add_header ... always` (езжают и на 4xx/5xx): CSP `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'` (inline-стили React); `img-src`/`frame-src` + blob: (PDF-предпросмотр в iframe); `connect-src 'self'`; `object-src 'none'` + `nosniff`, XFO DENY (не мешает blob-iframe), Referrer-Policy no-referrer |
| корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf` | Образ бэкенда (multi-stage `maven:3.9-eclipse-temurin-17` → `eclipse-temurin:17-jre-alpine`, non-root uid 10001, фиксированный heap `-Xms2g -Xmx2g`, HEALTHCHECK — busybox `wget`); compose app+web+gateway (`mem_limit: 3g` app, подсеть `10.113.0.0/24` gw `10.113.0.1`, `x-podman.name_separator_compat`); прод-compose не в репо — его рендерит job `deploy`; в репо-`compose.yml` springdoc выключен env (`SPRINGDOC_API_DOCS_ENABLED=false`, `SPRINGDOC_SWAGGER_UI_ENABLED=false`), в `compose.dev.yml` springdoc-переменных нет вовсе — включён по умолчанию (не отключается). `wordpdf-web/Containerfile` — `node:24-alpine` → `nginx:alpine`, `ARG VITE_BASE=/` (прод-CI печёт `/pdf-converter/`); `wordpdf-web/nginx.conf` копируется в образ (см. строку выше) |
| `.env.example` | Шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (пустое значение ломает binding long/int). Проду `.env` не нужен — ключ и лимиты подаёт job `deploy` из Gitea Secrets/Variables | | `.env.example` | Шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (пустое значение ломает binding long/int). Проду `.env` не нужен — ключ и лимиты подаёт job `deploy` из Gitea Secrets/Variables |
| `.gitea/workflows/` | Gitea Actions: `pr.yml` (`PR checks`), `main.yml` (тесты + coverage-сводка и комментарий в PR → `images-app`/`images-web` (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback) | | `.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, защита ветки, перезапуск — только имена переменных, без значений | | `GITEA-vars.md` | Инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений |
@@ -28,16 +29,16 @@
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки). - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j). - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB = 5`, `MAX_PAGES = 100`, `ERROR_ON_* = false`); рантайм-конфигурации в ядре нет. - Дефолтов лимитов в ядре нет (`WordPdfSettings` упразднён): лимиты входа всегда приходят с вызовом через `ConvertOptions`, производные пороги считает `WordPdfValidator.max*` (см. таблицу выше).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt/OMML-формул на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера (формула — текст вместо удаления).
- `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/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-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). - `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`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.28.0`, JaCoCo `0.8.15`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`). - Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.21.2` (движок PMD `6.55.0`), JaCoCo `0.8.15`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`).
- `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions). - `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions).
- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg). - `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. - `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 до перезапуска). - `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 до перезапуска); `X-Forwarded-For`/`-Proto`/`-Host` переписываются безусловно (`$remote_addr`/`$scheme`/`$host` — клиент не подставляет доверяемые Spring заголовки; `X-Forwarded-Prefix` проходит как есть — на нём base swagger-ui за внешним прокси). Тот же набор в прод-ренвере job `deploy` (`main.yml`, heredoc `NGINX`).
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`. - `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`.
- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. Корневые `javac.*.args` — мусор пробной компиляции (gitignored), тоже кандидат на удаление. - `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. Корневые `javac.*.args` — мусор пробной компиляции (gitignored), тоже кандидат на удаление.
@@ -79,7 +80,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
## REST API (детали bullet'ов) ## REST API (детали bullet'ов)
Единственный эндпоинт `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`. Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `false`) и `maxMb`/`maxPages` (лимиты входа, см. «Лимиты входа» ниже). Ответ — `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`.
Полная карта ответов: Полная карта ответов:
@@ -95,8 +96,8 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
| 504 | `ConversionTimeoutException` | | 504 | `ConversionTimeoutException` |
- **Ключ доступа**: `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`) открытыми не считаются никогда. - **Ключ доступа**: `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` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. - **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **сериализует конвертации монитором класса `WordPdfConverter.class`**; однопоточность воркера — ради 503/timeout. Головой очереди конструктор ставит `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-дефолт. - **Лимиты входа**: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`) — дефолт эндпоинта, `@Value` в `ConvertController` с литеральными дефолтами 5/100; значение свойства ≤ 0 → `IllegalStateException` на старте. Параметры запроса `maxMb`/`maxPages` переопределяют дефолт в обе стороны (значения ≤ 0 → 400), верхнего серверного потолка нет — пороги распаковки/записей/растров растут вместе с ними. Ключи в `application.properties` **не объявлены** — пустое значение затенит дефолт `@Value`.
- **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` + текст зоны). - **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` + текст зоны).
@@ -104,11 +105,11 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
- **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 таблицах).
PMD: `failurePriority` в плагине не задан — на практике `verify` валит нарушение любой приоритетности; перечень исключённых правил в AGENTS.md не дублируется — единственный источник `pmd-ruleset.xml`. PMD: `failurePriority` в плагине не задан — на практике `verify` валит нарушение любой приоритетности; закрытый список правил — единственный источник `pmd-ruleset.xml` (в AGENTS.md не дублируется). Четыре правила `*MustUseBraces` деприкейтед в 6.55.0 — предупреждения «Discontinue using…» в логе verify ожидаемы.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; цепочка `WordPdfConverter.normalizers()` = `DocxRewritePipeline.STEP` (правила 1–10 одним zip-проходом) + лямбда `OleObjectNormalizer`; нечего менять → **тот же массив**; package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений; есть у 10 из 11 — у многочастного `OleObjectNormalizer` нет); у `StrictOoxmlNormalizer` есть также `rewritePart(entryName, xml)`, у `TableIndentNormalizer` — `rewritePart(name, xml, band)` (per-part-логика, хуки пайплайна); правятся только части `word/*.xml`. - Нормализаторы — единый контракт `internal/DocxNormalizer`; константа `STEP` только у `DocxRewritePipeline` (сам собирает цепочку); цепочка `WordPdfConverter.normalizers()` = `DocxRewritePipeline.STEP` (правила 1–11 одним zip-проходом) + лямбда `OleObjectNormalizer`; нечего менять → **тот же массив**; package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений; есть у 11 из 12 — у многочастного `OleObjectNormalizer` нет); у `StrictOoxmlNormalizer` есть также `rewritePart(entryName, xml)`, у `TableIndentNormalizer` — `rewritePart(name, xml, band)` (per-part-логика, хуки пайплайна); правятся только части `word/*.xml`.
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. - Классы в `internal` — package-private; `public` только контракт наружу: `DocxNormalizer`, `DocxRewritePipeline`(+`STEP`), `OleObjectNormalizer`, `FopFallbackFonts`(+`declare`), `LayoutPostRenderer`(+`register`), `DependencyGuard`(+`check`) и `DrawingPreRenderer`(+`run`); `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`) и защитные ветви сканеров нормализаторов/валидатора. - Гейт 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`) и защитные ветви сканеров нормализаторов/валидатора.
- Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. 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`). - Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. 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`).
@@ -120,4 +121,4 @@ PMD: `failurePriority` в плагине не задан — на практик
## Шрифты (детали) ## Шрифты (детали)
`DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFontMapper.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движком). `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF **напрямую из classpath** `fonts/<file>` (не из temp-каталога `BundledFonts`), кэш по `family/variant`, `of()` возвращает `null` для неизвестного семейства; `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D. `DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFontAliases.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart/math-движком и покрытием); вынесен из `BundledFontMapper`, чтобы обращение к статике не тянуло `BestMatchingMapper.<clinit>` (скан classpath вне гейта свойств `docx4j.fonts.discover*`, которые выставляет `WordPdfConverter.<clinit>`). `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF **напрямую из classpath** `fonts/<file>` (не из temp-каталога `BundledFonts`), кэш по `family/variant`, `of()` возвращает `null` для неизвестного семейства; `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D.
+3 -3
View File
@@ -2,7 +2,7 @@
### Счётчики (2026-11) ### Счётчики (2026-11)
- 59 тестовых классов / 898 тестов: core 53/849 (`internal/doc/` 17/225, `internal/chart/` 17/271, `WordPdfConverterTest` 77), app 6/49 (ConvertController 23, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 5, ConversionTimeout 3). Обновлять при изменении набора. - 63 тестовых классов / 1023 теста: core 57/975 (`internal/doc/` 17/256, `internal/chart/` 18/311, `WordPdfConverterTest` 89), app 6/48 (ConvertController 26, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 3, ConversionTimeout 1). Обновлять при изменении набора.
### Пиксели, метрики шрифтов, стенд без fontconfig ### Пиксели, метрики шрифтов, стенд без fontconfig
@@ -20,7 +20,7 @@
- Юниты моста (`internal/doc/`): `CfbReaderTest` строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); `SummaryInfoTest` — крафтовый PropertySetStream (пинит **относительность offset от начала PropertySet**, реальные фикстуры её не различают); `PieceTableTest`/`ChpxIndexTest`/`PapxIndexTest` (в т.ч. `istdFor`: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → дефолтные свойства при сохранённой границе)/`SectionsTest`/`FibHeaderTest` (пара fcStshf)/`GrpprlTest` (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (`scan_pChgTabsSentinel_lengthByFormula`))/`FontTableTest`/`HeadersTest`/`OfficeArtTest`/`PrcDataTest` — byte[]-конструкции in memory (`PrcDataTest`: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); `StylesTest` — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; `TablesTest` — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; `ListsTest` — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → `%{n+1}` и литеральный `%` → `%%`, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→`w:suff`, grpprl уровня → `w:ind`/`w:rFonts`, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); `DocToDocxFormattingTest` — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (`styleTabsChg_reachesFooterPart`/`styleTabsChgDel_removesStop`: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (`footerTable_jcCenterEmitted`: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: `listParagraphs_getNumPrAndNumberingPart` (sprmPIlfo/sprmPIlvl в PAPX → `w:numPr` + `word/numbering.xml` c `w:num`/Override/rels), `listCancelledByDirectZero_noNumPr` (ilfo стиля, перекрытый прямым 0), `ilvlSkipValue_noNumPr` (ilvl=0x0C), `missingListTables_degradeToPlain` (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: `assertCyrillicAndStyles`/`assertPageNumbers`/`assertTableImage`/`assertOleObjectsRemoved`/`assertDrawingsBecomeImages`/`assertTooManyPages`/`assertExoticGlyphs` вызываются с `ru-plain.doc`/`page-numbers.doc`/`ru-table-image.doc`/`ole-embedded.doc`/`charts-smartart.doc`/`too-many-pages.doc`/`exotic-glyphs.doc` (тесты-пары называются по docx-имени, внутри зовут оба формата); `WordPdfValidatorTest#checkPageCountDoc_*` + `ConvertControllerTest` (`.doc` upload, `nonDocxFilename_rejected`). - Юниты моста (`internal/doc/`): `CfbReaderTest` строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); `SummaryInfoTest` — крафтовый PropertySetStream (пинит **относительность offset от начала PropertySet**, реальные фикстуры её не различают); `PieceTableTest`/`ChpxIndexTest`/`PapxIndexTest` (в т.ч. `istdFor`: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → дефолтные свойства при сохранённой границе)/`SectionsTest`/`FibHeaderTest` (пара fcStshf)/`GrpprlTest` (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (`scan_pChgTabsSentinel_lengthByFormula`))/`FontTableTest`/`HeadersTest`/`OfficeArtTest`/`PrcDataTest` — byte[]-конструкции in memory (`PrcDataTest`: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); `StylesTest` — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; `TablesTest` — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; `ListsTest` — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → `%{n+1}` и литеральный `%` → `%%`, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→`w:suff`, grpprl уровня → `w:ind`/`w:rFonts`, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); `DocToDocxFormattingTest` — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (`styleTabsChg_reachesFooterPart`/`styleTabsChgDel_removesStop`: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (`footerTable_jcCenterEmitted`: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: `listParagraphs_getNumPrAndNumberingPart` (sprmPIlfo/sprmPIlvl в PAPX → `w:numPr` + `word/numbering.xml` c `w:num`/Override/rels), `listCancelledByDirectZero_noNumPr` (ilfo стиля, перекрытый прямым 0), `ilvlSkipValue_noNumPr` (ilvl=0x0C), `missingListTables_degradeToPlain` (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: `assertCyrillicAndStyles`/`assertPageNumbers`/`assertTableImage`/`assertOleObjectsRemoved`/`assertDrawingsBecomeImages`/`assertTooManyPages`/`assertExoticGlyphs` вызываются с `ru-plain.doc`/`page-numbers.doc`/`ru-table-image.doc`/`ole-embedded.doc`/`charts-smartart.doc`/`too-many-pages.doc`/`exotic-glyphs.doc` (тесты-пары называются по docx-имени, внутри зовут оба формата); `WordPdfValidatorTest#checkPageCountDoc_*` + `ConvertControllerTest` (`.doc` upload, `nonDocxFilename_rejected`).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` max-mb/max-pages), `ConversionTimeoutTest` (`@TestPropertySource` convert-timeout=1ms) — четыре разных набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста (прямые юниты). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре контекста — `ConvertControllerTest` (пин `wordpdf.api-key=` — HTTP-контексты явно пиныт пустой ключ: mise подмешивает корневой `.env` в окружение тасок, ambient `WORDPDF_API_KEY` иначе дал бы 401 во всех MockMvc-тестах), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` max-mb/max-pages), `ConversionTimeoutTest` (`@TestPropertySource` convert-timeout=1ms) — четыре разных набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста (прямые юниты).
- 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, 31 проверка — 27 под маркером `needs_key` (SKIP без ключа; включая `.doc`-фикстуры обоих путей — растры/OLE и границы страниц), 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, 31 проверка — 27 под маркером `needs_key` (SKIP без ключа; включая `.doc`-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода.
@@ -31,5 +31,5 @@
- `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается. - `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается.
- `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде docx4j — перевендорить и перенести патчи). - `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде docx4j — перевендорить и перенести патчи).
- Крафт POIFS (закоммиченных фикстур нет, крафт продублирован в `WordPdfConverterTest`): `ListsTest`+`DocToDocxFormattingTest#list*`↔`docLists_numberingAndBulletsRendered` (синтетический .doc со списками → PDF: `1.` `2.` `a)` `b)` `•`, ни одного `#`; фикстур со списками нет — крафт POIFS продублирован в `WordPdfConverterTest`), `PrcDataTest`+`DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` (TTP-абзац с grpprl в PrcData Data-потока → `w:tbl`/`w:tr`/сетка из цепочки; фикстуры нет — `docTest.doc` заказчика не коммитим, крафт POIFS продублирован), `SectionsTest`+`HeadersTest`+`DocToDocxFormattingTest#twoSections*/sectionBreakInTable*`↔`docMultiSection_perSectionHeaders` (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной `#`; крафт POIFS продублирован в `WordPdfConverterTest`), `ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept`+`DocToDocxFormattingTest#runFlags_*/keepNextKeepLines_*/sectLandscapePgNumCols_*/sectUnevenCols_*/cellVertAlign_*/drawnObject_*`+`SectionsTest#orientationPgNumColumns_applied/unevenColumns_perIndexWidths/restartWithoutStart_clampsToOne`+`TablesTest#vertAlign_*`↔`WordPdfConverterTest#docClassD_landscapeHiddenDelCaps/#docClassD_pageNumberRestartLowerRoman/#docClassD_twoColumnsBreak/#docClassD_drawnObjectBecomesImage` (закрытие пробелов класса D: vanish-фильтр/правки/caps/position/keep, landscape+pgNumType, колонки+column break, vAlign, 0x08→inline-картинка; фикстур нет — крафт POIFS продублирован в обоих тестовых классах). - Крафт POIFS (закоммиченных фикстур нет, крафт продублирован в `WordPdfConverterTest`): `ListsTest`+`DocToDocxFormattingTest#list*`↔`docLists_numberingAndBulletsRendered` (синтетический .doc со списками → PDF: `1.` `2.` `a)` `b)` `•`, ни одного `#`; фикстур со списками нет — крафт POIFS продублирован в `WordPdfConverterTest`), `PrcDataTest`+`DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` (TTP-абзац с grpprl в PrcData Data-потока → `w:tbl`/`w:tr`/сетка из цепочки; фикстуры нет — `docTest.doc` заказчика не коммитим, крафт POIFS продублирован), `SectionsTest`+`HeadersTest`+`DocToDocxFormattingTest#twoSections*/sectionBreakInTable*`↔`docMultiSection_perSectionHeaders` (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной `#`; крафт POIFS продублирован в `WordPdfConverterTest`), `ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept`+`DocToDocxFormattingTest#runFlags_*/keepNextKeepLines_*/sectLandscapePgNumCols_*/sectUnevenCols_*/cellVertAlign_*/drawnObject_*`+`SectionsTest#orientationPgNumColumns_applied/unevenColumns_perIndexWidths/restartWithoutStart_clampsToOne`+`TablesTest#vertAlign_*`↔`WordPdfConverterTest#docClassD_landscapeHiddenDelCaps/#docClassD_pageNumberRestartLowerRoman/#docClassD_twoColumnsBreak/#docClassD_drawnObjectBecomesImage` (закрытие пробелов класса D: vanish-фильтр/правки/caps/position/keep, landscape+pgNumType, колонки+column break, vAlign, 0x08→inline-картинка; фикстур нет — крафт POIFS продублирован в обоих тестовых классах).
- Синтетика через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`: AUDIT-FIX-2↔`movedRevision_textPrinted`/`bdoDir_textPrinted` (фикстур нет — синтетический docx через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`); пиннинг аудита .docx↔`footnote_rendersAtPageBottom`, `endnote_rendersAtDocumentEnd`, `docxHyperlink_uriAnnotation`, `pageRefField_liveNotCached` (кэш 9001/7777 заменён живым номером), `dateField_notStaleCache` (кэш 01.02.2003 заменён текущей датой), `titlePg_firstPageHeader`, `vMergeCell_spansRows`, `sdtContent_rendered`, `drawingTextBox_textPrinted`, `ommlMath_drawnAsVectors` (пиксели: +150 тёмных px@150dpi сверх текста), `highlightAndShading_backgroundDrawn` (жёлтые px >0 против baseline 0), аудит [MS-DOC] моста 2026-11: `GrpprlTest#tInsertOperand_skippedBySpra`/`tInsertOperand_truncated_aborts` (sprmTInsert — 4 байта, хвост TAP не рассинхронизирован), `TablesTest#cellPadding_*` + `DocToDocxFormattingTest#cellMargins_becomeTcMar` ↔ `WordPdfConverterTest#tableTcMar_textInsetLikeWord` (CSSA→w:tcMar, пайплайн красит поля ячейки как tblCellMar — текст на margin+padding), `StylesTest#characterStyle_stk3_chainViaCharChain`/`charChain_nonCharacterStk_empty` + `DocToDocxFormattingTest#charStyle_viaIstd_mergesUnderDirect` (sprmCIstd: символьная chpx-цепочка между стилевой и прямыми, direct wins), `DocToDocxFormattingTest#runHighlightAndShading_inRPr`/`runShadingPattern_degradesToBackFill`/`paraShd_inPPrBeforeJc` ↔ `docHighlightAndShading_yellowPixels` (Ico→ST_HighlightColor; w:shd в форме FOP val="clear"+fill; паттерн→cvBack), `SectionsTest#titlePage_flagFromSepx` + `DocToDocxFormattingTest#titlePage_emittedAfterCols` ↔ `docTitlePage_firstHeaderOnlyFirstPage` (sprmSFTitlePage + first-слоты Plcfhdd → headerReference type="first", первая страница — только first-шапка).. - Синтетика через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`: AUDIT-FIX-2↔`movedRevision_textPrinted`/`bdoDir_textPrinted` (фикстур нет — синтетический docx через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`); пиннинг аудита .docx↔`footnote_rendersAtPageBottom`, `endnote_rendersAtDocumentEnd`, `docxHyperlink_uriAnnotation`, `pageRefField_liveNotCached` (кэш 9001/7777 заменён живым номером), `dateField_notStaleCache` (кэш 01.02.2003 заменён текущей датой), `titlePg_firstPageHeader`, `vMergeCell_spansRows`, `sdtContent_rendered`, `drawingTextBox_textPrinted`, `ommlMath_drawnAsRaster` (пиксели: +150 тёмных px@150dpi сверх текста, текст формулы не извлекается), `ommlUnsupported_degradesToText`, `highlightAndShading_backgroundDrawn` (жёлтые px >0 против baseline 0), аудит [MS-DOC] моста 2026-11: `GrpprlTest#tInsertOperand_skippedBySpra`/`tInsertOperand_truncated_aborts` (sprmTInsert — 4 байта, хвост TAP не рассинхронизирован), `TablesTest#cellPadding_*` + `DocToDocxFormattingTest#cellMargins_becomeTcMar` ↔ `WordPdfConverterTest#tableTcMar_textInsetLikeWord` (CSSA→w:tcMar, пайплайн красит поля ячейки как tblCellMar — текст на margin+padding), `StylesTest#characterStyle_stk2_chainViaCharChain`/`charChain_nonCharacterStk_empty` + `DocToDocxFormattingTest#charStyle_viaIstd_mergesUnderDirect` (sprmCIstd: символьная chpx-цепочка между стилевой и прямыми, direct wins), `DocToDocxFormattingTest#runHighlightAndShading_inRPr`/`runShadingPattern_degradesToBackFill`/`paraShd_inPPrBeforeJc` ↔ `docHighlightAndShading_yellowPixels` (Ico→ST_HighlightColor; w:shd в форме FOP val="clear"+fill; паттерн→cvBack), `SectionsTest#titlePage_flagFromSepx` + `DocToDocxFormattingTest#titlePage_emittedAfterCols` ↔ `docTitlePage_firstHeaderOnlyFirstPage` (sprmSFTitlePage + first-слоты Plcfhdd → headerReference type="first", первая страница — только first-шапка)..
- 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`. - 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`.
+52
View File
@@ -0,0 +1,52 @@
# Аутентификация
## Ключ доступа
Все запросы, кроме открытых путей, требуют заголовок:
```
X-API-Key: <ключ>
```
Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`).
Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство =
аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011).
Без ключа или с неверным:
```
HTTP 401
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
```
## Открытые пути
Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта
forwarded-contextPath):
|Префикс|Что|
|---|---|
|`/actuator/`|health-checks Spring Boot|
|`/swagger-ui`|Swagger UI|
|`/v3/api-docs`|OpenAPI-спек|
!!! warning "Точечные сегменты обходят открытие"
Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются
открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на
открытом префиксе. Это защита от обхода фильтра через нормализацию пути.
## Где задаётся ключ
|Среда|Как|
|---|---|
|`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`|
|prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`|
|прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)|
Сгенерировать ключ: `openssl rand -hex 32`.
## Как фронтенд узнаёт про ключ
SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 —
сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу.
Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.
+45
View File
@@ -0,0 +1,45 @@
# Эндпоинт конвертации
```
POST /api/v1/convert
```
Тело запроса — `multipart/form-data` с обязательным полем **`file`**: файл `.docx`
(OOXML) или `.doc` (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
расширений отклоняются 400.
## Факультативные query/form-параметры
Параметры можно передать в query-строке или как form-поля.
|Параметр|Тип|Дефолт|Действие|
|---|---|---|---|
|`errorOnCharts`|Boolean|`false`|при `true` диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда|
|`errorOnSmartArt`|Boolean|`false`|при `true` SmartArt отменяет конвертацию (422)|
|`errorOnOle`|Boolean|`false`|при `true` OLE-объекты отменяют конвертацию (422); при `false` OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется|
|`maxMb`|число|свойство сервера `wordpdf.max-mb` (5)|лимит размера входа в МБ; переопределяет серверный дефолт **в обе стороны**; `≤ 0` → 400|
|`maxPages`|число|свойство сервера `wordpdf.max-pages` (100)|лимит числа страниц; переопределяет в обе стороны; `≤ 0` → 400|
!!! note "На `.doc` error-флаги не срабатывают"
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
работают только для `.docx`.
## Успешный ответ
```
HTTP 200
Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
```
Имя файла берётся из `Content-Disposition` загруженного файла, санитизируется
(разрешены буквы, цифры, пробел и `._-`; кириллица разрешена; пустое имя → `document`)
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
## Обработка
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
синхронно до очереди. Конвертация дольше `wordpdf.convert-timeout` (2m) → 504,
очередь полна → 503. Полная таблица ответов — [Коды ошибок](errors.md),
пороги — [Лимиты](limits.md).
+55
View File
@@ -0,0 +1,55 @@
# Коды ошибок
Ошибки — JSON вида `{"error": "..."}`.
## Полная таблица
|Код|Смысл|
|---|---|
|200|PDF в теле ответа|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага|
|401|нет или неверен `X-API-Key`|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|405|не-POST|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|415|не-multipart тело|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|500|ошибка ядра/рендера|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
## Фиксированные тексты
Тексты ниже — контракт с фронтендом, они не меняются:
|Код|Тело|
|---|---|
|401|`{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`|
|404|`{"error":"Не найдено"}`|
|405|`{"error":"Метод не поддерживается"}`|
|415|`{"error":"Неподдерживаемый тип содержимого"}`|
|422 (диаграммы)|`{"error":"Конвертация отменена: в документе найдены диаграммы"}`|
|422 (SmartArt)|`{"error":"Конвертация отменена: в документе найден SmartArt"}`|
|422 (OLE)|`{"error":"Конвертация отменена: в документе найдены OLE-объекты"}`|
|500|`{"error":"Не удалось конвертировать документ"}`|
Другие 400-тексты параметризованы, например: `Файл не передан (multipart-поле «file»
обязательно)`, `Поддерживаются только .docx и .doc: <имя>`, `Файл больше <N> МБ: …`,
`Некорректное значение параметра «<имя>»`.
!!! info "500 — деталь только в лог"
Сообщения ядра (`ConversionException` и др.) логируются на сервере, наружу
всегда уходит фиксированный текст — внутренние детали не текут клиенту.
## Исключение → обработчик (для отладки)
|HTTP|Источник|
|---|---|
|400|`ValidationException`, `BadRequestException`, `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`|
|401|`ApiKeyFilter` (пишет ответ сам, до диспетчера)|
|404 / 405 / 415|`NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException`|
|413|`MaxUploadSizeExceededException`|
|422|`DrawingRejectedException`|
|500|`ConversionFailedException`|
|503|`ConversionRejectedException`|
|504|`ConversionTimeoutException`|
+74
View File
@@ -0,0 +1,74 @@
# Примеры клиентов
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
`java -jar` — `http://localhost:8080/api/v1/convert`.
## curl
Без ключа (сервер с выключенной аутентификацией):
```bash
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
```
С ключом и error-флагом:
```bash
curl -H "X-API-Key: $WORDPDF_API_KEY" \
-F "file=@Отчёт.docx" \
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
-o out.pdf
```
## JavaScript (fetch)
```js
const form = new FormData();
form.append("file", fileInput.files[0], fileInput.files[0].name);
const resp = await fetch("/api/v1/convert", {
method: "POST",
headers: apiKey ? { "X-API-Key": apiKey } : {},
body: form,
});
if (!resp.ok) {
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
throw new Error(error);
}
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
const cd = resp.headers.get("Content-Disposition") ?? "";
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
const blobUrl = URL.createObjectURL(await resp.blob());
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
a.click();
URL.revokeObjectURL(blobUrl);
```
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
## Python (requests)
Таймаут обязан быть больше серверных 2 минут на чтение:
```python
import requests
resp = requests.post(
"https://pjandro.ru/pdf-converter/api/v1/convert",
headers={"X-API-Key": API_KEY} if API_KEY else {},
files={"file": open("doc.docx", "rb")},
params={"errorOnCharts": "false"},
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
)
resp.raise_for_status()
with open("doc.pdf", "wb") as f:
f.write(resp.content)
```
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
+53
View File
@@ -0,0 +1,53 @@
# REST API
Базовый путь — корень сервера; единственный эндпоинт:
```
POST /api/v1/convert
```
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
требует, — в заголовке `X-API-Key`):
```bash
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
```
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
```bash
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
```
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
`Content-Disposition: attachment; filename*=UTF-8''…`).
## Документация в самом сервисе
|Что|Путь|Когда доступно|
|---|---|---|
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
## Разделы
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
- [Коды ошибок](errors.md) — полная таблица и тексты.
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
## Как устроена обработка
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
выполняется синхронно, до постановки в очередь.
+47
View File
@@ -0,0 +1,47 @@
# Лимиты
## Лимиты входа
|Свойство|Env|Дефолт|Смысл|
|---|---|---|---|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5|максимальный размер файла в МБ (MiB)|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100|максимальное число страниц|
Это **дефолт эндпоинта**: параметры запроса `maxMb`/`maxPages` переопределяют его
в обе стороны (значения `≤ 0` → 400; верхнего серверного потолка нет — защитные
пороги растут вместе с лимитами). Значение свойства сервера `≤ 0` — падение
приложения на старте (`IllegalStateException`).
## Производные защитные пороги
Остальные пороги выводятся из лимитов входа (`WordPdfValidator`), проверяются
до рендера, одним lightweight-сканом:
- распакованный размер архива;
- суммарный распакованный размер XML-частей;
- число записей zip и защита от дубликатов записей;
- площади растровых изображений (пиксели);
- размер `[Content_Types].xml` (жёсткие 8 МБ).
Превышение любого — `400` (в библиотеке — `ValidationException`).
## Потолок инфраструктуры — 100 МБ
`spring.servlet.multipart.max-file-size`/`max-request-size` = 100MB — потолок
контейнера, зеркалит `client_max_body_size 100m` nginx-шлюза. Тело больше — 413.
Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400;
413 возможен только когда серверный лимит поднят администратором выше дефолта.
Части загрузки больше 2 МБ (`file-size-threshold=2MB`) сбрасываются на диск Tomcat —
heap держит только копию байтов одной сериализованной конвертации.
## Очередь и таймаут
|Параметр|Значение|Поведение|
|---|---|---|
|ёмкость очереди|16 мест|переполнение → **503** (повторить позже)|
|`wordpdf.convert-timeout`|`2m` (env `WORDPDF_CONVERT_TIMEOUT`)|конвертация дольше → **504** (задача отменяется)|
Конвертации исполняются строго последовательно одним воркером (ядро мутирует
глобальный реестр шрифтов); при таймауте `future.cancel(true)` не останавливает FOP
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.
+62
View File
@@ -0,0 +1,62 @@
# Диаграммы, SmartArt, формулы
XSLT-экспорт docx4j диаграммы не умеет, поэтому `DrawingPreRenderer` (шаг 3.5
конвейера) **до** генерации XSL-FO заменяет `c:chart` / `dgm:relIds` / `m:oMath`
на PNG-картинки (`pic:pic`). Рендер — собственный Java2D-движок (`internal/chart`,
21 класс), без Word/LibreOffice/JEuclid; текст рисуется глифами fontbox (`GlyphFont`),
поэтому fontconfig серверу не нужен.
## Диаграммы
- Выход: PNG **300 dpi** (`ChartRenderer.DPI = 300`), размеры из `wp:extent` (EMU→pt).
- Поддерживаемые типы (`ChartSpec.Type`): `PIE`, `PIE3D`, `DOUGHNUT`, `BAR`,
`BAR_HORIZONTAL`, `LINE`, `AREA`, `SURFACE3D`, `AREA3D`, `BAR3D`, `LINE3D`,
`RADAR`, `SCATTER`, `BUBBLE`, `STOCK`, `OF_PIE`, `SURFACE` (+ `UNSUPPORTED`).
- **Combo** («Комбинированная», §21.2.2.145): несколько групп в одном plotArea
(bar+line/area), привязка по `c:axId`, вторичная ось значений справа; серии
масштабируются по своей оси.
- Стекинг `stacked`/`percentStacked` — ряды накопленной суммой.
- Геометрия/камера 3-D и пропорции откалиброваны по эталонным экспортам Word
(пиксельные тесты с допусками).
## Умные границы (враждебный XML)
|Бюджет|Значение|Поведение при превышении|
|---|---|---|
|`ChartRenderer.MAX_PIXELS`|16 777 216 (4096², 64 МБ ARGB)|`fitDpi` понижает эффективный dpi (24″-график: 300→≈171 dpi), геометрия не меняется|
|`ChartSpec.MAX_POINTS`|100 000|отказ **до** предвыделения списка|
|`ChartRenderer.MAX_TICKS`|1000|безумный шаг оси заменяется «красивым» 1/2/5·10ⁿ|
|`DrawingPreRenderer.MAX_EXTENT_EMU`|22 000 000 (≈24″)|объект **остаётся как есть** + warn (не удаляется)|
|бюджет chart/math-PNG на документ|128 MiB|объект удаляется + warn|
## Модель деградации
Битая/неподдерживаемая часть роняет не конвертацию, а объект:
|Ситуация|Исход|
|---|---|
|битая chart-часть / превышение бюджета PNG|объект удалён + warn|
|неподдерживаемая/битая OMML-формула|**текст** (конкатенация `m:t`) + warn — текст терять хуже|
|`wp:extent` вне диапазона/ноль|объект остаётся + warn (FOP молча потеряет)|
|`OutOfMemoryError`|не деградация — `ConversionException` (REST 500)|
## SmartArt
`SmartArtRenderer` рисует диаграмму по разметке [MS-ODRAWXML]/§21.4: узлы, макет,
связи; тот же DPI/`fitDpi`.
## Формулы OMML
Собственный растер: `MathModel` разбирает OMML (§22.1) в дерево боксов,
`MathRenderer` рисует его только бандл-шрифтами. Конструкции вне списка `SUPPORTED`
деградируют в текст ещё на шаге нормализации (правило 6). Inline-формула опускается
на нижний запас рана — FOP ставит инлайн-графику нижним краем на базу строки.
## Контрафт media-частей
PNG-части получают имена `/word/media/chart-N.png` (константа
`CHART_MEDIA_URI_PREFIX`); по этому префиксу `ChartImageHandler` отключает
пересжатие картинок в FOP — переименование молча вернёт «мыльный» ресемпл.
Глубина (пейнтеры, калибровки, спецификационные секции) —
[chart.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md).
+61
View File
@@ -0,0 +1,61 @@
# Мост .doc → .docx
Бинарный формат Word 97–2003 читается **собственным мостом** без внешних
зависимостей (POI остаётся test-scope): байты `.doc` парсятся по спецификациям
**[MS-DOC]** (сам документ) и **[MS-CFB]** (OLE2-контейнер), собираются in-memory
`.docx` — и дальше идут тем же конвейером, что и обычные docx.
## Точка входа
```java
DocToDocx.convert(byte[] docBytes, long maxMb) // → байты .docx (вызывает WordPdfConverter)
DocToDocx.countPages(byte[] docBytes) // → страницы по сырым байтам (вызывает валидатор)
```
Страницы `.doc` считаются **по сырым байтам до конвертации** (PageCount из
SummaryInformation, разрывы 0x0C, межсекционные разрывы, `pageBreakBefore`) —
тот же скан используется валидатором лимита страниц. Любой брак (не-CFB, шифрованный
документ, Word 6–95) → `ConversionException` (в REST — 400).
## Классы пакета `internal/doc` (18 top-level)
|Класс|Спецификация|Что делает|
|---|---|---|
|`CfbReader`|[MS-CFB] §2.2–2.6|FAT/DIFAT/miniFAT, directory; бюджеты против враждебного FAT, любой брак → `ConversionException`|
|`FibHeader`|[MS-DOC] §2.5.1|заголовок FIB: потоки 1Table/0Table, пары fc/lcb нужных индексов, сверка раскладок по nFib|
|`PieceTable`|§2.9.135|текст: куски CP1252/UTF-16LE, клампинг к `cbMac`, проверка aCP|
|`Grpprl`|§2.6.2|свойства форматирования (sprm'ы): bold/italic/шрифт/цвет/подсветка/заливка/отступы/табуляции|
|`ChpxIndex` / `PapxIndex`|§2.4.6|FKP-страницы символьных/абзацных свойств|
|`Styles`|§2.9.271|STSH: стилевые цепочки абзацев и символов (stk=1/2)|
|`Tables`|§2.6.3|TAP TTP-абзаца → сетка, границы, выравнивание таблицы|
|`Lists`|§2.9.200/.201|PlfLst/PlfLfo → `word/numbering.xml`|
|`Sections`|§2.8.26|PlcfSed → геометрия секций, ориентация, нумерация страниц, `titlePg`|
|`FontTable`|§2.9.286|SttbfFfn: индекс ftc → имя семейства|
|`SummaryInfo`|[MS-OLEPS]|`\x01SummaryInformation`: в т.ч. PageCount|
|`Headers`|§2.4.1|Plcfhdd: 6 колонтитуков на секцию → `headerN.xml`/`footerN.xml`|
|`OfficeArt`|[MS-ODRAW]|картинки: BLIP-хранилище (JPEG/PNG/TIFF/DIB/EMF/WMF/PICT)|
|`PrcData`|§2.9.210|разворачивание «огромных» grpprl, вынесенных за FKP-страницу|
|`DocToDocx`|—|оркестратор + вложенный `DocxBody` (сборка document.xml)|
|`DocxWriter`|—|мульти-частный zip: content-types, rels, numbering, headers, media|
17 из 18 классов package-private; наружу — только `DocToDocx`.
## Модель деградации (не падение)
|Объект в .doc|Поведение|
|---|---|
|OLE-внедрения (U+0001 в тексте)|плейсхолдер заменяется его же BLIP-картинкой|
|картинки JPEG/PNG/TIFF/DIB|переносятся дословно / через ImageIO в PNG|
|EMF/WMF/PICT|пропуск с warn (векторные растеризаторы не в контуре)|
|битые/неподдерживаемые конструкции|снисходительный разбор, объект исчезает или упрощается — текст не теряется|
Поэтому **error-флаги (`errorOnCharts`/`errorOnSmartArt`/`errorOnOle`) на `.doc` не
срабатывают**: OLE-вложения бинарного формата — это U+0001 с BLIP-плейсхолдером,
мост деградирует их в картинки, «OLE-объектов» в смысле docx-пути в результате нет.
## Сознательный остаток
Семантика рестартов списков (`fNoRestart`/`ilvlRestartLim`), `fLegal`,
AUTONUM-поля (трактуются как обычные списки), часть тонкостей объединённых ячеек —
осознанные упрощения вне контура; полный перечень —
[doc-bridge.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md).
+63
View File
@@ -0,0 +1,63 @@
# Шрифты
Конвертация не зависит от шрифтов системы: **30 TTF упакованы в jar**
`wordpdf-core/src/main/resources/fonts/`, выгружаются во временный каталог и
регистрируются в docx4j/FOP. Реестр шрифтов после каждой конвертации возвращается
к бандлу — шрифты, встроенные в чужие docx, не влияют на последующие документы.
`java.awt.Font` не используется (метрики и глифы — fontbox напрямую), поэтому
**fontconfig серверу не нужен**.
## Бандл
7 текстовых семейств по 4 начертания + 2 покрывающих (только regular):
|Семейство|Аналог MS-шрифта|Назначение|
|---|---|---|
|Carlito|Calibri|метрически совместимая замена|
|Caladea|Cambria|метрически совместимая замена|
|Arimo|Arial|метрически совместимая замена|
|Tinos|Times New Roman|метрически совместимая замена|
|Cousine|Courier New|метрически совместимая замена|
|DejaVu Sans / DejaVu Serif|—|fallback с гарантированной кириллицей|
|Noto Naskh Arabic|—|арабские дополнения U+07B1–U+08FF|
|Noto Sans Armenian|—|армянские знаки Unicode 16|
## Алиасы (`BundledFontAliases`)
Имена шрифтов из документа подменяются аналогами при конвертации:
|Имя в docx|Физический шрифт|
|---|---|
|Calibri|Carlito|
|Cambria|Caladea|
|Arial|Arimo|
|Times New Roman|Tinos|
|Courier New|Cousine|
## Fallback-цепочка
1. **Ран** идёт своим шрифтом (по `w:rFonts` + алиасам).
2. Знака нет в шрифте рана (тире «—», кавычки, U+2000–U+2EFF) — ран падает в
**DejaVu Sans** (FOP-фолбэк-семейства задекларированы всецело, шаг 4 конвейера).
3. Serif-раны ищут покрытие сначала в serif-семействах (DejaVu Serif, Tinos, Caladea).
4. Знака нет и там — `GlyphCoverageNormalizer` (правило 7) режет ран и каждой части
назначает покрывающее семейство: serif → DejaVu Serif, sans → DejaVu Sans,
экзотика → Noto.
5. Знака нет ни в одном шрифте бандла — остаётся `.notdef` (пустой бокс).
Все шрифты встраиваются в PDF как **подмножества** (кириллица и латиница
воспроизводятся на любом просмотрщике).
## Лицензии
|Шрифты|Лицензия|
|---|---|
|Arimo, Cousine, Tinos, Carlito, Caladea|SIL OFL 1.1 (`fonts/FONT-LICENSE.txt`)|
|DejaVu Sans / DejaVu Serif|SIL OFL 1.1 / Bitstream Vera (`fonts/DejaVu-LICENSE.txt`)|
|Noto Naskh Arabic, Noto Sans Armenian|SIL OFL 1.1 (`fonts/Noto-LICENSE.txt`)|
GPL-шрифты в бандл не добавляем намеренно (из-за этого два символа эталона —
U+2188/U+218A — остаются `.notdef`; см. [Ограничения](limitations.md)).
Новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES`
(синхронность проверяет `BundledFontsTest`).
+40
View File
@@ -0,0 +1,40 @@
# Ограничения рендера
Конвертер **не является pixel-perfect рендером Word**: часть расхождений —
неустранимые невозможности связки docx4j + Apache FOP, а не упущения проекта.
## Что конвертируется приближённо
- Раскладка, поля и некоторые эффекты могут отличаться от Word (ограничения
FOP/docx4j по построению).
- Символы U+2000–U+2EFF (тире, кавычки): из шрифта рана, если в нём есть глиф,
иначе — из fallback-семейства DejaVu.
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
остаётся `.notdef` (пустой бокс). В эталонном наборе таких два: U+2188 (ↈ) и
U+218A (↊) — глифы есть только в GNU FreeSerif под GPL, а бандл держится целиком
на SIL OFL.
- Поддержка таблиц/изображений — базовая (уровень docx4j/FOP).
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
бинарного формата — уже растры (вставляются картинками), EMF/WMF/PICT пропускаются
с warn — [Мост .doc](doc-bridge.md).
## Стоп-лист «не чинить»
До любой попытки «починить» расхождение с Word — сверьтесь со списком: это
невозможности движка, попытка фикса хуже самого расхождения.
|Конструкция|Что происходит|Почему не чинится|
|---|---|---|
|`w:jc="distribute"`|рендерится как left|межсимвольного распределения в FOP нет; `text-align-last` в форке отсутствует|
|`w:suff="tab"`|игнорируется (label через hanging-tab)|нужна per-item ширина; совпадает с поведением docx4j|
|`w:lvlJc`|игнорируется|—|
|кернинг|не применяется|—|
|`framePr` (обтекание)|не поддерживается|—|
|кэш полей `REF`/`SEQ`/`TOC`|печатается кэш из docx|живой пересчёт вне контура (`PAGE`/`NUMPAGES`/`PAGEREF`/`DATE` — пересчитываются)|
|руби (надстрочница)|надстрочная часть вырезается, база печатается|ruby-разметки в FOP нет; потеря текста хуже потери аннотации|
|`ptab`|не поддерживается|—|
|U+2188/U+218A|`.notdef`|GPL-шрифты не добавляем намеренно|
|`lineRule="auto"`|—|не «чинить»: метрический шаг пинен тестом|
Полный перечень с доказательствами по ECMA-376 —
[render-limitations.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md).
+68
View File
@@ -0,0 +1,68 @@
# Архитектура
## Конвейер конвертации (шаги 0–7)
Единственный вход ядра — `WordPdfConverter.convert(byte[], String, ConvertOptions)`;
порядок шагов фиксирован и каждый обоснован:
|#|Шаг|Зачем|
|---|---|---|
|0|`DependencyGuard.check()`|API-проба commons-compress ≥ 1.25.0 — понятная ошибка вместо `NoSuchMethodError` внутри docx4j|
|1|`new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()`|реестр шрифтов = только бандл (+ встроенные в docx); системные сканы отключены гейт-свойствами; порядок строго такой, до `load()`|
|2|нормализаторы → `WordprocessingMLPackage.load`|12 правил переписывания байтов одним zip-проходом + OLE-вычистка (см. ниже)|
|3|`setFontMapper`|привязка имён шрифтов документа к физическим TTF|
|3.5|`DrawingPreRenderer.run`|диаграммы/SmartArt/OMML-формулы → PNG 300 dpi; **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы|
|4|`FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`|FOP встраивает только задекларированные семейства; декларуются все бандл-семейства|
|4.25/4.5|`LayoutPostRenderer.register`, `setCustomXsltTemplates`|padding-компенсация таблиц; вендорный XSLT с AUDIT-FIX-патчами|
|5–6|общая `FopFactory` (DCL) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`|XSL-FO → PDF|
|7|`finally`|сброс temp-шрифтов, сброс общих кешей картинок (иначе ~1,5 ГБ за 30 конвертаций), возврат реестра к бандлу|
Нормализаторы правил 1–11 (один zip-проход, порядок значим): strict→transitional,
`on/off`→`true/false`, Symbol/Wingdings→Unicode, поля `PAGE`/`NUMPAGES` →
`w:fldSimple` (пересчёт вместо кэша), невидимые символы, OMML-фолбэк, резка ранов
по покрытию глифов, отступ таблиц, `suff="space"`, скрытый текст, руби. Правило 12 —
`OleObjectNormalizer` (отдельным байтовым проходом).
Полное «что делает каждый шаг и почему именно так» —
[pipeline.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md).
## Слои ядра (`wordpdf-core`)
|Слой|Содержимое|
|---|---|
|публичный API (`ru.pjandro.wordpdf`)|`WordPdfConverter`, `WordPdfValidator`, `ConvertOptions`, иерархия ошибок — см. [API библиотеки](../library/api.md)|
|`internal/`|нормализаторы (контракт `byte[] normalize(byte[])`), `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`|
|`internal/doc/`|мост бинарного `.doc` → in-memory `.docx` — [Мост .doc](doc-bridge.md)|
|`internal/chart/`|Java2D-рендер диаграмм/SmartArt/формул → PNG — [Диаграммы](charts.md)|
|`fonts/`|бандл из 30 TTF, маппинг алиасов, `GlyphFont` (метрики/глифы через fontbox, без AWT) — [Шрифты](fonts.md)|
Всё, кроме публичного API, — package-private; контракт наружу не расширяется.
## Параллельность
`PhysicalFonts` docx4j — глобальный мутируемый реестр → **все конвертации
сериализованы монитором класса `WordPdfConverter.class`**. Приложение (`wordpdf-app`)
дополнительно держит однопоточный `ThreadPoolExecutor` с очередью 16 мест (переполнение
→ 503, timeout 2m → 504), головой очереди стоит `warmup()`.
## REST-конвейер приложения (`wordpdf-app`)
`POST /api/v1/convert` → `ApiKeyFilter` (401) → `ConvertController` (проверка
расширения/размера, параметры) → `ConversionService` (очередь, Future с таймаутом,
перевод исключений ядра в HTTP) → ядро. Обработчик исключений пишет JSON
`{"error": …}` — карта кодов в [REST API](../api/errors.md). В модуле 11 классов,
все package-private кроме `WordPdfApplication`.
## Веб-интерфейс (`wordpdf-web`)
React SPA; вся сеть — ровно две функции в `api.ts` (`convertDocx`, `probeApiKey`),
состояние — `useState` в `App.tsx`, store-библиотек нет. Запросы идут на тот же
путь `/api/...` относительно базы раздачи — CORS не нужен.
## Внешние поверхности
- `gateway/nginx.conf` — единственная наружная точка стендов (:9010/:9011):
`/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → app:8080, остальное → web;
[Эксплуатация: стенды](../operations/stack.md).
- Прод (`https://pjandro.ru/pdf-converter/`) рендерится job'ом `deploy` из
Gitea Variables — [Деплой](../operations/deployment.md).
+64
View File
@@ -0,0 +1,64 @@
# Как контрибьютить
## Ветка и PR
Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`,
`master`, `dev`: прямо в них не коммитим.
1. Ветка от свежей `main` (`git switch -c <name>`).
2. Коммиты логическими блоками.
3. Перед push — полный гейт: `./mise.sh run verify`.
4. `git push -u origin <name>` → pull request в дефолтную ветку.
5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig +
сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required.
`macos-sim` — не required.
## Конвенции кода
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет);
в `internal/**` — package-private, `public` только вызываемым извне пакета.
- Ошибки публичного API — только `ConversionException` (и подтипы); в chart —
деградация вместо падения.
- Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24,
[MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
`Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке
грепом восстанавливаются пары тестов).
- Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа.
- PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены.
- Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J —
`internal/chart` и `wordpdf-app`; остальное молчит.
## Регрессивная конвенция (фикс бага)
Каждый фикс расхождения с Word оформляется полным набором:
```
нормализатор/рендерер → юнит на правило → тест во всём конвейере
→ javadoc-ссылка «Регрессия — Тест#имя, фикстура …»
```
Фикстуры для новых тестов не генерируются на лету и не перезаписываются:
`charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются
никогда**; все 12 `.doc` — эталоны заказчика.
## Критические инварианты (нарушение = битый вывод)
Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`,
[repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)):
- static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение
сканов PhysicalFonts) — не удалять;
- `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы;
- порядок нормализаторов правил 1–11 фиксирован;
- вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт
`vendoredXsltTracksJarCopy`;
- `slf4j-simple` обязателен в ядре;
- префикс `/word/media/chart-*` — контракт с `ChartImageHandler`;
- финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу.
## Документация сайта
Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят
в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе
strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация —
[`docs-deploy`](../operations/docs-site.md).
+83
View File
@@ -0,0 +1,83 @@
# Окружение разработчика
Требуется **Java 17**, **Maven 3.9.16**, **Node 24** (engines Vite: `^20.19.0 ||
>=22.12.0`), **Python 3.15** (прод-автотесты, сайт документации). Всё это ставит
project-local mise: сам бинарь — в `./.mise/bin` (gitignored), кеш инструментов —
в user-директории mise, **в систему ничего не устанавливается**. Версии пиныны
в `mise.toml`.
## Бутстрап (первая настройка)
```bash
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
```
Дальше команды — через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
```bash
./mise.sh run verify # полный гейт перед push
./mise.sh exec -- mvn -v # любая команда с инструментами в PATH
./mise.sh tasks # список задач
```
Альтернатива — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`):
`eval "$(./.mise/bin/mise activate bash)"`.
## Задачи mise
|Задача|Содержание|
|---|---|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo (гейт перед push)|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (как CI; требует podman/docker)|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|`app-package`|исполняемый jar бэкенда|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|`web-install`|`npm ci` в `wordpdf-web`|
|`web-build`|гейт SPA: `tsc -b && vite build`|
|`web-lint`|oxlint|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|`docs-install`|venv `docs/.venv` + `mkdocs-material`|
|`docs-serve`|локальный предпросмотр сайта на :8000 (live-reload)|
|`docs-build`|strict-сборка сайта в `site/` (битые ссылки/навигация = ошибка)|
|`docs-javadoc`|javadoc публичного API core в `wordpdf-core/target/site/apidocs`|
|`docs-deploy`|публикация сайта на rpi (:9012): javadoc + strict-build + rsync|
## Прямые команды (без задач)
```bash
mvn clean verify # все модули + тесты
mvn test -Djacoco.skip=true # тесты без агента покрытия
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test # -am обязателен: app берёт фикстуры из test-jar core
mvn -pl wordpdf-app -am package # исполняемый jar → wordpdf-app/target/
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
npm ci && npm run build # в wordpdf-web/ (или задачи web-*)
npm run dev # SPA :5173, проксирует /api на :8080
```
## Стенды на контейнерах (podman)
```bash
# dev (:9011), без ключа, springdoc включён
podman-compose -f compose.dev.yml up -d --build --force-recreate
# prod-like (:9010), fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
cp .env.example .env # ключ: openssl rand -hex 32
podman-compose up -d --build
```
`--force-recreate` для dev обязателен: без него podman-compose пересоберёт образ,
но контейнеры оставит на старом jar. Наружу публикуется только nginx-gateway
(9010/9011), 8080 наружу не выставляется. Подробности —
[Стенды](../operations/stack.md).
!!! info "«Запусти тестовый сервер»"
Так в проекте называют dev-стенд (`compose.dev.yml`, `http://<LAN-IP>:9011`),
а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f
compose.dev.yml ps`) + корень SPA отвечает 200.
+71
View File
@@ -0,0 +1,71 @@
# Тесты
## Гейты
Полный гейт перед push — `./mise.sh run verify` (= `mvn clean verify`); на `verify`
висят и валят сборку:
|Гейт|Порог|
|---|---|
|surefire (тесты)|все зелёные, `-Djava.awt.headless=true`|
|PMD (`pmd-ruleset.xml`)|любой приоритет нарушения валит; `includeTests=true`; **подавления запрещены** — чинить кодом|
|JaCoCo LINE|≥ 0.90 (оба модуля)|
|JaCoCo BRANCH|≥ 0.85 (только `wordpdf-core`)|
Провал — HTML/XML-отчёт уже в `target/site/jacoco/`. CI-эквивалент без fontconfig —
`./mise.sh run verify-nofontconfig`. `mvn test` PMD/JaCoCo-гейты не запускает.
## Стек и конвенции
- **JUnit 6** (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ
запрещены, их нет в pom (в app-тестах допустим inline-Hamcrest
`org.hamcrest.Matchers.containsString` в `andExpect`).
- Только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов, `@AfterEach
drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`,
ни `@Disabled`, ни `assertAll`.
- Тестовые классы package-private, зеркалят main-пакеты.
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`),
юниты — camelCase (`pageFieldBecomesFldSimple`).
- Сообщения ассертов — по-русски, с наблюдаемым значением; литерал слева.
- Тестовых утилит нет — хелперы намеренно дублируются в классах.
## Фикстуры
Только закоммиченные `wordpdf-core/src/test/resources/samples/`: **13 `.docx` +
12 `.doc`** (`.doc` — эталоны заказчика). В тестах фикстуры **не генерировать**;
XSD-невалидную `.docx`-фикстуру правят, а не код
(`python3 docs/standards/docx/validate-fixtures.py …`). Синтетика в памяти разрешена:
docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`.
Ловушка загрузки: **core** грузит classloader-ресурсом без ведущего слэша
(`getResourceAsStream("samples/…")`), **app** — class-relative со слэшем
(`/samples/…`, ресурсы из test-jar core; отсюда обязательный `-am`).
## Как проверяется PDF
**Текстом, не растеризацией**: PDFBox 3 `PDFTextStripper` (нормализация пробелов);
негативные маркеры — `#` (.notdef) и `Helvetica` (фолбэк-шрифт FOP); имя шрифта
символа — приём `fontNameOf`; встроенные подмножества — обход ресурсов страниц
(`EAAAAA+Carlito-Bold`). Пиксели (BufferedImage, отношения к эталонам Word 300 dpi
с допусками) — только юниты chart-пейнтеров.
## App-тесты
4 набора свойств = 4 Spring-контекста: `ConvertControllerTest` (пин пустого
`wordpdf.api-key=`), `ApiKeyFilterTest`, `ConvertLimitsTest`, `ConversionTimeoutTest`;
`ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Проверяют HTTP-код,
заголовки, текст ошибки. Ловушка: mise инжектирует корневой `.env` в окружение задач
— ambient `WORDPDF_API_KEY` дал бы 401 во всех MockMvc-тестах, поэтому ключ пинится
свойствами контекста.
## Прод-автотесты
`prod-autotests/` (pytest + requests): 31 проверка против **живого** стенда —
4 открытые + 27 `needs_key` (SKIP без ключа). Конфигурация только env:
`WORDPDF_BASE_URL` (обязателен), `WORDPDF_API_KEY`, `WORDPDF_MAX_MB`/`MAX_PAGES`,
`WORDPDF_SAMPLES_DIR`. Таймауты `(10, 180)` — больше серверных 2m. Запуск:
`WORDPDF_BASE_URL=… ./mise.sh run prod-tests` (в CI гоняются job'ом `autotests`
после deploy).
Глубина (счётчики, пары «нормализатор ↔ тест», пиксельные допуски) —
[testing.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md).
+64
View File
@@ -0,0 +1,64 @@
# Word → PDF конвертер
Конвертация **.docx/.doc → PDF** на чистой Java: `docx4j` 17.3.2 + форк `Apache FOP`
(`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6), **без LibreOffice и без Aspose**.
Бинарный `.doc` (Word 97–2003) читается собственным мостом [MS-DOC]/[MS-CFB]
и переносится в .docx в памяти — дальше идёт тем же конвейером. Шрифты упакованы
в jar: конвертация не зависит от шрифтов, установленных в системе, и работает
«из коробки» на голом сервере.
## Три поверхности
|Поверхность|Что это|Куда смотреть|
|---|---|---|
|Веб-интерфейс|React SPA: перетащил файл → предпросмотр PDF → скачивание. Публикация: `https://pjandro.ru/pdf-converter/`|[Пользователю](user.md)|
|REST API|`POST /api/v1/convert` (Spring Boot 4.1.1), ключ доступа, Swagger UI|[REST API](api/index.md)|
|Java-библиотека|`wordpdf-core`: `WordPdfConverter.convert(...)` — байты docx на входе, байты PDF на выходе|[Библиотека](library/getting-started.md)|
## Как это работает (схема)
```
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Вход проверяется до рендера (`WordPdfValidator`): размер → сигнатура байтов
(zip `PK\x03\x04` или CFB `D0 CF 11 E0`) → контейнер и страницы lightweight-сканом,
без зависимости от docx4j.
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом (12 правил
нормализации), затем OLE-объекты вычищает `OleObjectNormalizer`.
3. Документ загружается в `WordprocessingMLPackage`, привязывается `BundledFontMapper`.
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi собственным
Java2D-движком (`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
5. Экспорт в XSL-FO идёт вендорным стилем `docx2fo.xslt`; `Apache FOP` рендерит
PDF, встраивая подмножества шрифтов.
Полностью, с обоснованиями — [Архитектура](architecture/overview.md).
## Возможности
- RU/EN: кириллица и латиница встраиваются в PDF как embedded-подмножества.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
([Шрифты](architecture/fonts.md)).
- Диаграммы (17 типов, включая комбинированные) и SmartArt — PNG без Word/LibreOffice
([Диаграммы](architecture/charts.md)).
- `.doc`: текст, стили, таблицы, списки, колонтитуки, картинки — собственный мост
([Мост .doc](architecture/doc-bridge.md)).
## Ключевые версии
|Компонент|Версия|
|---|---|
|Java|17 (temurin)|
|docx4j|17.3.2|
|Apache FOP (форк `docx4j-fo-renderer*`)|2.11-docx4j.6|
|commons-compress|1.28.0 (минимум 1.25.0)|
|Spring Boot|4.1.1|
|springdoc|3.1.1|
|SPA|React 19.2 + TypeScript ~6.0 + Vite 8.3|
## Ссылки
- [Javadoc публичного API `wordpdf-core`](/apidocs/index.html)
- [Внутренние справочники репозитория](internal-guides.md) — для глубокой правки кода.
+39
View File
@@ -0,0 +1,39 @@
# Внутренние справочники репозитория
Сайт покрывает «как пользоваться и как устроено». Для **глубокой правки кода**
в репозитории живут авторитетные справочники (`docs/agent/`, читаются наравне
с `AGENTS.md`) и закоммиченные спецификации форматов (`docs/standards/`).
В этот сайт они не включены (огромные тексты спецификаций) — ссылки ведут на Gitea.
## Справочники `docs/agent/`
|Документ|Читать при|
|---|---|
|[pipeline.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md)|правке конвейера `WordPdfConverter`, нормализаторов, валидатора; шаги 0–7 с обоснованиями, правила 1–12|
|[doc-bridge.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md)|правке моста `internal/doc`; классы ↔ секции [MS-DOC]/[MS-CFB], остаток моста|
|[chart.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md)|правке `internal/chart`; пейнтеры, калибровки по Word, защитные лимиты, §ECMA-376|
|[render-limitations.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md)|любой попытке «починить» расхождение с Word — сначала стоп-лист|
|[testing.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md)|добавлении/правке тестов; счётчики, пиксельные допуски, фикстуры, конвенции|
|[ci-cd.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md)|правке workflow'ов, Containerfile'ов, деплоя|
|[repo-map.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)|поиске «где живёт X»: полная карта каталогов/файлов, REST-карта, конвенции|
## Спецификации `docs/standards/`
Нормативные тексты форматов, закоммиченные в репозиторий
(навигатор — `docs/standards/README.md`, ссылка в коде — с номером секции):
|Каталог|Содержимое|
|---|---|
|`ooxml/`|ECMA-376 Part 1 (PDF + md), [MS-OI29500], [MS-ODRAWXML], полные наборы XSD strict/transitional|
|`binary/`|[MS-CFB], [MS-OSHARED], [MS-ODRAW], [MS-OLEPS], [MS-OFFCRYPTO], [MS-OVBA], [MS-WMF], [MS-EMF]|
|`doc/`|[MS-DOC] — бинарный формат Word 97–2003|
|`docx/`|XSD-валидация фикстур (`validate-fixtures.py`)|
## Корневые документы
- [`AGENTS.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/AGENTS.md) —
правила репозитория: конвейер, инварианты, команды, конвенции, гейты.
- [`README.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/README.md) —
короткая точка входа в проект.
- [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md) —
все Secrets/Variables CI и настройка branch protection.
+75
View File
@@ -0,0 +1,75 @@
# API библиотеки
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
Javadoc каждого члена — [apidocs](/apidocs/index.html).
## `WordPdfConverter`
```java
public final class WordPdfConverter {
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
throws ConversionException;
public static synchronized void warmup();
}
```
- `convert` — единственный путь конвертации (двухаргументной перегрузки **нет**).
Принимает байты `.docx` или `.doc` (маршрутизация по сигнатуре), возвращает байты PDF.
`title` — заголовок PDF. `options == null` → `ValidationException`.
- `warmup()` — идемпотентный прогрев конвейера; не бросает.
## `WordPdfValidator`
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
```java
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
```
Проверяются: непустота, размер (`maxMb`), сигнатура (zip/CFB), для docx — контейнер
(`[Content_Types].xml` с типом документа), производные пороги (распаковка, XML,
растры, записи zip), число страниц (lightweight-скан, без docx4j; для `.doc` —
по сырым байтам мостом).
## `ConvertOptions`
```java
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
boolean errorOnOle, long maxMb, int maxPages) {}
```
**Порядок полей фиксирован.** `maxMb`/`maxPages` должны быть больше 0. Дефолтов
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
флаги только отменяют конвертацию находкой.
## Ошибки
```
ConversionException (RuntimeException)
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
├── ChartsFoundException — errorOnCharts и найдены диаграммы
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
└── OleFoundException — errorOnOle и найдены OLE-объекты
```
Ловите `ConversionException` — он покрывает всё; `ValidationException` — отдельно,
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
## Инвариант параллельности
`convert` **потокобезопасен, но сериализован**: все конвертации идут под монитором
класса `WordPdfConverter.class` — ядро мутирует глобальный реестр шрифтов docx4j
(`PhysicalFonts`). Параллельные вызовы корректны, но исполняются последовательно;
собственный пул/очередь с отказом при переполнении — забота вызывающего
(так делает `wordpdf-app`: один воркер, очередь 16).
## Шрифты и окружение
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации
возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие
конвертации.
- `java.awt.Font` не используется (глифы — fontbox напрямую): **fontconfig хосту не нужен**,
контейнер без `/etc/fonts` работает.
- Нужен SLF4J-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
предупреждений попадает в PDF.
+66
View File
@@ -0,0 +1,66 @@
# Зависимости потребителя
## commons-compress: единственная ловушка интеграции
Ядру (транзитивно, через docx4j) нужен `org.apache.commons:commons-compress`
**≥ 1.25.0**, рекомендован **1.28.0** — версию закрепляет POM `wordpdf-core`.
Симптом старой версии в classpath потребителя:
```
NoSuchMethodError: org.apache.commons.compress.archivers.zip.ZipArchiveEntry
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()
```
До входа в docx4j теперь срабатывает guard (`DependencyGuard`): вместо мутного
`NoSuchMethodError` внутри docx4j — `ConversionException` с текстом, объясняющим,
какую версию закрепить.
### Maven: закреплять в `dependencyManagement`
BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, а
`dependencyManagement` потребителя перекрывает транзитивные версии («nearest wins»)
— закреплять нужно именно в нём:
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-compress</artifactId>
<version>1.28.0</version>
</dependency>
</dependencies>
</dependencyManagement>
```
Диагностика:
```bash
mvn dependency:tree -Dincludes=org.apache.commons:commons-compress
```
### Gradle: достаточно не понижать
По умолчанию Gradle выбирает максимальную версию и конфликт разрешает сам —
guard не сработает и не нужен. Понижает версию только явный `constraints` /
`platform` / `resolutionStrategy`: уберите понижение либо закрепите нужную версию:
```kotlin
dependencies {
constraints {
implementation("org.apache.commons:commons-compress:1.28.0")
}
}
```
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
## Прочие транзитивные зависимости
|Артефакт|Зачем|Нужно ли трогать|
|---|---|---|
|`docx4j-export-fo` (+ форк FOP `docx4j-fo-renderer*`)|конвейер XSL-FO → PDF|нет|
|`slf4j-simple`|единственный SLF4J-провайдер из коробки — без провайдера docx4j пишет «TO HIDE THESE MESSAGES» в PDF|исключить, если у приложения свой провайдер|
|`jcl-over-slf4j`|мост commons-logging (pdfbox/fontbox) → slf4j|нет (`commons-logging` исключён)|
|`fontbox`|чтение TTF напрямую, без `java.awt.Font`|нет|
+72
View File
@@ -0,0 +1,72 @@
# wordpdf-core: первые шаги
`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice,
без Aspose, без системных шрифтов: все TTF упакованы в jar.
## Подключение
```xml
<dependency>
<groupId>ru.pjandro</groupId>
<artifactId>wordpdf-core</artifactId>
<version>1.0.0</version>
</dependency>
```
Требуется **Java 17**. Единственный обязательный аспект интеграции — версия
`commons-compress` (см. [Зависимости](dependencies.md)).
## Минимальный пример
```java
import ru.pjandro.wordpdf.WordPdfConverter;
import java.nio.file.Files;
import java.nio.file.Path;
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
byte[] pdf = WordPdfConverter.convert(docx, "doc",
new ru.pjandro.wordpdf.ConvertOptions(false, false, false, 5, 100));
Files.write(Path.of("out.pdf"), pdf);
```
Второй аргумент — заголовок PDF (пустой/`null` — без заголовка). Работа с файлами —
забота вызывающего: ядро пути не принимает, только байты.
Формат входа определяется **по сигнатуре байтов**, расширение имени файла ядру
неизвестно:
|Сигнатура|Маршрут|
|---|---|
|`PK\x03\x04`|zip → OOXML-путь (docx4j)|
|`D0 CF 11 E0 A1 B1 1A E1`|CFB → мост .doc → .docx в памяти → тот же конвейер|
## Опции конвертации
`ConvertOptions` — record из пяти полей (детали в [API библиотеки](api.md)):
error-флаги диаграмм/SmartArt/OLE и лимиты размера/страниц. Дефолтов в ядре нет —
все пять значений задаёт вызывающий:
```java
// отменить конвертацию, если в документе есть диаграммы; лимиты 10 МБ / 200 страниц
var opts = new ConvertOptions(true, false, false, 10, 200);
byte[] pdf = WordPdfConverter.convert(bytes, "Отчёт", opts);
```
## Прогрев
Первая конвертация после старта JVM стоит ~1,3–1,7 с (инициализация JAXB/XSLT/FOP).
`WordPdfConverter.warmup()` прогоняет весь конвейер на минимальном встроенном docx
и идемпотентен (повторные вызовы — no-op); бросать не должен никогда — решение
о реакции на сбой прогревает код. Вызывайте на старте приложения, если не хотите,
чтобы первый пользователь платил за инициализацию:
```java
WordPdfConverter.warmup(); // ~1,5–2,5 с, один раз при старте
```
## Провайдер логов
В classpath потребителя **обязан быть SLF4J-провайдер**. Без него docx4j пишет
предупреждение «TO HIDE THESE MESSAGES…» **прямо в выходной PDF**. В jar `wordpdf-core`
для этого включён `slf4j-simple`; если ваше приложение приносит свой провайдер
(logback и т.п.) — исключите `slf4j-simple` из транзитивных зависимостей.
+52
View File
@@ -0,0 +1,52 @@
# Конфигурация сервера (`wordpdf-app`)
## Свойства и env
|Свойство|Env|Дефолт|Смысл|
|---|---|---|---|
|`wordpdf.api-key`|`WORDPDF_API_KEY`|пусто|ключ заголовка `X-API-Key`; пусто = аутентификация выключена|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5 (литерал `@Value`)|дефолтный лимит размера входа, МБ (MiB); ≤ 0 на старте → `IllegalStateException`|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100 (литерал `@Value`)|дефолтный лимит страниц; ≤ 0 → падение на старте|
|`wordpdf.convert-timeout`|`WORDPDF_CONVERT_TIMEOUT`|`2m`|таймаут одной конвертации (Duration) → 504|
|`spring.servlet.multipart.max-file-size` / `max-request-size`|—|`100MB`|потолок контейнера, зеркалит nginx `client_max_body_size 100m`|
|`spring.servlet.multipart.file-size-threshold`|—|`2MB`|части больше — на диск Tomcat (heap держит только копию одной сериализованной конвертации)|
|`server.forward-headers-strategy`|—|`framework`|работа за префикс-срезающим прокси (`X-Forwarded-*`); `native` не понимает `X-Forwarded-Prefix`|
|`springdoc.api-docs.enabled`|`SPRINGDOC_API_DOCS_ENABLED`|`true`|OpenAPI-спек; `false` → `/v3/api-docs` отдаёт 404|
|`springdoc.swagger-ui.enabled`|`SPRINGDOC_SWAGGER_UI_ENABLED`|`true`|Swagger UI|
|`springdoc.swagger-ui.persist-authorization`|—|`true`|не требовать ключ заново после перезагрузки страницы UI|
Ограничитель очереди (16 мест) — константа `ConversionService.QUEUE_CAPACITY`,
не конфигурируется.
!!! warning "Не объявляйте `wordpdf.max-mb`/`max-pages` в `application.properties`"
Дефолты 5/100 живут литералами `@Value` в `ConvertController`. Пустое значение
ключа в properties **затенит** литерал и сломает старт. Либо не объявляйте
(тогда дефолт), либо конкретное число.
## Примеры запуска
```bash
# ключ + лимиты через env
WORDPDF_API_KEY=$(openssl rand -hex 32) WORDPDF_MAX_MB=10 \
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
# или аргументами
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar \
--wordpdf.api-key=secret --wordpdf.convert-timeout=3m
```
В prod-like compose-стеке `WORDPDF_API_KEY` читается из `.env` (fail-closed:
`${WORDPDF_API_KEY:?}` — без него стек не поднимается), на проде ключ приходит
только из Gitea Secret через окружение контейнера.
## Что задала не я, а инфраструктура
|Параметр|Где|Значение|
|---|---|---|
|`client_max_body_size`|`gateway/nginx.conf`|`100m`|
|proxy_read timeout|`gateway/nginx.conf`|300 с|
|heap контейнера app|`Containerfile` (ENTRYPOINT)|`-Xms2g -Xmx2g`; лимит `mem_limit: 3g` — в compose|
|`VITE_BASE`|build-arg образа web|`/pdf-converter/` (путь публикации на проде)|
Значение `maxMb`/`maxPages` конкретного стенда прод-автотесты читают из
`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (на проде — 5/100).
+54
View File
@@ -0,0 +1,54 @@
# Деплой (прод)
Наружный вход прода — **`https://pjandro.ru/pdf-converter/`** (пользовательский
nginx режет префикс и проксирует на стек конвертера). Публикация полностью
автоматизрована: **push в `main` → Gitea Actions**.
## Пайплайн `main.yml`
```
java + web (тесты/гейты) ──> images-app + images-web (build+push в реестр)
──> deploy (рендер прод-стека, pull, up, health-гейты, автооткат)
──> autotests (pytest против живого прода; провал → rollback)
```
1. **`java` / `web`** — те же гейты, что на PR (`mvn clean verify` в контейнере
без fontconfig; `npm ci`/build/lint).
2. **`images-app` / `images-web`** — сборка Containerfile в Nexus-реестр, теги
`prod` + неизменяемый `sha-<7 символов>`; web печётся с
`VITE_BASE=/pdf-converter/` (путь публикации запекается в образ).
3. **`deploy`** — job **рендерит** `docker-compose.yml` и `nginx.conf` в директорию
деплоя из Gitea Variables (прод-хост не хранит ни конфигураций, ни секретов;
API-ключ — из Secret через окружение деплоя, на диск не пишется), затем
login/pull/`up -d --force-recreate app web`, гейты healthy + recreate gateway.
Единственное состояние на проде — `.rollback.env` (image id предыдущего рана).
4. **`autotests`** — 31 pytest-проверка против живого стенда; провал → откат
на образ из `.rollback.env`.
## Где креды и координаты
Всё вне репозитория — **Gitea Actions Variables/Secrets** (полный список и настройка
branch protection: [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md)).
Прод-ключ `WORDPDF_API_KEY` — только Secret. В репо и на диске прод-хоста ключа нет.
## Ручные операции
!!! warning "Перед ручным перезапуском прода"
Прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (живёт на прод-хосте,
вне репозитория) — там актуальные координаты и процедура. Ручных скриптов
деплоя в репозитории нет и не заводить.
Прод-образ/`compose` правятся только через CI-рендер; копий прод-стека на хосте
или в репо быть не должно.
## Проверка после деплоя
CI сам докладывает по job'ам (`/actions/runs/<id>/jobs`); руками:
```bash
curl -sf https://pjandro.ru/pdf-converter/actuator/health # 200 {"status":"UP"}
curl -s -o /dev/null -w '%{http_code}\n' https://pjandro.ru/pdf-converter/ # 200 SPA
```
Глубина (нюансы runner'ов, `DOCKER_BUILDKIT=0`, реестр, rollback-механика) —
[ci-cd.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md).
+88
View File
@@ -0,0 +1,88 @@
# Этот сайт документации
Статический сайт (MkDocs Material) собирается из `docs/` этого репозитория и
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
- адрес: **`http://192.168.88.23:9012/`** (LAN; наружу не публикуется);
- статика: `/home/pjandro/srv/wordpdf-docs/` (rsync без рестарта контейнера);
- javadoc публичного API: [`/apidocs/index.html`](/apidocs/index.html).
## Публикация (с хоста, из репозитория)
```bash
./mise.sh run docs-install # разово: venv docs/.venv + mkdocs-material
./mise.sh run docs-deploy # javadoc → strict-build → rsync в ~/srv/wordpdf-docs
```
`docs-deploy` выполняет фиксированный порядок: `mvn javadoc:javadoc` → копия
`wordpdf-core/target/site/apidocs` → `docs/apidocs` → `mkdocs build --strict` →
`rsync -a --delete site/ ~/srv/wordpdf-docs/`. **Рестарт сервиса не нужен** —
nginx раздаёт файлы с смонтированного тома. Strict-сборка ловит битые ссылки и
страницы вне `nav`.
Dev-цикл: `./mise.sh run docs-serve` → `http://127.0.0.1:8000/` (live-reload).
## Сервис отдачи
Rootless podman (nginx-контейнер) под user-systemd (`linger=yes`). Юнит
`~/.config/systemd/user/wordpdf-docs.service` (вне git; канон текста — здесь):
```ini
[Unit]
Description=Word PDF — сайт документации (nginx static, :9012)
[Service]
# podman run без -d — foreground, systemd видит основной процесс
ExecStart=/usr/bin/podman run --name wordpdf-docs --replace -p 9012:80 -v /home/pjandro/srv/wordpdf-docs:/usr/share/nginx/html:ro docker.io/library/nginx:alpine
ExecStopPost=/usr/bin/podman rm -f wordpdf-docs
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
[Install]
WantedBy=default.target
```
Разовая установка (на хосте `192.168.88.23`):
```bash
podman pull docker.io/library/nginx:alpine
install -d /home/pjandro/srv/wordpdf-docs
systemctl --user daemon-reload
systemctl --user enable --now wordpdf-docs.service
```
Проверка/управление:
```bash
systemctl --user status wordpdf-docs.service
journalctl --user -u wordpdf-docs.service -n 50
curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9012/
```
Порт 9012: соседние 9010/9011 заняты стендами конвертера (конвенция сети), 8000 —
dev-preview. Наружу (wan) не публикуем; наружный nginx `pjandro.ru` при желании
добавит владелец сервера отдельно.
## Почему не Gitea Pages
Публиковать на инстансе `git.pjandro.ru` (Gitea 1.26.4) проверенным способом «Pages»
нельзя — встроенного Pages в этой сборке нет:
- в swagger инстанса отсутствует эндпоинт `/repos/{owner}/{repo}/pages`,
в config cheat sheet — `ENABLE_PAGES`/`PAGES_DOMAIN`;
- FAQ инстанса: «Gitea doesn't provide a built-in Pages server»;
- в Gitea Actions игнорируется `jobs.*.environment`, не поддерживаются scopes
`pages`/`deployments`; тандем `upload-pages-artifact` + `deploy-pages`
неработоспособен (`upload-artifact@v4` не поддерживается, `@v3` подвешивается).
Поэтому публикация — локальная задача `docs-deploy` на том же хосте, где живёт
сервис; CI не участвует (docs-файлы не требуют гейтов).
## Что входит в сайт / не входит
В сайт попадают все страницы `docs/`, **кроме** `docs/agent/`, `docs/standards/`
и `docs/requirements.txt` (`exclude_docs` в `mkdocs.yml`) — это внутренние
справочники и спецификации, на них ведут внешние ссылки на Gitea
([Внутренние справочники](../internal-guides.md)). Каталог `docs/apidocs/`
(gitignored) заполняется задачей `docs-deploy` и копируется mkdocs как статика.
+61
View File
@@ -0,0 +1,61 @@
# Стенды и топология
Наружу публикуется **только nginx-gateway**; контейнер `app` (:8080) наружу не
выставляется никогда. Порты стендов зафиксированы конвенцией сети.
|Стенд|Файл|Вход|Ключ доступа|springdoc|
|---|---|---|---|---|
|prod|`docker-compose.yml` (рендерится CI)|`https://pjandro.ru/pdf-converter/`|обязателен (Gitea Secret)|открыт|
|prod-like (локально)|`compose.yml`|`http://localhost:9010/`|fail-closed: `.env` с `WORDPDF_API_KEY`|выключен env-ами|
|dev|`compose.dev.yml`|`http://<LAN-IP>:9011/`|выключен|включён|
|без контейнеров|`java -jar` + `npm run dev`|`:8080` + `:5173`|выключен|включён|
## Gateway (prod-like/dev)
`gateway/nginx.conf`: `client_max_body_size 100m`, таймауты прокси 300 с,
`resolver` привязан literal-ом к шлюзу docker-сети стенда (10.113.0.1 / 10.112.0.1 —
не путать при копировании).
Маршруты:
|Location|Куда|
|---|---|
|`/api/`|`app:8080` (URI передаётся как есть)|
|`/swagger-ui`, `/v3/api-docs`, `/actuator`|`app:8080`|
|`/` (остальное)|`web` — чистая статика SPA|
`proxy_pass` через переменную + `resolver` — чтобы DNS-имя контейнера резолвилось
на каждый запрос, а не один раз при старте nginx.
## Подъём
```bash
# dev (:9011) — «тестовый сервер» проекта
podman-compose -f compose.dev.yml up -d --build --force-recreate
# prod-like (:9010) — нужен .env с WORDPDF_API_KEY (fail-closed), шаблон .env.example
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build
```
!!! warning "--force-recreate"
Без него podman-compose пересоберёт образ, но контейнеры оставит на старом —
будет крутиться jar прошлой сборки.
## Прод
Прод-стек (`docker-compose.yml` + прод `nginx.conf`) **не хранится ни на хосте, ни в
репозитории** — job `deploy` в CI рендерит их из Gitea Variables (ключ — из Secret,
на диск не пишется), затем pull/`up -d --force-recreate`/health-гейты/автооткат.
Копии прод-конфигов на хосте/в репо — нарушение конвенции. Подробности —
[Деплой](deployment.md).
## Порты (конвенция)
|Порт|Кто|
|---|---|
|9010|prod-like gateway|
|9011|dev gateway|
|9012|сайт документации (nginx static, [Docs-сайт](docs-site.md))|
|8080|`java -jar` бэкенд (только localhost)|
|5173|vite dev-сервер SPA|
+74
View File
@@ -0,0 +1,74 @@
# Troubleshooting
Симптом → причина → действие. Только подтверждённое поведение стендов.
## 401 «Ключ доступа не передан или неверен»
- Забыт заголовок `X-API-Key` / ключ не совпадает со `WORDPDF_API_KEY` сервера.
- Prod-like стенд не поднимается без `.env` — это fail-closed (`${WORDPDF_API_KEY:?}`),
не баг.
- Запрос идёт через точечный сегмент (`/actuator/../api/...`) — открытые префиксы
с `..`/`%2e` ключем не обходятся, так и задумано.
- Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что
`probeApiKey()` дошёл до сервера (network-вкладка); ключ из localStorage
стирается при 401.
## 422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты»
Не ошибка — сработал включённый error-флаг запроса. Снимите `errorOnCharts`/
`errorOnSmartArt`/`errorOnOle` (по умолчанию выключены). На `.doc` флаги не
срабатывают в принципе (плейсхолдеры — растры).
## 503
Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы.
Повторите позже. Систематически — увеличивайте время ответа вниз (документы
поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый
со своей очередью).
## 504
Конвертация дольше `wordpdf.convert-timeout` (2m). Уменьшите документ (много
больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая
конвертация дожигается, следующий запрос ждёт её в очереди.
## 413
Тело больше контейнерного потолка multipart (100 МБ) или nginx `client_max_body_size
100m` — обе границы стоят 100 МБ. Логический лимит входа (`wordpdf.max-mb`, дефолт
5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят
выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше,
но 413? Проверьте, не режет ли промежуточный прокси.
## В PDF напечатано «...TO HIDE THESE MESSAGES...»
В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF.
Для библиотеки: оставить `slf4j-simple` (в транзитивах `wordpdf-core`) или принести
свой провайдер. Для app: `slf4j-simple` исключён в пользу logback — если логическая
конфигурация app сломана и SLF4J не инициализирован, верните провайдер.
## Картинки диаграмм «мыльные» (ресемпл)
Нарушен контракт префикса media-частей `/word/media/chart-*`: по нему
`ChartImageHandler` отключает пересжатие PNG в FOP. Если части переименованы
ручной правкой — верните префикс (`DrawingPreRenderer.CHART_MEDIA_URI_PREFIX`).
## Вместо знаков — `#` или пустые боксы
- `#` — глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию
(для docx-пута это регрессия — заведите issue с документом).
- Пустой бокс `.notdef` для U+2188/U+218A — известное ограничение OFL-бандла, не чинится.
- «Битый»/подменённый шрифт в целом — проверьте алиасы (`Calibri→Carlito` и т.д.,
[Шрифты](../architecture/fonts.md)): подмена метрически совместима и ожидаема.
## Стенд крутит старый код после пересборки
podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите
с `--force-recreate` ([Стенды](stack.md)).
## `.doc` не конвертируется (400)
Проверьте сигнатуру: `D0 CF 11 E0 A1 B1 1A E1`. Word 6–95 и зашифрованные (Office 95
password) документы мостом не поддерживаются → 400/`ValidationException`. Расширение
`.doc` при zip-содержимом (переименованный docx) маршрутизируется по байтам — это
не ошибка.
+1
View File
@@ -0,0 +1 @@
mkdocs-material==9.8.2
+56
View File
@@ -0,0 +1,56 @@
# Пользователю
## Где открыть
Веб-конвертер: **`https://pjandro.ru/pdf-converter/`**. Работает в любом современном
браузере, установка не нужна.
## Как пользоваться
1. Перетащите файл `.docx` или `.doc` в зону загрузки (или выберите его через диалог).
2. Документ конвертируется на сервере; результат появляется во встроенном
предпросмотре PDF.
3. Нажмите «Скачать» — PDF сохранится под именем исходного файла с расширением `.pdf`
(кириллица в имени поддерживается).
В форме есть три переключателя («Диаграммы», «SmartArt», «OLE-объекты», по умолчанию
выключены): при включённом конвертация **отменится**, если документ содержит
соответствующие объекты, и интерфейс покажет понятное сообщение. По умолчанию
диаграммы и SmartArt конвертируются в картинки всегда, а OLE-объекты тихо удаляются
(картинка-плейсхолдер из документа сохраняется).
## Ключ доступа
Если сервер защищён ключом доступа, при первом открытии появится экран ввода ключа.
Ключ хранится в браузере (localStorage) и подставляется автоматически; при неверном
ключе стирается, и экран появляется снова. Если сервер ключ не требует, экран не
показывается вовсе.
## Поддерживаемые форматы
|Формат|Что это|
|---|---|
|`.docx`|OOXML (Word 2007 и новее), включая строгий (strict) OOXML|
|`.doc`|бинарный Word 97–2003; читается собственным мостом, без Word и LibreOffice|
Лимиты документа (размер, число страниц) задаёт сервер; конкретные значения зависят
от развёрнутого экземпляра.
## Что конвертируется точно, а что приближённо
Конвертер **не является pixel-perfect рендером Word**: это ограничения движка
FOP/docx4j, а не упущение проекта. Текст, стили, таблицы, списки, колонтитуки,
картинки, диаграммы и SmartArt воспроизводятся надёжно; раскладка, поля и некоторые
эффекты могут отличаться от Word.
Символы, которых нет в шрифте ранa (например, тире «—», кавычки), берутся из
fallback-семейства DejaVu с гарантированной кириллицей. Знаков, которых нет ни в одном
шрифте бандла, это не касается — для них останутся пустые боксы; в эталонном наборе
таких символа два (U+2188, U+218A — римские/осмы числительные, доступны только в
GPL-шрифтах).
На `.doc` переключатели «Диаграммы/SmartArt/OLE» не срабатывают: плейсхолдеры
бинарного формата — уже растры, они вставляются картинками; векторные EMF/WMF/PICT
пропускаются.
Полный перечень известных расхождений — [Ограничения рендера](architecture/limitations.md).
+10
View File
@@ -16,6 +16,16 @@ server {
set $upstream_app http://app:8080; set $upstream_app http://app:8080;
set $upstream_web http://web:80; set $upstream_web http://web:80;
# X-Forwarded-* переписываются безусловно: клиент не должен иметь возможности
# подсунуть бэкенду подставной "реальный IP/схема/хост" (Spring
# ForwardedHeaderFilter доверяет этим заголовкам; прямое попадание на
# 9010 мимо внешнего reverse-proxy — штатный случай стенда).
# X-Forwarded-Prefix не трогаем: его проставляет внешний nginx, на нём
# держится корректный base у swagger-ui за прокси.
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
location /api/ { location /api/ {
# в proxy_pass нет path-части, поэтому URI передаётся как есть # в proxy_pass нет path-части, поэтому URI передаётся как есть
proxy_pass $upstream_app; proxy_pass $upstream_app;
Executable
+128
View File
@@ -0,0 +1,128 @@
#!/bin/sh
# Замер памяти конвейера конвертации: пики кучи на конвертацию (TSV из MemoryBench)
# + топ аллокаций по JFR (jdk.ObjectAllocationSample). Методика и числа —
# docs/MEM_USAGE_UPGRADE.md.
#
# Вход: env MB_LABEL — метка прогона (before/after/f1…, файл JFR per-label);
# env MB_JAVA_OPTS — доп. флаги JVM ПОСЛЕ дефолтных (переопределение Xmx/GC
# для матрицы флагов; при -Xmx меньше дефолтного дефолт просто заменяется;
# для смены GC нужен и выключатель дефолта: "-XX:-UseG1GC -XX:+UseSerialGC",
# иначе JVM падает на старте с "Multiple garbage collectors selected");
# аргументы проходят в MemoryBench: --scenario suite|big|all|, --loops N,
# --big-loops N, --dir PATH (реальные документы, напр. develop/).
#
# Пример: MB_LABEL=before ./mise.sh run mem-bench --scenario all --loops 20 | tee target/mem-before.txt
set -eu
cd "$(dirname "$0")"
LABEL=${MB_LABEL:-run}
mvn -q -pl wordpdf-core test-compile
CPFILE=$PWD/wordpdf-core/target/cp.txt
if [ ! -f "$CPFILE" ] || [ wordpdf-core/pom.xml -nt "$CPFILE" ]; then
mvn -q -pl wordpdf-core org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath \
-Dmdep.outputFile="$CPFILE" -Dmdep.includeScope=test
fi
JFR=$PWD/wordpdf-core/target/membench-$LABEL.jfr
GCLOG=$PWD/wordpdf-core/target/membench-$LABEL.gc.log
ERRLOG=$PWD/wordpdf-core/target/membench-$LABEL.err
printf '# git %s\n' "$(git rev-parse HEAD)"
printf '# date %s\n' "$(date -u +%FT%TZ)"
printf '# MB_JAVA_OPTS=%s\n' "${MB_JAVA_OPTS:-}"
# MB_JAVA_OPTS без кавычек — намеренно: несколько флагов одним словом пользователя.
# shellcheck disable=SC2086
java -Xms64m -Xmx2g -XX:+UseG1GC -Djava.awt.headless=true \
-Xlog:gc*=info,gc+heap=debug:file=$GCLOG \
${MB_JAVA_OPTS:-} \
-XX:StartFlightRecording=filename=$JFR,settings=profile,maxsize=0,loglevel=error \
-cp "wordpdf-core/target/classes:wordpdf-core/target/test-classes:$(cat "$CPFILE")" \
ru.pjandro.wordpdf.MemoryBench "$@" 2>"$ERRLOG"
# --- аллокации по GC-логу (абсолютная оценка) -----------------------------------
# allocated ≈ выметенный Eden + выметенные humongous-области (G1); max-live —
# максимум heap после пауз (тренд накопления); паузы — число/сумма.
# awk — портативный (mawk/gawk): без 3-аргументного match().
echo
awk '
/Region Size:/ {
for (i = 1; i <= NF; i++) { if ($i ~ /^[0-9]+M$/) { tok = $i; sub(/M$/, "", tok); rs = tok + 0 } }
}
/Eden regions:/ {
for (i = 1; i <= NF; i++) {
if ($i ~ /^[0-9]+->[0-9]+/) { p = $i; sub(/\(.*/, "", p); split(p, a, "->"); eden += (a[1] - a[2]) * rs }
}
}
/Humongous regions:/ {
for (i = 1; i <= NF; i++) {
if ($i ~ /^[0-9]+->[0-9]+/) { p = $i; sub(/\(.*/, "", p); split(p, a, "->"); hum += (a[1] - a[2]) * rs }
}
}
/Pause (Young|Full)/ && /M->/ {
pauses++
tail = $NF; if (tail ~ /[0-9]ms$/) { sub(/ms$/, "", tail); ptime += tail }
for (i = 1; i <= NF; i++) {
if ($i ~ /^[0-9]+M->[0-9]+M/) {
v = $i; sub(/\(.*/, "", v); split(v, m, "->")
if (m[2] + 0 > maxlive) { maxlive = m[2] + 0 }
}
}
}
END {
printf "gc-summary allocated-estimate=%dMB max-live-after-gc=%dMB pauses=%d pause-total=%dms\n",
eden + hum, maxlive, pauses, ptime
}
' "$GCLOG"
# --- агрегация аллокаций из JFR -------------------------------------------------
TOPF=$(mktemp); APPF=$(mktemp)
trap 'rm -f "$TOPF" "$APPF"' EXIT
jfr print --events jdk.ObjectAllocationSample "$JFR" | awk \
-v TOPF="$TOPF" -v APPF="$APPF" '
function framekey(line, k) {
k = line
sub(/^[ \t]+/, "", k)
sub(/ line: [0-9]+$/, "", k)
return k
}
function cls(key, c) {
c = key
sub(/ ?\(.*$/, "", c)
sub(/^[^ ]*\//, "", c)
return c
}
/^ *weight = / { w = $3 + 0 }
/^ *stackTrace = \[/ { instk = 1; nf = 0; next }
instk == 1 && /^ *\]/ {
instk = 0
if (nf == 0) { next }
top = fr[1]
app = ""
for (i = 1; i <= nf; i++) {
c = cls(fr[i])
if (c !~ /^(java|javax|jdk|sun|com\.sun|org\.apache|org\.docx4j|org\.springframework|org\.springdoc|org\.w3c|org\.xml|net\.sf|org\.slf4j|ch\.qos)/) {
app = fr[i]
break
}
}
wsum[top] += w
if (app != "") { asum[app] += w }
next
}
instk == 1 { nf++; fr[nf] = framekey($0) }
END {
for (k in wsum) { print wsum[k] "\t" k > TOPF }
for (k in asum) { print asum[k] "\t" k > APPF }
}
'
echo
printf '===== top-frames: суммарный вес аллокаций, байт (JFR profile, оценка) — label %s =====\n' "$LABEL"
sort -rn "$TOPF" | head -15
printf '===== alloc-total: %s байт\n' "$(awk '{s+=$1} END {printf "%.0f", s}' "$TOPF")"
echo
printf '===== app-sites: аллокации с первым кадром из приложения (attribution) =====\n'
sort -rn "$APPF" | head -15
+38
View File
@@ -14,6 +14,14 @@ _.python.venv = { path = "prod-autotests/.venv", create = true }
description = "mvn clean verify — полный гейт перед push (тесты + PMD + JaCoCo)" description = "mvn clean verify — полный гейт перед push (тесты + PMD + JaCoCo)"
run = "mvn clean verify" run = "mvn clean verify"
[tasks.verify-nofontconfig]
description = "mvn clean verify в контейнере без fontconfig (гейт, которым живёт CI; verify — хост-гейт без контейнера)"
run = "podman build -f Containerfile.test ."
[tasks.mem-bench]
description = "Замер памяти конвейера: TSV пиков кучи + топ аллокаций JFR (docs/MEM_USAGE_UPGRADE.md)"
run = "sh membench.sh"
[tasks.app-package] [tasks.app-package]
description = "Исполняемый jar бэкенда" description = "Исполняемый jar бэкенда"
run = "mvn -pl wordpdf-app -am package" run = "mvn -pl wordpdf-app -am package"
@@ -46,3 +54,33 @@ run = "npm run dev"
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)" description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
dir = "prod-autotests" dir = "prod-autotests"
run = "python -m pip install -q -r requirements.txt && python -m pytest -q ." run = "python -m pip install -q -r requirements.txt && python -m pytest -q ."
[tasks.docs-install]
description = "Зависимости сайта документации: venv docs/.venv + mkdocs-material"
run = [
"[ -d docs/.venv ] || python -m venv docs/.venv",
"docs/.venv/bin/python -m pip install -q -r docs/requirements.txt",
]
[tasks.docs-serve]
description = "Локальный предпросмотр сайта на :8000 (live-reload)"
run = "docs/.venv/bin/mkdocs serve -a 127.0.0.1:8000"
[tasks.docs-build]
description = "Strict-сборка сайта в site/ (битые ссылки/навигация = ошибка)"
run = "docs/.venv/bin/mkdocs build --strict"
[tasks.docs-javadoc]
description = "Javadoc публичного API core в wordpdf-core/target/site/apidocs"
run = "mvn -q -pl wordpdf-core -am javadoc:javadoc"
[tasks.docs-deploy]
description = "Публикация сайта на rpi (:9012): javadoc + strict-build + rsync в ~/srv/wordpdf-docs"
run = [
"mvn -q -pl wordpdf-core -am javadoc:javadoc",
"rm -rf docs/apidocs",
"cp -r wordpdf-core/target/site/apidocs docs/apidocs",
"docs/.venv/bin/mkdocs build --strict",
"install -d /home/pjandro/srv/wordpdf-docs",
"rsync -a --delete site/ /home/pjandro/srv/wordpdf-docs/",
]
+76
View File
@@ -0,0 +1,76 @@
site_name: «Word → PDF конвертер» — документация
site_description: "docx4j + Apache FOP на чистой Java: библиотека, REST API, веб-интерфейс"
docs_dir: docs
site_dir: site
exclude_docs: |
/agent/
/standards/
/requirements.txt
# javadoc-копия (docs/apidocs, заполняет docs-deploy) — статика вне навигации;
# её md-файлы (legal/*) mkdocs иначе показывает как страницы вне nav
not_in_nav: |
/apidocs/**/*.md
theme:
name: material
language: ru
palette:
- scheme: default
primary: indigo
toggle:
icon: material/weather-sunny
name: Тёмная тема
- scheme: slate
primary: indigo
toggle:
icon: material/weather-night
name: Светлая тема
features:
- navigation.sections
- navigation.top
- toc.follow
- search.suggest
markdown_extensions:
- admonition
- attr_list
- footnotes
- toc:
permalink: true
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
plugins:
- search:
lang: ru
nav:
- Главное: index.md
- Пользователю: user.md
- REST API:
- api/index.md
- Аутентификация: api/authentication.md
- Эндпоинт конвертации: api/convert-endpoint.md
- Коды ошибок: api/errors.md
- Лимиты: api/limits.md
- Примеры клиентов: api/examples.md
- Библиотека wordpdf-core:
- library/getting-started.md
- library/api.md
- library/dependencies.md
- Архитектура:
- architecture/overview.md
- architecture/doc-bridge.md
- architecture/charts.md
- architecture/fonts.md
- architecture/limitations.md
- Разработчику:
- development/setup.md
- development/testing.md
- development/contributing.md
- Эксплуатация:
- operations/stack.md
- operations/configuration.md
- operations/deployment.md
- operations/troubleshooting.md
- operations/docs-site.md
- "Отчёт: потребление памяти": MEM_USAGE_UPGRADE.md
- Внутренние справочники репозитория: internal-guides.md
+30 -70
View File
@@ -2,76 +2,36 @@
<ruleset name="WordPDF code style" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0" <ruleset name="WordPDF code style" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd"> xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
<description>Код-стиль java-word-pdf: codestyle без opinionated-правил + unused-правила + NPE-safe equals</description> <description>Код-стиль java-word-pdf: закрытый список правил под движок PMD 6.55.0
(maven-pmd-plugin 3.21.2; откат с PMD 7 — правила *MustUseBraces удалены в 7-й
мажорной, их deprecation-предупреждения в логе verify ожидаемы). Нарушения чинятся
кодом — подавление @SuppressWarnings("PMD…") и // NOPMD запрещены; правила не
исключаются и не перенастраиваются.</description>
<rule ref="category/java/codestyle.xml"> <rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach"/>
<!-- opinionated/шумные, намеренно выключены --> <rule ref="category/java/design.xml/ExceptionAsFlowControl"/>
<exclude name="AtLeastOneConstructor"/> <rule ref="category/java/errorprone.xml/EqualsNull"/>
<exclude name="CallSuperInConstructor"/> <rule ref="category/java/errorprone.xml/CloseResource"/>
<exclude name="CommentDefaultAccessModifier"/> <rule ref="category/java/errorprone.xml/BrokenNullCheck"/>
<exclude name="ConfusingTernary"/> <rule ref="category/java/bestpractices.xml/AvoidPrintStackTrace"/>
<exclude name="FieldDeclarationsShouldBeAtStartOfClass"/> <rule ref="category/java/errorprone.xml/AvoidLosingExceptionInformation"/>
<exclude name="LocalVariableCouldBeFinal"/>
<exclude name="LongVariable"/>
<exclude name="MethodArgumentCouldBeFinal"/>
<exclude name="OnlyOneReturn"/>
<exclude name="PrematureDeclaration"/>
<exclude name="ShortMethodName"/>
<exclude name="ShortVariable"/>
<exclude name="UseExplicitTypes"/>
<exclude name="UseUnderscoresInNumericLiterals"/>
<!-- переопределены ниже -->
<exclude name="MethodNamingConventions"/>
<exclude name="TooManyStaticImports"/>
</rule>
<!-- регрессионные тесты репо именуются объект_условие (AGENTS.md) -->
<rule ref="category/java/codestyle.xml/MethodNamingConventions">
<properties>
<property name="junit5TestPattern" value="^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$"/>
</properties>
</rule>
<!-- MockMvc-тесты: >4 статических импортов — норма -->
<rule ref="category/java/codestyle.xml/TooManyStaticImports">
<properties>
<property name="maximumStaticImports" value="12"/>
</properties>
</rule>
<!-- PMD 7 удалил EqualsAvoidsNull; NPE-safe порядок операндов: литерал слева -->
<rule name="LiteralFirstInEquals" language="java"
message="NPE-safe сравнение строк: строковый литерал должен стоять слева: &quot;lit&quot;.equals(x)"
class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
<priority>3</priority>
<properties>
<property name="xpath">
<value><![CDATA[
//MethodCall[
(@MethodName = 'equals' or @MethodName = 'equalsIgnoreCase')
and ArgumentList/StringLiteral
and not(*[1][self::StringLiteral
or (self::VariableAccess and @CompileTimeConstant = true())])
]
]]></value>
</property>
</properties>
</rule>
<rule ref="category/java/bestpractices.xml/UnusedAssignment"/>
<rule ref="category/java/bestpractices.xml/UnusedFormalParameter"/>
<rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateMethod"/>
<!-- null вместо пустой коллекции запрещён (priority 1 по умолчанию — валит verify) -->
<rule ref="category/java/errorprone.xml/ReturnEmptyCollectionRatherThanNull"/>
<!-- литералы в условиях if — только именованными константами -->
<rule ref="category/java/errorprone.xml/AvoidLiteralsInIfCondition"/> <rule ref="category/java/errorprone.xml/AvoidLiteralsInIfCondition"/>
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"> <rule ref="category/java/errorprone.xml/AvoidCatchingNPE"/>
<priority>2</priority> <rule ref="category/java/errorprone.xml/AssignmentToNonFinalStatic"/>
</rule> <rule ref="category/java/errorprone.xml/DoNotCallGarbageCollectionExplicitly"/>
<rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach"> <rule ref="category/java/errorprone.xml/EmptyCatchBlock"/>
<priority>2</priority> <rule ref="category/java/errorprone.xml/CompareObjectsWithEquals"/>
</rule> <rule ref="category/java/bestpractices.xml/UnusedPrivateMethod"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
<rule ref="category/java/codestyle.xml/UnnecessaryImport"/>
<rule ref="category/java/bestpractices.xml/SystemPrintln"/>
<rule ref="category/java/multithreading.xml/UnsynchronizedStaticFormatter"/>
<rule ref="category/java/errorprone.xml/ReturnEmptyCollectionRatherThanNull"/>
<rule ref="category/java/errorprone.xml/MisplacedNullCheck"/>
<rule ref="category/java/bestpractices.xml/LiteralsFirstInComparisons"/>
<rule ref="category/java/codestyle.xml/WhileLoopsMustUseBraces"/>
<rule ref="category/java/codestyle.xml/IfStmtsMustUseBraces"/>
<rule ref="category/java/codestyle.xml/IfElseStmtsMustUseBraces"/>
<rule ref="category/java/errorprone.xml/ImplicitSwitchFallThrough"/>
<rule ref="category/java/codestyle.xml/ForLoopsMustUseBraces"/>
</ruleset> </ruleset>
+24 -1
View File
@@ -39,6 +39,8 @@
<!-- Покрытие: последняя стабильная на Maven Central --> <!-- Покрытие: последняя стабильная на Maven Central -->
<jacoco.version>0.8.15</jacoco.version> <jacoco.version>0.8.15</jacoco.version>
<!-- Javadoc публичного API core: последняя стабильная на Maven Central -->
<maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
<!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся <!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его --> о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
<argLine></argLine> <argLine></argLine>
@@ -156,10 +158,31 @@
<artifactId>maven-jar-plugin</artifactId> <artifactId>maven-jar-plugin</artifactId>
<version>3.5.1</version> <version>3.5.1</version>
</plugin> </plugin>
<!-- Javadoc: генерация только по явной цели javadoc:javadoc
(объявлен без executions в wordpdf-core) — поведение
mvn clean verify не затрагивает. -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin.version}</version>
<configuration>
<encoding>UTF-8</encoding>
<doclint>all,-missing</doclint>
<show>protected</show>
<nohelp>true</nohelp>
<windowtitle>wordpdf-core API</windowtitle>
<doctitle>wordpdf-core API (javadoc)</doctitle>
<!-- пин вывода: у 3.12.0 дефолт target/reports (параметр
outputDirectory, поверх него плагин сам кладёт apidocs/),
фиксируем target/site → target/site/apidocs — оттуда
копирует задача docs-deploy -->
<outputDirectory>${project.build.directory}/site</outputDirectory>
</configuration>
</plugin>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId> <artifactId>maven-pmd-plugin</artifactId>
<version>3.28.0</version> <version>3.21.2</version>
<configuration> <configuration>
<rulesets> <rulesets>
<ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset> <ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset>
+3 -3
View File
@@ -8,9 +8,9 @@ WORDPDF_BASE_URL обязателен: без него все проверки
не знает ни одного хоста. WORDPDF_API_KEY факультативен: без него проверки, не знает ни одного хоста. WORDPDF_API_KEY факультативен: без него проверки,
где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа
нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт 100 = лимит страниц стенда (конфигурация сервера, не константа набора; дефолт эндпоинта
дефолт ядра). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт 100). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
5 = дефолт ядра). .docx-фикстуры — из wordpdf-core/src/test/resources/samples, эндпоинта 5). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
либо из WORDPDF_SAMPLES_DIR. либо из WORDPDF_SAMPLES_DIR.
""" """
@@ -63,11 +63,17 @@ final class ApiExceptionHandler {
.body(new ApiError(e.getMessage())); .body(new ApiError(e.getMessage()));
} }
/** Ошибка ядра/рендера при формально корректном входе. */ /**
* Ошибка ядра/рендера при формально корректном входе. Сообщение ядра
* (тексты docx4j/FOP/JAXB, пути temp-файлов) — только в лог: наружу
* фиксированный текст, иначе 500 становится каналом внутренней информации.
* Регрессия — ConvertControllerTest#conversionFailure_hidesInternalDetails.
*/
@ExceptionHandler(ConversionFailedException.class) @ExceptionHandler(ConversionFailedException.class)
ResponseEntity<ApiError> conversionFailed(ConversionFailedException e) { ResponseEntity<ApiError> conversionFailed(ConversionFailedException e) {
LOG.error("Конвертация не удалась", e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(new ApiError(e.getMessage())); .body(new ApiError("Не удалось конвертировать документ"));
} }
/** Очередь конвертации занята/прерывание — повторить позже. */ /** Очередь конвертации занята/прерывание — повторить позже. */
@@ -3,9 +3,11 @@ package ru.pjandro.wordpdf.app;
import jakarta.annotation.PreDestroy; import jakarta.annotation.PreDestroy;
import org.springframework.beans.factory.annotation.Value; import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service; import org.springframework.stereotype.Service;
import ru.pjandro.wordpdf.ChartsFoundException;
import ru.pjandro.wordpdf.ConvertOptions; import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.ConversionException; import ru.pjandro.wordpdf.ConversionException;
import ru.pjandro.wordpdf.DrawingFoundException; import ru.pjandro.wordpdf.OleFoundException;
import ru.pjandro.wordpdf.SmartArtFoundException;
import ru.pjandro.wordpdf.WordPdfConverter; import ru.pjandro.wordpdf.WordPdfConverter;
import ru.pjandro.wordpdf.WordPdfValidator; import ru.pjandro.wordpdf.WordPdfValidator;
import ru.pjandro.wordpdf.ValidationException; import ru.pjandro.wordpdf.ValidationException;
@@ -23,22 +25,23 @@ import java.util.concurrent.TimeoutException;
/** /**
* Конвертация .docx-байтов в PDF-байты поверх {@code wordpdf-core}. * Конвертация .docx-байтов в PDF-байты поверх {@code wordpdf-core}.
* *
* <p>Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом — не «на всякий * <p>Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом: он держит очередь,
* случай»: каждая конвертация мутирует ГЛОБАЛЬНЫЙ реестр шрифтов docx4j * 503 при переполнении и timeout-семантику (backpressure). Само ядро при этом
* ({@code new BundledFontMapper()} заново добавляет системные шрифты * сериализует конвертации внутренним монитором ({@code WordPdfConverter.class}:
* в {@code PhysicalFonts}, {@code BundledFonts.init()/restrictToBundled()} * глобальный реестр {@code PhysicalFonts}, общая FopFactory с имиджевыми
* их вычищают — WordPdfConverter.convertToStream, шаг 1 пайплайна). Параллельные конвертации * кешами и их сброс в finally мутируются под рендером), так что параллельные
* вырывают реестр друг у друга из-под рендера, ядро не потокобезопасно * вызовы ядра не приводят к порче вывода.
* by design. Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.</p> * Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.</p>
* *
* <p>Ошибки разделены по смыслу (требование к API): некорректный вход → * <p>Ошибки разделены по смыслу (требование к API): некорректный вход →
* {@link ValidationException} (400), ошибка рендер-стадии → * {@link ValidationException} (400), ошибка рендер-стадии →
* {@link ConversionFailedException} (500). Граница: сломанный контейнер * {@link ConversionFailedException} (500). Граница: сломанный контейнер
* (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный * (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный
* zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди и * zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди
* в конвейере ядра вход проверяется тем же * проверяется только размер, корректность контейнера и число страниц —
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}, поэтому уже * сериализованно внутри воркера (ядро вызывает тот же
* принятый запрос внутренняя проверка ядра в ошибку не превратит.</p> * {@link WordPdfValidator#validate(byte[], ConvertOptions)}), поэтому
* тяжёлая проверка не занимает потоки контейнера в обход сериализации.</p>
*/ */
@Service @Service
final class ConversionService { final class ConversionService {
@@ -55,17 +58,18 @@ final class ConversionService {
new ArrayBlockingQueue<>(QUEUE_CAPACITY)); new ArrayBlockingQueue<>(QUEUE_CAPACITY));
// Прогрев ядра — головой той же однопоточной очереди: первый реальный // Прогрев ядра — головой той же однопоточной очереди: первый реальный
// запрос после деплоя становится за прогретым ядром (~50–300 мс вместо // запрос после деплоя становится за прогретым ядром (~50–300 мс вместо
// 1,4–1,9 с) и гарантированно сериализован с конвертациями (ядро не // 1,4–1,9 с); сериализация прогрева с конвертациями — тем же воркером
// потокобезопасно). warmup() не бросает — Future никто не забирает; // и монитором ядра (warmup() синхронизирован им же). warmup() не
// бросает — Future никто не забирает;
// запросы, пришедшие во время прогрева, ждут в очереди (штатная // запросы, пришедшие во время прогрева, ждут в очереди (штатная
// семантика, лимит convert-timeout с запасом). // семантика, лимит convert-timeout с запасом).
this.workers.submit(WordPdfConverter::warmup); this.workers.submit(WordPdfConverter::warmup);
} }
/** /**
* Полный путь: синхронная валидация байтов (до очереди — от obvious-отказа * Полный путь: синхронная проверка размера (до очереди) → постановка
* единый воркер не должен быть занят) → постановка в очередь → ожидание * в очередь → ожидание результата с таймаутом; корректность контейнера
* результата с таймаутом. * и число страниц проверяются сериализованно, внутри воркера (ядро).
* *
* @throws ValidationException некорректный вход (400) * @throws ValidationException некорректный вход (400)
* @throws ConversionFailedException ошибка ядра/рендера (500) * @throws ConversionFailedException ошибка ядра/рендера (500)
@@ -77,14 +81,14 @@ final class ConversionService {
* {@code null} не допускается (контроллер строит всегда).</p> * {@code null} не допускается (контроллер строит всегда).</p>
*/ */
byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) { byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) {
// Бинарный .doc — не zip: .docx-валидация к нему неприменима, размер // До очереди — только дешёвый гейт размера. Полная валидация
// проверяется общим checkInput, страницы — мостом по чистому .doc // (контейнер + страницы — до двух полных распакованных проходов до
// (ядро бросит ValidationException → 400 тем же обработчиком). // 64 МБ на обоих форматах) сериализована воркером: её выполняет ядро
if (WordPdfValidator.isBinaryDoc(docxBytes)) { // внутри WordPdfConverter.convert (тот же validate с теми же
WordPdfValidator.checkInput(docxBytes, options.maxMb()); // options, ValidationException → 400 тем же путём). Синхронный
} else { // полный validate до submit отдавал бы zip-бомбе потоки Tomcat
WordPdfValidator.validate(docxBytes, options); // в обход сериализации.
} WordPdfValidator.checkInput(docxBytes, options.maxMb());
Future<byte[]> future; Future<byte[]> future;
try { try {
future = workers.submit(() -> doConvert(docxBytes, originalFilename, options)); future = workers.submit(() -> doConvert(docxBytes, originalFilename, options));
@@ -139,10 +143,14 @@ final class ConversionService {
// отказ проверки страниц внутри конвейера ядра — некорректный // отказ проверки страниц внутри конвейера ядра — некорректный
// вход (400), а не ошибка рендера: без этого утонул бы в 500 // вход (400), а не ошибка рендера: без этого утонул бы в 500
throw e; throw e;
} catch (DrawingFoundException e) { } catch (ChartsFoundException e) {
// отказ по настройке запроса (error-флаг) — не ошибка рендера: 422, // отказ по настройке запроса (error-флаг) — не ошибка рендера: 422,
// иначе утонет в общем catch ниже как 500 // иначе утонет в общем catch ниже как 500
throw new DrawingRejectedException(e.kind()); throw new DrawingRejectedException(DrawingRejectedException.CHARTS);
} catch (SmartArtFoundException e) {
throw new DrawingRejectedException(DrawingRejectedException.SMART_ART);
} catch (OleFoundException e) {
throw new DrawingRejectedException(DrawingRejectedException.OLE);
} catch (ConversionException e) { } catch (ConversionException e) {
// всё, что упало на валидации/рендер-стадии ядра, — ошибка преобразования, 500 // всё, что упало на валидации/рендер-стадии ядра, — ошибка преобразования, 500
throw new ConversionFailedException("Не удалось конвертировать документ: " throw new ConversionFailedException("Не удалось конвертировать документ: "
@@ -12,7 +12,6 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value; import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.multipart.MultipartFile; import org.springframework.web.multipart.MultipartFile;
import ru.pjandro.wordpdf.ConvertOptions; import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.WordPdfSettings;
import java.io.IOException; import java.io.IOException;
import java.nio.charset.StandardCharsets; import java.nio.charset.StandardCharsets;
@@ -25,10 +24,11 @@ import java.util.Locale;
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование * <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) — * {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
* зона {@link ConversionService}. Ошибки в JSON-ответ переводит * зона {@link ConversionService}. Ошибки в JSON-ответ переводит
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера * {@link ApiExceptionHandler}. Лимиты входа: свойства
* (свойства {@code wordpdf.max-mb}/{@code wordpdf.max-pages}, env * {@code wordpdf.max-mb}/{@code wordpdf.max-pages} (env
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}); параметрами запроса * {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}) — дефолт эндпоинта;
* они не переопределяются.</p> * параметры запроса {@code maxMb}/{@code maxPages} переопределяют его в обе
* стороны (значения ≤ 0 → 400).</p>
*/ */
@RestController @RestController
final class ConvertController { final class ConvertController {
@@ -38,14 +38,15 @@ final class ConvertController {
private final int maxPages; private final int maxPages;
/** /**
* Дефолт плейсхолдеров — константы ядра через SpEL: буквальное значение * Дефолт плейсхолдеров — буквенные литералы 5/100 (дефолтов лимитов в
* в свойствах не дублируется. Невалидное значение (<= 0) роняет * ядре нет); свойства/env переопределяют их, параметры запроса — см.
* {@link #convert}. Невалидное значение свойства (<= 0) роняет
* приложение на старте (fail-fast): «сервис поднят, но весь вход * приложение на старте (fail-fast): «сервис поднят, но весь вход
* отсекается» — худший исход, чем не поднявшийся сервис. * отсекается» — худший исход, чем не поднявшийся сервис.
*/ */
ConvertController(ConversionService conversionService, ConvertController(ConversionService conversionService,
@Value("${wordpdf.max-mb:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_INPUT_MB}}") long maxMb, @Value("${wordpdf.max-mb:5}") long maxMb,
@Value("${wordpdf.max-pages:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_PAGES}}") int maxPages) { @Value("${wordpdf.max-pages:100}") int maxPages) {
if (maxMb <= 0) { if (maxMb <= 0) {
throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb); throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
} }
@@ -60,10 +61,11 @@ final class ConvertController {
@Operation(summary = "Конвертировать .docx/.doc в PDF", @Operation(summary = "Конвертировать .docx/.doc в PDF",
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx " description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию " + "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
+ "настройки ядра (ошибка не выбрасывается); диаграммы/SmartArt " + "ошибка не выбрасывается; диаграммы/SmartArt "
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. " + "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера " + "Лимиты входа (размер/страницы): свойства wordpdf.max-mb/wordpdf.max-pages — "
+ "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются") + "дефолт; параметры запроса maxMb/maxPages переопределяют его в обе стороны "
+ "(значения ≤ 0 → 400)")
@SecurityRequirement(name = OpenApiConfig.SCHEME) @SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping( @PostMapping(
path = "/api/v1/convert", path = "/api/v1/convert",
@@ -73,7 +75,9 @@ final class ConvertController {
@RequestParam("file") MultipartFile file, @RequestParam("file") MultipartFile file,
@RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts, @RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts,
@RequestParam(name = "errorOnSmartArt", required = false) Boolean errorOnSmartArt, @RequestParam(name = "errorOnSmartArt", required = false) Boolean errorOnSmartArt,
@RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle) { @RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle,
@RequestParam(name = "maxMb", required = false) Long maxMbParam,
@RequestParam(name = "maxPages", required = false) Integer maxPagesParam) {
if (file == null || file.isEmpty()) { if (file == null || file.isEmpty()) {
throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)"); throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)");
} }
@@ -84,13 +88,24 @@ final class ConvertController {
// .doc (Word 97–2003) переносится в .docx мостом internal.doc // .doc (Word 97–2003) переносится в .docx мостом internal.doc
throw new BadRequestException("Поддерживаются только .docx и .doc: " + name); throw new BadRequestException("Поддерживаются только .docx и .doc: " + name);
} }
// Лимиты входа: свойства сервера — дефолт, параметры запроса
// переопределяют в обе стороны (верхнего потолка нет — осознанное
// решение; остаточная защита от загрузки — multipart-лимит сервера).
if (maxMbParam != null && maxMbParam <= 0) {
throw new BadRequestException("maxMb должен быть больше 0: " + maxMbParam);
}
if (maxPagesParam != null && maxPagesParam <= 0) {
throw new BadRequestException("maxPages должен быть больше 0: " + maxPagesParam);
}
long effMaxMb = maxMbParam != null ? maxMbParam : maxMb;
int effMaxPages = maxPagesParam != null ? maxPagesParam : maxPages;
// Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ) // Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ)
// больше логического лимита входа (wordpdf.max-mb), и без этого гварда // больше логического лимита входа, и без этого гварда заведомо
// заведомо oversized-upload сначала материализовался бы в куче. // oversized-upload сначала материализовался бы в куче.
// Текст — тот же формат, что WordPdfValidator.checkInput. // Текст — тот же формат, что WordPdfValidator.checkInput.
long maxBytes = maxMb * 1024 * 1024; long maxBytes = effMaxMb * 1024 * 1024;
if (file.getSize() > maxBytes) { if (file.getSize() > maxBytes) {
throw new BadRequestException("Файл больше " + maxMb + " МБ: " throw new BadRequestException("Файл больше " + effMaxMb + " МБ: "
+ file.getSize() + " байт > " + maxBytes + " байт"); + file.getSize() + " байт > " + maxBytes + " байт");
} }
byte[] docxBytes; byte[] docxBytes;
@@ -100,10 +115,10 @@ final class ConvertController {
throw new BadRequestException("Не удалось прочитать загруженный файл", e); throw new BadRequestException("Не удалось прочитать загруженный файл", e);
} }
ConvertOptions options = new ConvertOptions( ConvertOptions options = new ConvertOptions(
errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS, Boolean.TRUE.equals(errorOnCharts),
errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART, Boolean.TRUE.equals(errorOnSmartArt),
errorOnOle != null ? errorOnOle : WordPdfSettings.ERROR_ON_OLE, Boolean.TRUE.equals(errorOnOle),
maxMb, maxPages); effMaxMb, effMaxPages);
byte[] pdf = conversionService.convert(docxBytes, name, options); byte[] pdf = conversionService.convert(docxBytes, name, options);
ContentDisposition disposition = ContentDisposition.attachment() ContentDisposition disposition = ContentDisposition.attachment()
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8) .filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
@@ -1,28 +1,25 @@
package ru.pjandro.wordpdf.app; package ru.pjandro.wordpdf.app;
import ru.pjandro.wordpdf.DrawingFoundException; import ru.pjandro.wordpdf.ChartsFoundException;
import ru.pjandro.wordpdf.OleFoundException;
import ru.pjandro.wordpdf.SmartArtFoundException;
/** /**
* Документ содержит диаграммы/SmartArt/OLE-объекты при включённом error-флаге * Документ содержит диаграммы/SmartArt/OLE-объекты при включённом error-флаге
* ({@link DrawingFoundException} ядра). * ({@link ChartsFoundException}, {@link SmartArtFoundException} или
* {@link OleFoundException} ядра).
* *
* <p>Маппится в HTTP 422 ({@link ApiExceptionHandler}); клиенту осмысленно * <p>Маппится в HTTP 422 ({@link ApiExceptionHandler}); клиенту осмысленно
* повторить без error-флага. Текст сообщения — * повторить без error-флага.</p>
* пользовательский контракт: фронт показывает его дословно.</p>
*/ */
class DrawingRejectedException extends RuntimeException { class DrawingRejectedException extends RuntimeException {
DrawingRejectedException(DrawingFoundException.Kind kind) { /** Тексты — пользовательский контракт: фронт показывает их дословно. */
super(message(kind)); static final String CHARTS = "Конвертация отменена: в документе найдены диаграммы";
} static final String SMART_ART = "Конвертация отменена: в документе найден SmartArt";
static final String OLE = "Конвертация отменена: в документе найдены OLE-объекты";
// switch вынесен из super(): парсер PMD 7.17 (движок maven-pmd-plugin) DrawingRejectedException(String message) {
// падает на switch-выражении в аргументе super (pmd/pmd#6234). super(message);
private static String message(DrawingFoundException.Kind kind) {
return switch (kind) {
case CHARTS -> "Конвертация отменена: в документе найдены диаграммы";
case SMARTART -> "Конвертация отменена: в документе найден SmartArt";
case OLE -> "Конвертация отменена: в документе найдены OLE-объекты";
};
} }
} }
@@ -1,12 +1,12 @@
spring.application.name=wordpdf-app spring.application.name=wordpdf-app
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в # Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный # nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Логический лимит
# лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ), по умолчанию # входа — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ) /
# WordPdfSettings.MAX_INPUT_MB = 5; здесь только потолок загрузки. # wordpdf.max-pages (env WORDPDF_MAX_PAGES): дефолты 5/100 — литералы @Value
# Лимиты входа: env WORDPDF_MAX_MB (МБ) / WORDPDF_MAX_PAGES (страницы), # в ConvertController (дефолтов лимитов в ядре нет); параметрами запроса
# дефолты — константы ядра (5 / 100), задаются ConvertController. # maxMb/maxPages дефолт переопределяется в обе стороны. Значение свойства
# Значение <= 0 — падение на старте. Сами ключи здесь не объявлены: # <= 0 — падение на старте. Сами ключи здесь не объявлены: пустое значение
# пустое значение затенит SpEL-дефолт @Value. # затенит дефолт @Value.
# file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap # file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap
# держит только копию getBytes() одной сериализованной конвертации (порог 100MB # держит только копию getBytes() одной сериализованной конвертации (порог 100MB
# буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл # буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл
@@ -92,7 +92,7 @@ class ConversionServiceTest {
byte[] sample = bytes("/samples/ru-plain.docx"); byte[] sample = bytes("/samples/ru-plain.docx");
ConversionRejectedException e = assertThrows(ConversionRejectedException.class, ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
() -> svc.convert(sample, "queue.docx", ConvertOptions.defaults())); () -> svc.convert(sample, "queue.docx", new ConvertOptions(false, false, false, 5, 100)));
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage()); assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
} finally { } finally {
block.countDown(); block.countDown();
@@ -115,7 +115,7 @@ class ConversionServiceTest {
try { try {
Thread.currentThread().interrupt(); Thread.currentThread().interrupt();
ConversionRejectedException e = assertThrows(ConversionRejectedException.class, ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
() -> svc.convert(sample, "ru-plain.docx", ConvertOptions.defaults())); () -> svc.convert(sample, "ru-plain.docx", new ConvertOptions(false, false, false, 5, 100)));
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage()); assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
assertTrue(Thread.currentThread().isInterrupted(), assertTrue(Thread.currentThread().isInterrupted(),
"флаг прерывания обязан быть восстановлен"); "флаг прерывания обязан быть восстановлен");
@@ -125,7 +125,7 @@ class ConversionServiceTest {
// барьер: отменённая задача ещё домучивает рендер на воркере, а // барьер: отменённая задача ещё домучивает рендер на воркере, а
// глобальный реестр шрифтов ядра не потокобезопасен — ждём освобождения // глобальный реестр шрифтов ядра не потокобезопасен — ждём освобождения
// воркера через успешную сериализованную конвертацию // воркера через успешную сериализованную конвертацию
byte[] pdf = svc.convert(sample, "barrier.docx", ConvertOptions.defaults()); byte[] pdf = svc.convert(sample, "barrier.docx", new ConvertOptions(false, false, false, 5, 100));
assertEquals("%PDF", new String(pdf, 0, 4, StandardCharsets.US_ASCII)); assertEquals("%PDF", new String(pdf, 0, 4, StandardCharsets.US_ASCII));
svc.shutdown(); svc.shutdown();
} }
@@ -30,7 +30,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/ */
@SpringBootTest @SpringBootTest
@AutoConfigureMockMvc @AutoConfigureMockMvc
@TestPropertySource(properties = "wordpdf.convert-timeout=1ms") @TestPropertySource(properties = {"wordpdf.convert-timeout=1ms",
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
// (mise подмешивает корневой .env в окружение тасок)
"wordpdf.api-key="})
class ConversionTimeoutTest { class ConversionTimeoutTest {
private static final MediaType DOCX = private static final MediaType DOCX =
@@ -44,7 +44,8 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
* ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны * ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны
* {@code WordPdfConverterTest} (norm/pdfText). * {@code WordPdfConverterTest} (norm/pdfText).
*/ */
@SpringBootTest @SpringBootTest(properties = "wordpdf.api-key=") // пустой = фильтр выключен; пин от
// ambient WORDPDF_API_KEY (mise подмешивает корневой .env в окружение тасок)
@AutoConfigureMockMvc @AutoConfigureMockMvc
class ConvertControllerTest { class ConvertControllerTest {
@@ -188,7 +189,8 @@ class ConvertControllerTest {
/** /**
* errorOnSmartArt=true — HTTP 422 с текстом про SmartArt (диаграммы * errorOnSmartArt=true — HTTP 422 с текстом про SmartArt (диаграммы
* конвертируются, их error-флаг выключен, поэтому бросается целевой Kind). * конвертируются, их error-флаг выключен, поэтому бросается
* {@code SmartArtFoundException}).
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt, * Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
* фикстура samples/charts-smartart.docx. * фикстура samples/charts-smartart.docx.
*/ */
@@ -311,8 +313,8 @@ class ConvertControllerTest {
@Test @Test
void oversizedOverCoreLimit_rejected() throws Exception { void oversizedOverCoreLimit_rejected() throws Exception {
// 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ) // 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ)
// и отсекается валидацией ядра до очереди (дефолт ядра цел — // и отсекается валидацией ядра до очереди (дефолт эндпоинта 5 МБ —
// лимит задаёт только конфигурация сервера) // параметры запроса здесь не участвуют)
byte[] big = new byte[5 * 1024 * 1024 + 1]; byte[] big = new byte[5 * 1024 * 1024 + 1];
mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big))) mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big)))
.andExpect(status().isBadRequest()) .andExpect(status().isBadRequest())
@@ -321,20 +323,60 @@ class ConvertControllerTest {
} }
/** /**
* Регрессия env-only: лимиты входа параметрами запроса не задаются. * Параметр запроса maxMb ужимает серверный дефолт: файл в пределах
* maxMb/maxPages в multipart-форме игнорируются — маленький * серверных 5 МБ отвергается по параметру 1 МБ (текст гварда — с
* документ проходит на серверных лимитах (дефолты ядра). * числом из запроса).
*/ */
@Test @Test
void requestLimitParams_areIgnored() throws Exception { void requestLimit_maxMbTightens_rejected() throws Exception {
byte[] twoMb = new byte[2 * 1024 * 1024];
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("two.docx", twoMb))
.param("maxMb", "1"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("больше 1 МБ")));
}
/** Параметр maxMb поднимает серверный дефолт: обычный документ проходит. */
@Test
void requestLimit_maxMbRaises_smallOk() throws Exception {
mockMvc.perform(multipart("/api/v1/convert") mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx"))) .file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxMb", "1000") .param("maxMb", "1000")
.param("maxPages", "1")) .param("maxPages", "1000"))
.andExpect(status().isOk()) .andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF)); .andExpect(content().contentType(MediaType.APPLICATION_PDF));
} }
/** Параметр maxPages ужимает дефолт: фикстура на 110 границ отвергается с числом из запроса. */
@Test
void requestLimit_maxPagesTightens_rejected() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("stale-cache.docx", bytes("/samples/stale-cache.docx")))
.param("maxPages", "1"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("длиннее 1 страниц")));
}
/** Нулевые лимиты в запросе — 400 до любой работы с файлом. */
@Test
void requestLimit_nonPositive_rejected() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxMb", "0"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("maxMb должен быть больше 0")));
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxPages", "0"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("maxPages должен быть больше 0")));
}
/** /**
* Невалидные лимиты в конфигурации — падение на старте (fail-fast): * Невалидные лимиты в конфигурации — падение на старте (fail-fast):
* «сервис поднят, но весь вход отсекается» хуже не поднявшегося. * «сервис поднят, но весь вход отсекается» хуже не поднявшегося.
@@ -417,8 +459,14 @@ class ConvertControllerTest {
mockMvc.perform(multipart("/api/v1/convert") mockMvc.perform(multipart("/api/v1/convert")
.file(docx("bad.docx", docxPackageWithGarbage()))) .file(docx("bad.docx", docxPackageWithGarbage())))
.andExpect(status().isInternalServerError()) .andExpect(status().isInternalServerError())
.andExpect(jsonPath("$.error", // фиксированный текст: сообщение ядра (docx4j/FOP/JAXB) —
org.hamcrest.Matchers.containsString("Не удалось конвертировать"))); // только в лог, наружу не уходит
.andExpect(jsonPath("$.error").value("Не удалось конвертировать документ"))
.andExpect(result -> {
String body = result.getResponse().getContentAsString();
assertTrue(!body.contains("docx4j") && !body.contains("Exception"),
"500 протёк внутренними деталями: " + body);
});
} }
@Test @Test
@@ -474,7 +522,7 @@ class ConvertControllerTest {
ConvertController controller = ConvertController controller =
new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100); new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100);
BadRequestException e = assertThrows(BadRequestException.class, BadRequestException e = assertThrows(BadRequestException.class,
() -> controller.convert(broken, null, null, null)); () -> controller.convert(broken, null, null, null, null, null));
assertTrue(e.getMessage().contains("Не удалось прочитать"), e.getMessage()); assertTrue(e.getMessage().contains("Не удалось прочитать"), e.getMessage());
} }
} }
@@ -35,7 +35,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/ */
@SpringBootTest @SpringBootTest
@AutoConfigureMockMvc @AutoConfigureMockMvc
@TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1"}) @TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1",
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
// (mise подмешивает корневой .env в окружение тасок)
"wordpdf.api-key="})
class ConvertLimitsTest { class ConvertLimitsTest {
private static final MediaType DOCX = private static final MediaType DOCX =
@@ -90,4 +93,26 @@ class ConvertLimitsTest {
.andExpect(jsonPath("$.error", .andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("страниц"))); org.hamcrest.Matchers.containsString("страниц")));
} }
/**
* Параметры запроса ПОДНИМАЮТ configured-дефолты (свойство — дефолт, не
* потолок): maxMb=5 — и файл за 1 MiB проходит байтовый гейт (отказ уже
* по контейнеру, не по размеру); maxPages=2 — и текст отказа несёт
* двойку, а не configured единицу.
*/
@Test
void restParamAboveConfigured_applies() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("big.docx", oversizedZip()))
.param("maxMb", "5"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("не является .docx")));
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("too-many-pages.docx", bytes("/samples/too-many-pages.docx")))
.param("maxPages", "2"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("длиннее 2 страниц")));
}
} }
+27
View File
@@ -29,6 +29,24 @@
<dependency> <dependency>
<groupId>org.docx4j</groupId> <groupId>org.docx4j</groupId>
<artifactId>docx4j-export-fo</artifactId> <artifactId>docx4j-export-fo</artifactId>
<!-- JEuclid (MathML-рендер FOP) исключён: формулы OMML больше не
доходят до FO — DrawingPreRenderer заменяет каждую math-узел
собственным растером (MathModel/MathRenderer) или текстом, а
MathFallbackNormalizer (правило 6) срезает unsupported до
загрузки. Jeuclid тянул AWT-менеджер шрифтов (fontconfig —
падение на без-fontconfig хостах) и системные шрифты в вывод;
инвариант «шрифты только бандла» пинит
FontsBundledOnlyInvariantTest. -->
<exclusions>
<exclusion>
<groupId>de.rototor.jeuclid</groupId>
<artifactId>jeuclid-fop</artifactId>
</exclusion>
<exclusion>
<groupId>de.rototor.jeuclid</groupId>
<artifactId>jeuclid-core</artifactId>
</exclusion>
</exclusions>
</dependency> </dependency>
<!-- Простой логгер в консоль (slf4j). Обязателен: без него docx4j <!-- Простой логгер в консоль (slf4j). Обязателен: без него docx4j
пишет предупреждение прямо в выходной PDF. --> пишет предупреждение прямо в выходной PDF. -->
@@ -125,6 +143,15 @@
</execution> </execution>
</executions> </executions>
</plugin> </plugin>
<!-- Javadoc публичного API модуля (цель javadoc:javadoc, задача mise
docs-javadoc; результат target/site/apidocs попадает на сайт
документации). Без executions: в лайфцикл не вмешивается.
wordpdf-app javadoc не генерирует — единственного public-класса
WordPdfApplication недостаточно для раздела документации. -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
</plugin>
</plugins> </plugins>
</build> </build>
</project> </project>
@@ -0,0 +1,16 @@
package ru.pjandro.wordpdf;
/**
* В документе найдены диаграммы, а их обработка запрещена включённым
* {@link ConvertOptions#errorOnCharts()}. Исключение отвергает документ целиком.
*
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts,
* фикстура samples/charts-smartart.docx.</p>
*/
public final class ChartsFoundException extends ConversionException {
public ChartsFoundException() {
super("В документе найдены диаграммы, а их обработка запрещена (errorOnCharts)");
}
}
@@ -2,25 +2,18 @@ package ru.pjandro.wordpdf;
/** /**
* на один вызов: error-флаги рисунков и лимиты входа (размер/страницы). * на один вызов: error-флаги рисунков и лимиты входа (размер/страницы).
* Дефолты — константы {@link WordPdfSettings}; вызывающий (например, REST API) * Дефолтов в ядре нет — значения задаёт вызывающий (приложение: свойства
* может переопределить их на конкретный вызов. Диаграммы/SmartArt * сервера как дефолт REST-эндпоинта + параметры запроса). Диаграммы/SmartArt
* конвертируются всегда. * конвертируются всегда.
* *
* @param errorOnCharts бросать {@link DrawingFoundException} при находке диаграмм * @param errorOnCharts бросать {@link ChartsFoundException} при находке диаграмм
* @param errorOnSmartArt бросать {@link DrawingFoundException} при находке SmartArt * @param errorOnSmartArt бросать {@link SmartArtFoundException} при находке SmartArt
* @param errorOnOle бросать {@link DrawingFoundException} при находке OLE-объектов * @param errorOnOle бросать {@link OleFoundException} при находке OLE-объектов
* (иначе — тихо удалить их из документа) * (иначе — тихо удалить их из документа)
* @param maxMb лимит размера входа в МБ (MiB) на этот вызов; * @param maxMb лимит размера входа в МБ (MiB) на этот вызов;
* дефолт — {@link WordPdfSettings#MAX_INPUT_MB} * должен быть больше 0
* @param maxPages лимит числа страниц на этот вызов; * @param maxPages лимит числа страниц на этот вызов; должен быть больше 0
* дефолт — {@link WordPdfSettings#MAX_PAGES}
*/ */
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnOle, public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnOle,
long maxMb, int maxPages) { long maxMb, int maxPages) {
/** Дефолты ядра из {@link WordPdfSettings}. */
public static ConvertOptions defaults() {
return new ConvertOptions(WordPdfSettings.ERROR_ON_CHARTS, WordPdfSettings.ERROR_ON_SMARTART,
WordPdfSettings.ERROR_ON_OLE, WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES);
}
} }
@@ -1,45 +0,0 @@
package ru.pjandro.wordpdf;
/**
* Документ содержит объект, находку которого вызывающий запретил:
* соответствующий error-флаг включён
* ({@link ConvertOptions#errorOnCharts()}, {@link ConvertOptions#errorOnSmartArt()},
* {@link ConvertOptions#errorOnOle()}).
* Диаграммы/SmartArt конвертируются всегда; OLE-объекты при выключенном
* {@code errorOnOle} теряют свои данные, но сохраняют картинку-плейсхолдер
* (в отличие от них).
* Исключение отвергает документ целиком.
*
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится
* только он; {@code kind()} даёт вызывающему тип объекта без разбора текста.
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts,
* фикстура samples/charts-smartart.docx; OLE —
* WordPdfConverterTest#drawingErrors_errorFlagRejectsOle,
* фикстура samples/ole-embedded.docx.</p>
*/
public class DrawingFoundException extends ConversionException {
/** Тип найденного объекта. */
public enum Kind { CHARTS, SMARTART, OLE }
private final Kind kind;
public DrawingFoundException(Kind kind) {
super(message(kind));
this.kind = kind;
}
// switch вынесен из super(): парсер PMD 7.17 (движок maven-pmd-plugin)
// падает на switch-выражении в аргументе super (pmd/pmd#6234).
private static String message(Kind kind) {
return switch (kind) {
case CHARTS -> "В документе найдены диаграммы, а их обработка запрещена (errorOnCharts)";
case SMARTART -> "В документе найден SmartArt, а его обработка запрещена (errorOnSmartArt)";
case OLE -> "В документе найдены OLE-объекты, а их обработка запрещена (errorOnOle)";
};
}
public Kind kind() {
return kind;
}
}
@@ -0,0 +1,22 @@
package ru.pjandro.wordpdf;
/**
* В документе найдены OLE-объекты, а их обработка запрещена включённым
* {@link ConvertOptions#errorOnOle()}. Исключение отвергает документ целиком.
*
* <p>При выключенном флаге OLE-объекты теряют свои данные, но сохраняют
* картинку-плейсхолдер (в отличие от диаграмм/SmartArt, конвертируемых
* всегда). Флаг действует только на {@code .docx}: в бинарном {@code .doc}
* вложения OLE — форматирование U+0001, мост деградирует их до картинки,
* поэтому находки OLE там не бывает.</p>
*
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsOle,
* фикстура samples/ole-embedded.docx; OleObjectNormalizerTest#errorOnOleThrowsOleFound.</p>
*/
public final class OleFoundException extends ConversionException {
public OleFoundException() {
super("В документе найдены OLE-объекты, а их обработка запрещена (errorOnOle)");
}
}
@@ -0,0 +1,16 @@
package ru.pjandro.wordpdf;
/**
* В документе найден SmartArt, а его обработка запрещена включённым
* {@link ConvertOptions#errorOnSmartArt()}. Исключение отвергает документ целиком.
*
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
* фикстура samples/charts-smartart.docx.</p>
*/
public final class SmartArtFoundException extends ConversionException {
public SmartArtFoundException() {
super("В документе найден SmartArt, а его обработка запрещена (errorOnSmartArt)");
}
}
@@ -2,7 +2,8 @@ package ru.pjandro.wordpdf;
import org.apache.fop.apps.FOUserAgent; import org.apache.fop.apps.FOUserAgent;
import org.apache.fop.apps.FopFactory; import org.apache.fop.apps.FopFactory;
import org.apache.fop.apps.FopFactoryBuilder; import org.apache.fop.util.ImageObjectCache;
import org.apache.fop.util.ImageObjectCacheImpl;
import org.docx4j.Docx4J; import org.docx4j.Docx4J;
import org.docx4j.XmlUtils; import org.docx4j.XmlUtils;
import org.docx4j.Docx4jProperties; import org.docx4j.Docx4jProperties;
@@ -30,6 +31,7 @@ import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream; import java.io.ByteArrayOutputStream;
import java.io.IOException; import java.io.IOException;
import javax.xml.transform.Templates; import javax.xml.transform.Templates;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.stream.StreamSource; import javax.xml.transform.stream.StreamSource;
import javax.imageio.ImageIO; import javax.imageio.ImageIO;
import java.io.InputStream; import java.io.InputStream;
@@ -54,9 +56,13 @@ import java.util.zip.ZipOutputStream;
* подменяются метрически совместимыми open-source аналогами * подменяются метрически совместимыми open-source аналогами
* (см. {@link BundledFontMapper}). * (см. {@link BundledFontMapper}).
* *
* Класс stateless, все методы статические. Класс НЕ потокобезопасен: * Класс stateless, все методы статические. Публичные {@code convert()} можно
* конвертации из нескольких потоков необходимо сериализовать (глобальный * вызывать из нескольких потоков: сериализация обеспечена внутри ядра —
* реестр {@code PhysicalFonts}, кэши шрифтов/покрытия). * конвертации выполняются по одной под монитором класса (глобальный реестр
* {@code PhysicalFonts}, общая FopFactory с имиджевыми кешами, сброс кеши в
* finally). {@link #warmup()} синхронизирован тем же монитором.
* {@link WordPdfValidator} stateless и выполняется до монитора — валидация
* параллельна и не блокируется.
*/ */
public final class WordPdfConverter { public final class WordPdfConverter {
@@ -83,38 +89,66 @@ public final class WordPdfConverter {
private WordPdfConverter() { private WordPdfConverter() {
} }
private static volatile FopFactory sharedFopFactory;
/** /**
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат * FopFactory, общая на JVM: разбор шрифтов форка (GPOS-таблицы, ~140k
* определяется по сигнатуре байтов) в PDF. Работа с файлами — забота * объектов) выполняется один раз, а не на каждую конвертацию. Фабрика
* вызывающего (файловое API было здесь раньше; ядро пути не принимает). * хранит имиджевые кеши ({@code ImageManager#getCache()} и
* * {@link ImageObjectCacheImpl}) c ключами {@code file:/tmp/<uuid>…} —
* <p>.doc предварительно переносится в .docx мостом * уникальными на каждую конвертацию (docx4j выкладывает медиа во временные
* {@link ru.pjandro.wordpdf.internal.doc.DocToDocx} (текст + прямое * файлы), поэтому кеш никогда не попадает и растёт на декодированный растр
* форматирование); число страниц для .doc проверяется мостом по чистому * каждого изображения (замер 2026-11: ~1,5 ГБ живых byte[] после 30
* бинарному документу (кэш PageCount + явные разрывы), сгенерированный * конвертаций с картинками). Поэтому каждая конвертация обязана вызвать
* .docx валидацией не проверяется. Для .docx вход проверяется * {@link #resetSharedImageCaches()} в finally. Вызывается только под локом
* {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера: * конвертации (см. {@code convert}), сброс mid-render невозможен. Методы
* {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_MB} (МБ) / zip-подпись / * приватны: вызов вне лока конвертера вскрыл бы DCL/сброс на параллельный
* число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет; * рендер. Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
* страницы считаются ровно раз по сырому входу, повторного скана по
* нормализованным байтам нет (см. javadoc перегрузки с {@link ConvertOptions}).
*
* @param docxBytes байты .docx или бинарного .doc
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @return байты готового PDF
* @throws ValidationException некорректный вход: {@code null}, размер больше
* {@link WordPdfSettings#MAX_INPUT_MB} (МБ), не .docx/.doc, зашифрованный .doc,
* документ длиннее {@link WordPdfSettings#MAX_PAGES} страниц
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/ */
public static byte[] convert(byte[] docxBytes, String title) throws ConversionException { private static FopFactory sharedFopFactory(final FOSettings foSettings) {
return convert(docxBytes, title, ConvertOptions.defaults()); FopFactory factory = sharedFopFactory;
if (factory == null) {
synchronized (WordPdfConverter.class) {
if (sharedFopFactory == null) {
try {
sharedFopFactory = FORendererApacheFOP.getFopFactoryBuilder(foSettings).build();
} catch (org.apache.fop.apps.FOPException e) {
throw new ConversionException("Не удалось собрать FOP-фабрику", e);
}
}
factory = sharedFopFactory;
}
}
return factory;
}
/**
* Сброс имиджевых кешей общей фабрики после конвертации. Без него форк
* удерживает растр каждого изображения документа до конца жизни JVM:
* записи лежат в soft-ссылках, которые сборщик не трогает, пока свободная
* куча велика (куча стенда фиксирована 2 ГБ). Сбросы публичные:
* {@code ImageCache.clearCache()} и {@code ImageObjectCacheImpl.clearCache()}.
* Вызывается исключительно из finally конвертации под локом (см.
* {@code convert}) — параллельный рендер под сброс не попадает.
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
*/
private static void resetSharedImageCaches() {
FopFactory factory = sharedFopFactory;
if (factory == null) {
return;
}
factory.getImageManager().getCache().clearCache();
ImageObjectCache imageObjects = factory.getImageObjectCache();
if (imageObjects instanceof ImageObjectCacheImpl impl) {
impl.clearCache();
}
} }
/** /**
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат * Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
* определяется по сигнатуре байтов, см. перегрузку выше) в PDF с * определяется по сигнатуре байтов) в PDF с настройками на вызов:
* настройками на вызов: error-флаги диаграмм/SmartArt и лимиты входа. * error-флаги диаграмм/SmartArt и лимиты входа. Работа с файлами — забота
* вызывающего (файловое API было здесь раньше; ядро пути не принимает).
* *
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} * <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)}
* до рендера — одна проверка на оба формата: {@code null} / размер больше * до рендера — одна проверка на оба формата: {@code null} / размер больше
@@ -123,15 +157,15 @@ public final class WordPdfConverter {
* считаются ровно раз по сырому входу, до аллокаций docx4j: для .docx — * считаются ровно раз по сырому входу, до аллокаций docx4j: для .docx —
* lightweight-скан по zip, для .doc — по чистому бинарному документу до * lightweight-скан по zip, для .doc — по чистому бинарному документу до
* конвертации. Повторного скана по нормализованным байтам нет: правила * конвертации. Повторного скана по нормализованным байтам нет: правила
* 1–10 {@code DocxRewritePipeline} число учитываемых разрывов не * 1–11 {@code DocxRewritePipeline} число учитываемых разрывов не
* увеличивают (правило 9 способно только убрать разрыв внутри скрытого * увеличивают (правило 10 способно только убрать разрыв внутри скрытого
* рана — счёт по сырому входу остаётся верхней оценкой лимита), а скан * рана — счёт по сырому входу остаётся верхней оценкой лимита), а скан
* внутри живой JAXB-модели удваивал бы пиковую память. * внутри живой JAXB-модели удваивал бы пиковую память.
* *
* @param docxBytes байты .docx или бинарного .doc * @param docxBytes байты .docx или бинарного .doc
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @param options error-флаги и лимиты входа на этот вызов; {@code null} — * @param options error-флаги и лимиты входа на этот вызов; обязательны,
* дефолты (константы {@link WordPdfSettings}) * {@code null} → {@link ValidationException} (дефолтов в ядре нет)
* @return байты готового PDF * @return байты готового PDF
* @throws ValidationException некорректный вход: {@code null}, размер больше * @throws ValidationException некорректный вход: {@code null}, размер больше
* {@code options.maxMb()} (МБ), не .docx/.doc, зашифрованный .doc, * {@code options.maxMb()} (МБ), не .docx/.doc, зашифрованный .doc,
@@ -139,7 +173,11 @@ public final class WordPdfConverter {
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/ */
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException { public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException {
ConvertOptions opts = options == null ? ConvertOptions.defaults() : options; if (options == null) {
throw new ValidationException("Не переданы параметры конвертации (ConvertOptions): "
+ "лимиты входа задаёт вызывающий");
}
ConvertOptions opts = options;
// Полная проверка входа — одна на оба формата: размер до // Полная проверка входа — одна на оба формата: размер до
// классификации (враждебный вход без подписи обязан получить ошибку // классификации (враждебный вход без подписи обязан получить ошибку
// лимита), затем для .docx — zip/контейнер/страницы, для .doc — // лимита), затем для .docx — zip/контейнер/страницы, для .doc —
@@ -152,18 +190,32 @@ public final class WordPdfConverter {
// .doc сбрасываются в кадре на этом же месте — детерминированно, до // .doc сбрасываются в кадре на этом же месте — детерминированно, до
// рендера (точные liveness-карты HotSpot строит только для // рендера (точные liveness-карты HotSpot строит только для
// скомпилированных кадров; отдельное присваивание null не нужно). // скомпилированных кадров; отдельное присваивание null не нужно).
docxBytes = WordPdfValidator.isBinaryDoc(docxBytes) ? DocToDocx.convert(docxBytes) : docxBytes; // Единый лок ядра: реестр PhysicalFonts, общая FopFactory (per-render
ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length)); // disableFontCache, имиджевые кеши) и её сброс в finally мутируются под
try { // рендером — параллельная конвертация обязана ждать, иначе чистит кеши
convertToStream(docxBytes, title, opts, bos); // посреди чужого рендера. Монитор класса тот же, что у warmup()
} catch (ConversionException e) { // (реентельно) и DCL в sharedFopFactory. Регрессия —
// ValidationException (отказ валидации входа) — подтип, уходит // WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
// вызывающему без обёртки synchronized (WordPdfConverter.class) {
throw e; docxBytes = WordPdfValidator.isBinaryDoc(docxBytes)
} catch (Exception e) { ? DocToDocx.convert(docxBytes, opts.maxMb()) : docxBytes;
throw new ConversionException("Не удалось конвертировать документ", e); ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length));
try {
convertToStream(docxBytes, title, opts, bos);
} catch (ConversionException e) {
// ValidationException (отказ валидации входа) — подтип, уходит
// вызывающему без обёртки
throw e;
} catch (Exception e) {
throw new ConversionException("Не удалось конвертировать документ", e);
} catch (StackOverflowError e) {
// Глубокая вложенность XML: JAXB-разбор рекурсивен и может
// разогнать стек раньше капы MathModel — детерминированный
// отказ вместо Error.
throw new ConversionException("Не удалось конвертировать документ", e);
}
return bos.toByteArray();
} }
return bos.toByteArray();
} }
/** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */ /** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */
@@ -171,14 +223,42 @@ public final class WordPdfConverter {
private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName()); private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName());
// Пороги защиты входа (считает WordPdfValidator.max* от лимитов входа
// ConvertOptions). Значения — строго литералы compile-time констант: javac
// инлайнит их в WordPdfValidator, и обращение из валидатора НЕ
// инициализирует этот класс (его static-блок выставляет sysprops docx4j —
// инвариант «WordPdfValidator не зависит от docx4j» сохраняется).
/** Бюджет суммарной распаковки: MiB на каждый МБ лимита размера входа. */
static final int DECOMPRESS_MB_PER_MAX_MB = 10;
/** Бюджет суммарной распаковки: KiB на каждую страницу лимита. */
static final int DECOMPRESS_KIB_PER_PAGE = 64;
/** Бюджет XML-частей: MiB на каждый МБ лимита (JAXB-разбор дороже байта). */
static final int DECOMPRESS_XML_MB_PER_MAX_MB = 4;
/** Бюджет XML-частей: KiB на каждую страницу лимита. */
static final int DECOMPRESS_XML_KIB_PER_PAGE = 32;
/** Пол бюджета суммарной распаковки (MiB) — чтобы мелкие лимиты не ломали легитимные документы. */
static final long MIN_DECOMPRESSED_MB = 16;
/** Пол бюджета XML-частей (MiB). */
static final long MIN_DECOMPRESSED_XML_MB = 4;
/** Порог пиксельной площади одного растра: пикселей на каждый МБ лимита размера. */
static final long IMAGE_PIXELS_PER_MAX_MB = 5_000_000;
/** Порог числа zip-записей: записей на каждый МБ лимита размера. */
static final int ZIP_ENTRIES_PER_MAX_MB = 512;
/** Порог числа zip-записей: записей на каждую страницу лимита. */
static final int ZIP_ENTRIES_PER_PAGE = 32;
/** Пол порога числа zip-записей. */
static final int MIN_ZIP_ENTRIES = 2048;
/** /**
* Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с * Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет * (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
* пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не * пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не
* задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм. * задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм.
* Идемпотентен, никогда не бросает (провал — только warn); вызывать нужно * Идемпотентен, никогда не бросает (провал — только warn); метод
* на том же потоке, на котором сериализованы конвертации (ядро не * синхронизирован монитором класса — тем же, что сериализует конвертации
* потокобезопасно, см. {@code PhysicalFonts}). Артефакты (PDF, растр) * в {@code convert()}, так что прогрев гарантированно не пересекается с
* рендером; приложение дополнительно держит warmup головой очереди.
* Артефакты (PDF, растр)
* отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева * отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева
* решает вызывающее приложение. * решает вызывающее приложение.
*/ */
@@ -187,7 +267,7 @@ public final class WordPdfConverter {
return; return;
} }
try { try {
convert(warmupDocx(), "warmup"); convert(warmupDocx(), "warmup", new ConvertOptions(false, false, false, 1, 1));
warmRaster(); warmRaster();
warmedUp = true; warmedUp = true;
} catch (Throwable t) { } catch (Throwable t) {
@@ -326,13 +406,15 @@ public final class WordPdfConverter {
LayoutPostRenderer.register(foSettings); LayoutPostRenderer.register(foSettings);
// 4.5 Вендорный xslt/docx2fo.xslt = копия из docx4j-export-fo + // 4.5 Вендорный xslt/docx2fo.xslt = копия из docx4j-export-fo +
// AUDIT-FIX-патч (w:rPr position) — стилист jar'а не // AUDIT-FIX-патчи (w:rPr/w:position→baseline-shift;
// AUDIT-FIX-2: moveFrom/moveTo/bdo/dir) — стилист jar'а не
// используется. // используется.
foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES); foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES);
// 5. Метаданные PDF: заголовок — из параметра title // 5. Метаданные PDF: заголовок — из параметра title. Фабрика —
FopFactoryBuilder builder = FORendererApacheFOP.getFopFactoryBuilder(foSettings); // общая на JVM (см. sharedFopFactory); после конвертации её
FopFactory fopFactory = builder.build(); // имиджевые кеши обязаны быть сброшены (шаг 7).
FopFactory fopFactory = sharedFopFactory(foSettings);
FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory); FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory);
if (title != null && !title.isEmpty()) { if (title != null && !title.isEmpty()) {
foUserAgent.setTitle(title); foUserAgent.setTitle(title);
@@ -341,18 +423,26 @@ public final class WordPdfConverter {
// 6. Проход XSLT (медленнее, но полнее), вывод в поток // 6. Проход XSLT (медленнее, но полнее), вывод в поток
Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL); Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
} finally { } finally {
// 7. Уборка временных файлов встроенных в docx шрифтов // 7. Уборка временных файлов встроенных в docx шрифтов, сброс
// имиджевых кешей общей FopFactory (без него форк копит растр
// каждого изображения: ~1,5 ГБ на 30 конвертаций, 2026-11) и
// возврат реестра шрифтов в бандл-состояние: load() регистрирует
// в глобальном PhysicalFonts встроенные шрифты документа, и без
// restrictToBundled последний документ продолжал бы влиять на
// выбор шрифта до следующей конвертации.
if (pkg.getMainDocumentPart() != null if (pkg.getMainDocumentPart() != null
&& pkg.getMainDocumentPart().getFontTablePart() != null) { && pkg.getMainDocumentPart().getFontTablePart() != null) {
pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles(); pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
} }
// Примечание: в docx4j 11.x OpcPackage.close() отсутствует — resetSharedImageCaches();
BundledFonts.restrictToBundled();
// Примечание: в docx4j 17.x OpcPackage.close() отсутствует —
// пакет загружается в память и ничего не закрывает. // пакет загружается в память и ничего не закрывает.
} }
} }
/** /**
* Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–10 * Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–11
* одним zip-проходом {@code DocxRewritePipeline} + условная OLE-вычистка) * одним zip-проходом {@code DocxRewritePipeline} + условная OLE-вычистка)
* и {@code WordprocessingMLPackage.load} полученного transitional-байта. * и {@code WordprocessingMLPackage.load} полученного transitional-байта.
* Нормализация переиспользует слот {@code bytes}: каждая замена массива * Нормализация переиспользует слот {@code bytes}: каждая замена массива
@@ -370,29 +460,33 @@ public final class WordPdfConverter {
/** /**
* Конвейер байтовой нормализации docx. Порядок фиксирован: сначала один * Конвейер байтовой нормализации docx. Порядок фиксирован: сначала один
* zip-проход переписывания XML-частей (внутри части порядок рерайтов * zip-проход переписывания XML-частей (внутри части порядок рерайтов
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→ * Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→
* NumberingSuffix→Hidden→Ruby значим: Strict первым — дальше transitional-байт; * NumberingSuffix→Hidden→Ruby значим: Strict первым — дальше transitional-байт;
* GlyphCoverage — по финальному тексту рана; Hidden — вырезает скрытые * MathFallback — деградирует OMML-формулы в текст m:t, когда JEuclid
* раны по финальному содержимому; Ruby — разворачивает руби-разметку, * недоступен, и следующий GlyphCoverage покрывает этот текст кириллицей
* которую схема docx4j не биндит), затем OleObjectNormalizer * бандла; GlyphCoverage — по финальному тексту рана; Hidden — вырезает
* (меняет части, а не XML ранов). * скрытые раны по финальному содержимому; Ruby — разворачивает
* руби-разметку, которую схема docx4j не биндит), затем
* OleObjectNormalizer (меняет части, а не XML ранов).
* Регрессии каждого рерайта — в javadoc соответствующего нормализатора. * Регрессии каждого рерайта — в javadoc соответствующего нормализатора.
*/ */
private static List<DocxNormalizer> normalizers(ConvertOptions options) { private static List<DocxNormalizer> normalizers(ConvertOptions options) {
return List.of( return List.of(
// один zip-проход: strict→transitional, on/off, Symbol-PUA, // один zip-проход: strict→transitional, on/off, Symbol-PUA,
// поля PAGE/NUMPAGES, невидимки, покрытие глифов, tblInd при // поля PAGE/NUMPAGES, невидимки, OMML-фолбэк в текст, покрытие
// jc≠left, suff=space, скрытый текст (vanish) — порядок // глифов, tblInd при jc≠left, suff=space, скрытый текст
// (vanish), снятие обёртки w:ruby — порядок
// рерайтов внутри части фиксирован (DocxRewritePipeline) // рерайтов внутри части фиксирован (DocxRewritePipeline)
DocxRewritePipeline.STEP, DocxRewritePipeline.STEP,
// OLE-объекты: при выключенном errorOnOle тихо удаляем // OLE-объекты: при выключенном errorOnOle тихо удаляем
// (часть/rels/w:object), при включённом — DrawingFoundException // (часть/rels/w:object), при включённом — OleFoundException
// (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML // (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML
bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle())); bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle()));
} }
/** /**
* Вендорный docx2fo.xslt (копия из docx4j-export-fo + AUDIT-FIX-патч). * Вендорный docx2fo.xslt (копия из docx4j-export-fo + AUDIT-FIX-патчи:
* w:rPr/w:position→baseline-shift; AUDIT-FIX-2: moveFrom/moveTo/bdo/dir).
* {@code AbstractXsltExporterDelegate.getTemplates} кастит значение * {@code AbstractXsltExporterDelegate.getTemplates} кастит значение
* {@code setCustomXsltTemplates} в {@code Templates} — компилируем заранее; * {@code setCustomXsltTemplates} в {@code Templates} — компилируем заранее;
* {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс. * {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс.
@@ -407,7 +501,7 @@ public final class WordPdfConverter {
throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден"); throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден");
} }
return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt)); return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt));
} catch (Exception e) { } catch (IOException | TransformerConfigurationException e) {
throw new ConversionException("Не удалось скомпилировать xslt/docx2fo.xslt", e); throw new ConversionException("Не удалось скомпилировать xslt/docx2fo.xslt", e);
} }
} }
@@ -1,42 +0,0 @@
package ru.pjandro.wordpdf;
/**
* Единая точка конфигурации ядра: все настройки-дефолты — константы здесь.
* Рантайм-конфигурации нет: изменение значения = правка этого файла и пересборка.
* Лимиты входа ({@link #MAX_INPUT_MB}, {@link #MAX_PAGES}) — дефолты:
* вызывающий может переопределить их на конкретный вызов через
* {@link ConvertOptions}.
*/
public final class WordPdfSettings {
/** Максимальный размер входного .docx в МБ (дефолт). МБ = MiB = 1024 × 1024 байт. */
public static final long MAX_INPUT_MB = 5;
/** Документ длиннее — ошибка (дефолт). */
public static final int MAX_PAGES = 100;
/** Потолок суммарного распакованного размера архива (МБ) — защита от zip-бомбы. */
public static final long MAX_DECOMPRESSED_MB = 200;
/** Потолок числа записей в архиве — защита от бомбы «много записей». */
public static final int MAX_ZIP_ENTRIES = 8192;
/**
* Ошибка при находке диаграмм ({@code c:chart}) — {@link DrawingFoundException}.
* Дефолт {@code false} — конвертация проходит.
*/
public static final boolean ERROR_ON_CHARTS = false;
/** Ошибка при находке SmartArt ({@code dgm:relIds}) — {@link DrawingFoundException}. */
public static final boolean ERROR_ON_SMARTART = false;
/**
* Ошибка при находке OLE-объектов (бинарные {@code .bin}-части) —
* {@link DrawingFoundException}. Дефолт {@code false} — объекты тихо
* удаляются из документа (см. OleObjectNormalizer), конвертация проходит.
*/
public static final boolean ERROR_ON_OLE = false;
private WordPdfSettings() {
}
}
@@ -30,19 +30,15 @@ import java.util.zip.ZipInputStream;
* но им можно пользоваться и напрямую — например, проверить байты * но им можно пользоваться и напрямую — например, проверить байты
* документа, полученного из сети или БД, до любой работы с ними. * документа, полученного из сети или БД, до любой работы с ними.
* *
* <p>Лимиты по умолчанию: * <p>Лимитов-констант в ядре нет: все пороги выводятся из лимитов входа
* <ul> * {@link ConvertOptions} ({@code maxMb} — размер в МБ, {@code maxPages} —
* <li>{@link WordPdfSettings#MAX_INPUT_MB} — максимальный размер входного .docx (МБ);</li> * число страниц): бюджеты распаковки {@link #maxDecompressedBytes(long, int)}
* <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц;</li> * и {@link #maxDecompressedXmlBytes(long, int)}, порог площади растра
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_MB} — потолок суммарного * {@link #maxImagePixels(long)}, потолок числа zip-записей
* распакованного размера архива (МБ);</li> * {@code maxZipEntries} (package-private) — коэффициенты в
* <li>{@link WordPdfSettings#MAX_ZIP_ENTRIES} — потолок числа записей * {@link WordPdfConverter}. Конвертер применяет {@link ConvertOptions} сам;
* в архиве.</li> * одноаргументных оверлодов-дефолтов нет — лимит задаётся параметром каждого
* </ul> * метода.
* Первые два переопределяются на вызов: перегрузками с явным лимитом или
* {@link ConvertOptions} (конвертер {@link WordPdfConverter} применяет их сам).
* Последние два — защитные константные пороги ({@link #validate(byte[], ConvertOptions)}),
* {@link ConvertOptions} их не переопределяет.
* *
* <p>Проверка контейнера: архив обязан декларировать документ * <p>Проверка контейнера: архив обязан декларировать документ
* wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx * wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx
@@ -70,6 +66,15 @@ public final class WordPdfValidator {
/** Элемент-контейнер body, внутри которого sectPr — межсекционный разрыв. */ /** Элемент-контейнер body, внутри которого sectPr — межсекционный разрыв. */
private static final String BODY_ELEMENT = "body"; private static final String BODY_ELEMENT = "body";
/** Кэш-элемент &lt;Pages&gt; в docProps/app.xml. */
private static final String PAGES_ELEMENT = "Pages";
/** Элемент sectPr — секция документа (межсекционный разрыв). */
private static final String SECTION_PROPERTIES = "sectPr";
/** Элемент w:br — разрыв строки/страницы. */
private static final String BREAK_ELEMENT = "br";
/** Кэш Word &lt;Pages&gt;. */ /** Кэш Word &lt;Pages&gt;. */
private static final String APP_PART = "docProps/app.xml"; private static final String APP_PART = "docProps/app.xml";
@@ -79,15 +84,6 @@ public final class WordPdfValidator {
private WordPdfValidator() { private WordPdfValidator() {
} }
/**
* Проверяет размер байтов входа (для документа, полученного из сети/БД).
*
* @throws ValidationException при {@code null} или превышении лимита (МБ)
*/
public static void checkInput(byte[] docxBytes) throws ValidationException {
checkInput(docxBytes, WordPdfSettings.MAX_INPUT_MB);
}
/** /**
* Проверяет размер байтов входа против явного лимита в МБ (переопределение * Проверяет размер байтов входа против явного лимита в МБ (переопределение
* на вызов, см. {@link ConvertOptions#maxMb()}). МБ = MiB = 1024 × 1024 байт. * на вызов, см. {@link ConvertOptions#maxMb()}). МБ = MiB = 1024 × 1024 байт.
@@ -98,7 +94,17 @@ public final class WordPdfValidator {
if (docxBytes == null) { if (docxBytes == null) {
throw new ValidationException("Не указаны байты входного файла"); throw new ValidationException("Не указаны байты входного файла");
} }
long maxBytes = maxMb * 1024 * 1024; long maxBytes;
try {
maxBytes = Math.multiplyExact(maxMb, 1048576L);
// .doc-путь (миновать бюджеты checkDocxContainer не даёт общая
// гейт-проверка): OfficeArt/DocToDocx считают порог растра только
// множителем maxMb×5_000_000 — при maxMb ≳ 1.8·10¹² переполнение
// бросало сырой ArithmeticException на границе convert.
Math.multiplyExact(maxMb, WordPdfConverter.IMAGE_PIXELS_PER_MAX_MB);
} catch (ArithmeticException e) {
throw new ValidationException("Лимит maxMb слишком велик: " + maxMb);
}
if (docxBytes.length > maxBytes) { if (docxBytes.length > maxBytes) {
throw new ValidationException("Файл больше " + maxMb + " МБ: " throw new ValidationException("Файл больше " + maxMb + " МБ: "
+ docxBytes.length + " байт > " + maxBytes + " байт"); + docxBytes.length + " байт > " + maxBytes + " байт");
@@ -111,7 +117,7 @@ public final class WordPdfValidator {
* такой вход не проверяется .docx-валидацией (zip-пути), его страницы * такой вход не проверяется .docx-валидацией (zip-пути), его страницы
* считает мост {@code internal.doc} по чистому бинарному документу. * считает мост {@code internal.doc} по чистому бинарному документу.
*/ */
public static boolean isBinaryDoc(byte[] bytes) { static boolean isBinaryDoc(byte[] bytes) {
byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0, byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1}; (byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
if (bytes == null || bytes.length < sig.length) { if (bytes == null || bytes.length < sig.length) {
@@ -154,19 +160,13 @@ public final class WordPdfValidator {
* .docx-манифест и распакованный размер (регрессия — * .docx-манифест и распакованный размер (регрессия —
* {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать * {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать
* {@code checkPageCount} напрямую допустимо только над доверенным входом. * {@code checkPageCount} напрямую допустимо только над доверенным входом.
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES} *
*/ * <p>Лимит страниц задаётся параметром (переопределение на вызов,
public static void checkPageCount(byte[] docxBytes) throws ValidationException { * см. {@link ConvertOptions#maxPages()}).
checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCount(byte[])}, с явным лимитом
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
* *
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages} * @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
*/ */
public static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException { static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
if (docxBytes == null) { if (docxBytes == null) {
throw new ValidationException("Не указаны байты входного .docx"); throw new ValidationException("Не указаны байты входного .docx");
} }
@@ -215,17 +215,7 @@ public final class WordPdfValidator {
* разрывы 0x0C − непрерывные межсекционные разрывы + абзацы с * разрывы 0x0C − непрерывные межсекционные разрывы + абзацы с
* pageBreakBefore)} — тот же контур, что lightweight-скан по zip для * pageBreakBefore)} — тот же контур, что lightweight-скан по zip для
* .docx. Разбор делает {@code internal.doc} ({@link DocToDocx#countPages(byte[])}). * .docx. Разбор делает {@code internal.doc} ({@link DocToDocx#countPages(byte[])}).
* * Лимит страниц задаётся параметром (см. {@link ConvertOptions#maxPages()}).
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
* или превышении {@link WordPdfSettings#MAX_PAGES}
*/
public static void checkPageCountDoc(byte[] docBytes) throws ValidationException {
checkPageCountDoc(docBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCountDoc(byte[])}, с явным лимитом
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
* *
* <p>Отказ разбора {@code .doc}-моста ({@code internal.doc}) — * <p>Отказ разбора {@code .doc}-моста ({@code internal.doc}) —
* {@link ConversionException} — оборачивается здесь в * {@link ConversionException} — оборачивается здесь в
@@ -237,7 +227,7 @@ public final class WordPdfValidator {
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании * @throws ValidationException при {@code null}, не-.doc-входе, шифровании
* или превышении {@code maxPages} * или превышении {@code maxPages}
*/ */
public static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException { static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
if (docBytes == null) { if (docBytes == null) {
throw new ValidationException("Не указаны байты входного .doc"); throw new ValidationException("Не указаны байты входного .doc");
} }
@@ -273,18 +263,25 @@ public final class WordPdfValidator {
* <p>Проверка контейнера: в {@code [Content_Types].xml} обязана быть * <p>Проверка контейнера: в {@code [Content_Types].xml} обязана быть
* декларация документа wordprocessingml (архив без неё — не .docx); * декларация документа wordprocessingml (архив без неё — не .docx);
* zip-бомба отсекается потоковым счётчиком распакованных байт * zip-бомба отсекается потоковым счётчиком распакованных байт
* ({@link WordPdfSettings#MAX_DECOMPRESSED_MB}) и числом записей * ({@link #maxDecompressedBytes(long, int)}, XML —
* ({@link WordPdfSettings#MAX_ZIP_ENTRIES}) — до разбора содержимого * {@link #maxDecompressedXmlBytes(long, int)}) и числом записей
* в {@link #checkPageCount(byte[], int)}. Оба лимита — * ({@code maxZipEntries}) — до разбора содержимого
* защитные пороги, {@link ConvertOptions} их не переопределяет. * в {@link #checkPageCount(byte[], int)}. Все пороги — производные от
* {@code options.maxMb()}/{@code options.maxPages()}, отдельных
* констант в ядре нет.
* Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected}, * Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected},
* {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected}, * {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected},
* {@code #validate_tooManyEntriesRejected}.</p> * {@code #validate_tooManyEntriesRejected}.</p>
* @throws ValidationException при {@code null}, превышении {@code options.maxMb()}, * @throws ValidationException при {@code null} входа или {@code options},
* превышении {@code options.maxMb()},
* отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы, * отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы,
* ошибке разбора zip или превышении {@code options.maxPages()} * ошибке разбора zip или превышении {@code options.maxPages()}
*/ */
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException { public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException {
if (options == null) {
throw new ValidationException("Не переданы параметры конвертации (ConvertOptions): "
+ "лимиты входа задаёт вызывающий");
}
checkInput(docxBytes, options.maxMb()); checkInput(docxBytes, options.maxMb());
if (isBinaryDoc(docxBytes)) { if (isBinaryDoc(docxBytes)) {
// Бинарный .doc: страницы — по чистому бинарному документу, // Бинарный .doc: страницы — по чистому бинарному документу,
@@ -296,7 +293,18 @@ public final class WordPdfValidator {
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { || (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
throw new ValidationException("Содержимое не похоже на .docx или .doc (не zip-архив)"); throw new ValidationException("Содержимое не похоже на .docx или .doc (не zip-архив)");
} }
checkDocxContainer(docxBytes); try {
checkDocxContainer(docxBytes,
maxDecompressedBytes(options.maxMb(), options.maxPages()),
maxDecompressedXmlBytes(options.maxMb(), options.maxPages()),
maxZipEntries(options.maxMb(), options.maxPages()),
maxImagePixels(options.maxMb()));
} catch (ArithmeticException e) {
// Бюджеты считаются multiplyExact от maxMb/maxPages: экстремальный
// лимит — отказ валидации (400), а не сырой ArithmeticException.
throw new ValidationException(
"Лимит maxMb слишком велик: " + options.maxMb());
}
checkPageCount(docxBytes, options.maxPages()); checkPageCount(docxBytes, options.maxPages());
} }
@@ -306,30 +314,60 @@ public final class WordPdfValidator {
* в {@link #checkPageCount(byte[], int)}) и наличие в * в {@link #checkPageCount(byte[], int)}) и наличие в
* {@code [Content_Types].xml} декларации документа wordprocessingml * {@code [Content_Types].xml} декларации документа wordprocessingml
* (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx). * (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx).
*
* <p>Пороги передаются параметром (считает
* {@link #validate(byte[], ConvertOptions)} из лимитов входа через
* {@link #maxDecompressedBytes} / {@link #maxDecompressedXmlBytes} /
* {@code maxZipEntries} / {@link #maxImagePixels}): заголовок
* центрального каталога врёт о размере, поэтому считается по ходу чтения.
*/ */
private static void checkDocxContainer(byte[] docxBytes) throws ValidationException { private static void checkDocxContainer(byte[] docxBytes, long maxTotal, long maxXmlTotal,
long maxTotal = WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024; long maxEntries, long maxPixels)
throws ValidationException {
long total = 0; long total = 0;
long xmlTotal = 0;
int entries = 0; int entries = 0;
// OPC требует уникальных имён частей: дубликат — либо крафт, либо
// обход кэша страниц (валидатор читает ПЕРВУЮ партию document.xml,
// парсер может взять другую) — отказ по первому повтору имени.
Set<String> names = new HashSet<>();
ByteArrayOutputStream ctBuf = new ByteArrayOutputStream(); ByteArrayOutputStream ctBuf = new ByteArrayOutputStream();
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) { try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
ZipEntry entry; ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) { while ((entry = zip.getNextEntry()) != null) {
if (!names.add(entry.getName())) {
throw new ValidationException("Дубликаты записей в архиве: " + entry.getName());
}
if (!entry.isDirectory()) { if (!entry.isDirectory()) {
entries++; entries++;
if (entries > WordPdfSettings.MAX_ZIP_ENTRIES) { if (entries > maxEntries) {
throw new ValidationException("Слишком много записей в архиве: больше " throw new ValidationException("Слишком много записей в архиве: больше "
+ WordPdfSettings.MAX_ZIP_ENTRIES); + maxEntries);
} }
} }
boolean isCt = "[Content_Types].xml".equals(entry.getName()); String name = entry.getName();
boolean isCt = "[Content_Types].xml".equals(name);
boolean isXml = name.endsWith(".xml") || name.endsWith(".rels");
// Raster-bomb: маленькая запись объявляет гигантский растр
// (декод по заголовку) — размеры читаются из head-буфера,
// весь содержимый поток идёт через счётчик total как раньше.
boolean isRaster = isRasterMedia(name);
byte[] head = isRaster ? new byte[RASTER_HEAD_LIMIT] : null;
int headLen = 0;
byte[] buf = new byte[8192]; byte[] buf = new byte[8192];
int n; int n;
while ((n = zip.read(buf)) > 0) { while ((n = zip.read(buf)) > 0) {
total += n; total += n;
if (total > maxTotal) { if (total > maxTotal) {
throw new ValidationException("Распакованный размер архива больше " throw new ValidationException("Распакованный размер архива больше "
+ WordPdfSettings.MAX_DECOMPRESSED_MB + " МБ (признак zip-бомбы)"); + (maxTotal / 1048576) + " МБ (признак zip-бомбы)");
}
if (isXml) {
xmlTotal += n;
if (xmlTotal > maxXmlTotal) {
throw new ValidationException("Суммарный распакованный размер XML-частей больше "
+ (maxXmlTotal / 1048576) + " МБ (признак zip-бомбы)");
}
} }
if (isCt) { if (isCt) {
if (ctBuf.size() + n > 8 * 1024 * 1024) { if (ctBuf.size() + n > 8 * 1024 * 1024) {
@@ -338,6 +376,18 @@ public final class WordPdfValidator {
} }
ctBuf.write(buf, 0, n); ctBuf.write(buf, 0, n);
} }
if (head != null && headLen < head.length) {
int take = Math.min(n, head.length - headLen);
System.arraycopy(buf, 0, head, headLen, take);
headLen += take;
}
}
if (head != null) {
long area = rasterArea(name, head, headLen);
if (area > maxPixels) {
throw new ValidationException("Изображение слишком большое: " + name
+ " объявляет не менее " + area + " пикселей");
}
} }
} }
} catch (ValidationException e) { } catch (ValidationException e) {
@@ -357,6 +407,55 @@ public final class WordPdfValidator {
} }
} }
/**
* Бюджет суммарной распаковки docx, байты: {@code max(MIN_DECOMPRESSED_MB×MiB,
* maxMb×10MiB + maxPages×64KiB)} — без верхней крышки: бюджет догоняет
* лимиты входа (защита от upload-бомбы масштабируется вместе с них).
* Коэффициенты — {@link WordPdfConverter#DECOMPRESS_MB_PER_MAX_MB} и
* {@link WordPdfConverter#DECOMPRESS_KIB_PER_PAGE} (запас на XML/медиа
* легитимного архива), пол — {@link WordPdfConverter#MIN_DECOMPRESSED_MB}
* (мелким лимитам входа). Регрессия —
* WordPdfValidatorTest#validate_smallLimitsBudgetFloor,
* #validate_budgetScalesWithInputLimits.
*/
static long maxDecompressedBytes(long maxMb, int maxPages) {
long budget = Math.multiplyExact(maxMb,
WordPdfConverter.DECOMPRESS_MB_PER_MAX_MB * 1048576L)
+ (long) maxPages * WordPdfConverter.DECOMPRESS_KIB_PER_PAGE * 1024L;
return Math.max(WordPdfConverter.MIN_DECOMPRESSED_MB * 1048576L, budget);
}
/**
* Бюджет распаковки XML-частей docx, байты: {@code max(MIN_DECOMPRESSED_XML_MB×MiB,
* maxMb×4MiB + maxPages×32KiB)} (XML парсится JAXB DOM — дороже байта,
* поэтому коэффициенты вдвое ниже суммарных, и пол ниже). Инвариант: при
* одних лимитах строго меньше суммарного бюджета, поэтому гейт XML
* достижим.
*/
static long maxDecompressedXmlBytes(long maxMb, int maxPages) {
long budget = Math.multiplyExact(maxMb,
WordPdfConverter.DECOMPRESS_XML_MB_PER_MAX_MB * 1048576L)
+ (long) maxPages * WordPdfConverter.DECOMPRESS_XML_KIB_PER_PAGE * 1024L;
return Math.max(WordPdfConverter.MIN_DECOMPRESSED_XML_MB * 1048576L, budget);
}
/**
* Порог пиксельной площади одного растрового медиа, пиксели:
* {@code maxMb×5_000_000} (при лимите 5 МБ — 25 Мпикс, как в Word;
* разложение в ARGB-буфер ≈ 4 байта/пиксель). Публичный — нужен
* .doc-мосту ({@code OfficeArt}) для той же защиты на своём пути.
*/
public static long maxImagePixels(long maxMb) {
return Math.multiplyExact(maxMb, WordPdfConverter.IMAGE_PIXELS_PER_MAX_MB);
}
/** Порог числа zip-записей: {@code max(2048, maxMb×512 + maxPages×32)} — защита от бомбы «много записей». */
static long maxZipEntries(long maxMb, int maxPages) {
long v = Math.multiplyExact(maxMb, WordPdfConverter.ZIP_ENTRIES_PER_MAX_MB)
+ (long) maxPages * WordPdfConverter.ZIP_ENTRIES_PER_PAGE;
return Math.max(WordPdfConverter.MIN_ZIP_ENTRIES, v);
}
/** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */ /** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */
private static boolean containsAscii(byte[] data, String needle) { private static boolean containsAscii(byte[] data, String needle) {
byte[] pat = needle.getBytes(StandardCharsets.UTF_8); byte[] pat = needle.getBytes(StandardCharsets.UTF_8);
@@ -372,6 +471,89 @@ public final class WordPdfValidator {
return false; return false;
} }
/** Растровые медиа, чьи размеры читываются из заголовка (прочие форматы не инспектируются). */
private static boolean isRasterMedia(String name) {
String n = name.toLowerCase(java.util.Locale.ROOT);
return n.endsWith(".png") || n.endsWith(".gif") || n.endsWith(".bmp")
|| n.endsWith(".jpg") || n.endsWith(".jpeg");
}
/** Хватает на PNG/GIF/BMP-заголовок и на JPEG-SOF даже с большими embedded-превью. */
private static final int RASTER_HEAD_LIMIT = 64 * 1024;
/** Минимальный читаемый заголовок GIF: сигнатура «GIF8xа» + width/height (2×u16). */
private static final int GIF_HEADER_MIN = 10;
/** Префикс каждого JPEG-сегмента: маркер 0xFF. */
private static final int JPEG_MARKER = 0xFF;
/**
* Пиксельная площадь по заголовку растра (PNG — IHDR big-endian, GIF/BMP —
* little-endian, JPEG — скан сегментов SOFn); нераспознанный/неполный
* заголовок → -1 (не отклонять: формат мог быть нестандартным, декод
* всё равно ограничен {@code total}).
*/
private static long rasterArea(String name, byte[] h, int len) {
String n = name.toLowerCase(java.util.Locale.ROOT);
if (n.endsWith(".png")) {
if (len >= 24 && (h[0] & 0xFF) == 0x89 && h[1] == 'P' && h[2] == 'N' && h[3] == 'G') {
return be32(h, 16) * (long) be32(h, 20);
}
return -1;
}
if (n.endsWith(".gif")) {
if (len >= GIF_HEADER_MIN) {
return (long) le16(h, 6) * le16(h, 8);
}
return -1;
}
if (n.endsWith(".bmp")) {
if (len >= 26 && h[0] == 'B' && h[1] == 'M') {
return Math.abs((long) le32(h, 18)) * Math.abs((long) le32(h, 22));
}
return -1;
}
// JPEG: скан маркеров до SOFn (C0–CF кроме C4/DHT, C8, CC/DAC);
// префикс FFD8 обязателен, иначе — не JPEG.
if (len < 4 || (h[0] & 0xFF) != 0xFF || (h[1] & 0xFF) != 0xD8) {
return -1;
}
int i = 2;
while (i + 4 <= len) {
if ((h[i] & JPEG_MARKER) != JPEG_MARKER) {
return -1;
}
int marker = h[i + 1] & 0xFF;
if (marker >= 0xC0 && marker <= 0xCF && marker != 0xC4 && marker != 0xC8 && marker != 0xCC) {
if (i + 9 > len) {
return -1;
}
return (long) be16(h, i + 7) * be16(h, i + 5);
}
if (marker == 0xD8 || (marker >= 0xD0 && marker <= 0xD7) || marker == 0x01) {
i += 2;
continue;
}
i += 2 + be16(h, i + 2);
}
return -1;
}
private static int be16(byte[] b, int off) {
return ((b[off] & 0xFF) << 8) | (b[off + 1] & 0xFF);
}
private static int le16(byte[] b, int off) {
return (b[off] & 0xFF) | ((b[off + 1] & 0xFF) << 8);
}
private static int be32(byte[] b, int off) {
return (be16(b, off) << 16) | be16(b, off + 2);
}
private static int le32(byte[] b, int off) {
return (le16(b, off) & 0xFFFF) | (le16(b, off + 2) << 16);
}
/** {@code word/headerN.xml} / {@code word/footerN.xml} (не .rels). */ /** {@code word/headerN.xml} / {@code word/footerN.xml} (не .rels). */
private static boolean isHeaderFooterPart(String name) { private static boolean isHeaderFooterPart(String name) {
return (name.startsWith("word/header") || name.startsWith("word/footer")) return (name.startsWith("word/header") || name.startsWith("word/footer"))
@@ -407,7 +589,7 @@ public final class WordPdfValidator {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in); XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) { while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT if (xr.next() == XMLStreamReader.START_ELEMENT
&& "Pages".equals(xr.getLocalName())) { && PAGES_ELEMENT.equals(xr.getLocalName())) {
String text = xr.getElementText().trim(); String text = xr.getElementText().trim();
return Math.max(0, Integer.parseInt(text)); return Math.max(0, Integer.parseInt(text));
} }
@@ -496,7 +678,7 @@ public final class WordPdfValidator {
// различает финальную и межсекционные) // различает финальную и межсекционные)
} }
case "type" -> { case "type" -> {
if (inBodySectPr && "sectPr".equals(parent)) { if (inBodySectPr && SECTION_PROPERTIES.equals(parent)) {
sectTypeVal = attrLocal(xr, "val"); sectTypeVal = attrLocal(xr, "val");
} }
} }
@@ -504,7 +686,7 @@ public final class WordPdfValidator {
} }
} }
} else if (ev == XMLStreamReader.END_ELEMENT) { } else if (ev == XMLStreamReader.END_ELEMENT) {
if ("sectPr".equals(xr.getLocalName()) && inBodySectPr) { if (SECTION_PROPERTIES.equals(xr.getLocalName()) && inBodySectPr) {
if (pendingNewPageSection) { if (pendingNewPageSection) {
bodyDirectSectPr++; bodyDirectSectPr++;
} }
@@ -537,7 +719,7 @@ public final class WordPdfValidator {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in); XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) { while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT if (xr.next() == XMLStreamReader.START_ELEMENT
&& "br".equals(xr.getLocalName()) && isPageBreak(xr)) { && BREAK_ELEMENT.equals(xr.getLocalName()) && isPageBreak(xr)) {
count++; count++;
} }
} }
@@ -0,0 +1,106 @@
package ru.pjandro.wordpdf.fonts;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
/**
* Таблица алиасов имён шрифтов и обратное имя для {@code w:rFonts}.
*
* Почему это вынесено из {@link BundledFontMapper}: обращение к статикам
* маппера (чарты, GlyphCoverageNormalizer, MathModel) по правилам JVM
* инициализирует и суперкласс {@code BestMatchingMapper}, чей
* {@code <clinit>} сканирует classpath-джары в реестр {@code PhysicalFonts};
* системный скан гейтится свойствами {@code docx4j.fonts.discover*},
* которые выставляет {@code WordPdfConverter.<clinit>}, — и при раннем
* обращении к мапперу скан мог пройти без гейта. У этого класса нет
* наследования, его статика безопасна при любом порядке загрузки.
* Экземпляр {@code BundledFontMapper} создаётся только в конвейере
* {@code WordPdfConverter} — всегда после его {@code <clinit>}.
*/
public final class BundledFontAliases {
/**
* Алиасы: имя шрифта из документа (lowercase) -> бандл-семейство (lowercase).
* Croscore (Arimo/Tinos/Cousine) и crosextra (Carlito/Caladea) шрифты
* метрически совместимы с соответствующими MS-шрифтами и содержат
* кириллицу.
*/
static final Map<String, String> ALIASES;
static {
Map<String, String> m = new HashMap<>();
// Частые MS-шрифты -> open-source аналоги
m.put("calibri", "carlito");
m.put("calibri light", "carlito");
m.put("cambria", "caladea");
m.put("arial", "arimo");
m.put("times new roman", "tinos");
m.put("courier new", "cousine");
// Бандл-шрифты сами по себе (на случай, если документ прямо
// указывает одно из них)
m.put("carlito", "carlito");
m.put("caladea", "caladea");
m.put("arimo", "arimo");
m.put("tinos", "tinos");
m.put("cousine", "cousine");
m.put("dejavu sans", "dejavu sans");
m.put("dejavu serif", "dejavu serif");
// Покрывающие шрифты (в документе обычно не встречаются, но если
// встречаться — маппятся на себя, а не в DejaVu-фолбэк)
m.put("noto naskh arabic", "noto naskh arabic");
m.put("noto sans armenian", "noto sans armenian");
ALIASES = Map.copyOf(m);
}
/** Финальный fallback: шрифт с гарантированной кириллицей. */
private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY;
/**
* Имя семейства для записи в {@code w:rFonts} (ключ — lowercase-семейство).
* Нужно {@code GlyphCoverageNormalizer}: он пишет в разрезанный ран
* человекочитаемое имя, а {@code BundledFontMapper.populateFontMappings}
* маппит его обратно на TTF.
*/
private static final Map<String, String> DISPLAY_NAMES = Map.of(
"dejavu sans", "DejaVu Sans",
"dejavu serif", "DejaVu Serif",
"noto naskh arabic", "Noto Naskh Arabic",
"noto sans armenian", "Noto Sans Armenian");
/**
* Имя, которое docx4j {@code RunFontSelector} запрашивает у маппера для
* символов диапазона U+2000–U+2EFF (em-dash «—», кавычки «„», многоточие
* «…»), если шрифт ранa не содержит глифа. Это виртуальное имя (в
* документе его нет), поэтому маппим его на {@link #FALLBACK_FAMILY}:
* без записи символ остаётся без font-family в FO и рендерится системным
* неembedded-шрифтом (Helvetica).
*/
static final String SYMBOL_FONT = "Segoe UI Symbol";
private BundledFontAliases() {
}
/**
* Бандл-семейство для имени шрифта из документа (таблица алиасов)
* или финальный fallback. Используется пре-рендером диаграмм и формул
* (internal/chart), которому нужен тот же шрифт, что и у текста PDF.
*/
public static String bundledFamily(String docFontName) {
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
return family != null && BundledFonts.regular(family) != null
? family
: FALLBACK_FAMILY;
}
/**
* Имя шрифта, которое можно поставить в {@code w:rFonts}, чтобы получить
* бандл-семейство {@code family}: {@code GlyphCoverageNormalizer} пишет
* его в разрезанные раны. Обратная к {@link #bundledFamily} операция —
* имена берутся из таблицы алиасов, поэтому маппинг гарантированно
* возвращается к тому же семейству.
*/
public static String documentFontName(String family) {
return DISPLAY_NAMES.getOrDefault(family, family);
}
}
@@ -4,10 +4,8 @@ import org.docx4j.fonts.BestMatchingMapper;
import org.docx4j.fonts.PhysicalFont; import org.docx4j.fonts.PhysicalFont;
import org.docx4j.wml.Fonts; import org.docx4j.wml.Fonts;
import java.util.HashMap;
import java.util.LinkedHashSet; import java.util.LinkedHashSet;
import java.util.Locale; import java.util.Locale;
import java.util.Map;
import java.util.Set; import java.util.Set;
/** /**
@@ -15,7 +13,8 @@ import java.util.Set;
* *
* Стратегия (см. {@link #populateFontMappings}): * Стратегия (см. {@link #populateFontMappings}):
* 1. Частые MS-шрифты заменяются метрически совместимыми open-source * 1. Частые MS-шрифты заменяются метрически совместимыми open-source
* аналогами (таблица алиасов) — они есть в jar и содержат кириллицу. * аналогами (таблица алиасов {@link BundledFontAliases}) — они есть в
* jar и содержат кириллицу.
* 2. Нераспознанные шрифты передаются родительскому * 2. Нераспознанные шрифты передаются родительскому
* {@link BestMatchingMapper} (совпадение по Panose-кодам среди * {@link BestMatchingMapper} (совпадение по Panose-кодам среди
* доступных шрифтов). * доступных шрифтов).
@@ -27,95 +26,30 @@ import java.util.Set;
* файл для каждого начертания. Ключи register*Form — точное имя из * файл для каждого начертания. Ключи register*Form — точное имя из
* документа: docx4j ищет варианты именно по нему. * документа: docx4j ищет варианты именно по нему.
* *
* ВАЖНО (macOS): {@code PhysicalFonts.getBoldForm} для имён бандл-шрифтов
* ({@code Tinos Regular}, {@code Carlito Regular}, …) на macOS уходит в
* {@code MicrosoftFontsRegistry} и возвращает {@code null} — у этих записей
* нет Mac-имени файла. docx4j тогда строит simulate-style fopconf (все
* начертания на regular-TTF), и FOP теряет реальные Bold/Italic: другие
* метрики и кернинг ломают переносы в узких ячейках (регрессии —
* {@code WordPdfConverterTest#strictOoxml_convertsNotRejected},
* {@code #ruPlain_regularRunsUseRegularFont}). Override-ы
* {@code getBoldForm}/{@code getItalicForm}/{@code getBoldItalicForm}
* отдают реальные бандл-варианты.
*
* ВАЖНО (порядок инициализации): конструктор BestMatchingMapper * ВАЖНО (порядок инициализации): конструктор BestMatchingMapper
* запускает обнаружение системных шрифтов, которые могут занять те же * запускает обнаружение системных шрифтов, которые могут занять те же
* имена в реестре docx4j. Поэтому {@code BundledFonts.init()} нужно * имена в реестре docx4j. Поэтому {@code BundledFonts.init()} нужно
* вызывать ПОСЛЕ создания маппера, чтобы бандл-шрифты оказались в * вызывать ПОСЛЕ создания маппера, чтобы бандл-шрифты оказались в
* реестре поверх системных. * реестре поверх системных. Таблица алиасов вынесена в
* {@link BundledFontAliases}, чтобы обращение к ней не инициировало этот
* класс до гейта {@code WordPdfConverter.<clinit>}.
*/ */
public class BundledFontMapper extends BestMatchingMapper { public class BundledFontMapper extends BestMatchingMapper {
/**
* Алиасы: имя шрифта из документа (lowercase) -> бандл-семейство (lowercase).
* Croscore (Arimo/Tinos/Cousine) и crosextra (Carlito/Caladea) шрифты
* метрически совместимы с соответствующими MS-шрифтами и содержат
* кириллицу.
*/
private static final Map<String, String> ALIASES;
/** Финальный fallback: шрифт с гарантированной кириллицей. */ /** Финальный fallback: шрифт с гарантированной кириллицей. */
private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY; private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY;
/**
* Имя семейства для записи в {@code w:rFonts} (ключ — lowercase-семейство).
* Нужно {@code GlyphCoverageNormalizer}: он пишет в разрезанный ран
* человекочитаемое имя, а {@link #populateFontMappings} маппит его
* обратно на TTF.
*/
private static final Map<String, String> DISPLAY_NAMES = Map.of(
"dejavu sans", "DejaVu Sans",
"dejavu serif", "DejaVu Serif",
"noto naskh arabic", "Noto Naskh Arabic",
"noto sans armenian", "Noto Sans Armenian");
/**
* Имя, которое docx4j {@code RunFontSelector} запрашивает у маппера для
* символов диапазона U+2000–U+2EFF (em-dash «—», кавычки «„», многоточие
* «…»), если шрифт ранa не содержит глифа. Это виртуальное имя (в
* документе его нет), поэтому маппим его на {@link #FALLBACK_FAMILY}:
* без записи символ остаётся без font-family в FO и рендерится системным
* неembedded-шрифтом (Helvetica).
*/
static final String SYMBOL_FONT = "Segoe UI Symbol";
static {
Map<String, String> m = new HashMap<>();
// Частые MS-шрифты -> open-source аналоги
m.put("calibri", "carlito");
m.put("calibri light", "carlito");
m.put("cambria", "caladea");
m.put("arial", "arimo");
m.put("times new roman", "tinos");
m.put("courier new", "cousine");
// Бандл-шрифты сами по себе (на случай, если документ прямо
// указывает одно из них)
m.put("carlito", "carlito");
m.put("caladea", "caladea");
m.put("arimo", "arimo");
m.put("tinos", "tinos");
m.put("cousine", "cousine");
m.put("dejavu sans", "dejavu sans");
m.put("dejavu serif", "dejavu serif");
// Покрывающие шрифты (в документе обычно не встречаются, но если
// встречаться — маппятся на себя, а не в DejaVu-фолбэк)
m.put("noto naskh arabic", "noto naskh arabic");
m.put("noto sans armenian", "noto sans armenian");
ALIASES = Map.copyOf(m);
}
/**
* Бандл-семейство для имени шрифта из документа (таблица алиасов)
* или финальный fallback. Используется пре-рендером диаграмм
* (internal/chart), которому нужен тот же шрифт, что и у текста PDF.
*/
public static String bundledFamily(String docFontName) {
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
return family != null && BundledFonts.regular(family) != null
? family
: FALLBACK_FAMILY;
}
/**
* Имя шрифта, которое можно поставить в {@code w:rFonts}, чтобы получить
* бандл-семейство {@code family}: {@link GlyphCoverageNormalizer} пишет
* его в разрезанные раны. Обратная к {@link #bundledFamily} операция —
* имена берутся из таблицы алиасов, поэтому маппинг гарантированно
* возвращается к тому же семейству.
*/
public static String documentFontName(String family) {
return DISPLAY_NAMES.getOrDefault(family, family);
}
/** /**
* Вызывается docx4j при {@code package.setFontMapper(...)}: для каждого * Вызывается docx4j при {@code package.setFontMapper(...)}: для каждого
* имени шрифта, использованного в документе, нужно определить, каким * имени шрифта, использованного в документе, нужно определить, каким
@@ -126,21 +60,21 @@ public class BundledFontMapper extends BestMatchingMapper {
*/ */
@Override @Override
public void populateFontMappings(Set<String> documentFontNames, Fonts wmlFonts) throws Exception { public void populateFontMappings(Set<String> documentFontNames, Fonts wmlFonts) throws Exception {
// Виртуальное имя для символов U+2000–U+2EFF (см. SYMBOL_FONT): // Виртуальное имя для символов U+2000–U+2EFF (см. BundledFontAliases.SYMBOL_FONT):
// маппим сразу, чтобы оно не попало в remaining и родительский // маппим сразу, чтобы оно не попало в remaining и родительский
// BestMatchingMapper не пытался искать его в fontTable (и не логировал // BestMatchingMapper не пытался искать его в fontTable (и не логировал
// "Font Segoe UI Symbol not found in font table!"). // "Font Segoe UI Symbol not found in font table!").
if (BundledFonts.regular(FALLBACK_FAMILY) != null) { if (BundledFonts.regular(FALLBACK_FAMILY) != null) {
mapFamily(SYMBOL_FONT, FALLBACK_FAMILY); mapFamily(BundledFontAliases.SYMBOL_FONT, FALLBACK_FAMILY);
} }
Set<String> remaining = new LinkedHashSet<>(); Set<String> remaining = new LinkedHashSet<>();
for (String docFontName : documentFontNames) { for (String docFontName : documentFontNames) {
if (SYMBOL_FONT.equalsIgnoreCase(docFontName)) { if (BundledFontAliases.SYMBOL_FONT.equalsIgnoreCase(docFontName)) {
// уже маппировано выше // уже маппировано выше
continue; continue;
} }
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT)); String family = BundledFontAliases.ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
if (family == null || BundledFonts.regular(family) == null) { if (family == null || BundledFonts.regular(family) == null) {
// Нет алиаса (или init() не вызван) — доверимся родителю // Нет алиаса (или init() не вызван) — доверимся родителю
remaining.add(docFontName); remaining.add(docFontName);
@@ -163,6 +97,51 @@ public class BundledFontMapper extends BestMatchingMapper {
} }
} }
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
@Override
public PhysicalFont getBoldForm(String fontName, PhysicalFont physicalFont) {
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_BOLD);
return bundled != null ? bundled : super.getBoldForm(fontName, physicalFont);
}
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
@Override
public PhysicalFont getItalicForm(String fontName, PhysicalFont physicalFont) {
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_ITALIC);
return bundled != null ? bundled : super.getItalicForm(fontName, physicalFont);
}
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
@Override
public PhysicalFont getBoldItalicForm(String fontName, PhysicalFont physicalFont) {
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_BOLD_ITALIC);
return bundled != null ? bundled : super.getBoldItalicForm(fontName, physicalFont);
}
/**
* Реальное начертание бандл-семейства, к которому относится {@code pf}.
*
* <p>Семейство опознаётся по {@code embeddedURI} regular-варианта, а не
* по имени: на macOS имя в реестре docx4j — полное из TTF-таблицы
* ({@code Tinos Regular}), и именно на нём ломается
* {@code PhysicalFonts.getBoldForm}. Шрифт вне бандла (или {@code pf ==
* null}, {@code BundledFonts.init()} не вызван) → {@code null}, вызывающий
* идёт родительской логикой.</p>
*/
private static PhysicalFont bundledSibling(PhysicalFont pf, String variant) {
if (pf == null || pf.getEmbeddedURI() == null) {
return null;
}
String uri = pf.getEmbeddedURI().toString();
for (String family : BundledFonts.families()) {
PhysicalFont regular = BundledFonts.regular(family);
if (regular != null && uri.equals(regular.getEmbeddedURI().toString())) {
return BundledFonts.font(family, variant);
}
}
return null;
}
/** /**
* Привязывает все начертания семейства к имени шрифта из документа. * Привязывает все начертания семейства к имени шрифта из документа.
*/ */
@@ -2,6 +2,7 @@ package ru.pjandro.wordpdf.fonts;
import org.docx4j.fonts.PhysicalFont; import org.docx4j.fonts.PhysicalFont;
import org.docx4j.fonts.PhysicalFonts; import org.docx4j.fonts.PhysicalFonts;
import ru.pjandro.wordpdf.WordPdfConverter;
import java.io.IOException; import java.io.IOException;
import java.io.InputStream; import java.io.InputStream;
@@ -124,57 +125,65 @@ public final class BundledFonts {
/** /**
* Выгружает шрифты из jar и регистрирует их в docx4j. * Выгружает шрифты из jar и регистрирует их в docx4j.
* Повторные вызовы игнорируются (idempotентно). * Повторные вызовы игнорируются (idempotентно).
*
* <p>Монитор — {@code WordPdfConverter.class}, а не {@code BundledFonts.class}:
* {@code PhysicalFonts} и {@link #VARIANTS} читаются рендером внутри
* конвертации (она сериализована монитором конвертера), и мутация под
* собственным замком вырезала бы записи из-под идущего рендера.
* Все синхронизированные методы класса держат ровно этот монитор.</p>
*/ */
public static synchronized void init() { public static void init() {
if (inited) { synchronized (WordPdfConverter.class) {
return; if (inited) {
} return;
try { }
extractDir = Files.createTempDirectory("wordpdf-fonts-"); try {
} catch (IOException e) { extractDir = Files.createTempDirectory("wordpdf-fonts-");
throw new IllegalStateException("Не удалось создать временный каталог для шрифтов", e);
}
// Ключ реестра docx4j — имя шрифта, и addPhysicalFont не перезаписывает
// занятый ключ. Системный DejaVuSerif.ttf занимает «dejavu serif», и
// наш DejaVuSerif-Regular.ttf (то же имя) просто не добавился бы.
dropNonBundled();
for (Entry entry : ENTRIES) {
// 1. Выгружаем файл из jar
Path target = extractDir.resolve(entry.file());
try (InputStream in = BundledFonts.class.getClassLoader()
.getResourceAsStream(CLASSPATH_DIR + "/" + entry.file())) {
if (in == null) {
throw new IllegalStateException(
"Шрифт не найден в jar: " + CLASSPATH_DIR + "/" + entry.file());
}
Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
// deleteOnExit не рекурсивен: каталог удалится только пустым,
// поэтому регистрируем каждый выгруженный TTF.
target.toFile().deleteOnExit();
} catch (IOException e) { } catch (IOException e) {
throw new IllegalStateException("Не удалось выгрузить шрифт " + entry.file(), e); throw new IllegalStateException("Не удалось создать временный каталог для шрифтов", e);
}
// Ключ реестра docx4j — имя шрифта, и addPhysicalFont не перезаписывает
// занятый ключ. Системный DejaVuSerif.ttf занимает «dejavu serif», и
// наш DejaVuSerif-Regular.ttf (то же имя) просто не добавился бы.
dropNonBundled();
for (Entry entry : ENTRIES) {
// 1. Выгружаем файл из jar
Path target = extractDir.resolve(entry.file());
try (InputStream in = BundledFonts.class.getClassLoader()
.getResourceAsStream(CLASSPATH_DIR + "/" + entry.file())) {
if (in == null) {
throw new IllegalStateException(
"Шрифт не найден в jar: " + CLASSPATH_DIR + "/" + entry.file());
}
Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
// deleteOnExit не рекурсивен: каталог удалится только пустым,
// поэтому регистрируем каждый выгруженный TTF.
target.toFile().deleteOnExit();
} catch (IOException e) {
throw new IllegalStateException("Не удалось выгрузить шрифт " + entry.file(), e);
}
// 2. Регистрируем в docx4j: имя в реестре docx4j берёт из
// name-таблицы TTF, поэтому ищем результат по URI файла
PhysicalFonts.addPhysicalFont(target.toUri());
PhysicalFont pf = findByFile(target.getFileName().toString());
if (pf == null) {
throw new IllegalStateException(
"docx4j не зарегистрировал шрифт: " + entry.file()
+ " (файл повреждён или не embeddable?)");
}
// 3. Учимся: семейство -> начертание -> PhysicalFont
VARIANTS
.computeIfAbsent(entry.family(), k -> new HashMap<>())
.put(entry.variant(), pf);
} }
// 2. Регистрируем в docx4j: имя в реестре docx4j берёт из // Удаление временного каталога при завершении JVM
// name-таблицы TTF, поэтому ищем результат по URI файла extractDir.toFile().deleteOnExit();
PhysicalFonts.addPhysicalFont(target.toUri()); inited = true;
PhysicalFont pf = findByFile(target.getFileName().toString());
if (pf == null) {
throw new IllegalStateException(
"docx4j не зарегистрировал шрифт: " + entry.file()
+ " (файл повреждён или не embeddable?)");
}
// 3. Учимся: семейство -> начертание -> PhysicalFont
VARIANTS
.computeIfAbsent(entry.family(), k -> new HashMap<>())
.put(entry.variant(), pf);
} }
// Удаление временного каталога при завершении JVM
extractDir.toFile().deleteOnExit();
inited = true;
} }
/** /**
@@ -188,12 +197,18 @@ public final class BundledFonts {
* em-dash на шрифте ранa (Carlito) вместо fallback-DejaVu. * em-dash на шрифте ранa (Carlito) вместо fallback-DejaVu.
* Шрифты, встроенные в docx, регистрируются при {@code load()} — * Шрифты, встроенные в docx, регистрируются при {@code load()} —
* если чистить до load(), они останутся в реестре. * если чистить до load(), они останутся в реестре.
* <p>Мутирует глобальный реестр {@code PhysicalFonts} под монитором
* {@code WordPdfConverter.class} — тем же, что сериализует конвертации,
* поэтому вызов рядом с идущей {@code WordPdfConverter.convert()}
* безопасен автоматически (замок удерживается внутри метода).
*/ */
public static synchronized void restrictToBundled() { public static void restrictToBundled() {
if (!inited) { synchronized (WordPdfConverter.class) {
return; if (!inited) {
return;
}
dropNonBundled();
} }
dropNonBundled();
} }
/** Удаляет из реестра всё, что не было выгружено из jar в {@link #extractDir}. */ /** Удаляет из реестра всё, что не было выгружено из jar в {@link #extractDir}. */
@@ -232,12 +247,18 @@ public final class BundledFonts {
/** /**
* Зарегистрированный шрифт: семейство (lowercase) + начертание. * Зарегистрированный шрифт: семейство (lowercase) + начертание.
* Синхронизирован с {@link #init()} общим монитором
* {@code WordPdfConverter.class}: {@code VARIANTS} — обычный
* {@code HashMap}, наполняемый в {@code init()}; без замка внешний
* читатель мог бы увидеть недобранную карту.
* *
* @return PhysicalFont или null (если init() не вызван или шрифта нет) * @return PhysicalFont или null (если init() не вызван или шрифта нет)
*/ */
public static PhysicalFont font(String family, String variant) { public static PhysicalFont font(String family, String variant) {
Map<String, PhysicalFont> m = VARIANTS.get(family); synchronized (WordPdfConverter.class) {
return m == null ? null : m.get(variant); Map<String, PhysicalFont> m = VARIANTS.get(family);
return m == null ? null : m.get(variant);
}
} }
public static PhysicalFont regular(String family) { public static PhysicalFont regular(String family) {
@@ -38,6 +38,12 @@ import java.util.Map;
* каталога {@link BundledFonts#init()} — поэтому класс не зависит от * каталога {@link BundledFonts#init()} — поэтому класс не зависит от
* порядка шагов конвертации. TTF буферизуется в памяти и живёт до конца * порядка шагов конвертации. TTF буферизуется в памяти и живёт до конца
* JVM (шрифты бандла конечны, {@link TrueTypeFont} намеренно не закрываем). * JVM (шрифты бандла конечны, {@link TrueTypeFont} намеренно не закрываем).
*
* Потокобезопасен: {@link #of(String, String)} идёт под монитором класса
* (единый {@code CACHE}), {@code cmap} — {@code volatile} поле с
* идемпотентным пересчётом, а ленивые таблицы fontbox читаются под её
* внутренними замками ({@code TrueTypeFont.lockReadtable}, fontbox 3.x) —
* один экземпляр можно держать в нескольких потоках.
*/ */
public final class GlyphFont { public final class GlyphFont {
@@ -13,7 +13,7 @@ import java.util.regex.Pattern;
/** /**
* Нормализация ST_OnOff-значений в docx перед загрузкой docx4j. * Нормализация ST_OnOff-значений в docx перед загрузкой docx4j.
* *
* docx4j 11.x теряет атрибуты {@code w:val="off"} / {@code w:val="on"} * docx4j 17.x теряет атрибуты {@code w:val="off"} / {@code w:val="on"}
* при JAXB-разборе (тип поля {@code Boolean} не принимает "on"/"off", * при JAXB-разборе (тип поля {@code Boolean} не принимает "on"/"off",
* поле остаётся null и {@code BooleanDefaultTrue.isVal()} считается * поле остаётся null и {@code BooleanDefaultTrue.isVal()} считается
* true). Из-за этого явные {@code <w:b w:val="off"/>} и * true). Из-за этого явные {@code <w:b w:val="off"/>} и
@@ -22,9 +22,14 @@ import java.util.regex.Pattern;
* docx4j разбирает корректно, поэтому заменяем "off"->"false", * docx4j разбирает корректно, поэтому заменяем "off"->"false",
* "on"->"true" в XML-частях word/*.xml. * "on"->"true" в XML-частях word/*.xml.
* *
* <p>Исключение — {@code w:scrollbar} (свойство фрейма, §17.15.2.37): его
* {@code w:val} — ST_FrameScrollbar (none/left/right/leftAndRight,
* §17.18.32), единственный не-ST_OnOff носитель on/off в WML; переписывать
* его нельзя — вывод станет невалидным.
*
* Если совпадений нет, возвращает исходный массив без переупаковки zip. * Если совпадений нет, возвращает исходный массив без переупаковки zip.
*/ */
public final class DocxOnOffNormalizer { final class DocxOnOffNormalizer {
/** /**
* {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от * {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от
@@ -33,15 +38,12 @@ public final class DocxOnOffNormalizer {
* {@code w:t} не правится. Регрессия — DocxOnOffNormalizerTest#onOffInTextNotTouched. * {@code w:t} не правится. Регрессия — DocxOnOffNormalizerTest#onOffInTextNotTouched.
*/ */
private static final Pattern ON_OFF = Pattern.compile( private static final Pattern ON_OFF = Pattern.compile(
"(<[A-Za-z][A-Za-z0-9:]*(?:\\s[^<>]*)?)w:val=([\"'])(on|off)\\2", "(<(?!w:scrollbar\\b)[A-Za-z][A-Za-z0-9:]*(?:\\s[^<>]*)?)w:val=([\"'])(on|off)\\2",
Pattern.CASE_INSENSITIVE); Pattern.CASE_INSENSITIVE);
private DocxOnOffNormalizer() { private DocxOnOffNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = DocxOnOffNormalizer::normalize;
/** /**
* Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on" * Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on"
* на "false"/"true". * на "false"/"true".
@@ -49,7 +51,7 @@ public final class DocxOnOffNormalizer {
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -15,19 +15,21 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
/** /**
* Единый zip-проход переписывания XML-частей (.docx) вместо отдельных * Единый zip-проход переписывания XML-частей (.docx) вместо отдельных
* проходов нормализаторов: к каждой записи {@code word/*.xml} применяются * проходов нормализаторов: к каждой записи {@code word/*.xml} применяются
* все десять рерайтов в фиксированном порядке * все одиннадцать рерайтов в фиксированном порядке
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. * Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby.
* Порядок значим: Strict первым — дальше части в transitional-виде * Порядок значим: Strict первым — дальше части в transitional-виде
* (TableIndent читает transitional-атрибуты {@code w:}); GlyphCoverage * (TableIndent читает transitional-атрибуты {@code w:}); MathFallback
* шестым — flatten unsupported-формул даёт обычный текст ранов, который
* следующий GlyphCoverage покрывает кириллицей бандла; GlyphCoverage
* режет раны по финальному тексту рана (после Symbol/Invisible); Hidden * режет раны по финальному тексту рана (после Symbol/Invisible); Hidden
* последним — вырезает уже финальные раны (после Symbol/GLYPH-разбиений), * десятым — вырезает уже финальные раны (после Symbol/GLYPH-разбиений),
* а его OnOff-форма vanish читается после правила 2. Каждый * а его OnOff-форма vanish читается после правила 2. Каждый
* рерайт работает только содержимым одной части, поэтому по-частная * рерайт работает только содержимым одной части, поэтому по-частная
* цепочка эквивалентна последовательным полным проходам. Исключения из * цепочка эквивалентна последовательным полным проходам. Исключения из
* «по-частности» — контексты, читаемые один раз до цикла: правило 7 * «по-частности» — контексты, читаемые один раз до цикла: правило 8
* (TableIndent) — у header/footer-частей своей sectPr нет, ширина полосы * (TableIndent) — у header/footer-частей своей sectPr нет, ширина полосы
* передаётся из document.xml (многосекционный документ — полоса * передаётся из document.xml (многосекционный документ — полоса
* неоднозначна, header/footer пропускаются); правило 9 (Hidden) — * неоднозначна, header/footer пропускаются); правило 10 (Hidden) —
* стилевые vanish читаются из word/styles.xml (цепочка w:basedOn). * стилевые vanish читаются из word/styles.xml (цепочка w:basedOn).
* *
* <p>Неизменённые записи (медиа, rels, прочее) переносятся raw-копией * <p>Неизменённые записи (медиа, rels, прочее) переносятся raw-копией
@@ -52,46 +54,51 @@ public final class DocxRewritePipeline {
public static final DocxNormalizer STEP = DocxRewritePipeline::normalize; public static final DocxNormalizer STEP = DocxRewritePipeline::normalize;
/** /**
* Применяет десять рерайтов к каждой записи {@code word/*.xml} за один * Применяет одиннадцать рерайтов к каждой записи {@code word/*.xml} за один
* проход zip. * проход zip.
* *
* @param docx байты .docx (валидный zip) * @param docx байты .docx (валидный zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx)); try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx));
ZipArchiveOutputStream zos = new ZipArchiveOutputStream(out)) { ZipArchiveOutputStream zos = new ZipArchiveOutputStream(out)) {
// Ширина полосы набора для правила 7 (таблицы в header/footer- // Ширина полосы набора для правила 8 (таблицы в header/footer-
// частях своей sectPr не содержат): из сырого document.xml — // частях своей sectPr не содержат): из сырого document.xml —
// геометрия инвариантна к рерайтам цепочки (Strict не трогает // геометрия инвариантна к рерайтам цепочки (Strict не трогает
// w:pgSz/@w:w, а pgMar-чередование left|start покрывает strict). // w:pgSz/@w:w; у strict CT_PageMar start/end нет вовсе —
// только left/right).
// Записи нет/несколько секций → −1, header/footer консервативно // Записи нет/несколько секций → −1, header/footer консервативно
// пропускаются (та же неоднозначность полосы, что для body). // пропускаются (та же неоднозначность полосы, что для body).
int band = -1; int band = -1;
ZipArchiveEntry docEntry = zf.getEntry("word/document.xml"); ZipArchiveEntry docEntry = zf.getEntry("word/document.xml");
if (docEntry != null) { if (docEntry != null) {
band = TableIndentNormalizer.bandOf( try (InputStream in = zf.getInputStream(docEntry)) {
new String(zf.getInputStream(docEntry).readAllBytes(), band = TableIndentNormalizer.bandOf(
StandardCharsets.UTF_8)); new String(in.readAllBytes(), StandardCharsets.UTF_8));
}
} }
// Стилевые vanish для правила 9 (скрытый текст): часть стилевой // Стилевые vanish для правила 10 (скрытый текст): часть стилевой
// цепочки w:basedOn вычисляется один раз до цикла. Записи нет → // цепочки w:basedOn вычисляется один раз до цикла. Записи нет →
// пустое множество, рерайт работает по прямому vanish. // пустое множество, рерайт работает по прямому vanish.
Set<String> hiddenStyles = Set.of(); Set<String> hiddenStyles = Set.of();
ZipArchiveEntry stylesEntry = zf.getEntry("word/styles.xml"); ZipArchiveEntry stylesEntry = zf.getEntry("word/styles.xml");
if (stylesEntry != null) { if (stylesEntry != null) {
hiddenStyles = HiddenTextNormalizer.vanishStyles( try (InputStream in = zf.getInputStream(stylesEntry)) {
new String(zf.getInputStream(stylesEntry).readAllBytes(), hiddenStyles = HiddenTextNormalizer.vanishStyles(
StandardCharsets.UTF_8)); new String(in.readAllBytes(), StandardCharsets.UTF_8));
}
} }
for (ZipArchiveEntry entry : Collections.list(zf.getEntries())) { for (ZipArchiveEntry entry : Collections.list(zf.getEntries())) {
String name = entry.getName(); String name = entry.getName();
byte[] rewritten = null; byte[] rewritten = null;
if (name.startsWith("word/") && name.endsWith(".xml")) { if (name.startsWith("word/") && name.endsWith(".xml")) {
String xml = new String(zf.getInputStream(entry).readAllBytes(), String xml;
StandardCharsets.UTF_8); try (InputStream in = zf.getInputStream(entry)) {
xml = new String(in.readAllBytes(), StandardCharsets.UTF_8);
}
String cur = xml; String cur = xml;
String next = StrictOoxmlNormalizer.rewritePart(name, cur); String next = StrictOoxmlNormalizer.rewritePart(name, cur);
if (next != null) { if (next != null) {
@@ -113,6 +120,10 @@ public final class DocxRewritePipeline {
if (next != null) { if (next != null) {
cur = next; cur = next;
} }
next = MathFallbackNormalizer.rewrite(cur);
if (next != null) {
cur = next;
}
next = GlyphCoverageNormalizer.rewrite(cur); next = GlyphCoverageNormalizer.rewrite(cur);
if (next != null) { if (next != null) {
cur = next; cur = next;
@@ -133,7 +144,7 @@ public final class DocxRewritePipeline {
if (next != null) { if (next != null) {
cur = next; cur = next;
} }
if (cur != xml) { if (!cur.equals(xml)) {
changed = true; changed = true;
rewritten = cur.getBytes(StandardCharsets.UTF_8); rewritten = cur.getBytes(StandardCharsets.UTF_8);
} }
@@ -161,7 +172,9 @@ public final class DocxRewritePipeline {
} else { } else {
// прочие методы/шифрованные — обычный перенос // прочие методы/шифрованные — обычный перенос
zos.putArchiveEntry(new ZipArchiveEntry(name)); zos.putArchiveEntry(new ZipArchiveEntry(name));
zf.getInputStream(entry).transferTo(zos); try (InputStream in = zf.getInputStream(entry)) {
in.transferTo(zos);
}
zos.closeArchiveEntry(); zos.closeArchiveEntry();
} }
} }
@@ -1,13 +1,6 @@
package ru.pjandro.wordpdf.internal; package ru.pjandro.wordpdf.internal;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Locale; import java.util.Locale;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;
/** /**
* Разворачивание «сложных» полей PAGE/NUMPAGES в {@code w:fldSimple} — * Разворачивание «сложных» полей PAGE/NUMPAGES в {@code w:fldSimple} —
@@ -30,13 +23,14 @@ import java.util.zip.ZipOutputStream;
* внутрь {@code w:sdt}: нумерация страниц Word почти всегда лежит в * внутрь {@code w:sdt}: нумерация страниц Word почти всегда лежит в
* контентном контроле («Page Numbers (Top of Page)»), и до поля не добирается. * контентном контроле («Page Numbers (Top of Page)»), и до поля не добирается.
* Отсюда и нормализация байтов, как в {@link DocxOnOffNormalizer}. * Отсюда и нормализация байтов, как в {@link DocxOnOffNormalizer}.
* Регрессия — WordPdfConverterTest#pageNumbers_recomputedNotCached.
* *
* Трогаются только поля, которые действительно есть кому рисовать * Трогаются только поля, которые действительно есть кому рисовать
* ({@link #SUPPORTED}); остальные остаются как были. Вложенные поля не * ({@link #SUPPORTED}); остальные остаются как были. Вложенные поля не
* разбираются — если внутри {@code begin … end} встречается ещё один * разбираются — если внутри {@code begin … end} встречается ещё один
* {@code begin}, поле пропускается. * {@code begin}, поле пропускается.
*/ */
public final class FieldNormalizer { final class FieldNormalizer {
/** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */ /** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */
private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"}; private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"};
@@ -44,39 +38,6 @@ public final class FieldNormalizer {
private FieldNormalizer() { private FieldNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = FieldNormalizer::normalize;
/**
* Переписывает поддерживаемые поля во всех word/*.xml частях docx.
*
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
ZipOutputStream zos = new ZipOutputStream(out)) {
ZipEntry entry;
while ((entry = zis.getNextEntry()) != null) {
byte[] data = zis.readAllBytes();
String name = entry.getName();
if (name.startsWith("word/") && name.endsWith(".xml")) {
String fixed = rewrite(new String(data, StandardCharsets.UTF_8));
if (fixed != null) {
changed = true;
data = fixed.getBytes(StandardCharsets.UTF_8);
}
}
zos.putNextEntry(new ZipEntry(name));
zos.write(data);
zos.closeEntry();
}
}
return changed ? out.toByteArray() : docx;
}
/** /**
* @return новая строка либо null, если менять нечего * @return новая строка либо null, если менять нечего
*/ */
@@ -26,7 +26,16 @@ import ru.pjandro.wordpdf.fonts.BundledFonts;
* рендерится шрифтом просмотрщика либо .notdef («#»). Поэтому в конфиг * рендерится шрифтом просмотрщика либо .notdef («#»). Поэтому в конфиг
* добавляются ВСЕ шрифты бандла: стоит они в документе или нет, решает FO. * добавляются ВСЕ шрифты бандла: стоит они в документе или нет, решает FO.
* *
* Метод идемпотентен: уже задекларированное семейство не дублируется. * Конфиг обязан быть полным при каждом {@code declare}: общая FopFactory
* ({@code WordPdfConverter.sharedFopFactory}) строится из fopconf первого
* документа JVM, а docx4j декларирует из {@code fontsInUse} только
* использованные начертания — {@code declareFamily} дополняет семейство
* недостающими реальными начертаниями, а не пропускает его целиком.
* Идемпотентность: начертание, уже имеющее в конфиге запись на реальном
* TTF, не дублируется.
*
* <p>Регрессия — FopFallbackFontsTest#declareWhenDocx4jDeclaredRegularOnly_addsMissingVariants,
* WordPdfConverterTest#fopFactoryFrozenFromFirstDoc_fontsComplete.
*/ */
public final class FopFallbackFonts { public final class FopFallbackFonts {
@@ -49,7 +58,15 @@ public final class FopFallbackFonts {
} }
} }
/** Одно семейство: regular + существующие начертания (Noto — только regular). */ /**
* Одно семейство: каждое начертание, для которого в конфиге нет
* записи с реальным TTF этого начертания (Noto — только regular,
* отсутствующие варианты пропускаются). Family-level «уже есть —
* пропускаем всё» запрещён: docx4j декларирует только использованные
* начертания (или simulate-style на одном файле), а общая FopFactory
* замораживает конфиг первого документа на всю JVM — пропущенное
* семейство остаётся неполным для всех последующих конвертаций.
*/
private static void declareFamily(Fonts rendererFonts, ObjectFactory factory, private static void declareFamily(Fonts rendererFonts, ObjectFactory factory,
String family) { String family) {
PhysicalFont regular = BundledFonts.regular(family); PhysicalFont regular = BundledFonts.regular(family);
@@ -61,21 +78,43 @@ public final class FopFallbackFonts {
// и под это же имя декларируются все начертания (так делает // и под это же имя декларируются все начертания (так делает
// docx4j FopConfigUtil.createVariant). // docx4j FopConfigUtil.createVariant).
String familyName = regular.getName(); String familyName = regular.getName();
for (Fonts.Font existing : rendererFonts.getFont()) { String[][] variants = {
for (Fonts.Font.FontTriplet triplet : existing.getFontTriplet()) { {BundledFonts.V_REGULAR, "normal", "normal"},
if (familyName.equals(triplet.getName())) { {BundledFonts.V_BOLD, "normal", "bold"},
return; {BundledFonts.V_ITALIC, "italic", "normal"},
{BundledFonts.V_BOLD_ITALIC, "italic", "bold"},
};
for (String[] v : variants) {
PhysicalFont variant = BundledFonts.font(family, v[0]);
if (variant == null
|| hasRealFace(rendererFonts, familyName, v[1], v[2], variant)) {
continue;
}
addFont(rendererFonts, factory, familyName, variant, v[1], v[2]);
}
}
/**
* Есть ли в конфиге запись триплета (familyName, style, weight) именно
* на реальном TTF {@code variant}. Триплет без этого embed-url
* (simulate-style docx4j — все начертания на regular-файле) реальным
* лицом не считается: FOP встроит из него не то начертание.
*/
private static boolean hasRealFace(Fonts rendererFonts, String familyName,
String style, String weight, PhysicalFont variant) {
String url = variant.getEmbeddedURI().toString();
for (Fonts.Font font : rendererFonts.getFont()) {
if (!url.equals(font.getEmbedUrl())) {
continue;
}
for (Fonts.Font.FontTriplet triplet : font.getFontTriplet()) {
if (familyName.equals(triplet.getName()) && style.equals(triplet.getStyle())
&& weight.equals(triplet.getWeight())) {
return true;
} }
} }
} }
return false;
addFont(rendererFonts, factory, familyName, regular, "normal", "normal");
addFont(rendererFonts, factory, familyName,
BundledFonts.bold(family), "normal", "bold");
addFont(rendererFonts, factory, familyName,
BundledFonts.italic(family), "italic", "normal");
addFont(rendererFonts, factory, familyName,
BundledFonts.boldItalic(family), "italic", "bold");
} }
/** /**
@@ -1,21 +1,14 @@
package ru.pjandro.wordpdf.internal; package ru.pjandro.wordpdf.internal;
import ru.pjandro.wordpdf.fonts.BundledFontMapper; import ru.pjandro.wordpdf.fonts.BundledFontAliases;
import ru.pjandro.wordpdf.fonts.BundledFonts; import ru.pjandro.wordpdf.fonts.BundledFonts;
import ru.pjandro.wordpdf.fonts.GlyphFont; import ru.pjandro.wordpdf.fonts.GlyphFont;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.List; import java.util.List;
import java.util.Map; import java.util.Map;
import java.util.regex.Matcher; import java.util.regex.Matcher;
import java.util.regex.Pattern; import java.util.regex.Pattern;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
/** /**
@@ -38,7 +31,7 @@ import java.util.concurrent.ConcurrentHashMap;
* Делаем то, что должен был сделать рендер: ран, в тексте которого есть * Делаем то, что должен был сделать рендер: ран, в тексте которого есть
* знаки без глифа, разрезается на части, и каждой части явно назначается * знаки без глифа, разрезается на части, и каждой части явно назначается
* бандл-семейство, где глиф есть ({@link #targetFamily}). Имя пишется в * бандл-семейство, где глиф есть ({@link #targetFamily}). Имя пишется в
* {@code w:rFonts}, дальше {@link BundledFontMapper} маппит его на TTF, * {@code w:rFonts}, дальше {@code BundledFontMapper} маппит его на TTF,
* а {@link FopFallbackFonts} декларирует его в FOP-конфиге. * а {@link FopFallbackFonts} декларирует его в FOP-конфиге.
* *
* Правила, ограничивающие вмешательство: * Правила, ограничивающие вмешательство:
@@ -54,7 +47,7 @@ import java.util.concurrent.ConcurrentHashMap;
* *
* Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора. * Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора.
*/ */
public final class GlyphCoverageNormalizer { final class GlyphCoverageNormalizer {
/** Семейства с засечками: для них fallback ищется сначала среди serif. */ /** Семейства с засечками: для них fallback ищется сначала среди serif. */
private static final List<String> SERIF_FAMILIES = private static final List<String> SERIF_FAMILIES =
@@ -81,39 +74,6 @@ public final class GlyphCoverageNormalizer {
private GlyphCoverageNormalizer() { private GlyphCoverageNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = GlyphCoverageNormalizer::normalize;
/**
* Разрезает раны с непокрытыми глифами в XML-частях docx (word/*.xml).
*
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
ZipOutputStream zos = new ZipOutputStream(out)) {
ZipEntry entry;
while ((entry = zis.getNextEntry()) != null) {
byte[] data = zis.readAllBytes();
String name = entry.getName();
if (name.startsWith("word/") && name.endsWith(".xml")) {
String fixed = rewrite(new String(data, StandardCharsets.UTF_8));
if (fixed != null) {
changed = true;
data = fixed.getBytes(StandardCharsets.UTF_8);
}
}
zos.putNextEntry(new ZipEntry(name));
zos.write(data);
zos.closeEntry();
}
}
return changed ? out.toByteArray() : docx;
}
/** /**
* Переписывает раны с непокрытыми глифами. * Переписывает раны с непокрытыми глифами.
* *
@@ -409,7 +369,7 @@ public final class GlyphCoverageNormalizer {
if (!m.find()) { if (!m.find()) {
return null; return null;
} }
return BundledFontMapper.bundledFamily(m.group(2)); return BundledFontAliases.bundledFamily(m.group(2));
} }
/** /**
@@ -417,7 +377,7 @@ public final class GlyphCoverageNormalizer {
* {@code w:rFonts}, а если их нет — вставляет элемент первым ребёнком. * {@code w:rFonts}, а если их нет — вставляет элемент первым ребёнком.
*/ */
private static String forceFont(String rPr, String family) { private static String forceFont(String rPr, String family) {
String name = BundledFontMapper.documentFontName(family); String name = BundledFontAliases.documentFontName(family);
String fonts = "<w:rFonts w:ascii=\"" + name + "\" w:hAnsi=\"" + name + "\"/>"; String fonts = "<w:rFonts w:ascii=\"" + name + "\" w:hAnsi=\"" + name + "\"/>";
if (rPr.isEmpty()) { if (rPr.isEmpty()) {
return "<w:rPr>" + fonts + "</w:rPr>"; return "<w:rPr>" + fonts + "</w:rPr>";
@@ -24,7 +24,7 @@ import org.apache.commons.compress.archivers.zip.ZipFile;
import org.apache.commons.compress.utils.SeekableInMemoryByteChannel; import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
/** /**
* Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.30) из * Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.41) из
* XML-частей — до загрузки docx4j. * XML-частей — до загрузки docx4j.
* *
* <p>Word по умолчанию не выводит скрытый текст ни на экран, ни на печать, * <p>Word по умолчанию не выводит скрытый текст ни на экран, ни на печать,
@@ -39,8 +39,13 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
* правило 2 к моменту запуска уже привело on/off к true/false, но обе формы * правило 2 к моменту запуска уже привело on/off к true/false, но обе формы
* принимаются) либо {@code w:rStyle} ссылается на стиль с vanish — по * принимаются) либо {@code w:rStyle} ссылается на стиль с vanish — по
* цепочке {@code w:basedOn} (капа 16, цикл — обрыв; тот же приём, что * цепочке {@code w:basedOn} (капа 16, цикл — обрыв; тот же приём, что
* {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой; * {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой
* вложенные раны ({@code w:rubyBase}/{@code w:rt}, текстовые боксы) * (§17.7.3: в конфликте toggle выигрывает direct formatting); принятое
* упрощение стилевого слоя — явный falsy {@code w:val} <b>у стиля</b>
* (vanish=false поверх vanish-предка по {@code w:basedOn}) не
* разворачивается: стиль с {@code w:vanish} делает раны скрытыми
* независимо от {@code w:val}; вложенные раны
* ({@code w:rubyBase}/{@code w:rt}, текстовые боксы)
* оцениваются независимо, но ран внутри уже удалённого внешнего не * оцениваются независимо, но ран внутри уже удалённого внешнего не
* вырезается повторно (диапазоны сливаются при сборке). * вырезается повторно (диапазоны сливаются при сборке).
* *
@@ -64,7 +69,7 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
* *
* <p>Регрессия — WordPdfConverterTest#hiddenText_notPrinted. * <p>Регрессия — WordPdfConverterTest#hiddenText_notPrinted.
*/ */
public final class HiddenTextNormalizer { final class HiddenTextNormalizer {
/** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */ /** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */
private static final int MAX_CHAIN = 16; private static final int MAX_CHAIN = 16;
@@ -72,6 +77,10 @@ public final class HiddenTextNormalizer {
/** Закрывающий слэш самозакрывающегося тега. */ /** Закрывающий слэш самозакрывающегося тега. */
private static final char SELF_CLOSE = '/'; private static final char SELF_CLOSE = '/';
/** Части, которые рерайт пропускает: ранов там нет, а vanish в styles — входные данные. */
private static final String STYLES_PART = "word/styles.xml";
private static final String NUMBERING_PART = "word/numbering.xml";
/** Открывающий/закрывающий тег рана; {@code <w:rPr>}/{@code <w:rStyle>} и прочее не матчатся по границе имени. */ /** Открывающий/закрывающий тег рана; {@code <w:rPr>}/{@code <w:rStyle>} и прочее не матчатся по границе имени. */
private static final Pattern RUN_TOKEN = Pattern.compile("<w:r(?=[ >/])|</w:r>"); private static final Pattern RUN_TOKEN = Pattern.compile("<w:r(?=[ >/])|</w:r>");
@@ -97,9 +106,6 @@ public final class HiddenTextNormalizer {
private HiddenTextNormalizer() { private HiddenTextNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = HiddenTextNormalizer::normalize;
/** /**
* Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей * Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей
* docx; {@code word/styles.xml}/{@code word/numbering.xml} пропускаются. * docx; {@code word/styles.xml}/{@code word/numbering.xml} пропускаются.
@@ -107,10 +113,10 @@ public final class HiddenTextNormalizer {
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
Set<String> vanishStyles = Set.of(); Set<String> vanishStyles = Set.of();
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) { try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) {
ZipArchiveEntry styles = zf.getEntry("word/styles.xml"); ZipArchiveEntry styles = zf.getEntry(STYLES_PART);
if (styles != null) { if (styles != null) {
vanishStyles = vanishStyles(new String( vanishStyles = vanishStyles(new String(
zf.getInputStream(styles).readAllBytes(), StandardCharsets.UTF_8)); zf.getInputStream(styles).readAllBytes(), StandardCharsets.UTF_8));
@@ -152,7 +158,7 @@ public final class HiddenTextNormalizer {
* @return новая строка либо null, если менять нечего * @return новая строка либо null, если менять нечего
*/ */
static String rewritePart(String name, String xml, Set<String> vanishStyleIds) { static String rewritePart(String name, String xml, Set<String> vanishStyleIds) {
if ("word/styles.xml".equals(name) || "word/numbering.xml".equals(name)) { if (STYLES_PART.equals(name) || NUMBERING_PART.equals(name)) {
return null; return null;
} }
return rewrite(vanishStyleIds, xml); return rewrite(vanishStyleIds, xml);
@@ -309,6 +315,9 @@ public final class HiddenTextNormalizer {
if (hasTruthyVanish(region)) { if (hasTruthyVanish(region)) {
return true; return true;
} }
if (hasExplicitFalsyVanish(region)) {
return false; // явный w:val=false/0/off перекрывает стилевой vanish (§17.7.3)
}
if (!vanishStyleIds.isEmpty()) { if (!vanishStyleIds.isEmpty()) {
Matcher r = RSTYLE.matcher(region); Matcher r = RSTYLE.matcher(region);
if (r.find() && vanishStyleIds.contains(r.group(1))) { if (r.find() && vanishStyleIds.contains(r.group(1))) {
@@ -360,7 +369,7 @@ public final class HiddenTextNormalizer {
String tag = end < 0 ? region.substring(i) : region.substring(i, end + 1); String tag = end < 0 ? region.substring(i) : region.substring(i, end + 1);
Matcher v = VAL_ATTR.matcher(tag); Matcher v = VAL_ATTR.matcher(tag);
if (!v.find()) { if (!v.find()) {
return true; // вал опущен — default true (Part 1 §17.3.2.30) return true; // вал опущен — default true (Part 1 §17.3.2.41)
} }
if (truthy(v.group(1))) { if (truthy(v.group(1))) {
return true; return true;
@@ -372,11 +381,21 @@ public final class HiddenTextNormalizer {
return false; return false;
} }
/** truthy по Part 1 §17.18.69 ST_OnOff: false/0/off — выключено, прочее — включено. */ /** truthy по Part 1 §22.9.2.7 ST_OnOff: false/0/off — выключено, прочее — включено. */
private static boolean truthy(String val) { private static boolean truthy(String val) {
return !"false".equalsIgnoreCase(val) && !"0".equals(val) && !"off".equalsIgnoreCase(val); return !"false".equalsIgnoreCase(val) && !"0".equals(val) && !"off".equalsIgnoreCase(val);
} }
/** Явный falsy {@code w:vanish} (val=false/0/off) — перекрытие стилевого. */
private static final Pattern FALSY_VANISH =
Pattern.compile("<w:vanish\\b[^>]*w:val=\"(?:false|0|off)\"",
Pattern.CASE_INSENSITIVE);
/** Есть ли в регионе явный falsy {@code w:vanish} (val=false/0/off). */
private static boolean hasExplicitFalsyVanish(String region) {
return FALSY_VANISH.matcher(region).find();
}
/** Есть ли защищённый элемент в содержимом рана [from, to). */ /** Есть ли защищённый элемент в содержимом рана [from, to). */
private static boolean hasProtected(String xml, int from, int to) { private static boolean hasProtected(String xml, int from, int to) {
for (String p : PROTECTED) { for (String p : PROTECTED) {
@@ -27,9 +27,10 @@ import java.util.zip.ZipOutputStream;
* в невидимый DejaVu — FOP рисует «тофу» прямо в тексте.</li> * в невидимый DejaVu — FOP рисует «тофу» прямо в тексте.</li>
* </ul> * </ul>
* *
* Zero-width знаки, значимые для shaping и переносов (U+00A0, U+00AD, * NBSP (U+00A0, ширина пробела — не zero-width) и zero-width знаки, значимые
* U+200B, U+200C, U+200D), НЕ трогаем: во всех шрифтах бандла они * для shaping и переносов (U+00AD, U+200B, U+200C, U+200D), НЕ трогаем:
* нулевой ширины и пустых строк не создают. * во всех шрифтах бандла NBSP широк, остальное нулевой ширины, и ни то ни
* другое пустых строк не создаёт.
* *
* Правим байты zip до JAXB-разбора, как остальные нормализаторы; запускается * Правим байты zip до JAXB-разбора, как остальные нормализаторы; запускается
* до {@link GlyphCoverageNormalizer}, чтобы тот не искал шрифт для уже * до {@link GlyphCoverageNormalizer}, чтобы тот не искал шрифт для уже
@@ -38,7 +39,7 @@ import java.util.zip.ZipOutputStream;
* Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines, * Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines,
* WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn. * WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn.
*/ */
public final class InvisibleCharNormalizer { final class InvisibleCharNormalizer {
/** /**
* Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029), * Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029),
@@ -86,9 +87,6 @@ public final class InvisibleCharNormalizer {
private InvisibleCharNormalizer() { private InvisibleCharNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = InvisibleCharNormalizer::normalize;
/** /**
* Вырезает невидимые символы из текстовых узлов XML-частей docx * Вырезает невидимые символы из текстовых узлов XML-частей docx
* (word/*.xml). * (word/*.xml).
@@ -96,7 +94,7 @@ public final class InvisibleCharNormalizer {
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -0,0 +1,270 @@
package ru.pjandro.wordpdf.internal;
import ru.pjandro.wordpdf.internal.chart.MathModel;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* Байтовый скан формул OMML (§22.1): блок {@code m:oMathPara}/{@code m:oMath},
* содержащий math-элемент вне {@link MathModel#SUPPORTED}, заменяется раном с
* конкатенацией текста {@code m:t} (как штатный фолбэк docx4j
* {@code XsltFOFunctions.mathText}) — формула видна текстом, а не теряется.
* Регрессия — WordPdfConverterTest#ommlUnsupported_degradesToText,
* юниты — MathFallbackNormalizerTest.
*
* <p>Зачем скан до загрузки docx4j: собственный растер формул
* ({@code MathModel}/{@code MathRenderer} в {@code DrawingPreRenderer})
* уронил бы unsupported-конструкцию в {@code MathUnsupportedException} и
* деградировал тем же текстом — но скан даёт детерминизм «формула целиком
* текстом» для байтового уровня пайплайна и не зависит от JAXB-биндинга.
* Рантайм-деградация остаётся второй сетью (биндинг может не смонтировать
* неизвестный элемент, который скан увидел).
*
* <p>Скан namespace-aware: префиксы, привязанные к math-URI на корневом
* элементе (+ переопределения {@code xmlns} внутри блока), — unsupported
* проверяется только для тегов в math-namespace; префиксы чужих namespace'ов
* ( {@code w:rPr} внутри рана формулы) игнорируются. Непривязанный/отсутствующий
* map объявлений при наличии {@code :oMath} — консервативная обработка «как
* math» (риск потерять контент при недобитом биндинге сильнее избыточной
* деградации).
*
* <p>Позиция в цепочке — шестое правило, перед GlyphCoverage: flatten даёт
* обычный текст ранов, который следующий рерайт покрывает кириллицей бандла
* (раньше формулы с {@code &#x043C;} теряли глифы именно из-за порядка —
* GlyphCoverage не видел текст внутри OMML). Блок para заменяется первым:
* {@code m:oMathPara} содержит {@code m:oMath}, иначе остался бы
* несбалансированный каркас.
*/
final class MathFallbackNormalizer {
/** Закрывающий символ открывающего тега (скан конца корня формулы). */
private static final char TAG_END = '>';
/** Math-namespace OMML (§22.1). */
private static final String MATH_NS =
"http://schemas.openxmlformats.org/officeDocument/2006/math";
/** Объявление {@code xmlns:prefix="uri"} (значение без кавычек). */
private static final Pattern XMLNS = Pattern.compile(
"xmlns:([A-Za-z_][\\w.-]*)=\"([^\"]*)\"");
/** Начало блока формулы; префикс обязателен (без него {@code :oMath} нет). */
private static final Pattern MATH_BLOCK = Pattern.compile(
"<([A-Za-z_][\\w.-]*):oMath(Para)?(?=[\\s/>])");
/** Элементный тег с префиксом {@code <p:name>} / {@code </p:name>}. */
private static final Pattern PREFIXED_TAG = Pattern.compile(
"</?([A-Za-z_][\\w.-]*):([A-Za-z_][\\w.-]*)");
/** Текстовый узел {@code <p:t>}; содержимое — уже экранированный XML. */
private static final Pattern MATH_TEXT = Pattern.compile(
"<([A-Za-z_][\\w.-]*):t(?:\\s[^>]*)?>(.*?)</\\1:t>", Pattern.DOTALL);
private MathFallbackNormalizer() {
}
/**
* Рерайт одной XML-части: unsupported-формулы → текст. Формул нет /
* все поддерживаются / ничего не изменилось → {@code null}
* (пайплайн отдаёт тот же массив).
*/
static String rewrite(String xml) {
if (!xml.contains(":oMath")) {
return null;
}
Map<String, String> rootNs = rootNamespaces(xml);
StringBuilder out = new StringBuilder();
int pos = 0;
boolean changed = false;
Matcher m = MATH_BLOCK.matcher(xml);
int search = 0;
while (m.find(search)) {
String prefix = m.group(1);
boolean para = m.group(2) != null;
int start = m.start();
int tagEnd = tagEnd(xml, start);
if (tagEnd < 0) {
break; // незакрытый тег — дело валидатора, скан останавливаем
}
Map<String, String> ns = mergedNamespaces(rootNs, xml.substring(start, tagEnd));
if (!isMath(ns, prefix)) {
search = tagEnd;
continue; // чужой namespace — не формула
}
int blockEnd;
int before = tagEnd - 2;
while (before > start && Character.isWhitespace(xml.charAt(before))) {
before--;
}
boolean selfClosing = xml.charAt(before) == '/';
if (selfClosing) {
blockEnd = tagEnd;
} else {
String closing = "</" + prefix + ":oMath" + (para ? "Para" : "") + ">";
int close = xml.indexOf(closing, tagEnd);
if (close < 0) {
break; // битый каркас — валидатор его и отвергнет
}
blockEnd = close + closing.length();
}
String block = xml.substring(start, blockEnd);
if (hasUnsupported(ns, block)) {
out.append(xml, pos, start).append(run(text(ns, block)));
pos = blockEnd;
changed = true;
search = blockEnd;
continue;
}
search = tagEnd;
}
if (!changed) {
return null;
}
return out.append(xml, pos, xml.length()).toString();
}
/**
* Объявления {@code xmlns:} фактического корневого элемента: пролог
* ({@code <?xml ...?>}, комментарии, DOCTYPE) пропускается — иначе
* карта осталась бы пустой на реальном XML-файле части, а пустая карта
* консервативно считает каждый префикс math-тегом и срезает боевые
* формулы (внутри {@code m:r}/{@code m:ctrlPr} Word пишет
* {@code w:rPr}/{@code w:rFonts} — имена вне SUPPORTED).
*/
private static Map<String, String> rootNamespaces(String xml) {
Map<String, String> map = new HashMap<>();
int pos = 0;
while (pos < xml.length()) {
int open = xml.indexOf('<', pos);
if (open < 0) {
return map;
}
if (xml.startsWith("<?", open)) {
int end = xml.indexOf("?>", open);
pos = end < 0 ? xml.length() : end + 2;
continue;
}
if (xml.startsWith("<!--", open)) {
int end = xml.indexOf("-->", open);
pos = end < 0 ? xml.length() : end + 3;
continue;
}
if (xml.startsWith("<!", open)) {
int end = xml.indexOf('>', open);
pos = end < 0 ? xml.length() : end + 1;
continue;
}
int end = tagEnd(xml, open);
if (end < 0) {
return map;
}
Matcher m = XMLNS.matcher(xml.substring(open, end));
while (m.find()) {
map.put(m.group(1), m.group(2));
}
return map;
}
return map;
}
/** Корневые объявления + переопределения из заголовка блока. */
private static Map<String, String> mergedNamespaces(Map<String, String> root,
String openTag) {
Matcher m = XMLNS.matcher(openTag);
if (!m.find()) {
return root;
}
Map<String, String> map = new HashMap<>(root);
m.reset();
while (m.find()) {
map.put(m.group(1), m.group(2));
}
return map;
}
/**
* Привязан ли префикс к math-namespace: явная привязка — да; привязка к
* другому URI — нет; префикс не объявлен нигде — да (консервативно, см.
* javadoc класса), если только вообще нет ни одного объявления xmlns
* (тогда это не XML с map префиксов, а мусор — тоже «как math»).
*/
private static boolean isMath(Map<String, String> ns, String prefix) {
String bound = ns.get(prefix);
if (MATH_NS.equals(bound)) {
return true;
}
return bound == null;
}
/** Есть ли в блоке тег math-namespace вне {@link MathModel#SUPPORTED}. */
private static boolean hasUnsupported(Map<String, String> ns, String block) {
List<String> mathPrefixes = new ArrayList<>();
for (Map.Entry<String, String> e : ns.entrySet()) {
if (MATH_NS.equals(e.getValue())) {
mathPrefixes.add(e.getKey());
}
}
Matcher m = PREFIXED_TAG.matcher(block);
while (m.find()) {
String prefix = m.group(1);
String name = m.group(2);
boolean mathTag = mathPrefixes.contains(prefix)
|| (mathPrefixes.isEmpty() && !ns.containsKey(prefix));
if (mathTag && !MathModel.SUPPORTED.contains(name)) {
return true;
}
}
return false;
}
/** Текст формулы: конкатенация {@code m:t} math-префиксов (как mathText). */
private static String text(Map<String, String> ns, String block) {
Set<String> mathPrefixes = new HashSet<>();
for (Map.Entry<String, String> e : ns.entrySet()) {
if (MATH_NS.equals(e.getValue())) {
mathPrefixes.add(e.getKey());
}
}
StringBuilder sb = new StringBuilder();
Matcher m = MATH_TEXT.matcher(block);
while (m.find()) {
String prefix = m.group(1);
if (mathPrefixes.contains(prefix)
|| (mathPrefixes.isEmpty() && !ns.containsKey(prefix))) {
sb.append(m.group(2));
}
}
return sb.toString();
}
/** Конец открывающего тега (индекс после {@code >}), кавычки-осведомлённый. */
private static int tagEnd(String xml, int start) {
char quote = 0;
for (int i = start + 1; i < xml.length(); i++) {
char c = xml.charAt(i);
if (quote != 0) {
if (c == quote) {
quote = 0;
}
} else if (c == '"' || c == '\'') {
quote = c;
} else if (c == TAG_END) {
return i + 1;
}
}
return -1;
}
/** Ран с текстом формулы; пустая формула удаляется. */
private static String run(String text) {
return text.isEmpty() ? ""
: "<w:r><w:t xml:space=\"preserve\">" + text + "</w:t></w:r>";
}
}
@@ -16,7 +16,8 @@ import java.util.zip.ZipOutputStream;
* *
* Word рисует после номера лейбла разделитель по {@code w:suff}: tab — * Word рисует после номера лейбла разделитель по {@code w:suff}: tab —
* табуляция до позиционного отступа, space — обычный пробел, nothing — ничего * табуляция до позиционного отступа, space — обычный пробел, nothing — ничего
* (Part 1 §17.3.1.28). docx4j/export-fo разделитель не эмитит вовсе: в FO * (Part 1 §17.9.28, тип — ST_LevelSuffix §17.18.46). docx4j/export-fo
* разделитель не эмитит вовсе: в FO
* уходит только текст лейбла («1.»), хинт {@code docx4j:label-suffix} — * уходит только текст лейбла («1.»), хинт {@code docx4j:label-suffix} —
* заготовка без обработчика (дамп n4.fo аудита раскладки). Для suff=tab это * заготовка без обработчика (дамп n4.fo аудита раскладки). Для suff=tab это
* отдельный Class C-остаток (нужна per-item ширина), а suff=space чинится * отдельный Class C-остаток (нужна per-item ширина), а suff=space чинится
@@ -29,7 +30,7 @@ import java.util.zip.ZipOutputStream;
* заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing — * заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing —
* не трогаем. Нечего менять → тот же массив. * не трогаем. Нечего менять → тот же массив.
*/ */
public final class NumberingSuffixNormalizer { final class NumberingSuffixNormalizer {
private static final Pattern SUFF_SPACE = private static final Pattern SUFF_SPACE =
Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>"); Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>");
@@ -38,16 +39,13 @@ public final class NumberingSuffixNormalizer {
private NumberingSuffixNormalizer() { private NumberingSuffixNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = NumberingSuffixNormalizer::normalize;
/** /**
* Дописывает пробел в lvlText у уровней с suff=space. * Дописывает пробел в lvlText у уровней с suff=space.
* *
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -1,9 +1,10 @@
package ru.pjandro.wordpdf.internal; package ru.pjandro.wordpdf.internal;
import ru.pjandro.wordpdf.DrawingFoundException; import ru.pjandro.wordpdf.OleFoundException;
import java.io.ByteArrayOutputStream; import java.io.ByteArrayOutputStream;
import java.io.IOException; import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets; import java.nio.charset.StandardCharsets;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.HashMap; import java.util.HashMap;
@@ -41,13 +42,14 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
* по ECMA-376 §15.2.10 у каждого внедрённого объекта обязан быть «associated * по ECMA-376 §15.2.10 у каждого внедрённого объекта обязан быть «associated
* image, which appears in the document as a placeholder» — именно его показывает * image, which appears in the document as a placeholder» — именно его показывает
* Word вместо объекта, — поэтому {@code w:object} заменяется его статичным * Word вместо объекта, — поэтому {@code w:object} заменяется его статичным
* представлением (картинкой-плейсхолдером, §17.3.3.3); без плейсхолдера блок * представлением (картинкой-плейсхолдером, §17.3.3.19; картинка — §17.3.3.9);
* без плейсхолдера блок
* удаляется. OLE-бинарники при этом никогда не читаются — байты только * удаляется. OLE-бинарники при этом никогда не читаются — байты только
* удаляются, так что содержимое объекта (вплоть до враждебного архива) на * удаляются, так что содержимое объекта (вплоть до враждебного архива) на
* вывод не влияет.</p> * вывод не влияет.</p>
* *
* <p>Отличие от остальных нормализаторов пакета: принимает флаг * <p>Отличие от остальных нормализаторов пакета: принимает флаг
* {@code errorOnOle} и умеет бросать {@link DrawingFoundException} * {@code errorOnOle} и умеет бросать {@link OleFoundException}
* (при включённом флаге документ отвергается вместо вычистки), и правит * (при включённом флаге документ отвергается вместо вычистки), и правит
* не только {@code word/*.xml}, но и {@code [Content_Types].xml} с * не только {@code word/*.xml}, но и {@code [Content_Types].xml} с
* {@code *.rels}. Хука {@code rewrite(String)} нет — нормализатор * {@code *.rels}. Хука {@code rewrite(String)} нет — нормализатор
@@ -74,6 +76,9 @@ public final class OleObjectNormalizer {
/** Сегмент «наверх» в относительном Target rels. */ /** Сегмент «наверх» в относительном Target rels. */
private static final String PARENT_DIR = ".."; private static final String PARENT_DIR = "..";
/** Сегмент «текущий каталог» в относительном Target rels. */
private static final String CURRENT_DIR = ".";
private static final Pattern DEFAULT_TYPE = Pattern.compile( private static final Pattern DEFAULT_TYPE = Pattern.compile(
"<Default\\b[^>]*\\bExtension=\"([^\"]*)\"[^>]*\\bContentType=\"([^\"]*)\"[^>]*/>" "<Default\\b[^>]*\\bExtension=\"([^\"]*)\"[^>]*\\bContentType=\"([^\"]*)\"[^>]*/>"
+ "|<Default\\b[^>]*\\bContentType=\"([^\"]*)\"[^>]*\\bExtension=\"([^\"]*)\"[^>]*/>"); + "|<Default\\b[^>]*\\bContentType=\"([^\"]*)\"[^>]*\\bExtension=\"([^\"]*)\"[^>]*/>");
@@ -135,9 +140,46 @@ public final class OleObjectNormalizer {
private static final Logger LOG = Logger.getLogger(OleObjectNormalizer.class.getName()); private static final Logger LOG = Logger.getLogger(OleObjectNormalizer.class.getName());
/** Детект `w:object` по байтам: ASCII-литерал в UTF-8 не может
* встретиться внутри многобайтовой последовательности, поэтому поиск
* по сырым байтам эквивалентен `new String(...).contains(...)`. */
private static final byte[] OBJECT_NEEDLE = "<w:object".getBytes(StandardCharsets.US_ASCII);
private OleObjectNormalizer() { private OleObjectNormalizer() {
} }
/**
* Поиск ASCII-литерала в потоке окном 8 KiB с перекрытием
* {@code needle.length - 1} байт на границе окна — без материализации
* всей XML-части (document.xml десятки МБ дублировались в память ради
* поиска 9-байтного литерала).
*/
private static boolean containsAscii(InputStream in, byte[] needle) throws IOException {
try (in) {
byte[] window = new byte[8192];
int carried = 0; // байт перенесённого хвоста предыдущего окна
int read;
while ((read = in.read(window, carried, window.length - carried)) > 0) {
int limit = carried + read;
for (int i = 0; i + needle.length <= limit; i++) {
boolean hit = true;
for (int j = 0; j < needle.length; j++) {
if (window[i + j] != needle[j]) {
hit = false;
break;
}
}
if (hit) {
return true;
}
}
carried = Math.min(needle.length - 1, limit);
System.arraycopy(window, limit - carried, window, 0, carried);
}
return false;
}
}
/** /**
* Вычистляет из docx OLE-объекты: бинарные `.bin`-части с OLE-типом (или * Вычистляет из docx OLE-объекты: бинарные `.bin`-части с OLE-типом (или
* ложным XML-типом), ссылки на них и oleObject-ссылки (включая External) в * ложным XML-типом), ссылки на них и oleObject-ссылки (включая External) в
@@ -167,8 +209,10 @@ public final class OleObjectNormalizer {
if (contentTypes == null) { if (contentTypes == null) {
return docx; return docx;
} }
String ctXml = new String(zf.getInputStream(contentTypes).readAllBytes(), String ctXml;
StandardCharsets.UTF_8); try (InputStream in = zf.getInputStream(contentTypes)) {
ctXml = new String(in.readAllBytes(), StandardCharsets.UTF_8);
}
Map<String, String> defaults = defaultTypes(ctXml); Map<String, String> defaults = defaultTypes(ctXml);
Map<String, String> overrides = overrideTypes(ctXml); Map<String, String> overrides = overrideTypes(ctXml);
@@ -183,8 +227,7 @@ public final class OleObjectNormalizer {
oleParts.add(name); oleParts.add(name);
} }
} else if (!hasObjectMarkup && name.startsWith("word/") && name.endsWith(".xml") } else if (!hasObjectMarkup && name.startsWith("word/") && name.endsWith(".xml")
&& new String(zf.getInputStream(entry).readAllBytes(), && containsAscii(zf.getInputStream(entry), OBJECT_NEEDLE)) {
StandardCharsets.UTF_8).contains("<w:object")) {
// сам w:object — уже OLE: без bin-части он всё равно роняет docx4j // сам w:object — уже OLE: без bin-части он всё равно роняет docx4j
// (NPE chunkType is null) и обязан быть переписан // (NPE chunkType is null) и обязан быть переписан
hasObjectMarkup = true; hasObjectMarkup = true;
@@ -194,7 +237,7 @@ public final class OleObjectNormalizer {
return docx; return docx;
} }
if (errorOnOle) { if (errorOnOle) {
throw new DrawingFoundException(DrawingFoundException.Kind.OLE); throw new OleFoundException();
} }
for (String part : oleParts) { for (String part : oleParts) {
LOG.warning("Удалён OLE-объект: " + part); LOG.warning("Удалён OLE-объект: " + part);
@@ -209,7 +252,10 @@ public final class OleObjectNormalizer {
if (oleParts.contains(name)) { if (oleParts.contains(name)) {
continue; continue;
} }
byte[] data = zf.getInputStream(entry).readAllBytes(); byte[] data;
try (InputStream in = zf.getInputStream(entry)) {
data = in.readAllBytes();
}
if (name.endsWith(".rels")) { if (name.endsWith(".rels")) {
String fixed = stripRels( String fixed = stripRels(
new String(data, StandardCharsets.UTF_8), name, oleParts); new String(data, StandardCharsets.UTF_8), name, oleParts);
@@ -222,7 +268,7 @@ public final class OleObjectNormalizer {
if (fixed != null) { if (fixed != null) {
data = fixed.getBytes(StandardCharsets.UTF_8); data = fixed.getBytes(StandardCharsets.UTF_8);
} }
} else if (name.equals(CONTENT_TYPES_ENTRY)) { } else if (CONTENT_TYPES_ENTRY.equals(name)) {
String fixed = stripOverrides( String fixed = stripOverrides(
new String(data, StandardCharsets.UTF_8), oleParts); new String(data, StandardCharsets.UTF_8), oleParts);
if (fixed != null) { if (fixed != null) {
@@ -336,7 +382,7 @@ public final class OleObjectNormalizer {
} }
} }
for (String s : target.split("/")) { for (String s : target.split("/")) {
if (s.isEmpty() || ".".equals(s)) { if (s.isEmpty() || CURRENT_DIR.equals(s)) {
continue; continue;
} }
if (PARENT_DIR.equals(s)) { if (PARENT_DIR.equals(s)) {
@@ -352,7 +398,7 @@ public final class OleObjectNormalizer {
/** /**
* Заменяет в word/*.xml каждый w:object его статичным представлением * Заменяет в word/*.xml каждый w:object его статичным представлением
* (плейсхолдером, ECMA-376 §15.2.10/§17.3.3.3): блок с `w:control` * (плейсхолдером, ECMA-376 §15.2.10/§17.3.3.19): блок с `w:control`
* (ActiveX) удаляется целиком — property bag всё равно остаётся сиротой; * (ActiveX) удаляется целиком — property bag всё равно остаётся сиротой;
* блок с `w:drawing` (ветка mc:Choice) заменяется этим drawing дословно; * блок с `w:drawing` (ветка mc:Choice) заменяется этим drawing дословно;
* блок с `v:imagedata r:id` заменяется inline-DrawingML на ту же * блок с `v:imagedata r:id` заменяется inline-DrawingML на ту же
@@ -10,8 +10,9 @@ import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream; import java.util.zip.ZipOutputStream;
/** /**
* Разбор руби-разметки ({@code w:rubyBase}/{@code w:rt}/{@code w:rubyPr}, * Разбор руби-разметки ({@code w:ruby}/{@code w:rubyBase}/{@code w:rt}/
* Part 1 §17.3.3.19/.20/.21) в байтах до загрузки docx4j. * {@code w:rubyPr}/{@code w:rubyAlign}, Part 1 §17.3.3.25/.27/.24/.28/.26)
* в байтах до загрузки docx4j.
* *
* <p>Джинябиндованные схемы docx4j 17.3.2 {@code w:rubyBase}/{@code w:rt} * <p>Джинябиндованные схемы docx4j 17.3.2 {@code w:rubyBase}/{@code w:rt}
* в {@code w:r} <b>не содержат</b> (unmarshaller сообщает «unexpected * в {@code w:r} <b>не содержат</b> (unmarshaller сообщает «unexpected
@@ -20,20 +21,22 @@ import java.util.zip.ZipOutputStream;
* (в отличие от {@code w:moveFrom}/{@code w:moveTo}/{@code w:bdo}/{@code w:dir}, * (в отличие от {@code w:moveFrom}/{@code w:moveTo}/{@code w:bdo}/{@code w:dir},
* которые схема знает). Единственный слой починки — байтовый нормализатор. * которые схема знает). Единственный слой починки — байтовый нормализатор.
* *
* <p>Деградация принята: база ({@code w:rubyBase}/{@code w:rubyBaseText}) * <p>Деградация принята: база ({@code w:rubyBase}) разворачивается в обычные
* разворачивается в обычные раны ранa — текст печатается; надстрочница * раны ранa — текст печатается; надстрочница ({@code w:rt}) и форматирование
* ({@code w:rt}) и форматирование руби ({@code w:rubyPr}, {@code w:rubyAlign}) * руби ({@code w:rubyPr}, {@code w:rubyAlign}) удаляются вместе с содержимым
* удаляются вместе с содержимым — ruby-разметки в XSL-FO у FOP нет, а потеря * — ruby-разметки в XSL-FO у FOP нет, а потеря текста хуже потери аннотации.
* текста хуже потери аннотации. * Снимается и обёртка {@code w:ruby}: схемно-валидная разметка (транзишнл
* CT_R: {@code w:r} → {@code w:ruby} → rubyPr/rt/rubyBase, wml.xsd) иначе
* достаёт catch-all-шаблону XSLT и база теряется молча.
* *
* <p>В конвейере подключается десятым рерайтом в {@link DocxRewritePipeline} * <p>В конвейере подключается одиннадцатым рерайтом в {@link DocxRewritePipeline}
* (после Hidden; порядок 1–8 не перенумеровать); в * (после Hidden; порядок правил фиксирован в {@code DocxRewritePipeline}); в
* {@code WordPdfConverter#normalizers} напрямую не вызывается, как и * {@code WordPdfConverter#normalizers} напрямую не вызывается, как и
* остальные rewrite-нормализаторы. * остальные rewrite-нормализаторы.
* *
* <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted. * <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted.
*/ */
public final class RubyNormalizer { final class RubyNormalizer {
private RubyNormalizer() { private RubyNormalizer() {
} }
@@ -46,18 +49,21 @@ public final class RubyNormalizer {
private static final Pattern RUBY_PR_BLOCK = private static final Pattern RUBY_PR_BLOCK =
Pattern.compile("<w:rubyPr(?:\\s[^>]*)?(?:/>|>.*?</w:rubyPr>)", Pattern.DOTALL); Pattern.compile("<w:rubyPr(?:\\s[^>]*)?(?:/>|>.*?</w:rubyPr>)", Pattern.DOTALL);
/** Одиночный {@code w:rubyPr}. */ /** Одиночный {@code w:rubyAlign}. */
private static final Pattern RUBY_ALIGN = private static final Pattern RUBY_ALIGN =
Pattern.compile("<w:rubyAlign(?:\\s[^>]*)?(?:/>|>\\s*</w:rubyAlign>)", Pattern.DOTALL); Pattern.compile("<w:rubyAlign(?:\\s[^>]*)?(?:/>|>\\s*</w:rubyAlign>)", Pattern.DOTALL);
private static final Pattern RUBY_BASE_OPEN = private static final Pattern RUBY_BASE_OPEN =
Pattern.compile("<w:rubyBase(?:\\s[^>]*)?>"); Pattern.compile("<w:rubyBase(?:\\s[^>]*)?>");
private static final Pattern RUBY_BASE_TEXT_OPEN =
Pattern.compile("<w:rubyBaseText(?:\\s[^>]*)?>"); /** Обёртка {@code w:ruby} (снимается: ран разворачивается в обычные раны). */
private static final Pattern RUBY_OPEN =
Pattern.compile("<w:ruby(?:\\s[^>]*)?>");
private static final String RUBY_CLOSE = "</w:ruby>";
/** /**
* Рерайт одной XML-строки: разворачивает {@code w:rubyBase}/ * Рерайт одной XML-строки: разворачивает {@code w:rubyBase}, снимает
* {@code w:rubyBaseText}, вырезает {@code w:rt}/{@code w:rubyPr}/ * обёртку {@code w:ruby}, вырезает {@code w:rt}/{@code w:rubyPr}/
* {@code w:rubyAlign}. Руби-токенов нет / ничего не поменялось → {@code null}. * {@code w:rubyAlign}. Руби-токенов нет / ничего не поменялось → {@code null}.
*/ */
static String rewrite(String xml) { static String rewrite(String xml) {
@@ -67,10 +73,10 @@ public final class RubyNormalizer {
String out = RT_BLOCK.matcher(xml).replaceAll(""); String out = RT_BLOCK.matcher(xml).replaceAll("");
out = RUBY_PR_BLOCK.matcher(out).replaceAll(""); out = RUBY_PR_BLOCK.matcher(out).replaceAll("");
out = RUBY_ALIGN.matcher(out).replaceAll(""); out = RUBY_ALIGN.matcher(out).replaceAll("");
out = RUBY_BASE_TEXT_OPEN.matcher(out).replaceAll("");
out = out.replace("</w:rubyBaseText>", "");
out = RUBY_BASE_OPEN.matcher(out).replaceAll(""); out = RUBY_BASE_OPEN.matcher(out).replaceAll("");
out = out.replace("</w:rubyBase>", ""); out = out.replace("</w:rubyBase>", "");
out = RUBY_OPEN.matcher(out).replaceAll("");
out = out.replace(RUBY_CLOSE, "");
return out.equals(xml) ? null : out; return out.equals(xml) ? null : out;
} }
@@ -78,7 +84,7 @@ public final class RubyNormalizer {
* Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере * Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере
* {@link DocxRewritePipeline} вызывает {@link #rewrite} в общем проходе. * {@link DocxRewritePipeline} вызывает {@link #rewrite} в общем проходе.
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -26,14 +26,17 @@ import java.util.zip.ZipOutputStream;
* {@code w14:fillToRect w14:t="130%"} — JAXB падает на * {@code w14:fillToRect w14:t="130%"} — JAXB падает на
* {@code NumberFormatException: Not a number: 130%};</li> * {@code NumberFormatException: Not a number: 130%};</li>
* <li>текстовые проценты в {@code wp14:pctWidth}/{@code wp14:pctHeight};</li> * <li>текстовые проценты в {@code wp14:pctWidth}/{@code wp14:pctHeight};</li>
* <li>границы и отступы в элементах {@code w:start}/{@code w:end} * <li>границы и отступы в элементах {@code w:start}/{@code w:end} — в
* (в transitional они называются {@code w:left}/{@code w:right}) — * strict-схеме это единственные имена, transitional-схема допускает
* JAXB сообщает «unexpected element» и границы теряются;</li> * обе пары детей (wml.xsd CT_TcMar/CT_TblCellMar), но strict-часть их
* не пишет — JAXB transitional-модели сообщает «unexpected element»
* и границы теряются;</li>
* <li>атрибуты {@code w:start}/{@code w:end} у {@code w:ind} и значения * <li>атрибуты {@code w:start}/{@code w:end} у {@code w:ind} и значения
* {@code start}/{@code end} у {@code w:jc}/{@code w:tab} — в strict-модели * {@code start}/{@code end} у {@code w:jc}/{@code w:tab} — в strict-модели
* это единственные имена, а transitional-модель docx4j их не принимает * это единственные имена, а transitional-модель docx4j их не принимает
* (значения {@code w:tab} — и подавно: enum {@code STTabJc} в docx4j * (значения {@code w:tab} — и подавно: enum {@code STTabJc} в docx4j
* 17.3.2 содержит только left/right).</li> * 17.3.2 содержит только left/center/right; в спековом ST_TabJc
* §17.18.84 start/end есть, но JAXB-enum их не принимает).</li>
* </ul> * </ul>
* *
* <p>Полный strict→transitional рерайт не делается: mc-preprocessor уже * <p>Полный strict→transitional рерайт не делается: mc-preprocessor уже
@@ -72,12 +75,14 @@ import java.util.zip.ZipOutputStream;
* RTL; ST_Jc §17.18.44); RTL вне контура конвейера (FOP без complex-script, * RTL; ST_Jc §17.18.44); RTL вне контура конвейера (FOP без complex-script,
* direction docx4j не выставляет — start и так рендерился как left).</li> * direction docx4j не выставляет — start и так рендерился как left).</li>
* <li>значения {@code start}/{@code end} у {@code w:tab} правятся всегда * <li>значения {@code start}/{@code end} у {@code w:tab} правятся всегда
* (enum без start/end).</li> * (enum {@code STTabJc} docx4j — left/center/right, без start/end;
* спека ST_TabJc §17.18.84 их содержит, но JAXB-биндинг их не
* принимает).</li>
* </ul> * </ul>
* *
* Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected. * Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected.
*/ */
public final class StrictOoxmlNormalizer { final class StrictOoxmlNormalizer {
/** Открывающий тег элемента префикса {@code a:} (DrawingML). */ /** Открывающий тег элемента префикса {@code a:} (DrawingML). */
private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>"); private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>");
@@ -121,9 +126,6 @@ public final class StrictOoxmlNormalizer {
private StrictOoxmlNormalizer() { private StrictOoxmlNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = StrictOoxmlNormalizer::normalize;
/** /**
* Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который * Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который
* разбирает JAXB-модель transitional (детали — в javadoc класса). * разбирает JAXB-модель transitional (детали — в javadoc класса).
@@ -131,7 +133,7 @@ public final class StrictOoxmlNormalizer {
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -219,13 +221,14 @@ public final class StrictOoxmlNormalizer {
/** /**
* Атрибуты {@code w:start→w:left}/{@code w:end→w:right} только внутри * Атрибуты {@code w:start→w:left}/{@code w:end→w:right} только внутри
* открывающего тега {@code w:ind} (MS-OI29500 §2.1.174a: start/end как * открывающего тега {@code w:ind} (MS-OI29500 §2.1.44 (ind) плюс
* псевдонимы left/right в strict — единственный носитель w:ind) и только * strict wml.xsd: {@code CT_Ind} знает только start/end — единственный
* носитель w:ind в strict) и только
* при отсутствии в нём {@code w:left}/{@code w:right}: CT_Ind * при отсутствии в нём {@code w:left}/{@code w:right}: CT_Ind
* (transitional) допускает обе пары, дубль атрибута — не well-formed * (transitional) допускает обе пары, дубль атрибута — не well-formed
* XML; литеральный текст {@code w:val}-вида в {@code w:t} не * XML; литеральный текст {@code w:val}-вида в {@code w:t} не
* затрагивается. У {@code w:pgNumType} атрибут {@code w:start} — старт * затрагивается. У {@code w:pgNumType} атрибут {@code w:start} — старт
* нумерации страниц, легален в transitional (Part 1 §17.13.7), — не * нумерации страниц, легален в transitional (Part 1 §17.6.12), — не
* трогается (регрессия — pgNumTypeStartAttrUntouched). * трогается (регрессия — pgNumTypeStartAttrUntouched).
*/ */
private static String renameStartEndAttrs(String xml) { private static String renameStartEndAttrs(String xml) {
@@ -22,8 +22,8 @@ import java.util.zip.ZipOutputStream;
* {@code <w:lvlText w:val="&#xF0A7;"/>} + {@code w:rFonts w:ascii="Wingdings"} * {@code <w:lvlText w:val="&#xF0A7;"/>} + {@code w:rFonts w:ascii="Wingdings"}
* — это «▪», а тот же код в Symbol — «♣». Экспорт docx4j в XSL-FO эти * — это «▪», а тот же код в Symbol — «♣». Экспорт docx4j в XSL-FO эти
* шрифты не знает: код уходит в fallback-семейство, глифа там нет, и FOP * шрифты не знает: код уходит в fallback-семейство, глифа там нет, и FOP
* рисует {@code .notdef} — в PDF решётку «#» (регрессия: * рисует {@code .notdef} — в PDF решётку «#».
* {@code WordPdfConverterTest#symbolFonts_bulletsAreNotHash}). * Регрессия — WordPdfConverterTest#symbolFonts_bulletsAreNotHash.
* *
* Делаем то же, что Word: код из PUA заменяем его Unicode-эквивалентом, * Делаем то же, что Word: код из PUA заменяем его Unicode-эквивалентом,
* а имя шрифта — на fallback-семейство (в нём этих глифов достаточно). * а имя шрифта — на fallback-семейство (в нём этих глифов достаточно).
@@ -42,7 +42,7 @@ import java.util.zip.ZipOutputStream;
* *
* Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора. * Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора.
*/ */
public final class SymbolFontNormalizer { final class SymbolFontNormalizer {
/** Семейство, на которое заменяются символьные шрифты (есть в jar). */ /** Семейство, на которое заменяются символьные шрифты (есть в jar). */
static final String REPLACEMENT_FAMILY = "DejaVu Sans"; static final String REPLACEMENT_FAMILY = "DejaVu Sans";
@@ -51,8 +51,9 @@ public final class SymbolFontNormalizer {
* Имя шрифта (lowercase) -> таблица из 256 слотов по 4 hex-цифры: * Имя шрифта (lowercase) -> таблица из 256 слотов по 4 hex-цифры:
* младший байт кода из PUA -> Unicode-код цели (0 — соответствия нет). * младший байт кода из PUA -> Unicode-код цели (0 — соответствия нет).
* Источник — SymbolMapper из docx4j 17.x; сгенерировано, см. javadoc * Источник — SymbolMapper из docx4j 17.x; сгенерировано, см. javadoc
* класса. Коды вне U+F000–U+F0FF (обычная ASCII-часть символьного * класса. Прямые коды {@code w:sym} (≤0xFF, вне PUA) маппятся по той же
* шрифта) не переписываются. * таблице как индекс символной cmap (§17.3.3.30); слот без маппинга, код
* &gt;0xFF вне PUA или отсутствие font-map — элемент сохраняется как есть.
*/ */
private static final Map<String, String> SYMBOL_MAPS = buildMaps(); private static final Map<String, String> SYMBOL_MAPS = buildMaps();
@@ -70,16 +71,13 @@ public final class SymbolFontNormalizer {
private SymbolFontNormalizer() { private SymbolFontNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = SymbolFontNormalizer::normalize;
/** /**
* Заменяет символьные шрифты в XML-частях docx (word/*.xml). * Заменяет символьные шрифты в XML-частях docx (word/*.xml).
* *
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -311,14 +309,20 @@ public final class SymbolFontNormalizer {
char mapped = 0; char mapped = 0;
if (charHex != null && fontMap != null) { if (charHex != null && fontMap != null) {
char code = (char) Integer.parseInt(charHex, 16); char code = (char) Integer.parseInt(charHex, 16);
if (code >= 0xF000 && code <= 0xF0FF) { // PUA-форма (U+F0xx) и прямая (код ≤0xFF — индекс в символной
mapped = mapped(fontMap, code & 0xFF); // cmap, §17.3.3.30) маппятся по одной таблице
} int slot = (code >= 0xF000 && code <= 0xF0FF) ? code & 0xFF
: (code <= 0xFF ? code : -1);
mapped = slot >= 0 ? mapped(fontMap, slot) : 0;
} }
if (mapped != 0) { if (mapped != 0) {
sb.append(openTag).append(fallbackRPr) sb.append(openTag).append(fallbackRPr)
.append("<w:t xml:space=\"preserve\">").append(mapped) .append("<w:t xml:space=\"preserve\">").append(mapped)
.append("</w:t></w:r>"); .append("</w:t></w:r>");
} else if (charHex != null) {
// неразрешимый, но схемно-валидный w:sym (§17.3.3.30) —
// сохраняем verbatim: удалять валидный контент нельзя
sb.append(openTag).append(rPr).append(m.group()).append("</w:r>");
} }
pos = m.end(); pos = m.end();
} }
@@ -14,7 +14,9 @@ import java.util.zip.ZipOutputStream;
* Свёртка {@code w:tblPr/w:jc} (center/right) с ненулевым {@code w:tblInd} в * Свёртка {@code w:tblPr/w:jc} (center/right) с ненулевым {@code w:tblInd} в
* абсолютный {@code w:tblInd} — до загрузки docx4j. * абсолютный {@code w:tblInd} — до загрузки docx4j.
* *
* Word (Part 1 §17.4.50 в чтении MS-OI29500 §2.1.155): при {@code w:jc}≠left * Word (MS-OI29500 §2.1.155; Part 1 §17.4.28 {@code w:jc} + §17.4.50
* {@code w:tblInd} описывают без аддитивной семантики — «сдвиг от поля после
* центрирования/прижимания» есть измеренное поведение Word): при {@code w:jc}≠left
* таблица центрируется/прижимается, а {@code w:tblInd} добавляется сдвигом от * таблица центрируется/прижимается, а {@code w:tblInd} добавляется сдвигом от
* поля. docx4j же при {@code w:jc}≠left {@code w:tblInd} игнорирует буквально * поля. docx4j же при {@code w:jc}≠left {@code w:tblInd} игнорирует буквально
* (аудит раскладки ECMA-376, матрица B3) — таблица рендерилась без учёта * (аудит раскладки ECMA-376, матрица B3) — таблица рендерилась без учёта
@@ -31,12 +33,17 @@ import java.util.zip.ZipOutputStream;
* <p>Пропускается (не ломая существующее поведение): документы без * <p>Пропускается (не ломая существующее поведение): документы без
* единственного body-level {@code w:sectPr} (несколько секций — полоса * единственного body-level {@code w:sectPr} (несколько секций — полоса
* неоднозначна), {@code w:tblW type="pct"} и таблицы с gridCol без целого * неоднозначна), {@code w:tblW type="pct"} и таблицы с gridCol без целого
* {@code w:w} (фактическая ширина неизвестна), {@code w:tblInd} не-dxa и * {@code w:w} (фактическая ширина неизвестна), {@code w:tblInd} с явным
* {@code w:type}≠dxa (опущенный type — dxa, §17.4.87) и
* {@code w:tblPr} с {@code w:tblCellSpacing} без {@code w:tblInd} (вставить * {@code w:tblPr} с {@code w:tblCellSpacing} без {@code w:tblInd} (вставить
* тег в корректную позицию CT_TblPrBase некуда). Дефолты при отсутствии * тег в корректную позицию CT_TblPrBase некуда). Дефолты при отсутствии
* pgSz/pgMar — 11906 и 1440/1440: измеренное поведение docx4j при отсутствующем * pgSz/pgMar — 11906 и 1440/1440: ECMA дефолтов {@code w:pgSz}/{@code w:pgMar}
* {@code w:pgMar} (левый край текста = 72pt = 1440 twips), а не ECMA-дефолт * не фиксирует (§17.6.13/§17.6.11), а 11906/1440 — измеренное поведение
* 1800 — нормализатор обязан считать ту же полосу, что рендерит стек. * docx4j при отсутствующем {@code w:pgMar} (левый край текста = 72pt =
* 1440 twips) — нормализатор обязан считать ту же полосу, что рендерит стек.
* Band берётся из сырого {@code word/document.xml}: геометрия инвариантна
* к рерайтам (Strict-схема у {@code CT_PageMar} не имеет start/end, rule 1
* {@code w:pgSz}/{@code w:pgMar} не трогает).
* *
* <p>{@link #normalize} трогает только {@code word/document.xml} (признак — * <p>{@link #normalize} трогает только {@code word/document.xml} (признак —
* {@code <w:body}); нечего менять → тот же массив. {@link #rewritePart} — * {@code <w:body}); нечего менять → тот же массив. {@link #rewritePart} —
@@ -46,7 +53,7 @@ import java.util.zip.ZipOutputStream;
* WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, * WordPdfConverterTest#tableIndentCentered_shiftedLikeWord,
* #headerTableIndent_centeredInHeader. * #headerTableIndent_centeredInHeader.
*/ */
public final class TableIndentNormalizer { final class TableIndentNormalizer {
/** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */ /** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */
private static final int DEFAULT_PG_W = 11906; private static final int DEFAULT_PG_W = 11906;
@@ -57,13 +64,14 @@ public final class TableIndentNormalizer {
private static final String DOCUMENT_ENTRY = "word/document.xml"; private static final String DOCUMENT_ENTRY = "word/document.xml";
private static final Pattern PG_SZ_W = Pattern.compile("<w:pgSz\\b[^>]*w:w=\"(\\d+)\""); private static final Pattern PG_SZ_W = Pattern.compile("<w:pgSz\\b[^>]*w:w=\"(\\d+)\"");
// strict-OOXML пишет поля как w:start/w:end; band считается из СЫРОГО // полоса считается из СЫРОГО document.xml; чередование left|start не
// document.xml (до rule 1, которая их переименует) — чередование // нужен: CT_PageMar не имеет start/end ни в strict-, ни в transitional-
// обязательно, иначе полоса строгого документа молча возьмётся из дефолтов // схеме (wml.xsd), StrictOoxmlNormalizer w:pgSz/w:pgMar не трогает —
// геометрия инвариантна к рерайтам
private static final Pattern PG_MAR_LEFT = private static final Pattern PG_MAR_LEFT =
Pattern.compile("<w:pgMar\\b[^>]*w:(?:left|start)=\"(\\d+)\""); Pattern.compile("<w:pgMar\\b[^>]*w:left=\"(\\d+)\"");
private static final Pattern PG_MAR_RIGHT = private static final Pattern PG_MAR_RIGHT =
Pattern.compile("<w:pgMar\\b[^>]*w:(?:right|end)=\"(\\d+)\""); Pattern.compile("<w:pgMar\\b[^>]*w:right=\"(\\d+)\"");
private static final Pattern JC = private static final Pattern JC =
Pattern.compile("<w:jc\\b[^>]*w:val=\"(center|right)\"[^>]*/>"); Pattern.compile("<w:jc\\b[^>]*w:val=\"(center|right)\"[^>]*/>");
private static final Pattern TBL_IND = Pattern.compile("<w:tblInd\\b[^>]*/>"); private static final Pattern TBL_IND = Pattern.compile("<w:tblInd\\b[^>]*/>");
@@ -74,16 +82,13 @@ public final class TableIndentNormalizer {
private TableIndentNormalizer() { private TableIndentNormalizer() {
} }
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = TableIndentNormalizer::normalize;
/** /**
* Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}. * Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}.
* *
* @param docx байты .docx (zip) * @param docx байты .docx (zip)
* @return те же или переупакованные байты * @return те же или переупакованные байты
*/ */
public static byte[] normalize(byte[] docx) throws IOException { static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length); ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false; boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx)); try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -186,10 +191,18 @@ public final class TableIndentNormalizer {
if (hasInd) { if (hasInd) {
String indTag = ind.group(); String indTag = ind.group();
Matcher indW = TBL_IND_W.matcher(indTag); Matcher indW = TBL_IND_W.matcher(indTag);
if (!indW.find() || !indTag.contains("w:type=\"dxa\"")) { // CT_TblWidth (§17.4.87): опущенный w:type = dxa;
continue; // не-dxa — величина сдвига неизвестна // явный не-dxa (pct и т.п.) — величина сдвига неизвестна
boolean nonDxa = indTag.contains("w:type=") && !indTag.contains("w:type=\"dxa\"");
if (!indW.find() || nonDxa) {
continue;
} }
x = Integer.parseInt(indW.group(1)); x = Integer.parseInt(indW.group(1));
} else if (pr.contains("<w:tblInd")) {
// парный (не самозакрывающийся) w:tblInd — паттерн видит
// только самозакрытый; вставка нового тега оставила бы старый
// → дубль элемента (maxOccurs=1 у CT_TblPrBase), консервативно
continue;
} else if (pr.contains("<w:tblCellSpacing")) { } else if (pr.contains("<w:tblCellSpacing")) {
// tblInd по CT_TblPrBase идёт ПОСЛЕ tblCellSpacing — вставить // tblInd по CT_TblPrBase идёт ПОСЛЕ tblCellSpacing — вставить
// тег в корректную позицию некуда, консервативно пропускаем // тег в корректную позицию некуда, консервативно пропускаем
@@ -11,7 +11,7 @@ import java.util.List;
/** /**
* Объёмные декартовы графики: c:bar3DChart, c:line3DChart, c:area3DChart * Объёмные декартовы графики: c:bar3DChart, c:line3DChart, c:area3DChart
* (ECMA-376 §21.2.2.19/.101/.122). Камера — та же, что у поверхности * (ECMA-376 §21.2.2.15/.96/.4). Камера — та же, что у поверхности
* ({@link Surface3dPainter#project}): u — категория (ширина), v — ряд * ({@link Surface3dPainter#project}): u — категория (ширина), v — ряд
* (глубина), w — значение (высота); вписка равномерным масштабом в поля * (глубина), w — значение (высота); вписка равномерным масштабом в поля
* {@link Surface3dPainter#GUTTER_LEFT} и т.д. * {@link Surface3dPainter#GUTTER_LEFT} и т.д.
@@ -21,8 +21,8 @@ import java.util.List;
* §2.1.1474(a)); торец затемняется (псевдо-свет, калибровка — Cartesian3dPainterTest). * §2.1.1474(a)); торец затемняется (псевдо-свет, калибровка — Cartesian3dPainterTest).
* line3D: полилиния ряда на своей глубине, лента-толщина не имитируется; * line3D: полилиния ряда на своей глубине, лента-толщина не имитируется;
* area3D: стена ряда от пола до значений, полупрозрачная, как AREA. * area3D: стена ряда от пола до значений, полупрозрачная, как AREA.
* c:shape (§21.2.2.177, ST_Shape §21.2.3.44): box/cone/coneToMax/cylinder/pyramid/ * c:shape (§21.2.2.177, ST_Shape §21.2.3.42): box/cone/coneToMax/cylinder/pyramid/
* pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1545(a/b)), * pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1546(a/b)),
* ToMax-формы сужаются к верху пропорционально val/max (семантика Excel — ECMA геометрию * ToMax-формы сужаются к верху пропорционально val/max (семантика Excel — ECMA геометрию
* не нормирует); неизвестное значение — box. c:barDir="bar" — горизонтальная ориентация * не нормирует); неизвестное значение — box. c:barDir="bar" — горизонтальная ориентация
* боксов (Word UI не сочетает barDir=bar с формами). * боксов (Word UI не сочетает barDir=bar с формами).
@@ -343,7 +343,7 @@ final class Cartesian3dPainter {
} }
} }
/** Грани колонки в модельных координатах (§21.2.3.44 ST_Shape); все вершины /** Грани колонки в модельных координатах (§21.2.3.42 ST_Shape); все вершины
* проецируются в nodes — по ним происходит вписка. Неизвестная форма — box. */ * проецируются в nodes — по ним происходит вписка. Неизвестная форма — box. */
private static List<Face> buildFaces(Color color, String shape, double t, private static List<Face> buildFaces(Color color, String shape, double t,
double u0, double u1, double v0, double v1, double u0, double u1, double v0, double v1,
@@ -600,7 +600,7 @@ final class Cartesian3dPainter {
} }
/** Подписи: значения — вдоль переднего левого ребра, категории — нижнего, /** Подписи: значения — вдоль переднего левого ребра, категории — нижнего,
* ряды — правого; c:delete (§21.2.2.38) убирает подписи оси. * ряды — правого; c:delete (§21.2.2.40) убирает подписи оси.
* Регрессия — Cartesian3dPainterTest#bar3d_seriesAxisLabelsDrawn. */ * Регрессия — Cartesian3dPainterTest#bar3d_seriesAxisLabelsDrawn. */
private static void drawLabels(Graphics2D g, ChartSpec spec, List<Double> tickValues, private static void drawLabels(Graphics2D g, ChartSpec spec, List<Double> tickValues,
List<Surface3dPainter.Node> valueAnchors, int nCat, List<Surface3dPainter.Node> valueAnchors, int nCat,
@@ -70,12 +70,12 @@ final class CartesianPainter {
"percentStacked".equalsIgnoreCase(lineGrouping)) "percentStacked".equalsIgnoreCase(lineGrouping))
: null; : null;
// Разделение серий по осям значений: ссылочное равенство с secondaryValAxis // Разделение серий по осям значений: та же ось по c:axId
// (назначается ChartSpec.parse по c:axId, §21.2.2.9). // (назначается ChartSpec.parse, §21.2.2.9; {@link ChartSpec#sameAxis}).
List<Integer> primIdx = new ArrayList<>(); List<Integer> primIdx = new ArrayList<>();
List<Integer> secIdx = new ArrayList<>(); List<Integer> secIdx = new ArrayList<>();
for (int si = 0; si < spec.series.size(); si++) { for (int si = 0; si < spec.series.size(); si++) {
if (secAxis != null && spec.series.get(si).valAxis == secAxis) { if (ChartSpec.sameAxis(spec.series.get(si).valAxis, secAxis)) {
secIdx.add(si); secIdx.add(si);
} else { } else {
primIdx.add(si); primIdx.add(si);
@@ -278,9 +278,9 @@ final class CartesianPainter {
return gr != null ? gr : spec.grouping; return gr != null ? gr : spec.grouping;
} }
/** Серия на вторичной оси значений (ссылочное равенство с secondaryValAxis). */ /** Серия на вторичной оси значений (та же ось по c:axId, §21.2.2.9; {@link ChartSpec#sameAxis}). */
private static boolean onSecondary(ChartSpec.Series s, ChartSpec spec) { private static boolean onSecondary(ChartSpec.Series s, ChartSpec spec) {
return spec.secondaryValAxis != null && s.valAxis == spec.secondaryValAxis; return ChartSpec.sameAxis(s.valAxis, spec.secondaryValAxis);
} }
private static List<Integer> intersect(List<Integer> family, List<Integer> prim) { private static List<Integer> intersect(List<Integer> family, List<Integer> prim) {
@@ -2,10 +2,13 @@ package ru.pjandro.wordpdf.internal.chart;
import org.docx4j.convert.out.fo.FOConversionImageHandler; import org.docx4j.convert.out.fo.FOConversionImageHandler;
import org.docx4j.model.images.AbstractWordXmlPicture; import org.docx4j.model.images.AbstractWordXmlPicture;
import org.docx4j.model.images.PictureCompression;
import org.docx4j.openpackaging.exceptions.Docx4JException; import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPart; import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPart;
import org.docx4j.relationships.Relationship; import org.docx4j.relationships.Relationship;
import java.nio.ByteBuffer;
/** /**
* Image-обработчик FO-экспорта, отключающий docx4j «Compress Pictures» * Image-обработчик FO-экспорта, отключающий docx4j «Compress Pictures»
* (CR-029) для наших chart-PNG. * (CR-029) для наших chart-PNG.
@@ -25,13 +28,26 @@ import org.docx4j.relationships.Relationship;
* {@code /word/media/chart-*} возвращаем null (нет варианта), картинка * {@code /word/media/chart-*} возвращаем null (нет варианта), картинка
* уходит в PDF как есть. * уходит в PDF как есть.
* *
* Медиа документов (фото/скрины) — не наши части, им остаётся штатный * Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
* docx4j-режим CR-029. * дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
* ДО любых решений, а для не-JPEG без кропа с ppi {@code <=} threshold (и без размера
* в макете) результат всегда null — декод впустую. Здесь такое решение
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
* вовсе. JPEG сознательно не ускоряем: Word при ppi {@code <=} threshold перекодирует
* его «для размера», вывод должен остаться побайтно прежним.
* *
* Регрессия — WordPdfConverterTest#chartMedia_notDownsampled. * Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
* ChartImageHandlerTest#plainPngBelowThreshold_returnsNull,
* ChartImageHandlerTest#jpegBelowThreshold_stillDelegates,
* ChartImageHandlerTest#pngAboveThreshold_stillDelegates.
*/ */
public final class ChartImageHandler extends FOConversionImageHandler { public final class ChartImageHandler extends FOConversionImageHandler {
private static final int[] PNG_SIGNATURE =
{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A};
private static final int[] GIF_SIGNATURE = {0x47, 0x49, 0x46, 0x38};
private static final int[] BMP_SIGNATURE = {0x42, 0x4D};
@Override @Override
protected String compressedVariant(AbstractWordXmlPicture picture, protected String compressedVariant(AbstractWordXmlPicture picture,
Relationship relationship, BinaryPart part) Relationship relationship, BinaryPart part)
@@ -41,6 +57,85 @@ public final class ChartImageHandler extends FOConversionImageHandler {
.startsWith(DrawingPreRenderer.CHART_MEDIA_URI_PREFIX)) { .startsWith(DrawingPreRenderer.CHART_MEDIA_URI_PREFIX)) {
return null; return null;
} }
// Быстрый путь: null идентичен тому, что super вернул бы после
// полного декода. PictureCompression.compress для не-JPEG без кропа
// возвращает null, когда ресемпл не нужен: ppi по заголовку не выше
// threshold (формула — дословно из compress) или размер в макете
// задан нулём/не задан (кроп при этом исключён, reencoding требует
// JPEG). Кроп, high-fidelity, JPEG и нераспознанный формат — super.
if (picture != null && picture.isForXslFo() && part != null
&& (!cropsPictures() || picture.getCrop().isNone())) {
PictureCompression.Resolution resolution =
PictureCompression.resolution(picture.getWmlPackage(), pictureResolution);
if (!resolution.isHighFidelity() && noResampleNeeded(part.getBuffer(),
picture.getWidthInPoints(), picture.getHeightInPoints(),
resolution.threshold)) {
return null;
}
}
return super.compressedVariant(picture, relationship, part); return super.compressedVariant(picture, relationship, part);
} }
/**
* Истинно, когда по 26 байтам заголовка контейнера картинка — из быстрого
* списка (PNG/GIF/BMP) и ресемпл ей не нужен: нативный ppi при заданном
* макетном размере не выше {@code threshold} (формула — дословно из
* {@code PictureCompression.compress}), либо размер в макете не задан
* (без кропа и без JPEG super тоже приходит к null). Ложь — формат вне
* списка (JPEG — решение пользователя, TIFF/EMF/WMF/…), заголовок
* неполный/неправдоподобный или буфер части пуст: решение отдаём super.
* Байты читаются абсолютными индексами — позиция общего {@link ByteBuffer}
* части не мутируется.
*/
private static boolean noResampleNeeded(ByteBuffer bb, double widthPt, double heightPt,
int threshold) {
if (bb == null) {
return false;
}
final int len = bb.limit();
final int width;
final int height;
// PNG: сигнатура, затем длина блока, «IHDR» со смещения 12,
// ширина/высота big-endian в 16/20.
if (len >= 24 && magic(bb, 0, PNG_SIGNATURE) && be32(bb, 12) == 0x49484452) {
width = be32(bb, 16);
height = be32(bb, 20);
// GIF: «GIF8», ширина/высота little-endian в 6/8 (le32-чтение
// с 8 идёт до байта 11 включительно).
} else if (len >= 12 && magic(bb, 0, GIF_SIGNATURE)) {
width = le32(bb, 6) & 0xFFFF;
height = le32(bb, 8) & 0xFFFF;
// BMP: «BM», ширина/высота BITMAPINFOHEADER little-endian в 18/22
// (высота отрицательная для top-down — берём модуль).
} else if (len >= 26 && magic(bb, 0, BMP_SIGNATURE)) {
width = le32(bb, 18);
height = Math.abs(le32(bb, 22));
} else {
return false;
}
if (width <= 0 || height <= 0) {
return false;
}
return widthPt <= 0 || heightPt <= 0
|| Math.max(width / (widthPt / 72d), height / (heightPt / 72d)) <= threshold;
}
private static boolean magic(ByteBuffer bb, int at, int[] bytes) {
for (int i = 0; i < bytes.length; i++) {
if ((bb.get(at + i) & 0xFF) != bytes[i]) {
return false;
}
}
return true;
}
private static int be32(ByteBuffer bb, int at) {
return ((bb.get(at) & 0xFF) << 24) | ((bb.get(at + 1) & 0xFF) << 16)
| ((bb.get(at + 2) & 0xFF) << 8) | (bb.get(at + 3) & 0xFF);
}
private static int le32(ByteBuffer bb, int at) {
return (bb.get(at) & 0xFF) | ((bb.get(at + 1) & 0xFF) << 8)
| ((bb.get(at + 2) & 0xFF) << 16) | ((bb.get(at + 3) & 0xFF) << 24);
}
} }
@@ -52,6 +52,10 @@ final class ChartRenderer {
/** Порог «значение целое» при форматировании подписей. */ /** Порог «значение целое» при форматировании подписей. */
private static final double INTEGER_EPSILON = 1e-9; private static final double INTEGER_EPSILON = 1e-9;
/** Позиции легенды (ECMA-376 §21.2.2.95 legendPos, ST_LegendPos §21.2.3.24): снизу/сверху. */
private static final String LEGEND_BOTTOM = "b";
private static final String LEGEND_TOP = "t";
/** /**
* Верхняя граница числа делений: {@code c:majorUnit} (ECMA-376 §21.2.2.103) — * Верхняя граница числа делений: {@code c:majorUnit} (ECMA-376 §21.2.2.103) —
* double без нижней границы; Word пишет «круглые» значения, а враждебный docx — * double без нижней границы; Word пишет «круглые» значения, а враждебный docx —
@@ -110,12 +114,12 @@ final class ChartRenderer {
// дорисовывается поверх после художника. Регрессия — ChartRendererTest#overlayLegend_drawnOverPlot. // дорисовывается поверх после художника. Регрессия — ChartRendererTest#overlayLegend_drawnOverPlot.
double legendH = legend == null || spec.legendOverlay ? 0 : legend.height; double legendH = legend == null || spec.legendOverlay ? 0 : legend.height;
Rectangle2D box0 = box; Rectangle2D box0 = box;
if (legend != null && !spec.legendOverlay && "b".equals(spec.legendPos)) { if (legend != null && !spec.legendOverlay && LEGEND_BOTTOM.equals(spec.legendPos)) {
legend.draw(g, box.getX(), box.getY() + box.getHeight() - legendH, legend.draw(g, box.getX(), box.getY() + box.getHeight() - legendH,
box.getWidth()); box.getWidth());
box = new Rectangle2D.Double(box.getX(), box.getY(), box = new Rectangle2D.Double(box.getX(), box.getY(),
box.getWidth(), box.getHeight() - legendH); box.getWidth(), box.getHeight() - legendH);
} else if (legend != null && !spec.legendOverlay && "t".equals(spec.legendPos)) { } else if (legend != null && !spec.legendOverlay && LEGEND_TOP.equals(spec.legendPos)) {
legend.draw(g, box.getX(), box.getY(), box.getWidth()); legend.draw(g, box.getX(), box.getY(), box.getWidth());
box = new Rectangle2D.Double(box.getX(), box.getY() + legendH, box = new Rectangle2D.Double(box.getX(), box.getY() + legendH,
box.getWidth(), box.getHeight() - legendH); box.getWidth(), box.getHeight() - legendH);
@@ -144,7 +148,7 @@ final class ChartRenderer {
default -> LOG.warn("тип графика {} не поддерживается — пустой PNG", spec.type); default -> LOG.warn("тип графика {} не поддерживается — пустой PNG", spec.type);
} }
if (legend != null && spec.legendOverlay) { if (legend != null && spec.legendOverlay) {
double y = "t".equals(spec.legendPos) double y = LEGEND_TOP.equals(spec.legendPos)
? box0.getY() : box0.getY() + box0.getHeight() - legend.height; ? box0.getY() : box0.getY() + box0.getHeight() - legend.height;
legend.draw(g, box0.getX(), y, box0.getWidth()); legend.draw(g, box0.getX(), y, box0.getWidth());
} }
@@ -117,7 +117,7 @@ final class ChartSpec {
final List<Double> xValues = new ArrayList<>(); final List<Double> xValues = new ArrayList<>();
/** bubble: размеры пузырей (c:bubbleSize). */ /** bubble: размеры пузырей (c:bubbleSize). */
final List<Double> bubbleSizes = new ArrayList<>(); final List<Double> bubbleSizes = new ArrayList<>();
/** c:shape ряда bar3D (MS-OI29500 §2.1.1545(b)); null = дефолт диаграммы ({@link #shape3d}). */ /** c:shape ряда bar3D (MS-OI29500 §2.1.1546(b)); null = дефолт диаграммы ({@link #shape3d}). */
String shape3d; String shape3d;
/** Способ отрисовки ряда в combo-диаграмме (несколько групп в одном c:plotArea, /** Способ отрисовки ряда в combo-диаграмме (несколько групп в одном c:plotArea,
* ECMA-376 §21.2.2.145): BAR/BAR_HORIZONTAL/LINE/AREA по группе-источнику. * ECMA-376 §21.2.2.145): BAR/BAR_HORIZONTAL/LINE/AREA по группе-источнику.
@@ -396,7 +396,7 @@ final class ChartSpec {
break; break;
} }
} }
if (va == null || va == spec.valAxis) { if (va == null || sameAxis(va, spec.valAxis)) {
continue; continue;
} }
if (spec.secondaryValAxis == null) { if (spec.secondaryValAxis == null) {
@@ -409,6 +409,14 @@ final class ChartSpec {
} }
} }
/** Та же ось по c:axId (§21.2.2.9): id уникален в диаграмме, оси с id ≥ 0 лежат
* в {@code axesById} по одному на id — для осей, назначенных из карты при разборе,
* эквивалентно ссылочному равенству. Прямое сравнение осей через == запрещено
* PMD CompareObjectsWithEquals; null и id &lt; 0 — никогда «та же». */
static boolean sameAxis(AxisSpec a, AxisSpec b) {
return a != null && b != null && a.axId >= 0 && a.axId == b.axId;
}
private static void readChartFrame(CTChartSpace space, ChartSpec spec, DrawMlColor colors) { private static void readChartFrame(CTChartSpace space, ChartSpec spec, DrawMlColor colors) {
CTShapeProperties sp = space.getSpPr(); CTShapeProperties sp = space.getSpPr();
if (sp == null) { if (sp == null) {
@@ -1129,7 +1137,11 @@ final class ChartSpec {
return null; return null;
} }
try { try {
return Double.parseDouble(s.trim()); double v = Double.parseDouble(s.trim());
// ST_Double допускает литералы NaN/Infinity; в пиксельных
// формулах пейнтеров они дают молча пустой график — считаем
// точку отсутствующей.
return Double.isFinite(v) ? v : null;
} catch (NumberFormatException e) { } catch (NumberFormatException e) {
return null; return null;
} }
@@ -29,12 +29,13 @@ import java.util.Map;
* Палитра цветов DrawingML: цвета схемы из word/theme/theme1.xml плюс * Палитра цветов DrawingML: цвета схемы из word/theme/theme1.xml плюс
* разбор {@code a:color} (srgbClr / scrgbClr / hslClr / sysClr / * разбор {@code a:color} (srgbClr / scrgbClr / hslClr / sysClr /
* schemeClr / prstClr) с полным набором трансформаций EG_ColorTransform * schemeClr / prstClr) с полным набором трансформаций EG_ColorTransform
* (§20.1.2.3.2-28: lum/sat/hue Mod/Off и абсолютные, tint/shade, * (§20.1.2.3.2-34: lum/sat/hue Mod/Off и абсолютные, tint §20.1.2.3.34 /
* shade §20.1.2.3.31,
* alpha/alphaMod/alphaOff, red/green/blue + Mod/Off, comp, inv, gray, * alpha/alphaMod/alphaOff, red/green/blue + Mod/Off, comp, inv, gray,
* gamma/invGamma). * gamma/invGamma).
* *
* tint/shade — модуляция светлоты в HSL (L' = L·p + (1−p) / L·p, * tint/shade — модуляция светлоты в HSL (L' = L·p + (1−p) / L·p,
* MS-OI29500 §17.3.2.6(a) — поведение Word); ECMA-примеры именно для * MS-OI29500 §2.1.72 — поведение Word); ECMA-примеры именно для
* tint/shade (00BC00) противоречат его же примерам семейства lum/sat — * tint/shade (00BC00) противоречат его же примерам семейства lum/sat —
* расхождение на стороне спецификации. * расхождение на стороне спецификации.
* *
@@ -432,7 +433,7 @@ final class DrawMlColor {
rgb = toRgb(hsl); rgb = toRgb(hsl);
} }
// §20.1.2.3.31/.34: Office-семантика — модуляция // §20.1.2.3.31/.34: Office-семантика — модуляция
// светлоты в HSL (MS-OI29500 §17.3.2.6(a)), не // светлоты в HSL (MS-OI29500 §2.1.72), не
// гамма-микс; ECMA-примеры tint/shade противоречат // гамма-микс; ECMA-примеры tint/shade противоречат
// собственному семейству lum/sat (§20.1.2.3.19-28). // собственному семейству lum/sat (§20.1.2.3.19-28).
case "tint" -> { case "tint" -> {
@@ -7,7 +7,7 @@ import org.docx4j.dml.CTTextParagraph;
import org.docx4j.dml.CTTextParagraphProperties; import org.docx4j.dml.CTTextParagraphProperties;
import org.docx4j.dml.CTTextSpacing; import org.docx4j.dml.CTTextSpacing;
import org.docx4j.dml.TextFont; import org.docx4j.dml.TextFont;
import ru.pjandro.wordpdf.fonts.BundledFontMapper; import ru.pjandro.wordpdf.fonts.BundledFontAliases;
import ru.pjandro.wordpdf.fonts.BundledFonts; import ru.pjandro.wordpdf.fonts.BundledFonts;
import ru.pjandro.wordpdf.fonts.GlyphFont; import ru.pjandro.wordpdf.fonts.GlyphFont;
@@ -23,7 +23,7 @@ import java.util.List;
* (a:defRPr / a:rPr: sz, b, i, solidFill, latin) и разбивка на строки. * (a:defRPr / a:rPr: sz, b, i, solidFill, latin) и разбивка на строки.
* *
* Шрифты берутся из того же бандла, что и у текста PDF * Шрифты берутся из того же бандла, что и у текста PDF
* ({@link BundledFontMapper#bundledFamily}), поэтому подпись диаграммы * ({@link BundledFontAliases#bundledFamily}), поэтому подпись диаграммы
* рисуется тем же Carlito/Tinos, что и абзацы документа. * рисуется тем же Carlito/Tinos, что и абзацы документа.
*/ */
final class DrawMlText { final class DrawMlText {
@@ -43,7 +43,7 @@ final class DrawMlText {
/** /**
* Один абзац: текст + начертание + выравнивание + межстрочный интервал * Один абзац: текст + начертание + выравнивание + межстрочный интервал
* из {@code a:lnSpc} (ECMA-376 §21.1.2.4): {@code spacingPct} — доля * из {@code a:lnSpc} (ECMA-376 §21.1.2.2.5): {@code spacingPct} — доля
* одинарного (a:spcPct/100000), {@code spacingPts} — фиксированная * одинарного (a:spcPct/100000), {@code spacingPts} — фиксированная
* высота строки в pt (a:spcPts/100); оба null — одинарный. * высота строки в pt (a:spcPts/100); оба null — одинарный.
*/ */
@@ -57,6 +57,8 @@ final class DrawMlText {
/** Значения выравнивания DrawingML (a:pPr/@algn, a:bodyPr/@anchor). */ /** Значения выравнивания DrawingML (a:pPr/@algn, a:bodyPr/@anchor). */
private static final String ALIGN_CTR = "ctr"; private static final String ALIGN_CTR = "ctr";
private static final String ALIGN_RIGHT = "r";
private static final String ALIGN_FAR = "far";
private static final String VALIGN_BOTTOM = "b"; private static final String VALIGN_BOTTOM = "b";
/** Длина строки, дальше которую рез не идёт (прогресс гарантирован 1 символом). */ /** Длина строки, дальше которую рез не идёт (прогресс гарантирован 1 символом). */
@@ -82,7 +84,7 @@ final class DrawMlText {
String fallbackFam, double fallbackSize, Color fallbackColor) { String fallbackFam, double fallbackSize, Color fallbackColor) {
Style base = new Style(fallbackSize, false, false, fallbackColor, Style base = new Style(fallbackSize, false, false, fallbackColor,
fallbackFam == null ? BundledFonts.FALLBACK_FAMILY fallbackFam == null ? BundledFonts.FALLBACK_FAMILY
: BundledFontMapper.bundledFamily(fallbackFam)); : BundledFontAliases.bundledFamily(fallbackFam));
if (txPr == null || txPr.getP().isEmpty()) { if (txPr == null || txPr.getP().isEmpty()) {
return base; return base;
} }
@@ -168,7 +170,7 @@ final class DrawMlText {
case "+mj-lt", "+mj-ea", "+mj-cs" -> colors.majorFontName(); case "+mj-lt", "+mj-ea", "+mj-cs" -> colors.majorFontName();
default -> typeface; default -> typeface;
}; };
return BundledFontMapper.bundledFamily(name != null ? name : fallbackFam); return BundledFontAliases.bundledFamily(name != null ? name : fallbackFam);
} }
/** /**
@@ -241,7 +243,7 @@ final class DrawMlText {
String align = line.align() != null ? line.align() : defAlign; String align = line.align() != null ? line.align() : defAlign;
if (ALIGN_CTR.equals(align)) { if (ALIGN_CTR.equals(align)) {
x += (box.getWidth() - line.width()) / 2.0; x += (box.getWidth() - line.width()) / 2.0;
} else if ("r".equals(align) || "far".equals(align)) { } else if (ALIGN_RIGHT.equals(align) || ALIGN_FAR.equals(align)) {
x += box.getWidth() - line.width(); x += box.getWidth() - line.width();
} }
fontFor(line.style()).draw(g, line.text(), x, y + line.ascent(), fontFor(line.style()).draw(g, line.text(), x, y + line.ascent(),
@@ -253,7 +255,7 @@ final class DrawMlText {
/** /**
* Высота строки абзаца: a:lnSpc/a:spcPts — фиксированная в pt, * Высота строки абзаца: a:lnSpc/a:spcPts — фиксированная в pt,
* a:spcPct — доля одинарного (ascent+descent+leading), ничего — * a:spcPct — доля одинарного (ascent+descent+leading), ничего —
* одинарный (ECMA-376 §21.1.2.4 CT_TextLineSpacing). * одинарный (ECMA-376 §21.1.2.2.5 CT_TextLineSpacing).
*/ */
private static double lineFor(Paragraph p, double single) { private static double lineFor(Paragraph p, double single) {
if (p.spacingPts() != null) { if (p.spacingPts() != null) {
@@ -22,6 +22,8 @@ import org.docx4j.dml.diagram2008.CTDrawing;
import org.docx4j.dml.picture.Pic; import org.docx4j.dml.picture.Pic;
import org.docx4j.dml.wordprocessingDrawing.Anchor; import org.docx4j.dml.wordprocessingDrawing.Anchor;
import org.docx4j.dml.wordprocessingDrawing.Inline; import org.docx4j.dml.wordprocessingDrawing.Inline;
import org.docx4j.math.CTOMath;
import org.docx4j.math.CTOMathPara;
import org.docx4j.openpackaging.contenttype.ContentTypes; import org.docx4j.openpackaging.contenttype.ContentTypes;
import org.docx4j.openpackaging.exceptions.Docx4JException; import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.exceptions.InvalidFormatException; import org.docx4j.openpackaging.exceptions.InvalidFormatException;
@@ -32,19 +34,34 @@ import org.docx4j.openpackaging.parts.PartName;
import org.docx4j.openpackaging.parts.ThemePart; import org.docx4j.openpackaging.parts.ThemePart;
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPartAbstractImage; import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPartAbstractImage;
import org.docx4j.openpackaging.parts.relationships.RelationshipsPart; import org.docx4j.openpackaging.parts.relationships.RelationshipsPart;
import org.docx4j.wml.CTSignedHpsMeasure;
import org.docx4j.wml.Drawing; import org.docx4j.wml.Drawing;
import org.docx4j.wml.Jc;
import org.docx4j.wml.JcEnumeration;
import org.docx4j.wml.P;
import org.docx4j.wml.PPr;
import org.docx4j.wml.R;
import org.docx4j.wml.RPr;
import org.docx4j.wml.Text;
import org.slf4j.Logger; import org.slf4j.Logger;
import org.slf4j.LoggerFactory; import org.slf4j.LoggerFactory;
import ru.pjandro.wordpdf.ChartsFoundException;
import ru.pjandro.wordpdf.ConvertOptions; import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.DrawingFoundException; import ru.pjandro.wordpdf.ConversionException;
import ru.pjandro.wordpdf.SmartArtFoundException;
import javax.imageio.ImageIO; import javax.imageio.ImageIO;
import javax.xml.namespace.QName;
import java.awt.image.BufferedImage; import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream; import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream; import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.lang.reflect.Method; import java.lang.reflect.Method;
import java.math.BigInteger;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections;
import java.util.HashSet; import java.util.HashSet;
import java.util.IdentityHashMap;
import java.util.List; import java.util.List;
import java.util.Set; import java.util.Set;
@@ -58,8 +75,20 @@ import java.util.Set;
* пакета и до создания FOSettings, иначе FOP увидит исходные chart/diagram * пакета и до создания FOSettings, иначе FOP увидит исходные chart/diagram
* и молча их выбросит (notImplemented в шаблоне). * и молча их выбросит (notImplemented в шаблоне).
* *
* <p>Третий объект — формулы OMML (§22.1): {@code m:oMathPara}/{@code m:oMath}
* доходят сюда нетронутыми (docx2fo.xslt кладёт их в
* {@code fo:instream-foreign-object} с MathML, который FOP+jeuclid на
* без-fontconfig хостах роняет конвертацию, а на остальных рисует чужими
* системными шрифтами). Каждая формула рендерится своим растером
* ({@link MathModel} → {@link MathRenderer}) и заменяется inline-картинкой
* на месте; unsupported/битая формула деградирует раном с текстом
* {@code m:t}. Байтовый скан {@code MathFallbackNormalizer} (правило 6)
* срезает unsupported-конструкции до загрузки docx4j — этот путь остаётся
* безопасной сетью.
*
* Error-флаги {@link ConvertOptions}: при выключенном render-флаге и * Error-флаги {@link ConvertOptions}: при выключенном render-флаге и
* включённом error-флаге находка объекта — {@link DrawingFoundException} * включённом error-флаге находка объекта — {@link ChartsFoundException} или
* {@link SmartArtFoundException}
* (бросок здесь, на шаге 3.5, до XSLT/FOP). Регрессия — * (бросок здесь, на шаге 3.5, до XSLT/FOP). Регрессия —
* WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts, фикстура * WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts, фикстура
* samples/charts-smartart.docx. * samples/charts-smartart.docx.
@@ -76,6 +105,15 @@ public final class DrawingPreRenderer {
"http://schemas.openxmlformats.org/drawingml/2006/picture"; "http://schemas.openxmlformats.org/drawingml/2006/picture";
private static final String DIAGRAM_DRAWING_REL = private static final String DIAGRAM_DRAWING_REL =
"http://schemas.microsoft.com/office/2007/relationships/diagramDrawing"; "http://schemas.microsoft.com/office/2007/relationships/diagramDrawing";
/** {@code m:} — namespace OMML (§22.1); {@code w:} — wordprocessingML. */
private static final String MATH_URI =
"http://schemas.openxmlformats.org/officeDocument/2006/math";
/** Local name элемента {@code m:oMath} (диспетч JAXBElement по имени тега). */
private static final String LOCAL_OMATH = "oMath";
/** Local name элемента {@code m:oMathPara} (формула отдельным абзацем). */
private static final String LOCAL_OMATH_PARA = "oMathPara";
private static final String WML_URI =
"http://schemas.openxmlformats.org/wordprocessingml/2006/main";
/** /**
* Верхняя граница {@code wp:extent} в EMU: максимальная страница Word — * Верхняя граница {@code wp:extent} в EMU: максимальная страница Word —
@@ -98,10 +136,25 @@ public final class DrawingPreRenderer {
/** /**
* Рендерит диаграммы/SmartArt пакета в PNG и подменяет их картинками — * Рендерит диаграммы/SmartArt пакета в PNG и подменяет их картинками —
* объекты конвертируются всегда. Бросается {@link DrawingFoundException}, * объекты конвертируются всегда. Бросается {@link ChartsFoundException} или
* {@link SmartArtFoundException},
* когда для объектов включён error-флаг ({@link ConvertOptions}). * когда для объектов включён error-флаг ({@link ConvertOptions}).
*/ */
public static void run(WordprocessingMLPackage pkg, ConvertOptions options) { public static void run(WordprocessingMLPackage pkg, ConvertOptions options) {
run(pkg, options, MAX_CHART_PNG_BYTES_TOTAL);
}
/**
* Потолок суммарного размера chart-PNG на документ: пер-объектные гейты
* ({@code MAX_EXTENT_EMU}, {@code MAX_PIXELS}) ограничивают один объект,
* но тысячи chart-частей × MB PNG оседали бы в heap как media-части
* (много-ГБ пик с входа ≤5 MiB). Превышение — деградация «объект удалён
* + warn», конвертация продолжается.
*/
private static final long MAX_CHART_PNG_BYTES_TOTAL = 128L * 1024 * 1024;
/** Тестовый шов: бюджет задаётся явно (публичный {@link #run} — с константой). */
static void run(WordprocessingMLPackage pkg, ConvertOptions options, long maxPngBytesTotal) {
ThemePart themePart = null; ThemePart themePart = null;
for (Part p : new ArrayList<>(pkg.getParts().getParts().values())) { for (Part p : new ArrayList<>(pkg.getParts().getParts().values())) {
if (p instanceof ThemePart tp) { if (p instanceof ThemePart tp) {
@@ -116,7 +169,9 @@ public final class DrawingPreRenderer {
// ConcurrentModificationException. // ConcurrentModificationException.
List<Part> parts = new ArrayList<>(pkg.getParts().getParts().values()); List<Part> parts = new ArrayList<>(pkg.getParts().getParts().values());
Set<Part> handled = new HashSet<>(); Set<Part> handled = new HashSet<>();
Set<List<?>> visitedContents = Collections.newSetFromMap(new IdentityHashMap<>());
int[] idSeq = {1000}; int[] idSeq = {1000};
long[] pngTotal = {0};
for (Part p : parts) { for (Part p : parts) {
if (!handled.add(p)) { if (!handled.add(p)) {
continue; continue;
@@ -125,7 +180,8 @@ public final class DrawingPreRenderer {
if (content.isEmpty()) { if (content.isEmpty()) {
continue; continue;
} }
walk(p, content, pkg, colors, idSeq, options); walk(p, content, pkg, colors, idSeq, pngTotal, maxPngBytesTotal, options,
visitedContents, null);
} }
} }
@@ -151,20 +207,61 @@ public final class DrawingPreRenderer {
} }
private static void walk(Part part, List<?> content, WordprocessingMLPackage pkg, private static void walk(Part part, List<?> content, WordprocessingMLPackage pkg,
DrawMlColor colors, int[] idSeq, ConvertOptions options) { DrawMlColor colors, int[] idSeq, long[] pngTotal,
for (Object o : content) { long maxPngBytesTotal, ConvertOptions options,
Set<List<?>> visitedContents, P ownerPara) {
// Посещённые списки — по идентичности (IdentityHashMap): рефлексивный
// getContent (ребёнок возвращает список родителя) не зацикливает обход.
// Сравнение списков через ==/!= запрещено PMD CompareObjectsWithEquals.
if (!visitedContents.add(content)) {
return;
}
for (int i = 0; i < content.size(); i++) {
Object o = content.get(i);
Object v = o instanceof JAXBElement ? ((JAXBElement<?>) o).getValue() : o; Object v = o instanceof JAXBElement ? ((JAXBElement<?>) o).getValue() : o;
if (v instanceof Drawing drawing) { if (v instanceof Drawing drawing) {
replaceDrawing(part, drawing, pkg, colors, idSeq, options); replaceDrawing(part, drawing, pkg, colors, idSeq, pngTotal,
maxPngBytesTotal, options);
continue; continue;
} }
if (o instanceof JAXBElement<?> el && el.getName() != null
&& MATH_URI.equals(el.getName().getNamespaceURI())) {
String local = el.getName().getLocalPart();
if (LOCAL_OMATH.equals(local) && v instanceof CTOMath math) {
i = splice(content, i, mathReplacements(math, false, part, pkg,
idSeq, pngTotal, maxPngBytesTotal));
continue;
}
if (LOCAL_OMATH_PARA.equals(local) && v instanceof CTOMathPara para) {
i = splice(content, i, mathParaReplacements(para, ownerPara, part,
pkg, idSeq, pngTotal, maxPngBytesTotal));
continue;
}
}
P para = v instanceof P p ? p : ownerPara;
List<?> nested = invokeList(v, "getContent"); List<?> nested = invokeList(v, "getContent");
if (!nested.isEmpty() && nested != content) { if (!nested.isEmpty()) {
walk(part, nested, pkg, colors, idSeq, options); walk(part, nested, pkg, colors, idSeq, pngTotal, maxPngBytesTotal,
options, visitedContents, para);
} }
} }
} }
/**
* In-place замена элемента {@code index} живого списка дерева на {@code reps}
* (формула → картинка/текст). Живые списки docx4j — изменяемые
* {@code ArrayList}; немодифицируемый список (нетипичный биндинг) —
* {@link UnsupportedOperationException}, который вызывающий не ловит:
* это ошибка программы, а не враждебный вход (валидатор пропускает только
* OOXML-валидные пакеты). Raw-сигнатура — единственный способ mutate
* {@code List<?>} без {@code @SuppressWarnings}.
*/
private static int splice(List content, int index, List reps) {
content.remove(index);
content.addAll(index, reps);
return index + reps.size() - 1;
}
private static List<?> invokeList(Object target, String getter) { private static List<?> invokeList(Object target, String getter) {
try { try {
Method m = target.getClass().getMethod(getter); Method m = target.getClass().getMethod(getter);
@@ -176,7 +273,8 @@ public final class DrawingPreRenderer {
} }
private static void replaceDrawing(Part part, Drawing drawing, WordprocessingMLPackage pkg, private static void replaceDrawing(Part part, Drawing drawing, WordprocessingMLPackage pkg,
DrawMlColor colors, int[] idSeq, ConvertOptions options) { DrawMlColor colors, int[] idSeq, long[] pngTotal,
long maxPngBytesTotal, ConvertOptions options) {
for (Object wrapper : drawing.getAnchorOrInline()) { for (Object wrapper : drawing.getAnchorOrInline()) {
Graphic graphic; Graphic graphic;
long cx; long cx;
@@ -207,10 +305,10 @@ public final class DrawingPreRenderer {
boolean isChart = CHART_ELEMENT.equals(name); boolean isChart = CHART_ELEMENT.equals(name);
boolean isDiagram = DIAGRAM_ELEMENT.equals(name); boolean isDiagram = DIAGRAM_ELEMENT.equals(name);
if (isChart && options.errorOnCharts()) { if (isChart && options.errorOnCharts()) {
throw new DrawingFoundException(DrawingFoundException.Kind.CHARTS); throw new ChartsFoundException();
} }
if (isDiagram && options.errorOnSmartArt()) { if (isDiagram && options.errorOnSmartArt()) {
throw new DrawingFoundException(DrawingFoundException.Kind.SMARTART); throw new SmartArtFoundException();
} }
if (cx <= 0 || cy <= 0 || cx > MAX_EXTENT_EMU || cy > MAX_EXTENT_EMU) { if (cx <= 0 || cy <= 0 || cx > MAX_EXTENT_EMU || cy > MAX_EXTENT_EMU) {
LOG.warn("drawing вне допустимого wp:extent (cx={}, cy={}) — объект оставлен как есть", LOG.warn("drawing вне допустимого wp:extent (cx={}, cy={}) — объект оставлен как есть",
@@ -234,10 +332,169 @@ public final class DrawingPreRenderer {
} }
continue; continue;
} }
swapForPicture(part, gd, img, cx, cy, idSeq, pkg); swapForPicture(part, gd, img, cx, cy, idSeq, pkg, pngTotal, maxPngBytesTotal);
} }
} }
/**
* Одна {@code m:oMath} → замены на позиции формулы: inline
* {@code w:drawing} с pic:pic (успех) или ран с конкатенацией
* {@code m:t} (деградация: unsupported-конструкция — безопасная сеть
* после байтового скана MathFallbackNormalizer, пустая/битая формула,
* переполнение бюджета PNG). OOM — {@link ConversionException}, не
* деградация (тот же контракт, что у графиков).
*/
private static List<Object> mathReplacements(CTOMath math, boolean display,
Part part, WordprocessingMLPackage pkg,
int[] idSeq, long[] pngTotal,
long maxPngBytesTotal) {
try {
MathRenderer.MathImage mi = MathRenderer.render(MathModel.build(math, display));
if (mi.image() == null) {
return textRuns(MathModel.mathText(math));
}
byte[] png;
try {
ByteArrayOutputStream bos = new ByteArrayOutputStream();
ImageIO.write(mi.image(), "png", bos);
png = bos.toByteArray();
} finally {
mi.image().flush();
}
if (png.length == 0) {
LOG.warn("PNG формулы пуст — формула деградирована в текст");
return textRuns(MathModel.mathText(math));
}
if (pngTotal[0] + png.length > maxPngBytesTotal) {
LOG.warn("суммарный размер PNG превысил {} байт — формула деградирована в текст",
maxPngBytesTotal);
return textRuns(MathModel.mathText(math));
}
pngTotal[0] += png.length;
String relId = addChartMedia(pkg, part, png);
long cx = Math.round(mi.widthPt() * 12700.0);
long cy = Math.round(mi.heightPt() * 12700.0);
Drawing pic = mathPicture(idSeq, relId, cx, cy);
if (display) {
return List.of(pic);
}
// FOP ставит инлайн-картинку НИЖНИМ краем на базовую линию
// строки, поэтому формула «всплывала» на descent+PAD над
// текстом. Word роняет базовую линию формулы на базовую
// линию строки — компенсируем смещением ранa вниз:
// w:rPr/w:position (полупункты, отрицательное опускает,
// §17.3.2.24) через AUDIT-FIX baseline-shift вендорного
// XSLT. belowBaselinePt > PAD всегда (канва ≥ габариту +
// 2·PAD), нулевого смещения не бывает. Регрессия —
// WordPdfConverterTest#ommlMathInline_sitsOnTextBaseline.
R run = new R();
RPr rpr = new RPr();
CTSignedHpsMeasure pos = new CTSignedHpsMeasure();
pos.setVal(BigInteger.valueOf(-Math.round(2 * mi.belowBaselinePt())));
rpr.setPosition(pos);
run.setRPr(rpr);
run.getContent().add(pic);
return List.of(run);
} catch (MathUnsupportedException e) {
LOG.info("формула не поддерживается рендером — деградация в текст: {}",
e.getMessage());
return textRuns(MathModel.mathText(math));
} catch (OutOfMemoryError e) {
LOG.error("память исчерпана при рендере формулы", e);
throw new ConversionException("Память исчерпана при рендере формулы", e);
} catch (Docx4JException | IOException | RuntimeException e) {
LOG.warn("рендер формулы упал: {}", e.toString());
return textRuns(MathModel.mathText(math));
}
}
/**
* Блок {@code m:oMathPara} (§22.1.3.13): все формулы блока — display.
* Word кладёт {@code oMathPara} либо в блок-контейнер (§22.1.3 —
* наблюдаемая раскладка Word-файлов), либо в {@code w:p}; в первом
* случае формулы заворачиваются в новый центрированный {@code w:p},
* во втором — вставляются на место блока, а содержащему абзацу
* выставляется {@code jc=center} (семантика центрированной
* формулы-абзаца; prose в том же абзаце — враждебный вход, центрируется
* тоже — зарегистрированная деградация).
*/
private static List<Object> mathParaReplacements(CTOMathPara para, P ownerPara,
Part part, WordprocessingMLPackage pkg,
int[] idSeq, long[] pngTotal,
long maxPngBytesTotal) {
List<Object> inner = new ArrayList<>();
for (CTOMath m : para.getOMath()) {
inner.addAll(mathReplacements(m, true, part, pkg, idSeq, pngTotal,
maxPngBytesTotal));
}
if (ownerPara != null) {
centerParagraph(ownerPara);
return inner;
}
if (inner.isEmpty()) {
return List.of();
}
P p = new P();
PPr ppr = new PPr();
Jc jc = new Jc();
jc.setVal(JcEnumeration.CENTER);
ppr.setJc(jc);
p.setPPr(ppr);
p.getContent().addAll(inner);
return List.of(p);
}
/** {@code jc=center} на абзаце (создаёт {@code w:pPr}, если нет). */
private static void centerParagraph(P para) {
PPr ppr = para.getPPr();
if (ppr == null) {
ppr = new PPr();
para.setPPr(ppr);
}
Jc jc = new Jc();
jc.setVal(JcEnumeration.CENTER);
ppr.setJc(jc);
}
/** Inline {@code w:drawing} с pic:Pic заданного размера (EMU). */
private static Drawing mathPicture(int[] idSeq, String relId, long cx, long cy) {
Drawing drawing = new Drawing();
Inline inline = new Inline();
inline.setDistT(0L);
inline.setDistB(0L);
inline.setDistL(0L);
inline.setDistR(0L);
CTPositiveSize2D extent = new CTPositiveSize2D();
extent.setCx(cx);
extent.setCy(cy);
inline.setExtent(extent);
CTNonVisualDrawingProps docPr = new CTNonVisualDrawingProps();
docPr.setId(idSeq[0]++);
docPr.setName("Формула " + docPr.getId());
inline.setDocPr(docPr);
Graphic graphic = new Graphic();
GraphicData gd = new GraphicData();
gd.setUri(PICTURE_URI);
gd.getAny().add(buildPic(idSeq, relId, cx, cy, "Формула"));
graphic.setGraphicData(gd);
inline.setGraphic(graphic);
drawing.getAnchorOrInline().add(inline);
return drawing;
}
/** Ран с текстом (деградация формулы); пустой текст — пустой список. */
private static List<Object> textRuns(String text) {
if (text.isEmpty()) {
return List.of();
}
R run = new R();
Text t = new Text();
t.setValue(text);
t.setSpace("preserve");
run.getContent().add(new JAXBElement<>(new QName(WML_URI, "t"), Text.class, t));
return List.of(run);
}
private static BufferedImage renderChart(Part part, CTRelId ref, private static BufferedImage renderChart(Part part, CTRelId ref,
DrawMlColor colors, long cx, long cy) { DrawMlColor colors, long cx, long cy) {
Part target = resolve(part, ref.getId()); Part target = resolve(part, ref.getId());
@@ -248,8 +505,15 @@ public final class DrawingPreRenderer {
try { try {
ChartSpec spec = ChartSpec.parse(space, colors); ChartSpec spec = ChartSpec.parse(space, colors);
return ChartRenderer.render(spec, cx / 12700.0, cy / 12700.0, colors); return ChartRenderer.render(spec, cx / 12700.0, cy / 12700.0, colors);
} catch (RuntimeException | OutOfMemoryError e) { } catch (OutOfMemoryError e) {
// OOM — второй эшелон после MAX_EXTENT_EMU/MAX_POINTS: враждебный // OOM — не «деградация объекта»: состояние heap после него
// ненадёжно, продолжение рендера следующих объектов — второй
// OOM вместо одного детерминированного 500.
LOG.error("память исчерпана при рендере графика r:id={}", ref.getId(), e);
throw new ConversionException(
"Память исчерпана при рендере объектов рисования", e);
} catch (RuntimeException e) {
// второй эшелон после MAX_EXTENT_EMU/MAX_POINTS: враждебный
// chart-XML не должен валить всю конвертацию, деградация = объект удалён. // chart-XML не должен валить всю конвертацию, деградация = объект удалён.
LOG.warn("рендер графика r:id={} упал: {}", ref.getId(), e.toString()); LOG.warn("рендер графика r:id={} упал: {}", ref.getId(), e.toString());
return null; return null;
@@ -265,7 +529,11 @@ public final class DrawingPreRenderer {
} }
try { try {
return SmartArtRenderer.render(drawing, colors, cx / 12700.0, cy / 12700.0); return SmartArtRenderer.render(drawing, colors, cx / 12700.0, cy / 12700.0);
} catch (RuntimeException | OutOfMemoryError e) { } catch (OutOfMemoryError e) {
LOG.error("память исчерпана при рендере SmartArt", e);
throw new ConversionException(
"Память исчерпана при рендере объектов рисования", e);
} catch (RuntimeException e) {
LOG.warn("рендер SmartArt упал: {}", e.toString()); LOG.warn("рендер SmartArt упал: {}", e.toString());
return null; return null;
} }
@@ -309,7 +577,8 @@ public final class DrawingPreRenderer {
*/ */
private static void swapForPicture(Part part, GraphicData gd, BufferedImage img, private static void swapForPicture(Part part, GraphicData gd, BufferedImage img,
long cx, long cy, int[] idSeq, long cx, long cy, int[] idSeq,
WordprocessingMLPackage pkg) { WordprocessingMLPackage pkg,
long[] pngTotal, long maxPngBytesTotal) {
byte[] png; byte[] png;
try { try {
ByteArrayOutputStream bos = new ByteArrayOutputStream(); ByteArrayOutputStream bos = new ByteArrayOutputStream();
@@ -325,6 +594,13 @@ public final class DrawingPreRenderer {
gd.getAny().clear(); // контракт: упавший рендер — объект удалён gd.getAny().clear(); // контракт: упавший рендер — объект удалён
return; return;
} }
if (pngTotal[0] + png.length > maxPngBytesTotal) {
LOG.warn("суммарный размер chart-PNG превысил {} байт — объект удалён",
maxPngBytesTotal);
gd.getAny().clear(); // деградация «объект удалён + warn»
return;
}
pngTotal[0] += png.length;
String relId; String relId;
try { try {
relId = addChartMedia(pkg, part, png); relId = addChartMedia(pkg, part, png);
@@ -334,11 +610,25 @@ public final class DrawingPreRenderer {
return; return;
} }
Pic pic = buildPic(idSeq, relId, cx, cy, "Диаграмма");
gd.setUri(PICTURE_URI);
gd.getAny().clear();
gd.getAny().add(pic);
}
/**
* {@code pic:pic} на готовый media-r:id: id/имя из счётчика {@code idSeq}
* (общего для картинок диаграмм и формул), геометрия — входной extent
* (EMU), превью не нужно.
*/
private static Pic buildPic(int[] idSeq, String relId, long cx, long cy,
String namePrefix) {
Pic pic = new Pic(); Pic pic = new Pic();
org.docx4j.dml.picture.CTPictureNonVisual nv = new org.docx4j.dml.picture.CTPictureNonVisual(); org.docx4j.dml.picture.CTPictureNonVisual nv = new org.docx4j.dml.picture.CTPictureNonVisual();
CTNonVisualDrawingProps props = new CTNonVisualDrawingProps(); CTNonVisualDrawingProps props = new CTNonVisualDrawingProps();
props.setId(idSeq[0]++); props.setId(idSeq[0]++);
props.setName("Диаграмма " + props.getId()); props.setName(namePrefix + " " + props.getId());
nv.setCNvPr(props); nv.setCNvPr(props);
nv.setCNvPicPr(new CTNonVisualPictureProperties()); nv.setCNvPicPr(new CTNonVisualPictureProperties());
pic.setNvPicPr(nv); pic.setNvPicPr(nv);
@@ -368,10 +658,7 @@ public final class DrawingPreRenderer {
geom.setAvLst(new CTGeomGuideList()); geom.setAvLst(new CTGeomGuideList());
spPr.setPrstGeom(geom); spPr.setPrstGeom(geom);
pic.setSpPr(spPr); pic.setSpPr(spPr);
return pic;
gd.setUri(PICTURE_URI);
gd.getAny().clear();
gd.getAny().add(pic);
} }
/** /**
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,75 @@
package ru.pjandro.wordpdf.internal.chart;
import java.awt.Color;
import java.awt.Graphics2D;
import java.awt.RenderingHints;
import java.awt.image.BufferedImage;
/**
* Растеризация разобранной формулы: дерево {@link MathModel.Box} → PNG
* в координатах pt×dpi/72 (тот же растер-контракт, что у график:
* {@link ChartRenderer#DPI}, понижение dpi по {@link ChartRenderer#fitDpi}
* при превышении площади). Фон прозрачный (ARGB), сглаживание включено —
* глифы рисуются контурами fontbox, шрифтов хоста не касается.
*
* <p>Пустая формула (нулевые метрики) → {@link MathImage} с нулевыми
* размерами и {@code image == null}: вызывающий заменяет её текстом
* {@code m:t} либо убирает вовсе. {@code OutOfMemoryError} при раздутии
* битмапа НЕ перехватывается — это {@code ConversionException} (500) выше
* по стеку, не деградация (контракт chart-модели).
*/
final class MathRenderer {
/** Минимальный размер растра формулы, pt (тонкий индекс не «схлопнется»). */
static final double MIN_WIDTH_PT = 4.0;
/** Минимальная высота растра формулы, pt. */
static final double MIN_HEIGHT_PT = 12.0;
/** Отступ вокруг габарита формулы, pt (обрезка сглаженных краёв). */
static final double PAD_PT = 1.0;
private MathRenderer() {
}
/**
* Растр формулы: PNG-носитель, габарит в pt (для extcx/extcy) и
* {@code belowBaselinePt} — расстояние от базовой линии формулы до
* нижнего края растра (высота минус верхний отступ и ascent; при
* клампе к MIN_HEIGHT — с запасом снизу).
*/
record MathImage(BufferedImage image, double widthPt, double heightPt,
double belowBaselinePt) {
}
/** Растр бокса; пустой бокс → {@code image == null}, размеры 0. */
static MathImage render(MathModel.Box root) {
if (root.isEmpty()) {
return new MathImage(null, 0, 0, 0);
}
double widthPt = Math.max(MIN_WIDTH_PT, root.width + 2 * PAD_PT);
double heightPt = Math.max(MIN_HEIGHT_PT, root.ascent + root.descent + 2 * PAD_PT);
double dpi = ChartRenderer.fitDpi(widthPt, heightPt);
int w = Math.max(1, (int) Math.round(widthPt * dpi / 72.0));
int h = Math.max(1, (int) Math.round(heightPt * dpi / 72.0));
BufferedImage img = new BufferedImage(w, h, BufferedImage.TYPE_INT_ARGB);
Graphics2D g = img.createGraphics();
try {
g.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
RenderingHints.VALUE_ANTIALIAS_ON);
g.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,
RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
g.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL,
RenderingHints.VALUE_STROKE_PURE);
g.setColor(new Color(0, 0, 0, 0));
double k = dpi / 72.0;
g.scale(k, k);
double x = (widthPt - root.width) / 2.0;
double baseline = PAD_PT + root.ascent;
root.paint(g, x, baseline);
} finally {
g.dispose();
}
return new MathImage(img, widthPt, heightPt, heightPt - PAD_PT - root.ascent);
}
}
@@ -0,0 +1,20 @@
package ru.pjandro.wordpdf.internal.chart;
/**
* Конструкция OMML, которую формульный рендер не раскладывает: math-элемент
* вне {@link MathModel#SUPPORTED}, math-узел не JAXBElement или структурная
* поломка (например, {@code w:br} внутри math-рана).
*
* <p>Сигнал деградации, не отказа: {@code DrawingPreRenderer} заменяет
* формулу её текстом {@code m:t} вместо растра (контент не теряется).
* Бросается на разборе ({@link MathModel#build}), тем же критерием
* срезается раньше — на байтовом уровне в {@code MathFallbackNormalizer}.
*/
final class MathUnsupportedException extends RuntimeException {
private static final long serialVersionUID = 1L;
MathUnsupportedException(String what) {
super(what);
}
}
@@ -11,11 +11,11 @@ import java.util.List;
import java.util.Set; import java.util.Set;
/** /**
* Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.108): главный * Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.126): главный
* пирог из первичных точек + вторичная круговая (c:ofPieType="pie") либо * пирог из первичных точек + вторичная круговая (c:ofPieType="pie") либо
* вертикальный стек ("bar") из вторичных. Разбиение по c:splitType * вертикальный стек ("bar") из вторичных. Разбиение по c:splitType
* (auto|cust|percent|pos|val, §21.2.2.155; семантика splitPos — * (auto|cust|percent|pos|val, §21.2.2.196; семантика splitPos —
* MS-OI29500 §2.1.1554a/b): auto/pos — последние ceil(n/3) (или splitPos) * MS-OI29500 §2.1.1553): auto/pos — последние ceil(n/3) (или splitPos)
* точек, val/percent — точки ниже splitPos, cust — c:secondPiePt. * точек, val/percent — точки ниже splitPos, cust — c:secondPiePt.
* Вторичных точек нет → обычная круговая через {@link PiePainter}. * Вторичных точек нет → обычная круговая через {@link PiePainter}.
* «Other»-сектор (MS-OI29500 §2.1.1507(a)) замыкает главный пирог и обращён к * «Other»-сектор (MS-OI29500 §2.1.1507(a)) замыкает главный пирог и обращён к
@@ -37,7 +37,7 @@ final class OfPiePainter {
* калибровка — OfPiePainterTest). */ * калибровка — OfPiePainterTest). */
private static final double GAP_FIT = 0.25; private static final double GAP_FIT = 0.25;
/** c:ofPieType="bar" — вторичная часть столбчатая (§21.2.2.134). */ /** c:ofPieType="bar" — вторичная часть столбчатая (§21.2.2.127). */
private static final String SECONDARY_BAR = "bar"; private static final String SECONDARY_BAR = "bar";
private OfPiePainter() { private OfPiePainter() {
@@ -9,9 +9,9 @@ import java.util.ArrayList;
import java.util.List; import java.util.List;
/** /**
* Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.143): категории — * Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.153): категории —
* спицы от 12 часов по часовой, значения — радиус по оси значений. * спицы от 12 часов по часовой, значения — радиус по оси значений.
* c:radarStyle (§21.2.2.119): standard — контур, marker — контур + маркеры, * c:radarStyle (§21.2.2.154): standard — контур, marker — контур + маркеры,
* filled — полупрозрачная заливка без контура (вид как у AREA). * filled — полупрозрачная заливка без контура (вид как у AREA).
* Сетка — концентрические многоугольники по делениям оси значений (паутина * Сетка — концентрические многоугольники по делениям оси значений (паутина
* прямыми звеньями, как в Word) и спицы. * прямыми звеньями, как в Word) и спицы.
@@ -15,9 +15,9 @@ import java.util.List;
* ChartSpecTest#scatterFirstValAxisIsX). * ChartSpecTest#scatterFirstValAxisIsX).
* *
* scatter: маркеры по c:marker ряда, линия по c:scatterStyle (line/smooth — * scatter: маркеры по c:marker ряда, линия по c:scatterStyle (line/smooth —
* ECMA-376 §21.2.2.136, сглаживание — кривая Жозефа де Кастельно не * ECMA-376 §21.2.2.162, сглаживание — кривая Жозефа де Кастельно не
* имитируется, ломаная с JOIN_ROUND). bubble: круги без обводки, радиус * имитируется, ломаная с JOIN_ROUND). bubble: круги без обводки, радиус
* sqrt(|size|/maxSize) при c:sizeRepresents="area" (§21.2.2.128) и линейно * sqrt(|size|/maxSize) при c:sizeRepresents="area" (§21.2.2.193) и линейно
* при "w", масштаб c:bubbleScale. Ограничения: c:bubble3D рисуется плоско. * при "w", масштаб c:bubbleScale. Ограничения: c:bubble3D рисуется плоско.
* *
* Регрессия — ScatterPainterTest, фикстура samples/chart-types.docx * Регрессия — ScatterPainterTest, фикстура samples/chart-types.docx

Some files were not shown because too many files have changed in this diff Show More