Compare commits

...

33 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
153 changed files with 9504 additions and 1916 deletions
+29 -20
View File
@@ -20,28 +20,29 @@ jobs:
exit 1
}
- name: Setup JDK 17
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)
- name: Build and test without fontconfig (PMD+JaCoCo included)
env:
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
if: always()
@@ -329,6 +330,14 @@ jobs:
resolver 10.112.0.1 valid=10s ipv6=off;
set \$upstream_app http://app:8080;
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/ {
# в proxy_pass нет path-части, поэтому URI передаётся как есть
proxy_pass \$upstream_app;
+46 -20
View File
@@ -19,28 +19,29 @@ jobs:
exit 1
}
- name: Setup JDK 17
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)
- name: Build and test without fontconfig (PMD+JaCoCo included)
env:
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
if: always()
@@ -103,6 +104,31 @@ jobs:
f"{base}/{existing}" if existing else base, {"body": body})
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:
runs-on: ubuntu-latest
steps:
+5
View File
@@ -44,3 +44,8 @@ DEPLOY.md
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
/.mise/
# Сайт документации: сборка, venv, копия javadoc
site/
docs/.venv/
docs/apidocs/
+105 -103
View File
@@ -1,128 +1,130 @@
# 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
Конвертер `.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-app` | REST API на Spring Boot 4.1.1: 11 классов, единственный `public` — `WordPdfApplication` |
| `wordpdf-web` | SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ |
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API + `internal/` (нормализаторы) + `internal/doc/` (мост) + `internal/chart/` (рендер) + `fonts/`|
|`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL/Bitstream-Vera/Noto), `xslt/docx2fo.xslt`, `slf4j-simple.properties`|
|`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])`
Порядок шагов 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): ядро дополнительно сериализует конвертации монитором `WordPdfConverter.class` (`convert()` безопасен из нескольких потоков); головой очереди на старте стоит `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` от всего, что вне бандла; `font()`/`regular()`/... синхронизированы с `init()` (реестр `VARIANTS`). Внешние `init()`/`restrictToBundled()` во время идущих конвертаций — только под монитором `WordPdfConverter.class`.
- `PhysicalFonts` — глобальный и мутируемый → конвертации сериализуются монитором `WordPdfConverter.class` внутри ядра (общая `FopFactory` и сброс её image-кешей — под тем же монитором); приложение держит однопоточный воркер ради 503/timeout; `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`.
Бутстрап: `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`).
```bash
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
mvn clean verify # то же; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am: core test-jar
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
./mise.sh run verify-nofontconfig # тот же verify в контейнерах без fontconfig (как CI)
mvn test -Djacoco.skip=true # работает: пустой <argLine> по умолчанию в корневом pom
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен: core test-jar
./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
./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 prod-tests # прод-автотесты в prod-autotests/
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
./mise.sh run mem-bench # membench.sh + core MemoryBench (MB_LABEL, --scenario suite|big|all, --dir develop/)
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)
```
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе.
Пересоздание фикстур и перевендоривание стилиста — `docs/agent/repo-map.md`. Деплой: **прод** — на пользовательском LAN-сервере; **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**; пуск — push в `main` или Run workflow, ручных скриптов нет (детали — `docs/agent/ci-cd.md`).
- «Запусти тестовый сервер» (термин пользователя) = 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).
- Деплой — push в `main` → Gitea Actions (детали — `docs/agent/ci-cd.md`); **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`** (вне репо); ручных скриптов нет.
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper`, `DrawMlColor`, Spring-компоненты `wordpdf-app`.
- В `internal/**` классы `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: `normalize`/`STEP`/`declare`/`run`/`check`/`register`; `rewrite`-хуки — package-private. В `wordpdf-app` всё package-private кроме `WordPdfApplication`; в `internal/doc` публичны только `DocToDocx` и `CfbReader`.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`.
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — собственность `WordPdfValidator`; не оборачивать в общий `ConversionException`.
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`).
- Константы UPPER_SNAKE с эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Логирование: `java.util.logging.Logger` в корневом пакете и `internal/`, SLF4J — в `internal/chart` и `wordpdf-app`.
- Тестовые методы: регрессионные — `объект_условие` через 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.
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет). Исключения-экземпляры: `BundledFontMapper`, Spring-компоненты app. В `internal/**` классы package-private; `public` — только вызываемые извне пакета, контракт не расширять.
- Ошибки публичного API — только `ConversionException extends RuntimeException`; `ValidationException` не оборачивать; в chart — деградация вместо падения; текст 500 наружу фиксированный (сообщения ядра логируются, не отдаются).
- Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»).
- Логирование по пакетам: `java.util.logging` — корневой пакет и `internal/` (`WordPdfConverter`, `OleObjectNormalizer`, `DocToDocx`); SLF4J — `internal/chart` (`ChartRenderer`, `DrawingPreRenderer`) и `wordpdf-app`; остальное молчит.
- Модели — `record` (`ConvertOptions`, `BundledFonts.Entry`, `MathRenderer.MathImage`, `ApiError`); константы UPPER_SNAKE с javadoc-обоснованием числа; holder-идиомы для ленивой инициализации (`VendoredXslt.TEMPLATES`); DCL+caches (`sharedFopFactory`, `GlyphFont.CACHE`); compile-time literals там, где важен инлайн (`WordPdfConverter` ↔ `WordPdfValidator`).
- Шрифты: новый шрифт = файл в `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.
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify`, `includeTests=true`, валит любой приоритет): правила не перенастраивать, подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены — нарушения чинятся кодом.
- 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 стенда).
## 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).
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только `java -jar`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}` (список — `GITEA-vars.md`). Локальный `.env` (gitignored) — только для `compose.yml`.
|Файл|Что держать в голове|
|---|---|
|`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`|
|`wordpdf-core/src/main/java/.../WordPdfConverter.java`|весь конвейер, static-блок sysprops, пороги-константы, монитор сериализации|
|`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`)|
|`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`.
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
- 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).
- Веб: только 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
- Гейты: 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`. Плотность покрытия держат тесты, а не заглушки.
- Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры — `.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`.
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре контекста (отдельные классы, не `@Nested`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Core-юниты Spring **не поднимают**; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали — `docs/agent/testing.md`.
- Жизненный цикл: только `@Test`; исключения — два `@BeforeAll` (прогрев шрифтов) и `@AfterEach drainWorker` в `ConversionTimeoutTest`. Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
- Идиомы загрузки фикстур: **core** — classloader без ведущего слэша, **app** — class-relative со слэшем (core test-jar). Синтетика: docx — `ZipOutputStream`, `.doc` — крафт `POIFSFileSystem`.
- Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (`"%PDF".equals(...)`, PMD `LiteralFirstInEquals`); контракт идентичности — `assertSame`/`assertNotSame`. Общих test-util-классов нет: хелперы (`norm`, `pdfText`, `assertRatio`) намеренно продублированы.
- Прод-автотесты: 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.
- Гейты на `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 запрещены и в 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`.
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`), юниты — camelCase (`pageFieldBecomesFldSimple`).
- **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа, живёт только в `WordPdfConverterTest`). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10, эталонные числа Word-рендеров 300 dpi захардкожены). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%PDF".equals(…)`).
- Фикстуры — только закоммиченные `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` — эталоны заказчика, не вывод генераторов).
- Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar).
- 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-тесты, если ключ не запинен свойствами контекста.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1023 теста (core 57/975, app 6/48); детали — `docs/agent/testing.md`.
- Прод-автотесты: 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.
+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 — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
## Возможности
- Поддержка 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-core`):
## Быстрый старт
|Класс|Назначение|
|---|---|
|`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:
Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24,
python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA:
```bash
sh bootstrap.sh # Linux / macOS
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
```
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
```bash
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH
./mise.sh tasks # список задач с описаниями
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен
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|
|`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|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080|
|`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173|
|`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 в шелле и работать напрямую
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
## Сборка
## Документация
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
```bash
mvn clean verify # все модули + тесты
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
```
Результат: `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 требующих его пропускаются.
- **Сайт документации** (пользователю / REST API / библиотека / архитектура /
разработчику / эксплуатация): `http://192.168.88.23:9012/`
— исходники в `docs/`, публикация `./mise.sh run docs-deploy`,
javadoc — там же по `/apidocs/`.
- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`.
- Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge,
chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации
форматов — `docs/standards/`.
- Правила репозитория — `AGENTS.md`.
+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) рисуется поверх области построения, место не резервирует.
Пейнтеры: `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`.
+1 -1
View File
@@ -6,7 +6,7 @@
### 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).
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 |
| 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.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) |
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные |
| 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 встраивает только задекларированные. Конфиг обязан быть **полным при каждом `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.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 |
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
| 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)
Первая конвертация после старта 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-частей).
### Нормализаторы: контракт и правила 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`, текст между тегами не трогается.
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 не попадает); вложенные/битые поля пропускаются.
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.
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.
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.
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.
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.
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`-хука нет.
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. `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. `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. `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. `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. `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»).
+2 -2
View File
@@ -4,6 +4,6 @@
- Известный остаток эталона: 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 вне контура).
+16 -15
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/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `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-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), `BundledFontAliases` (алиасы, `DISPLAY_NAMES`, `bundledFamily` — без наследования, статика безопасна до гейта), `BundledFontMapper` (экземпляр-маппер docx4j), `GlyphFont` (глиф-движок fontbox) |
| `…/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/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/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/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-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, фиксированный 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` в образ **не** копируется (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 |
| `.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, защита ветки, перезапуск — только имена переменных, без значений |
@@ -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/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`); рантайм-конфигурации в ядре нет.
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера.
- Дефолтов лимитов в ядре нет (`WordPdfSettings` упразднён): лимиты входа всегда приходят с вызовом через `ConvertOptions`, производные пороги считает `WordPdfValidator.max*` (см. таблицу выше).
- `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/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, 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).
- `.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.
- `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-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'ов)
Единственный эндпоинт `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`.
Полная карта ответов:
@@ -96,7 +97,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
- **Ключ доступа**: `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.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` + текст зоны).
@@ -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 таблицах).
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`) и защитные ветви сканеров нормализаторов/валидатора.
- Счётчики тестов и описание блока аудита .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)
- 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
@@ -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`).
- 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 против живого прода.
@@ -31,5 +31,5 @@
- `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается.
- `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 продублирован в обоих тестовых классах).
- Синтетика через общий хелпер `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`.
+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_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/ {
# в proxy_pass нет path-части, поэтому URI передаётся как есть
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)"
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]
description = "Исполняемый jar бэкенда"
run = "mvn -pl wordpdf-app -am package"
@@ -46,3 +54,33 @@ run = "npm run dev"
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
dir = "prod-autotests"
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"
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">
<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">
<!-- opinionated/шумные, намеренно выключены -->
<exclude name="AtLeastOneConstructor"/>
<exclude name="CallSuperInConstructor"/>
<exclude name="CommentDefaultAccessModifier"/>
<exclude name="ConfusingTernary"/>
<exclude name="FieldDeclarationsShouldBeAtStartOfClass"/>
<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/bestpractices.xml/ForLoopCanBeForeach"/>
<rule ref="category/java/design.xml/ExceptionAsFlowControl"/>
<rule ref="category/java/errorprone.xml/EqualsNull"/>
<rule ref="category/java/errorprone.xml/CloseResource"/>
<rule ref="category/java/errorprone.xml/BrokenNullCheck"/>
<rule ref="category/java/bestpractices.xml/AvoidPrintStackTrace"/>
<rule ref="category/java/errorprone.xml/AvoidLosingExceptionInformation"/>
<rule ref="category/java/errorprone.xml/AvoidLiteralsInIfCondition"/>
<rule ref="category/java/errorprone.xml/EmptyCatchBlock">
<priority>2</priority>
</rule>
<rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach">
<priority>2</priority>
</rule>
<rule ref="category/java/errorprone.xml/AvoidCatchingNPE"/>
<rule ref="category/java/errorprone.xml/AssignmentToNonFinalStatic"/>
<rule ref="category/java/errorprone.xml/DoNotCallGarbageCollectionExplicitly"/>
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"/>
<rule ref="category/java/errorprone.xml/CompareObjectsWithEquals"/>
<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>
+24 -1
View File
@@ -39,6 +39,8 @@
<!-- Покрытие: последняя стабильная на Maven Central -->
<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 не споткнётся
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
<argLine></argLine>
@@ -156,10 +158,31 @@
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.1</version>
</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>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.28.0</version>
<version>3.21.2</version>
<configuration>
<rulesets>
<ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset>
+3 -3
View File
@@ -8,9 +8,9 @@ WORDPDF_BASE_URL обязателен: без него все проверки
не знает ни одного хоста. WORDPDF_API_KEY факультативен: без него проверки,
где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа
нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт 100 =
дефолт ядра). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
5 = дефолт ядра). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт эндпоинта
100). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
эндпоинта 5). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
либо из WORDPDF_SAMPLES_DIR.
"""
@@ -63,11 +63,17 @@ final class ApiExceptionHandler {
.body(new ApiError(e.getMessage()));
}
/** Ошибка ядра/рендера при формально корректном входе. */
/**
* Ошибка ядра/рендера при формально корректном входе. Сообщение ядра
* (тексты docx4j/FOP/JAXB, пути temp-файлов) — только в лог: наружу
* фиксированный текст, иначе 500 становится каналом внутренней информации.
* Регрессия — ConvertControllerTest#conversionFailure_hidesInternalDetails.
*/
@ExceptionHandler(ConversionFailedException.class)
ResponseEntity<ApiError> conversionFailed(ConversionFailedException e) {
LOG.error("Конвертация не удалась", e);
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 org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import ru.pjandro.wordpdf.ChartsFoundException;
import ru.pjandro.wordpdf.ConvertOptions;
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.WordPdfValidator;
import ru.pjandro.wordpdf.ValidationException;
@@ -35,10 +37,11 @@ import java.util.concurrent.TimeoutException;
* {@link ValidationException} (400), ошибка рендер-стадии →
* {@link ConversionFailedException} (500). Граница: сломанный контейнер
* (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный
* zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди и
* в конвейере ядра вход проверяется тем же
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}, поэтому уже
* принятый запрос внутренняя проверка ядра в ошибку не превратит.</p>
* zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди
* проверяется только размер, корректность контейнера и число страниц —
* сериализованно внутри воркера (ядро вызывает тот же
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}), поэтому
* тяжёлая проверка не занимает потоки контейнера в обход сериализации.</p>
*/
@Service
final class ConversionService {
@@ -64,9 +67,9 @@ final class ConversionService {
}
/**
* Полный путь: синхронная валидация байтов (до очереди — от obvious-отказа
* единый воркер не должен быть занят) → постановка в очередь → ожидание
* результата с таймаутом.
* Полный путь: синхронная проверка размера (до очереди) → постановка
* в очередь → ожидание результата с таймаутом; корректность контейнера
* и число страниц проверяются сериализованно, внутри воркера (ядро).
*
* @throws ValidationException некорректный вход (400)
* @throws ConversionFailedException ошибка ядра/рендера (500)
@@ -78,14 +81,14 @@ final class ConversionService {
* {@code null} не допускается (контроллер строит всегда).</p>
*/
byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) {
// Бинарный .doc — не zip: .docx-валидация к нему неприменима, размер
// проверяется общим checkInput, страницы — мостом по чистому .doc
// (ядро бросит ValidationException → 400 тем же обработчиком).
if (WordPdfValidator.isBinaryDoc(docxBytes)) {
WordPdfValidator.checkInput(docxBytes, options.maxMb());
} else {
WordPdfValidator.validate(docxBytes, options);
}
// До очереди — только дешёвый гейт размера. Полная валидация
// (контейнер + страницы — до двух полных распакованных проходов до
// 64 МБ на обоих форматах) сериализована воркером: её выполняет ядро
// внутри WordPdfConverter.convert (тот же validate с теми же
// options, ValidationException → 400 тем же путём). Синхронный
// полный validate до submit отдавал бы zip-бомбе потоки Tomcat
// в обход сериализации.
WordPdfValidator.checkInput(docxBytes, options.maxMb());
Future<byte[]> future;
try {
future = workers.submit(() -> doConvert(docxBytes, originalFilename, options));
@@ -140,10 +143,14 @@ final class ConversionService {
// отказ проверки страниц внутри конвейера ядра — некорректный
// вход (400), а не ошибка рендера: без этого утонул бы в 500
throw e;
} catch (DrawingFoundException e) {
} catch (ChartsFoundException e) {
// отказ по настройке запроса (error-флаг) — не ошибка рендера: 422,
// иначе утонет в общем 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) {
// всё, что упало на валидации/рендер-стадии ядра, — ошибка преобразования, 500
throw new ConversionFailedException("Не удалось конвертировать документ: "
@@ -12,7 +12,6 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.multipart.MultipartFile;
import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.WordPdfSettings;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
@@ -25,10 +24,11 @@ import java.util.Locale;
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
* зона {@link ConversionService}. Ошибки в JSON-ответ переводит
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера
* (свойства {@code wordpdf.max-mb}/{@code wordpdf.max-pages}, env
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}); параметрами запроса
* они не переопределяются.</p>
* {@link ApiExceptionHandler}. Лимиты входа: свойства
* {@code wordpdf.max-mb}/{@code wordpdf.max-pages} (env
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}) — дефолт эндпоинта;
* параметры запроса {@code maxMb}/{@code maxPages} переопределяют его в обе
* стороны (значения ≤ 0 → 400).</p>
*/
@RestController
final class ConvertController {
@@ -38,14 +38,15 @@ final class ConvertController {
private final int maxPages;
/**
* Дефолт плейсхолдеров — константы ядра через SpEL: буквальное значение
* в свойствах не дублируется. Невалидное значение (<= 0) роняет
* Дефолт плейсхолдеров — буквенные литералы 5/100 (дефолтов лимитов в
* ядре нет); свойства/env переопределяют их, параметры запроса — см.
* {@link #convert}. Невалидное значение свойства (<= 0) роняет
* приложение на старте (fail-fast): «сервис поднят, но весь вход
* отсекается» — худший исход, чем не поднявшийся сервис.
*/
ConvertController(ConversionService conversionService,
@Value("${wordpdf.max-mb:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_INPUT_MB}}") long maxMb,
@Value("${wordpdf.max-pages:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_PAGES}}") int maxPages) {
@Value("${wordpdf.max-mb:5}") long maxMb,
@Value("${wordpdf.max-pages:100}") int maxPages) {
if (maxMb <= 0) {
throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
}
@@ -60,10 +61,11 @@ final class ConvertController {
@Operation(summary = "Конвертировать .docx/.doc в PDF",
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
+ "настройки ядра (ошибка не выбрасывается); диаграммы/SmartArt "
+ "ошибка не выбрасывается; диаграммы/SmartArt "
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются")
+ "Лимиты входа (размер/страницы): свойства wordpdf.max-mb/wordpdf.max-pages — "
+ "дефолт; параметры запроса maxMb/maxPages переопределяют его в обе стороны "
+ "(значения ≤ 0 → 400)")
@SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping(
path = "/api/v1/convert",
@@ -73,7 +75,9 @@ final class ConvertController {
@RequestParam("file") MultipartFile file,
@RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts,
@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()) {
throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)");
}
@@ -84,13 +88,24 @@ final class ConvertController {
// .doc (Word 97–2003) переносится в .docx мостом internal.doc
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 МБ)
// больше логического лимита входа (wordpdf.max-mb), и без этого гварда
// заведомо oversized-upload сначала материализовался бы в куче.
// больше логического лимита входа, и без этого гварда заведомо
// oversized-upload сначала материализовался бы в куче.
// Текст — тот же формат, что WordPdfValidator.checkInput.
long maxBytes = maxMb * 1024 * 1024;
long maxBytes = effMaxMb * 1024 * 1024;
if (file.getSize() > maxBytes) {
throw new BadRequestException("Файл больше " + maxMb + " МБ: "
throw new BadRequestException("Файл больше " + effMaxMb + " МБ: "
+ file.getSize() + " байт > " + maxBytes + " байт");
}
byte[] docxBytes;
@@ -100,10 +115,10 @@ final class ConvertController {
throw new BadRequestException("Не удалось прочитать загруженный файл", e);
}
ConvertOptions options = new ConvertOptions(
errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS,
errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART,
errorOnOle != null ? errorOnOle : WordPdfSettings.ERROR_ON_OLE,
maxMb, maxPages);
Boolean.TRUE.equals(errorOnCharts),
Boolean.TRUE.equals(errorOnSmartArt),
Boolean.TRUE.equals(errorOnOle),
effMaxMb, effMaxPages);
byte[] pdf = conversionService.convert(docxBytes, name, options);
ContentDisposition disposition = ContentDisposition.attachment()
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
@@ -1,28 +1,25 @@
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-флаге
* ({@link DrawingFoundException} ядра).
* ({@link ChartsFoundException}, {@link SmartArtFoundException} или
* {@link OleFoundException} ядра).
*
* <p>Маппится в HTTP 422 ({@link ApiExceptionHandler}); клиенту осмысленно
* повторить без error-флага. Текст сообщения —
* пользовательский контракт: фронт показывает его дословно.</p>
* повторить без error-флага.</p>
*/
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)
// падает на switch-выражении в аргументе super (pmd/pmd#6234).
private static String message(DrawingFoundException.Kind kind) {
return switch (kind) {
case CHARTS -> "Конвертация отменена: в документе найдены диаграммы";
case SMARTART -> "Конвертация отменена: в документе найден SmartArt";
case OLE -> "Конвертация отменена: в документе найдены OLE-объекты";
};
DrawingRejectedException(String message) {
super(message);
}
}
@@ -1,12 +1,12 @@
spring.application.name=wordpdf-app
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный
# лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ), по умолчанию
# WordPdfSettings.MAX_INPUT_MB = 5; здесь только потолок загрузки.
# Лимиты входа: env WORDPDF_MAX_MB (МБ) / WORDPDF_MAX_PAGES (страницы),
# дефолты — константы ядра (5 / 100), задаются ConvertController.
# Значение <= 0 — падение на старте. Сами ключи здесь не объявлены:
# пустое значение затенит SpEL-дефолт @Value.
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Логический лимит
# входа — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ) /
# wordpdf.max-pages (env WORDPDF_MAX_PAGES): дефолты 5/100 — литералы @Value
# в ConvertController (дефолтов лимитов в ядре нет); параметрами запроса
# maxMb/maxPages дефолт переопределяется в обе стороны. Значение свойства
# <= 0 — падение на старте. Сами ключи здесь не объявлены: пустое значение
# затенит дефолт @Value.
# file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap
# держит только копию getBytes() одной сериализованной конвертации (порог 100MB
# буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл
@@ -92,7 +92,7 @@ class ConversionServiceTest {
byte[] sample = bytes("/samples/ru-plain.docx");
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());
} finally {
block.countDown();
@@ -115,7 +115,7 @@ class ConversionServiceTest {
try {
Thread.currentThread().interrupt();
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());
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));
svc.shutdown();
}
@@ -30,7 +30,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/
@SpringBootTest
@AutoConfigureMockMvc
@TestPropertySource(properties = "wordpdf.convert-timeout=1ms")
@TestPropertySource(properties = {"wordpdf.convert-timeout=1ms",
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
// (mise подмешивает корневой .env в окружение тасок)
"wordpdf.api-key="})
class ConversionTimeoutTest {
private static final MediaType DOCX =
@@ -44,7 +44,8 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
* ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны
* {@code WordPdfConverterTest} (norm/pdfText).
*/
@SpringBootTest
@SpringBootTest(properties = "wordpdf.api-key=") // пустой = фильтр выключен; пин от
// ambient WORDPDF_API_KEY (mise подмешивает корневой .env в окружение тасок)
@AutoConfigureMockMvc
class ConvertControllerTest {
@@ -188,7 +189,8 @@ class ConvertControllerTest {
/**
* errorOnSmartArt=true — HTTP 422 с текстом про SmartArt (диаграммы
* конвертируются, их error-флаг выключен, поэтому бросается целевой Kind).
* конвертируются, их error-флаг выключен, поэтому бросается
* {@code SmartArtFoundException}).
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
* фикстура samples/charts-smartart.docx.
*/
@@ -311,8 +313,8 @@ class ConvertControllerTest {
@Test
void oversizedOverCoreLimit_rejected() throws Exception {
// 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ)
// и отсекается валидацией ядра до очереди (дефолт ядра цел —
// лимит задаёт только конфигурация сервера)
// и отсекается валидацией ядра до очереди (дефолт эндпоинта 5 МБ —
// параметры запроса здесь не участвуют)
byte[] big = new byte[5 * 1024 * 1024 + 1];
mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big)))
.andExpect(status().isBadRequest())
@@ -321,20 +323,60 @@ class ConvertControllerTest {
}
/**
* Регрессия env-only: лимиты входа параметрами запроса не задаются.
* maxMb/maxPages в multipart-форме игнорируются — маленький
* документ проходит на серверных лимитах (дефолты ядра).
* Параметр запроса maxMb ужимает серверный дефолт: файл в пределах
* серверных 5 МБ отвергается по параметру 1 МБ (текст гварда — с
* числом из запроса).
*/
@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")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxMb", "1000")
.param("maxPages", "1"))
.param("maxPages", "1000"))
.andExpect(status().isOk())
.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):
* «сервис поднят, но весь вход отсекается» хуже не поднявшегося.
@@ -417,8 +459,14 @@ class ConvertControllerTest {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("bad.docx", docxPackageWithGarbage())))
.andExpect(status().isInternalServerError())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("Не удалось конвертировать")));
// фиксированный текст: сообщение ядра (docx4j/FOP/JAXB) —
// только в лог, наружу не уходит
.andExpect(jsonPath("$.error").value("Не удалось конвертировать документ"))
.andExpect(result -> {
String body = result.getResponse().getContentAsString();
assertTrue(!body.contains("docx4j") && !body.contains("Exception"),
"500 протёк внутренними деталями: " + body);
});
}
@Test
@@ -474,7 +522,7 @@ class ConvertControllerTest {
ConvertController controller =
new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100);
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());
}
}
@@ -35,7 +35,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/
@SpringBootTest
@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 {
private static final MediaType DOCX =
@@ -90,4 +93,26 @@ class ConvertLimitsTest {
.andExpect(jsonPath("$.error",
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>
<groupId>org.docx4j</groupId>
<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>
<!-- Простой логгер в консоль (slf4j). Обязателен: без него docx4j
пишет предупреждение прямо в выходной PDF. -->
@@ -125,6 +143,15 @@
</execution>
</executions>
</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>
</build>
</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-флаги рисунков и лимиты входа (размер/страницы).
* Дефолты — константы {@link WordPdfSettings}; вызывающий (например, REST API)
* может переопределить их на конкретный вызов. Диаграммы/SmartArt
* Дефолтов в ядре нет — значения задаёт вызывающий (приложение: свойства
* сервера как дефолт REST-эндпоинта + параметры запроса). Диаграммы/SmartArt
* конвертируются всегда.
*
* @param errorOnCharts бросать {@link DrawingFoundException} при находке диаграмм
* @param errorOnSmartArt бросать {@link DrawingFoundException} при находке SmartArt
* @param errorOnOle бросать {@link DrawingFoundException} при находке OLE-объектов
* @param errorOnCharts бросать {@link ChartsFoundException} при находке диаграмм
* @param errorOnSmartArt бросать {@link SmartArtFoundException} при находке SmartArt
* @param errorOnOle бросать {@link OleFoundException} при находке OLE-объектов
* (иначе — тихо удалить их из документа)
* @param maxMb лимит размера входа в МБ (MiB) на этот вызов;
* дефолт — {@link WordPdfSettings#MAX_INPUT_MB}
* @param maxPages лимит числа страниц на этот вызов;
* дефолт — {@link WordPdfSettings#MAX_PAGES}
* должен быть больше 0
* @param maxPages лимит числа страниц на этот вызов; должен быть больше 0
*/
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnOle,
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)");
}
}
@@ -31,6 +31,7 @@ import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import javax.xml.transform.Templates;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.stream.StreamSource;
import javax.imageio.ImageIO;
import java.io.InputStream;
@@ -100,10 +101,11 @@ public final class WordPdfConverter {
* каждого изображения (замер 2026-11: ~1,5 ГБ живых byte[] после 30
* конвертаций с картинками). Поэтому каждая конвертация обязана вызвать
* {@link #resetSharedImageCaches()} в finally. Вызывается только под локом
* конвертации (см. {@code convert}), сброс mid-render невозможен.
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
* конвертации (см. {@code convert}), сброс mid-render невозможен. Методы
* приватны: вызов вне лока конвертера вскрыл бы DCL/сброс на параллельный
* рендер. Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
*/
static FopFactory sharedFopFactory(final FOSettings foSettings) {
private static FopFactory sharedFopFactory(final FOSettings foSettings) {
FopFactory factory = sharedFopFactory;
if (factory == null) {
synchronized (WordPdfConverter.class) {
@@ -130,7 +132,7 @@ public final class WordPdfConverter {
* {@code convert}) — параллельный рендер под сброс не попадает.
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
*/
static void resetSharedImageCaches() {
private static void resetSharedImageCaches() {
FopFactory factory = sharedFopFactory;
if (factory == null) {
return;
@@ -144,37 +146,10 @@ public final class WordPdfConverter {
/**
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
* определяется по сигнатуре байтов) в PDF. Работа с файлами — забота
* определяется по сигнатуре байтов) в PDF с настройками на вызов:
* error-флаги диаграмм/SmartArt и лимиты входа. Работа с файлами — забота
* вызывающего (файловое API было здесь раньше; ядро пути не принимает).
*
* <p>.doc предварительно переносится в .docx мостом
* {@link ru.pjandro.wordpdf.internal.doc.DocToDocx} (текст + прямое
* форматирование); число страниц для .doc проверяется мостом по чистому
* бинарному документу (кэш PageCount + явные разрывы), сгенерированный
* .docx валидацией не проверяется. Для .docx вход проверяется
* {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера:
* {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_MB} (МБ) / zip-подпись /
* число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет;
* страницы считаются ровно раз по сырому входу, повторного скана по
* нормализованным байтам нет (см. 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 {
return convert(docxBytes, title, ConvertOptions.defaults());
}
/**
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
* определяется по сигнатуре байтов, см. перегрузку выше) в PDF с
* настройками на вызов: error-флаги диаграмм/SmartArt и лимиты входа.
*
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)}
* до рендера — одна проверка на оба формата: {@code null} / размер больше
* {@code options.maxMb()} (МБ) / не .docx и не .doc / число страниц больше
@@ -182,15 +157,15 @@ public final class WordPdfConverter {
* считаются ровно раз по сырому входу, до аллокаций docx4j: для .docx —
* lightweight-скан по zip, для .doc — по чистому бинарному документу до
* конвертации. Повторного скана по нормализованным байтам нет: правила
* 1–10 {@code DocxRewritePipeline} число учитываемых разрывов не
* увеличивают (правило 9 способно только убрать разрыв внутри скрытого
* 1–11 {@code DocxRewritePipeline} число учитываемых разрывов не
* увеличивают (правило 10 способно только убрать разрыв внутри скрытого
* рана — счёт по сырому входу остаётся верхней оценкой лимита), а скан
* внутри живой JAXB-модели удваивал бы пиковую память.
*
* @param docxBytes байты .docx или бинарного .doc
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @param options error-флаги и лимиты входа на этот вызов; {@code null} —
* дефолты (константы {@link WordPdfSettings})
* @param options error-флаги и лимиты входа на этот вызов; обязательны,
* {@code null} → {@link ValidationException} (дефолтов в ядре нет)
* @return байты готового PDF
* @throws ValidationException некорректный вход: {@code null}, размер больше
* {@code options.maxMb()} (МБ), не .docx/.doc, зашифрованный .doc,
@@ -198,7 +173,11 @@ public final class WordPdfConverter {
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/
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 —
@@ -218,7 +197,8 @@ public final class WordPdfConverter {
// (реентельно) и DCL в sharedFopFactory. Регрессия —
// WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
synchronized (WordPdfConverter.class) {
docxBytes = WordPdfValidator.isBinaryDoc(docxBytes) ? DocToDocx.convert(docxBytes) : docxBytes;
docxBytes = WordPdfValidator.isBinaryDoc(docxBytes)
? DocToDocx.convert(docxBytes, opts.maxMb()) : docxBytes;
ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length));
try {
convertToStream(docxBytes, title, opts, bos);
@@ -228,6 +208,11 @@ public final class WordPdfConverter {
throw e;
} catch (Exception e) {
throw new ConversionException("Не удалось конвертировать документ", e);
} catch (StackOverflowError e) {
// Глубокая вложенность XML: JAXB-разбор рекурсивен и может
// разогнать стек раньше капы MathModel — детерминированный
// отказ вместо Error.
throw new ConversionException("Не удалось конвертировать документ", e);
}
return bos.toByteArray();
}
@@ -238,6 +223,32 @@ public final class WordPdfConverter {
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 с
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
@@ -256,7 +267,7 @@ public final class WordPdfConverter {
return;
}
try {
convert(warmupDocx(), "warmup");
convert(warmupDocx(), "warmup", new ConvertOptions(false, false, false, 1, 1));
warmRaster();
warmedUp = true;
} catch (Throwable t) {
@@ -395,7 +406,8 @@ public final class WordPdfConverter {
LayoutPostRenderer.register(foSettings);
// 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);
@@ -411,21 +423,26 @@ public final class WordPdfConverter {
// 6. Проход XSLT (медленнее, но полнее), вывод в поток
Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
} finally {
// 7. Уборка временных файлов встроенных в docx шрифтов и сброс
// 7. Уборка временных файлов встроенных в docx шрифтов, сброс
// имиджевых кешей общей FopFactory (без него форк копит растр
// каждого изображения: ~1,5 ГБ на 30 конвертаций, 2026-11).
// каждого изображения: ~1,5 ГБ на 30 конвертаций, 2026-11) и
// возврат реестра шрифтов в бандл-состояние: load() регистрирует
// в глобальном PhysicalFonts встроенные шрифты документа, и без
// restrictToBundled последний документ продолжал бы влиять на
// выбор шрифта до следующей конвертации.
if (pkg.getMainDocumentPart() != null
&& pkg.getMainDocumentPart().getFontTablePart() != null) {
pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
}
resetSharedImageCaches();
// Примечание: в docx4j 11.x OpcPackage.close() отсутствует —
BundledFonts.restrictToBundled();
// Примечание: в docx4j 17.x OpcPackage.close() отсутствует —
// пакет загружается в память и ничего не закрывает.
}
}
/**
* Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–10
* Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–11
* одним zip-проходом {@code DocxRewritePipeline} + условная OLE-вычистка)
* и {@code WordprocessingMLPackage.load} полученного transitional-байта.
* Нормализация переиспользует слот {@code bytes}: каждая замена массива
@@ -443,29 +460,33 @@ public final class WordPdfConverter {
/**
* Конвейер байтовой нормализации docx. Порядок фиксирован: сначала один
* zip-проход переписывания XML-частей (внутри части порядок рерайтов
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→
* Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→
* NumberingSuffix→Hidden→Ruby значим: Strict первым — дальше transitional-байт;
* GlyphCoverage — по финальному тексту рана; Hidden — вырезает скрытые
* раны по финальному содержимому; Ruby — разворачивает руби-разметку,
* которую схема docx4j не биндит), затем OleObjectNormalizer
* (меняет части, а не XML ранов).
* MathFallback — деградирует OMML-формулы в текст m:t, когда JEuclid
* недоступен, и следующий GlyphCoverage покрывает этот текст кириллицей
* бандла; GlyphCoverage — по финальному тексту рана; Hidden — вырезает
* скрытые раны по финальному содержимому; Ruby — разворачивает
* руби-разметку, которую схема docx4j не биндит), затем
* OleObjectNormalizer (меняет части, а не XML ранов).
* Регрессии каждого рерайта — в javadoc соответствующего нормализатора.
*/
private static List<DocxNormalizer> normalizers(ConvertOptions options) {
return List.of(
// один zip-проход: strict→transitional, on/off, Symbol-PUA,
// поля PAGE/NUMPAGES, невидимки, покрытие глифов, tblInd при
// jc≠left, suff=space, скрытый текст (vanish) — порядок
// поля PAGE/NUMPAGES, невидимки, OMML-фолбэк в текст, покрытие
// глифов, tblInd при jc≠left, suff=space, скрытый текст
// (vanish), снятие обёртки w:ruby — порядок
// рерайтов внутри части фиксирован (DocxRewritePipeline)
DocxRewritePipeline.STEP,
// OLE-объекты: при выключенном errorOnOle тихо удаляем
// (часть/rels/w:object), при включённом — DrawingFoundException
// (часть/rels/w:object), при включённом — OleFoundException
// (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML
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 setCustomXsltTemplates} в {@code Templates} — компилируем заранее;
* {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс.
@@ -480,7 +501,7 @@ public final class WordPdfConverter {
throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден");
}
return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt));
} catch (Exception e) {
} catch (IOException | TransformerConfigurationException 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>Лимиты по умолчанию:
* <ul>
* <li>{@link WordPdfSettings#MAX_INPUT_MB} — максимальный размер входного .docx (МБ);</li>
* <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц;</li>
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_MB} — потолок суммарного
* распакованного размера архива (МБ);</li>
* <li>{@link WordPdfSettings#MAX_ZIP_ENTRIES} — потолок числа записей
* в архиве.</li>
* </ul>
* Первые два переопределяются на вызов: перегрузками с явным лимитом или
* {@link ConvertOptions} (конвертер {@link WordPdfConverter} применяет их сам).
* Последние два — защитные константные пороги ({@link #validate(byte[], ConvertOptions)}),
* {@link ConvertOptions} их не переопределяет.
* <p>Лимитов-констант в ядре нет: все пороги выводятся из лимитов входа
* {@link ConvertOptions} ({@code maxMb} — размер в МБ, {@code maxPages} —
* число страниц): бюджеты распаковки {@link #maxDecompressedBytes(long, int)}
* и {@link #maxDecompressedXmlBytes(long, int)}, порог площади растра
* {@link #maxImagePixels(long)}, потолок числа zip-записей
* {@code maxZipEntries} (package-private) — коэффициенты в
* {@link WordPdfConverter}. Конвертер применяет {@link ConvertOptions} сам;
* одноаргументных оверлодов-дефолтов нет — лимит задаётся параметром каждого
* метода.
*
* <p>Проверка контейнера: архив обязан декларировать документ
* wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx
@@ -70,6 +66,15 @@ public final class WordPdfValidator {
/** Элемент-контейнер body, внутри которого sectPr — межсекционный разрыв. */
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;. */
private static final String APP_PART = "docProps/app.xml";
@@ -79,15 +84,6 @@ public final class 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 байт.
@@ -98,7 +94,17 @@ public final class WordPdfValidator {
if (docxBytes == null) {
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) {
throw new ValidationException("Файл больше " + maxMb + " МБ: "
+ docxBytes.length + " байт > " + maxBytes + " байт");
@@ -111,7 +117,7 @@ public final class WordPdfValidator {
* такой вход не проверяется .docx-валидацией (zip-пути), его страницы
* считает мост {@code internal.doc} по чистому бинарному документу.
*/
public static boolean isBinaryDoc(byte[] bytes) {
static boolean isBinaryDoc(byte[] bytes) {
byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
if (bytes == null || bytes.length < sig.length) {
@@ -154,19 +160,13 @@ public final class WordPdfValidator {
* .docx-манифест и распакованный размер (регрессия —
* {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать
* {@code checkPageCount} напрямую допустимо только над доверенным входом.
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES}
*/
public static void checkPageCount(byte[] docxBytes) throws ValidationException {
checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCount(byte[])}, с явным лимитом
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
*
* <p>Лимит страниц задаётся параметром (переопределение на вызов,
* см. {@link ConvertOptions#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) {
throw new ValidationException("Не указаны байты входного .docx");
}
@@ -215,17 +215,7 @@ public final class WordPdfValidator {
* разрывы 0x0C − непрерывные межсекционные разрывы + абзацы с
* pageBreakBefore)} — тот же контур, что lightweight-скан по zip для
* .docx. Разбор делает {@code internal.doc} ({@link DocToDocx#countPages(byte[])}).
*
* @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()}).
* Лимит страниц задаётся параметром (см. {@link ConvertOptions#maxPages()}).
*
* <p>Отказ разбора {@code .doc}-моста ({@code internal.doc}) —
* {@link ConversionException} — оборачивается здесь в
@@ -237,7 +227,7 @@ public final class WordPdfValidator {
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
* или превышении {@code maxPages}
*/
public static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
if (docBytes == null) {
throw new ValidationException("Не указаны байты входного .doc");
}
@@ -273,18 +263,25 @@ public final class WordPdfValidator {
* <p>Проверка контейнера: в {@code [Content_Types].xml} обязана быть
* декларация документа wordprocessingml (архив без неё — не .docx);
* zip-бомба отсекается потоковым счётчиком распакованных байт
* ({@link WordPdfSettings#MAX_DECOMPRESSED_MB}) и числом записей
* ({@link WordPdfSettings#MAX_ZIP_ENTRIES}) — до разбора содержимого
* в {@link #checkPageCount(byte[], int)}. Оба лимита —
* защитные пороги, {@link ConvertOptions} их не переопределяет.
* ({@link #maxDecompressedBytes(long, int)}, XML —
* {@link #maxDecompressedXmlBytes(long, int)}) и числом записей
* ({@code maxZipEntries}) — до разбора содержимого
* в {@link #checkPageCount(byte[], int)}. Все пороги — производные от
* {@code options.maxMb()}/{@code options.maxPages()}, отдельных
* констант в ядре нет.
* Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected},
* {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected},
* {@code #validate_tooManyEntriesRejected}.</p>
* @throws ValidationException при {@code null}, превышении {@code options.maxMb()},
* @throws ValidationException при {@code null} входа или {@code options},
* превышении {@code options.maxMb()},
* отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы,
* ошибке разбора zip или превышении {@code options.maxPages()}
*/
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException {
if (options == null) {
throw new ValidationException("Не переданы параметры конвертации (ConvertOptions): "
+ "лимиты входа задаёт вызывающий");
}
checkInput(docxBytes, options.maxMb());
if (isBinaryDoc(docxBytes)) {
// Бинарный .doc: страницы — по чистому бинарному документу,
@@ -296,7 +293,18 @@ public final class WordPdfValidator {
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
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());
}
@@ -306,30 +314,60 @@ public final class WordPdfValidator {
* в {@link #checkPageCount(byte[], int)}) и наличие в
* {@code [Content_Types].xml} декларации документа wordprocessingml
* (архив без неё — не .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 {
long maxTotal = WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024;
private static void checkDocxContainer(byte[] docxBytes, long maxTotal, long maxXmlTotal,
long maxEntries, long maxPixels)
throws ValidationException {
long total = 0;
long xmlTotal = 0;
int entries = 0;
// OPC требует уникальных имён частей: дубликат — либо крафт, либо
// обход кэша страниц (валидатор читает ПЕРВУЮ партию document.xml,
// парсер может взять другую) — отказ по первому повтору имени.
Set<String> names = new HashSet<>();
ByteArrayOutputStream ctBuf = new ByteArrayOutputStream();
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
if (!names.add(entry.getName())) {
throw new ValidationException("Дубликаты записей в архиве: " + entry.getName());
}
if (!entry.isDirectory()) {
entries++;
if (entries > WordPdfSettings.MAX_ZIP_ENTRIES) {
if (entries > maxEntries) {
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];
int n;
while ((n = zip.read(buf)) > 0) {
total += n;
if (total > maxTotal) {
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 (ctBuf.size() + n > 8 * 1024 * 1024) {
@@ -338,6 +376,18 @@ public final class WordPdfValidator {
}
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) {
@@ -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 МБ — наивного поиска достаточно). */
private static boolean containsAscii(byte[] data, String needle) {
byte[] pat = needle.getBytes(StandardCharsets.UTF_8);
@@ -372,6 +471,89 @@ public final class WordPdfValidator {
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). */
private static boolean isHeaderFooterPart(String name) {
return (name.startsWith("word/header") || name.startsWith("word/footer"))
@@ -407,7 +589,7 @@ public final class WordPdfValidator {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT
&& "Pages".equals(xr.getLocalName())) {
&& PAGES_ELEMENT.equals(xr.getLocalName())) {
String text = xr.getElementText().trim();
return Math.max(0, Integer.parseInt(text));
}
@@ -496,7 +678,7 @@ public final class WordPdfValidator {
// различает финальную и межсекционные)
}
case "type" -> {
if (inBodySectPr && "sectPr".equals(parent)) {
if (inBodySectPr && SECTION_PROPERTIES.equals(parent)) {
sectTypeVal = attrLocal(xr, "val");
}
}
@@ -504,7 +686,7 @@ public final class WordPdfValidator {
}
}
} else if (ev == XMLStreamReader.END_ELEMENT) {
if ("sectPr".equals(xr.getLocalName()) && inBodySectPr) {
if (SECTION_PROPERTIES.equals(xr.getLocalName()) && inBodySectPr) {
if (pendingNewPageSection) {
bodyDirectSectPr++;
}
@@ -537,7 +719,7 @@ public final class WordPdfValidator {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT
&& "br".equals(xr.getLocalName()) && isPageBreak(xr)) {
&& BREAK_ELEMENT.equals(xr.getLocalName()) && isPageBreak(xr)) {
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.wml.Fonts;
import java.util.HashMap;
import java.util.LinkedHashSet;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
/**
@@ -15,7 +13,8 @@ import java.util.Set;
*
* Стратегия (см. {@link #populateFontMappings}):
* 1. Частые MS-шрифты заменяются метрически совместимыми open-source
* аналогами (таблица алиасов) — они есть в jar и содержат кириллицу.
* аналогами (таблица алиасов {@link BundledFontAliases}) — они есть в
* jar и содержат кириллицу.
* 2. Нераспознанные шрифты передаются родительскому
* {@link BestMatchingMapper} (совпадение по Panose-кодам среди
* доступных шрифтов).
@@ -27,95 +26,30 @@ import java.util.Set;
* файл для каждого начертания. Ключи register*Form — точное имя из
* документа: 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
* запускает обнаружение системных шрифтов, которые могут занять те же
* имена в реестре docx4j. Поэтому {@code BundledFonts.init()} нужно
* вызывать ПОСЛЕ создания маппера, чтобы бандл-шрифты оказались в
* реестре поверх системных.
* реестре поверх системных. Таблица алиасов вынесена в
* {@link BundledFontAliases}, чтобы обращение к ней не инициировало этот
* класс до гейта {@code WordPdfConverter.<clinit>}.
*/
public class BundledFontMapper extends BestMatchingMapper {
/**
* Алиасы: имя шрифта из документа (lowercase) -> бандл-семейство (lowercase).
* Croscore (Arimo/Tinos/Cousine) и crosextra (Carlito/Caladea) шрифты
* метрически совместимы с соответствующими MS-шрифтами и содержат
* кириллицу.
*/
private static final Map<String, String> ALIASES;
/** Финальный fallback: шрифт с гарантированной кириллицей. */
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(...)}: для каждого
* имени шрифта, использованного в документе, нужно определить, каким
@@ -126,21 +60,21 @@ public class BundledFontMapper extends BestMatchingMapper {
*/
@Override
public void populateFontMappings(Set<String> documentFontNames, Fonts wmlFonts) throws Exception {
// Виртуальное имя для символов U+2000–U+2EFF (см. SYMBOL_FONT):
// Виртуальное имя для символов U+2000–U+2EFF (см. BundledFontAliases.SYMBOL_FONT):
// маппим сразу, чтобы оно не попало в remaining и родительский
// BestMatchingMapper не пытался искать его в fontTable (и не логировал
// "Font Segoe UI Symbol not found in font table!").
if (BundledFonts.regular(FALLBACK_FAMILY) != null) {
mapFamily(SYMBOL_FONT, FALLBACK_FAMILY);
mapFamily(BundledFontAliases.SYMBOL_FONT, FALLBACK_FAMILY);
}
Set<String> remaining = new LinkedHashSet<>();
for (String docFontName : documentFontNames) {
if (SYMBOL_FONT.equalsIgnoreCase(docFontName)) {
if (BundledFontAliases.SYMBOL_FONT.equalsIgnoreCase(docFontName)) {
// уже маппировано выше
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) {
// Нет алиаса (или init() не вызван) — доверимся родителю
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.PhysicalFonts;
import ru.pjandro.wordpdf.WordPdfConverter;
import java.io.IOException;
import java.io.InputStream;
@@ -124,57 +125,65 @@ public final class BundledFonts {
/**
* Выгружает шрифты из jar и регистрирует их в docx4j.
* Повторные вызовы игнорируются (idempotентно).
*
* <p>Монитор — {@code WordPdfConverter.class}, а не {@code BundledFonts.class}:
* {@code PhysicalFonts} и {@link #VARIANTS} читаются рендером внутри
* конвертации (она сериализована монитором конвертера), и мутация под
* собственным замком вырезала бы записи из-под идущего рендера.
* Все синхронизированные методы класса держат ровно этот монитор.</p>
*/
public static synchronized void init() {
if (inited) {
return;
}
try {
extractDir = Files.createTempDirectory("wordpdf-fonts-");
} catch (IOException 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();
public static void init() {
synchronized (WordPdfConverter.class) {
if (inited) {
return;
}
try {
extractDir = Files.createTempDirectory("wordpdf-fonts-");
} 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 берёт из
// 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);
// Удаление временного каталога при завершении JVM
extractDir.toFile().deleteOnExit();
inited = true;
}
// Удаление временного каталога при завершении JVM
extractDir.toFile().deleteOnExit();
inited = true;
}
/**
@@ -188,17 +197,18 @@ public final class BundledFonts {
* em-dash на шрифте ранa (Carlito) вместо fallback-DejaVu.
* Шрифты, встроенные в docx, регистрируются при {@code load()} —
* если чистить до load(), они останутся в реестре.
* <p>Мутирует глобальный реестр {@code PhysicalFonts}: нельзя звать
* параллельно идущей {@code WordPdfConverter.convert()} — рендер
* начнёт терять шрифты. Внешний вызов рядом с идущей конвертацией
* обязан держать монитор {@code WordPdfConverter.class} — тот же,
* что сериализует конвертации.
* <p>Мутирует глобальный реестр {@code PhysicalFonts} под монитором
* {@code WordPdfConverter.class} — тем же, что сериализует конвертации,
* поэтому вызов рядом с идущей {@code WordPdfConverter.convert()}
* безопасен автоматически (замок удерживается внутри метода).
*/
public static synchronized void restrictToBundled() {
if (!inited) {
return;
public static void restrictToBundled() {
synchronized (WordPdfConverter.class) {
if (!inited) {
return;
}
dropNonBundled();
}
dropNonBundled();
}
/** Удаляет из реестра всё, что не было выгружено из jar в {@link #extractDir}. */
@@ -237,15 +247,18 @@ public final class BundledFonts {
/**
* Зарегистрированный шрифт: семейство (lowercase) + начертание.
* Синхронизирован с {@link #init()}: {@code VARIANTS} — обычный
* {@code HashMap}, наполняемый в {@code init()} под тем же монитором
* класса; без замка внешний читатель мог бы увидеть недобранную карту.
* Синхронизирован с {@link #init()} общим монитором
* {@code WordPdfConverter.class}: {@code VARIANTS} — обычный
* {@code HashMap}, наполняемый в {@code init()}; без замка внешний
* читатель мог бы увидеть недобранную карту.
*
* @return PhysicalFont или null (если init() не вызван или шрифта нет)
*/
public static synchronized PhysicalFont font(String family, String variant) {
Map<String, PhysicalFont> m = VARIANTS.get(family);
return m == null ? null : m.get(variant);
public static PhysicalFont font(String family, String variant) {
synchronized (WordPdfConverter.class) {
Map<String, PhysicalFont> m = VARIANTS.get(family);
return m == null ? null : m.get(variant);
}
}
public static PhysicalFont regular(String family) {
@@ -13,7 +13,7 @@ import java.util.regex.Pattern;
/**
* Нормализация 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",
* поле остаётся null и {@code BooleanDefaultTrue.isVal()} считается
* true). Из-за этого явные {@code <w:b w:val="off"/>} и
@@ -22,9 +22,14 @@ import java.util.regex.Pattern;
* docx4j разбирает корректно, поэтому заменяем "off"->"false",
* "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.
*/
public final class DocxOnOffNormalizer {
final class DocxOnOffNormalizer {
/**
* {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от
@@ -33,15 +38,12 @@ public final class DocxOnOffNormalizer {
* {@code w:t} не правится. Регрессия — DocxOnOffNormalizerTest#onOffInTextNotTouched.
*/
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);
private DocxOnOffNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = DocxOnOffNormalizer::normalize;
/**
* Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on"
* на "false"/"true".
@@ -49,7 +51,7 @@ public final class DocxOnOffNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -15,19 +15,21 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
/**
* Единый zip-проход переписывания XML-частей (.docx) вместо отдельных
* проходов нормализаторов: к каждой записи {@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-виде
* (TableIndent читает transitional-атрибуты {@code w:}); GlyphCoverage
* (TableIndent читает transitional-атрибуты {@code w:}); MathFallback
* шестым — flatten unsupported-формул даёт обычный текст ранов, который
* следующий GlyphCoverage покрывает кириллицей бандла; GlyphCoverage
* режет раны по финальному тексту рана (после Symbol/Invisible); Hidden
* последним — вырезает уже финальные раны (после Symbol/GLYPH-разбиений),
* десятым — вырезает уже финальные раны (после Symbol/GLYPH-разбиений),
* а его OnOff-форма vanish читается после правила 2. Каждый
* рерайт работает только содержимым одной части, поэтому по-частная
* цепочка эквивалентна последовательным полным проходам. Исключения из
* «по-частности» — контексты, читаемые один раз до цикла: правило 7
* «по-частности» — контексты, читаемые один раз до цикла: правило 8
* (TableIndent) — у header/footer-частей своей sectPr нет, ширина полосы
* передаётся из document.xml (многосекционный документ — полоса
* неоднозначна, header/footer пропускаются); правило 9 (Hidden) —
* неоднозначна, header/footer пропускаются); правило 10 (Hidden) —
* стилевые vanish читаются из word/styles.xml (цепочка w:basedOn).
*
* <p>Неизменённые записи (медиа, rels, прочее) переносятся raw-копией
@@ -52,46 +54,51 @@ public final class DocxRewritePipeline {
public static final DocxNormalizer STEP = DocxRewritePipeline::normalize;
/**
* Применяет десять рерайтов к каждой записи {@code word/*.xml} за один
* Применяет одиннадцать рерайтов к каждой записи {@code word/*.xml} за один
* проход zip.
*
* @param docx байты .docx (валидный zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx));
ZipArchiveOutputStream zos = new ZipArchiveOutputStream(out)) {
// Ширина полосы набора для правила 7 (таблицы в header/footer-
// Ширина полосы набора для правила 8 (таблицы в header/footer-
// частях своей sectPr не содержат): из сырого document.xml —
// геометрия инвариантна к рерайтам цепочки (Strict не трогает
// w:pgSz/@w:w, а pgMar-чередование left|start покрывает strict).
// w:pgSz/@w:w; у strict CT_PageMar start/end нет вовсе —
// только left/right).
// Записи нет/несколько секций → −1, header/footer консервативно
// пропускаются (та же неоднозначность полосы, что для body).
int band = -1;
ZipArchiveEntry docEntry = zf.getEntry("word/document.xml");
if (docEntry != null) {
band = TableIndentNormalizer.bandOf(
new String(zf.getInputStream(docEntry).readAllBytes(),
StandardCharsets.UTF_8));
try (InputStream in = zf.getInputStream(docEntry)) {
band = TableIndentNormalizer.bandOf(
new String(in.readAllBytes(), StandardCharsets.UTF_8));
}
}
// Стилевые vanish для правила 9 (скрытый текст): часть стилевой
// Стилевые vanish для правила 10 (скрытый текст): часть стилевой
// цепочки w:basedOn вычисляется один раз до цикла. Записи нет →
// пустое множество, рерайт работает по прямому vanish.
Set<String> hiddenStyles = Set.of();
ZipArchiveEntry stylesEntry = zf.getEntry("word/styles.xml");
if (stylesEntry != null) {
hiddenStyles = HiddenTextNormalizer.vanishStyles(
new String(zf.getInputStream(stylesEntry).readAllBytes(),
StandardCharsets.UTF_8));
try (InputStream in = zf.getInputStream(stylesEntry)) {
hiddenStyles = HiddenTextNormalizer.vanishStyles(
new String(in.readAllBytes(), StandardCharsets.UTF_8));
}
}
for (ZipArchiveEntry entry : Collections.list(zf.getEntries())) {
String name = entry.getName();
byte[] rewritten = null;
if (name.startsWith("word/") && name.endsWith(".xml")) {
String xml = new String(zf.getInputStream(entry).readAllBytes(),
StandardCharsets.UTF_8);
String xml;
try (InputStream in = zf.getInputStream(entry)) {
xml = new String(in.readAllBytes(), StandardCharsets.UTF_8);
}
String cur = xml;
String next = StrictOoxmlNormalizer.rewritePart(name, cur);
if (next != null) {
@@ -113,6 +120,10 @@ public final class DocxRewritePipeline {
if (next != null) {
cur = next;
}
next = MathFallbackNormalizer.rewrite(cur);
if (next != null) {
cur = next;
}
next = GlyphCoverageNormalizer.rewrite(cur);
if (next != null) {
cur = next;
@@ -133,7 +144,7 @@ public final class DocxRewritePipeline {
if (next != null) {
cur = next;
}
if (cur != xml) {
if (!cur.equals(xml)) {
changed = true;
rewritten = cur.getBytes(StandardCharsets.UTF_8);
}
@@ -161,7 +172,9 @@ public final class DocxRewritePipeline {
} else {
// прочие методы/шифрованные — обычный перенос
zos.putArchiveEntry(new ZipArchiveEntry(name));
zf.getInputStream(entry).transferTo(zos);
try (InputStream in = zf.getInputStream(entry)) {
in.transferTo(zos);
}
zos.closeArchiveEntry();
}
}
@@ -1,13 +1,6 @@
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.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;
/**
* Разворачивание «сложных» полей PAGE/NUMPAGES в {@code w:fldSimple} —
@@ -30,13 +23,14 @@ import java.util.zip.ZipOutputStream;
* внутрь {@code w:sdt}: нумерация страниц Word почти всегда лежит в
* контентном контроле («Page Numbers (Top of Page)»), и до поля не добирается.
* Отсюда и нормализация байтов, как в {@link DocxOnOffNormalizer}.
* Регрессия — WordPdfConverterTest#pageNumbers_recomputedNotCached.
*
* Трогаются только поля, которые действительно есть кому рисовать
* ({@link #SUPPORTED}); остальные остаются как были. Вложенные поля не
* разбираются — если внутри {@code begin … end} встречается ещё один
* {@code begin}, поле пропускается.
*/
public final class FieldNormalizer {
final class FieldNormalizer {
/** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */
private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"};
@@ -44,39 +38,6 @@ public final class 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, если менять нечего
*/
@@ -26,7 +26,16 @@ import ru.pjandro.wordpdf.fonts.BundledFonts;
* рендерится шрифтом просмотрщика либо .notdef («#»). Поэтому в конфиг
* добавляются ВСЕ шрифты бандла: стоит они в документе или нет, решает 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 {
@@ -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,
String family) {
PhysicalFont regular = BundledFonts.regular(family);
@@ -61,21 +78,43 @@ public final class FopFallbackFonts {
// и под это же имя декларируются все начертания (так делает
// docx4j FopConfigUtil.createVariant).
String familyName = regular.getName();
for (Fonts.Font existing : rendererFonts.getFont()) {
for (Fonts.Font.FontTriplet triplet : existing.getFontTriplet()) {
if (familyName.equals(triplet.getName())) {
return;
String[][] variants = {
{BundledFonts.V_REGULAR, "normal", "normal"},
{BundledFonts.V_BOLD, "normal", "bold"},
{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;
}
}
}
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");
return false;
}
/**
@@ -1,21 +1,14 @@
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.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.List;
import java.util.Map;
import java.util.regex.Matcher;
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;
/**
@@ -38,7 +31,7 @@ import java.util.concurrent.ConcurrentHashMap;
* Делаем то, что должен был сделать рендер: ран, в тексте которого есть
* знаки без глифа, разрезается на части, и каждой части явно назначается
* бандл-семейство, где глиф есть ({@link #targetFamily}). Имя пишется в
* {@code w:rFonts}, дальше {@link BundledFontMapper} маппит его на TTF,
* {@code w:rFonts}, дальше {@code BundledFontMapper} маппит его на TTF,
* а {@link FopFallbackFonts} декларирует его в FOP-конфиге.
*
* Правила, ограничивающие вмешательство:
@@ -54,7 +47,7 @@ import java.util.concurrent.ConcurrentHashMap;
*
* Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора.
*/
public final class GlyphCoverageNormalizer {
final class GlyphCoverageNormalizer {
/** Семейства с засечками: для них fallback ищется сначала среди serif. */
private static final List<String> SERIF_FAMILIES =
@@ -81,39 +74,6 @@ public final class 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()) {
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}, а если их нет — вставляет элемент первым ребёнком.
*/
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 + "\"/>";
if (rPr.isEmpty()) {
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;
/**
* Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.30) из
* Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.41) из
* XML-частей — до загрузки docx4j.
*
* <p>Word по умолчанию не выводит скрытый текст ни на экран, ни на печать,
@@ -39,8 +39,13 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
* правило 2 к моменту запуска уже привело on/off к true/false, но обе формы
* принимаются) либо {@code w:rStyle} ссылается на стиль с vanish — по
* цепочке {@code w:basedOn} (капа 16, цикл — обрыв; тот же приём, что
* {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой;
* вложенные раны ({@code w:rubyBase}/{@code w:rt}, текстовые боксы)
* {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой
* (§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.
*/
public final class HiddenTextNormalizer {
final class HiddenTextNormalizer {
/** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */
private static final int MAX_CHAIN = 16;
@@ -72,6 +77,10 @@ public final class HiddenTextNormalizer {
/** Закрывающий слэш самозакрывающегося тега. */
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>} и прочее не матчатся по границе имени. */
private static final Pattern RUN_TOKEN = Pattern.compile("<w:r(?=[ >/])|</w:r>");
@@ -97,9 +106,6 @@ public final class HiddenTextNormalizer {
private HiddenTextNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = HiddenTextNormalizer::normalize;
/**
* Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей
* docx; {@code word/styles.xml}/{@code word/numbering.xml} пропускаются.
@@ -107,10 +113,10 @@ public final class HiddenTextNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
Set<String> vanishStyles = Set.of();
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) {
ZipArchiveEntry styles = zf.getEntry("word/styles.xml");
ZipArchiveEntry styles = zf.getEntry(STYLES_PART);
if (styles != null) {
vanishStyles = vanishStyles(new String(
zf.getInputStream(styles).readAllBytes(), StandardCharsets.UTF_8));
@@ -152,7 +158,7 @@ public final class HiddenTextNormalizer {
* @return новая строка либо null, если менять нечего
*/
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 rewrite(vanishStyleIds, xml);
@@ -309,6 +315,9 @@ public final class HiddenTextNormalizer {
if (hasTruthyVanish(region)) {
return true;
}
if (hasExplicitFalsyVanish(region)) {
return false; // явный w:val=false/0/off перекрывает стилевой vanish (§17.7.3)
}
if (!vanishStyleIds.isEmpty()) {
Matcher r = RSTYLE.matcher(region);
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);
Matcher v = VAL_ATTR.matcher(tag);
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))) {
return true;
@@ -372,11 +381,21 @@ public final class HiddenTextNormalizer {
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) {
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). */
private static boolean hasProtected(String xml, int from, int to) {
for (String p : PROTECTED) {
@@ -27,9 +27,10 @@ import java.util.zip.ZipOutputStream;
* в невидимый DejaVu — FOP рисует «тофу» прямо в тексте.</li>
* </ul>
*
* Zero-width знаки, значимые для shaping и переносов (U+00A0, U+00AD,
* U+200B, U+200C, U+200D), НЕ трогаем: во всех шрифтах бандла они
* нулевой ширины и пустых строк не создают.
* NBSP (U+00A0, ширина пробела — не zero-width) и zero-width знаки, значимые
* для shaping и переносов (U+00AD, U+200B, U+200C, U+200D), НЕ трогаем:
* во всех шрифтах бандла NBSP широк, остальное нулевой ширины, и ни то ни
* другое пустых строк не создаёт.
*
* Правим байты zip до JAXB-разбора, как остальные нормализаторы; запускается
* до {@link GlyphCoverageNormalizer}, чтобы тот не искал шрифт для уже
@@ -38,7 +39,7 @@ import java.util.zip.ZipOutputStream;
* Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines,
* WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn.
*/
public final class InvisibleCharNormalizer {
final class InvisibleCharNormalizer {
/**
* Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029),
@@ -86,9 +87,6 @@ public final class InvisibleCharNormalizer {
private InvisibleCharNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = InvisibleCharNormalizer::normalize;
/**
* Вырезает невидимые символы из текстовых узлов XML-частей docx
* (word/*.xml).
@@ -96,7 +94,7 @@ public final class InvisibleCharNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
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 —
* табуляция до позиционного отступа, 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} —
* заготовка без обработчика (дамп n4.fo аудита раскладки). Для suff=tab это
* отдельный Class C-остаток (нужна per-item ширина), а suff=space чинится
@@ -29,7 +30,7 @@ import java.util.zip.ZipOutputStream;
* заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing —
* не трогаем. Нечего менять → тот же массив.
*/
public final class NumberingSuffixNormalizer {
final class NumberingSuffixNormalizer {
private static final Pattern SUFF_SPACE =
Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>");
@@ -38,16 +39,13 @@ public final class NumberingSuffixNormalizer {
private NumberingSuffixNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = NumberingSuffixNormalizer::normalize;
/**
* Дописывает пробел в lvlText у уровней с suff=space.
*
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -1,6 +1,6 @@
package ru.pjandro.wordpdf.internal;
import ru.pjandro.wordpdf.DrawingFoundException;
import ru.pjandro.wordpdf.OleFoundException;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
@@ -42,13 +42,14 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
* по ECMA-376 §15.2.10 у каждого внедрённого объекта обязан быть «associated
* image, which appears in the document as a placeholder» — именно его показывает
* Word вместо объекта, — поэтому {@code w:object} заменяется его статичным
* представлением (картинкой-плейсхолдером, §17.3.3.3); без плейсхолдера блок
* представлением (картинкой-плейсхолдером, §17.3.3.19; картинка — §17.3.3.9);
* без плейсхолдера блок
* удаляется. OLE-бинарники при этом никогда не читаются — байты только
* удаляются, так что содержимое объекта (вплоть до враждебного архива) на
* вывод не влияет.</p>
*
* <p>Отличие от остальных нормализаторов пакета: принимает флаг
* {@code errorOnOle} и умеет бросать {@link DrawingFoundException}
* {@code errorOnOle} и умеет бросать {@link OleFoundException}
* (при включённом флаге документ отвергается вместо вычистки), и правит
* не только {@code word/*.xml}, но и {@code [Content_Types].xml} с
* {@code *.rels}. Хука {@code rewrite(String)} нет — нормализатор
@@ -75,6 +76,9 @@ public final class OleObjectNormalizer {
/** Сегмент «наверх» в относительном Target rels. */
private static final String PARENT_DIR = "..";
/** Сегмент «текущий каталог» в относительном Target rels. */
private static final String CURRENT_DIR = ".";
private static final Pattern DEFAULT_TYPE = Pattern.compile(
"<Default\\b[^>]*\\bExtension=\"([^\"]*)\"[^>]*\\bContentType=\"([^\"]*)\"[^>]*/>"
+ "|<Default\\b[^>]*\\bContentType=\"([^\"]*)\"[^>]*\\bExtension=\"([^\"]*)\"[^>]*/>");
@@ -205,8 +209,10 @@ public final class OleObjectNormalizer {
if (contentTypes == null) {
return docx;
}
String ctXml = new String(zf.getInputStream(contentTypes).readAllBytes(),
StandardCharsets.UTF_8);
String ctXml;
try (InputStream in = zf.getInputStream(contentTypes)) {
ctXml = new String(in.readAllBytes(), StandardCharsets.UTF_8);
}
Map<String, String> defaults = defaultTypes(ctXml);
Map<String, String> overrides = overrideTypes(ctXml);
@@ -231,7 +237,7 @@ public final class OleObjectNormalizer {
return docx;
}
if (errorOnOle) {
throw new DrawingFoundException(DrawingFoundException.Kind.OLE);
throw new OleFoundException();
}
for (String part : oleParts) {
LOG.warning("Удалён OLE-объект: " + part);
@@ -246,7 +252,10 @@ public final class OleObjectNormalizer {
if (oleParts.contains(name)) {
continue;
}
byte[] data = zf.getInputStream(entry).readAllBytes();
byte[] data;
try (InputStream in = zf.getInputStream(entry)) {
data = in.readAllBytes();
}
if (name.endsWith(".rels")) {
String fixed = stripRels(
new String(data, StandardCharsets.UTF_8), name, oleParts);
@@ -259,7 +268,7 @@ public final class OleObjectNormalizer {
if (fixed != null) {
data = fixed.getBytes(StandardCharsets.UTF_8);
}
} else if (name.equals(CONTENT_TYPES_ENTRY)) {
} else if (CONTENT_TYPES_ENTRY.equals(name)) {
String fixed = stripOverrides(
new String(data, StandardCharsets.UTF_8), oleParts);
if (fixed != null) {
@@ -373,7 +382,7 @@ public final class OleObjectNormalizer {
}
}
for (String s : target.split("/")) {
if (s.isEmpty() || ".".equals(s)) {
if (s.isEmpty() || CURRENT_DIR.equals(s)) {
continue;
}
if (PARENT_DIR.equals(s)) {
@@ -389,7 +398,7 @@ public final class OleObjectNormalizer {
/**
* Заменяет в 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 всё равно остаётся сиротой;
* блок с `w:drawing` (ветка mc:Choice) заменяется этим drawing дословно;
* блок с `v:imagedata r:id` заменяется inline-DrawingML на ту же
@@ -10,8 +10,9 @@ import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;
/**
* Разбор руби-разметки ({@code w:rubyBase}/{@code w:rt}/{@code w:rubyPr},
* Part 1 §17.3.3.19/.20/.21) в байтах до загрузки docx4j.
* Разбор руби-разметки ({@code w:ruby}/{@code w:rubyBase}/{@code w:rt}/
* {@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}
* в {@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},
* которые схема знает). Единственный слой починки — байтовый нормализатор.
*
* <p>Деградация принята: база ({@code w:rubyBase}/{@code w:rubyBaseText})
* разворачивается в обычные раны ранa — текст печатается; надстрочница
* ({@code w:rt}) и форматирование руби ({@code w:rubyPr}, {@code w:rubyAlign})
* удаляются вместе с содержимым — ruby-разметки в XSL-FO у FOP нет, а потеря
* текста хуже потери аннотации.
* <p>Деградация принята: база ({@code w:rubyBase}) разворачивается в обычные
* раны ранa — текст печатается; надстрочница ({@code w:rt}) и форматирование
* руби ({@code w:rubyPr}, {@code w:rubyAlign}) удаляются вместе с содержимым
* — 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}
* (после Hidden; порядок 1–8 не перенумеровать); в
* <p>В конвейере подключается одиннадцатым рерайтом в {@link DocxRewritePipeline}
* (после Hidden; порядок правил фиксирован в {@code DocxRewritePipeline}); в
* {@code WordPdfConverter#normalizers} напрямую не вызывается, как и
* остальные rewrite-нормализаторы.
*
* <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted.
*/
public final class RubyNormalizer {
final class RubyNormalizer {
private RubyNormalizer() {
}
@@ -46,18 +49,21 @@ public final class RubyNormalizer {
private static final Pattern RUBY_PR_BLOCK =
Pattern.compile("<w:rubyPr(?:\\s[^>]*)?(?:/>|>.*?</w:rubyPr>)", Pattern.DOTALL);
/** Одиночный {@code w:rubyPr}. */
/** Одиночный {@code w:rubyAlign}. */
private static final Pattern RUBY_ALIGN =
Pattern.compile("<w:rubyAlign(?:\\s[^>]*)?(?:/>|>\\s*</w:rubyAlign>)", Pattern.DOTALL);
private static final Pattern RUBY_BASE_OPEN =
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}/
* {@code w:rubyBaseText}, вырезает {@code w:rt}/{@code w:rubyPr}/
* Рерайт одной XML-строки: разворачивает {@code w:rubyBase}, снимает
* обёртку {@code w:ruby}, вырезает {@code w:rt}/{@code w:rubyPr}/
* {@code w:rubyAlign}. Руби-токенов нет / ничего не поменялось → {@code null}.
*/
static String rewrite(String xml) {
@@ -67,10 +73,10 @@ public final class RubyNormalizer {
String out = RT_BLOCK.matcher(xml).replaceAll("");
out = RUBY_PR_BLOCK.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 = out.replace("</w:rubyBase>", "");
out = RUBY_OPEN.matcher(out).replaceAll("");
out = out.replace(RUBY_CLOSE, "");
return out.equals(xml) ? null : out;
}
@@ -78,7 +84,7 @@ public final class RubyNormalizer {
* Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере
* {@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);
boolean changed = false;
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 NumberFormatException: Not a number: 130%};</li>
* <li>текстовые проценты в {@code wp14:pctWidth}/{@code wp14:pctHeight};</li>
* <li>границы и отступы в элементах {@code w:start}/{@code w:end}
* (в transitional они называются {@code w:left}/{@code w:right}) —
* JAXB сообщает «unexpected element» и границы теряются;</li>
* <li>границы и отступы в элементах {@code w:start}/{@code w:end} — в
* strict-схеме это единственные имена, transitional-схема допускает
* обе пары детей (wml.xsd CT_TcMar/CT_TblCellMar), но strict-часть их
* не пишет — JAXB transitional-модели сообщает «unexpected element»
* и границы теряются;</li>
* <li>атрибуты {@code w:start}/{@code w:end} у {@code w:ind} и значения
* {@code start}/{@code end} у {@code w:jc}/{@code w:tab} — в strict-модели
* это единственные имена, а transitional-модель 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>
*
* <p>Полный strict→transitional рерайт не делается: mc-preprocessor уже
@@ -72,12 +75,14 @@ import java.util.zip.ZipOutputStream;
* RTL; ST_Jc §17.18.44); RTL вне контура конвейера (FOP без complex-script,
* direction docx4j не выставляет — start и так рендерился как left).</li>
* <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>
*
* Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected.
*/
public final class StrictOoxmlNormalizer {
final class StrictOoxmlNormalizer {
/** Открывающий тег элемента префикса {@code a:} (DrawingML). */
private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>");
@@ -121,9 +126,6 @@ public final class StrictOoxmlNormalizer {
private StrictOoxmlNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = StrictOoxmlNormalizer::normalize;
/**
* Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который
* разбирает JAXB-модель transitional (детали — в javadoc класса).
@@ -131,7 +133,7 @@ public final class StrictOoxmlNormalizer {
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
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:ind} (MS-OI29500 §2.1.174a: start/end как
* псевдонимы left/right в strict — единственный носитель w:ind) и только
* открывающего тега {@code w:ind} (MS-OI29500 §2.1.44 (ind) плюс
* strict wml.xsd: {@code CT_Ind} знает только start/end — единственный
* носитель w:ind в strict) и только
* при отсутствии в нём {@code w:left}/{@code w:right}: CT_Ind
* (transitional) допускает обе пары, дубль атрибута — не well-formed
* XML; литеральный текст {@code w:val}-вида в {@code w:t} не
* затрагивается. У {@code w:pgNumType} атрибут {@code w:start} — старт
* нумерации страниц, легален в transitional (Part 1 §17.13.7), — не
* нумерации страниц, легален в transitional (Part 1 §17.6.12), — не
* трогается (регрессия — pgNumTypeStartAttrUntouched).
*/
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"}
* — это «▪», а тот же код в Symbol — «♣». Экспорт docx4j в XSL-FO эти
* шрифты не знает: код уходит в fallback-семейство, глифа там нет, и FOP
* рисует {@code .notdef} — в PDF решётку «#» (регрессия:
* {@code WordPdfConverterTest#symbolFonts_bulletsAreNotHash}).
* рисует {@code .notdef} — в PDF решётку «#».
* Регрессия — WordPdfConverterTest#symbolFonts_bulletsAreNotHash.
*
* Делаем то же, что Word: код из PUA заменяем его Unicode-эквивалентом,
* а имя шрифта — на fallback-семейство (в нём этих глифов достаточно).
@@ -42,7 +42,7 @@ import java.util.zip.ZipOutputStream;
*
* Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора.
*/
public final class SymbolFontNormalizer {
final class SymbolFontNormalizer {
/** Семейство, на которое заменяются символьные шрифты (есть в jar). */
static final String REPLACEMENT_FAMILY = "DejaVu Sans";
@@ -51,8 +51,9 @@ public final class SymbolFontNormalizer {
* Имя шрифта (lowercase) -> таблица из 256 слотов по 4 hex-цифры:
* младший байт кода из PUA -> Unicode-код цели (0 — соответствия нет).
* Источник — 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();
@@ -70,16 +71,13 @@ public final class SymbolFontNormalizer {
private SymbolFontNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = SymbolFontNormalizer::normalize;
/**
* Заменяет символьные шрифты в XML-частях docx (word/*.xml).
*
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -311,14 +309,20 @@ public final class SymbolFontNormalizer {
char mapped = 0;
if (charHex != null && fontMap != null) {
char code = (char) Integer.parseInt(charHex, 16);
if (code >= 0xF000 && code <= 0xF0FF) {
mapped = mapped(fontMap, code & 0xFF);
}
// PUA-форма (U+F0xx) и прямая (код ≤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) {
sb.append(openTag).append(fallbackRPr)
.append("<w:t xml:space=\"preserve\">").append(mapped)
.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();
}
@@ -14,7 +14,9 @@ import java.util.zip.ZipOutputStream;
* Свёртка {@code w:tblPr/w:jc} (center/right) с ненулевым {@code w:tblInd} в
* абсолютный {@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} добавляется сдвигом от
* поля. docx4j же при {@code w:jc}≠left {@code w:tblInd} игнорирует буквально
* (аудит раскладки ECMA-376, матрица B3) — таблица рендерилась без учёта
@@ -31,12 +33,17 @@ import java.util.zip.ZipOutputStream;
* <p>Пропускается (не ломая существующее поведение): документы без
* единственного body-level {@code w:sectPr} (несколько секций — полоса
* неоднозначна), {@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} (вставить
* тег в корректную позицию CT_TblPrBase некуда). Дефолты при отсутствии
* pgSz/pgMar — 11906 и 1440/1440: измеренное поведение docx4j при отсутствующем
* {@code w:pgMar} (левый край текста = 72pt = 1440 twips), а не ECMA-дефолт
* 1800 — нормализатор обязан считать ту же полосу, что рендерит стек.
* pgSz/pgMar — 11906 и 1440/1440: ECMA дефолтов {@code w:pgSz}/{@code w:pgMar}
* не фиксирует (§17.6.13/§17.6.11), а 11906/1440 — измеренное поведение
* 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} (признак —
* {@code <w:body}); нечего менять → тот же массив. {@link #rewritePart} —
@@ -46,7 +53,7 @@ import java.util.zip.ZipOutputStream;
* WordPdfConverterTest#tableIndentCentered_shiftedLikeWord,
* #headerTableIndent_centeredInHeader.
*/
public final class TableIndentNormalizer {
final class TableIndentNormalizer {
/** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */
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 Pattern PG_SZ_W = Pattern.compile("<w:pgSz\\b[^>]*w:w=\"(\\d+)\"");
// strict-OOXML пишет поля как w:start/w:end; band считается из СЫРОГО
// document.xml (до rule 1, которая их переименует) — чередование
// обязательно, иначе полоса строгого документа молча возьмётся из дефолтов
// полоса считается из СЫРОГО document.xml; чередование left|start не
// нужен: CT_PageMar не имеет start/end ни в strict-, ни в transitional-
// схеме (wml.xsd), StrictOoxmlNormalizer w:pgSz/w:pgMar не трогает —
// геометрия инвариантна к рерайтам
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 =
Pattern.compile("<w:pgMar\\b[^>]*w:(?:right|end)=\"(\\d+)\"");
Pattern.compile("<w:pgMar\\b[^>]*w:right=\"(\\d+)\"");
private static final Pattern JC =
Pattern.compile("<w:jc\\b[^>]*w:val=\"(center|right)\"[^>]*/>");
private static final Pattern TBL_IND = Pattern.compile("<w:tblInd\\b[^>]*/>");
@@ -74,16 +82,13 @@ public final class TableIndentNormalizer {
private TableIndentNormalizer() {
}
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
public static final DocxNormalizer STEP = TableIndentNormalizer::normalize;
/**
* Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}.
*
* @param docx байты .docx (zip)
* @return те же или переупакованные байты
*/
public static byte[] normalize(byte[] docx) throws IOException {
static byte[] normalize(byte[] docx) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
boolean changed = false;
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
@@ -186,10 +191,18 @@ public final class TableIndentNormalizer {
if (hasInd) {
String indTag = ind.group();
Matcher indW = TBL_IND_W.matcher(indTag);
if (!indW.find() || !indTag.contains("w:type=\"dxa\"")) {
continue; // не-dxa — величина сдвига неизвестна
// CT_TblWidth (§17.4.87): опущенный w:type = 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));
} else if (pr.contains("<w:tblInd")) {
// парный (не самозакрывающийся) w:tblInd — паттерн видит
// только самозакрытый; вставка нового тега оставила бы старый
// → дубль элемента (maxOccurs=1 у CT_TblPrBase), консервативно
continue;
} else if (pr.contains("<w:tblCellSpacing")) {
// tblInd по CT_TblPrBase идёт ПОСЛЕ tblCellSpacing — вставить
// тег в корректную позицию некуда, консервативно пропускаем
@@ -11,7 +11,7 @@ import java.util.List;
/**
* Объёмные декартовы графики: 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 — ряд
* (глубина), w — значение (высота); вписка равномерным масштабом в поля
* {@link Surface3dPainter#GUTTER_LEFT} и т.д.
@@ -21,8 +21,8 @@ import java.util.List;
* §2.1.1474(a)); торец затемняется (псевдо-свет, калибровка — Cartesian3dPainterTest).
* line3D: полилиния ряда на своей глубине, лента-толщина не имитируется;
* area3D: стена ряда от пола до значений, полупрозрачная, как AREA.
* c:shape (§21.2.2.177, ST_Shape §21.2.3.44): box/cone/coneToMax/cylinder/pyramid/
* pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1545(a/b)),
* c:shape (§21.2.2.177, ST_Shape §21.2.3.42): box/cone/coneToMax/cylinder/pyramid/
* pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1546(a/b)),
* ToMax-формы сужаются к верху пропорционально val/max (семантика Excel — ECMA геометрию
* не нормирует); неизвестное значение — box. c: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. */
private static List<Face> buildFaces(Color color, String shape, double t,
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. */
private static void drawLabels(Graphics2D g, ChartSpec spec, List<Double> tickValues,
List<Surface3dPainter.Node> valueAnchors, int nCat,
@@ -70,12 +70,12 @@ final class CartesianPainter {
"percentStacked".equalsIgnoreCase(lineGrouping))
: null;
// Разделение серий по осям значений: ссылочное равенство с secondaryValAxis
// (назначается ChartSpec.parse по c:axId, §21.2.2.9).
// Разделение серий по осям значений: та же ось по c:axId
// (назначается ChartSpec.parse, §21.2.2.9; {@link ChartSpec#sameAxis}).
List<Integer> primIdx = new ArrayList<>();
List<Integer> secIdx = new ArrayList<>();
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);
} else {
primIdx.add(si);
@@ -278,9 +278,9 @@ final class CartesianPainter {
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) {
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) {
@@ -30,10 +30,10 @@ import java.nio.ByteBuffer;
*
* Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
* дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
* ДО любых решений, а для не-JPEG без кропа с ppi <= threshold (и без размера
* ДО любых решений, а для не-JPEG без кропа с ppi {@code <=} threshold (и без размера
* в макете) результат всегда null — декод впустую. Здесь такое решение
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
* вовсе. JPEG сознательно не ускоряем: Word при ppi <= threshold перекодирует
* вовсе. JPEG сознательно не ускоряем: Word при ppi {@code <=} threshold перекодирует
* его «для размера», вывод должен остаться побайтно прежним.
*
* Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
@@ -52,6 +52,10 @@ final class ChartRenderer {
/** Порог «значение целое» при форматировании подписей. */
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) —
* double без нижней границы; Word пишет «круглые» значения, а враждебный docx —
@@ -110,12 +114,12 @@ final class ChartRenderer {
// дорисовывается поверх после художника. Регрессия — ChartRendererTest#overlayLegend_drawnOverPlot.
double legendH = legend == null || spec.legendOverlay ? 0 : legend.height;
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,
box.getWidth());
box = new Rectangle2D.Double(box.getX(), box.getY(),
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());
box = new Rectangle2D.Double(box.getX(), box.getY() + legendH,
box.getWidth(), box.getHeight() - legendH);
@@ -144,7 +148,7 @@ final class ChartRenderer {
default -> LOG.warn("тип графика {} не поддерживается — пустой PNG", spec.type);
}
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;
legend.draw(g, box0.getX(), y, box0.getWidth());
}
@@ -117,7 +117,7 @@ final class ChartSpec {
final List<Double> xValues = new ArrayList<>();
/** bubble: размеры пузырей (c:bubbleSize). */
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;
/** Способ отрисовки ряда в combo-диаграмме (несколько групп в одном c:plotArea,
* ECMA-376 §21.2.2.145): BAR/BAR_HORIZONTAL/LINE/AREA по группе-источнику.
@@ -396,7 +396,7 @@ final class ChartSpec {
break;
}
}
if (va == null || va == spec.valAxis) {
if (va == null || sameAxis(va, spec.valAxis)) {
continue;
}
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) {
CTShapeProperties sp = space.getSpPr();
if (sp == null) {
@@ -1129,7 +1137,11 @@ final class ChartSpec {
return null;
}
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) {
return null;
}
@@ -29,12 +29,13 @@ import java.util.Map;
* Палитра цветов DrawingML: цвета схемы из word/theme/theme1.xml плюс
* разбор {@code a:color} (srgbClr / scrgbClr / hslClr / sysClr /
* 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,
* gamma/invGamma).
*
* 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 —
* расхождение на стороне спецификации.
*
@@ -432,7 +433,7 @@ final class DrawMlColor {
rgb = toRgb(hsl);
}
// §20.1.2.3.31/.34: Office-семантика — модуляция
// светлоты в HSL (MS-OI29500 §17.3.2.6(a)), не
// светлоты в HSL (MS-OI29500 §2.1.72), не
// гамма-микс; ECMA-примеры tint/shade противоречат
// собственному семейству lum/sat (§20.1.2.3.19-28).
case "tint" -> {
@@ -7,7 +7,7 @@ import org.docx4j.dml.CTTextParagraph;
import org.docx4j.dml.CTTextParagraphProperties;
import org.docx4j.dml.CTTextSpacing;
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.GlyphFont;
@@ -23,7 +23,7 @@ import java.util.List;
* (a:defRPr / a:rPr: sz, b, i, solidFill, latin) и разбивка на строки.
*
* Шрифты берутся из того же бандла, что и у текста PDF
* ({@link BundledFontMapper#bundledFamily}), поэтому подпись диаграммы
* ({@link BundledFontAliases#bundledFamily}), поэтому подпись диаграммы
* рисуется тем же Carlito/Tinos, что и абзацы документа.
*/
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} — фиксированная
* высота строки в pt (a:spcPts/100); оба null — одинарный.
*/
@@ -57,6 +57,8 @@ final class DrawMlText {
/** Значения выравнивания DrawingML (a:pPr/@algn, a:bodyPr/@anchor). */
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";
/** Длина строки, дальше которую рез не идёт (прогресс гарантирован 1 символом). */
@@ -82,7 +84,7 @@ final class DrawMlText {
String fallbackFam, double fallbackSize, Color fallbackColor) {
Style base = new Style(fallbackSize, false, false, fallbackColor,
fallbackFam == null ? BundledFonts.FALLBACK_FAMILY
: BundledFontMapper.bundledFamily(fallbackFam));
: BundledFontAliases.bundledFamily(fallbackFam));
if (txPr == null || txPr.getP().isEmpty()) {
return base;
}
@@ -168,7 +170,7 @@ final class DrawMlText {
case "+mj-lt", "+mj-ea", "+mj-cs" -> colors.majorFontName();
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;
if (ALIGN_CTR.equals(align)) {
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();
}
fontFor(line.style()).draw(g, line.text(), x, y + line.ascent(),
@@ -253,7 +255,7 @@ final class DrawMlText {
/**
* Высота строки абзаца: a:lnSpc/a:spcPts — фиксированная в pt,
* 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) {
if (p.spacingPts() != null) {
@@ -22,6 +22,8 @@ import org.docx4j.dml.diagram2008.CTDrawing;
import org.docx4j.dml.picture.Pic;
import org.docx4j.dml.wordprocessingDrawing.Anchor;
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.exceptions.Docx4JException;
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.WordprocessingML.BinaryPartAbstractImage;
import org.docx4j.openpackaging.parts.relationships.RelationshipsPart;
import org.docx4j.wml.CTSignedHpsMeasure;
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.LoggerFactory;
import ru.pjandro.wordpdf.ChartsFoundException;
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.xml.namespace.QName;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.lang.reflect.Method;
import java.math.BigInteger;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashSet;
import java.util.IdentityHashMap;
import java.util.List;
import java.util.Set;
@@ -58,8 +75,20 @@ import java.util.Set;
* пакета и до создания FOSettings, иначе FOP увидит исходные chart/diagram
* и молча их выбросит (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 DrawingFoundException}
* включённом error-флаге находка объекта — {@link ChartsFoundException} или
* {@link SmartArtFoundException}
* (бросок здесь, на шаге 3.5, до XSLT/FOP). Регрессия —
* WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts, фикстура
* samples/charts-smartart.docx.
@@ -76,6 +105,15 @@ public final class DrawingPreRenderer {
"http://schemas.openxmlformats.org/drawingml/2006/picture";
private static final String DIAGRAM_DRAWING_REL =
"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 —
@@ -98,10 +136,25 @@ public final class DrawingPreRenderer {
/**
* Рендерит диаграммы/SmartArt пакета в PNG и подменяет их картинками —
* объекты конвертируются всегда. Бросается {@link DrawingFoundException},
* объекты конвертируются всегда. Бросается {@link ChartsFoundException} или
* {@link SmartArtFoundException},
* когда для объектов включён error-флаг ({@link ConvertOptions}).
*/
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;
for (Part p : new ArrayList<>(pkg.getParts().getParts().values())) {
if (p instanceof ThemePart tp) {
@@ -116,7 +169,9 @@ public final class DrawingPreRenderer {
// ConcurrentModificationException.
List<Part> parts = new ArrayList<>(pkg.getParts().getParts().values());
Set<Part> handled = new HashSet<>();
Set<List<?>> visitedContents = Collections.newSetFromMap(new IdentityHashMap<>());
int[] idSeq = {1000};
long[] pngTotal = {0};
for (Part p : parts) {
if (!handled.add(p)) {
continue;
@@ -125,7 +180,8 @@ public final class DrawingPreRenderer {
if (content.isEmpty()) {
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,
DrawMlColor colors, int[] idSeq, ConvertOptions options) {
for (Object o : content) {
DrawMlColor colors, int[] idSeq, long[] pngTotal,
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;
if (v instanceof Drawing drawing) {
replaceDrawing(part, drawing, pkg, colors, idSeq, options);
replaceDrawing(part, drawing, pkg, colors, idSeq, pngTotal,
maxPngBytesTotal, options);
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");
if (!nested.isEmpty() && nested != content) {
walk(part, nested, pkg, colors, idSeq, options);
if (!nested.isEmpty()) {
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) {
try {
Method m = target.getClass().getMethod(getter);
@@ -176,7 +273,8 @@ public final class DrawingPreRenderer {
}
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()) {
Graphic graphic;
long cx;
@@ -207,10 +305,10 @@ public final class DrawingPreRenderer {
boolean isChart = CHART_ELEMENT.equals(name);
boolean isDiagram = DIAGRAM_ELEMENT.equals(name);
if (isChart && options.errorOnCharts()) {
throw new DrawingFoundException(DrawingFoundException.Kind.CHARTS);
throw new ChartsFoundException();
}
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) {
LOG.warn("drawing вне допустимого wp:extent (cx={}, cy={}) — объект оставлен как есть",
@@ -234,10 +332,169 @@ public final class DrawingPreRenderer {
}
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,
DrawMlColor colors, long cx, long cy) {
Part target = resolve(part, ref.getId());
@@ -248,8 +505,15 @@ public final class DrawingPreRenderer {
try {
ChartSpec spec = ChartSpec.parse(space, colors);
return ChartRenderer.render(spec, cx / 12700.0, cy / 12700.0, colors);
} catch (RuntimeException | OutOfMemoryError e) {
// OOM — второй эшелон после MAX_EXTENT_EMU/MAX_POINTS: враждебный
} catch (OutOfMemoryError e) {
// 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 не должен валить всю конвертацию, деградация = объект удалён.
LOG.warn("рендер графика r:id={} упал: {}", ref.getId(), e.toString());
return null;
@@ -265,7 +529,11 @@ public final class DrawingPreRenderer {
}
try {
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());
return null;
}
@@ -309,7 +577,8 @@ public final class DrawingPreRenderer {
*/
private static void swapForPicture(Part part, GraphicData gd, BufferedImage img,
long cx, long cy, int[] idSeq,
WordprocessingMLPackage pkg) {
WordprocessingMLPackage pkg,
long[] pngTotal, long maxPngBytesTotal) {
byte[] png;
try {
ByteArrayOutputStream bos = new ByteArrayOutputStream();
@@ -325,6 +594,13 @@ public final class DrawingPreRenderer {
gd.getAny().clear(); // контракт: упавший рендер — объект удалён
return;
}
if (pngTotal[0] + png.length > maxPngBytesTotal) {
LOG.warn("суммарный размер chart-PNG превысил {} байт — объект удалён",
maxPngBytesTotal);
gd.getAny().clear(); // деградация «объект удалён + warn»
return;
}
pngTotal[0] += png.length;
String relId;
try {
relId = addChartMedia(pkg, part, png);
@@ -334,11 +610,25 @@ public final class DrawingPreRenderer {
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();
org.docx4j.dml.picture.CTPictureNonVisual nv = new org.docx4j.dml.picture.CTPictureNonVisual();
CTNonVisualDrawingProps props = new CTNonVisualDrawingProps();
props.setId(idSeq[0]++);
props.setName("Диаграмма " + props.getId());
props.setName(namePrefix + " " + props.getId());
nv.setCNvPr(props);
nv.setCNvPicPr(new CTNonVisualPictureProperties());
pic.setNvPicPr(nv);
@@ -368,10 +658,7 @@ public final class DrawingPreRenderer {
geom.setAvLst(new CTGeomGuideList());
spPr.setPrstGeom(geom);
pic.setSpPr(spPr);
gd.setUri(PICTURE_URI);
gd.getAny().clear();
gd.getAny().add(pic);
return 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;
/**
* Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.108): главный
* Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.126): главный
* пирог из первичных точек + вторичная круговая (c:ofPieType="pie") либо
* вертикальный стек ("bar") из вторичных. Разбиение по c:splitType
* (auto|cust|percent|pos|val, §21.2.2.155; семантика splitPos —
* MS-OI29500 §2.1.1554a/b): auto/pos — последние ceil(n/3) (или splitPos)
* (auto|cust|percent|pos|val, §21.2.2.196; семантика splitPos —
* MS-OI29500 §2.1.1553): auto/pos — последние ceil(n/3) (или splitPos)
* точек, val/percent — точки ниже splitPos, cust — c:secondPiePt.
* Вторичных точек нет → обычная круговая через {@link PiePainter}.
* «Other»-сектор (MS-OI29500 §2.1.1507(a)) замыкает главный пирог и обращён к
@@ -37,7 +37,7 @@ final class OfPiePainter {
* калибровка — OfPiePainterTest). */
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 OfPiePainter() {
@@ -9,9 +9,9 @@ import java.util.ArrayList;
import java.util.List;
/**
* Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.143): категории —
* Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.153): категории —
* спицы от 12 часов по часовой, значения — радиус по оси значений.
* c:radarStyle (§21.2.2.119): standard — контур, marker — контур + маркеры,
* c:radarStyle (§21.2.2.154): standard — контур, marker — контур + маркеры,
* filled — полупрозрачная заливка без контура (вид как у AREA).
* Сетка — концентрические многоугольники по делениям оси значений (паутина
* прямыми звеньями, как в Word) и спицы.
@@ -15,9 +15,9 @@ import java.util.List;
* ChartSpecTest#scatterFirstValAxisIsX).
*
* scatter: маркеры по c:marker ряда, линия по c:scatterStyle (line/smooth —
* ECMA-376 §21.2.2.136, сглаживание — кривая Жозефа де Кастельно не
* ECMA-376 §21.2.2.162, сглаживание — кривая Жозефа де Кастельно не
* имитируется, ломаная с 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 рисуется плоско.
*
* Регрессия — ScatterPainterTest, фикстура samples/chart-types.docx
@@ -278,8 +278,9 @@ final class SmartArtRenderer {
if (paragraphs.isEmpty()) {
return;
}
// autofit по ECMA-376 §21.1.2.1.2/.3: noAutofit, spAutoFit (§21.1.2.1.4 —
// под размер текста ресайзится фигура, сам текст не масштабируется)
// autofit по ECMA-376 §21.1.2.1.2 noAutofit / §21.1.2.1.3 normAutofit /
// §21.1.2.1.4 spAutoFit (под размер текста ресайзится фигура,
// сам текст не масштабируется)
// или отсутствие autofit-элемента (отсутствие имплицирует noAutofit) —
// текст рисуется заявленным кеглем. normAutofit — применяем запечённые
// Word-ом fontScale/lnSpcReduction из XML; если fontScale не запечён
@@ -9,7 +9,7 @@ import java.util.ArrayList;
import java.util.List;
/**
* Биржевая диаграмма (c:stockChart, ECMA-376 §21.2.2.153): ряды — линии
* Биржевая диаграмма (c:stockChart, ECMA-376 §21.2.2.198): ряды — линии
* (CT_LineSer, обычно open/high/low/close), плюс факультативные
* c:hiLowLines (вертикаль min..max по всем рядам категории),
* c:upDownBars (столбик между первым и последним рядом: вверх — зелёный,
@@ -402,19 +402,24 @@ final class Surface3dPainter {
private static List<double[]> clipHalf(List<double[]> poly, double bound, boolean keepAbove) {
List<double[]> out = new ArrayList<>();
for (int i = 0; i < poly.size(); i++) {
double[] cur = poly.get(i);
double[] nxt = poly.get((i + 1) % poly.size());
if (poly.isEmpty()) {
return out;
}
// Рёбра (prev → cur) по кругу от замыкающего: то же множество рёбер, что у
// индексного (i, (i+1)%n); foreach — ForLoopCanBeForeach.
double[] prev = poly.get(poly.size() - 1);
for (double[] cur : poly) {
boolean inPrev = keepAbove ? prev[2] >= bound : prev[2] <= bound;
boolean inCur = keepAbove ? cur[2] >= bound : cur[2] <= bound;
boolean inNxt = keepAbove ? nxt[2] >= bound : nxt[2] <= bound;
if (inCur) {
out.add(cur);
if (inPrev) {
out.add(prev);
}
if (inCur != inNxt && Math.abs(nxt[2] - cur[2]) > 1e-12) {
double t = (bound - cur[2]) / (nxt[2] - cur[2]);
out.add(new double[]{cur[0] + t * (nxt[0] - cur[0]),
cur[1] + t * (nxt[1] - cur[1]), bound});
if (inPrev != inCur && Math.abs(cur[2] - prev[2]) > 1e-12) {
double t = (bound - prev[2]) / (cur[2] - prev[2]);
out.add(new double[]{prev[0] + t * (cur[0] - prev[0]),
prev[1] + t * (cur[1] - prev[1]), bound});
}
prev = cur;
}
return out;
}
@@ -459,7 +464,7 @@ final class Surface3dPainter {
project(0.5, v, floorW, rotX, rotY, depthScale, persp), fit);
}
// сетка значений: левая стенка (от переднего левого ребра в глубину)
// и дальней стенка — обе рисует Word; c:delete (§21.2.2.38) убирает ось
// и дальней стенка — обе рисует Word; c:delete (§21.2.2.40) убирает ось
// целиком — сетка удалённой оси не рисуется.
if (valAxis.gridlines && !valAxis.deleted) {
for (double v = lo; v <= hi + unit / 2; v += unit) {
@@ -22,7 +22,7 @@ import java.util.Map;
* любой цепочки ограничена числом секторов файла, иначе враждебный FAT
* зациклил бы разбор.</p>
*/
public final class CfbReader {
final class CfbReader {
/** Сигнатура контейнера, MS-CFB §2.2 (Header Signature). */
static final byte[] SIGNATURE = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
@@ -33,9 +33,6 @@ public final class CfbReader {
private static final long FREESECT = 0xFFFFFFFFL;
private static final long MAX_SECT = 0xFFFFFFFAL;
/** Разумный потолок mini-sector shift: 2^16 = 64 KiB (MS-CFB §2.2). */
private static final int MAX_MINI_SECTOR_SHIFT = 16;
/** Типы записей directory (MS-CFB §2.6, Object Type). */
private static final int TYPE_STREAM = 0x02;
private static final int TYPE_ROOT = 0x05;
@@ -44,6 +41,7 @@ public final class CfbReader {
private static final int ENTRY_SIZE = 128;
/** Смещения полей заголовка (MS-CFB §2.2: сигнатура 8 + CLSID 16). */
private static final int OFF_BYTE_ORDER = 0x1C;
private static final int OFF_SECTOR_SHIFT = 0x1E;
private static final int OFF_MINI_SECTOR_SHIFT = 0x20;
private static final int OFF_FIRST_DIR = 0x30;
@@ -63,6 +61,16 @@ public final class CfbReader {
/** Минимальный заголовок — 512 байт (сектор v3). */
private static final int HEADER_SIZE = 512;
/** ByteOrder MUST быть little-endian ([MS-CFB] §2.2). */
private static final int BYTE_ORDER_LITTLE = 0xFFFE;
/** SectorShift: 9 (v3, 512 Б) или 12 (v4, 4096 Б) ([MS-CFB] §2.2). */
private static final int SECTOR_SHIFT_V3 = 9;
private static final int SECTOR_SHIFT_V4 = 12;
/** MiniSectorShift MUST быть 6 (64 Б) ([MS-CFB] §2.2). */
private static final int MINI_SECTOR_SHIFT_MUST = 6;
/** Mini Stream Cutoff MUST быть 0x1000 ([MS-CFB] §2.2). */
private static final int MINI_STREAM_CUTOFF_MUST = 0x1000;
private CfbReader() {
}
@@ -73,22 +81,30 @@ public final class CfbReader {
* @throws ConversionException если это не CFB, файл обрезан или цепочки
* секторов цикличны/указывают за конец файла
*/
public static Map<String, byte[]> readStreams(byte[] cfb) {
static Map<String, byte[]> readStreams(byte[] cfb) {
if (cfb == null || cfb.length < HEADER_SIZE || !startsWithSignature(cfb)) {
throw new ConversionException("Содержимое не похоже на .doc Word 97–2003");
}
// MUST-поля заголовка ([MS-CFB] §2.2): не-равенство — чужой/битый
// формат, разбор дал бы мусор вместо отказа
if (u16(cfb, OFF_BYTE_ORDER) != BYTE_ORDER_LITTLE) {
throw new ConversionException("Неизвестный Byte Order контейнера .doc");
}
int sectorShift = u16(cfb, OFF_SECTOR_SHIFT);
int miniSectorShift = u16(cfb, OFF_MINI_SECTOR_SHIFT);
if (sectorShift != 9 && sectorShift != 12) {
if (sectorShift != SECTOR_SHIFT_V3 && sectorShift != SECTOR_SHIFT_V4) {
throw new ConversionException("Неподдерживаемый размер сектора CFB: 2^" + sectorShift);
}
if (miniSectorShift > MAX_MINI_SECTOR_SHIFT) {
if (miniSectorShift != MINI_SECTOR_SHIFT_MUST) { // §2.2: «MUST be set to 0x0006»
throw new ConversionException("Неподдерживаемый размер mini-сектора CFB: 2^" + miniSectorShift);
}
int sectorSize = 1 << sectorShift;
int miniSectorSize = 1 << miniSectorShift;
long firstDir = u32(cfb, OFF_FIRST_DIR);
long cutoff = u32(cfb, OFF_CUTOFF);
if (cutoff != MINI_STREAM_CUTOFF_MUST) { // §2.2: «MUST be set to 0x00001000»
throw new ConversionException("Неподдерживаемый Mini Stream Cutoff контейнера .doc");
}
long firstMiniFat = u32(cfb, OFF_FIRST_MINI_FAT);
long firstDifat = u32(cfb, OFF_FIRST_DIFAT);
long difatCount = u32(cfb, OFF_DIFAT_COUNT);
@@ -123,6 +139,13 @@ public final class CfbReader {
}
if (rootStart >= 0 && rootSize > 0) {
// Root-запись не проходит фильтр «size <= cfb.length», что ниже для
// stream-записей: readChain аллоцирует new byte[(int) size] ДО
// любых проверок границ — завышенный rootSize уложил бы heap (MS-CFB §2.4,
// поток не может быть больше контейнера).
if (rootSize > cfb.length) {
throw new ConversionException("Размер mini stream .doc больше контейнера");
}
miniStream = readChain(cfb, fat, rootStart, rootSize, sectorSize, sectorTotal, "mini stream");
}
if (firstMiniFat != FREESECT && firstMiniFat != ENDOFCHAIN && firstMiniFat <= MAX_SECT) {
@@ -137,11 +160,27 @@ public final class CfbReader {
}
}
// второй проход: содержимое потоков
// второй проход: содержимое потоков.
// Суммарный бюджет аллокаций big-потоков: FAT легально шарит сектора
// между записями, поэтому пер-запись «size <= cfb.length» не
// ограничивает итог — N записей с size ≈ cfb.length аллоцировали бы
// N×файл (OOM с одного враждебного контейнера). В легитимном
// контейнере big-потоки не перекрываются: rootSize + Σ big ≤ файл +
// служебные сектора (FAT/dir/докругление) ≈ 1.1×файла; 1.5× — запас.
// Mini-потоки (size < cutoff) в бюджет НЕ идут: их данные физически
// лежат внутри rootSize ([MS-CFB] §2.1/§2.4 — «The space for these
// objects comes from a special stream that is called the mini
// stream»), учёт их размеров второй раз удваивал бы rootSize и
// ложно отвергал контейнер из одних мелких потоков.
Map<String, byte[]> result = new HashMap<>();
long allocated = rootSize;
for (Entry e : entries) {
byte[] data;
if (e.size() >= cutoff) {
if (allocated + e.size() > 3L * cfb.length / 2) {
throw new ConversionException("Суммарный размер потоков .doc больше лимита контейнера");
}
allocated += e.size();
data = readChain(cfb, fat, e.start(), e.size(), sectorSize, sectorTotal,
"цепочка потока «" + e.name() + "»");
} else {
@@ -224,7 +263,15 @@ public final class CfbReader {
return fat;
}
/** Цепочка секторов по FAT; цикл/выход за FAT → {@link ConversionException}. */
/**
* Цепочка секторов по FAT; цикл/выход за FAT → {@link ConversionException}.
* Капа min(fat.length, sectorTotal): sectorOffset=(sector+1)·sectorSize
* обязан остаться положительным int — сектор «за файлом» дал бы оффлоу
* и обход проверок base+n&gt;cfb.length; капка fat.length — ещё и на
* индексацию fat[] при FAT, покрывающем меньше файла (битый DIFAT).
* Регрессия — CfbReaderTest#streamChainBeyondFile_rejected,
* #rootChainBeyondFile_rejected.
*/
private static int[] chain(int[] fat, long start, int sectorTotal, String what) {
List<Integer> sectors = new ArrayList<>();
long sect = start;
@@ -233,7 +280,7 @@ public final class CfbReader {
if (sectors.size() > limit) {
throw new ConversionException("Циклическая " + what + " в .doc");
}
if (sect >= fat.length) {
if (sect >= limit - 1) {
throw new ConversionException("Сектор за концом FAT в .doc: " + what);
}
sectors.add((int) sect);
@@ -286,12 +333,15 @@ public final class CfbReader {
if (sect >= miniFat.length) {
throw new ConversionException("Mini-сектор за концом MiniFAT в .doc");
}
int base = (int) sect * miniSectorSize;
int n = Math.min(miniSectorSize, (int) size - done);
if (base + n > miniStream.length) {
// long-арифметика: sect уже long, умножение не может уйти в
// отрицательный int-wrap и пройти прежний guard — arraycopy тогда бросал
// ArrayIndexOutOfBoundsException (не ConversionException → 500).
long base = sect * miniSectorSize;
if (base < 0 || base + n > miniStream.length) {
throw new ConversionException("Mini-поток .doc ссылается за конец mini stream");
}
System.arraycopy(miniStream, base, out, done, n);
System.arraycopy(miniStream, (int) base, out, done, n);
done += n;
sect = miniFat[(int) sect] & 0xFFFFFFFFL;
}
@@ -303,11 +353,15 @@ public final class CfbReader {
}
private static int sectorOffset(int sector, int sectorSize) {
return (sector + 1) * sectorSize;
long off = (long) (sector + 1) * sectorSize;
if (off > Integer.MAX_VALUE) {
throw new ConversionException("Сектор за концом файла в .doc");
}
return (int) off;
}
private static void requireInFile(int offset, int len, int fileLen, String what) {
if (offset < HEADER_SIZE || offset + len > fileLen) {
if (offset < HEADER_SIZE || (long) offset + len > fileLen) {
throw new ConversionException("Ссылка за конец файла в .doc: " + what);
}
}

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