Files
java-word-pdf/README.md
T
Pjandro 8529b6877b
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 18m31s
Слияние docx4j 17.3.5 в wordpdf-core и форк FO-рендерера 2.11-docx4j.8 в реактор
- wordpdf-core/src/main/java впитаны исходники docx4j-core, -export-fo,
  -chart-render, -JAXB-ReferenceImpl, -copy, -generated-objects (17.3.5) +
  сгенерированная XJC JAXB-модель; ресурсы — тем же путём; артефакты группы
  org.docx4j из внешних репозиториев больше не подключаются
- vendor/fop: форк docx4j-fo-renderer 2.11-docx4j.8 (util/events/core/fop)
  собирается в реакторе вместо jar из Nexus
- docx2fo.xslt перевендорен со стилем 17.3.5, оба AUDIT-FIX-патча перенесены;
  дрейф-гейт vendoredXsltTracksJarCopy зелёный
- upstream-тесты docx4j перенесены в src/test/java/org (658 классов, вне гейта);
  execution upstream-docx4j-tests в профиле upstream-tests (./mise.sh run
  upstream-tests, в pr.yml non-blocking шаг): 3470 тестов, 3457 зелёных,
  13 красных — категории окружения/калибровки хоста и следствий слияния
  classpath задокументированы в docs/agent/testing.md
- surefire: провайдер SLF4J фиксируется коротким slf4j.provider по execution;
  перенесён upstream logback.xml (root=DEBUG без конфига ломает visitor-экспорт
  VML); upstream-форки пинят JDK JAXP-фабрики; PMD/JaCoCo исключают org/**
- wordpdf-app: без изменений кода (зависит от слитого ядра); тесты 44/44
- документация синхронизирована (AGENTS.md, README, docs/agent/*), mise task
  upstream-tests
2026-11-08 02:54:49 +00:00

372 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# java-word-pdf
Конвертация **.docx/.doc → PDF** на чистом Java: `docx4j` 17.3.5 (исходники
библиотеки слиты в `wordpdf-core`, отдельная зависимость от Maven Central не
нужна) + форк `Apache FOP` (собирается из исходников в `vendor/fop`), без
LibreOffice/Aspose. Бинарный `.doc` (Word 97–2003) читается
собственным мостом [MS-DOC]/[MS-CFB] и переносится в .docx в памяти — дальше
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
## Возможности
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются
в docx4j/FOP.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
(см. «Шрифты» ниже).
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки,
картинки — собственный мост `internal/doc` без внешних зависимостей;
error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры
уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
и веб-интерфейс (`wordpdf-web`, React SPA).
## Структура
```
java-word-pdf/
├── wordpdf-core/ библиотека: конвертер, мост .doc, шрифты, диаграммы
│ + слитый docx4j 17.3.5 (пакеты org.docx4j.*, org.pptx4j.*, org.xlsx4j.*)
├── vendor/fop/ форк FO-рендерера (docx4j-fo-renderer, Apache FOP 2.11 + патчи docx4j)
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot 4.1.1, Swagger UI)
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
```
Ключевые классы (`wordpdf-core`):
|Класс|Назначение|
|---|---|
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`checkPageCount`/`checkPageCountDoc`/`isBinaryDoc`/`validate`)|
|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`; `ConvertOptions.defaults()`)|
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|правила 1–10 нормализации XML-частей одним zip-проходом (+ `OleObjectNormalizer`, правило 11)|
|`ru.pjandro.wordpdf.internal.doc.DocToDocx`|мост бинарного `.doc` → in-memory `.docx` (`convert`/`countPages`)|
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
## Инструменты проекта (mise)
Java, Maven, Node и Python для разработки ставит project-local mise: сам бинарь —
в `./.mise/bin` (gitignored), кеш инструментов — в user-директории mise, в систему
ничего не устанавливается. Версии зафиксированы в корневом `mise.toml`
(temurin-17, maven 3.9.16, node 24, python 3.15).
Первая настройка — скачивает mise, ставит инструменты и делает `npm ci` SPA:
```bash
sh bootstrap.sh # Linux / macOS
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
```
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
```bash
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH
./mise.sh tasks # список задач с описаниями
```
Задачи проекта (`./mise.sh run <задача>`):
|Задача|Содержание|
|---|---|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|`upstream-tests`|перенесённые upstream-тесты docx4j (`-Pupstream-tests`), не в гейте; десятки минут|
|`app-package`|исполняемый jar бэкенда|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|`web-install`|`npm ci` в `wordpdf-web`|
|`web-build`|гейт SPA: `tsc -b && vite build`|
|`web-lint`|oxlint|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
Альтернатива обёртке — активировать mise в шелле и работать напрямую
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
## Сборка
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
```bash
mvn clean verify # все модули + тесты (vendor/fop собирается в реакторе)
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
```
Первый `mvn` скачивает зависимости и собирает форк FOP; JAI (`javax.media:jai-core:1.1.3`,
только для компиляции форка) — бинарь в `vendor/fop/lib/`, устанавливается в локальный
Maven-репозиторий автоматически.
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`).
## Использование
### REST API
```bash
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
http://localhost:8080/api/v1/convert -o doc.pdf
```
`POST /api/v1/convert` принимает multipart-поле `file` (.docx или .doc) и синхронно
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key`
(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`,
dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа
или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`.
**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle`
(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют
конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты
при `errorOnOle=false` тихо удаляются.
**Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages`
(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц); параметрами
запроса не переопределяются.
|Код|Смысл|
|---|---|
|200|PDF в теле ответа|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|401|нет или неверен `X-API-Key`|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|405|не-POST|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|415|не-multipart тело|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|500|ошибка ядра/рендера|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
мутирует глобальный реестр шрифтов; головой очереди на старте стоит `warmup()` —
первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с).
Интерактивная документация: Swagger UI —
`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде;
в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`,
`SPRINGDOC_SWAGGER_UI_ENABLED=false`).
### Библиотека
```java
import ru.pjandro.wordpdf.WordPdfConverter;
import ru.pjandro.wordpdf.ConvertOptions;
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
// с опциями: errorOnCharts/errorOnSmartArt/errorOnOle, лимиты МБ/страниц
pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, false, 5, 100));
Files.write(Path.of("out.pdf"), pdf);
```
Ошибки валидации (содержимое не `.docx`/не `.doc` по сигнатуре, размер больше
5 МБ, страниц больше ста, зашифрованный `.doc`) бросают `ValidationException`
(подтип `ConversionException`). Формат определяется по сигнатуре байтов:
`PK\x03\x04` → .docx-путь, CFB-подпись `D0 CF 11 E0 A1 B1 1A E1` → мост → тот же
конвейер. Те же проверки без рендера доступны отдельно:
`WordPdfValidator.validate(bytes, options)`.
Работа с файлами — забота вызывающего: ядро пути не принимает.
#### Зависимость commons-compress (интеграция в чужой проект)
Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`,
рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в
classpath потребителя — `NoSuchMethodError:
org.apache.commons.compress.archivers.zip.ZipArchiveEntry
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`.
До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом,
объясняющим, какую версию закрепить.
**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress,
а `dependencyManagement` потребителя перекрывает транзитивные версии
(«nearest wins») — закреплять нужно именно в нём:
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-compress</artifactId>
<version>1.28.0</version>
</dependency>
</dependencies>
</dependencyManagement>
```
Диагностика: `mvn dependency:tree -Dincludes=org.apache.commons:commons-compress`.
**Gradle.** По умолчанию Gradle выбирает максимальную версию и конфликт
разрешает сам — guard не сработает и не нужен. Понижает версию только явный
`constraints` / `platform` / `resolutionStrategy`: уберите понижение либо
закрепите нужную версию:
```kotlin
dependencies {
constraints {
implementation("org.apache.commons:commons-compress:1.28.0")
}
}
```
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
### Веб-интерфейс и контейнеры (podman)
```bash
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build
```
Наружный вход — nginx-контейнер `gateway` на `http://localhost:9010/` (контейнер
`app` наружу не публикуется). Файл `compose.yml` fail-closed: без `WORDPDF_API_KEY`
в `.env` стек не поднимется. Маршруты gateway: `/api/`, `/swagger-ui`,
`/v3/api-docs`, `/actuator` → `app:8080` (таймауты прокси 300s,
`client_max_body_size 100m`), остальное → `web` — чистая статика SPA.
Dev-стенд без ключа, с включённым springdoc:
```bash
podman-compose -f compose.dev.yml up -d --build --force-recreate # http://<LAN-IP>:9011
```
(`--force-recreate` обязателен: без него podman-compose пересоберёт образ, но
контейнеры оставит на старом — будет крутиться jar прошлой сборки)
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 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/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx:
контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому
бинарному документу мостом) — `WordPdfValidator`, без зависимости от docx4j.
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — десять
правил (порядок значим): strict→transitional (`w:start`/`w:end`, проценты),
`on/off` → `true/false` (иначе docx4j теряет значение, и regular-раны
рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»),
поля `PAGE`/`NUMPAGES` → `w:fldSimple` (пересчитываются, а не печатают кэш
из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию
глифов), `w:jc` center/right + `w:tblInd` → абсолютный отступ таблицы,
`w:suff="space"` → пробел в номере списка, скрытые раны (`w:vanish`), руби
(надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11,
`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
3. Документ загружается в `WordprocessingMLPackage`, привязывается
`BundledFontMapper`.
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста
docx4j-export-fo — база `org/docx4j/convert/out/fo/docx2fo.xslt` слитого
docx4j — с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
`w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer`
компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP`
(форк `docx4j-fo-renderer`, `vendor/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).
- Часть расхождений с Word — неустранимые невозможности FOP/docx4j
(`jc="distribute"`, `suff="tab"`, кернинг, `framePr`, кэш `REF`/`SEQ`/`TOC`,
надстрочница руби) — полный перечень с доказательствами:
`docs/agent/render-limitations.md`.
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
бинарного формата — уже растры, они вставляются картинками; EMF/WMF/PICT
пропускаются с warn.
## Тесты
Тесты используют 25 закоммиченных фикстур (13 `.docx` + 12 `.doc`) из
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
`./mise.sh run verify` (тесты + PMD + JaCoCo).
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
на тех же фикстурах — ядро отдаёт их test-jar'ом.
В ядро перенесён upstream-набор тестов docx4j (658 классов, `src/test/java/org`) —
он не входит в гейт `verify` и прогоняется отдельно: `./mise.sh run upstream-tests`
(в CI — non-blocking шаг-отчёт в `pr.yml`).
## CI/CD и деплой
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + non-blocking отчёт по upstream-набору docx4j + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
- Push в `main` → `main.yml`: тесты → сборка и push образов `wordpdf-app`/`wordpdf-web` в реестр → deploy (job рендерит прод-конфиги, `podman-compose pull && up -d --force-recreate`, health-гейты, автооткат при провале) → prod-автотесты против живого стенда.
- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx.
- Локальный прогон prod-автотестов (задача `prod-tests`: `pip install`
зависимостей + `pytest -q .` в `prod-autotests/`):
```bash
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests
```
31 проверка; без ключа 27 требующих его пропускаются.