- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
5.5 KiB
Архитектура
Конвейер конвертации (шаги 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 — Деплой.