65746db9d2
- git mv docker-compose*.yml -> compose*.yml, Dockerfile -> Containerfile (podman-compose picks compose.yml; buildah finds Containerfile first) - compose/compose.dev: x-podman.name_separator_compat (dash container names), explicit app/web healthchecks (OCI export drops image HEALTHCHECK, depends_on service_healthy would hang forever), fixed subnet 10.113.0.0/24 gw 10.113.0.1 for the aardvark-dns resolver - gateway/nginx.conf: resolver + proxy_pass via variables (static proxy_pass resolves once at start; podman-restart.service brings gateway up before app -> dead upstream, 502 until manual restart) - Containerfiles: pin base images to docker.io/library/* (no unqualified-search-registries on hosts), truthful buildah proxy comments - comments/docs: Docker HEALTHCHECK -> container HEALTHCHECK; READMEs, AGENTS.md updated for podman/podman-compose Verified on dev (podman 5.7.0, podman-compose 1.5.0): stack up with dash names, app/web healthy, conversion through gateway returns PDF, gateway survives app container restart without restart (resolver).
176 lines
9.3 KiB
Markdown
176 lines
9.3 KiB
Markdown
# 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'ом.
|