59 lines
13 KiB
Markdown
59 lines
13 KiB
Markdown
# 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/...`).
|
||
- `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 не конвертирован хотя бы один файл.
|