Files
java-word-pdf/AGENTS.md
T

15 KiB
Raw Blame History

AGENTS.md

Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: wordpdf-core (библиотека), wordpdf-cli (fat-jar через maven-shade).

Сборка

  • mvn clean verify — все модули + тесты; единственный гейт перед git push (lint/typecheck/CI в репозитории нет).
  • mvn -pl wordpdf-cli package — только fat-jar wordpdf-cli/target/wordpdf-cli-1.0.0.jar.
  • dependency-reduced-pom.xml — артефакт shade, уже в .gitignore, не коммитить.

Тесты

  • JUnit 5, без внешних сервисов, headless (surefire уже задаёт -Djava.awt.headless=true).
  • Один тест: mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont.
  • Тесты wordpdf-cli зависят от test-jar wordpdf-core (classifier tests): сборка -pl wordpdf-cli без -am не пройдёт — либо строить из корня, либо -am.
  • Тестовые .docx коммитятся в wordpdf-core/src/test/resources/samples/; тесты их не генерируют. Пересоздать — одноразовой утилитой SampleDocxGenerator (команда в javadoc класса); POI — только test scope.
  • BundledFontsTest проверяет синхронность списка ENTRIES с реальными TTF в resources/fonts/: новый шрифт = файл + Entry, иначе тест красный.

Эталон в references/

  • Два варианта одного и того же 11-страничного документа (текст, таблицы, колонтитулы, 3 диаграммы + SmartArt, формулы), каждый со своим эталонным PDF, экспортированным из Word 365: word.docx + word.pdf — обычный Transitional OOXML (schemas.openxmlformats.org/.../2006/...); word-export.docx + word-export.pdf — тот же документ, сохранённый в Strict OOXML (purl.oclc.org/ooxml/...).
  • Оба эталонных PDF визуально идентичны (11/11 страниц растрово совпадают, кроме антиалиасинга на стр. 2) — это один и тот же документ, различие только в пространстве имён XML.
  • word-export.docx (Strict) сейчас не конвертируется: Docx4JException: No relationship of type officeDocument в Load3.get (CLI — код возврата 2, пустой PDF). Причина: в _rels/.rels тип связи http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument, а docx4j ждёт Transitional-URI. Правка — нормализация Strict→Transitional (URI purl.oclc.org/ooxml/ → schemas.openxmlformats.org/officeDocument/2006/ и аналоги для drawingml/diagram/picture/relationships) в байтах пакета до WordprocessingMLPackage.load, рядом с DocxOnOffNormalizer.
  • При конвертации в Strict Word теряет VML-fallback'ы и совместимость: в word-export.docx нет v:, wps:, wpc:, w10: и mc:AlternateContent (в word.docx они есть, включая 8 w:pict). Сравнивать вывод с эталоном нужно по паре word.docx/word.pdf.
  • references/ — материалы для ручного сравнения с Word, не тестовые фикстуры: в тесты и в jar их не подключать (фикстуры — wordpdf-core/src/test/resources/samples/).

Шрифты (важно при изменениях)

  • 28 TTF в wordpdf-core/src/main/resources/fonts/ — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга.
  • Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans.
  • slf4j-simple обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест noLoggingWarningInPdf).
  • Символы U+2000–U+2EFF (em-dash, кавычки, многоточие) рендерятся DejaVu Sans, а не шрифтом ранa — по дизайну; виртуальный «Segoe UI Symbol» мапится на fallback.

Архитектура (неочевидное)

  • Пайплайн: байты docx → DocxOnOffNormalizer → docx4j → XSL-FO (XSLT) → FOP → PDF.
  • Порядок инициализации в WordPdfConverter.convertToStream важен: сначала new BundledFontMapper(), потом BundledFonts.init() (бандл-шрифты регистрируются поверх системных), затем BundledFonts.restrictToBundled() (чистит реестр PhysicalFonts от системных шрифтов до load(); конструктор маппера каждый раз заново добавляет их, и GlyphCheck на Windows находит системный Calibri — em-dash остаётся на Carlito, красный ruPlain_emDashEmbeddedNotHelvetica). Не менять местами.
  • docx4j 11.x теряет атрибуты w:val="off"/"on" при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тест ruPlain_regularRunsUseRegularFont).
  • Диаграммы: docx2fo.xslt умеет только a:graphicData/pic:pic, для c:chart и dgm:relIds там notImplemented (объект молча исчезает). Поэтому DrawingPreRenderer.run(pkg) (шаг 3.5 в convertToStream, после setFontMapper и до FOSettings) рендерит их своим Java2D-движком в PNG 300 dpi (internal/chart/*) и подменяет на pic:pic. Тест chartsSmartArt_drawingsBecomeImages, фикстура samples/charts-smartart.docx.
  • В DrawingPreRenderer нужны собственные rels части — part.getRelationshipsPart() (Base), а не getOwningRelationshipPart(): у document.xml последнее указывает на пакетный .rels. Обход pkg.getParts() — только по снимку списка: createImagePart докидывает части в тот же реестр.
  • SmartArt рисуется из word/diagrams/drawing1.xml (кэш разложенной Word-ом схемы: абсолютные позиции + prstGeom); текст-заполнители ([Текст]) лежат в data1.xml на dgm:pt type="node", а формы ссылаются на dgm:pt type="pres" — связь через dgm:cxn type="presOf".
  • surface3D (Surface3dPainter): перспективная проекция (c:view3D/perspective, по умолчанию 30°, и depth), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет из c:bandFmts затемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными на scale/off — забыть масштаб значит нарисовать поверхность в субпиксельный ноль.
  • Знак rotY в DrawingML обратный правому правилу вокруг вертикали: в Surface3dPainter.paint он берётся как -Math.toRadians(spec.rotY). Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word).
  • c:view3D/perspective — НЕ угол обзора камеры. Расстояние камеры в Surface3dPainter = CAMERA_DISTANCE * (30/perspective), где CAMERA_DISTANCE = 2.36 (эффективный fov ≈ 49°, подобран фитом по эталону Word). При наивном fov = perspective перспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку.
  • Пропорции «коробки» surface3D (DEPTH_RATIO = 0.705, HEIGHT_RATIO = 0.664): глубина = 0.705 ширины (от неё c:view3D/depth), высота значений = 0.664 * availH/availW, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты.
  • Поля вокруг коробки — доли области построения GUTTER_LEFT = GUTTER_RIGHT = 0.1485, GUTTER_TOP = 0.116, GUTTER_BOTTOM = 0.146; offX/offY обязаны включать левое и верхнее поле (без topGutter поверхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений.
  • Калибровка камеры, коробки и полей зафиксирована тестами Surface3dPainterTest.cameraMatchesWordReference и surfaceSilhouetteMatchesWordPlacement. Эталон — стр. 3 word-export.pdf (экспорт Word), растеризованная pdftoppm -r 300; цели замеряются по связному блоку граней (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину.
  • Нормаль грани считается в той же метрике, что и проекция: v умножается на depthScale, w уже умножен на hScale. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert.
  • Затенение граней surface3D — Lambert 0.92 + 0,88·dot с клампом [0,80; 1,25] и боковым светом LIGHT = (0,83, 0,48, 0,28). Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. Тест shadingMatchesWordRange.
  • Триангуляция ячейки — диагональ с большей суммой значений (z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1] → w00–w11, иначе w01–w10), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3 word-export.pdf, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированная w00–w11 — 81,6 %, фиксированная w01–w10 — 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия — Surface3dPainterTest.saddleCellUsesHigherDiagonal (нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду.
  • Пустой c:title при c:autoTitleDeleted val="0" даёт автозаголовок Chart Title (ChartSpec.AUTO_TITLE); для круговых (pie/pie3D/doughnut) вместо него — имя ряда. Тесты ChartSpecTest.
  • В кваде ячейки w01 обязан быть z[r+1][c], а w10 — z[r][c+1] (u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней.
  • ChartRenderer.axisBounds для линейной оси значений без явного c:min всегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (0-1 … 4-5, а не 1-2 … 4-5). Юнит-тесты — Surface3dPainterTest.
  • Не убирать shade-фильтры META-INF/*.SF|*.DSA|*.RSA — подписанные jar-файлы зависимостей ломают fat-jar.

Точка входа

  • Библиотека: WordPdfConverter.convert(Path) / convert(Path, Path) — статический stateless-класс; ошибки — ConversionException.
  • CLI: WordPdfCli (fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.