Files
java-word-pdf/README.md
T
Pjandro 68e4f41cb2
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 59s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m30s
Main: tests, deploy, autotests / autotests (push) Successful in 41s
Main: tests, deploy, autotests / rollback (push) Has been skipped
docs: полная синхронизация документации с кодом
README: X-API-Key/401, полная таблица статусов, gateway-топология :9010/:9011,
лимиты 100 МБ multipart и конфигурируемые wordpdf.max-mb/max-pages, пайплайн из
7 правил DocxRewritePipeline + OLE, ConvertOptions/WordPdfValidator, секция CI/CD.
AGENTS.md: заголовок диаграммы по ECMA (autoTitleDeleted, §21.2.2.7), потолок
растра MAX_PIXELS/fitDpi, стриминговый checkPageCount, 535 @Test (core 493),
регрессии ChartSpecTest, сноска «README устарел» удалена.
GITEA-vars.md: падающие job'ы — images-app/images-web первыми.
wordpdf-web: охват vite-прокси, комментарий VITE_BASE (печёт CI-job images-web).
2026-10-27 00:14:26 +00:00

326 lines
20 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 → PDF** на чистом Java: `docx4j` + `Apache FOP`, без
LibreOffice/Aspose. Шрифты упакованы в jar — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
## Возможности
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются
в docx4j/FOP.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
(см. «Шрифты» ниже).
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
- Клиентская библиотека (`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[, ConvertOptions])` — байты на входе, байты PDF на выходе|
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц по zip без рендера (`checkInput`/`checkPageCount`/`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`|семь правил нормализации XML-частей одним zip-проходом|
|`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|
|`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 # все модули + тесты
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 -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) и синхронно
возвращает байты 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 / пустой / не zip / больше `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": "..."}`. Конвертации сериализуются одним воркером: ядро
мутирует глобальный реестр шрифтов. Интерактивная документация: 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` по содержимому, размер больше 5 МБ, страниц
больше ста) бросают `ValidationException` (подтип `ConversionException`). Те же
проверки без рендера доступны отдельно: `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 # http://<LAN-IP>:9011
```
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 ──> валидация входа ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> диаграммы → PNG ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Вход проверяется до рендера: размер → zip-подпись → контейнер → число страниц
(`WordPdfValidator`, lightweight StAX-оценка по zip без зависимости от 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), невидимые символы,
раны со знаками вне их шрифта. Затем вычищаются OLE-объекты
(`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
3. Документ загружается в `WordprocessingMLPackage`, привязывается
`BundledFontMapper`.
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
5. Экспорт в 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).
## Тесты
Тесты используют 13 закоммиченных `.docx`-фикстур из
`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'ом.
## CI/CD и деплой
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в 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-autotests/`):
```bash
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> mise exec -- python -m pytest -q .
```
21 проверка; без ключа 17 требующих его пропускаются.