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:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+64
View File
@@ -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) — для глубокой правки кода.