aec4dbffe7
- WordPdfValidator (новый): MAX_INPUT_BYTES/MAX_PAGES, три нижние оценки страниц (кэш app.xml недостоверен — реальный кейс <Pages>1</Pages> при 110 маркерах lastRenderedPageBreak); lightweight zip/StAX-путь. - convert(Path,Path): неполный PDF удаляется при отказе, но только если поток вывода реально открылся (чужой read-only файл не стирается); checkPageCount внутри try — finally чистит temp-файлы шрифтов. - lightweight: continuous-секции не считаются страницами; w:type — дочерний элемент, классификация на закрытии sectPr; мёртвый атрибутный перегруз startsNewPage удалён. - Фикстуры too-many-pages.docx (151 страница) и stale-cache.docx (кэш 1 при 110 маркерах) + регрессии tooManyPages, staleCachePageCountRejectedBeforeRender, inputTooLarge, oversizedInputReturnsError, pageCount_continuousSectionsNotCountedLightweight. - SampleDocxGenerator: точный поиск <w:t (не матчить <w:tbl/<w:tc), константа STALE_CACHE_UNMARKED_RUNS вместо литерала. - AGENTS.md переписан; .gitignore += /diff/ и /word-export.*. mvn clean verify: 95/95; fat-jar проверен java -jar (код 0/2, артефактов нет).
118 lines
18 KiB
Markdown
118 lines
18 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Overview
|
||
|
||
Конвертер `.docx` → `.pdf` на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint в репозитории нет).
|
||
|
||
## Architecture & Data Flow
|
||
|
||
Пайплайн `WordPdfConverter.convertToStream` — порядок шагов фиксирован, менять местами нельзя:
|
||
|
||
1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз заново добавляет системные шрифты в реестр `PhysicalFonts`; бандл регистрируется поверх; чистка реестра — **до** `load()`. Ключ реестра — имя шрифта, `addPhysicalFont(URI)` НЕ перезаписывает занятый ключ → `BundledFonts.init()` вызывает `dropNonBundled()` (иначе системный `DejaVuSerif.ttf` блокирует наш `DejaVuSerif-Regular.ttf`).
|
||
2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим):
|
||
`DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`; docx4j 17.x теряет on/off при разборе)
|
||
→ `SymbolFontNormalizer` (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица `SymbolMapper` сгенерирована, руками не менять)
|
||
→ `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`)
|
||
→ `GlyphCoverageNormalizer` (шаг 2.4: режет ран по покрытию глифов и пишет семейство в `w:rFonts`; трогает только раны с одним `w:t` и явным `w:rFonts`; покрытие — `java.awt.Font.canDisplay` через `BundledFonts.awtFont`, не `GlyphCheck` — тот логирует на каждый глиф).
|
||
3. `WordprocessingMLPackage.load(байты)` → `WordPdfValidator.checkPageCount(pkg)` — **до** рендера.
|
||
4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок `internal/chart/*` рендерит их в PNG 300 dpi и подменяет на `pic:pic`; после `setFontMapper`, до `FOSettings`)
|
||
→ `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует в FOP-конфиге **все** бандл-семейства — FOP встраивает только задекларированные)
|
||
→ `FORendererApacheFOP` / `FOUserAgent` (заголовок PDF = имя файла)
|
||
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
|
||
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
|
||
|
||
### Критические инварианты (нарушение = битый вывод)
|
||
|
||
- **`docx4j.convert.out.fo.gsubFeatures=false`** — ставится в статическом блоке `WordPdfConverter`. Иначе docx4j навешивает `fox:gsub-features` без объявления префикса → FO невалиден → `WordLayoutFixups` молча отказывается от всех фиксов → FOP падает на `docx4j-baseline`. Без фиксов нет колонок и колонок таблиц.
|
||
- **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` дублируется в `docx4j-fo-renderer-core` и `docx4j-export-fo`; без слияния FOP падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar из тестов не видно — проверять `java -jar`.
|
||
- **Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA`** — подписанные jar ломают fat-jar.
|
||
- **`slf4j-simple` обязателен**: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия `noLoggingWarningInPdf`).
|
||
- **JAXB-обход обязан раскрывать `JAXBElement`** (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через `ContentAccessor` из `org.docx4j.wml` (НЕ `org.docx4j.contentcontrol` — в 17.x его нет). Тип секции — `SectPr$Type.getVal()`; маркер — `R.LastRenderedPageBreak` (`CTLastRenderedPageBreak` в 17.x отсутствует).
|
||
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`), умеет хинты `docx4j:baseline`/`docx4j:line-box`. `Fop.Renderers.getRenderer()` возвращает **список** — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
|
||
- `docx2fo.xslt` в репозитория нет — он в jar `docx4j-export-fo`. `WordLayoutFixups` (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки `w:cols/@w:num` и колонки таблиц; побочный эффект — авто-ширины колонок без `tblGrid`/`tcW` стали уже (слово может перенестись в ячейке).
|
||
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
||
|
||
### Шрифты (30 TTF в `wordpdf-core/src/main/resources/fonts/`, SIL OFL)
|
||
|
||
Алиасы MS→open-source (`BundledFontMapper`): Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). Noto Naskh Arabic / Noto Sans Armenian (только regular, ради глифов U+07B1–08FF и U+058D/E) в `BundledFontMapper` не регистрируются — `FontFallback.selectCovering` перебирает весь реестр `PhysicalFonts` сам. У них только regular-начертание: `BundledFonts.families()` это учитывает, `BundledFontsTest.allFamiliesHaveAllVariants` их не проверяет. Символы U+2000–U+2EFF: `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если глиф есть, иначе виртуальный «Segoe UI Symbol» → fallback (как в Word; регрессия `ruPlain_emDashEmbeddedNotHelvetica`).
|
||
|
||
### Валидация входа (`WordPdfValidator`)
|
||
|
||
`MAX_INPUT_BYTES = 5 MiB`, `MAX_PAGES = 100`. Страницы = **максимум трёх нижних оценок**: (1) кэш `docProps/app.xml <Pages>` — недостоверен (реальный кейс: `<Pages>1</Pages>` при 110 маркерах); (2) явные разрывы `w:br type="page"` / `pageBreakBefore` / межсекционные `sectPr` (кроме `continuous`); (3) `w:lastRenderedPageBreak` + 1. Lightweight-путь (zip/StAX, без docx4j) согласован с JAXB: `sectPr` в body — «все минус 1»; `sectPr` в `pPr` не считается; колонтитулы — по содержимому zip. Расхождение допустимо только в завышение. При отказе `convert(Path,Path)` **удаляет** уже открытый PDF (регрессия `staleCachePageCountRejectedBeforeRender` проверяет отсутствие артефакта).
|
||
|
||
### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
|
||
|
||
Свой Java2D-рендер DrawingML. Калибровка surface3D зафиксирована тестами, эталон — стр. 3 gitignored `word-export.pdf` (экспорт Word, `pdftoppm -r 300`): `CAMERA_DISTANCE = 2.36` (`perspective` — НЕ угол FOV; fov≈49°), `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, поля `0.1485/0.116/0.146` от области построения, `rotY` берётся как `-Math.toRadians(...)` (знак обратный правому правилу), Lambert `0.92 + 0.88·dot` кламп `[0.80; 1.25]`, свет `(0.83, 0.48, 0.28)`. Цели: силуэт 314,9×65,3 pt центр (227,3; 82,3), уклон передней кромки 0.1282, аспект 0.207, шаги осей 0.0504/0.1176. Триангуляция ячейки — диагональ с большей суммой значений (седло; фиксированная диагональ даёт невидимую щепку); клиппинг полос — по треугольникам. `w01 = z[r+1][c]`, `w10 = z[r][c+1]` — перестановка закручивает квад в бабочку. `ChartRenderer.axisBounds` без явного `c:min` поднимает нижнюю границу до 0. Пустой `c:title` + `autoTitleDeleted val="0"` → автозаголовок `Chart Title` (для pie/pie3D/doughnut — имя ряда). Границы калибровки менять только вместе с тестами `Surface3dPainterTest`/`PiePainterTest`.
|
||
|
||
В `DrawingPreRenderer` rels части берутся через `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()` — у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр (живой обход → `ConcurrentModificationException`).
|
||
|
||
## Key Directories
|
||
|
||
| Путь | Назначение |
|
||
|---|---|
|
||
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException` |
|
||
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы MS→open-source) |
|
||
| `…/wordpdf/internal/` | 4 байтовых нормализатора + `FopFallbackFonts` |
|
||
| `…/wordpdf/internal/chart/` | Java2D-рендер диаграмм/SmartArt в PNG |
|
||
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + лицензии — бинарные фикстуры, часть jar |
|
||
| `wordpdf-core/src/test/resources/samples/` | 11 закоммиченных `.docx`-фикстур (единственные фикстуры) |
|
||
| `wordpdf-cli/src/main/java/…/cli/` | `WordPdfCli` (fat-jar) |
|
||
| `references/` | эталон Word 365 (`word.docx` + `word.pdf`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
|
||
| `diff/`, корневые `word-export.*` | gitignored артефакты ручной калибровки |
|
||
|
||
## Development Commands
|
||
|
||
```bash
|
||
mvn clean verify # все модули + тесты — обязательный гейт перед push
|
||
mvn -pl wordpdf-cli package # fat-jar (из корня); из каталога cli — только с -am
|
||
java -jar wordpdf-cli/target/wordpdf-cli-1.0.0.jar in.docx [out.pdf]
|
||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
|
||
```
|
||
|
||
CLI: 1 аргумент → PDF рядом с исходником; 2-й `.pdf` → явный выход; **два `.docx` = пакетная конвертация**. Коды возврата: 0 успех, 1 ошибка использования, 2 не сконвертирован хотя бы один файл.
|
||
|
||
`dependency-reduced-pom.xml` — артефакт shade, не коммитить.
|
||
|
||
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
|
||
|
||
```bash
|
||
mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
|
||
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
|
||
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
|
||
```
|
||
|
||
## Code Conventions & Common Patterns
|
||
|
||
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе docx4j: `BundledFontMapper` (наследник `BestMatchingMapper`), `DrawMlColor` (палитра темы).
|
||
- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов.
|
||
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние `IOException`/`IllegalStateException` оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог.
|
||
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
|
||
- Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
|
||
- Внутренние API package-private; наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`.
|
||
- `WordPdfCli.main` тонко обёртывает `public static int run(String[])` — CLI тестируется без `System.exit`.
|
||
|
||
## Important Files
|
||
|
||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
|
||
- `wordpdf-cli/pom.xml` — shade: Main-Class, `ServicesResourceTransformer`, фильтры подписей.
|
||
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.0`, slf4j `2.0.17`, JUnit `5.12.2`, PDFBox `3.0.7` (test), POI `5.5.1` (test, только генератор фикстур); форки FOP/jeuclid приходят транзитивно с `docx4j-export-fo`, пинить не надо.
|
||
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
|
||
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур (команда в javadoc).
|
||
|
||
## Runtime & Tooling Preferences
|
||
|
||
- Java 17 + Maven (обязательны; wrapper `mvnw` нет). UTF-8.
|
||
- Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой `dependencyManagement`.
|
||
- CI, линтеров, форматтеров, checkstyle — нет; проверка одна: `mvn clean verify`.
|
||
- Fat-jar проверять только `java -jar` (тесты идут по classpath и shade-проблем не видят).
|
||
|
||
## Testing & QA
|
||
|
||
- JUnit 5, surefire c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ), package-private тесты в mirror-пакетах.
|
||
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
|
||
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
|
||
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → временный файл (`extractSample`/`extractToTemp`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`).
|
||
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`.
|
||
- Тесты `wordpdf-cli` берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-cli` без `-am` не соберётся; проверять коды возврата `WordPdfCli.run`.
|
||
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`.
|