docs: README — актуализация под код #94
@@ -1,7 +1,9 @@
|
|||||||
# java-word-pdf
|
# java-word-pdf
|
||||||
|
|
||||||
Конвертация **docx → PDF** на чистом Java: `docx4j` + `Apache FOP`, без
|
Конвертация **.docx/.doc → PDF** на чистом Java: `docx4j` 17.3.2 + форк
|
||||||
LibreOffice/Aspose. Шрифты упакованы в jar — конвертация не зависит от
|
`Apache FOP`, без LibreOffice/Aspose. Бинарный `.doc` (Word 97–2003) читается
|
||||||
|
собственным мостом [MS-DOC]/[MS-CFB] и переносится в .docx в памяти — дальше
|
||||||
|
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
|
||||||
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
||||||
|
|
||||||
## Возможности
|
## Возможности
|
||||||
@@ -12,6 +14,10 @@ LibreOffice/Aspose. Шрифты упакованы в jar — конверта
|
|||||||
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
||||||
(см. «Шрифты» ниже).
|
(см. «Шрифты» ниже).
|
||||||
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
||||||
|
- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки,
|
||||||
|
картинки — собственный мост `internal/doc` без внешних зависимостей;
|
||||||
|
error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры
|
||||||
|
уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
|
||||||
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
||||||
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
||||||
и веб-интерфейс (`wordpdf-web`, React SPA).
|
и веб-интерфейс (`wordpdf-web`, React SPA).
|
||||||
@@ -20,8 +26,8 @@ LibreOffice/Aspose. Шрифты упакованы в jar — конверта
|
|||||||
|
|
||||||
```
|
```
|
||||||
java-word-pdf/
|
java-word-pdf/
|
||||||
├── wordpdf-core/ библиотека: конвертер, шрифты, маппинг
|
├── wordpdf-core/ библиотека: конвертер, мост .doc, шрифты, диаграммы
|
||||||
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot, Swagger UI)
|
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot 4.1.1, Swagger UI)
|
||||||
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -29,13 +35,14 @@ java-word-pdf/
|
|||||||
|
|
||||||
|Класс|Назначение|
|
|Класс|Назначение|
|
||||||
|---|---|
|
|---|---|
|
||||||
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — байты на входе, байты PDF на выходе|
|
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|
||||||
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц по zip без рендера (`checkInput`/`checkPageCount`/`validate`)|
|
|`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.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`; `ConvertOptions.defaults()`)|
|
||||||
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
||||||
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|семь правил нормализации XML-частей одним zip-проходом|
|
|`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.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|
||||||
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
|
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
|
||||||
|
|
||||||
@@ -93,8 +100,9 @@ mvn -pl wordpdf-app -am package # исполняемый jar бэкенд
|
|||||||
```
|
```
|
||||||
|
|
||||||
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
|
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
|
||||||
внутри). Для фронтенда — отдельный деп: `npm install && npm run build`
|
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
|
||||||
в `wordpdf-web/` (результат — статика в `wordpdf-web/dist/`).
|
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
|
||||||
|
mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`).
|
||||||
|
|
||||||
## Использование
|
## Использование
|
||||||
|
|
||||||
@@ -106,7 +114,7 @@ curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
|||||||
http://localhost:8080/api/v1/convert -o doc.pdf
|
http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
```
|
```
|
||||||
|
|
||||||
`POST /api/v1/convert` принимает multipart-поле `file` (.docx) и синхронно
|
`POST /api/v1/convert` принимает multipart-поле `file` (.docx или .doc) и синхронно
|
||||||
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
||||||
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
||||||
|
|
||||||
@@ -127,7 +135,7 @@ dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `
|
|||||||
|Код|Смысл|
|
|Код|Смысл|
|
||||||
|---|---|
|
|---|---|
|
||||||
|200|PDF в теле ответа|
|
|200|PDF в теле ответа|
|
||||||
|400|некорректный вход (не .docx / пустой / не zip / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|
||||||
|401|нет или неверен `X-API-Key`|
|
|401|нет или неверен `X-API-Key`|
|
||||||
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||||
|405|не-POST|
|
|405|не-POST|
|
||||||
@@ -139,7 +147,9 @@ dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `
|
|||||||
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||||
|
|
||||||
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
|
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
|
||||||
мутирует глобальный реестр шрифтов. Интерактивная документация: Swagger UI —
|
мутирует глобальный реестр шрифтов; головой очереди на старте стоит `warmup()` —
|
||||||
|
первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с).
|
||||||
|
Интерактивная документация: Swagger UI —
|
||||||
`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде;
|
`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде;
|
||||||
в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`,
|
в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`,
|
||||||
`SPRINGDOC_SWAGGER_UI_ENABLED=false`).
|
`SPRINGDOC_SWAGGER_UI_ENABLED=false`).
|
||||||
@@ -159,9 +169,12 @@ pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, fals
|
|||||||
Files.write(Path.of("out.pdf"), pdf);
|
Files.write(Path.of("out.pdf"), pdf);
|
||||||
```
|
```
|
||||||
|
|
||||||
Ошибки валидации (не `.docx` по содержимому, размер больше 5 МБ, страниц
|
Ошибки валидации (содержимое не `.docx`/не `.doc` по сигнатуре, размер больше
|
||||||
больше ста) бросают `ValidationException` (подтип `ConversionException`). Те же
|
5 МБ, страниц больше ста, зашифрованный `.doc`) бросают `ValidationException`
|
||||||
проверки без рендера доступны отдельно: `WordPdfValidator.validate(bytes, options)`.
|
(подтип `ConversionException`). Формат определяется по сигнатуре байтов:
|
||||||
|
`PK\x03\x04` → .docx-путь, CFB-подпись `D0 CF 11 E0 A1 B1 1A E1` → мост → тот же
|
||||||
|
конвейер. Те же проверки без рендера доступны отдельно:
|
||||||
|
`WordPdfValidator.validate(bytes, options)`.
|
||||||
Работа с файлами — забота вызывающего: ядро пути не принимает.
|
Работа с файлами — забота вызывающего: ядро пути не принимает.
|
||||||
|
|
||||||
#### Зависимость commons-compress (интеграция в чужой проект)
|
#### Зависимость commons-compress (интеграция в чужой проект)
|
||||||
@@ -224,9 +237,12 @@ podman-compose up -d --build
|
|||||||
Dev-стенд без ключа, с включённым springdoc:
|
Dev-стенд без ключа, с включённым springdoc:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
podman-compose -f compose.dev.yml up -d --build # http://<LAN-IP>:9011
|
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`
|
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
|
||||||
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
||||||
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
|
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
|
||||||
@@ -268,25 +284,33 @@ Dev-режим без контейнеров: бэкенд `java -jar wordpdf-ap
|
|||||||
## Как это работает
|
## Как это работает
|
||||||
|
|
||||||
```
|
```
|
||||||
docx ──> валидация входа ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
|
||||||
──> диаграммы → PNG ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||||
|
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Вход проверяется до рендера: размер → zip-подпись → контейнер → число страниц
|
1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx:
|
||||||
(`WordPdfValidator`, lightweight StAX-оценка по zip без зависимости от docx4j).
|
контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому
|
||||||
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — семь правил:
|
бинарному документу мостом) — `WordPdfValidator`, без зависимости от docx4j.
|
||||||
strict→transitional (`w:start`/`w:end`, проценты), `on/off` → `true/false`
|
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — десять
|
||||||
(иначе docx4j теряет значение, и regular-раны рендерились жирным курсивом),
|
правил (порядок значим): strict→transitional (`w:start`/`w:end`, проценты),
|
||||||
маркеры Symbol/Wingdings → Unicode (вместо «#»), поля `PAGE`/`NUMPAGES` →
|
`on/off` → `true/false` (иначе docx4j теряет значение, и regular-раны
|
||||||
`w:fldSimple` (пересчитываются, а не печатают кэш из docx), невидимые символы,
|
рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»),
|
||||||
раны со знаками вне их шрифта. Затем вычищаются OLE-объекты
|
поля `PAGE`/`NUMPAGES` → `w:fldSimple` (пересчитываются, а не печатают кэш
|
||||||
(`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
|
из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию
|
||||||
|
глифов), `w:jc` center/right + `w:tblInd` → абсолютный отступ таблицы,
|
||||||
|
`w:suff="space"` → пробел в номере списка, скрытые раны (`w:vanish`), руби
|
||||||
|
(надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11,
|
||||||
|
`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
|
||||||
3. Документ загружается в `WordprocessingMLPackage`, привязывается
|
3. Документ загружается в `WordprocessingMLPackage`, привязывается
|
||||||
`BundledFontMapper`.
|
`BundledFontMapper`.
|
||||||
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
|
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
|
||||||
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
||||||
5. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
|
5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста
|
||||||
рендерит PDF, встраивая используемые подмножества шрифтов.
|
docx4j-export-fo с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
|
||||||
|
`w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer`
|
||||||
|
компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP`
|
||||||
|
(форк `docx4j-fo-renderer`) рендерит PDF, встраивая подмножества шрифтов.
|
||||||
|
|
||||||
## Ограничения
|
## Ограничения
|
||||||
|
|
||||||
@@ -299,10 +323,17 @@ docx ──> валидация входа ──> нормализация ба
|
|||||||
и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится
|
и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится
|
||||||
целиком на SIL OFL.
|
целиком на SIL OFL.
|
||||||
- Поддержка таблиц/изображений — базовая (через docx4j/FOP).
|
- Поддержка таблиц/изображений — базовая (через 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.
|
||||||
|
|
||||||
## Тесты
|
## Тесты
|
||||||
|
|
||||||
Тесты используют 13 закоммиченных `.docx`-фикстур из
|
Тесты используют 25 закоммиченных фикстур (13 `.docx` + 12 `.doc`) из
|
||||||
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
|
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
|
||||||
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
|
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
|
||||||
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
|
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
|
||||||
@@ -316,10 +347,11 @@ API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`Co
|
|||||||
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
|
- 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-автотесты против живого стенда.
|
- 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.
|
- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx.
|
||||||
- Локальный прогон prod-автотестов (из `prod-autotests/`):
|
- Локальный прогон prod-автотестов (задача `prod-tests`: `pip install`
|
||||||
|
зависимостей + `pytest -q .` в `prod-autotests/`):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> mise exec -- python -m pytest -q .
|
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests
|
||||||
```
|
```
|
||||||
|
|
||||||
21 проверка; без ключа 17 требующих его пропускаются.
|
31 проверка; без ключа 27 требующих его пропускаются.
|
||||||
|
|||||||
Reference in New Issue
Block a user