# Архитектура ## Конвейер конвертации (шаги 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 (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md). ## Слои ядра (`wordpdf-core`) |Слой|Содержимое| |---|---| |публичный API (`ru.pjandro.wordpdf`)|`WordPdfConverter`, `WordPdfValidator`, `ConvertOptions`, иерархия ошибок — см. [API библиотеки](../library/api.md)| |`internal/`|нормализаторы (контракт `byte[] normalize(byte[])`), `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`| |`internal/doc/`|мост бинарного `.doc` → in-memory `.docx` — [Мост .doc](doc-bridge.md)| |`internal/chart/`|Java2D-рендер диаграмм/SmartArt/формул → PNG — [Диаграммы](charts.md)| |`fonts/`|бандл из 30 TTF, маппинг алиасов, `GlyphFont` (метрики/глифы через fontbox, без AWT) — [Шрифты](fonts.md)| Всё, кроме публичного 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](../api/errors.md). В модуле 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; [Эксплуатация: стенды](../operations/stack.md). - Прод (`https://pjandro.ru/pdf-converter/`) рендерится job'ом `deploy` из Gitea Variables — [Деплой](../operations/deployment.md).