# java-word-pdf Конвертация **docx → PDF** на чистом Java: `docx4j` + `Apache FOP`, без LibreOffice/Aspose. Шрифты упакованы в jar — конвертация не зависит от шрифтов, установленных в системе (работает «из коробки» на голом сервере). ## Возможности - Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества). - Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются в docx4j/FOP. - Частые MS-шрифты подменяются метрически совместимыми open-source аналогами (см. «Шрифты» ниже). - Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot) и веб-интерфейс (`wordpdf-web`, React SPA). ## Структура ``` java-word-pdf/ ├── wordpdf-core/ библиотека: конвертер, шрифты, маппинг ├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot, Swagger UI) └── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven) ``` Ключевые классы (`wordpdf-core`): | Класс | Назначение | |---|---| | `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(byte[], String)` — байты на входе, байты PDF на выходе | | `ru.pjandro.wordpdf.ConversionException` | исключение конвертации | | `ru.pjandro.wordpdf.fonts.BundledFonts` | выгрузка TTF из jar и регистрация в docx4j | | `ru.pjandro.wordpdf.fonts.BundledFontMapper` | маппинг имён шрифтов документа → TTF | | `ru.pjandro.wordpdf.internal.DocxOnOffNormalizer` | нормализация `w:val="off"/"on"` перед загрузкой | | `ru.pjandro.wordpdf.internal.FopFallbackFonts` | декларация fallback-семейства в FOP-конфиге | ## Сборка Требуется **Java 21** и **Maven** (бэкенд), **Node.js ≥ 20.19** (веб-интерфейс). ```bash mvn clean verify # все модули + тесты mvn -pl wordpdf-app -am package # исполняемый jar бэкенда ``` Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости внутри). Для фронтенда — отдельный деп: `npm install && npm run build` в `wordpdf-web/` (результат — статика в `wordpdf-web/dist/`). ## Использование ### REST API ```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 ``` `POST /api/v1/convert` принимает multipart-поле `file` (.docx) и синхронно возвращает байты PDF (`application/pdf`, attachment). |Код|Смысл| |---|---| |200|PDF в теле ответа| |400|некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц| |413|тело запроса больше контейнерного лимита multipart (6 МБ)| |503|очередь конвертации занята — повторить позже| |504|конвертация дольше таймаута (`wordpdf.convert-timeout`, по умолчанию 2m)| Ошибки — JSON `{"error": "..."}`. Интерактивная документация: Swagger UI — `/swagger-ui.html`, OpenAPI — `/v3/api-docs`. ### Библиотека ```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"); // заголовок PDF Files.write(Path.of("out.pdf"), pdf); ``` Ошибки валидации (не `.docx` по содержимому, размер больше 5 МБ, страниц больше ста) бросают `ConversionException`. Работа с файлами — забота вызывающего: ядро пути не принимает. ### Веб-интерфейс и контейнеры (podman) ```bash podman-compose up -d --build ``` Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не публикуется). Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar` (порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173` (Vite проксирует `/api` на 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 ──> нормализация байтов ──> docx4j (WordprocessingMLPackage) ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты) ``` 1. Байты `.docx` нормализуются, пока docx4j не увидел документ: `DocxOnOffNormalizer` (docx4j теряет `w:val="off"/"on"` при JAXB-разборе, из-за чего regular-раны могли рендериться жирным курсивом), `SymbolFontNormalizer` (маркеры из Symbol/Wingdings вместо «#») и `FieldNormalizer` (поля `PAGE`/`NUMPAGES` пересчитываются, а не печатают кэш из docx) и `GlyphCoverageNormalizer` (раны со знаками вне их шрифта). 2. Документ загружается в `WordprocessingMLPackage`, привязывается `BundledFontMapper`, диаграммы и SmartArt предварительно растеризуются в PNG (`DrawingPreRenderer`). 3. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP` рендерит 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). ## Тесты Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/` (генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание шрифтов. Запуск: `mvn test`. API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`) на тех же фикстурах — ядро отдаёт их test-jar'ом.