3.7 KiB
3.7 KiB
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-jarwordpdf-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-jarwordpdf-core(classifiertests): сборка-pl wordpdf-cliбез-amне пройдёт — либо строить из корня, либо-am. - Тестовые
.docxкоммитятся вwordpdf-core/src/test/resources/samples/; тесты их не генерируют. Пересоздать — одноразовой утилитойSampleDocxGenerator(команда в javadoc класса); POI — только test scope. BundledFontsTestпроверяет синхронность спискаENTRIESс реальными TTF вresources/fonts/: новый шрифт = файл +Entry, иначе тест красный.
Шрифты (важно при изменениях)
- 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()(бандл-шрифты регистрируются поверх системных). Не менять местами. - docx4j 11.x теряет атрибуты
w:val="off"/"on"при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тестruPlain_regularRunsUseRegularFont). - Не убирать 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 не конвертирован хотя бы один файл.