docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# 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) — для глубокой правки кода.
|
||||
Reference in New Issue
Block a user