Files
java-word-pdf/docs/architecture/overview.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

5.5 KiB
Raw Blame History

Архитектура

Конвейер конвертации (шаги 0–7)

Единственный вход ядра — WordPdfConverter.convert(byte[], String, ConvertOptions); порядок шагов фиксирован и каждый обоснован:

# Шаг Зачем
0 DependencyGuard.check() API-проба commons-compress ≥ 1.25.0 — понятная ошибка вместо NoSuchMethodError внутри docx4j
1 new BundledFontMapper() → BundledFonts.init() → restrictToBundled() реестр шрифтов = только бандл (+ встроенные в docx); системные сканы отключены гейт-свойствами; порядок строго такой, до load()
2 нормализаторы → WordprocessingMLPackage.load 12 правил переписывания байтов одним zip-проходом + OLE-вычистка (см. ниже)
3 setFontMapper привязка имён шрифтов документа к физическим TTF
3.5 DrawingPreRenderer.run диаграммы/SmartArt/OMML-формулы → PNG 300 dpi; обязателен до FOSettings, иначе FOP молча теряет диаграммы
4 FOSettings + ChartImageHandler + FopFallbackFonts.declare FOP встраивает только задекларированные семейства; декларуются все бандл-семейства
4.25/4.5 LayoutPostRenderer.register, setCustomXsltTemplates padding-компенсация таблиц; вендорный XSLT с AUDIT-FIX-патчами
5–6 общая FopFactory (DCL) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL) XSL-FO → PDF
7 finally сброс temp-шрифтов, сброс общих кешей картинок (иначе ~1,5 ГБ за 30 конвертаций), возврат реестра к бандлу

Нормализаторы правил 1–11 (один zip-проход, порядок значим): strict→transitional, on/off→true/false, Symbol/Wingdings→Unicode, поля PAGE/NUMPAGES → w:fldSimple (пересчёт вместо кэша), невидимые символы, OMML-фолбэк, резка ранов по покрытию глифов, отступ таблиц, suff="space", скрытый текст, руби. Правило 12 — OleObjectNormalizer (отдельным байтовым проходом).

Полное «что делает каждый шаг и почему именно так» — pipeline.md (репозиторий).

Слои ядра (wordpdf-core)

Слой Содержимое
публичный API (ru.pjandro.wordpdf) WordPdfConverter, WordPdfValidator, ConvertOptions, иерархия ошибок — см. API библиотеки
internal/ нормализаторы (контракт byte[] normalize(byte[])), FopFallbackFonts, LayoutPostRenderer, DependencyGuard
internal/doc/ мост бинарного .doc → in-memory .docx — Мост .doc
internal/chart/ Java2D-рендер диаграмм/SmartArt/формул → PNG — Диаграммы
fonts/ бандл из 30 TTF, маппинг алиасов, GlyphFont (метрики/глифы через fontbox, без AWT) — Шрифты

Всё, кроме публичного API, — package-private; контракт наружу не расширяется.

Параллельность

PhysicalFonts docx4j — глобальный мутируемый реестр → все конвертации сериализованы монитором класса WordPdfConverter.class. Приложение (wordpdf-app) дополнительно держит однопоточный ThreadPoolExecutor с очередью 16 мест (переполнение → 503, timeout 2m → 504), головой очереди стоит warmup().

REST-конвейер приложения (wordpdf-app)

POST /api/v1/convert → ApiKeyFilter (401) → ConvertController (проверка расширения/размера, параметры) → ConversionService (очередь, Future с таймаутом, перевод исключений ядра в HTTP) → ядро. Обработчик исключений пишет JSON {"error": …} — карта кодов в REST API. В модуле 11 классов, все package-private кроме WordPdfApplication.

Веб-интерфейс (wordpdf-web)

React SPA; вся сеть — ровно две функции в api.ts (convertDocx, probeApiKey), состояние — useState в App.tsx, store-библиотек нет. Запросы идут на тот же путь /api/... относительно базы раздачи — CORS не нужен.

Внешние поверхности

  • gateway/nginx.conf — единственная наружная точка стендов (:9010/:9011): /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080, остальное → web; Эксплуатация: стенды.
  • Прод (https://pjandro.ru/pdf-converter/) рендерится job'ом deploy из Gitea Variables — Деплой.