b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# Word → PDF конвертер
|
|
|
|
Конвертация **.docx/.doc → PDF** на чистой Java: `docx4j` 17.3.2 + форк `Apache FOP`
|
|
(`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6), **без LibreOffice и без Aspose**.
|
|
Бинарный `.doc` (Word 97–2003) читается собственным мостом [MS-DOC]/[MS-CFB]
|
|
и переносится в .docx в памяти — дальше идёт тем же конвейером. Шрифты упакованы
|
|
в jar: конвертация не зависит от шрифтов, установленных в системе, и работает
|
|
«из коробки» на голом сервере.
|
|
|
|
## Три поверхности
|
|
|
|
|Поверхность|Что это|Куда смотреть|
|
|
|---|---|---|
|
|
|Веб-интерфейс|React SPA: перетащил файл → предпросмотр PDF → скачивание. Публикация: `https://pjandro.ru/pdf-converter/`|[Пользователю](user.md)|
|
|
|REST API|`POST /api/v1/convert` (Spring Boot 4.1.1), ключ доступа, Swagger UI|[REST API](api/index.md)|
|
|
|Java-библиотека|`wordpdf-core`: `WordPdfConverter.convert(...)` — байты docx на входе, байты PDF на выходе|[Библиотека](library/getting-started.md)|
|
|
|
|
## Как это работает (схема)
|
|
|
|
```
|
|
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
|
|
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
|
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
|
```
|
|
|
|
1. Вход проверяется до рендера (`WordPdfValidator`): размер → сигнатура байтов
|
|
(zip `PK\x03\x04` или CFB `D0 CF 11 E0`) → контейнер и страницы lightweight-сканом,
|
|
без зависимости от docx4j.
|
|
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом (12 правил
|
|
нормализации), затем OLE-объекты вычищает `OleObjectNormalizer`.
|
|
3. Документ загружается в `WordprocessingMLPackage`, привязывается `BundledFontMapper`.
|
|
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi собственным
|
|
Java2D-движком (`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
|
5. Экспорт в XSL-FO идёт вендорным стилем `docx2fo.xslt`; `Apache FOP` рендерит
|
|
PDF, встраивая подмножества шрифтов.
|
|
|
|
Полностью, с обоснованиями — [Архитектура](architecture/overview.md).
|
|
|
|
## Возможности
|
|
|
|
- RU/EN: кириллица и латиница встраиваются в PDF как embedded-подмножества.
|
|
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
|
([Шрифты](architecture/fonts.md)).
|
|
- Диаграммы (17 типов, включая комбинированные) и SmartArt — PNG без Word/LibreOffice
|
|
([Диаграммы](architecture/charts.md)).
|
|
- `.doc`: текст, стили, таблицы, списки, колонтитуки, картинки — собственный мост
|
|
([Мост .doc](architecture/doc-bridge.md)).
|
|
|
|
## Ключевые версии
|
|
|
|
|Компонент|Версия|
|
|
|---|---|
|
|
|Java|17 (temurin)|
|
|
|docx4j|17.3.2|
|
|
|Apache FOP (форк `docx4j-fo-renderer*`)|2.11-docx4j.6|
|
|
|commons-compress|1.28.0 (минимум 1.25.0)|
|
|
|Spring Boot|4.1.1|
|
|
|springdoc|3.1.1|
|
|
|SPA|React 19.2 + TypeScript ~6.0 + Vite 8.3|
|
|
|
|
## Ссылки
|
|
|
|
- [Javadoc публичного API `wordpdf-core`](/apidocs/index.html)
|
|
- [Внутренние справочники репозитория](internal-guides.md) — для глубокой правки кода.
|